JSBI: Pure JavaScript BigInt Implementation

4.3.2 · active · verified Sun Apr 19

JSBI (JavaScript BigInt) is a pure-JavaScript implementation of the ECMAScript BigInt proposal, which officially became a part of the JavaScript language in ES2020. The current stable version is 4.3.2. This library serves as a robust polyfill, enabling developers to use arbitrary-precision integers in JavaScript environments that lack native BigInt support, such as older browsers and Node.js versions. A key differentiator of JSBI is its precise adherence to the native BigInt specification's behavior, which facilitates a straightforward, mechanical migration path to native BigInts once they are universally supported, often accomplished through the `babel-plugin-transform-jsbi-to-bigint` plugin. JSBI prioritizes performance, aiming to be highly competitive with native BigInt implementations. Its release cadence is primarily driven by maintenance requirements and alignment with ECMAScript specification updates, rather than frequent feature additions, given its role as a specification-compliant polyfill.

Common errors

```
TypeError: Cannot mix BigInt and other types, use explicit conversions
```
cause Attempting to use native JavaScript operators or functions with a mix of JSBI BigInts and standard JavaScript Numbers or other primitive types.

fix Ensure all operands in an arithmetic or comparison operation are `JSBI` instances and use `JSBI`'s static methods. If interconversion is necessary, use `JSBI.toNumber(jsbiValue)` or `JSBI.BigInt(numberValue)`.
```
console.log(myJsbiValue) outputs '[object Object]' or similar non-numeric representation.
```
cause The default `toString` method of the `JSBI` object returns a generic object string when implicitly converted by `console.log`.

fix Call `String(myJsbiValue)` or `myJsbiValue.toString()` explicitly when logging `JSBI` instances to view their numeric value.

Warnings

breaking JSBI does not polyfill native JavaScript operator overloading for BigInts (e.g., `+`, `-`, `*`, `/`). All operations must be performed using static methods provided by the `JSBI` object (e.g., `JSBI.add(a, b)`, `JSBI.multiply(a, b)`).
Fix: Replace native operators with corresponding `JSBI` static methods for all BigInt arithmetic. For example, `a + b` becomes `JSBI.add(a, b)`.
gotcha Directly logging a `JSBI` instance to the console (e.g., `console.log(myJsbiInstance)`) will often display the internal object representation instead of its numeric value, which can be misleading.
Fix: Always explicitly convert `JSBI` instances to a string representation before logging, using `String(myJsbiInstance)` or `myJsbiInstance.toString()`.
deprecated The primary use case for JSBI (polyfills for BigInt) is diminishing as native BigInt support is now widespread across modern browsers (Chrome 67+, Firefox 68+, Edge 79+, Safari 14+) and Node.js (v10.4+).
Fix: For new projects targeting modern environments, consider using native BigInts directly instead of JSBI. For existing projects, evaluate migration to native BigInts using `babel-plugin-transform-jsbi-to-bigint`.
gotcha Migrating JSBI code to native BigInt syntax requires a specific Babel plugin (`babel-plugin-transform-jsbi-to-bigint`). This adds a build-step dependency and configuration complexity.
Fix: Integrate `babel-plugin-transform-jsbi-to-bigint` into your Babel configuration to automatically convert JSBI syntax to native BigInts.

Install

npm install jsbi npm
yarn add jsbi yarn
pnpm add jsbi pnpm

Imports

JSBI
wrong:
```
import JSBI from './jsbi.mjs';
```
correct:
```
import JSBI from 'jsbi';
```
Standard ESM import for consumers. The README's './jsbi.mjs' path is for internal use or specific bundler configurations, not the typical public API.
JSBI
wrong:
```
const { JSBI } = require('jsbi');
```
correct:
```
const JSBI = require('jsbi');
```
Standard CommonJS import. JSBI is exported as the default, not a named export.

JSBI.BigInt

wrong:

import { BigInt } from 'jsbi'; const myBigInt = BigInt('123');

correct:

import JSBI from 'jsbi'; const myBigInt = JSBI.BigInt('123');

BigInt is a static method of the JSBI object, not a direct named export from the package.

Quickstart

This example demonstrates how to import JSBI, create BigInt instances from numbers and strings, and perform arithmetic operations like addition and multiplication using JSBI's static methods, mimicking native BigInt behavior.

import JSBI from 'jsbi';

function demonstrateJSBI() {
  // Install: npm install jsbi

  const maxSafeInteger = Number.MAX_SAFE_INTEGER;
  console.log(`Max safe integer (JS Number): ${maxSafeInteger}`);

  // Create JSBI instances from numbers or strings
  const max = JSBI.BigInt(maxSafeInteger);
  console.log(`JSBI equivalent of MAX_SAFE_INTEGER: ${String(max)}`); // Use String() for clear output

  const other = JSBI.BigInt('2');
  console.log(`Another JSBI instance: ${String(other)}`);

  // Perform addition using JSBI's static methods, as native operators are not overloaded
  const result = JSBI.add(max, other);
  console.log(`Result of JSBI.add(${String(max)}, ${String(other)}): ${String(result)}`);

  // Demonstrate arithmetic beyond Number.MAX_SAFE_INTEGER
  const largeNumber = JSBI.BigInt("9007199999999999");
  const anotherLargeNumber = JSBI.BigInt("12345678901234567890");
  const product = JSBI.multiply(largeNumber, anotherLargeNumber);
  console.log(`Product of two large JSBI numbers: ${String(product)}`);

  // Comparison operations
  const isGreater = JSBI.greaterThan(product, JSBI.BigInt(0));
  console.log(`Is the product greater than 0? ${isGreater}`);
}

demonstrateJSBI();

view raw JSON →