README.md

es-money

A value object class for dealing with money and currencies

Basic usage

const Money = require('es-money')
const oneDollar = new Money('USD', 1) // Money {currency: 'USD', amount: '1.00'}

Additional examples

oneDollar.add(oneDollar)
// -> Money { currency: 'USD', amount: '1.00' }

oneDollar.subtract(oneDollar)
// -> Money { currency: 'USD', amount: '0.00' }

oneDollar.multiply(1.1)
// -> Money { currency: 'USD', amount: '1.10' }

oneDollar.allocate([75, 25])
// -> [Money { currency: 'USD', amount: '0.75' }, Money { currency: 'USD', amount: '0.25' }]

oneHundredDollars.allocate([1, 1, 1])
// -> [Money { currency: 'USD', amount: '33.34' }, Money { currency: 'USD', amount: '33.33' }, Money { currency: 'USD', amount: '33.33' }]

JSON.stringify(oneDollar) // -> '{"currency":"USD","amount":"1.00"}'
Money.fromObject({currency:'VND', amount:'1234'}) // -> Money { currency: 'VND', amount: '1234' }

Custom exception types

Inherits from Error:

Money.CurrencyMismatchError // Can't add apples to oranges
Money.CurrencyUnknownError // Currency code not registered
Money.SubunitError // Can't create fractional cents
Money.AmountError // Passed amount doesn't look like a number

Registering / modifying currencies

The module comes with >120 currencies by default in ./currencymap.json. In addition, definitions can be added or updates like so:

Money.registerCurrency('XYZ', {decimalDigits: 2})
new Money('XYZ', 3.14) // ... and so on

Design rationale

• Keep feature set and module interface minimal (a value object should be just a value object)
• Store amounts internally in integer subunit form (and avoid implementation leak)
• Present amounts in string form (to avoid precision ambiguities)
• Fail / throw exceptions early (to avoid mistakes from proliferating)
• Use accessors for immutable properties (to allow exceptions even if the calling code forgot to 'use strict' itself)
• Don't deal in currency-specific rounding rules (they are likely application-specific anyway, and often complex enough to be the concern of a separate component)
• Don't deal with localization of currency names (or currency symbols, or other presentation-level stuff)
• Test everything (what else?)

Background

The Money pattern is a well-known specialized form of the broader Value Object design pattern: it provides a level of protection against common programming errors when dealing with financial records of multiple currencies.

Aside from the risk of mistakenly adding or subtracting values in differing currencies, the JavaScript Number type makes it easy to end up with impossibly tiny (-for the currency-) fractional amounts (e.g. 0.1 + 0.2 = 0.30000000000000004 or 100 * 1.1 = 110.00000000000001) that end up causing issues in user interfaces and in communications with external systems.

Module name

The es- prefix might be an abbreviation of ECMAScript or e(a)s(y)-.

Caveats

This module was written with transpilation for some feasible level of backwards compatibility, but will still probably not run on any Node.js version older than 4.6

Acknowledgements

The included currency registry is based on data published by the LocalePlanet project: http://www.localeplanet.com/

License

Copyright (c) 2016 Conny Brunnkvist. Licensed under the MIT License