{"_id":"@countrystatecity/currencies","_rev":"6-6cd67a7738acf36d6ef783556f7a8203","name":"@countrystatecity/currencies","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.0":{"name":"@countrystatecity/currencies","version":"1.0.0","keywords":["country-state-city","currencies","currency","iso-4217","money","exchange","symbol","typescript","lazy-loading"],"author":{"name":"dr5hn"},"license":"ODbL-1.0","_id":"@countrystatecity/currencies@1.0.0","maintainers":[{"name":"dr5hn","email":"gadadarshan@gmail.com"}],"homepage":"https://github.com/dr5hn/countrystatecity-currencies#readme","bugs":{"url":"https://github.com/dr5hn/countrystatecity-currencies/issues"},"dist":{"shasum":"502699d8ae696917bf92ec9a21c47bf2f00ff02d","tarball":"https://registry.npmjs.org/@countrystatecity/currencies/-/currencies-1.0.0.tgz","fileCount":9,"integrity":"sha512-alERAFsXjrm+xp1d8uFTCRvXw9eu/lwEbJHm6kArrrjVwqLJX5R+MmknIMu12Z4/7Chtn8KhvFoJPAxlekCPUQ==","signatures":[{"sig":"MEYCIQDHGDgIHcBym1XSLASGqgar9jtsuccKYthO4A0MD3EfsAIhAMXKv2tgmhxd/057nwkjB/sUdvdfdVvivTOPA2/hS+yG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@countrystatecity%2fcurrencies@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":69976},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./data/*":"./dist/data/*"},"gitHead":"d9ac2ac2017e80d0b698b6475d7a04a831aafd38","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:compat":"vitest run compatibility"},"_npmUser":{"name":"dr5hn","email":"gadadarshan@gmail.com"},"repository":{"url":"git+https://github.com/dr5hn/countrystatecity-currencies.git","type":"git"},"_npmVersion":"10.8.2","description":"Comprehensive world currency data with ISO 4217 codes, symbols, and country mappings","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^2.0.0","typescript":"^5.9.0","@types/node":"^20.19.0"},"_npmOperationalInternal":{"tmp":"tmp/currencies_1.0.0_1780563148471_0.5869454304399122","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@countrystatecity/currencies","version":"1.0.1","keywords":["country-state-city","currencies","currency","iso-4217","money","exchange","symbol","typescript","lazy-loading"],"author":{"name":"dr5hn"},"license":"ODbL-1.0","_id":"@countrystatecity/currencies@1.0.1","maintainers":[{"name":"dr5hn","email":"gadadarshan@gmail.com"}],"homepage":"https://github.com/dr5hn/countrystatecity-currencies#readme","bugs":{"url":"https://github.com/dr5hn/countrystatecity-currencies/issues"},"dist":{"shasum":"ebba6b65a953f20e77cac363e64a89ec574549f1","tarball":"https://registry.npmjs.org/@countrystatecity/currencies/-/currencies-1.0.1.tgz","fileCount":9,"integrity":"sha512-s4HVg+Cxh48eojpccBAsDBTvUyaDi9uXOYfunxSIyFBRCG27wlVMTzUTmZKt4Lc/qSr78a44/0TPpOV8SMTNow==","signatures":[{"sig":"MEUCIAPr645L7stxdKOo7Goh1ZhJW34pqN5C3Frnrm1/jynsAiEAvbSeuA3T9lbiS2xFiimjROPK7kSnGAepkLWt1QcF4NE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73507},"main":"./dist/index.cjs","type":"module","_from":"file:countrystatecity-currencies-1.0.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./data/*":"./dist/data/*"},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:compat":"vitest run compatibility"},"_npmUser":{"name":"dr5hn","email":"gadadarshan@gmail.com"},"_resolved":"/tmp/98d755cf964fa4aaa6c24b18e4052ede/countrystatecity-currencies-1.0.1.tgz","_integrity":"sha512-s4HVg+Cxh48eojpccBAsDBTvUyaDi9uXOYfunxSIyFBRCG27wlVMTzUTmZKt4Lc/qSr78a44/0TPpOV8SMTNow==","repository":{"url":"git+https://github.com/dr5hn/countrystatecity-currencies.git","type":"git"},"_npmVersion":"10.8.2","description":"Comprehensive world currency data with ISO 4217 codes, symbols, and country mappings","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^4.1.8","typescript":"^5.9.0","@types/node":"^20.19.0"},"_npmOperationalInternal":{"tmp":"tmp/currencies_1.0.1_1781165869197_0.7241890485633664","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@countrystatecity/currencies","version":"1.0.2","keywords":["country-state-city","currencies","currency","iso-4217","money","exchange","symbol","typescript","lazy-loading"],"author":{"name":"dr5hn"},"license":"ODbL-1.0","_id":"@countrystatecity/currencies@1.0.2","maintainers":[{"name":"dr5hn","email":"gadadarshan@gmail.com"}],"homepage":"https://github.com/dr5hn/countrystatecity-currencies#readme","bugs":{"url":"https://github.com/dr5hn/countrystatecity-currencies/issues"},"dist":{"shasum":"183c1ea471edb37de7e51dd47b0544a719101a8b","tarball":"https://registry.npmjs.org/@countrystatecity/currencies/-/currencies-1.0.2.tgz","fileCount":9,"integrity":"sha512-QCXsllqlaCWQ45jJuaGkKQIo9HlMVCdNN7lJoMq3QJNBT/X4Sj4/zMw5CNF3rSvVNVG70De3oohWUIB+tp/c0w==","signatures":[{"sig":"MEYCIQCtVpKb58efF4jeTfka0qLUrwWGe6+HNWoI2cWtwZ1FvgIhAMysqmhDm9GXDsb6pBI3WcFnzzLdRa96X+NhxjRdCsZP","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73507},"main":"./dist/index.cjs","type":"module","_from":"file:countrystatecity-currencies-1.0.2.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./data/*":"./dist/data/*"},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:compat":"vitest run compatibility"},"_npmUser":{"name":"dr5hn","email":"gadadarshan@gmail.com"},"_resolved":"/tmp/bfaf009dc82720237ddb592aa87fc53c/countrystatecity-currencies-1.0.2.tgz","_integrity":"sha512-QCXsllqlaCWQ45jJuaGkKQIo9HlMVCdNN7lJoMq3QJNBT/X4Sj4/zMw5CNF3rSvVNVG70De3oohWUIB+tp/c0w==","repository":{"url":"git+https://github.com/dr5hn/countrystatecity-currencies.git","type":"git"},"_npmVersion":"10.8.2","description":"Comprehensive world currency data with ISO 4217 codes, symbols, and country mappings","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^4.1.8","typescript":"^5.9.0","@types/node":"^20.19.0"},"_npmOperationalInternal":{"tmp":"tmp/currencies_1.0.2_1781168799821_0.34577739833092314","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@countrystatecity/currencies","version":"1.0.3","keywords":["country-state-city","currencies","currency","iso-4217","money","exchange","symbol","typescript","lazy-loading"],"author":{"name":"dr5hn"},"license":"ODbL-1.0","_id":"@countrystatecity/currencies@1.0.3","maintainers":[{"name":"dr5hn","email":"gadadarshan@gmail.com"}],"homepage":"https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/currencies#readme","bugs":{"url":"https://github.com/dr5hn/countrystatecity-npm/issues"},"dist":{"shasum":"f5271c8cbfa6829e0bc99168d781739e27bc8bad","tarball":"https://registry.npmjs.org/@countrystatecity/currencies/-/currencies-1.0.3.tgz","fileCount":9,"integrity":"sha512-+aBy0YNReKaaP38qaWhMfv8jtE3t0LEKbm0i7rti3Aj1LthjOgqA6u5o40Ye0X046+2/CopMqrixcTDZCMLWcA==","signatures":[{"sig":"MEQCIGtQsKxfZXWRO1KzugYaRXNTjcJLj74wC7bfv3VnBOdAAiBXJLm0gkEQDsH49++guNZF8ixEmaTCw7sJ3hWtz6UImw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73573},"main":"./dist/index.cjs","type":"module","_from":"file:countrystatecity-currencies-1.0.3.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./data/*":"./dist/data/*"},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:compat":"vitest run compatibility","generate-data":"node scripts/generate-data.cjs"},"_npmUser":{"name":"dr5hn","email":"gadadarshan@gmail.com"},"_resolved":"/tmp/f94e8e48a48261425af7215d73323c4e/countrystatecity-currencies-1.0.3.tgz","_integrity":"sha512-+aBy0YNReKaaP38qaWhMfv8jtE3t0LEKbm0i7rti3Aj1LthjOgqA6u5o40Ye0X046+2/CopMqrixcTDZCMLWcA==","repository":{"url":"git+https://github.com/dr5hn/countrystatecity-npm.git","type":"git"},"_npmVersion":"10.8.2","description":"Comprehensive world currency data with ISO 4217 codes, symbols, and country mappings","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^4.1.8","typescript":"^5.9.0","@types/node":"^20.19.0"},"_npmOperationalInternal":{"tmp":"tmp/currencies_1.0.3_1781173091789_0.7534266051107721","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@countrystatecity/currencies","version":"1.0.4","keywords":["country-state-city","currencies","currency","iso-4217","money","exchange","symbol","typescript","lazy-loading"],"author":{"name":"dr5hn"},"license":"ODbL-1.0","_id":"@countrystatecity/currencies@1.0.4","maintainers":[{"name":"dr5hn","email":"gadadarshan@gmail.com"}],"homepage":"https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/currencies#readme","bugs":{"url":"https://github.com/dr5hn/countrystatecity-npm/issues"},"dist":{"shasum":"1accd0050b60e13fb612772fb70f7bddb55aced6","tarball":"https://registry.npmjs.org/@countrystatecity/currencies/-/currencies-1.0.4.tgz","fileCount":9,"integrity":"sha512-2AhjjVBtnsxdUnQ4bsIpoBa0Y99L71pIG7r3Q2nP+Ol+HI0hQfrHv3gzb4B2d10+tilpNn1f08On9D00CTSl5g==","signatures":[{"sig":"MEQCIGPKzX/7+vQXkVr6Fi69wLt7dhrbM196/G1ttw0bJ6eRAiA6LRRgI47A3Yzs57lNLTmPVHOGUV/OmYDtRMD3l4UQhA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":73534},"main":"./dist/index.cjs","type":"module","_from":"file:countrystatecity-currencies-1.0.4.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./data/*":"./dist/data/*"},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","test:compat":"vitest run compatibility","generate-data":"node scripts/generate-data.cjs"},"_npmUser":{"name":"dr5hn","email":"gadadarshan@gmail.com"},"_resolved":"/tmp/3955b4a34f042c414089b61001a72ec3/countrystatecity-currencies-1.0.4.tgz","_integrity":"sha512-2AhjjVBtnsxdUnQ4bsIpoBa0Y99L71pIG7r3Q2nP+Ol+HI0hQfrHv3gzb4B2d10+tilpNn1f08On9D00CTSl5g==","repository":{"url":"git+https://github.com/dr5hn/countrystatecity-npm.git","type":"git"},"_npmVersion":"10.8.2","description":"Comprehensive world currency data with ISO 4217 codes, symbols, and country mappings","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^4.1.8","typescript":"^5.9.0","@types/node":"^20.19.0"},"_npmOperationalInternal":{"tmp":"tmp/currencies_1.0.4_1786169492770_0.9701640627000476","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@countrystatecity/currencies","version":"1.0.5","description":"Comprehensive world currency data with ISO 4217 codes, symbols, and country mappings","keywords":["country-state-city","currencies","currency","iso-4217","money","exchange","symbol","typescript","lazy-loading"],"author":{"name":"dr5hn"},"license":"ODbL-1.0","repository":{"type":"git","url":"git+https://github.com/dr5hn/countrystatecity-npm.git"},"homepage":"https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/currencies#readme","bugs":{"url":"https://github.com/dr5hn/countrystatecity-npm/issues"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./data/*":"./dist/data/*"},"devDependencies":{"@types/node":"^20.19.0","tsup":"^8.5.0","typescript":"^5.9.0","vitest":"^4.1.8"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:compat":"vitest run compatibility","typecheck":"tsc --noEmit","generate-data":"node scripts/generate-data.cjs"},"_id":"@countrystatecity/currencies@1.0.5","_integrity":"sha512-EkNtCuHnjtQuFqXpiLSh0dkfKySmTsCMPc82F8/OefPDF7abVKRGN2JR5Isa5RS89qRJ8Y8XIwyWlAvoQGtEnA==","_resolved":"/tmp/cb1d8bf0e66d5d4ac6ff1733eae7c02c/countrystatecity-currencies-1.0.5.tgz","_from":"file:countrystatecity-currencies-1.0.5.tgz","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-EkNtCuHnjtQuFqXpiLSh0dkfKySmTsCMPc82F8/OefPDF7abVKRGN2JR5Isa5RS89qRJ8Y8XIwyWlAvoQGtEnA==","shasum":"0b0b2524c5edb064ef24fac9e2ef6eee381e4338","tarball":"https://registry.npmjs.org/@countrystatecity/currencies/-/currencies-1.0.5.tgz","fileCount":9,"unpackedSize":73534,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGQDxZBRisiRdJV+XKIIDgc4YTvO75IsC9BtVMdSfBfYAiBf3X/y2QL8uzb+BWvf7E/WGpxo39TUKZ9zZM/wv1LE/w=="}]},"_npmUser":{"name":"dr5hn","email":"gadadarshan@gmail.com"},"directories":{},"maintainers":[{"name":"dr5hn","email":"gadadarshan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/currencies_1.0.5_1786188776568_0.6247115619343024"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-04T08:52:28.308Z","modified":"2026-08-08T11:32:56.860Z","1.0.0":"2026-06-04T08:52:28.677Z","1.0.1":"2026-06-11T08:17:49.362Z","1.0.2":"2026-06-11T09:06:39.978Z","1.0.3":"2026-06-11T10:18:11.955Z","1.0.4":"2026-08-08T06:11:32.927Z","1.0.5":"2026-08-08T11:32:56.707Z"},"bugs":{"url":"https://github.com/dr5hn/countrystatecity-npm/issues"},"author":{"name":"dr5hn"},"license":"ODbL-1.0","homepage":"https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/currencies#readme","keywords":["country-state-city","currencies","currency","iso-4217","money","exchange","symbol","typescript","lazy-loading"],"repository":{"type":"git","url":"git+https://github.com/dr5hn/countrystatecity-npm.git"},"description":"Comprehensive world currency data with ISO 4217 codes, symbols, and country mappings","maintainers":[{"name":"dr5hn","email":"gadadarshan@gmail.com"}],"readme":"# @countrystatecity/currencies\n\n[![npm](https://img.shields.io/npm/v/@countrystatecity/currencies)](https://www.npmjs.com/package/@countrystatecity/currencies)\n[![CI](https://github.com/dr5hn/countrystatecity-npm/workflows/Pipeline/badge.svg)](https://github.com/dr5hn/countrystatecity-npm/actions/workflows/ci.yml)\n[![npm downloads](https://img.shields.io/npm/dm/@countrystatecity/currencies?label=currencies)](https://www.npmjs.com/package/@countrystatecity/currencies)\n[![npm downloads](https://img.shields.io/npm/dw/@countrystatecity/currencies?label=currencies)](https://www.npmjs.com/package/@countrystatecity/currencies)\n\nComprehensive world currency data with ISO 4217 codes, symbols, and country mappings.\n\n## ✨ Features\n\n- 💰 **155 ISO 4217 Currencies**: Complete world currency database\n- 🌍 **195 Countries**: Full country-to-currency and currency-to-countries mapping\n- 🔍 **Flexible Lookup**: Find by code, name, symbol, or country\n- 🖋️ **Native Symbols**: Both display (`$`) and native (`₹`) symbols included\n- 🔢 **Decimal Rules**: Correct `decimalDigits` and `rounding` per currency\n- 🎨 **Amount Formatting**: Format numbers as currency strings out of the box\n- 🚀 **Minimal Bundle**: <3KB initial load with lazy-loaded data file\n- 📦 **ESM + CJS**: Works in Node.js, browsers, and edge runtimes\n- 📝 **TypeScript**: Full type definitions included\n- 🔧 **Tree-Shakeable**: Only bundle what you use\n\n## 📦 Installation\n\n```bash\nnpm install @countrystatecity/currencies\n# or\nyarn add @countrystatecity/currencies\n# or\npnpm add @countrystatecity/currencies\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport {\n  getCurrencies,\n  getCurrencyByCode,\n  getCurrenciesByCountry,\n  searchCurrencies,\n  formatCurrencyAmount,\n} from '@countrystatecity/currencies';\n\n// Get all currencies\nconst currencies = await getCurrencies();\nconsole.log(currencies.length); // 155\n\n// Look up by ISO 4217 code\nconst usd = await getCurrencyByCode('USD');\nconsole.log(usd);\n// {\n//   code: 'USD',\n//   name: 'US Dollar',\n//   namePlural: 'US dollars',\n//   symbol: '$',\n//   symbolNative: '$',\n//   decimalDigits: 2,\n//   rounding: 0,\n//   countries: ['AS', 'EC', 'FM', 'GU', 'IO', 'MH', 'MP', 'PR', 'PW', 'SV', 'TC', 'TL', 'UM', 'US', 'VG', 'VI']\n// }\n\n// Get all currencies used in a country\nconst inCurrencies = await getCurrenciesByCountry('IN');\nconsole.log(inCurrencies);\n// [{ code: 'INR', name: 'Indian Rupee', symbol: '₹', ... }]\n\n// Format an amount\nconst formatted = await formatCurrencyAmount(1234.5, 'USD');\nconsole.log(formatted); // \"$1,234.50\"\n```\n\n## 📖 API Reference\n\n### Core Functions\n\n#### `getCurrencies()`\n\nGet all available currencies.\n\n```typescript\nconst currencies = await getCurrencies();\n// Returns: ICurrency[]\n```\n\n#### `getCurrencyByCode(code: string)`\n\nGet a currency by its ISO 4217 code.\n\n```typescript\nconst currency = await getCurrencyByCode('EUR');\n// Returns: ICurrency | undefined\n```\n\n**Parameters:**\n- `code` — ISO 4217 currency code (e.g., `'USD'`, `'EUR'`). Case-insensitive.\n\n#### `getCurrenciesByCountry(countryCode: string)`\n\nGet all currencies used in a given country.\n\n```typescript\nconst currencies = await getCurrenciesByCountry('US');\n// Returns: ICurrency[]\n```\n\n**Parameters:**\n- `countryCode` — ISO 3166-1 alpha-2 country code (e.g., `'US'`, `'IN'`). Case-insensitive.\n\n#### `isValidCurrencyCode(code: string)`\n\nCheck whether a string is a valid ISO 4217 currency code.\n\n```typescript\nconst valid = await isValidCurrencyCode('USD'); // true\nconst invalid = await isValidCurrencyCode('XYZ'); // false\n// Returns: boolean\n```\n\n#### `searchCurrencies(query: string)`\n\nSearch currencies by name or code (case-insensitive, partial match).\n\n```typescript\nconst results = await searchCurrencies('dollar');\n// Returns: ICurrency[]  — USD, CAD, AUD, HKD, ...\n```\n\n### Utility Functions\n\n#### `getCurrencySymbol(code: string)`\n\nGet the display symbol for a currency code.\n\n```typescript\nconst symbol = await getCurrencySymbol('USD');\n// Returns: \"$\"\n```\n\n#### `getCurrencySymbolNative(code: string)`\n\nGet the native/local symbol for a currency code.\n\n```typescript\nconst symbol = await getCurrencySymbolNative('INR');\n// Returns: \"₹\"\n```\n\n#### `getCurrencyBySymbol(symbol: string)`\n\nFind a currency by its symbol (checks both `symbol` and `symbolNative`).\n\n```typescript\nconst currency = await getCurrencyBySymbol('€');\n// Returns: ICurrency | undefined  — EUR\n```\n\n#### `formatCurrencyAmount(amount: number, code: string)`\n\nFormat a number as a currency string using the currency's symbol and decimal rules.\n\n```typescript\nconst formatted = await formatCurrencyAmount(1234567.5, 'USD');\n// Returns: \"$1,234,567.50\"\n\nconst jpy = await formatCurrencyAmount(1234567, 'JPY');\n// Returns: \"¥1,234,567\"  (JPY has 0 decimal digits)\n```\n\n**Parameters:**\n- `amount` — The numeric amount to format\n- `code` — ISO 4217 currency code\n\n## 🌍 Real-World Examples\n\n### Price Formatter\n\n```typescript\nimport { formatCurrencyAmount, getCurrencyByCode } from '@countrystatecity/currencies';\n\nasync function displayPrice(amount: number, currencyCode: string) {\n  const currency = await getCurrencyByCode(currencyCode);\n  if (!currency) return String(amount);\n\n  const formatted = await formatCurrencyAmount(amount, currencyCode);\n  return `${formatted} (${currency.name})`;\n}\n\nconsole.log(await displayPrice(99.99, 'USD')); // \"$99.99 (US Dollar)\"\nconsole.log(await displayPrice(8500, 'JPY'));   // \"¥8,500 (Japanese Yen)\"\nconsole.log(await displayPrice(4999, 'INR'));   // \"₹4,999 (Indian Rupee)\"\n```\n\n### Country Currency Lookup\n\n```typescript\nimport { getCurrenciesByCountry } from '@countrystatecity/currencies';\n\nasync function getCountryCurrencyInfo(countryCode: string) {\n  const currencies = await getCurrenciesByCountry(countryCode);\n\n  return currencies.map((c) => ({\n    code: c.code,\n    name: c.name,\n    symbol: c.symbol,\n    nativeSymbol: c.symbolNative,\n  }));\n}\n\nconst usCurrencies = await getCountryCurrencyInfo('US');\n// [{ code: 'USD', name: 'US Dollar', symbol: '$', nativeSymbol: '$' }]\n\nconst paCurrencies = await getCountryCurrencyInfo('PA'); // Panama uses USD + PAB\n// [{ code: 'PAB', ... }, { code: 'USD', ... }]\n```\n\n### Currency Search & Validator\n\n```typescript\nimport { searchCurrencies, isValidCurrencyCode } from '@countrystatecity/currencies';\n\n// Autocomplete: suggest currencies matching a query\nasync function autocompleteCurrency(input: string) {\n  if (input.length < 2) return [];\n  return searchCurrencies(input);\n}\n\n// Validate user input before processing payment\nasync function validatePayload(code: string, amount: number) {\n  const isValid = await isValidCurrencyCode(code);\n  if (!isValid) throw new Error(`Unknown currency code: ${code}`);\n  if (amount <= 0) throw new Error('Amount must be positive');\n  return true;\n}\n\nawait validatePayload('USD', 100); // true\nawait validatePayload('XYZ', 100); // throws Error\n```\n\n### Multi-Currency Cart\n\n```typescript\nimport { getCurrencyByCode, formatCurrencyAmount } from '@countrystatecity/currencies';\n\ninterface CartItem {\n  name: string;\n  price: number;\n  currency: string;\n}\n\nasync function renderCart(items: CartItem[]) {\n  const rendered = [];\n\n  for (const item of items) {\n    const currency = await getCurrencyByCode(item.currency);\n    const formatted = await formatCurrencyAmount(item.price, item.currency);\n    rendered.push({\n      name: item.name,\n      price: formatted,\n      decimals: currency?.decimalDigits ?? 2,\n    });\n  }\n\n  return rendered;\n}\n\nconst cart = await renderCart([\n  { name: 'Book', price: 12.99, currency: 'USD' },\n  { name: 'Manga', price: 880, currency: 'JPY' },\n  { name: 'Tea', price: 250.5, currency: 'INR' },\n]);\n```\n\n## 🔧 TypeScript Types\n\n```typescript\ninterface ICurrency {\n  code: string;          // \"USD\" — ISO 4217 code\n  name: string;          // \"US Dollar\"\n  namePlural: string;    // \"US dollars\"\n  symbol: string;        // \"$\"\n  symbolNative: string;  // \"$\" (or \"₹\" for INR, \"د.إ.‏\" for AED, etc.)\n  decimalDigits: number; // 2 (0 for JPY, 3 for KWD, etc.)\n  rounding: number;      // 0 (or 0.05 for CHF, etc.)\n  countries: string[];   // [\"US\", \"EC\", \"SV\", ...] — ISO 3166-1 alpha-2\n}\n```\n\n## 📊 Bundle Size\n\n| Action | Bundle Size |\n|--------|-------------|\n| Install package + import function | ~3KB |\n| Load all currencies | ~40KB |\n| **Typical usage** | **~3KB** |\n\n### Data Coverage\n\n- **155 ISO 4217 Currencies**: All major and minor world currencies\n- **195 Countries**: Complete country-to-currency mappings\n- **Multi-currency countries**: Countries that use more than one currency (e.g., Panama, Zimbabwe) are fully supported\n\n**Note**: Currency data is automatically sourced from the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database) and updates weekly.\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Watch mode\nnpm run test:watch\n```\n\nAll packages include comprehensive tests:\n- ✅ Unit tests for every function\n- ✅ Integration tests\n- ✅ ESM + CJS compatibility tests\n\n## 🔄 CI/CD & Automation\n\n### Continuous Integration\nEvery push and PR automatically:\n- ✅ Runs type checking with TypeScript\n- ✅ Executes comprehensive test suite across Node.js 18, 20, and 22\n- ✅ Builds the package\n\n### Automated Data Updates\nWeekly automated updates (Sundays at 00:00 UTC):\n- 📥 Downloads latest currency data from authoritative sources\n- 🔄 Regenerates `currencies.json` with updated mappings\n- 🧪 Runs full test suite\n- 📝 Creates PR for review if changes detected\n\nThis ensures your application always has access to the most current currency information without manual intervention.\n\n### Automated Publishing\nAutomated publishing to npm on GitHub Release:\n- 📦 Builds and tests before publishing\n- 🚀 Publishes to npm registry with provenance\n- 🏷️ Linked to the exact source commit\n\n## 📄 License\n\n[ODbL-1.0](https://github.com/dr5hn/countrystatecity/blob/main/LICENSE) © [dr5hn](https://github.com/dr5hn)\n\nThis package and its data are licensed under the Open Database License (ODbL) v1.0. The data is sourced from the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database) which is also licensed under ODbL-1.0.\n\nYou are free to share, create, and adapt this database as long as you attribute the original sources, distribute adaptations under the same license, and don't use technical restrictions to lock down the data.\n\n## 🤝 Contributing\n\nContributions are welcome! Please open an issue or PR.\n\n**For data-related issues** (incorrect currency data, missing currencies, wrong symbols, etc.), please report them to the [Countries States Cities Database](https://github.com/dr5hn/countries-states-cities-database/issues) repository, which is the authoritative source of data for this package.\n\n## 📦 Package Ecosystem\n\nThis package is part of the [@countrystatecity package ecosystem](https://github.com/dr5hn/countrystatecity-npm):\n\n- **[@countrystatecity/countries](https://www.npmjs.com/package/@countrystatecity/countries)** — Server-side countries, states, and cities database. Environment: Node.js, Next.js API routes, Express. Bundle: <10KB initial load.\n\n- **[@countrystatecity/countries-browser](https://www.npmjs.com/package/@countrystatecity/countries-browser)** — Browser-native version with jsDelivr CDN and lazy loading. Environment: React, Vue, Svelte, Vite, any browser. Same API as the server package — zero config, just import and use.\n\n- **[@countrystatecity/timezones](https://www.npmjs.com/package/@countrystatecity/timezones)** — Comprehensive timezone data with conversion utilities. Environment: Server-side only. Bundle: <20KB initial load.\n\n- **[@countrystatecity/currencies](https://www.npmjs.com/package/@countrystatecity/currencies)** (This package) — ISO 4217 currency data with symbols, decimal rules, and country mappings. Environment: Node.js, browsers, edge runtimes. Bundle: <3KB initial load.\n\n## 🔗 Links\n\n- [GitHub Repository](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/currencies)\n- [Issues](https://github.com/dr5hn/countrystatecity-npm/issues)\n- [NPM Package](https://www.npmjs.com/package/@countrystatecity/currencies)\n- [NPM Organization](https://www.npmjs.com/org/countrystatecity)\n","readmeFilename":"README.md"}