📖 These are the docs for an older version. View the latest BigDecimal.js documentation →
bigdecimal.js
    Preparing search index...

    bigdecimal.js

    BigDecimal.js

    NPM Version NPM Downloads codecov

    BigInt based BigDecimal implementation for Node.js 10.4 and above, and for browsers that support native BigInt (Chrome 67+, Firefox 68+, Safari 14+). This implementation is inspired from java BigDecimal class. This implementation is faster than popular big decimal libraries for most operations. See benchmarks results part below for comparison of each operation.

    • Faster than other BigDecimal libraries because of native BigInt
    • Simple API that is almost same with Java's BigDecimal
    • No dependencies
    • Well tested
    • Includes type definition file
    • This library's minified version is about 5 times larger than big.js's minified version. So the library is not small.
    npm install bigdecimal.js
    • The example usage is given below:
    // Single unified constructor for multiple values
    const { Big } = require('bigdecimal.js');

    // Construct from a string and clone it
    const x = Big('1.1111111111111111111111');
    const y = new Big(x); // you can also use 'new'

    const z = x.add(y);
    console.log(z.toString()); // 2.2222222222222222222222

    // You can also construct from a number or BigInt:
    const u = Big(1.1);
    const v = Big(2n);

    console.log(u.toString()); // 1.1
    console.log(v.toString()); // 2

    You can use MathContext to set precision and rounding mode for a specific operation:

    const { Big, MC, RoundingMode } = require('bigdecimal.js');

    const x = Big('1');
    const y = Big('3');

    // MC is MathContext constructor that can be used with or without `new`
    const res1 = x.divideWithMathContext(y, MC(3)); 
    console.log(res1.toString()); // 0.333

    const res2 = x.divideWithMathContext(y, new MC(3, RoundingMode.UP));
    console.log(res2.toString()); // 0.334

    try {
        x.divide(y);
        // throws since full precision is requested but it is not possible
    } catch (e) {
        console.log(e); // RangeError: Non-terminating decimal expansion; no exact representable decimal result.
    }

    Besides the Java-style toString / toEngineeringString / toPlainString, there are JS-convention formatting methods. All rounding defaults to RoundingMode.HALF_UP and takes an optional RoundingMode argument:

    const { Big } = require('bigdecimal.js');
    const x = Big('1234.56789');

    x.toFixed(2);        // "1234.57"   — exactly N decimals, never exponential
    x.toExponential(2);  // "1.23e+3"   — JS exponential notation
    x.toPrecision(3);    // "1.23e+3"   — N significant digits (fixed or exponential)

    // Locale-aware formatting via the built-in Intl.NumberFormat (no dependency):
    x.toFormat('en-US');                                        // "1,234.56789"
    x.toFormat('de-DE');                                        // "1.234,56789"
    Big('1234.5').toFormat('en-US', { style: 'currency', currency: 'USD' }); // "$1,234.50"

    // Value coercion (Symbol.toPrimitive): string contexts are exact, numeric ones are lossy
    `${x}`;   // "1234.56789"  (exact — same as toString())
    +x;       // 1234.56789    (lossy numberValue(), like other JS number coercion)

    toFormat passes the value to Intl.NumberFormat as a string, so integer precision is preserved; full-precision string formatting needs Node ≥ 20 or a current browser (older engines fall back to double precision past 15–17 significant digits). By default it shows every decimal the value has (Intl otherwise caps at 3), except for currency/percent styles where Intl's own rules apply. Anything you pass in options overrides these defaults.

    Migrating from decimal.js / bignumber.js / big.js

    The API mirrors Java's BigDecimal, so method names differ from other JS decimal libraries. Common equivalents:

    decimal.js / bignumber.js bigdecimal.js
    new Decimal('1.5') / BigNumber('1.5') Big('1.5') (with or without new)
    x.plus(y) / x.minus(y) x.add(y) / x.subtract(y)
    x.times(y) / x.div(y) x.multiply(y) / x.divide(y, scale?, roundingMode?)
    x.mod(y) / x.pow(n) x.remainder(y) / x.pow(n)
    x.abs() / x.neg() / x.sqrt() x.abs() / x.negate() / x.sqrt(mc)
    x.cmp(y) / x.eq(y) x.compareTo(y) / x.equals(y)
    x.gt(y) / x.gte(y) / x.lt(y) / x.lte(y) same names (gt/gte/lt/lte)
    x.isZero() / x.isNeg() / x.isPos() x.isZero() / x.isNegative() / x.isPositive()
    x.toNumber() x.numberValue()
    x.toFixed(n) / x.toExponential(n) / x.toPrecision(n) same names
    x.toFormat(...) (bignumber.js) x.toFormat(locales, options) (Intl-based)
    Decimal.ROUND_HALF_UP RoundingMode.HALF_UP

    Two differences to note: there is no global config — precision and rounding are set per operation via MathContext (MC) and RoundingMode — and divide throws a RangeError on a non-terminating result unless you pass a scale or a MathContext (use divideWithMathContext for the latter).

    JSON is the weak spot of every decimal library: JSON.parse rounds numbers to IEEE-754 doubles before your code runs, and JSON.stringify turns a BigDecimal into a string (via toJSON()), which changes the wire type for consumers expecting a JSON number (Java's Jackson serializes BigDecimal as a bare number by default, OpenAPI number schemas, etc.).

    Modern engines (Node.js ≥ 21, Chrome ≥ 114) fix both directions:

    const { Big, BigDecimal } = require('bigdecimal.js');

    // Parse losslessly: context.source is the exact number text from the input.
    const order = JSON.parse('{"price":0.1000000000000000000001}', (key, value, context) =>
        typeof value === 'number' && context ? Big(context.source) : value);
    order.price.toString(); // '0.1000000000000000000001' — nothing rounded

    // Stringify as a bare JSON number with full precision. Must be a regular
    // function reading this[key]: JSON.stringify calls toJSON() *before* the
    // replacer, so `value` is already a string at this point.
    function decimalReplacer(key, value) {
        return this[key] instanceof BigDecimal ? JSON.rawJSON(this[key].toString()) : value;
    }
    JSON.stringify({ price: Big('0.10') }, decimalReplacer); // '{"price":0.10}'

    toString() output is always valid JSON number syntax, so the replacer is safe for every value. In real payloads, scope the reviver to known keys — the one above converts every number in the document. Feature-detect with typeof JSON.rawJSON === 'function'; on older engines the default behavior (serialize as a JSON string) still round-trips exactly, just as a string.

    The library is pure JavaScript with zero runtime dependencies and uses native BigInt, so it runs in the browser with no polyfills. The only requirement is a browser with BigInt support (Chrome 67+, Firefox 68+, Safari 14+).

    With a bundler (Vite, webpack, esbuild, Rollup) just import it as usual:

    import { Big } from 'bigdecimal.js';

    Without a bundler, import the ESM build straight from a CDN:

    <script type="module">
      import { Big } from 'https://esm.sh/bigdecimal.js';
      console.log(Big('0.1').add(Big('0.2')).toString()); // 0.3
    </script>

    Or use the minified UMD bundle, which exposes a global BigDecimalJS:

    <script src="https://cdn.jsdelivr.net/npm/bigdecimal.js/lib/bigdecimal.umd.min.js"></script>
    <script>
      const { Big } = BigDecimalJS;
      console.log(Big('0.1').add(Big('0.2')).toString()); // 0.3
    </script>
    • Install dependencies: npm i
    • Compile: npm run compile
    • Run tests: npm test

    There is a benchmark suite that compares

    To run the benchmark run npm install and then npm run benchmark.

    Benchmarked against big.js, bigdecimal (GWT-based), bignumber.js and decimal.js.

    • Test Machine:

      • Apple M1
      • 8 GB Ram
      • macOS 26.3
      • Node.js 24

    • Update Date: July 10th 2026

    • Library versions used:

      • big.js 7.0.1
      • (this library) bigdecimal.js 1.5.1
      • bigdecimal 0.6.1
      • bignumber.js: 11.1.5
      • decimal.js: 10.6.0

    • Each operation is run with a fixed set of decimal numbers composed of both simple and complex numbers.

    • Micro benchmark framework used is benchmark. Check out benchmarks folder for source code of benchmarks.

    • Numbers are operations per second (higher is better). In each row the fastest library is bold, and the Fastest column names the winner with how many times faster it is than the runner-up. A - means the library has no equivalent operation.

    Operation Bigdecimal.js Big.js BigNumber.js decimal.js GWTBased Fastest
    Constructor 93,779 41,763 46,527 47,096 3,488 🏆 Bigdecimal.js (2.0×)
    Add 442,537 119,788 260,192 101,015 895 🏆 Bigdecimal.js (1.7×)
    Subtract 408,086 102,520 238,409 103,944 861 🏆 Bigdecimal.js (1.7×)
    Multiply 848,781 33,785 91,903 81,919 3,162 🏆 Bigdecimal.js (9.2×)
    Divide 39,520 1,090 12,695 14,965 807 🏆 Bigdecimal.js (2.6×)
    DivideToIntegralValue 16,051 - 23,701 47,231 1,453 🏆 decimal.js (2.0×)
    Remainder 15,789 7,393 19,041 30,891 2,279 🏆 decimal.js (1.6×)
    Positive pow 31,771 26 118 3,611 7 🏆 Bigdecimal.js (8.8×)
    Negative pow 10,142 22 113 2,019 334 🏆 Bigdecimal.js (5.0×)
    Sqrt 4,960 48 1,162 1,584 - 🏆 Bigdecimal.js (3.1×)
    Abs 3,955,846 1,808,679 982,481 351,996 17,393 🏆 Bigdecimal.js (2.2×)
    Negate 3,280,750 1,778,738 954,034 361,869 8,990 🏆 Bigdecimal.js (1.8×)
    Round 190,517 669,441 - 186,759 5,330 🏆 Big.js (3.5×)
    SetScale 304,017 682,850 219,248 175,313 1,913 🏆 Big.js (2.2×)
    Compare 2,065,774 1,243,907 942,303 420,017 1,157,599 🏆 Bigdecimal.js (1.7×)
    Equals 8,732,574 1,232,550 926,046 417,482 1,619,827 🏆 Bigdecimal.js (5.4×)
    Min 1,750,053 - 462,664 143,793 37,196 🏆 Bigdecimal.js (3.8×)
    Max 1,787,793 - 465,469 145,346 31,895 🏆 Bigdecimal.js (3.8×)
    MovePointLeft 2,549,444 - - - 2,168 🏆 Bigdecimal.js (1176.1×)
    MovePointRight 1,242,843 - - - 2,075 🏆 Bigdecimal.js (599.0×)
    ScaleByPowerOfTen 9,367,076 - 65,704 - 9,073 🏆 Bigdecimal.js (142.6×)
    StripTrailingZeros 495,846 - - - 7,470 🏆 Bigdecimal.js (66.4×)
    Ulp 10,790,507 - - - 55,046 🏆 Bigdecimal.js (196.0×)
    UnscaledValue 3,224,447 - - - 11,115 🏆 Bigdecimal.js (290.1×)
    ToString 10,721,214 118,681 253,251 254,004 1,238,199 🏆 Bigdecimal.js (8.7×)
    NumberValue 759,586 105,392 233,353 119,015 289,260 🏆 Bigdecimal.js (2.6×)
    ToBigInt 247,680 - - - 2,388 🏆 Bigdecimal.js (103.7×)

    bigdecimal.js is the fastest in 23 of 27 operations. It trails decimal.js on remainder/divideToIntegralValue, and big.js on round/setScale.

    The table above is measured on Node.js, i.e. V8. Because bigdecimal.js builds on native BigInt, relative results depend on the engine's BigInt implementation. Running the same suite on the same machine under Bun 1.3.14 (JavaScriptCore, the engine of Safari), bigdecimal.js is the fastest in 22 of 27 operations, and its absolute throughput is often higher than on V8 — for example ToString reaches 18.3M ops/sec (10.7M on V8), NumberValue 5.7M (760K on V8) and Divide 50K (40K on V8).

    Operations where the outcome differs on JavaScriptCore:

    Operation Node.js (V8) Bun (JavaScriptCore)
    Constructor 🏆 Bigdecimal.js (2.0×) 🏆 Big.js (1.0×) — JavaScriptCore parses decimal strings into BigInt more slowly than V8
    Round 🏆 Big.js (3.5×) 🏆 decimal.js (2.0×)
    SetScale 🏆 Big.js (2.2×) 🏆 decimal.js (1.1×), Bigdecimal.js a close second
    DivideToIntegralValue 🏆 decimal.js (2.0×) 🏆 decimal.js (1.4×)
    Remainder 🏆 decimal.js (1.6×) 🏆 decimal.js (1.2×)

    To reproduce, run the suite with Bun: bun benchmarks/index.js.

    Settings
    Member Visibility

    On This Page
    BigDecimal.js