BigInt

BigInt is a built-in object whose constructor returns a bigint primitive — also called a BigInt value, or sometimes just a BigInt — to represent whole numbers larger than 2^53 - 1 (Number.MAX_SAFE_INTEGER), which is the largest number JavaScript can represent with a number primitive (or Number value). BigInt values can be used for arbitrarily large integers.

Description

A BigInt value, also sometimes just called a BigInt, is a bigint primitive, created by appending n to the end of an integer literal, or by calling the BigInt() constructor (but without the new operator) and giving it an integer value or string value.

const previouslyMaxSafeInteger = 9007199254740991n

const alsoHuge = BigInt(9007199254740991)
// ↪ 9007199254740991n

const hugeString = BigInt("9007199254740991")
// ↪ 9007199254740991n

const hugeHex = BigInt("0x1fffffffffffff")
// ↪ 9007199254740991n

const hugeOctal = BigInt("0o377777777777777777")
// ↪ 9007199254740991n

const hugeBin = BigInt("0b11111111111111111111111111111111111111111111111111111")
// ↪ 9007199254740991n

BigInt values are similar to Number values in some ways, but also differ in a few key matters: A BigInt value cannot be used with methods in the built-in Math object and cannot be mixed with a Number value in operations; they must be coerced to the same type. Be careful coercing values back and forth, however, as the precision of a BigInt value may be lost when it is coerced to a Number value.

Type information

When tested against typeof, a BigInt value (bigint primitive) will give "bigint":

typeof 1n === 'bigint'           // true
typeof BigInt('1') === 'bigint'  // true

A BigInt value can also be wrapped in an Object:

typeof Object(1n) === 'object'  // true

Operators

The following operators may be used with BigInt values or object-wrapped BigInt values:

+ * - % **

Bitwise operators are supported as well, except >>> (zero-fill right shift), as every BigInt value is signed.

Also unsupported is the unary operator (+), in order to not break asm.js.

const previousMaxSafe = BigInt(Number.MAX_SAFE_INTEGER)
// ↪ 9007199254740991n

const maxPlusOne = previousMaxSafe + 1n
// ↪ 9007199254740992n

const theFuture = previousMaxSafe + 2n
// ↪ 9007199254740993n, this works now!

const multi = previousMaxSafe * 2n
// ↪ 18014398509481982n

const subtr = multi - 10n
// ↪ 18014398509481972n

const mod = multi % 10n
// ↪ 2n

const bigN = 2n ** 54n
// ↪ 18014398509481984n

bigN * -1n
// ↪ -18014398509481984n

The / operator also works as expected with whole numbers — but operations with a fractional result will be truncated when used with a BigInt value — they won’t return any fractional digits.

const expected = 4n / 2n
// ↪ 2n

const truncated = 5n / 2n
// ↪ 2n, not 2.5n

Comparisons

A BigInt value is not strictly equal to a Number value, but it is loosely so:

0n === 0
// ↪ false

0n == 0
// ↪ true

A Number value and a BigInt value may be compared as usual:

1n < 2
// ↪ true

2n > 1
// ↪ true

2 > 2
// ↪ false

2n > 2
// ↪ false

2n >= 2
// ↪ true

BigInt values and Number values may be mixed in arrays and sorted:

const mixed = [4n, 6, -12n, 10, 4, 0, 0n]
// ↪  [4n, 6, -12n, 10, 4, 0, 0n]

mixed.sort() // default sorting behavior
// ↪  [ -12n, 0, 0n, 10, 4n, 4, 6 ]

mixed.sort((a, b) => a - b)
// won't work since subtraction will not work with mixed types
// TypeError: can't convert BigInt value to Number value

// sort with an appropriate numeric comparator
mixed.sort((a, b) => (a < b) ? -1 : ((a > b) ? 1 : 0))
// ↪  [ -12n, 0, 0n, 4n, 4, 6, 10 ]

Note that comparisons with Object-wrapped BigInt values act as with other objects, only indicating equality when the same object instance is compared:

0n === Object(0n)          // false
Object(0n) === Object(0n)  // false

const o = Object(0n)
o === o                    // true

Conditionals

A BigInt value behaves like a Number value in cases where:

• it is converted to a Boolean: via the Boolean function;
• when used with logical operators ||, &&, and !; or
• within a conditional test like an if statement.

if (0n) {
  console.log('Hello from the if!')
} else {
  console.log('Hello from the else!')
}

// ↪ "Hello from the else!"

0n || 12n
// ↪ 12n

0n && 12n
// ↪ 0n

Boolean(0n)
// ↪ false

Boolean(12n)
// ↪ true

!12n
// ↪ false

!0n
// ↪ true

Constructor

BigInt()

Creates a new BigInt value.

Static methods

BigInt.asIntN()

Clamps a BigInt value to a signed integer value, and returns that value.

BigInt.asUintN()

Clamps a BigInt value to an unsigned integer value, and returns that value.

Instance methods

BigInt.prototype.toLocaleString()

Returns a string with a language-sensitive representation of this BigInt value. Overrides the Object.prototype.toLocaleString() method.

BigInt.prototype.toString()

Returns a string representing this BigInt value in the specified radix (base). Overrides the Object.prototype.toString() method.

BigInt.prototype.valueOf()

Returns this BigInt value. Overrides the Object.prototype.valueOf() method.

Usage recommendations

Coercion

Because coercing between Number values and BigInt values can lead to loss of precision, the following are recommended:

• Only use a BigInt value when values greater than 2^53 are reasonably expected.
• Don’t coerce between BigInt values and Number values.

Cryptography

The operations supported on BigInt values are not constant-time, and are thus open to timing attacks. JavaScript BigInts are therefore not well-suited for use in cryptography.

Use within JSON

Using JSON.stringify() with any BigInt value will raise a TypeError, as BigInt values aren't serialized in JSON by default. However, you can implement your own toJSON method:

BigInt.prototype.toJSON = function() { return this.toString()  }

Instead of throwing, JSON.stringify now produces a string like this:

JSON.stringify(BigInt(1))
// '"1"'

Examples

Calculating Primes

// Returns true if the passed BigInt value is a prime number
function isPrime(p) {
  for (let i = 2n; i * i <= p; i++) {
    if (p % i === 0n) return false;
  }
  return true
}

// Takes a BigInt value as an argument, returns nth prime number as a BigInt value
function nthPrime(nth) {
  let maybePrime = 2n
  let prime = 0n

  while (nth >= 0n) {
    if (isPrime(maybePrime)) {
      nth--
      prime = maybePrime
    }
    maybePrime++
  }

  return prime
}

nthPrime(20n)
// ↪ 73n

Specifications

Browser compatibility

See also

• Number
• Number.MAX_SAFE_INTEGER