bignumber.js

You can minify the browser/global bundle using terser. First, install terser globally, then run the minification command against the distribution file.

npm install -g terser
terser dist/bignumber.js -c -m -o dist/bignumber.min.js

You can load bignumber.js in a browser using a standard <script> tag or as an ES module via a CDN.

Standard Script Tag:

<script src='https://cdn.jsdelivr.net/npm/bignumber.js@latest/dist/bignumber.min.js'></script>

ES Module:

<script type="module">
import BigNumber from 'https://cdn.jsdelivr.net/npm/bignumber.js@latest/+esm';
// ...
</script>

The test suite is located in the test/methods directory. Before running tests, you must build the CommonJS distributable. You can run all tests using npm test or by calling node test/test. To test a specific method, run its corresponding script directly, for example: node test/methods/toFraction. For browser-based testing, open test/test.html in a web browser.

npm run build
npm test
# or: node test/test

# To test a single method:
node test/methods/toFraction

The bigtime-OOM.js tool is a variation of bigtime.js designed for more granular timing. Unlike bigtime.js, it provides separate timings for object creation versus method execution.

Warning: This tool creates objects in a single batch and is prone to running out of memory (OOM) if the number of iterations is very high (e.g., > 500,000) or the number of random digits is large (e.g., > 40).

Depending on your module system, import BigNumber as follows:

CommonJS:

const BigNumber = require('bignumber.js');

ES Modules:

import BigNumber from 'bignumber.js';
// or
import { BigNumber } from 'bignumber.js';

Use the bigtime.js command-line application to compare the performance of bignumber.js methods against JavaScript translations of Java's BigDecimal (GWT or ICU4J versions). This tool runs a specified number of iterations using random operands and verifies that the results match.

To run a comparison, use the following syntax:

node bigtime <method> <iterations> <digits>

Example: To time 10,000 calls to the plus method using operands with up to 40 random digits:

node bigtime plus 10000 40

To use bignumber.js in a Node.js project, install it using npm:

npm install bignumber.js

In Deno, import the ES module directly from a URL. It is recommended to use @deno-types to provide type definitions.

// @deno-types="https://raw.githubusercontent.com/MikeMcl/bignumber.js/main/dist/bignumber.d.mts"
import BigNumber from 'https://raw.githubusercontent.com/MikeMcl/bignumber.js/main/dist/bignumber.mjs';

Use BigNumber.set() to configure global settings such as DECIMAL_PLACES and ROUNDING_MODE. These settings affect the precision of operations like division, square root, and base conversion.

BigNumber.set({ DECIMAL_PLACES: 10, ROUNDING_MODE: 4 });

let x = new BigNumber(2);
let y = new BigNumber(3);
let z = x.dividedBy(y); // "0.6666666667"

For advanced usage, you can create a new constructor with its own independent configuration using BigNumber.clone(). This allows different parts of your application to use different precision settings.

BigNumber.set({ DECIMAL_PLACES: 10 });
const BN = BigNumber.clone({ DECIMAL_PLACES: 5 });

let x = new BigNumber(1);
let y = new BN(1);

x.div(3); // '0.3333333333'
y.div(3); // '0.33333'

BigNumber.set({ DECIMAL_PLACES: 10 })

// Create another BigNumber constructor, optionally passing in a configuration object
BN = BigNumber.clone({ DECIMAL_PLACES: 5 })

x = new BigNumber(1)
y = new BN(1)

x.div(3)                            // '0.3333333333'
y.div(3)                            // '0.33333'

BigNumber instances are immutable; methods return a new BigNumber rather than modifying the original. Methods can be chained for complex calculations.

Common Arithmetic Methods:

• .plus(n) / .add(n)
• .minus(n) / .sub(n)
• .times(n) / .mul(n)
• .dividedBy(n) / .div(n)
• .exponentiatedBy(n) / .pow(n)
• .squareRoot() / .sqrt()
• .modulo(n) / .mod(n)

Example:

x.dividedBy(y).plus(z).times(9)