Check Digit Currency Library

Copyright © 2021–2025 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 14+ includes full ICU)
- uses built-in JS engine Intl implementation, no dependencies

Installing

``shell
npm install @checkdigit/currency
`

then:

`ts
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

`ts
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

$3

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

$3

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

$3

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

$3

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

Usage examples

$3

`ts
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',
);
// ১২৩৪৫৬
`

$3

`ts
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' }
`

$3

`ts
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');
// $
`

$3

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

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

$3

`ts
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
// }
`

$3

`ts
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
// }
`

$3

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

$3

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

License

MIT