decimal.js-light

What is decimal.js-light?

The decimal.js-light npm package is a library for arbitrary-precision decimal arithmetic. It allows for high-precision arithmetic operations on decimal numbers, which can be crucial in financial calculations, scientific computation, and any other domain where the precision of floating-point arithmetic is insufficient.

What are decimal.js-light's main functionalities?

Arithmetic Operations

Perform precise arithmetic operations such as addition, subtraction, multiplication, and division.

"use strict";
const Decimal = require('decimal.js-light');
let result = new Decimal('0.1').plus('0.2');
console.log(result.toString()); // '0.3'

Chaining Operations

Allows chaining of arithmetic operations for more complex calculations.

"use strict";
const Decimal = require('decimal.js-light');
let result = new Decimal('0.1').plus('0.2').minus('0.1').times('2').div('0.2');
console.log(result.toString()); // '2'

Comparison

Compare decimal numbers to determine the relative order or equality.

"use strict";
const Decimal = require('decimal.js-light');
let a = new Decimal('0.1');
let b = new Decimal('0.2');
console.log(a.lessThan(b)); // true

Rounding

Round decimal numbers to a specified number of decimal places.

"use strict";
const Decimal = require('decimal.js-light');
let result = new Decimal('0.12345').toDP(3);
console.log(result.toString()); // '0.123'

Other packages similar to decimal.js-light

bignumber.js

bignumber.js is another arbitrary-precision decimal and non-decimal arithmetic library with similar functionality. It offers more features and is more widely used than decimal.js-light, but it is also larger in size, which might be a consideration for projects where size is a constraint.

big.js

big.js is a small, fast JavaScript library for arbitrary-precision arithmetic with decimals. It is similar to decimal.js-light in terms of size and performance but has a different API and slightly different feature set.

mathjs

mathjs is an extensive math library for JavaScript and Node.js, which includes arbitrary-precision arithmetic as well as a wide range of other mathematical functions and data types. It is much larger and more comprehensive than decimal.js-light, which focuses solely on decimal arithmetic.

README

The light version of decimal.js, an arbitrary-precision Decimal type for JavaScript.

This library is the newest of the family of libraries: bignumber.js, big.js, decimal.js and decimal.js-light.
The API is more or less a subset of the API of decimal.js.

Differences between this library and decimal.js

Size of decimal.js minified: 32.1 KB.
Size of decimal.js-light minified: 12.7 KB.

This library does not include NaN, Infinity or -0 as legitimate values, or work with values in other bases.

Here, the Decimal.round property is just the default rounding mode for toDecimalPlaces, toExponential, toFixed, toPrecision and toSignificantDigits. It does not apply to arithmetic operations, which are simply truncated at the required precision.

If rounding is required just apply it explicitly, for example

x = new Decimal(2);
y = new Decimal(3);

// decimal.js
x.dividedBy(y).toString();                       // '0.66666666666666666667'

// decimal.js-light
x.dividedBy(y).toString();                       // '0.66666666666666666666'
x.dividedBy(y).toDecimalPlaces(19).toString();   // '0.6666666666666666667'

The naturalExponential, naturalLogarithm, logarithm, and toPower methods in this library have by default a limited precision of around 100 digits. This limit can be increased at runtime using the LN10 (the natural logarithm of ten) configuration object property.

For example, if a maximum precision of 400 digits is required for these operations use

// 415 digits
Decimal.set({
  LN10: '2.302585092994045684017991454684364207601101488628772976033327900967572609677352480235997205089598298341967784042286248633409525465082806756666287369098781689482907208325554680843799894826233198528393505308965377732628846163366222287698219886746543667474404243274365155048934314939391479619404400222105101714174800368808401264708068556774321622835522011480466371565912137345074785694768346361679210180644507064800027'
});

Also, in this library the e property of a Decimal is the base 10000000 exponent, not the base 10 exponent as in decimal.js.
Use the exponent method to get the base 10 exponent.

Quickstart

Browser:

<script src='path/to/decimal.js-light'></script>

Node package manager:

$ npm install --save decimal.js-light

// 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
});

phi = new Decimal('1.61803398874989484820458683436563811772030917980576');

phi.toFixed(10);    // '1.6180339887'

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

See the documentation for further information.

TypeScript type declaration file contributed by TANAKA Koichi.