# money-works
> Work with money in multiple currencies
Latest version **1.5.4** (published 2018-06-21) · MIT license · 0 weekly downloads
## Install
```sh
npm install money-works
pnpm add money-works
yarn add money-works
bun add money-works
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.5.4 |
| Published | 2018-06-21 |
| First published | 2016-11-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 416.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Richard Schneider |
| Maintainers | makaretu |
| Keywords | money, currency, forex, conversion, fiat, moolah, i18n, internationalization, internationalisation, 10n, localization, localisation, locale, math, accounting |
## Links
- npm: https://www.npmjs.com/package/money-works
- Repository: https://github.com/richardschneider/money-works
- Issues: https://github.com/richardschneider/money-works/issues
- npm.io page: https://npm.io/package/money-works
## Dependencies (3)
- [intl](https://npm.io/package/intl.md) ^1.2.5
- [big.js](https://npm.io/package/big.js.md) ^5.1.0
- [memoize-immutable](https://npm.io/package/memoize-immutable.md) ^2.1.0
## Recent versions
- 1.5.4 (latest) — 2018-06-21
- 1.5.3 — 2018-06-21
- 1.5.2 — 2016-11-20
- 1.5.1 — 2016-11-19
- 1.5.0 — 2016-11-19
- 1.4.0 — 2016-11-18
- 1.3.1 — 2016-11-17
- 1.3.0 — 2016-11-15
- 1.2.0 — 2016-11-10
- 1.1.0 — 2016-11-07
- 1.0.0 — 2016-11-05
- 0.5.0 — 2016-11-04
- 0.4.1 — 2016-11-04
- 0.4.0 — 2016-11-04
- 0.3.0 — 2016-11-04
- … 3 more at https://npm.io/package/money-works/versions
## README
# money-works
[](https://travis-ci.org/richardschneider/money-works)
[](https://coveralls.io/github/richardschneider/money-works?branch=master)
[](https://badge.fury.io/js/money-works)
Work with money in multiple currencies and different locales. See the [online demonstration](https://richardschneider.github.io/money-works/index.html).
The [change log](https://github.com/richardschneider/money-works/releases) is automatically produced with
the help of [semantic-release](https://github.com/semantic-release/semantic-release).
## Features
- [Banker's rounding](https://en.wikipedia.org/wiki/Rounding) to the precision of the currency
- Locale specific formatting using the [Internationalization API](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Intl)
- Precision decimal arithmetic using a [big number](https://www.npmjs.com/package/big.js) package
- [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) currency codes
- Currency conversion
- Uses [Martin Folwer's](http://martinfowler.com/) design pattern for [Money](http://martinfowler.com/eaaCatalog/money.html)
- Allocation of funds without loosing pennies (smallest denomination)
- Uses [Andy Earnshaw's Intl](https://github.com/andyearnshaw/Intl.js) when the environment's `Intl` package doesn't support the language.
- Non-latin numbering systems
- Maintains a cache of locales for performance
- Supports the common cryptocurrencies XBT(BTC), ETH, XMR and XRP
## Getting started
**money-works** is available for [Node.js](https://nodejs.org) and most modern browsers. If you want to know if your currrent browser is compatible, run the [online test suite](https://richardschneider.github.io/money-works/test.html) or the [online demonstration](https://richardschneider.github.io/money-works/index.html).
Install with [npm](http://blog.npmjs.org/post/85484771375/how-to-install-npm)
> npm install money-works --save
### Usage
const Money = require('money-works');
const price = new Money(1000.6, 'JPY');
`toString` always returns the exact amount and currency
price.toString() // '1000.6 JPY'
`toLocaleString` returns the localised version of the Money. Note that YEN is not displayed with decimal places.
price.toLocaleString('en-NZ') // '¥1,001'
price.toLocaleString('fr-CA') // '1 001 ¥'
`allocate` distributes the Money based on the ratio without loosing any pennies. It returns an Array of Money.
price.allocate([1, 1]) // '501 JPY' and '500 JPY'
price.allocate([70, 20, 10]) // '701 JPY', '200 JPY' and '100 JPY'
with ES6, `me` gets 70% and `other` only 30% of the price
let [me, other] = price.allocate([70, 30]);
The standard Math functions (`plus`, `minus` and `times`) are available and are chainable. `plus` and `minus` require Money of the same currency. Its always a good idea to `round` the result of a calculation, which uses banker's rounding to the precision of the currency.
let gst = 0.15,
total = price // '1151 YPN' = 1000.6 + 150.09
.plus(price.times(gst))
.round();
Comparision functions are `eq`, `ne`, `lt`, `lte`, `gt`, `gte` and require Money of the same currency. Testing the amount against zero is done with `isZero`, `isNotZero`, `isPositive` and `isNegative`.
if (total.isPositive()) {
placeOrder();
}
### Rounding
When required, Money is normally rounded to the precision of the currency using the banker's rounding algorithm. The precision (number of decimal places) can be optionally specified.
The `round` method can accept the number of decimal places.
new Money(123.57719, 'NZD').round(); // '123.58 NZD'
new Money(123.57719, 'NZD').round(4); // '123.5772 NZD'
The `allocate` method also has an optional precision
const fund = new Money(1000.6, 'JPY');
fund.allocate([1, 1]) // '501 JPY' and '500 JPY'
fund.allocate([1, 1], 4) // '501.3 JPY' and '500.3 JPY'
And `toLocaleString`
let money = new Money(123.57719, 'NZD');
let options = { maximumFractionDigits: 4 };
money.toLocaleString('fr-FR', options); // '123,5772 $NZ'
### Localisation
`toLocaleString([locales], [options])` gets the local representation of the Money in the locale; see [MDN](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) for the details. The `options.style` and `options.currency` are always set to 'currency' and Money.currency, respectively.
price.toLocaleString('fr-CA') // '1 001 ¥'
let opt = { currencyDisplay: 'code' }
price.toLocaleString('fr-CA', opt) // '1 001 JPY'
A default locale and localeOptions is set with `Money.defaultLocale` and `Money.defaultLocaleOptions`. Both defaults are a function that return the default locale (string or array) and default locale options (object), respectively.
Money.defaultLocale = () => window.lang;
### Currency conversion
`to(currency)` returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to convert the Money into another currency. It uses `Money.forexService` to determine the exchange rate. If the exchange rate cannot be determined, then the Promise is rejected. The conversion does not round the result.
The default `forexService` uses the exchange rates from the [free currency converter](https://free.currencyconverterapi.com/).
new Money('100 NZD')
.to('JPY')
.then(console.log) // 7758.9 JPY
### Browser usage
Include the package from your project
or from the [unpkg CDN](https://unpkg.com)
The script creates the `Money` global constructor or defines it if you are using [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition).
Because of its size, Andy Earnshaw's Intl package is not inlcuded in the distribution. To include it, please read his [Getting Started](https://github.com/andyearnshaw/Intl.js/blob/master/README.md#getting-started) section. For example:
---
_Source: https://npm.io/package/money-works · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._