Skip to content

frolovdev/easymoney

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

easy money logo

codecov License: MIT

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.:

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

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 βœ… ❌

Packages

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

CDN

Comunity

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!