Class Money

Create a new Money object from a floating-point value. The value will be automatically rounded to the currency's smallest unit. The value will only be precise to the currency's smallest unit (e.g. USD$18.98123 will be rounded to USD$18.98)

Throws

• TypeError on non-float amount values.
• RangeError on unsupported currency.

Example

const fiveDollarsAndSeventyCents = Money.fromFloat('USD', 5.70)
fiveDollarsAndSeventyCents.getCurrency()      // => 'USD'
fiveDollarsAndSeventyCents.getAmount()        // => 570
fiveDollarsAndSeventyCents.toLocaleString()   // => '$5.70'

Create a new Money object from a string. Supports both integer and floating-point string values. If the amount is a floating-point, it will be automatically rounded to the currency's smallest unit. The value will only be precise to the currency's smallest unit (e.g. USD$18.98123 will be rounded to USD$18.98)

Throws

• TypeError on incorrect amount values.
• RangeError on unsupported currency.

Example

// Float
const fiveDollarsAndSeventyCents = Money.fromString('USD', '5.70')
fiveDollarsAndSeventyCents.getCurrency()      // => 'USD'
fiveDollarsAndSeventyCents.getAmount()        // => 570
fiveDollarsAndSeventyCents.toLocaleString()   // => '$5.70'
// Int
const eightyEur = Money.fromString('EUR', '8000')
eightyEur.getCurrency()                       // => 'EUR'
eightyEur.getAmount()                         // => 8000
eightyEur.toLocaleString()                    // => '€80.00'

Returns

The amount value.

Example

const oneDollar = new Money('USD', 10)
oneDollar.getAmount()   // => 10

Returns

The currency code.

Example

const oneDollar = new Money('USD', 10)
oneDollar.getCurrency() // => 'USD'

Returns

True if input is identical to this Money, otherwise false.

Throws

• TypeError if input is not a Money.

Example

const a = new Money('USD', 2000)
const b = new Money('USD', 1000)
a.equals(b)  // => false
const c = new Money('USD', 2000)
a.equals(c)  // => true
const d = new Money('EUR', 2000)
c.equals(d)  // => false

Returns

True if input is greater than this Money, otherwise false.

Throws

• TypeError if input is not a Money.

Example

const a = new Money('USD', 2000)
const b = new Money('USD', 1000)
a.greaterThan(b)  // => true
b.greaterThan(a)  // => false
a.greaterThan(a)  // => false

Returns

True if input is greater than or equal to this Money, otherwise false.

Throws

• TypeError if input is not a Money.

Example

const a = new Money('USD', 1900)
const b = new Money('USD', 2000)
const c = new Money('USD', 2100)
a.greaterThanOrEqual(b)  // => false
b.greaterThanOrEqual(a)  // => true
a.greaterThanOrEqual(a)  // => true
c.greaterThanOrEqual(b)  // => true

Returns

True if input is less than this Money, otherwise false.

Throws

• TypeError if input is not a Money.

Example

const a = new Money('USD', 1000)
const b = new Money('USD', 2000)
a.lessThan(b)  // => true
b.lessThan(a)  // => false
a.lessThan(a)  // => false

Returns

True if input is less than or equal to this Money, otherwise false.

Throws

• TypeError if input is not a Money.

Example

const a = new Money('USD', 1900)
const b = new Money('USD', 2000)
const c = new Money('USD', 2100)
a.lessThanOrEqual(b)  // => true
b.lessThanOrEqual(a)  // => false
a.lessThanOrEqual(a)  // => true
c.lessThanOrEqual(b)  // => false

Returns

A new Money holding the sum of this Money and input(s).

Throws

• TypeError if input(s) is not a Money.
• RangeError if currencies are not identical.

Example

const fiveUsd = new Money('USD', 500)
const tenUsd = new Money('USD', 1000)
const sum0 = fiveUsd.add(tenUsd)           // $5 + $10
sum0.getAmount()                           // => 1500
sum0.toLocaleString()                      // => '$15.00'
const fiftyUsd = new Money('USD', 5000)
const sum1 = fiveUsd.add(tenUsd, fiftyUsd) // $5 + $10 + $50
sum1.getAmount()                           // => 6500
sum1.toLocaleString()                      // => '$65.00'

Returns

A new Money holding the quotient of this Money and input.

Example

const twentyYuan = new Money('CNY', 2000)
const quotient = twentyYuan.divide(8)  // CN¥20 / 8
quotient.getAmount()                   // => 250
quotient.toLocaleString()              // => 'CN¥2.50'

Returns

A new Money holding the product of this Money and input.

Example

const fiveYen = new Money('JPY', 500)
const product = fiveYen.multiply(9)   // ¥500 * 9
product.getAmount()                   // => 4500
product.toLocaleString()              // => '¥4,500'

Returns

A new Money holding the difference between this Money and input(s).

Throws

• TypeError if input(s) is not a Money.
• RangeError if currencies are not identical.

Example

const tenEur = new Money('EUR', 1000)
const fiveEur = new Money('EUR', 500)
const diff0 = tenEur.subtract(fiveEur)           // €10 - €5
diff0.getAmount()                                // => 500
diff0.toLocaleString()                           // => '€5.00'
const fiftyEur = new Money('EUR', 5000)
const diff1 = tenEur.subtract(fiftyEur, fiveEur) // €10 - €50 - €5
diff1.getAmount()                                // => -4500
diff1.toLocaleString()                           // => '-€45.00'

Convert Money to JSON.

Returns

JSON object.

Example

const tenDollars = new Money('USD', 1000)
tenDollars.toJSON()  // => { currency: 'USD', amount: 1000 }

Formats this Money object to locale-aware string with its currency symbol, using Intl.NumberFormat.

Returns

The string-formatted Money with its currency symbol (e.g. "$49.99", "9,99 €").

Example

const tenDollars = new Money('USD', 1000)
// Using default locale (`en-US`):
tenDollars.toLocaleString()         // => $10.00
// Using different locale:
tenDollars.toLocaleString('fr-CA')  // => 10,00 $ US

Returns

Currency unit for currency.