country-currency-utils

country-currency-utils is a comprehensive npm package providing country and currency data for all countries. It offers an extensive set of utilities for handling monetary amounts efficiently, including formatting, rounding, and accessing currency symbols. This package ensures accurate monetary representation and simplifies working with detailed country and currency information.

Installation

To install the package, run:

1npm install country-currency-utils

or

1yarn add country-currency-utils

Countries and Currencies data

The package hosts country and currency data via CDN URLs:

COUNTRIES_DETAILS_URL, CURRENCIES_DETAILS_URL

• Countries: Countries JSON
• Currencies: Currencies JSON

1# Countries
2https://cdn.jsdelivr.net/gh/headlesstech/country-currency-utils@main/data/countries.json
3
4# Currencies
5https://cdn.jsdelivr.net/gh/headlesstech/country-currency-utils@main/data/currencies.json

---

Country utilities

Type references

1type TCountryDetails = {
2  name: string; // Country name
3  dialCode: string; // Country dial code
4  currencyCode: string; // Country currency code
5  flagEmoji: string; // Country flag emoji
6};
7
8type TCountryData = TCountryDetails & {
9  countryCode: string; // ISO 3166 country code
10};

Available functions

getAllCountryDetails

Reference

1getAllCountryDetails(): Promise<Record<string, TCountryDetails>>

Return all country details in Object format. The key in object is Country Code (ISO 3166).

getAllCountryData

Reference

1getAllCountryData(): Promise<TCountryData[]>

Return all country data in array format.

getCountryData

Reference

1getCountryData(countryCode: string): Promise<TCountryData | undefined>

Return country data given a country code.

Example:

1const countryData = await getCountryData("BD");

getCountriesData

Reference

1getCountriesData(countryCodes: string[]): Promise<(TCountryData | undefined)[]>

Return multiple countries data given array of country codes.

Example:

1const countriesData = await getCountriesData(["US", "BD"]);

---

Currencies utilities

Type references

1type TCurrencyDetails = {
2  name: string; // Currency name
3  demonym: string; // Currency demonym
4  majorSingle: string; // Major unit name in singular form (e.g. Dollar)
5  majorPlural: string; // Major unit name in plural form (e.g. Dollars)
6  symbol: string; // Currency symbol (e.g. $, CA$)
7  symbolNative: string; // Currency symbol in native language (e.g. $)
8  symbolPreferred: string; // preferred currency symbol, used for display
9  minorSingle: string; // Minor unit name in singular form (e.g. Cent)
10  minorPlural: string; // Minor unit name in plural form (e.g. Cents)
11  decimals: number; // Number of decimal places, used for standard display
12  decimalsCompact: number; // Number of decimal places, used for compact display
13  digitGrouping: 2 | 3; // Digit grouping for formatting (e.g. 2 for 1,00,000, 3 for 100,000)
14};
15
16type TCurrencyData = TCurrencyDetails & {
17  currencyCode: string; // ISO 4217 currency codes
18};

Available functions

getAllCurrencyDetails

Reference

1getAllCurrencyDetails(): Promise<Record<string, TCurrencyDetails>>

Return all currency details in Object format. The key in object is Currency Code (ISO 4217).

getAllCurrencyData

Reference

1getAllCurrencyData(): Promise<TCurrencyData[]>

Return all currency data in array format.

getCurrencyData

Reference

1getCurrencyData(currencyCode: string): Promise<TCurrencyData | undefined>

Returns Currency data given a currency code

Example:

1const currencyData = await getCurrencyData("BDT");

getCurrenciesData

Reference

1getCurrenciesData(currencyCodes: string[]): Promise<(TCurrencyData | undefined)[]>

Returns Currencies data given am array of currency codes

Example:

1const currenciesData = await getCurrenciesData(["USD", "BDT"]);

---

Amount Formatting Utilities

There are many functions and utilities that may be required when handling monetory amounts. Here are a list of functions:

getFixedAmount

1getFixedAmount(amount: number, decimals: number, isRoundMiddle?: boolean): number

The default behavior is to ceil the amount to the specified decimal places. This is because we want to maximize the monetory amount. However, use the roundingMethod param to use actual "ceil" | "round" method to round the amount.

Example:

1const fixedAmount = getFixedAmount(123.4517, 2); // 123.46
2const fixedAmount = getFixedAmount(123.4517, 2, "round"); // 123.45

getFixedAmountOnCurrency

1type TRoundingMethod = "ceil" | "round";
2type TDecimalsOption = "standard" | "compact";
3
4type TCurrencyRoundOptions = {
5  roundingMethod?: TRoundingMethod; // Default behavior is Math.ceil
6  roundingDecimals?: TDecimalsOption; // Default behavior is to use standard decimals, isDecimalsCompact uses compact decimals
7};
8
9getFixedAmountOnCurrency(amount: number, currencyData?: TCurrencyData, options?: TCurrencyRoundOptions): number

This uses the getFixedAmount function internally to ceil/round on details of a currency code. Default behavior is to use the decimals (standard) decimal places, but this can be overridden using decimalsCompact. decimalsCompact is usually a more compact number of decimal places which may be used in previews and in UI.

Example:

1const USDCurrencyData = await getCurrencyData("USD");
2const BDTCurrencyData = await getCurrencyData("BDT");
3
4const roundedAmount = getFixedAmountOnCurrency(123.4567, USDCurrencyData); // 123.46
5const roundedAmount = getFixedAmountOnCurrency(123.45, BDTCurrencyData); // 123.45
6const roundedAmount = getFixedAmountOnCurrency(123.45, BDTCurrencyData, {
7  roundingDecimals: "compact",
8}); // 124

Note: You will notice that we are having to run a promise to get CurrencyData and then round/format/display monetory amount. When handling many countries and currencies, it is better to fetch data and then use it, rather that keeping a list of countries and currencies as data or as constant in code base. This keeps codebase light. However if you are handling single currency or just a few currencies. You can keep a list of currencies data and use it directly in function in stead of fetching through an async call.

getFormattedAmount

1getFormattedAmount(amount: number, digitGrouping: number, fixedDecimals?: number): string

Returns a string with comma separated amount. digitGrouping maybe 2 or 3. fixedDecimals pads the decimal places with 0s or truncates (does not round) extra decimal places.

Example:

1const formattedAmount = getFormattedAmount(123456.7, 2); // "1,23,456.7"
2const formattedAmount = getFormattedAmount(123456.7, 3); // "123,456.7"
3const formattedAmount = getFormattedAmount(123456.7, 2, 2); // "1,23,456.70"
4const formattedAmount = getFormattedAmount(123456.789, 3, 2); // "123,456.78"

getFormattedAmountOnCurrency

1export type TCurrencyFormatOptions = TCurrencyRoundOptions & {
2  avoidRound?: boolean; // avoids rounding amount
3  previewDecimals?: TDecimalsOption; // default behavior is decimals compact
4};
5
6getFormattedAmountOnCurrency(amount: number, currencyData?: TCurrencyData, options?: TCurrencyFormatOptions): string

Formats the given amount according to the currency's standard decimal places and digit grouping and returns it as a string. The function by default ceils the number and formats on the currency definitions. The options inherits from rounding options. avoidRound avoids rounding the amount. previewDecimals tells how many decimal places should at least show up.

Example:

1const USDCurrencyData = await getCurrencyData("USD");
2const BDTCurrencyData = await getCurrencyData("BDT");
3
4const formattedAmount = getFormattedAmountOnCurrency(123456.7, USDCurrencyData); // "123,456.70"
5const formattedAmount = getFormattedAmountOnCurrency(
6  123456.711,
7  USDCurrencyData,
8  {
9    avoidRound: true,
10  }
11); // "123,456.711"
12
13const formattedAmount = getFormattedAmountOnCurrency(123456.7, BDTCurrencyData); // "1,23,456.7"
14const formattedAmount = getFormattedAmountOnCurrency(
15  123456.7,
16  BDTCurrencyData,
17  {
18    roundingDecimals: "compact",
19  }
20); // "1,23,457"
21const formattedAmount = getFormattedAmountOnCurrency(1, BDTCurrencyData); // "1"
22const formattedAmount = getFormattedAmountOnCurrency(1.2, BDTCurrencyData); // "1.2"
23const formattedAmount = getFormattedAmountOnCurrency(1.2, BDTCurrencyData, {
24  previewDecimals: "standard",
25}); // "1.20"

getDisplayAmountOnCurrency

1type TCurrencyDisplayOptions = TCurrencyFormatOptions & {
2  avoidFormat?: boolean; // Default: format amount
3  isSymbolStandard?: boolean; // Default: preferredSymbol, isSymbolStandard: standard symbol
4  isSymbolNative?: boolean; // Default: preferredSymbol, isSymbolNative: symbolNative
5  separator?: string; // Default: space between symbol and amount, can be changed
6};
7
8getDisplayAmountOnCurrency(amount: number, currencyData?: TCurrencyData, options?: TCurrencyFormatOptions): string

Returns a displayable amount with currency symbol, rounded by default and uses proper digit grouping on currency. avoidFormat avoid formatting. isSymbolStandard and isSymbolNative defined the symbol to use, default is to use preferredSymbol. separator can be used define separator string between symbol and amount. The function inherits options for rounding and formatting

Example:

1const USDCurrencyData = await getCurrencyData("USD");
2const BDTCurrencyData = await getCurrencyData("BDT");
3
4const displayAmount = getDisplayAmountOnCurrency(123.4567, USDCurrencyData); // "$ 123.46"
5const displayAmount = getDisplayAmountOnCurrency(123456.7, USDCurrencyData); // "$ 123,456.70"
6const displayAmount = getDisplayAmountOnCurrency(123456.7, USDCurrencyData, {
7  avoidFormat: true,
8}); // "$ 123456.7"
9const displayAmount = getDisplayAmountOnCurrency(123456.7, USDCurrencyData, {
10  separator: "",
11}); // "$123,456.70"
12const displayAmount = getDisplayAmountOnCurrency(123.4567, BDTCurrencyData); // "Tk 123.46"
13const displayAmount = getDisplayAmountOnCurrency(123, BDTCurrencyData, {
14  isSymbolStandard: true,
15}); // "৳ 123"

getDisplayAmountOnCurrencyCode

1getDisplayAmountOnCurrencyCode(amount: number, currencyCode: string, options?: TCurrencyFormatOptions): Promise<string>

Returns a displayable amount with currency symbol, using the getDisplayAmountOnCurrency function and looks up currency details on currency code

Example:

1const displayAmount = await getDisplayAmountOnCurrencyCode(123.4567, "USD"); // "$ 123.46"
2const displayAmount = await getDisplayAmountOnCurrencyCode(123456.7, "USD"); // "$ 123,456.70"
3const displayAmount = await getDisplayAmountOnCurrencyCode(123456.7, "USD", {
4  avoidFormat: true,
5}); // "$ 123456.7"
6const displayAmount = await getDisplayAmountOnCurrencyCode(123456.7, "USD", {
7  separator: "",
8}); // "$123,456.70"
9const displayAmount = await getDisplayAmountOnCurrencyCode(123.4567, "BDT"); // "Tk 123.46"
10const displayAmount = await getDisplayAmountOnCurrencyCode(123, "BDT", {
11  isSymbolStandard: true,
12}); // "৳ 123"

Testing

All data and functions have been tested using Jest.

License

This project is licensed under the MIT License

Developed By

Headless Technologies Limited

A software, hardware, and AI company building solutions on tech.

Support

If you find this package useful, please consider starring the repository on GitHub to show your support!

Contribution

Developers are welcome to create issues and pull requests.