{"id":10723,"library":"decimal.js-light","title":"Arbitrary-precision Decimal (Light)","description":"decimal.js-light is an arbitrary-precision Decimal type for JavaScript, currently at stable version 2.5.1. It is a 'light' version of the more comprehensive `decimal.js` library, specifically optimized for a smaller footprint (12.7 KB minified compared to `decimal.js`'s 32.1 KB). This reduction in size comes with specific tradeoffs: it does not support `NaN`, `Infinity`, or `-0` as legitimate values, nor does it handle numbers in bases other than 10. A key difference in behavior is its approach to rounding; arithmetic operations such as division are truncated at the required precision by default, unlike `decimal.js` where a global rounding mode can apply to such operations. Explicit rounding methods like `toDecimalPlaces` must be called to achieve rounded results. Furthermore, transcendental functions like `naturalExponential`, `naturalLogarithm`, `logarithm`, and `toPower` have a default precision limited to about 100 digits, which can be extended by configuring the `LN10` property. The library also distinguishes its internal `e` property (base 10000000 exponent) from the `exponent()` method (base 10 exponent). The project appears to be actively maintained, with regular updates. It provides TypeScript type declarations.","status":"active","version":"2.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/MikeMcl/decimal.js-light","tags":["javascript","arbitrary","precision","arithmetic","big","number","decimal","float","biginteger","typescript"],"install":[{"cmd":"npm install decimal.js-light","lang":"bash","label":"npm"},{"cmd":"yarn add decimal.js-light","lang":"bash","label":"yarn"},{"cmd":"pnpm add decimal.js-light","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Standard CommonJS import for Node.js environments.","symbol":"Decimal","correct":"var Decimal = require('decimal.js-light');"},{"note":"Common practice for importing CommonJS default exports in ESM-compatible environments (e.g., with bundlers or TypeScript). The library's main entry point is CommonJS, exposing a default export. Direct named imports are not supported.","wrong":"import { Decimal } from 'decimal.js-light';","symbol":"Decimal","correct":"import Decimal from 'decimal.js-light';"},{"note":"TypeScript type import for the Decimal class, compatible with the library's provided type declarations.","symbol":"Decimal","correct":"import type { Decimal } from 'decimal.js-light';"}],"quickstart":{"code":"// Node.js\nvar Decimal = require('decimal.js-light');\n\n// Adjust the global configuration if required (these are the defaults)\nDecimal.set({\n  precision: 20,\n  rounding: Decimal.ROUND_HALF_UP,\n  toExpNeg: -7,\n  toExpPos: 21\n});\n\nconst phi = new Decimal('1.61803398874989484820458683436563811772030917980576');\n\nconsole.log(phi.toFixed(10));    // Outputs: '1.6180339887'\n\nconsole.log(phi.times(2).minus(1).toPower(2).plus('1e-19').equals(5));    // Outputs: true","lang":"typescript","description":"Initializes the Decimal library with default configuration and performs basic arithmetic operations with arbitrary precision, demonstrating common usage."},"warnings":[{"fix":"Ensure all inputs are valid finite base-10 numbers. If these features are required, consider using the full `decimal.js` library.","message":"Unlike `decimal.js`, this library does not support `NaN`, `Infinity`, `-0`, or operations with values in bases other than 10. Attempting to use these can lead to unexpected behavior or errors.","severity":"breaking","affected_versions":"*"},{"fix":"Explicitly call rounding methods after arithmetic operations, e.g., `x.dividedBy(y).toDecimalPlaces(N)`.","message":"Arithmetic operations (e.g., `dividedBy`) are truncated by default at the required precision. Explicit rounding via `toDecimalPlaces`, `toExponential`, `toFixed`, `toPrecision`, or `toSignificantDigits` is required to achieve rounded results, unlike `decimal.js` where `Decimal.round` can apply to arithmetic.","severity":"gotcha","affected_versions":"*"},{"fix":"Increase the maximum precision at runtime by configuring the `LN10` property via `Decimal.set({ LN10: '...' })`. A pre-calculated `LN10` string with sufficient digits for the desired precision must be provided.","message":"Methods like `naturalExponential`, `naturalLogarithm`, `logarithm`, and `toPower` have a default precision limit of approximately 100 digits. This can lead to unexpected loss of precision for high-precision calculations.","severity":"gotcha","affected_versions":"*"},{"fix":"Always use `myDecimal.exponent()` to retrieve the base 10 exponent. Avoid directly accessing `myDecimal.e` unless working with the internal base 10000000 representation.","message":"The `e` property of a `Decimal` instance represents the base 10000000 exponent, not the base 10 exponent as in `decimal.js`. To get the base 10 exponent, use the `exponent()` method.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For Node.js CommonJS, use `const Decimal = require('decimal.js-light');`. For environments supporting ESM with bundlers (like Webpack or Rollup), use `import Decimal from 'decimal.js-light';`.","cause":"Attempting to use `Decimal` without properly importing or requiring it, or using an incorrect ESM import syntax for a CommonJS default export.","error":"TypeError: Decimal is not a constructor"},{"fix":"Ensure all input values are finite base-10 numbers. If `NaN`, `Infinity`, or `-0` support is required, consider using the full `decimal.js` library.","cause":"Passing `NaN`, `Infinity`, or `-0` as a value to the Decimal constructor or any method. `decimal.js-light` explicitly disallows these values.","error":"RangeError: Argument 'NaN' must be a valid number"},{"fix":"Apply explicit rounding after arithmetic operations using methods like `toDecimalPlaces()`. For example: `x.dividedBy(y).toDecimalPlaces(19).toString()`.","cause":"Arithmetic operations like `dividedBy` are truncated, not rounded, by default in `decimal.js-light`.","error":"Unexpected truncated result from arithmetic operation (e.g., division)"}],"ecosystem":"npm"}