Currency

The currency is one of the three pieces of domain data necessary to create a Dinero object.

A Dinero currency is composed of:

• A unique code.
• A base, or radix.
• An exponent.

Copy linkCurrency code

The currency code is a unique identifier for the currency. By convention, they're usually a three-letter or number. For example, in the case of national ISO 4217 currencies, the first two letters of the code are the two letters of the ISO 3166-1 alpha-2 country code, and the third is usually the initial of the currency itself.

// United States dollar
const USD = {
  code: 'USD',
  // ...
};

When they don't refer to a specific country (e.g., euro) or aren't a traditional currency (e.g., cryptocurrencies), the code can vary into a less standard but more mnemonic scheme. Ultimately, the code is your choice and needs to make sense in your application. The only requirement is for it to be unique.

Copy linkCurrency base

The currency base (or radix) is the number of unique digits used to represent a currency's minor unit. Most currencies in circulation are decimal, meaning their base is 10.

const USD = {
  code: 'USD',
  base: 10,
  // ...
};

There are still non-decimal currencies in circulation, such as the Mauritanian ouguiya and the Malagasy ariary.

// Mauritanian ouguiya
const MRU = {
  code: 'MRU',
  base: 5,
  // ...
};

Some currencies have multiple subdivisions. For example, before decimalization, the British pound sterling was divided into 20 shillings, and each shilling into 12 pence. You also have examples in fiction, like Harry Potter, where one Galleon is divided into 17 Sickles, and each Sickle into 29 Knuts.

To represent these currencies, you can specify each subdivision with an array.

// Pre-decimal Great Britain pound sterling
const GBP = {
  code: 'GBP',
  base: [20, 12],
  exponent: 1,
};

// Great Britain wizarding currency (Harry Potter universe)
const GBW = {
  code: 'GBW',
  base: [17, 29],
  exponent: 1,
};

Copy linkCurrency exponent

The currency exponent expresses the decimal relationship between the currency and its minor unit. For example, there are 100 cents in a US dollar, being 10 to the power of 2, so the exponent for the US dollar is 2.

const USD = {
  code: 'USD',
  base: 10,
  exponent: 2,
};

An easier way to think about it is as the number of digits after the decimal separator.

When a currency doesn't have minor currency units (e.g., the Japanese yen), the exponent should be 0. In this case, you can express the amount in major currency units.

// Japanese yen
const JPY = {
  code: 'JPY',
  base: 10,
  exponent: 0,
};

When you pass a scale to a Dinero object, it overrides the exponent. This has an impact on how you should specify the amount.

Copy linkUsing built-in currencies

Dinero.js provides ISO 4217 currency objects out of the box via the @dinero.js/currencies package.

Once you've installed Dinero.js currencies, you can use them in your project.

import { dinero } from 'dinero.js';
import { USD, EUR } from '@dinero.js/currencies';

const d1 = dinero({ amount: 1000, currency: USD });
const d2 = dinero({ amount: 1000, currency: EUR });

Currencies fluctuate, meaning their code and exponent can change, there can be new currencies, and existing currencies can disappear. ISO 4217 currencies account for these changes with amendments, maintained by the Secretariat of the Maintenance Agency.

Dinero.js tracks those amendments and updates currencies accordingly. Such changes are, by definition, breaking. To preserve fixed versioning, the library's entry point doesn't export updated currencies. In other words, if you import currencies from the path @dinero.js/currencies, they won't change.

To access always up to date currencies, you can import them from the latest submodule.

// This imports the latest version of the currency, which might be different
// from the last time you used it and break your application. Use with caution.
import { USD } from '@dinero.js/currencies/latest';

const d = dinero({ amount: 1000, currency: USD });

To pin a currency to a specific amendment, you can import it from its submodule. Amendments follow the numbering system of the maintenance agency.

import { USD } from '@dinero.js/currencies/168';

const d = dinero({ amount: 1000, currency: USD });

Copy linkCreating custom currencies

You can build your own currency object if it isn't available in @dinero.js/currencies.

const FRF = {
  code: 'FRF',
  base: 10,
  exponent: 2,
};

If you're a TypeScript user, you can implement the Currency type. It takes a generic parameter TAmount which represents the type you're using for numeric values (number by default).

import { Currency } from 'dinero.js';

const FRF: Currency<number> = {
  code: 'FRF',
  base: 10,
  exponent: 2,
};

If you want to use a different amount type, you'll need to pass a custom Calculator to Dinero.