money-works

Work with money in multiple currencies and different locales.

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

Features

• Precision decimal arithmetic using a big number package
• ISO-4217 currency codes
• Uses Martin Folwer's design pattern for Money
• Allocation of funds without loosing pennies (smallest denomination)
• Banker's rounding to the precision of the currency
• Formats to the user's conventions using the Internationalization API; including non-latin numbering systems
• Uses Andy Earnshaw's Intl when the environment's Intl package doesn't support the language.

Getting started

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();
}