currency.js

library2.0.4jsnpmunverified

currency.js is a lightweight JavaScript library specifically designed for accurate financial calculations and handling currency values, aiming to circumvent common floating-point precision issues inherent in JavaScript's number type. The current stable version is 2.0.4, with recent releases primarily focusing on critical bug fixes related to the `fromCents` option and minor security updates to development dependencies. The library provides a simple, fluent API for creating currency objects, performing arithmetic operations (add, subtract, multiply, divide), and robust formatting capabilities. It supports various international currency formats, custom patterns, and precision settings, making it a suitable choice for applications requiring reliable money management without the overhead of larger, more complex financial libraries. Its key differentiator is its small footprint and dedicated focus on fixed-point arithmetic for ensuring precision in monetary calculations.

payments serialization

npm install currency.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CURRENCY.JS

currency.js

paymentsjavascriptv2.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

currency

✓ import currency from 'currency.js';

✗ import { currency } from 'currency.js';

The primary `currency` function is typically imported as a default export.

CurrencyJs

✓ import currency, { type CurrencyJs } from 'currency.js';

When using TypeScript, the `CurrencyJs` type represents the instance returned by the `currency` function, allowing for type-safe operations.

currency (CommonJS)

✓ const currency = require('currency.js');

For CommonJS environments (e.g., older Node.js projects), `require` is used to import the library.

This quickstart demonstrates basic instantiation, arithmetic operations, custom formatting, and handling values explicitly as cents.

import currency from 'currency.js'; // Create a currency object const price = currency(1234.56); // Perform arithmetic operations const tax = price.multiply(0.0825); // Calculate 8.25% tax const shipping = currency(15.99); const total = price.add(tax).add(shipping); console.log(`Original Price: ${price.format()}`); console.log(`Tax Amount: ${tax.format()}`); console.log(`Shipping Cost: ${shipping.format()}`); console.log(`Total Amount: ${total.format()}`); // Using custom options const euroPrice = currency(100.50, { symbol: '€', separator: '.', decimal: ',' }); const discount = currency(10, { symbol: '€', separator: '.', decimal: ',' }); const finalEuroPrice = euroPrice.subtract(discount); console.log(`Euro Price: ${euroPrice.format()}`); console.log(`Final Euro Price after discount: ${finalEuroPrice.format()}`); // Handling values as cents const valueInCents = currency(2500, { fromCents: true }); // Represents $25.00 console.log(`Value from cents: ${valueInCents.format()}`);

Debug

Known issues

breakingThe `formatter` option within `currency.js` options object no longer exclusively accepts a string pattern. It now accepts either a function for fine-tuned customization or a static object defining formatting rules. Direct string patterns for `formatter` will no longer work as expected.

fix

If you were using a string for the `formatter` option, you must update your code to either provide a function that returns the formatted string, or an object with specific formatting properties like `symbol`, `separator`, etc.

affects: >=2.0.0

breakingThe behavior of parsing input values has changed when the `fromCents` option is enabled. Previously, inputs were always treated as standard decimal values; with `fromCents`, the input number is now interpreted directly as the total number of cents (e.g., `currency(100, { fromCents: true })` now represents $1.00, not $100.00 interpreted as cents).

fix

Review all instances where `fromCents: true` is used. Adjust your input values accordingly to ensure they represent the total cents rather than decimal currency amounts.

affects: >=2.0.0

gotchaMultiple bugs in early v2.x releases (v2.0.1, v2.0.2, v2.0.3) led to incorrect values being returned from methods, particularly when the `fromCents` option was in use. These issues could result in incorrect calculations or truncated fractional cents.

fix

Upgrade to `currency.js@2.0.4` or later to ensure correct calculations, especially when using the `fromCents` option. Thoroughly test your application's financial logic after upgrading.

affects: >=2.0.0 <2.0.4

gotchaBetween v1.2.0 and v1.2.1, there were adjustments to internal precision and flow definitions. While intended to fix edge cases, subtle differences in rounding or calculation results might occur compared to versions prior to v1.2.0.

fix

If migrating from versions older than `1.2.0`, re-verify critical financial calculations to ensure consistent results, as internal precision handling was adjusted.

affects: >=1.2.0 <2.0.0

Errors

Common errors & fixes

TypeError: currency.js: formatter option must be a function or object

Using a string as the value for the `formatter` option, which is no longer supported since v2.0.0.

fix

Change the `formatter` option to either a function that returns the formatted string or an object specifying formatting properties. Example: `{ formatter: (value) => `$${value}` }` or `{ formatter: { symbol: '$', separator: ',', decimal: '.' } }`.

Incorrect currency value after using fromCents option.

The input value when `fromCents: true` is interpreted directly as cents since v2.0.0. Also, bugs in `v2.0.0` through `v2.0.3` caused incorrect calculations when `fromCents` was active.

fix

For versions `v2.0.4` and above, ensure your input value is the exact number of cents (e.g., `currency(2500, { fromCents: true })` for $25.00). If you are on an older `v2.x` release, upgrade to `v2.0.4` or newer to resolve the calculation bugs.

Unformatted number instead of currency string.

Forgetting to call the `.format()` method on a `currency.js` object, or incorrect formatting options.

fix

Always call `.format()` on the `currency` object instance to get the formatted string (e.g., `myCurrencyValue.format()`). Review options like `pattern`, `separator`, `decimal`, and `symbol` for correct display.

Upgrade

Version history

2.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/scurker/currency.js ↗

packagehttps://www.npmjs.com/package/currency.js ↗

homepagehttp://scurker.github.io/currency.js ↗