README

@vested/money

A Money wrapper class for node and the browser, built on Big.js, to make dealing with arbitrarily large amounts of money easy.

Each Money object is immutable, infiniately large, and infiniately small.

Installation

yarn add @vested/money

Example Usage

import { Money } from '@vested/money'

const oneFifty = new Money('1.50', 'USD')
// => $1.50

const threeDollars = oneFifty.times(2)
// => $3.00

const threeFifty = threeDollars.plus(50)
// => $3.50

const fourDollars = threeFifty.roundUnit()
// => $4.00

const oneDollar = fourDollars.minus(threeDollars)
// => $1.00

const twoDollars = fourDollars.div(2)
// => $2.00

threeDollars.gt(twoDollars)
// => true

threeDollars.lt(twoDollars)
// => false

fourDollars.eq(twoDollars.plus(twoDollars))
// => true

Methods

new Money(units, currency = 'USD): Money

Money.fromAmount(units, currency = 'USD'): Money

Builds a new Money object, taking the number of units (dollars) as the first argument and an optional currency string as a second argument (default 'USD'). For example, the following builds a $3.50 USD Money object:

const money = new Money(3.50, 'USD')
// => 3.50

const money2 = Money.fromAmount('3.50', 'USD')
// => 3.50

You can pass a string, number, or Big as the first argument.

Money.fromCents(units, currency = 'USD'): Money

Builds a new Money object, taking subunits (cents) as the first argument and an optional currency string as a second argument (default 'USD'). For example, the following builds a $3.50 USD Money object:

const money = Money.fromCents('350', 'USD')
// => $3.50

You can pass a string, number, or Big as the first argument.

Money.fromJSON(): Money

Builds a new Money object from a given MoneyJSON object, generally created by the money.toJSON() method below.

const money = Money.fromJSON({
  units: '3.50',
  cents: '350',
  currency: 'USD'
})
// => $3.50

Money.zero(currency = 'USD'): Money

Helper method to build a zero object of a given currency (default 'USD').

const money = Money.zero('USD')
// => $0.00

money.cents: Big

Returns a Big object representing the cents of the Money object

const money = Money.fromAmount(3.50, 'EUR')
money.cents
// => '350'

money.currency: string

Returns a string representing the currency.

const money = Money.zero('EUR')
money.currency
// => 'EUR'

money.units: Big

Returns a Big object representing the units of the Money object

const money = Money.fromCents(350, 'EUR')
money.units
// => '3.50'

money.toJSON(): MoneyJSON

Returns a MoneyJSON representation of a Money object

const money = Money.fromAmount('3.50')
money.toJSON()
// => { units: '3.50', cents: '350', currency: 'USD' }

money.toFixed(size = 2): string

Returns a string rounded to a given number of units, using half-up rounding.

const money = Money.fromAmount('3.50')
money.toFixed()
// => '3.50'
money.toFixed(2)
// => '3.50'
money.toFixed(1)
// => '3.5'
money.toFixed(0)
// => '4'

money.roundToUnit(mode = 'half-up'): Money

Returns a new Money object rounded to the nearest unit, using the provided rounding mode.

const money = Money.fromAmount('4.50')
money.roundToUnit()
// => Money<$5.00>

money.roundToUnit('down')
// => Money<$4.00>

money.roundToUnit('up')
// => Money<$5.00>

money.roundToUnit('half-up')
// => Money<$5.00>

money.roundToUnit('half-even')
// => Money<$4.00>

money.rountToCent(mode = 'half-up'): Money

Returns a new Money object rounded to the nearest cent, using the provided rounding mode.

const money = Money.fromAmount('0.985')
money.roundToCent()
// => Money<$0.99>

money.roundToCent('down')
// => Money<$0.98>

money.roundToCent('up')
// => Money<$0.99>

money.roundToCent('half-up')
// => Money<$0.99>

money.roundToCent('half-even')
// => Money<$0.98>