Check Digit Currency Library

Copyright © 2021–2026 Check Digit, LLC

The Check Digit currency library is the officially sanctioned method for Check Digit services to deal with currency types, formatting and country/currency relationships at a particular date/time. Features:

• various currency and country lookup functions at a particular date/time starting 2018 and beyond, anything earlier will throw an error.
• TypeScript types for Amount, Money, ISO 3166 country codes (numeric, alpha2, alpha3), and ISO 4217 currency codes (name, alphabetic, numeric)
• currency formatting of Check Digit-standard Money objects, with a variety of options
• currency parsing of strings into Check Digit-standard Money objects
• tests to ensure compliance with number-based Intl.NumberFormat currency implementation
• tests to ensure correctness of underlying JS engine Intl implementation, with respect to currency
• multi-locale (all modern browsers and Node 24+ include full ICU)
• uses built-in JS engine Intl implementation, no dependencies

Installing

npm install @checkdigit/currency

then:

import * as currency from '@checkdigit/currency';

Types and interfaces

The four core types in the currency library are

• Amount, which is an integer either in bigint or string form (or -0).
• Money, which is an Amount combined with currency of type CurrencyAlphabeticCode (e.g. 'USD')
• Country, which is an object containing a country's ISO 3166 information and currencies
• Currency, which is an object containing a currency's ISO 4217 information

There are defined literal types for country and currency codes:

• CurrencyAlphabeticCode
• CurrencyNumericCode
• CurrencyName
• CountryAlpha2
• CountryAlpha3
• CountryNumeric

export interface Money {
  amount: string; // integer amount in minor units, e.g. '12345' for $123.45
  currency: CurrencyAlphabeticCode;
}

export interface Country {
  // ISO 3166 country display name, alpha2/3 and numeric codes
  name: string;
  alpha2: CountryAlpha2; // 'US' | 'NZ' ...
  alpha3: CountryAlpha3; // 'USA' | 'NZL' ...
  numeric: CountryNumeric; // '840' | '554' ...

  // ISO 4217 currencies
  currencyCodes: CurrencyAlphabeticCode[];
}

export interface Currency {
  name: CurrencyName; // 'US Dollar' | 'New Zealand Dollar' ...
  alphabeticCode: CurrencyAlphabeticCode; // 'USD' | 'NZD' ...
  numericCode: CurrencyNumericCode; // '840' | '554' ...
  minorUnits?: number;
  isFund?: true;
}

Functions

Formatting

• format({ amount, currency }: Money, options?: CurrencyFormatOptions, locales?: string | string[]): string

Parsing

• parse(money: string, currency: CurrencyAlphabeticCode, locales?: string | string[]) => Money;

Currencies

• allCurrencies(): Currency[]
• findCurrency(search: string): Currency
• getCurrency(code: CurrencyAlphabeticCode | CurrencyNumericCode): Currency
• getMinorUnitDigits(currency: CurrencyAlphabeticCode)
• getSymbol(currency: CurrencyAlphabeticCode, locales?: string | string[]): string

Countries

• allCountries(): Country[]
• getCountry(code: CountryAlpha2 | CountryAlpha3 | CountryNumeric): Country
• getCountriesForCurrency(code: CurrencyAlphabeticCode): CountryAlpha3[]

Usage examples

format

currency('2023-11-02T15:35:47.191Z').format({
  amount: '123456789012345678901234567890',
  currency: 'USD',
});
// $1,234,567,890,123,456,789,012,345,678.90

currency('2023-11-02T15:35:47.191Z').format({
  amount: '123456',
  currency: 'USD',
});
// $1234.56

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456', currency: 'USD' },
  {
    useGrouping: false,
    useCurrency: false,
  },
);
// 1234.56

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456', currency: 'USD' },
  {
    useGrouping: false,
    useCurrency: false,
    useDecimal: false,
  },
);
// 123456

currency('2023-11-02T15:35:47.191Z').format({ amount: '-0', currency: 'USD' });
// -$0.00

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456789', currency: 'USD' },
  {
    currencyDisplay: 'code',
  },
  'de-DE',
);
// 1.234.567,89 USD

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456', currency: 'USD' },
  {
    useDecimal: false,
    useGrouping: false,
    useCurrency: false,
  },
  'as-IN',
);
// ১২৩৪৫৬

parse

currency('2023-11-02T15:35:47.191Z').parse('.1', 'USD');
// { amount: '10', currency: 'USD' }

currency('2023-11-02T15:35:47.191Z').parse('1', 'USD');
// { amount: '100', currency: 'USD' }

currency('2023-11-02T15:35:47.191Z').parse('$1.23', 'USD');
// { amount: '123', currency: 'USD' }

currency('2023-11-02T15:35:47.191Z').parse('123.456,78', 'EUR', 'de-DE');
// { amount: '12345678', currency: 'EUR' }

currency('2023-11-02T15:35:47.191Z').parse('10€', 'EUR');
// { amount: '1000', currency: 'EUR' }

currency('2023-11-02T15:35:47.191Z').parse('10', 'JPY');
// { amount: '10', currency: 'JPY' }

getSymbol

currency('2023-11-02T15:35:47.191Z').getSymbol('USD');
// $

currency('2023-11-02T15:35:47.191Z').getSymbol('NZD');
// NZ$

currency('2023-11-02T15:35:47.191Z').getSymbol('NZD', 'en-NZ');
// $

getMinorUnitDigits

currency('2023-11-02T15:35:47.191Z').getMinorUnitDigits('USD');
// 2

currency('2023-11-02T15:35:47.191Z').getMinorUnitDigits('JPY');
// 0

findCurrency

currency('2023-11-02T15:35:47.191Z').findCurrency('us dollar');
// {
//   name: 'US Dollar',
//   alphabeticCode: 'USD',
//   numericCode: '840',
//   minorUnits: 2
// }

currency('2023-11-02T15:35:47.191Z').findCurrency(554);
// {
//   name: 'New Zealand Dollar',
//   alphabeticCode: 'NZD',
//   numericCode: '554',
//   minorUnits: 2
// }

getCurrency

currency('2023-11-02T15:35:47.191Z').getCurrency('840');
// {
//   name: 'US Dollar',
//   alphabeticCode: 'USD',
//   numericCode: '840',
//   minorUnits: 2
// }

currency('2023-11-02T15:35:47.191Z').getCurrency('NZD');
// {
//   name: 'New Zealand Dollar',
//   alphabeticCode: 'NZD',
//   numericCode: '554',
//   minorUnits: 2
// }

getCountry

currency('2023-11-02T15:35:47.191Z').getCountry('USA');
// {
//   name: 'US',
//   alpha2: 'US',
//   alpha3: 'USA',
//   numeric: '840',
//   currencyCodes: [ 'USD' ]
// }

getCountriesForCurrency

currency('2023-11-02T15:35:47.191Z').getCountriesForCurrency('NZD');
// [ 'COK', 'NIU', 'NZL', 'PCN', 'TKL' ]

License

MIT