Neatly Punctuated Musings

    ts-money
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.8 • Public • Published

    TS Money

    NPM version License: MIT

    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')
    
    // the following will fail and throw an Error since USD allows for 2 decimals
    const moreDollars = Money.fromDecimal(15.3456, Currencies.USD)
    // but with rounder function provider the following will work
    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) // 5 EUR
    
    // add
    fiveEur.add(new Money(250, Currencies.EUR)) // 7.50 EUR
    
    // subtract 
    fiveEur.subtract(new Money(470, Currencies.EUR)) // 0.30 EUR
    
    // multiply
    fiveEur.multiply(1.2345) // 6.17 EUR
    fiveEur.multiply(1.2345, Math.ceil) // 6.18 EUR
    
    // divide 
    fiveEur.divide(2.3456) // 2.13 EUR
    fiveEur.divide(2.3456, Math.ceil) // 2.14 EUR

    Allocating funds

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

    const tenEur = new Money(1000, Currencies.EUR)
    
    // divide 10 EUR into 3 parts
    const shares = tenEur.allocate([1,1,1]) 
    // returns an array of Money instances worth [334,333,333]
    
    // split 5 EUR 70/30
    const fiveEur = new Money(500, Currencies.EUR)
    const 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.

    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) // 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
    
    fiveEur.greaterThan(sevenEur) // return false
    fiveEur.greaterThanOrEqual(sevenEur) // return false
    fiveEur.lessThan(sevenEur) // return true
    fiveEur.lessThanOrEqual(fiveEur) // return true

    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.

    Donate with Bitcoin

    Donate with Ethereum

    Donate with Monero

    License

    The MIT License

    Install

    npm i ts-money

    DownloadsWeekly Downloads

    17,499

    Version

    0.4.8

    License

    MIT

    Unpacked Size

    57.7 kB

    Total Files

    13

    Last publish

    Collaborators

    • mcormier