charlieyqin / currency.js

A javascript library for handling currencies

currency.js

currency.js is a lightweight ~1kb javascript library for working with currency values. It was built to work around floating point issues in javascript. This talk by Bartek Szopka explains in detail why javascript has floating point issues.

currency.js works with values as integers behind the scenes, resolving some of the most basic precision problems.

2.51 + .01;                   // 2.5199999999999996
currency(2.51).add(.01);      // 2.52

2.52 - .01;                   // 2.5100000000000002
currency(2.52).subtract(.01); // 2.51

This should work for most reasonable values of currencies. As long as your currency values are less than 2⁵³ (in cents) or 90,071,992,547,409.91 you should be okay.

Features

• 0 dependencies!
• Immutable
• Flexible formatting options
• Handles any type of currency input, strings, numbers, or another currency instance

Installation

With npm:

npm install --save currency.js

With yarn:

yarn add currency.js

Via cdn:

<script src="https://unpkg.com/currency.js@~2.0.0/dist/currency.min.js"></script>

Need the latest cutting edge? All commits on master are tagged with next on npm:

npm install --save currency.js@next

Usage

Currency will accept numbers, strings, or the currency object itself as values.

currency(123);      // 123.00
currency(1.23);     // 1.23
currency("1.23")    // 1.23
currency("$12.30")  // 12.30

var value = currency("123.45");
currency(value);    // 123.45

Currency accepts decimal values (i.e. 1.23) with a default precision of 2, but can accept a minor currency unit (e.g. cents in a dollar). This will respect the precision option when parsing.

currency(123, { fromCents: true });               // 1.23
currency('123', { fromCents: true });             // 1.23
currency(123, { fromCents: true, precision: 0 }); // 123
currency(123, { fromCents: true, precision: 3 }); // 0.123

There's various arithmetic methods that help take the guesswork out of trying to resolve floating point problems.

currency(123.50).add(0.23);       // 123.73
currency(5.00).subtract(0.50);    // 4.50
currency(45.25).multiply(3);      // 135.75
currency(1.12).distribute(5);     // [0.23, 0.23, 0.22, 0.22, 0.22]

There's even a built in formatter that will automatically place comma delimiters in the right place.

currency("2,573,693.75").add("100,275.50").format();  // "$2,673,969.25"
currency("1,237.72").subtract(300).format();          // "$937.72"

You can also change the format, localizing the decimal and/or delimiter to your locale.

var euro = value => currency(value, { symbol: "€", separator: ".", decimal: "," });
euro("2.573.693,75").add("100.275,50").format();  // "€2.673.969,25"
euro("1.237,72").subtract(300).format();          // "€937,72"

Options

currency.js comes with its own set of default options conforming to USD. You can customize these according to your locale.

symbol default: $
Currency symbol included when calling currency.format().

separator default: ,
Separator dividing the number groups when calling currency.format().

decimal default: .
Decimal used when calling currency.format().

precision default: 2
Number of decimal places to store as cents.

pattern default: !#
Allows you to customize the format pattern using ! as replacement for the currency symbol and # as replacement for the currency amount.

negativePattern default: -!#
Allows you to customize the negative format pattern using ! as replacement for the currency symbol and # as replacement for the currency amount.

format default null Allows you to customize the format of the currency when calling currency.format(). format passes in the currency object as well as the options object to the function and expects a string to be returned. Use this when the provided formatting options do not meet your needs.

errorOnInvalid default: false
If an invalid value such as null or undefined is passed in, will throw an error.

increment default: null
When implementing a currency that implements rounding, setting the increment value will allow you to set the closest increment to round the display value to. currency(1.48, { increment: .05 }); // => 1.50

useVedic default: false
Formats number groupings using the Indian Numbering System, i.e. 10,00,000.00

fromCents default: false
Parse the amount value as a minor currency unit (e.g. cents in a dollar) instead of dollars.

View more examples and full documentation at scurker.github.io/currency.js.

Internationalization Examples

currency(1.23, { separator: " ", decimal: ",", symbol: "€" });

If you need to work with multiple currency values, the easiest way is to setup factory functions with your required currency settings.

const USD = value => currency(value, { symbol: "$", precision: 2 });
const JPY = value => currency(value, { symbol: "¥", precision: 0 });
const GAS = value => currency(value, { precision: 3 });

USD(1234.56).format(); // "$1,234.56"
JPY(1234.56).format(); // "¥1,235"
GAS(1234.56).format(); // "$1,234.560"

Add-ons

• babel-plugin-transform-currency-operators: An experimental babel plugin for transforming currency operations currency(1.23) + 4.56 to currency(1.23).add(4.56).

Other Libraries

Maybe currency.js isn't the right fit for your needs. Check out some of these other fine libraries:

• accounting.js
• dinero.js
• walletjs

License

MIT