money

Part of Alexantrite Software Library - a set of high-quality and performant JavaScript libraries for everyday use.

Provides a lightweight fixed-point type and helpers for financial calculations in JavaScript, now with optional currency tracking.

Money, a type that the library provides, represents a fixed-point decimal number. This type is designed to be used in financial calculations, where rounding errors are not acceptable.

The asljs-money named export money creates a new instance of Money from a number of minor units (e.g. cents) or another Money instance. It also provides functions to create a Money instance from a variety of sources:

• from a string formatted as -1,234.56, use money.parse(value) or money.fromString(value).
• from a number of cents (or pence), use money.fromMinor(value).
• from a floating-point number, truncating beyond 1/100, use money.fromNumber(value).
• from a number of major units (dollars), use money.fromMajor(value).

It holds values from -90071992547409.91 to 90071992547409.91.

A Money instance provides these operations:

• value - returns an integer representation of this Money instance.
• add(money1, money2, ...) - returns a new instance of Money with added amounts. Requires the same currency.
• distribute(recipients, unit) - divides the amount among recipients, proportionally to their shares. Operate in unit (default is minor).
• major() - returns a number of major units (dollars) as an integer JavaScript number, e.g. 1 for 1.23.
• minor() - returns a number of minor units (dollars) as an integer JavaScript number, e.g. 23 for 1.23.
• subtract(money1, money2, ...) - returns a new instance of Money with subtracted amounts. Requires the same currency.
• toNumber() - returns a floating-point number representation of the Money instance.
• toString() - returns string representation of the Money instance, e.g. -1,234.56.
• convert(rate, currency) - converts the amount to another currency using a positive finite exchange rate. Rounds by truncation to the nearest cent.

Constants, defined in the module:

• minor - indicates that computations are done in minor units (cents).
• major - indicates that computations are done in major units (dollars).
• zero - zero value.

In addition, money provides these utility functions:

• isMoney(value) - returns true if value is an instance of Money.

Usage

Import money (ESM):

import { money } from 'asljs-money';

Create a Money instance, distribute it among shareholders, and sum up the result:

const amount =
  money.fromString('1,204.20');

const dividends =
  amount.distribute([0.6, 0.2, 0.2]);

const total =
  dividends.reduce(
    (sum, item) =>
      sum.add(item),
    money.zero);

console.log(total.toString());

Currency-aware operations:

const usd = money.fromMinor(10000, 'USD');
const eur = usd.convert(0.9, 'EUR');
console.log(usd.toString()); // "100.00 USD"
console.log(eur.toString()); // "90.00 EUR"