TS Money
TS Money is a Typescript port of the great js-money package, which is an implementation of Martin Fowlers Money pattern.
Install
npm install ts-money
Usage
First we need to import the library.
import { Money, Currencies } from 'ts-money'
or in javascript:
const TsMoney = require('ts-money')
const Money = TsMoney.Money
const Currencies = TsMoney.Currencies
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 (only with
fromInteger
and fromDecimal
methods)
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.
const fiveEur = new Money(500, Currencies.EUR)
const tenDollars = Money.fromInteger({ amount: 1000, currency: Currencies.USD })
const someDollars = Money.fromDecimal(15.25, 'USD')
const moreDollars = Money.fromDecimal(15.3456, Currencies.USD)
const someMoreDollars = Money.fromDecimal(15.12345, 'USD', Math.ceil)
The Currency
interface hold the following properties:
interface Currency {
symbol: string
name: string
symbol_native: string
decimal_digits: number
rounding: number
code: string
name_plural: string
}
Ex:
import { Currency } from 'ts-money'
const usd: Currency = {
"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.
const fiveEur = new Money(500, Currencies.EUR)
fiveEur.add(new Money(250, Currencies.EUR))
fiveEur.subtract(new Money(470, Currencies.EUR))
fiveEur.multiply(1.2345)
fiveEur.multiply(1.2345, Math.ceil)
fiveEur.divide(2.3456)
fiveEur.divide(2.3456, Math.ceil)
Allocating funds
Will divide the funds based on the ratio without loosing any pennies.
const tenEur = new Money(1000, Currencies.EUR)
const shares = tenEur.allocate([1,1,1])
const fiveEur = new Money(500, Currencies.EUR)
const shares = fiveEur.allocate([70,30])
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.
const fiveEur = new Money(500, Currencies.EUR)
const anotherFiveEur = new Money(500, Currencies.EUR)
const sevenEur = new Money(700, Currencies.EUR)
const fiveDollars = new Money(500, Currencies.USD)
fiveEur.equals(fiveDollars)
fiveEur.equals(anotherFiveEur)
fiveEur.compare(sevenEur)
sevenEur.compare(fiveEur)
fiveEur.compare(anotherFiveEur)
fiveEur.compare(fileDollars)
fiveEur.greaterThan(sevenEur)
fiveEur.greaterThanOrEqual(sevenEur)
fiveEur.lessThan(sevenEur)
fiveEur.lessThanOrEqual(fiveEur)
Modifications
Some changes have been made compared with the javascript version:
Currencies object
Currencies are now exported in a standalone object:
import { Money, Currencies } from 'ts-money'
Currencies.LTC = {
symbol: "Ł",
name: "Litecoin",
symbol_native: "Ł",
decimal_digits: 8,
rounding: 0,
code: "LTC",
name_plural: "Litecoins"
}
const m1 = new Money(12, 'LTC')
const m2 = new Money(234, Currencies.USD)
const m3 = new Money(543, Currencies.LTC)
Case insensitive currencies
Money accepts currencies as case insensitive:
const m1 = new Money(1, 'usd')
const m2 = new Money(2, 'USD')
const m3 = new Money(3, 'Usd')
Development
Install dependencies
npm install
Build library
npm run build
Run tests
npm test
🎁 Thank you for your donations
TS Money is an open source library and is completely free to use.
If you find this project useful and would like to support its development, consider making a donation.
License
The MIT License