{"id":12719,"library":"currency.js","title":"Currency.js - Financial Calculations","description":"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.","status":"active","version":"2.0.4","language":"javascript","source_language":"en","source_url":"git://github.com/scurker/currency.js","tags":["javascript","currency","money","utilities","accounting","format","number","parse","precision","typescript"],"install":[{"cmd":"npm install currency.js","lang":"bash","label":"npm"},{"cmd":"yarn add currency.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add currency.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `currency` function is typically imported as a default export.","wrong":"import { currency } from 'currency.js';","symbol":"currency","correct":"import currency from 'currency.js';"},{"note":"When using TypeScript, the `CurrencyJs` type represents the instance returned by the `currency` function, allowing for type-safe operations.","symbol":"CurrencyJs","correct":"import currency, { type CurrencyJs } from 'currency.js';"},{"note":"For CommonJS environments (e.g., older Node.js projects), `require` is used to import the library.","symbol":"currency (CommonJS)","correct":"const currency = require('currency.js');"}],"quickstart":{"code":"import currency from 'currency.js';\n\n// Create a currency object\nconst price = currency(1234.56);\n\n// Perform arithmetic operations\nconst tax = price.multiply(0.0825); // Calculate 8.25% tax\nconst shipping = currency(15.99);\nconst total = price.add(tax).add(shipping);\n\nconsole.log(`Original Price: ${price.format()}`);\nconsole.log(`Tax Amount: ${tax.format()}`);\nconsole.log(`Shipping Cost: ${shipping.format()}`);\nconsole.log(`Total Amount: ${total.format()}`);\n\n// Using custom options\nconst euroPrice = currency(100.50, { symbol: '€', separator: '.', decimal: ',' });\nconst discount = currency(10, { symbol: '€', separator: '.', decimal: ',' });\nconst finalEuroPrice = euroPrice.subtract(discount);\n\nconsole.log(`Euro Price: ${euroPrice.format()}`);\nconsole.log(`Final Euro Price after discount: ${finalEuroPrice.format()}`);\n\n// Handling values as cents\nconst valueInCents = currency(2500, { fromCents: true }); // Represents $25.00\nconsole.log(`Value from cents: ${valueInCents.format()}`);\n","lang":"typescript","description":"This quickstart demonstrates basic instantiation, arithmetic operations, custom formatting, and handling values explicitly as cents."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The 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).","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Multiple 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.","severity":"gotcha","affected_versions":">=2.0.0 <2.0.4"},{"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.","message":"Between 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.","severity":"gotcha","affected_versions":">=1.2.0 <2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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: '.' } }`.","cause":"Using a string as the value for the `formatter` option, which is no longer supported since v2.0.0.","error":"TypeError: currency.js: formatter option must be a function or object"},{"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.","cause":"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.","error":"Incorrect currency value after using fromCents option."},{"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.","cause":"Forgetting to call the `.format()` method on a `currency.js` object, or incorrect formatting options.","error":"Unformatted number instead of currency string."}],"ecosystem":"npm"}