big-integer

library1.6.52jsnpmunverified

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.

serialization

npm install big-integer

github ↗package ↗

INSTALL

IMPORT

SIG · BIG-INTEGER

big-integer

serializationjavascriptv1.6.52

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bigInt

✓ import bigInt from 'big-integer';

✗ 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)

✓ const bigInt = require('big-integer');

✗ 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)

✓ import type { BigInteger } from 'big-integer';

✗ import { 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.

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.

Debug

Known issues

breakingStarting 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.

affects: >=1.6.37

gotchaJavaScript 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)`.

affects: >=1.0.0

deprecatedWith 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.

affects: >=1.6.37

Errors

Common errors & fixes

Error: Invalid integer

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

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)`.

Upgrade

Version history

1.6.52latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/peterolson/BigInteger.js ↗

packagehttps://www.npmjs.com/package/big-integer ↗