ts-money
Version:
Typescript port of js-money. Implementation of the Money value object.
230 lines (157 loc) • 6.15 kB
Markdown
# TS Money
[](https://www.npmjs.com/package/ts-money)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/ts-money)
[](https://www.npmjs.com/package/ts-money)
TS Money is a Typescript port of the great [js-money](https://www.npmjs.com/package/js-money) package, which is an implementation of Martin Fowlers [Money pattern](http://martinfowler.com/eaaCatalog/money.html).
## Install
```sh
npm install ts-money
```
## Usage
First we need to import the library.
```typescript
import { Money, Currencies } from 'ts-money'
```
or in javascript:
```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.
```typescript
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:
```typescript
interface Currency {
symbol: string
name: string
symbol_native: string
decimal_digits: number
rounding: number
code: string
name_plural: string
}
```
Ex:
```typescript
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.
```typescript
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.
```typescript
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.
```typescript
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:
```typescript
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:
```typescript
const m1 = new Money(1, 'usd')
const m2 = new Money(2, 'USD')
const m3 = new Money(3, 'Usd')
```
## Development
### Install dependencies
```sh
npm install
```
### Build library
```sh
npm run build
```
### Run tests
```sh
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.
[](https://en.cryptobadges.io/donate/1A71NTVtocr1WG6qFuQjhbVsEwXC7pKB5R)
[](https://en.cryptobadges.io/donate/0x5cE72fB54733a15640AD23f8c8c296AadEeC53Cb)
[](https://en.cryptobadges.io/donate/4AzAgF56m5ihvDR5ctPVUE1RH78JEMsBHc63yYokHXbYGUCWsxphsmsgKzUkoQKmk7Tv6CSr3MosZ1wTR1wfHGt2187nHgj)
## License
[The MIT License](http://opensource.org/licenses/MIT)