{"id":10724,"library":"decimal.js","title":"Arbitrary-precision Decimal Arithmetic","description":"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.","status":"active","version":"10.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/MikeMcl/decimal.js","tags":["javascript","arbitrary","precision","arithmetic","big","number","decimal","float","biginteger","typescript"],"install":[{"cmd":"npm install decimal.js","lang":"bash","label":"npm"},{"cmd":"yarn add decimal.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add decimal.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary way to import the Decimal constructor in ESM. It is the default export.","wrong":"const Decimal = require('decimal.js').Decimal;","symbol":"Decimal","correct":"import Decimal from 'decimal.js';"},{"note":"CommonJS import pattern for Node.js. The module's default export is the Decimal constructor.","wrong":"import Decimal from 'decimal.js';","symbol":"Decimal","correct":"const Decimal = require('decimal.js');"},{"note":"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.","wrong":"import * as Decimal from 'decimal.js';","symbol":"Decimal","correct":"import { Decimal } from 'decimal.js';"}],"quickstart":{"code":"import Decimal from 'decimal.js';\n\n// Initialize Decimal instances\nconst x = new Decimal(123.4567);\nconst y = new Decimal('123456.7e-3');\nconst z = new Decimal(x);\n\nconsole.log(`x: ${x}`);\nconsole.log(`y: ${y}`);\nconsole.log(`z: ${z}`);\nconsole.log(`x equals y: ${x.equals(y)}`); // true\nconsole.log(`y equals z: ${y.equals(z)}`); // true\n\n// Demonstrate precision loss with native JavaScript Number literals\nconsole.log('\\nDemonstrating native Number precision pitfalls:');\nconst lossyNumber = new Decimal(1.0000000000000001);\nconsole.log(`new Decimal(1.0000000000000001): ${lossyNumber}`); // Expected '1' (due to JS Number precision)\nconst largeNumberLoss = new Decimal(99999999999999999999);\nconsole.log(`new Decimal(99999999999999999999): ${largeNumberLoss}`); // Expected '100000000000000000000'\n\n// Arithmetic precision loss\nconst nativeSum = 0.7 + 0.1;\nconst decimalSum = new Decimal(0.7).plus(new Decimal(0.1));\nconsole.log(`0.7 + 0.1 (native): ${nativeSum}`); // 0.7999999999999999\nconsole.log(`new Decimal(0.7).plus(new Decimal(0.1)): ${decimalSum}`); // 0.8","lang":"typescript","description":"Illustrates initializing Decimal instances from various types and highlights common precision pitfalls with native JavaScript numbers versus Decimal's exact arithmetic."},"warnings":[{"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)`.","message":"Passing 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'))`.","message":"Arithmetic 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Decimal.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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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');`.","cause":"Attempting to use `Decimal` without the `new` keyword or an incorrect CommonJS import when the module's default export is the constructor.","error":"TypeError: Decimal is not a constructor"},{"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.","cause":"Input numbers or intermediate steps are still being processed as native JavaScript Numbers before being converted to Decimal instances, introducing imprecision.","error":"Calculations result in unexpected floating-point inaccuracies despite using decimal.js."}],"ecosystem":"npm"}