BigInt
values represent numeric values which are too large to be represented by the number
.
Description
A BigInt value, also sometimes just called a BigInt, is a bigint
, created by appending n
to the end of an integer literal, or by calling the BigInt() function (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
Most operators support BigInts, however most do not permit operands to be of mixed types — both operands must be BigInt or neither:
- Arithmetic operators:
+
,-
,*
,/
,%
,**
- Bitwise operators:
>>
,<<
,&
,|
,^
,~
- Unary negation (
-
) - Increment/decrement:
++
,--
The boolean-returning operators allow mixing numbers and BigInts as operands:
- Relational operators and equality operators:
>
,<
,>=
,<=
,==
,!=
,===
,!==
- Logical operators only rely on the truthiness of operands
A couple of operators do not support BigInt at all:
- Unary plus (
+
) cannot be supported due to conflicting usage in asm.js, so it has been left out in order to not break asm.js. - Unsigned right shift (
>>>
) is the only bitwise operator that's unsupported, as every BigInt value is signed.
Special cases:
- Addition (
+
) involving a string and a BigInt returns a string. - Division (
/
) truncates fractional components towards zero, since BigInt is unable to represent fractional quantities.
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
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:
Object(0n) === 0n; // false
Object(0n) === Object(0n); // false
const o = Object(0n);
o === o; // true
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 253 are reasonably expected.
- Don't coerce between BigInt values and Number values.
Conditionals
A BigInt value follows the same conversion rules as Numbers when:
- it is converted to a
Boolean
: via theBoolean
function; - when used with logical operators
||
,&&
, and!
; or - within a conditional test like an
if
statement.
Namely, only 0n
is falsy; everything else is truthy.
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
Cryptography
The operations supported on BigInt values are not constant-time and are thus open to timing attacks. JavaScript BigInts therefore could be dangerous for use in cryptography without mitigating factors. As a very generic example, an attacker could measure the time difference between 101n ** 65537n
and 17n ** 9999n
, and deduce the magnitude of secrets, such as private keys, based on the time elapsed. If you still have to use BigInts, take a look at the Timing attack FAQ for general advice regarding the issue.
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, JSON.stringify()
specifically leaves a backdoor for BigInt values: it would try to call the BigInt's toJSON()
method. (It doesn't do so for any other primitive values.) Therefore, you can implement your own toJSON()
method (which is one of the few cases where patching built-in objects is not explicitly discouraged):
BigInt.prototype.toJSON = function () {
return this.toString();
};
Instead of throwing, JSON.stringify()
now produces a string like this:
console.log(JSON.stringify({ a: 1n }));
// {"a":"1"}
If you do not wish to patch BigInt.prototype
, you can use the replacer
parameter of JSON.stringify
to serialize BigInt values:
const replacer = (key, value) =>
typeof value === "bigint" ? value.toString() : value;
const data = {
number: 1,
big: 18014398509481982n,
};
const stringified = JSON.stringify(data, replacer);
console.log(stringified);
// {"number":1,"big":"18014398509481982"}
If you have JSON data containing values you know will be large integers, you can use the reviver
parameter of JSON.parse
to handle them:
const reviver = (key, value) => (key === "big" ? BigInt(value) : value);
const payload = '{"number":1,"big":"18014398509481982"}';
const parsed = JSON.parse(payload, reviver);
console.log(parsed);
// { number: 1, big: 18014398509481982n }
Note: While it's possible to make the replacer of
JSON.stringify()
generic and properly serialize BigInt values for all objects, the reviver ofJSON.parse()
must be specific to the payload shape you expect, because the serialization is lossy: it's not possible to distinguish between a string that represents a BigInt and a normal string.
BigInt coercion
Many built-in operations that expect BigInts first coerce their arguments to BigInts. The operation can be summarized as follows:
- BigInts are returned as-is.
undefined
andnull
throw a TypeError.true
turns into1n
;false
turns into0n
.- Strings are converted by parsing them as if they contain an integer literal. Any parsing failure results in a SyntaxError. The syntax is a subset of string numeric literals, where decimal points or exponent indicators are not allowed.
- Numbers throw a TypeError to prevent unintended implicit coercion causing loss of precision.
- Symbols throw a TypeError.
- Objects are first converted to a primitive by calling their
[@@toPrimitive]()
(with"number"
as hint),valueOf()
, andtoString()
methods, in that order. The resulting primitive is then converted to a BigInt.
The best way to achieve nearly the same effect in JavaScript is through the BigInt()
function: BigInt(x)
uses the same algorithm to convert x
, except that Numbers don't throw a TypeError, but are converted to BigInts if they are integers.
Note that built-in operations expecting BigInts often truncate the BigInt to a fixed width after coercion. This includes BigInt.asIntN, BigInt.asUintN, and methods of BigInt64Array and BigUint64Array.
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 properties
These properties are defined on BigInt.prototype
and shared by all BigInt
instances.
- BigInt.prototype.constructor
- : The constructor function that created the instance object. For
BigInt
instances, the initial value is the BigInt constructor.
- : The constructor function that created the instance object. For
BigInt.prototype[@@toStringTag]
- : The initial value of the
@@toStringTag
property is the string"BigInt"
. This property is used in Object.prototype.toString. However, becauseBigInt
also has its owntoString()
method, this property is not used unless you callObject.prototype.toString.call()
with a BigInt asthisArg
.
- : The initial value of the
Instance methods
- BigInt.prototype.toLocaleString
- : Returns a string with a language-sensitive representation of this BigInt value. Overrides the
Object.prototype.toLocaleString()
method.
- : Returns a string with a language-sensitive representation of this BigInt value. Overrides the
- BigInt.prototype.toString
- : Returns a string representing this BigInt value in the specified radix (base). Overrides the
Object.prototype.toString()
method.
- : Returns a string representing this BigInt value in the specified radix (base). Overrides the
- BigInt.prototype.valueOf
- : Returns this BigInt value. Overrides the
Object.prototype.valueOf()
method.
- : Returns this BigInt value. Overrides the
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