money-works

Work with money in multiple currencies and different locales. See the online demonstration.

The change log is automatically produced with the help of semantic-release.

Features

• Banker's rounding to the precision of the currency
• Locale specific formatting using the Internationalization API
• Precision decimal arithmetic using a big number package
• ISO-4217 currency codes
• Currency conversion
• Uses Martin Folwer's design pattern for Money
• Allocation of funds without loosing pennies (smallest denomination)
• Uses Andy Earnshaw's Intl when the environment's Intl package doesn't support the language.
• Non-latin numbering systems
• Maintains a cache of locales for performance
• Supports the common cryptocurrencies XBT(BTC), ETH, XMR and XRP

Getting started

money-works is available for Node.js and most modern browsers. If you want to know if your currrent browser is compatible, run the online test suite or the online demonstration.

Install with npm

> npm install money-works --save

Usage

const Money = require('money-works');
const price = new Money(1000.6, 'JPY');

toString always returns the exact amount and currency

price.toString()                // '1000.6 JPY'

toLocaleString returns the localised version of the Money. Note that YEN is not displayed with decimal places.

price.toLocaleString('en-NZ')   // '¥1,001'
price.toLocaleString('fr-CA')   // '1 001 ¥'

allocate distributes the Money based on the ratio without loosing any pennies. It returns an Array of Money.

price.allocate([1, 1])          // '501 JPY' and '500 JPY'
price.allocate([70, 20, 10])    // '701 JPY', '200 JPY' and '100 JPY'

with ES6, me gets 70% and other only 30% of the price

let [me, other] = price.allocate([70, 30]);

The standard Math functions (plus, minus and times) are available and are chainable. plus and minus require Money of the same currency. Its always a good idea to round the result of a calculation, which uses banker's rounding to the precision of the currency.

let gst = 0.15,
    total = price               // '1151 YPN' = 1000.6 + 150.09
        .plus(price.times(gst))
        .round();

Comparision functions are eq, ne, lt, lte, gt, gte and require Money of the same currency. Testing the amount against zero is done with isZero, isNotZero, isPositive and isNegative.

if (total.isPositive()) {
    placeOrder();
}

Rounding

When required, Money is normally rounded to the precision of the currency using the banker's rounding algorithm. The precision (number of decimal places) can be optionally specified.

The round method can accept the number of decimal places.

new Money(123.57719, 'NZD').round();    // '123.58 NZD'
new Money(123.57719, 'NZD').round(4);   // '123.5772 NZD'

The allocate method also has an optional precision

const fund = new Money(1000.6, 'JPY');
fund.allocate([1, 1])                   // '501 JPY' and '500 JPY'
fund.allocate([1, 1], 4)                // '501.3 JPY' and '500.3 JPY'

And toLocaleString

 let money = new Money(123.57719, 'NZD');
 let options = { maximumFractionDigits: 4 };
 money.toLocaleString('fr-FR', options);    // '123,5772 $NZ'
 

Localisation

toLocaleString([locales], [options]) gets the local representation of the Money in the locale; see MDN for the details. The options.style and options.currency are always set to 'currency' and Money.currency, respectively.

price.toLocaleString('fr-CA')       // '1 001 ¥'
let opt = { currencyDisplay: 'code' }
price.toLocaleString('fr-CA', opt)  // '1 001 JPY'

A default locale and localeOptions is set with Money.defaultLocale and Money.defaultLocaleOptions. Both defaults are a function that return the default locale (string or array) and default locale options (object), respectively.

Money.defaultLocale = () => window.lang;

Currency conversion

to(currency) returns a Promise to convert the Money into another currency. It uses Money.forexService to determine the exchange rate. If the exchange rate cannot be determined, then the Promise is rejected. The conversion does not round the result.

The default forexService uses the exchange rates from the free currency converter.

new Money('100 NZD')
    .to('JPY')
    .then(console.log)      // 7758.9 JPY

Browser usage

Include the package from your project

<script src="./node_modules/money-works/dist/money-works.min.js" type="text/javascript"></script>

or from the unpkg CDN

<script src="https://unpkg.com/money-works/dist/money-works.min.js"></script>

The script creates the Money global constructor or defines it if you are using AMD.

Because of its size, Andy Earnshaw's Intl package is not inlcuded in the distribution. To include it, please read his Getting Started section. For example:

<script src="https://unpkg.com/money-works/dist/money-works.min.js"></script>
<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Intl.~locale.fr,Intl.~locale.pt"></script>