bignum-core

Arbitrary-precision decimal arithmetic for JavaScript.

bignum-core exports a single Decimal constructor. Values are stored as a sign, a base-10 exponent, and a digit array, and every operation is rounded to a configurable number of significant digits.

const Decimal = require('bignum-core');
// import Decimal from 'bignum-core';

new Decimal(0.1).plus(0.2).toString();           // '0.3'
new Decimal('1.23456789e+18').sqrt().toFixed(4); // '1111111106.0556'

Install

npm install bignum-core

Node.js (CommonJS and ESM):

const Decimal = require('bignum-core');
import Decimal from 'bignum-core';
import { Decimal } from 'bignum-core';

Browser:

<script src="path/to/bignum-core.js"></script>
<script type="module">
  import Decimal from './path/to/bignum-core.mjs';
</script>

The ES module bignum-core.mjs is the source. bignum-core.js is the generated UMD build (npm run build). TypeScript definitions ship as bignum-core.d.ts.

Precision vs JavaScript numbers

Pass strings (or other Decimal values) when a number has more than about 15 significant digits. Numeric literals are already rounded by JavaScript before they reach the constructor.

new Decimal(1.0000000000000001);   // '1'
new Decimal('1.0000000000000001'); // '1.0000000000000001'

new Decimal(0.7 + 0.1);            // '0.7999999999999999'
new Decimal('0.7').plus('0.1');    // '0.8'

Binary, octal, and hex strings are accepted with a prefix. Underscores are allowed as digit separators.

new Decimal('0xff.f');             // '255.9375'
new Decimal('0b10101100');         // '172'
new Decimal('2_147_483_647');      // '2147483647'

Arithmetic

Instances are immutable: methods return new Decimals.

const x = new Decimal(0.3);
x.minus(0.1).toString();           // '0.2'
x.toString();                      // '0.3'

x.div(3).plus(1).times(9).floor();

Most methods have a short alias (div / dividedBy, mul / times, sub / minus, add / plus, cmp / comparedTo, …).

x.sqrt().div(y).pow(3).eq(x.squareRoot().dividedBy(y).toPower(3));

Static helpers match the instance methods and several Math functions:

Decimal.sqrt('6.98372465832e+9823');
Decimal.pow(2, 0.0979843);
Decimal.max(1, '1e+30', -4);
Decimal.hypot(3, 4);               // '5'
Decimal.sum(0.1, 0.2, 0.3);        // '0.6'

Formatting:

const n = new Decimal(255.5);
n.toExponential(5);                // '2.55500e+2'
n.toFixed(5);                      // '255.50000'
n.toPrecision(5);                  // '255.50'
n.toFraction(1000);                // ['511', '2']

NaN and Infinity are valid values; use isNaN() and isFinite() instead of the global functions.

Configuration

Results are rounded to Decimal.precision significant digits using Decimal.rounding.

Decimal.set({ precision: 5, rounding: Decimal.ROUND_HALF_UP });
new Decimal(5).div(3);             // '1.6667'

Decimal.clone creates an independent constructor with its own settings:

const Money = Decimal.clone({ precision: 2, rounding: Decimal.ROUND_HALF_EVEN });
new Money(1).div(8);               // '0.12'

| Setting | Default | Meaning | |-------------|---------|---------| | precision | 20 | Significant digits kept on each result | | rounding | 4 | Rounding mode (Decimal.ROUND_HALF_UP) | | toExpNeg | -7 | Exponent at which toString switches to exponential form | | toExpPos | 21 | Exponent at which toString switches to exponential form | | minE | -9e15 | Underflow threshold | | maxE | 9e15 | Overflow threshold | | modulo | 1 | Remainder sign convention (1 matches JavaScript %) | | crypto | false | Use a CSPRNG for Decimal.random when available |

Rounding modes: ROUND_UP (0), ROUND_DOWN (1), ROUND_CEIL (2), ROUND_FLOOR (3), ROUND_HALF_UP (4), ROUND_HALF_DOWN (5), ROUND_HALF_EVEN (6), ROUND_HALF_CEIL (7), ROUND_HALF_FLOOR (8). Decimal.EUCLID (9) is a modulo mode only.

Representation

const x = new Decimal(-12345.67);
x.d;  // [12345, 6700000]  limbs, base 1e7
x.e;  // 4                 base-10 exponent
x.s;  // -1                sign

Treat d, e, and s as read-only.

Method-by-method documentation lives in doc/API.html.

Test

npm test

npm test rebuilds the UMD file, then runs the suite. Individual modules: node test/modules/toFraction. Open test/test.html to run the suite in a browser.

Minify

uglifyjs bignum-core.js --source-map url=bignum-core.min.js.map -c -m -o bignum-core.min.js
terser bignum-core.mjs --source-map url=bignum-core.min.mjs.map -c -m --toplevel -o bignum-core.min.mjs

Licence

MIT. Copyright (c) 2026 artemcheiv.