country-currency-utils

KO | EN

gitlite — search

#python #hacktoberfest #golang #android #rust #docker #macos #java #windows #awesome #cli #vue #mcp #openai

country-currency-utils

(★ 10)

A package with useful data and functions to manage countries, currencies, processing monetary amounts and dial codes

country-currency-utils 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# country-currency-utils

[![npm version](https://img.shields.io/npm/v/country-currency-utils)](https://www.npmjs.com/package/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:

```bash
npm install country-currency-utils
```

or

```bash
yarn add country-currency-utils
```

## Country utilities

### Type references

```typescript
type TCountryDetails = {
  name: string; // Country name
  dialCode: string; // Country dial code
  currencyCode: string; // Country currency code
  flagEmoji: string; // Country flag emoji
};

type TCountryData = TCountryDetails & {
  countryCode: string; // ISO 3166 country code
};
```

### Available functions

#### `getAllCountryDetails`

_Reference_

```typescript
getAllCountryDetails(): Record<string, TCountryDetails>
```

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

#### `getAllCountryData`

_Reference_

```typescript
getAllCountryData(): TCountryData[]
```

Return all country data in array format.

#### `getCountryData`

_Reference_

```typescript
getCountryData(countryCode: string): TCountryData | undefined
```

Return country data given a country code.

_Example:_

```typescript
const countryData = getCountryData("BD");
```

#### `getCountriesData`

_Reference_

```typescript
getCountriesData(countryCodes: string[]): (TCountryData | undefined)[]
```

Return multiple countries data given array of country codes.

_Example:_

```typescript
const countriesData = getCountriesData(["US", "BD"]);
```

---

## Currencies utilities

### Type references

```typescript
type TCurrencyDetails = {
  name: string; // Currency name
  demonym: string; // Currency demonym
  majorSingle: string; // Major unit name in singular form (e.g. Dollar)
  majorPlural: string; // Major unit name in plural form (e.g. Dollars)
  symbol: string; // Currency symbol (e.g. $, CA$)
  symbolNative: string; // Currency symbol in native language (e.g. $)
  symbolPreferred: string; // preferred currency symbol, used for display
  minorSingle: string; // Minor unit name in singular form (e.g. Cent)
  minorPlural: string; // Minor unit name in plural form (e.g. Cents)
  decimals: number; // Number of decimal places, used for standard display
  decimalsCompact: number; // Number of decimal places, used for compact display
  digitGrouping: 2 | 3; // Digit grouping for formatting (e.g. 2 for 1,00,000, 3 for 100,000)
};

type TCurrencyData = TCurrencyDetails & {
  currencyCode: string; // ISO 4217 currency codes
};
```

### Available functions

#### `getAllCurrencyDetails`

_Reference_

```typescript
getAllCurrencyDetails(): Record<string, TCurrencyDetails>
```

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

#### `getAllCurrencyData`

_Reference_

```typescript
getAllCurrencyData(): TCurrencyData[]
```

Return all currency data in array format.

#### `getCurrencyData`

_Reference_

```typescript
getCurrencyData(currencyCode: string): TCurrencyData | undefined
```

Returns Currency data given a currency code

_Example:_

```typescript
const currencyData = getCurrencyData("BDT");
```

#### `getCurrenciesData`

_Reference_

```typescript
getCurrenciesData(currencyCodes: string[]): (TCurrencyData | undefined)[]
```

Returns Currencies data given an array of currency codes

_Example:_

```typescript
const currenciesData = 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`

```typescript
getFixedAmount(amount: number, decimals: number, roundingMethod?: "ceil" | "round"): number
```

The default behavior is to `round` the amount to the specified decimal places. Use the `roundingMethod` param to switch to `"ceil"` (e.g. when you want to maximize the monetory amount) or explicitly request `"round"`.

_Example:_

```typescript
const fixedAmount = getFixedAmount(123.4517, 2); // 123.45
const fixedAmount = getFixedAmount(123.4517, 2, "ceil"); // 123.46
```

#### `getFixedAmountOnCurrency`

```typescript
type TRoundingMethod = "ceil" | "round";
type TDecimalsOption = "standard" | "compact";

type TCurrencyRoundOptions = {
  roundingMethod?: TRoundingMethod; // Default behavior is Math.round, "ceil" uses Math.ceil
  roundingDecimals?: TDecimalsOption; // Default behavior is to use standard decimals, isDecimalsCompact uses compact decimals
};

getFixedAmountOnCurrency(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:_

```typescript
const USDCurrencyData = getCurrencyData("USD");
const BDTCurrencyData = getCurrencyData("BDT");

const roundedAmount = getFixedAmountOnCurrency(123.4567, USDCurrencyData); // 123.46
const roundedAmount = getFixedAmountOnCurrency(123.45, BDTCurrencyData); // 123.45
const roundedAmount = getFixedAmountOnCurrency(123.45, BDTCurrencyData, {
  roundingDecimals: "compact",
}); // 123
const roundedAmount = getFixedAmountOnCurrency(123.45, BDTCurrencyData, {
  roundingDecimals: "compact",
  roundingMethod: "ceil",
}); // 124
```

#### `getFixedAmountOnCurrencyCode`

```typescript
getFixedAmountOnCurrencyCode(amount: number, currencyCode: string, options?: TCurrencyRoundOptions): number
```

Convenience wrapper around `getFixedAmountOnCurrency` that accepts a currency code string instead of a currency data object.

_Example:_

```typescript
const roundedAmount = getFixedAmountOnCurrencyCode(123.4567, "USD"); // 123.46
const roundedAmount = getFixedAmountOnCurrencyCode(123.45, "BDT", {
  roundingDecimals: "compact",
}); // 123
const roundedAmount = getFixedAmountOnCurrencyCode(123.45, "BDT", {
  roundingDecimals: "compact",
  roundingMethod: "ceil",
}); // 124
```

#### `getFormattedAmount`

```typescript
getFormattedAmount(amount: number, digitGrouping: 2 | 3, 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:_

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

#### `getFormattedAmountOnCurrency`

```typescript
export type TCurrencyFormatOptions = TCurrencyRoundOptions & {
  avoidRound?: boolean; // avoids rounding amount
  previewDecimals?: TDecimalsOption; // default behavior is decimals compact
};

getFormattedAmountOnCurrency(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 rounds 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:_

```typescript
const USDCurrencyData = getCurrencyData("USD");
const BDTCurrencyData = getCurrencyData("BDT");

const formattedAmount = getFormattedAmountOnCurrency(123456.7, USDCurrencyData); // "123,456.70"
const formattedAmount = getFormattedAmountOnCurrency(
  123456.711,
  USDCurrencyData,
  {
    avoidRound: true,
  }
); // "123,456.71" (rounding skipped, but formatting still truncates to decimalsCompact)

const formattedAmount = getFormattedAmountOnCurrency(123456.7, BDTCurrencyData); // "1,23,456.7"
const formattedAmount = getFormattedAmountOnCurrency(
  123456.7,
  BDTCurrencyData,
  {
    roundingDecimals: "compact",
  }
); // "1,23,457"
const formattedAmount = getFormattedAmountOnCurrency(1, BDTCurrencyData); // "1"
const formattedAmount = getFormattedAmountOnCurrency(1.2, BDTCurrencyData); // "1.2"
const formattedAmount = getFormattedAmountOnCurrency(1.2, BDTCurrencyData, {
  previewDecimals: "standard",
}); // "1.20"
```

#### `getFormattedAmountOnCurrencyCode`

```typescript
getFormattedAmountOnCurrencyCode(amount: number, currencyCode: string, options?: TCurrencyFormatOptions): string
```

Convenience wrapper around `getFormattedAmountOnCurrency` that accepts a currency code string instead of a currency data object.

_Example:_

```typescript
const formattedAmount = getFormattedAmountOnCurrencyCode(123456.7, "USD"); // "123,456.70"
const formattedAmount = getFormattedAmountOnCurrencyCode(123456.7, "BDT"); // "1,23,456.7"
const formattedAmount = getFormattedAmountOnCurrencyCode(123456.7, "BDT", {
  roundingDecimals: "compact",
}); // "1,23,457"
```

#### `getDisplayAmountOnCurrency`

```typescript
type TCurrencyDisplayOptions = TCurrencyFormatOptions & {
  avoidFormat?: boolean; // Default: format amount
  isSymbolStandard?: boolean; // Default: preferredSymbol, isSymbolStandard: standard symbol
  isSymbolNative?: boolean; // Default: preferredSymbol, isSymbolNative: symbolNative
  separator?: string; // Default: space between symbol and amount, can be changed
};

getDisplayAmountOnCurrency(amount: number, currencyData?: TCurrencyData, options?: TCurrencyDisplayOptions): 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:_

```typescript
const USDCurrencyData = getCurrencyData("USD");
const BDTCurrencyData = getCurrencyData("BDT");

#### `getDisplayAmountOnCurrencyCode`

```typescript
getDisplayAmountOnCurrencyCode(amount: number, currencyCode: string, options?: TCurrencyDisplayOptions): string
```

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

_Example:_

```typescript
const displayAmount = getDisplayAmountOnCurrencyCode(123.4567, "USD"); // "$ 123.46"
const displayAmount = getDisplayAmountOnCurrencyCode(123456.7, "USD"); // "$ 123,456.70"
const displayAmount = getDisplayAmountOnCurrencyCode(123456.7, "USD", {
  avoidFormat: true,
}); // "$ 123456.7"
const displayAmount = getDisplayAmountOnCurrencyCode(123456.7, "USD", {
  separator: "",
}); // "$123,456.70"
const displayAmount = getDisplayAmountOnCurrencyCode(123.4567, "BDT"); // "Tk 123.46"
const displayAmount = getDisplayAmountOnCurrencyCode(123, "BDT", {
  isSymbolStandard: true,
}); // "৳ 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](https://headless.ltd)**

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.

country-currency-utils

country-currency-utils 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

country-currency-utils

country-currency-utils 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README