BigInteger.js: Arbitrary-Length Integers

1.6.52 · active · verified Sun Apr 19

BigInteger.js is a robust JavaScript library for performing arithmetic operations on integers of unlimited size, circumventing JavaScript's standard number precision limitations. The current stable version is 1.6.52. While releases are not on a fixed schedule, the project is actively maintained, with recent updates addressing various fixes and TypeScript definitions. A key differentiator and recent major change is its evolution into a polyfill for the native JavaScript `BigInt` feature (introduced to TC39 in 2018). If the execution environment supports native `BigInt`, this library will transparently wrap the native implementation, otherwise, it provides its own software-based arbitrary-length integer solution. This makes it a highly compatible choice for environments with varying `BigInt` support.

Common errors

```
Error: Invalid integer
```
cause Attempting to create a `bigInt` from a string or number that cannot be parsed as a valid integer, or providing a base that is not a valid `bigInt`.

fix Ensure that string inputs only contain valid digits for the specified base and that the base parameter itself is a valid integer. For example, `bigInt('hello')` will throw this error, as will `bigInt('10', 0)`.
```
TypeError: Cannot mix BigInt and other types, use explicit conversions
```
cause This error occurs when trying to perform operations between a native `BigInt` (which `big-integer` might return as a polyfill) and a standard JavaScript `Number` or other type, without explicit conversion.

fix When `big-integer` uses native `BigInt` as a polyfill, all operands in an arithmetic operation must be `BigInt`s. Convert standard numbers to `BigInt` using `BigInt(number)` or `bigInt(number)` before operations, e.g., `bigInt('100').plus(bigInt(5))` instead of `bigInt('100').plus(5)`.

Warnings

breaking Starting with v1.6.37, `big-integer` acts as a polyfill for the native JavaScript `BigInt`. If the environment supports native `BigInt`, the library internally uses and often returns native `BigInt` instances. This can lead to unexpected behavior when using `instanceof` checks (e.g., `value instanceof bigInt.BigInteger`) or strict type comparisons, as the returned objects might be native `BigInt` primitives.
Fix: Prefer using `bigInt.isInstance(value)` for checking if a value is a big-integer managed type. Avoid `instanceof` or direct type checking if cross-compatibility with native `BigInt` is required.
gotcha JavaScript numbers have a maximum safe integer limit (`Number.MAX_SAFE_INTEGER`). Passing numbers larger than `9007199254740992` or smaller than `-9007199254740992` directly to `bigInt()` will result in loss of precision, as JavaScript itself cannot precisely represent these values.
Fix: Always pass large integer values as strings to the `bigInt()` factory function to ensure exact representation and avoid precision loss. For example, `bigInt('9007199999999999')` instead of `bigInt(9007199999999999)`.
deprecated With the widespread adoption of native `BigInt` in modern JavaScript environments, for new projects targeting environments with `BigInt` support, it is generally recommended to use native `BigInt` directly rather than relying on polyfill libraries like `big-integer` for simple arithmetic.
Fix: Evaluate your project's target environment support. If native `BigInt` is available, consider using `n` suffix for literals (e.g., `123n`) and native operations. If broader compatibility is needed or older environments must be supported, `big-integer` remains a viable polyfill.

Install

npm install big-integer npm
yarn add big-integer yarn
pnpm add big-integer pnpm

Imports

bigInt
wrong:
```
import { bigInt } from 'big-integer';
```
correct:
```
import bigInt from 'big-integer';
```
The primary `bigInt` factory function is the default export of the package for ESM. Named import `{ bigInt }` is incorrect.
bigInt (CommonJS)
wrong:
```
const { bigInt } = require('big-integer');
```
correct:
```
const bigInt = require('big-integer');
```
In CommonJS, the `bigInt` factory function is the default export. Destructuring `bigInt` from `require('big-integer')` is incorrect.
BigInteger (Type)
wrong:
```
import { BigInteger } from 'big-integer';
```
correct:
```
import type { BigInteger } from 'big-integer';
```
Since v1.6.22, TypeScript definitions are included. Use `import type` for the `BigInteger` interface if you are only importing the type.

Quickstart

This quickstart demonstrates how to initialize `bigInt` values from numbers and strings, perform arithmetic operations like factorial calculation, and use pre-defined constants, highlighting its use in handling large integer arithmetic beyond standard JavaScript number limits.

import bigInt from 'big-integer';

function calculateFactorial(n: number): bigInt.BigInteger {
  let result = bigInt.one;
  for (let i = 2; i <= n; i++) {
    result = result.times(i);
  }
  return result;
}

// Calculate factorial of a moderately large number
const numberToFactorial = 50;
const factorialResult = calculateFactorial(numberToFactorial);
console.log(`Factorial of ${numberToFactorial} is: ${factorialResult.toString()}`);

// Demonstrating operations with large string inputs to avoid JS number precision limits
const largeA = bigInt('123456789012345678901234567890');
const largeB = bigInt('987654321098765432109876543210');
const sum = largeA.plus(largeB);
console.log(`Sum of two large numbers: ${sum.toString()}`);

// Accessing pre-stored constants
console.log(`Zero: ${bigInt.zero.toString()}`);
console.log(`One: ${bigInt.one.toString()}`);
console.log(`Minus One: ${bigInt.minusOne.toString()}`);

// Note: The actual type of `factorialResult` might be native `BigInt` or `BigInteger` object
// depending on environment support and library's polyfill behavior.

view raw JSON →