• dinero.js: export DineroComparisonOperator as value, not type-only (124eb05), closes #847

• core: add "type": "module" to package.json (#845) (c8098ad), closes #843

Dinero.js v2 is a complete rewrite of the library, designed from the ground up for modern JavaScript and TypeScript. It replaces the object-oriented, chainable API with a functional architecture of pure, standalone functions that are fully tree-shakeable.

For a step-by-step migration guide, see the upgrade guide.

All chainable methods are now standalone functions. This enables bundlers to tree-shake unused operations.

- import Dinero from 'dinero.js';
- const price = Dinero({ amount: 500, currency: 'USD' });
- price.add(Dinero({ amount: 100, currency: 'USD' }));
+ import { dinero, add } from 'dinero.js';
+ import { USD } from 'dinero.js/currencies';
+ const price = dinero({ amount: 500, currency: USD });
+ add(price, dinero({ amount: 100, currency: USD }));

Currencies are now objects with code, base, and exponent properties instead of ISO 4217 strings. All 166 ISO 4217 currencies ship with the library.

- Dinero({ amount: 500, currency: 'USD' })
+ import { USD } from 'dinero.js/currencies';
+ dinero({ amount: 500, currency: USD })

The precision parameter is renamed to scale. Scale tracks the decimal point position independently of the currency exponent, allowing Dinero to preserve full precision through multi-step calculations.

- Dinero({ amount: 500, currency: 'USD', precision: 3 })
+ dinero({ amount: 500, currency: USD, scale: 3 })

Operations like multiply, allocate, and convert no longer accept floating-point numbers. All fractional values must be passed as scaled amounts to prevent IEEE 754 rounding errors.

- price.multiply(0.055)
+ multiply(price, { amount: 55, scale: 3 })

• divide — use allocate for lossless distribution
• percentage — use allocate or multiply
• toFormat, toUnit, toRoundedUnit — use toDecimal or toUnits with a transformer
• getAmount, getCurrency, getPrecision — use toSnapshot
• getLocale, setLocale — locale support removed; use toDecimal with Intl.NumberFormat
• Global defaults (Dinero.defaultCurrency, Dinero.globalLocale, etc.) — no global state

All public types use a Dinero prefix to avoid naming conflicts:

• Calculator → DineroCalculator
• Currency → DineroCurrency
• Snapshot → DineroSnapshot
• Options → DineroOptions

• Node.js 20+ required (v1 had no formal engine requirement)
• Internet Explorer is no longer supported

The dinero.js/bigint entry point provides a dinero function backed by native bigint arithmetic, enabling representation of amounts beyond Number.MAX_SAFE_INTEGER — essential for cryptocurrencies, high-precision finance, and currencies with many decimal places.

import { dinero, add } from 'dinero.js/bigint';
import { USD } from 'dinero.js/bigint/currencies';

const d = dinero({ amount: 999999999999999999n, currency: USD });

The createDinero factory accepts any object implementing DineroCalculator<T>, allowing third-party arbitrary-precision libraries (big.js, JSBI, etc.) as the numeric backend.

The currency.base field supports arrays for currencies with multiple subdivisions (e.g., pre-decimal British pounds: [20, 12] for 20 shillings/pound and 12 pence/shilling). The toUnits function decomposes amounts across all subdivisions.

Currency objects are typed with literal codes (DineroCurrency<number, 'USD'>), enabling TypeScript to catch currency mismatches at compile time — for example, preventing addition of USD and EUR values.

Scale propagates automatically during calculations. The trimScale function reduces it back to the smallest safe representation when needed, eliminating manual precision management.

• compare — three-way comparison returning -1 | 0 | 1
• toDecimal — string decimal representation with optional transformer
• toUnits — array of amounts per currency subdivision
• trimScale — reduce scale to smallest safe representation
• normalizeScale — align multiple Dinero objects to a common scale
• transformScale — convert to a specific scale

Eight rounding functions for precise control: up, down, halfUp, halfDown, halfEven, halfOdd, halfTowardsZero, halfAwayFromZero.

The package is marked sideEffects: false. Only the functions you import are included in your bundle.

• allocate: distribute remainder to largest ratio first (#776)
• allocate: prevent infinite loop with large amounts (#771)
• convert: throw when converting between currencies with different bases (#477)
• isPositive: return false for zero values (#728)
• toDecimal: handle negative units correctly (#690)
• toDecimal: preserve negative sign for leading zeros (#692)
• toDecimal: do not append decimal string when scale is zero (#751)
• rounding: fix up, down, halfUp handling of numbers close to 0 (#710, #713)
• currencies: use proper base and exponents for MRU and MGA
• currencies: update to ISO 4217 amendments 169-179

The library is distributed as a single dinero.js package with subpath exports:

ESM and UMD bundles are available. TypeScript declarations are included.

• Build system: tsdown (powered by Rolldown) for bundling and type generation
• Linting: Oxlint (Rust-based)
• Testing: Vitest with native TypeScript support
• Documentation: new VitePress site at dinerojs.com, with Algolia DocSearch and AskAI
• Node.js: 20+ required

The documentation has been completely rewritten and is available at dinerojs.com. It includes:

• Core concepts guide (amount, currency, scale, mutations, comparisons, formatting)
• Practical guides (serialization, database storage, payment services, cryptocurrencies, and more)
• Full API reference with examples
• Interactive examples: shopping cart (React + Vue), invoice builder, expense splitter, portfolio tracker, and pricing page

• api: throw when converting between currencies with different bases (#832) (47d6145), closes #477
• docs: add .html extension to documentation links in README (2536a1f)
• docs: add Vercel redirects for old URLs (4002439)
• docs: remove unnecessary npm install from Vercel build command (72f0a91)

• add compile-time currency safety with TCurrency type parameter (#833) (ab5d4a3)
• docs: add DocSearch AskAI integration (a343fb2)

All @dinero.js/* packages have been removed. The library is now distributed as a single dinero.js package with subpath exports.

import { dinero, add } from '@dinero.js/core';
import { USD } from '@dinero.js/currencies';
import { calculator } from '@dinero.js/calculator-bigint';

import { dinero, add } from 'dinero.js';
import { USD } from 'dinero.js/currencies';
import { dinero as dineroBigint } from 'dinero.js/bigint';

1. Uninstall all @dinero.js/* packages
2. Install dinero.js
3. Update imports as shown above

All public types now use a Dinero prefix to avoid naming conflicts:

• Calculator → DineroCalculator
• Currency → DineroCurrency
• Snapshot → DineroSnapshot
• Options → DineroOptions
• etc.

• dinero.js: consolidate packages with subpath exports (16b0ad8)
• dinero.js: add granular UMD bundles per RFC #722 (aea9dc2)
• bigint: include bigint currencies in UMD bundle (1054497)
• currencies: add bigint currency definitions (0e4aef8), closes #582
• currencies: add SLE, VED, XAD, XCG, ZWG (amendments 172-179)
• currencies: remove HRK, SLL, CUC, ANG, ZWL (amendments 172-179)

• currencies: correct UYW to amendment 169 and fix generation (0ea9d7e)
• docs: correct OG image path and hero animation target (f9a8585)

• allocate: distribute remainder to largest ratio first (#776) (6049038)
• allocate: prevent infinite loop with large amounts (#771) (d787b98)
• toDecimal: do not append decimal string when scale is zero (#759) (80a1dd7)

• upgrade to Node 24 and modernize dependencies (62b63c4)
• migrate CI from CircleCI to GitHub Actions (bd9249d)
• migrate from Yarn to npm (6ac35a3)

• isPositive: return false with zero (#728) (140fe68)
• up, down, halfUp: fix handling of numbers close to 0 and rounding of integer results (#711) (6b30aa0), closes #710 #713

• toDecimal: preserve negative sign for leading zeros (#693) (e6f290d), closes #692

• toDecimal: teach toDecimal how to handle negative units (#690) (81c5566)

• provide better support for non-decimal currencies (#309) (e7e9a19), closes #294

• ** the toUnit and the toFormat functions were removed.