Arbitrary-precision Decimal (Light)

2.5.1 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: Decimal is not a constructor
```
cause Attempting to use `Decimal` without properly importing or requiring it, or using an incorrect ESM import syntax for a CommonJS default export.

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';`.
```
RangeError: Argument 'NaN' must be a valid number
```
cause Passing `NaN`, `Infinity`, or `-0` as a value to the Decimal constructor or any method. `decimal.js-light` explicitly disallows these values.

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.
```
Unexpected truncated result from arithmetic operation (e.g., division)
```
cause Arithmetic operations like `dividedBy` are truncated, not rounded, by default in `decimal.js-light`.

fix Apply explicit rounding after arithmetic operations using methods like `toDecimalPlaces()`. For example: `x.dividedBy(y).toDecimalPlaces(19).toString()`.

Warnings

breaking 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.
Fix: Ensure all inputs are valid finite base-10 numbers. If these features are required, consider using the full `decimal.js` library.
gotcha 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.
Fix: Explicitly call rounding methods after arithmetic operations, e.g., `x.dividedBy(y).toDecimalPlaces(N)`.
gotcha 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.
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.
gotcha 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.
Fix: Always use `myDecimal.exponent()` to retrieve the base 10 exponent. Avoid directly accessing `myDecimal.e` unless working with the internal base 10000000 representation.

Install

npm install decimal.js-light npm
yarn add decimal.js-light yarn
pnpm add decimal.js-light pnpm

Imports

Decimal
```
var Decimal = require('decimal.js-light');
```
Standard CommonJS import for Node.js environments.
Decimal
wrong:
```
import { Decimal } from 'decimal.js-light';
```
correct:
```
import Decimal from 'decimal.js-light';
```
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.
Decimal
```
import type { Decimal } from 'decimal.js-light';
```
TypeScript type import for the Decimal class, compatible with the library's provided type declarations.

Quickstart

Initializes the Decimal library with default configuration and performs basic arithmetic operations with arbitrary precision, demonstrating common usage.

// Node.js
var Decimal = require('decimal.js-light');

// Adjust the global configuration if required (these are the defaults)
Decimal.set({
  precision: 20,
  rounding: Decimal.ROUND_HALF_UP,
  toExpNeg: -7,
  toExpPos: 21
});

const phi = new Decimal('1.61803398874989484820458683436563811772030917980576');

console.log(phi.toFixed(10));    // Outputs: '1.6180339887'

console.log(phi.times(2).minus(1).toPower(2).plus('1e-19').equals(5));    // Outputs: true

view raw JSON →