frolovdev / Easymoney

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.

📖 Read more

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

Further reading

How to Operate with Monetary Values in JavaScript

Main features of easymoney

Why rounding is more important than you think

Comparison with dinero.js

Packages

Package	Version	Dependencies	Size
@easymoney/bigint-money
@easymoney/bignumber.js
@easymoney/currencies
@easymoney/money
@easymoney/formatter
@easymoney/crypto-formatter

CDN

• @easymoney/money
• @easymoney/bigint-money
• @easymoney/currencies
• @easymoney/bignumber.js
• @easymoney/formatter
• @easymoney/crypto-formatter

Comunity

• Spectrum
• Ask question on twitter

Learn more

API Reference

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Andrey Frolov ⚠️ 📖 💻

oneyan1 ⚠️ 📖 💻

Mikchail 📖

Roman Martynenko 📖

Artem676 📖

This project follows the all-contributors specification. Contributions of any kind welcome!