frolovdev/easymoney

fowler-money-pattern money money-library formatter currency

Library for operating with monetary values in JavaScript and Typescript

Modular. It's written with modular and composable architecture so that your final bundle will be as small as possible.
Statically typed. First-class support of Typescript.
Immutable: It has a chainable API, but without mutations.
Supports big numbers. Support values greater than MAX_SAFE_INTEGER with Bignumber.js
Crypto currencies. It has support for custom currencies and formatting them.
Big int support. It has a package for supporting new standard of big int out of the box in a separate pacakge.
Custom calculators. You can override functionality with your own custom calculator.

import { createMoney } from '@easymoney/money';

const money1 = createMoney({ amount: 100, currency: 'USD' });

const money2 = createMoney({ amount: 106, currency: 'USD' });

const money3 = money1.add(money2).getAmount();
// => 206

import { createMoneyIntlFormatter } from "@easymoney/formatter"
import { createMoney } from '@easymoney/money';

const money = createMoney({ amount: 5, currency: "USD" });

const formatted = createMoneyIntlFormatter().format(money);
// => "$0.05"

import { createMoneyCryptoFormatter } from "@easymoney/crypto-formatter"
import { createMoney } from '@easymoney/money';
import { cryptoCurrenciesMap } from "@easymoney/currencies"

const money = createMoney({ amount: 5, currency: "LTC" });

const formatted = createMoneyCryptoFormatter().format(money);
// => "0.00000005LTC"

const currencies = [{ minorUnit: 2, code: "XBT" }, { minorUnit: 5, code: "DXBT" }];

const list = createCurrencyList(currencies);

list.getCurrencies();
/**
 * => {
  XBT: { minorUnit: 2, code: "XBT" },
  DXBT: { minorUnit: 5, code: "DXBT" },
};
 */

Requirements

For typescript users TS 3.7+
If you use @easymoney/bigint-money you need Node Version or Browser Version that supports this proposal

Quick start

npm i @easymoney/money

or

yarn add @easymoney/money

Why

JavaScript developers attempt to use just numbers or strings (i.g. https://github.com/MikeMcl/bignumber.js) to operate with monetary values. I don't think this is the right way, and strings or numbers are not well suited for financial applications for these main reasons:

tricky rounding (described here)
conversion
allocating (dividing money between parties)
formatting
working with cents (minor units of currency)

The solution to these problems is the Martin Fowler's Money Type from "Patterns of Enterprise Application Architecture".

It's an old pattern that is implemented in many other languages e.g.:

Java Moneta
PHP moneyphp
Go go-money

Comparison with dinero.js

	easymoney	Dinero.js
Typescript	✅	❌ (only @types/Dinero)
Modular	functionality is divided by domains, which allows the library to be divided into separate modules as efficiently as possible	written as a monolith, one big object with a bunch of functions, no way to divide it into packages by design
Custom currencies support	✅	❌ (only ISO currencies)
Custom calculators support	✅	❌
Monetary values greater than MAX_SAFE_INTEGER	✅	❌
Bigint support	✅	❌