JavaScript BigInt

BigInt literals and the BigInt() function, including the TypeError for mixed Number arithmetic and the default JSON.stringify TypeError.

模块页正文目前为英文。

BigInt is an ECMAScript primitive for integers of arbitrary magnitude. Write a literal with an n suffix, or call BigInt(value). It is not Number, and it is not a decimal type.

The JSON page already shows that JSON.stringify throws TypeError for BigInt. This page states that default and the arithmetic rules; it does not replace the JSON reference.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
BigInt arithmetic and conversionsBigInt arithmetic stays in BigInt and truncates division toward zero. Mixing in Number for +, -, *, /, %, **, or bitwise operators throws TypeError.
JSON.stringify and BigIntThe default JSON serializer throws TypeError for BigInt values. That is the same exception used for cyclic objects, not SyntaxError.

Arithmetic and mixed types

BigInt values can use +, -, *, /, %, **, and bitwise operators with other BigInt values. Division truncates toward zero, so 5n / 2n is 2n.

Mixing BigInt and Number in an arithmetic or bitwise operation throws TypeError. Comparisons may mix the two types: 1n == 1 is true, 1n === 1 is false, and 1n > 0 is true. Convert explicitly with Number(bigint) or BigInt(number) when you intend a conversion.

BigInt arithmetic and conversions

bigint + bigint
BigInt(value)
Number(bigint)

BigInt arithmetic stays in BigInt and truncates division toward zero. Mixing in Number for +, -, *, /, %, **, or bitwise operators throws TypeError.

ParameterDescription
valueBigInt() accepts an integer, an integer-like string, or another BigInt. A non-integer Number such as 1.5 throws RangeError.

Returns: A BigInt, except Number(bigint), which returns a Number and may lose precision for large values.

Throws

  • TypeError — Thrown when a BigInt and a Number are combined in arithmetic or bitwise operations.
  • RangeError — Thrown by BigInt() when the value is not an integer, for example BigInt(1.5).
javascript
const n = 10n;
console.log(typeof n, n + 2n, 5n / 2n);
try {
  console.log(1n + 1);
} catch (error) {
  console.log(error.name);
}
console.log(1n == 1, 1n === 1, 1n > 0);
try {
  BigInt(1.5);
} catch (error) {
  console.log(error.name);
}
console.log(Number(1n), BigInt("10"));

Expected output

bigint 12n 2n
TypeError
true false true
RangeError
1 10n

Related: JSON.stringify and BigInt, Number and Math

MDN documentation →

JSON.stringify throws by default

JSON.stringify(1n) and JSON.stringify({ x: 1n }) throw TypeError. There is no default BigInt encoding in JSON. A replacer can choose a string or number representation, which is a data-format decision, not something this page recommends as a general standard.

JSON.parse has no built-in BigInt revival. See the JSON page for stringify exceptions and parse errors.

JSON.stringify and BigInt

JSON.stringify(value)

The default JSON serializer throws TypeError for BigInt values. That is the same exception used for cyclic objects, not SyntaxError.

Throws

  • TypeError — Thrown when a BigInt appears in the value, unless a replacer returns a JSON-safe substitute.
  • Do not assume a JSON API will accept 1n. Convert or omit the value first, or provide a replacer that you control.
javascript
try {
  JSON.stringify(1n);
} catch (error) {
  console.log(error.name);
}
try {
  JSON.stringify({ x: 1n });
} catch (error) {
  console.log(error.name);
}

Expected output

TypeError
TypeError

Related: JSON.stringify, Official BigInt

MDN documentation →