dinerojs/dinero.js
Dinero.js
Dinero.js is a TypeScript-first library for creating, calculating, and formatting monetary values. It provides immutable money objects that represent amounts in the smallest currency subdivision as integers, ensuring precision and preventing floating-point errors. The library enforces same-currency rules on arithmetic operations and validates currency codes against ISO 4217 definitions at creation time.
The library distinguishes itself through a calculator plugin architecture that delegates arithmetic operations to interchangeable backends, supporting number, bigint, or custom precision libraries. It offers type-safe module variants with separate import paths for number and bigint backends, enabling compile-time type selection without runtime overhead. Dinero.js also includes a proportional allocation algorithm that distributes monetary values across recipients without losing fractional cents, and provides scale-normalized arithmetic that converts amounts to a common decimal scale before addition or subtraction.
The library supports immutable arithmetic operations including addition, subtraction, comparison, proportional allocation, and currency conversion. It generates decimal string representations of monetary amounts without locale-specific formatting, allowing callers to apply their own localization layer. Custom scale configuration enables overriding the default currency exponent to handle currencies with no minor units or non-decimal subdivisions.
Features
- Monetary Value Libraries - Provides an immutable library for creating, calculating, and formatting monetary values with precision-safe arithmetic.
- Multi-Currency Value Objects - Represents and converts monetary values across currencies with configurable scale and subdivision handling.
- Currency Validators - Enforces same-currency rules on arithmetic and validates currency codes against ISO 4217.
- Monetary Calculator Plugins - Provides a plugin architecture that delegates arithmetic to interchangeable calculator backends.
- Monetary Value Objects - Provides immutable money objects with safe arithmetic, comparison, and formatting operations.
- Scale-Normalized Monetary Arithmetic - Normalizes monetary amounts to a common decimal scale before arithmetic to prevent precision loss.
- Monetary Arithmetic Libraries - Handles monetary values with multiple amount types including number, bigint, and custom precision backends.
- Proportional Money Splitters - Splits monetary values across recipients according to ratios without losing fractional cents.
- Smallest Subdivision Integers - Represents amounts in the smallest currency subdivision as integers to prevent floating-point errors.
- Monetary Precision Backends - Supports custom calculator plugins for third-party precision libraries like big.js.
- Monetary Allocation Algorithms - Implements a proportional allocation algorithm that distributes monetary values without losing fractional cents.
- Financial Arithmetic Libraries - Performs arithmetic on monetary values without floating-point errors, supporting proportional allocation and currency conversion.
- Bigint and Number Variants - Provides separate import paths for number and bigint backends, enabling compile-time type selection.
- Monetary - Represents monetary values as frozen immutable objects with amount and currency.
- Addition and Subtraction Operations - Adds or subtracts monetary values immutably, returning new objects without altering originals.
- Addition Operations - Sums money objects with scale normalization and same-currency enforcement.
- Safe Arithmetic Operations - Performs immutable arithmetic on monetary values with scale normalization and same-currency enforcement.
- Value Comparisons - Compares monetary values for equality, greater-than, or less-than relationships.
- Value Constructors - Creates immutable money objects from an amount and currency code for safe arithmetic.
- Subdivision Overrides - Ships custom scale configuration to override default currency exponents for non-standard subdivisions.
- Locale-Aware Currency Formatting - Generates decimal string representations of monetary amounts without locale-specific formatting.
- Locale-Independent Decimal Formatters - Generates decimal strings without locale-specific formatting, leaving localization to the caller.
- Currency Conversion - Converts monetary values between currencies using exchange rates while maintaining precision.
- Monetary Amount Type Selectors - Selects between number, bigint, or library-backed types for monetary amounts based on precision needs.
- Module Variant Imports - Provides separate import paths for number and bigint backends with compile-time type selection.
- Currency Scale Configurations - Overrides default currency exponent scale to handle currencies with no minor units or non-decimal subdivisions.
- Bigint Monetary Amounts - Uses bigint for monetary amounts to safely represent arbitrarily large values beyond number limits.
- Custom Calculator Backends - Accepts custom calculator objects to support third-party arithmetic libraries for arbitrary precision.
- Customizable Monetary Formatters - Formats monetary values as strings with optional custom transformer functions.
- Locale-Aware Value Formatting - Provides locale-aware formatting of monetary values with configurable decimal separators.
