decimal.js

library10.6.0jsnpmunverified

decimal.js is an arbitrary-precision Decimal type for JavaScript, providing robust arithmetic capabilities for numbers that require exact precision, such as financial calculations. Currently at version 10.6.0, it offers a stable and actively maintained solution. Unlike bignumber.js, decimal.js defines precision in terms of significant digits rather than decimal places, aligning with Python's decimal module. It further distinguishes itself by including comprehensive trigonometric functions and support for non-integer powers, making it a more feature-rich (and larger) library than bignumber.js or big.js. The library has no external dependencies and maintains wide platform compatibility by using only ECMAScript 3 features. It ships with TypeScript declaration files, ensuring type safety for modern JavaScript projects.

serialization payments

npm install decimal.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DECIMAL.JS

decimal.js

serializationjavascriptv10.6.0

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.

Decimal

✓ import Decimal from 'decimal.js';

✗ const Decimal = require('decimal.js').Decimal;

The primary way to import the Decimal constructor in ESM. It is the default export.

Decimal

✓ const Decimal = require('decimal.js');

✗ import Decimal from 'decimal.js';

CommonJS import pattern for Node.js. The module's default export is the Decimal constructor.

Decimal

✓ import { Decimal } from 'decimal.js';

✗ import * as Decimal from 'decimal.js';

Although less common for a library with a direct default export, the package also provides 'Decimal' as a named export, which points to the same constructor. This is explicitly shown in the README as a valid ESM import.

Illustrates initializing Decimal instances from various types and highlights common precision pitfalls with native JavaScript numbers versus Decimal's exact arithmetic.

import Decimal from 'decimal.js'; // Initialize Decimal instances const x = new Decimal(123.4567); const y = new Decimal('123456.7e-3'); const z = new Decimal(x); console.log(`x: ${x}`); console.log(`y: ${y}`); console.log(`z: ${z}`); console.log(`x equals y: ${x.equals(y)}`); // true console.log(`y equals z: ${y.equals(z)}`); // true // Demonstrate precision loss with native JavaScript Number literals console.log('\nDemonstrating native Number precision pitfalls:'); const lossyNumber = new Decimal(1.0000000000000001); console.log(`new Decimal(1.0000000000000001): ${lossyNumber}`); // Expected '1' (due to JS Number precision) const largeNumberLoss = new Decimal(99999999999999999999); console.log(`new Decimal(99999999999999999999): ${largeNumberLoss}`); // Expected '100000000000000000000' // Arithmetic precision loss const nativeSum = 0.7 + 0.1; const decimalSum = new Decimal(0.7).plus(new Decimal(0.1)); console.log(`0.7 + 0.1 (native): ${nativeSum}`); // 0.7999999999999999 console.log(`new Decimal(0.7).plus(new Decimal(0.1)): ${decimalSum}`); // 0.8

Debug

Known issues

gotchaPassing JavaScript Number literals with more than 15 significant digits or outside the safe integer range (Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER) directly to the Decimal constructor can lead to precision loss or incorrect values (e.g., 'Infinity', '0') before decimal.js even processes them, as JavaScript's native Number type cannot accurately represent these values.

fix

Always pass numerical values as strings when they exceed JavaScript's native Number precision or range, especially for financial or scientific calculations. E.g., `new Decimal('1.0000000000000001')` instead of `new Decimal(1.0000000000000001)`.

affects: >=1.0.0

gotchaArithmetic operations performed directly on native JavaScript Numbers (e.g., `0.1 + 0.2`) before passing them to Decimal.js can introduce floating-point inaccuracies. Decimal.js can only correct precision for operations it performs itself.

fix

Ensure all parts of a calculation are handled by Decimal.js instances from the start. Convert all initial numbers to Decimal instances (preferably from strings) before performing any arithmetic operations. E.g., `new Decimal('0.1').plus(new Decimal('0.2'))`.

affects: >=1.0.0

gotchaDecimal.js uses significant digits for precision, which differs from libraries like bignumber.js that use decimal places. This means rounding occurs on all calculations, not just division.

fix

Familiarize yourself with the library's precision settings (e.g., `Decimal.set({ precision: N })`) and rounding modes (`Decimal.set({ rounding: Decimal.ROUND_HALF_UP })`) to ensure calculations meet specific requirements. Understand that intermediate results are rounded according to the global precision setting.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Decimal is not a constructor

Attempting to use `Decimal` without the `new` keyword or an incorrect CommonJS import when the module's default export is the constructor.

fix

Always instantiate `Decimal` with `new`, e.g., `const num = new Decimal('123.45');`. For CommonJS, ensure `const Decimal = require('decimal.js');` and not `const { Decimal } = require('decimal.js');`.

Calculations result in unexpected floating-point inaccuracies despite using decimal.js.

Input numbers or intermediate steps are still being processed as native JavaScript Numbers before being converted to Decimal instances, introducing imprecision.

fix

Convert all numeric inputs to strings before creating Decimal instances, especially for values prone to floating-point issues (e.g., `new Decimal('0.1').plus(new Decimal('0.2'))`). Ensure all arithmetic operations are performed using Decimal methods.

Upgrade

Version history

10.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Perplexity

Resources

githubhttps://github.com/MikeMcl/decimal.js ↗

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

homepagehttps://mikemcl.github.io/decimal.js/ ↗