curcode

A lightweight Node.js module to lookup and work with currency codes, symbols, and countries based on the ISO 4217 standard.

Features

• 🔍 Lookup currencies by code, symbol, number, or country
• 💱 179 currencies with complete ISO 4217 data
• 🌍 260+ countries coverage
• 💲 Currency symbols for all codes
• 📦 Zero dependencies for production use
• 📘 TypeScript support with full type definitions
• ⚡ Fast & efficient - pure data lookups, no async operations

Installation

Install using your preferred package manager:

npm

npm install curcode

yarn

yarn add curcode

pnpm

pnpm add curcode

bun

bun add curcode

Usage

JavaScript (CommonJS)

const curcode = require('curcode');

// Lookup by currency code
const euro = curcode.code('EUR');
console.log(euro);
// {
//   code: 'EUR',
//   number: '978',
//   digits: 2,
//   currency: 'Euro',
//   symbol: '€',
//   countries: ['Åland Islands', 'Andorra', 'Austria', ...]
// }

// Lookup by symbol
const dollar = curcode.symbol('$');
console.log(dollar.code); // 'AED' (first match)

// Lookup by country
const colombianCurrencies = curcode.country('Colombia');
console.log(colombianCurrencies);
// [
//   { code: 'COP', number: '170', ... },
//   { code: 'COU', number: '970', ... }
// ]

// Lookup by numeric code
const zambian = curcode.number(967);
console.log(zambian.currency); // 'Zambian Kwacha'

TypeScript

import * as curcode from 'curcode';
// or
import { code, symbol, country, number, codes, numbers, countries, data, symbols, publishDate, CurrencyCodeRecord } from 'curcode';

// Type-safe currency lookup
const eur: CurrencyCodeRecord | undefined = curcode.code('EUR');

if (eur) {
  console.log(eur.symbol); // '€'
  console.log(eur.digits); // 2
}

// Get all currency codes
const allCodes: string[] = curcode.codes();
console.log(allCodes.length); // 179

// Get all countries
const allCountries: string[] = curcode.countries();
console.log(allCountries.length); // 260

ES Modules (with Node.js + type: "module")

import curcode from 'curcode';

const usd = curcode.code('USD');
console.log(usd.currency); // 'US Dollar'

Bun

import curcode from 'curcode';

// Bun works with both CommonJS and ES modules
const gbp = curcode.code('GBP');
console.log(gbp.symbol); // '£'

API Reference

code(code: string): CurrencyCodeRecord | undefined

Lookup currency by ISO 4217 code.

const eur = curcode.code('EUR');
console.log(eur.currency); // 'Euro'

symbol(symbol: string): CurrencyCodeRecord | undefined

Lookup currency by symbol. Returns the first matching currency.

const euro = curcode.symbol('€');
console.log(euro.code); // 'EUR'

country(country: string): CurrencyCodeRecord[]

Lookup currencies by country name (case insensitive). Returns an array as some countries use multiple currencies.

const currencies = curcode.country('switzerland');
// Returns currencies used in Switzerland

number(number: string | number): CurrencyCodeRecord | undefined

Lookup currency by ISO 4217 numeric code.

const usd = curcode.number('840');
// or
const usd = curcode.number(840);
console.log(usd.code); // 'USD'

codes(): string[]

Get all ISO 4217 currency codes.

const allCodes = curcode.codes();
console.log(allCodes); // ['AED', 'AFN', 'ALL', ...]

numbers(): string[]

Get all ISO 4217 numeric codes.

const allNumbers = curcode.numbers();
console.log(allNumbers); // ['784', '971', '008', ...]

countries(): string[]

Get all unique country names.

const allCountries = curcode.countries();
console.log(allCountries.length); // 260

data: CurrencyCodeRecord[]

Direct access to the raw currency data array.

const rawData = curcode.data;
console.log(rawData.length); // 179

symbols: Record<string, string>

Direct access to currency symbols mapped by code.

const symbols = curcode.symbols;
console.log(symbols.USD); // '$'
console.log(symbols.EUR); // '€'
console.log(symbols.GBP); // '£'

publishDate: string

ISO 4217 data publish date.

console.log(curcode.publishDate); // '2018-08-29'

TypeScript Types

CurrencyCodeRecord

interface CurrencyCodeRecord {
  code: string;        // ISO 4217 alpha code (e.g., 'USD')
  number: string;      // ISO 4217 numeric code (e.g., '840')
  digits: number;      // Decimal places (e.g., 2)
  currency: string;    // Currency name (e.g., 'US Dollar')
  symbol?: string;     // Currency symbol (e.g., '$')
  countries: string[]; // Countries using this currency
}

Examples

Format Currency Amount

const curcode = require('curcode');

function formatCurrency(amount, code) {
  const currency = curcode.code(code);
  if (!currency) return `${amount}`;
  
  const formatted = amount.toFixed(currency.digits);
  return `${currency.symbol || currency.code} ${formatted}`;
}

console.log(formatCurrency(1234.5, 'USD'));  // '$ 1234.50'
console.log(formatCurrency(1234.5, 'EUR'));  // '€ 1234.50'
console.log(formatCurrency(1234.5, 'JPY'));  // '¥ 1235' (0 digits)

List All Currencies for a Region

const curcode = require('curcode');

const europeanCountries = ['germany', 'france', 'italy', 'spain', 'poland'];

europeanCountries.forEach(country => {
  const currencies = curcode.country(country);
  console.log(`${country}: ${currencies.map(c => c.code).join(', ')}`);
});

Validate Currency Code

const curcode = require('curcode');

function isValidCurrency(code) {
  return curcode.code(code) !== undefined;
}

console.log(isValidCurrency('USD')); // true
console.log(isValidCurrency('XXX')); // true (valid test code)
console.log(isValidCurrency('INVALID')); // false

Currency Converter Helper

import { code, CurrencyCodeRecord } from 'curcode';

interface ConversionRate {
  from: CurrencyCodeRecord;
  to: CurrencyCodeRecord;
  rate: number;
}

function convert(amount: number, fromCode: string, toCode: string, rate: number): string {
  const from = code(fromCode);
  const to = code(toCode);
  
  if (!from || !to) {
    throw new Error('Invalid currency code');
  }
  
  const converted = amount * rate;
  return `${from.symbol}${amount.toFixed(from.digits)} = ${to.symbol}${converted.toFixed(to.digits)}`;
}

console.log(convert(100, 'USD', 'EUR', 0.85));
// '$100.00 = €85.00'

Data Source

This package uses official ISO 4217 data from the International Organization for Standardization. The data includes:

• 179 active currency codes
• 260+ countries and territories
• Currency symbols from multiple sources
• Decimal place information
• Numeric codes

Last updated: 2018-08-29

Development

Running Tests

npm test
# or
yarn test
# or
pnpm test
# or
bun test

Updating ISO 4217 Data

To fetch and ingest the latest ISO 4217 XML data:

npm run iso
# or
pnpm run iso

This will:

1. Fetch the latest XML from the official ISO 4217 source
2. Parse and convert it to the internal format

Browser Support

While this package is designed for Node.js, it can be used in browsers with bundlers like:

• Webpack
• Rollup
• Vite
• esbuild
• Parcel

The package has zero runtime dependencies, making it lightweight for browser bundles.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © idimetrix

Related Packages

• currency-symbol-map - Map currency codes to symbols
• iso-4217 - Alternative ISO 4217 implementation

Links

• GitHub Repository
• npm Package
• ISO 4217 Standard
• Issue Tracker