vongohren/js-money

JavaScript Implementation of Fowlers Money object.

JS Money

JS Money is a JavaScript implementation of Martin Fowlers Money pattern.

Install

The package is available through npm and bower.

$ npm install js-money
$ bower install js-money

Usage

First we need to import the library.

var Money = require('js-money');

Creating a new instance

There are multiple options of what to pass into the constructor to create a new Money instance:

• amount as number, currency as string
• amount as number, currency as object
• object with amount and currency fields

Amounts can be supplied either as integers or decimal numbers.

Instances of Money are immutable and each arithmetic operation will return a new instance of the object.

When using decimals the library will allow only decimals with the precision allowed by the currencies smallest unit.

var fiveEur = new Money(500, Money.EUR);
var someDollars = new Money(15.25, 'USD');
var tenDollars = new Money({amount: 100, currency: Money.USD});

// the following will fail and throw an Error since USD allows for 2 decimals
var moreDollars = new Money(15.3456, Money.USD); // 

The currency object hold the following properties

    {
        "symbol": "$",
        "name": "US Dollar",
        "symbol_native": "$",
        "decimal_digits": 2,
        "rounding": 0,
        "code": "USD",
        "name_plural": "US dollars"
    }

Basic arithmetics

Arithmetic operations involving multiple objects are only possible on instances with the same currency and will throw an Error otherwise.

var fiveEur = new Money(500, Money.EUR); // 5 EUR

// add
var result = fiveEur.add(250, Money.EUR); // 7.50 EUR

// subtract 
var result = fiveEur.subtract(470, Money.EUR); // 0.30 EUR

// multiply
var result = fiveEur.multiply(1.2); // 6 EUR

// divide 
var result = fiveEur.divide(2); // 2.50 EUR

Allocating funds

Will divide the funds based on the ratio without loosing any pennies.

var tenEur = new Money(1000, Money.EUR);

// divide 10 EUR into 3 parts
var shares = tenEur.allocate([1,1,1]); 
// returns an array of money worth [334,333,333]

// split 5 EUR 70/30
var fiveEur = new Money(500, Money.EUR);
var shares = fiveEur.allocate([70,30]);
// returns an array of money [350,150]

Comparison and equality

Two objects are equal when they are of the same amount and currency. Trying to compare 2 objects with different currencies will throw an Error.

var fiveEur = new Money(500, Money.EUR);
var anotherFiveEur = new Money(500, Money.EUR);
var sevenEur = new Money(700, Money.EUR);
var fiveDollars = new Money(500, Money.USD);

fiveEur.equals(fiveDollars); // return false
fiveEur.equals(anotherFiveEur); // return true

fiveEur.compare(sevenEur); // return -1
sevenEur.compare(fiveEur); // return 1
fiveEur.compare(anotherFiveEur); // return 0

fiveEur.compare(fileDollars); // throw Error

Tests

$ npm install
$ npm test

License

The MIT License

Copyright (c) 2014 David Kalosi http://davidkalosi.com/