{"_id":"@codebender-io/i18n-currency","_rev":"6-4c2d20a5627500923b1ab9a827dc85a4","name":"@codebender-io/i18n-currency","dist-tags":{"latest":"2.0.0"},"versions":{"0.1.0":{"name":"@codebender-io/i18n-currency","version":"0.1.0","author":{"name":"codebender-io"},"license":"Apache-2.0","_id":"@codebender-io/i18n-currency@0.1.0","maintainers":[{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"}],"homepage":"https://github.com/codebender-io/i18n-currency#readme","bugs":{"url":"https://github.com/codebender-io/i18n-currency/issues"},"dist":{"shasum":"f6192e9941842a803afb76d11e417597dbe4f319","tarball":"https://registry.npmjs.org/@codebender-io/i18n-currency/-/i18n-currency-0.1.0.tgz","fileCount":100,"integrity":"sha512-WiD3TVst6tq9LM/OeuruJL+2y4pyAg2gZJzTSvSxkVxFgUk2ceygjsCS9w4Zt9PBDuq3QzhmI8+hg3/JUXvoxQ==","signatures":[{"sig":"MEUCICmAu26GzdpBN7iBfpR0YYaTGwjK7yykPDLjLDBevgJCAiEA4il5lZnf5jhj1BtCByj5Z0fBNbCTL0FjzyiD6he6kfs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2186054},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./locales/*":"./locales/*"},"gitHead":"a0ce2f6cd1be456d99bcb4f407c51d6dc846cbcc","scripts":{"lint":"eslint ./src","build":"pnpm run clean && pnpm run copy-locales && pnpm run barrel && pnpm run pretty:fix && pnpm run lint:fix && pnpm run build:ts","clean":"rimraf dist","barrel":"tsx scripts/generate-barrel.ts","pretty":"prettier './**/*.{js,ts,jsx,tsx}' --check","prepack":"tsx scripts/prepare-package.ts","build:ts":"tsup","lint:fix":"eslint ./src --fix","postpack":"mv package.json.bak package.json && rimraf package.publish.json && prettier package.json --write","pretty:fix":"prettier './**/*.{js,ts,jsx,tsx}' --write","production":"pnpm run clean && pnpm i && pnpm run build && pnpm pack","copy-locales":"tsx scripts/copy-locales.ts"},"_npmUser":{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"},"repository":{"url":"git+https://github.com/codebender-io/i18n-currency.git","type":"git"},"_npmVersion":"10.9.2","description":"Utils project for dealing with currencies","directories":{},"_nodeVersion":"22.17.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","pnpm":"^10.13.1","tsup":"^8.5.0","eslint":"^9.27.0","rimraf":"^5.0.0","globals":"^16.3.0","prettier":"^3.6.2","fast-glob":"^3.3.3","@eslint/js":"^9.32.0","typescript":"^5.8.3","@types/node":"^22.17.0","typescript-eslint":"^8.38.0","eslint-plugin-unused-imports":"^4.1.4"},"_npmOperationalInternal":{"tmp":"tmp/i18n-currency_0.1.0_1761660356282_0.5648926420688518","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@codebender-io/i18n-currency","version":"0.1.1","author":{"name":"codebender-io"},"license":"Apache-2.0","_id":"@codebender-io/i18n-currency@0.1.1","maintainers":[{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"}],"homepage":"https://github.com/codebender-io/i18n-currency#readme","bugs":{"url":"https://github.com/codebender-io/i18n-currency/issues"},"dist":{"shasum":"b47172ab0527000453d850182d7e7109a51d790d","tarball":"https://registry.npmjs.org/@codebender-io/i18n-currency/-/i18n-currency-0.1.1.tgz","fileCount":100,"integrity":"sha512-6uUMOfmEFGOcXdC6o216BdBXgsznjK9gdRVWcCadULH7BzgCMTW2OAQmlasS0buFDDl2IpMjXW9R0jYBxILC/g==","signatures":[{"sig":"MEUCIBFCeqaZ8JJtwDXMA67AXGG3NlNfXMNh7qu5Ue1bqESAAiEAk3ssBg6tAvoc9T8h1y01bEyyf1oWzBiY7/J0iRwhqXg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2186696},"main":"./dist/index.cjs","type":"module","_from":"file:codebender-io-i18n-currency-0.1.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./locales/*":"./locales/*"},"_npmUser":{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"},"_resolved":"/tmp/a5e197d0f00ae53b51a6d1184aeb710b/codebender-io-i18n-currency-0.1.1.tgz","_integrity":"sha512-6uUMOfmEFGOcXdC6o216BdBXgsznjK9gdRVWcCadULH7BzgCMTW2OAQmlasS0buFDDl2IpMjXW9R0jYBxILC/g==","repository":{"url":"git+https://github.com/codebender-io/i18n-currency.git","type":"git"},"_npmVersion":"10.9.3","description":"Utils project for dealing with currencies","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/i18n-currency_0.1.1_1761737303788_0.5880951969504391","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@codebender-io/i18n-currency","version":"0.1.2","author":{"name":"codebender-io"},"license":"Apache-2.0","_id":"@codebender-io/i18n-currency@0.1.2","maintainers":[{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"}],"homepage":"https://github.com/codebender-io/i18n-currency#readme","bugs":{"url":"https://github.com/codebender-io/i18n-currency/issues"},"dist":{"shasum":"aad8adc9a574f44fda5bd28438579156b7e16a34","tarball":"https://registry.npmjs.org/@codebender-io/i18n-currency/-/i18n-currency-0.1.2.tgz","fileCount":99,"integrity":"sha512-rm5BhW7sRuMbsrYtdEPgyX9OM1NRkfk+gWYUr3E7edocy5UazRUF+EMULaOgzFMV0pPv0iYSLgSBm7n54n9Vvw==","signatures":[{"sig":"MEQCIFv+/rVGvblnRFyla+6kOfkaKmviQ9DIWmaT3T8Vh9GKAiBiERWKoKglj+ZPpnsDKBZasIgl1FgkFI3emUjZCBph6A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2187315},"main":"./dist/index.cjs","type":"module","_from":"file:codebender-io-i18n-currency-0.1.2.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./locales/*":"./locales/*"},"_npmUser":{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"},"_resolved":"/tmp/e0d81c68053cadd11fcc34cb787b5423/codebender-io-i18n-currency-0.1.2.tgz","_integrity":"sha512-rm5BhW7sRuMbsrYtdEPgyX9OM1NRkfk+gWYUr3E7edocy5UazRUF+EMULaOgzFMV0pPv0iYSLgSBm7n54n9Vvw==","repository":{"url":"git+https://github.com/codebender-io/i18n-currency.git","type":"git"},"_npmVersion":"10.9.3","description":"Utils project for dealing with currencies","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/i18n-currency_0.1.2_1761752190005_0.5258290669012708","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@codebender-io/i18n-currency","version":"0.1.3","author":{"name":"codebender-io"},"license":"Apache-2.0","_id":"@codebender-io/i18n-currency@0.1.3","maintainers":[{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"}],"homepage":"https://github.com/codebender-io/i18n-currency#readme","bugs":{"url":"https://github.com/codebender-io/i18n-currency/issues"},"dist":{"shasum":"a17cd1884553aef6da44f5212e30d58d1522db05","tarball":"https://registry.npmjs.org/@codebender-io/i18n-currency/-/i18n-currency-0.1.3.tgz","fileCount":99,"integrity":"sha512-WDaLqXoBht73Voq3Nz7zvMihnaDE8bgFiJvSKg/R/6wgLXw/OqZOangswGMo5VJzPbE2xICyGp0Iz/GhPUtY7g==","signatures":[{"sig":"MEUCIB3rXoa+ozsWvOySi9j53iIREtYX72s8goKFbZBqwVc9AiEA3HKmKUjTx3N4b8+GFx/BdEp6dYjXKqkuP0IVXTONEa4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2187703},"main":"./dist/index.cjs","type":"module","_from":"file:codebender-io-i18n-currency-0.1.3.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./locales/*":"./locales/*"},"_npmUser":{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"},"_resolved":"/tmp/09555f9a5c46bfd9f825f97be62bdc36/codebender-io-i18n-currency-0.1.3.tgz","_integrity":"sha512-WDaLqXoBht73Voq3Nz7zvMihnaDE8bgFiJvSKg/R/6wgLXw/OqZOangswGMo5VJzPbE2xICyGp0Iz/GhPUtY7g==","repository":{"url":"git+https://github.com/codebender-io/i18n-currency.git","type":"git"},"_npmVersion":"10.9.3","description":"Utils project for dealing with currencies","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/i18n-currency_0.1.3_1761753285721_0.8850723439913748","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@codebender-io/i18n-currency","version":"1.0.0","keywords":["i18n","internationalization","currency","currencies","localization","l10n","iso-4217","currency-codes","currency-symbols","currency-names","currency-data","money","financial","locale","locales","country","countries","multilingual","translation","typescript","utilities","library","metadata","formatting","node"],"author":{"name":"codebender-io"},"license":"Apache-2.0","_id":"@codebender-io/i18n-currency@1.0.0","maintainers":[{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"}],"homepage":"https://github.com/codebender-io/i18n-currency#readme","bugs":{"url":"https://github.com/codebender-io/i18n-currency/issues"},"dist":{"shasum":"9f40ae5a9b74e036fbdda6712b8d50e055a35ef5","tarball":"https://registry.npmjs.org/@codebender-io/i18n-currency/-/i18n-currency-1.0.0.tgz","fileCount":99,"integrity":"sha512-LmiieIYCjQKMHxbyTqsgaEjaBBNqaFiZKMCZcbpCillrLFqM/7TWGdEoySYdvdsZ+LYiYiAzLIdUn3/ICaY6nA==","signatures":[{"sig":"MEUCIQDWw3gU4TP5tZG5l/Jg6a4DfUkWZAi78Wt+Dp/Yf7NpZAIgUTXsafG+tpHe9ARj6OHcN78Dody2LJojJaYrCP+gOsY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2214561},"main":"./dist/index.cjs","type":"module","_from":"file:codebender-io-i18n-currency-1.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./locales/*":"./locales/*"},"_npmUser":{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"},"_resolved":"/tmp/20ab750cef4c39d2fa7d6d77e8ffc905/codebender-io-i18n-currency-1.0.0.tgz","_integrity":"sha512-LmiieIYCjQKMHxbyTqsgaEjaBBNqaFiZKMCZcbpCillrLFqM/7TWGdEoySYdvdsZ+LYiYiAzLIdUn3/ICaY6nA==","repository":{"url":"git+https://github.com/codebender-io/i18n-currency.git","type":"git"},"_npmVersion":"10.9.3","description":"Utility library for dealing with currencies","directories":{},"_nodeVersion":"22.20.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/i18n-currency_1.0.0_1761781524674_0.2708729801843135","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@codebender-io/i18n-currency","version":"2.0.0","description":"Utility library for dealing with currencies","license":"Apache-2.0","author":{"name":"codebender-io"},"type":"module","types":"./dist/index.d.ts","main":"./dist/index.cjs","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./locales/*":"./locales/*"},"engines":{"node":">=20"},"repository":{"type":"git","url":"git+https://github.com/codebender-io/i18n-currency.git"},"bugs":{"url":"https://github.com/codebender-io/i18n-currency/issues"},"homepage":"https://github.com/codebender-io/i18n-currency#readme","keywords":["i18n","internationalization","currency","currencies","localization","l10n","iso-4217","currency-codes","currency-symbols","currency-names","currency-data","money","financial","locale","locales","country","countries","multilingual","translation","typescript","utilities","library","metadata","formatting","node"],"_id":"@codebender-io/i18n-currency@2.0.0","_integrity":"sha512-LJC0trfsPTfBtBm6nq4Xj2sc3vi+NxI4LHlPn5lwCvuTppPbv0DG3Lvvwp4ckRd+iDn8NTIBJg4Qf8j9FiLsqw==","_resolved":"/tmp/13cd16b7cdd87462540695724760bbce/codebender-io-i18n-currency-2.0.0.tgz","_from":"file:codebender-io-i18n-currency-2.0.0.tgz","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-LJC0trfsPTfBtBm6nq4Xj2sc3vi+NxI4LHlPn5lwCvuTppPbv0DG3Lvvwp4ckRd+iDn8NTIBJg4Qf8j9FiLsqw==","shasum":"fda5012a36a869ede1cbf63fe2c7c82920934b20","tarball":"https://registry.npmjs.org/@codebender-io/i18n-currency/-/i18n-currency-2.0.0.tgz","fileCount":99,"unpackedSize":2196140,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE3RivTRJycRuRoQD7g2gx5FzaIxfHCPnIqrYKS7uEvsAiEAoCo+Y0MceMWfMDbDzRFPgPf55REwMeWq/fLbcp6uMXg="}]},"_npmUser":{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"},"directories":{},"maintainers":[{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/i18n-currency_2.0.0_1761849146315_0.27033874492265153"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-28T14:05:56.148Z","modified":"2025-10-30T18:32:26.763Z","0.1.0":"2025-10-28T14:05:56.551Z","0.1.1":"2025-10-29T11:28:24.039Z","0.1.2":"2025-10-29T15:36:30.248Z","0.1.3":"2025-10-29T15:54:45.935Z","1.0.0":"2025-10-29T23:45:24.971Z","2.0.0":"2025-10-30T18:32:26.543Z"},"bugs":{"url":"https://github.com/codebender-io/i18n-currency/issues"},"author":{"name":"codebender-io"},"license":"Apache-2.0","homepage":"https://github.com/codebender-io/i18n-currency#readme","keywords":["i18n","internationalization","currency","currencies","localization","l10n","iso-4217","currency-codes","currency-symbols","currency-names","currency-data","money","financial","locale","locales","country","countries","multilingual","translation","typescript","utilities","library","metadata","formatting","node"],"repository":{"type":"git","url":"git+https://github.com/codebender-io/i18n-currency.git"},"description":"Utility library for dealing with currencies","maintainers":[{"name":"a7med3ouda","email":"ahmed.ouda@codebender.io"}],"readme":"# @codebender-io/i18n-currency\n\n[![npm version](https://img.shields.io/npm/v/@codebender-io/i18n-currency?label=npm)](https://www.npmjs.com/package/@codebender-io/i18n-currency)\n[![License](https://img.shields.io/badge/license-Apache-2.0-blue.svg)](LICENSE)\n[![CI](https://github.com/codebender-io/i18n-currency/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/codebender-io/i18n-currency/actions)\nMaintained by **CodeBender** — website: https://codebender.io · GitHub: https://github.com/codebender-io\n\n---\n\n## What is this?\n\n`@codebender-io/i18n-currency` is a small, focused utility library that provides:\n\n- base ISO-4217 currency metadata (codes, symbols, decimal digits, subunit info),\n- localized currency names and subunit names for multiple locales,\n- convenient lookup utilities by locale and by country.\n\nIt is intended for server and client (Node >=20 / ESM) usage and designed in TypeScript with full types.\n\n## Size & bundle behaviour\n\n- **Base package (ESM, minified + gzipped)** — ~**39.7 KB**.\n- **Each locale file** (JSON) — ~**19–24 KB**.\n\nThe library is **fully modular** and **tree-shakeable**: we expose ESM modules and ship locale files as separate JSON assets, so your bundler will include **only** the base code and the locale files you import. In other words — _you ship what you use only_.\n\n### How to keep bundles small\n\n- Import only the locales you need (don't import the entire `locales` directory).\n- Use a standard production build (e.g. `webpack`/`rollup`/`esbuild`) with tree-shaking enabled to remove any unused exports.\n\n---\n\n## Install\n\n```bash\n# npm\nnpm install @codebender-io/i18n-currency\n\n# pnpm\npnpm add @codebender-io/i18n-currency\n\n# yarn\nyarn add @codebender-io/i18n-currency\n```\n\n---\n\n## ESM / CJS usage\n\nThe package ships both ESM and CommonJS builds. Use `import` for modern projects and `require()` for older environments.\n\n```ts\nimport { CurrencyLibrary } from \"@codebender-io/i18n-currency\";\n```\n\n```js\nconst { CurrencyLibrary } = require(\"@codebender-io/i18n-currency\");\n```\n\n---\n\n## Quick example\n\n```ts\nimport { CurrencyLibrary } from \"@codebender-io/i18n-currency\";\n// or for CJS require:\n// const { CurrencyLibrary } = require(\"@codebender-io/i18n-currency\");\n\nimport enLocales from \"@codebender-io/i18n-currency/locales/en.json\" assert { type: \"json\" };\n\nconst lib = new CurrencyLibrary({ locales: { en: enLocales }, fallbackLocale: \"en\" });\n\nconst usd = lib.getCurrency(\"en-US\", \"USD\");\nconsole.log(usd?.name); // \"US Dollar\" (for the provided locale data)\n```\n\n> Note: This package expects you to provide localized `locales` when constructing `CurrencyLibrary`. The library includes base currency metadata bundled in `src/data/base-currencies.json` and country mappings in `src/data/country-currencies.json`. Provide locale JSON maps for translated names.\n\n---\n\n## API\n\n### Types (summary)\n\n```ts\nexport interface CurrencyBase {\n\tcode: string;\n\tnumeric_code: string;\n\tsymbol: string;\n\tsymbol_native: string;\n\tdecimal_digits: number;\n\trounding: number;\n\tsubunit_to_unit: number;\n\tcountries: string[]; // ISO 3166-1 alpha-2 codes\n\tname_native: string;\n\tsubunit_name_native: string;\n}\n\nexport interface CurrencyLocalized {\n\tname: string;\n\tname_plural: string;\n\tsubunit_name: string;\n\tsubunit_name_plural: string;\n}\n\nexport type Currency = CurrencyBase & CurrencyLocalized;\nexport type CurrencyCode = string;\nexport type CurrencyBaseMap = Record<CurrencyCode, CurrencyBase>;\nexport type CurrencyLocalizedMap = Record<CurrencyCode, CurrencyLocalized>;\nexport type CurrencyMap = Record<CurrencyCode, Currency>;\nexport type LocaleCode = string;\nexport type LocaleCurrencyMap = Record<LocaleCode, CurrencyLocalizedMap>;\nexport type CountryCode = string;\nexport type CountryCurrencyMap = Record<CountryCode, CurrencyCode[]>;\n```\n\n### `new CurrencyLibrary({ locales, fallbackLocale = \"en\" })`\n\n- `locales: LocaleCurrencyMap` — mapping of locale keys (e.g., `en`, `fr`) to localized currency translations.\n- `fallbackLocale?: string` — fallback locale root (defaults to `\"en\"`). Throws if resolved fallback is not present in `locales`.\n\n### Methods\n\n- `getMap(locale: string): CurrencyMap`  \n  Returns a merged map of base currency data + localized fields for the best-match locale (root language fallback).\n\n- `getList(locale: string): Currency[]`  \n  Returns an array of all localized currency objects for the locale.\n\n- `getCurrency(locale: string, code: string): Currency | undefined`  \n  Returns a single localized currency object or `undefined` if not found.\n\n- `hasCurrency(code: string): boolean`  \n  Returns `true` if the currency code exists in base data.\n\n- `getCurrenciesByCountry(countryCode: string): CurrencyCode[]`  \n  Returns a list of currency codes used by the country (throws if country not found).\n\n- `getCountryCurrencyData(locale: string, countryCode: string): Currency[]`  \n  Returns the localized currency objects for the currencies used by `countryCode`.\n\n- `getPrimaryCurrencyByCountry(countryCode: string): CurrencyCode`  \n  The first currency code listed for the country.\n\n- `hasMultipleCurrencies(countryCode: string): boolean`  \n  `true` when the country uses multiple currencies.\n\n- `getSupportedCountryCodes(): CountryCode[]`  \n  All supported country codes (upper case).\n\n- `getCountriesByCurrency(currencyCode: CurrencyCode): CountryCode[]`  \n  Countries that use a specified currency.\n\n- `getCurrencyCodes(): CurrencyCode[]`  \n  All available ISO 4217 codes.\n\n- `getAvailableLocales(): LocaleCode[]`  \n  Returns locales provided in the initialization `locales` argument.\n\n- `getLocaleBestMatch(locale: string): string`  \n  Returns the best matching locale from available locales, falling back to the configured fallback locale.\n\n- `isLocaleSupported(locale: string): boolean`  \n  Checks if locale root is supported.\n\n---\n\n## ✅ Summary\n\n| Function                                      | Description                                 |\n| --------------------------------------------- | ------------------------------------------- |\n| `getMap(locale)`                              | Get currency map for locale                 |\n| `getList(locale)`                             | List all currencies for a locale            |\n| `getCurrency(locale, code)`                   | Get localized currency info                 |\n| `hasCurrency(code)`                           | Check if currency code exists               |\n| `getCurrenciesByCountry(countryCode)`         | Get currency codes by country               |\n| `getCountryCurrencyData(locale, countryCode)` | Get localized currency data by country      |\n| `getPrimaryCurrencyByCountry(countryCode)`    | Get country's main currency                 |\n| `hasMultipleCurrencies(countryCode)`          | Check if a country uses multiple currencies |\n| `getSupportedCountryCodes()`                  | List all supported country codes            |\n| `getCountriesByCurrency(code)`                | Get all countries using a currency          |\n| `getCurrencyCodes()`                          | List all available currency codes           |\n| `getAvailableLocales()`                       | List available locales                      |\n| `getLocaleBestMatch(locale)`                  | Get best matching locale                    |\n| `isLocaleSupported(locale)`                   | Verify if a locale is supported             |\n\n---\n\n## Locale JSON shape (example)\n\nA locale map should be an object where top-level keys are currency codes and values provide localized fields:\n\n```json\n{\n\t\"USD\": {\n\t\t\"name\": \"US Dollar\",\n\t\t\"name_plural\": \"US Dollars\",\n\t\t\"subunit_name\": \"cent\",\n\t\t\"subunit_name_plural\": \"cents\"\n\t},\n\t\"EUR\": {\n\t\t\"name\": \"Euro\",\n\t\t\"name_plural\": \"Euros\",\n\t\t\"subunit_name\": \"cent\",\n\t\t\"subunit_name_plural\": \"cents\"\n\t}\n}\n```\n\nYou can provide multiple locale roots:\n\n```ts\nconst locales = {\n\ten: require(\"@codebender-io/i18n-currency/locales/en.json\"),\n\tfr: require(\"@codebender-io/i18n-currency/locales/fr.json\"),\n};\n```\n\n---\n\n# Usage Examples\n\nThis document demonstrates how to use the **CurrencyLibrary** class to access currency and localization data.\n\n---\n\n## 1. Importing and Initializing the Library\n\n```ts\nimport { CurrencyLibrary } from \"@codebender-io/i18n-currency\";\nimport en from \"@codebender-io/i18n-currency/locales/en.json\" assert { type: \"json\" };\nimport fr from \"@codebender-io/i18n-currency/locales/fr.json\" assert { type: \"json\" };\n\n// Initialize with available locales\nconst lib = new CurrencyLibrary({\n\tlocales: { en, fr },\n\tfallbackLocale: \"en\",\n});\n```\n\n---\n\n## 2. Get Localized Currency Data\n\n### Get a Specific Currency\n\n```ts\nconst usd = lib.getCurrency(\"en-US\", \"usd\");\nconsole.log(usd?.name); // \"US Dollar\"\n```\n\n### Get All Currencies for a Locale\n\n```ts\nconst currencies = lib.getList(\"fr\");\nconsole.log(currencies.length); // e.g., 180\n```\n\n### Check if a Currency Exists\n\n```ts\nconsole.log(lib.hasCurrency(\"JPY\")); // true\n```\n\n---\n\n## 3. Country-Based Lookups\n\n### Get All Currencies Used by a Country\n\n```ts\nconst currencies = lib.getCurrenciesByCountry(\"US\");\nconsole.log(currencies); // [\"USD\"]\n```\n\n### Get Localized Currency Data for a Country\n\n```ts\nconst countryData = lib.getCountryCurrencyData(\"fr\", \"CA\");\nconsole.log(countryData[0].name); // \"Dollar canadien\"\n```\n\n### Get Primary Currency of a Country\n\n```ts\nconst mainCurrency = lib.getPrimaryCurrencyByCountry(\"JP\");\nconsole.log(mainCurrency); // \"JPY\"\n```\n\n### Check if a Country Has Multiple Currencies\n\n```ts\nconsole.log(lib.hasMultipleCurrencies(\"CH\")); // true (Switzerland: CHF, EUR)\n```\n\n---\n\n## 4. Supported Data Utilities\n\n### List Supported Countries\n\n```ts\nconst countries = lib.getSupportedCountryCodes();\nconsole.log(countries.slice(0, 5)); // [\"US\", \"CA\", \"GB\", \"FR\", \"DE\"]\n```\n\n### List Supported Currency Codes\n\n```ts\nconst codes = lib.getCurrencyCodes();\nconsole.log(codes.length); // e.g., 180\n```\n\n### Get Countries Using a Specific Currency\n\n```ts\nconst euroCountries = lib.getCountriesByCurrency(\"EUR\");\nconsole.log(euroCountries); // [\"FR\", \"DE\", \"IT\", \"ES\", ...]\n```\n\n### List Available Locales\n\n```ts\nconsole.log(lib.getAvailableLocales()); // [\"en\", \"fr\"]\n```\n\n### Check Locale Support\n\n```ts\nconsole.log(lib.isLocaleSupported(\"fr-CA\")); // true\nconsole.log(lib.isLocaleSupported(\"xx-YY\")); // false\n```\n\n---\n\n## 5. Locale Matching\n\n### Get Best Match for a Locale\n\n```ts\nconsole.log(lib.getLocaleBestMatch(\"en-US\")); // \"en\"\nconsole.log(lib.getLocaleBestMatch(\"fr-CA\")); // \"fr\"\nconsole.log(lib.getLocaleBestMatch(\"xx-YY\")); // \"en\" (fallback)\n```\n\n---\n\n## Contribution\n\nContributions welcome! Please open issues or PRs on GitHub: https://github.com/codebender-io/i18n-currency\n\nSuggested workflow:\n\n1. Fork repository\n2. Create feature branch\n3. Run `pnpm install`\n4. Run `pnpm build`\n5. Run `pnpm test` (if available)\n6. Open PR and describe changes\n\n---\n\n## License\n\nApache-2.0 — see `LICENSE` file.\n\n---\n\n## Contact & Links\n\n- Website: https://codebender.io\n- GitHub: https://github.com/codebender-io\n- npm org: https://www.npmjs.com/org/codebender-io\n- LinkedIn: https://www.linkedin.com/company/codebender-io\n\n---\n\n## Publishing notes\n\n- Scoped packages default to private on npm. To publish publicly use:\n    ```bash\n    npm publish --access public\n    ```\n- Ensure you are logged into an npm user that has publish access to `@codebender-io`.\n\n---\n\nCopyright © 2025 [CodeBender](https://codebender.io). Licensed under Apache-2.0. See [LICENSE](LICENSE) for details.\n","readmeFilename":"README.md"}