JavaScript BigInt

BigInt is a separate data type for whole numbers of any size, limited only by your computer's memory. Regular numbers lose accuracy past about 9 quadrillion (see JS Number Properties). BigInt does not. It was added in ES2020, bringing JavaScript to its 8 data types: String, Number, BigInt, Boolean, Undefined, Null, Symbol, and Object.

// The Problem

All regular JavaScript numbers are 64-bit floating point, so whole numbers are only accurate up to 15 digits, and exact only up to Number.MAX_SAFE_INTEGER (9007199254740991):

console.log(9999999999999999);      // 16 digits
console.log(9007199254740993);      // just past the safe limit
console.log(2 ** 64);

All three are wrong, and none of them give an error. That can even be a security problem:

console.log(9007199254740992 === 9007199254740993);      // two different numbers...
console.log(9007199254740992n === 9007199254740993n);    // ...as BigInts

If those were two different account IDs, regular numbers would treat them as the same account.

// Creating a BigInt

There are two ways: put an n on the end of a whole number, or pass a string to BigInt():

let a = 12345678901234567890n;
let b = BigInt("12345678901234567890");

console.log(a);
console.log(a === b);
console.log(typeof a);
console.log(2n ** 64n);            // exact this time

Like regular numbers, BigInts can be written in hex, octal, or binary. These are all 256:

let num = 256n;
let hex = 0x100n;
let oct = 0o400n;
let bin = 0b100000000n;

// Math with BigInt

BigInt supports the usual arithmetic operators: + - * / % ** and also ++ and --, as long as both sides are BigInts:

let x = 100n;
let y = 7n;
console.log(x + y);
console.log(x * y);
console.log(x % y);
console.log(x / y);      // no decimals: the remainder is dropped

let count = 5n;
count++;
console.log(count);

// No Decimals

BigInt is whole numbers only. Division always drops the fraction (7n / 2n is 3n, not 3.5), and a BigInt can never hold a decimal:

let x = 1.5n;          // SyntaxError: not even valid code
let y = BigInt(1.5);   // RangeError: 1.5 is not an integer

(W3Schools lists 1.5n as a TypeError; it is actually a SyntaxError, so the whole script refuses to run.)

// No Mixing Types

You cannot combine a BigInt and a regular number in math. Convert one side first, with BigInt() or Number():

let big = 10n;
let num = 5;

// big + num;   TypeError: Cannot mix BigInt and other types
console.log(big + BigInt(num));
console.log(Number(big) + num);

// Need a decimal answer? Convert to Number first
console.log(Number(5n) / 2);

// Comparing

Comparisons do work across the two types:

console.log(10n > 5);       // works across types
console.log(10n == 10);     // loose: same value
console.log(10n === 10);    // strict: different types, always false

// Bitwise Operators

The bitwise operators from the last lesson work on BigInts too, but only with other BigInts:

let a = 5n;   // 0101
let b = 3n;   // 0011
console.log(a & b, a | b, a ^ b, ~a);
console.log(10n << 2n, 10n >> 1n);

BigInt supports only two shifts, << and >>. The unsigned shift >>> throws a TypeError, because a BigInt has no fixed 32-bit size to fill with zeros.

// Things BigInt Cannot Do

Math.sqrt(16n);                // TypeError: Math methods need regular numbers
JSON.stringify({ id: 1n });    // TypeError: JSON cannot store BigInt

console.log(1n.toString());      // convert to a string to send or save it

(JSON is the text format used to send data to servers; you will meet it later.)

// Real Example: Big Factorials

A factorial multiplies every whole number up to n: 5! is 5 × 4 × 3 × 2 × 1 = 120. The results get huge very quickly:

let result = 1n;
for (let i = 2n; i <= 25n; i++) {
  result *= i;
}
console.log(result);

Notice the loop counter is a BigInt too (2n, 25n), so the multiplication never mixes types. With regular numbers, 25! would come out rounded. With BigInt every digit is exact.

// Quick Check

// Try It

▶ Open Playground

1. Click Open Playground and run it. Which one is exact?
2. Try 10n + 1 and read the error, then fix it two different ways
3. Compute 17n / 5n and 17n % 5n. How do the two answers fit together?
4. Open the factorial loop with its Try it Yourself button and change it to calculate 30! and then 50!