Integers, the safe range and BigInt
The one number type of the previous lesson is exact for every integer up to two to the fifty-third, and above that it rounds to the nearest representable value. That limit is not a warning in the language: an addition that leaves the range returns a number that is silently wrong by one or two, and a comparison against a value that was never stored answers true. Number.MAX_SAFE_INTEGER names the boundary.
JavaScript gained a second numeric type for values beyond that boundary: bigint, written with an n after an integer literal and stored without a fixed width. This lesson shows the rounding at the edge of the number type, then the bigint itself, its arithmetic, the error that mixing the two types produces, and the one place where a bigint breaks a program that works with numbers.
The safe range
A 64-bit float spends eleven bits on the exponent, which leaves fifty-three bits for the digits. Every integer that fits in those bits is stored exactly, and the largest of them is 2 ** 53 - 1. One step above it the gap between neighbouring values becomes two, so an odd number cannot be represented and the addition rounds to the even neighbour.
console.log('MAX_SAFE_INTEGER:', Number.MAX_SAFE_INTEGER);
console.log('MIN_SAFE_INTEGER:', Number.MIN_SAFE_INTEGER);
console.log('MAX_SAFE_INTEGER + 1:', Number.MAX_SAFE_INTEGER + 1);
console.log('isSafeInteger(MAX):', Number.isSafeInteger(Number.MAX_SAFE_INTEGER));
console.log('isSafeInteger(MAX + 1):', Number.isSafeInteger(Number.MAX_SAFE_INTEGER + 1));
console.log('2 ** 53 + 1:', 2 ** 53 + 1);
console.log('2 ** 53 === 2 ** 53 + 1:', 2 ** 53 === 2 ** 53 + 1);
node safe-range.js
MAX_SAFE_INTEGER: 9007199254740991
MIN_SAFE_INTEGER: -9007199254740991
MAX_SAFE_INTEGER + 1: 9007199254740992
isSafeInteger(MAX): true
isSafeInteger(MAX + 1): false
2 ** 53 + 1: 9007199254740992
2 ** 53 === 2 ** 53 + 1: true
The last line is the failure that matters: two additions produced the same value, so the program cannot tell a count of nine quadrillion from a count one higher. A database key, an account balance in cents or a nanosecond timestamp reaches that size in real systems, and Number.isSafeInteger is the check that catches the value before the arithmetic loses it. Above the safe range the same number type keeps working and stops being exact; the fix is the other type, not a bigger number.
The BigInt literal
A bigint is an integer of any size, written as an integer literal followed by n. It has its own arithmetic and its own precision: the value below is one above the largest safe integer, and it stays one above it through the printing, which is exactly what the number type could not do. The type also accepts a decimal string, which is how a value read from a database arrives.
const big = 9007199254740993n;
console.log('big:', big);
console.log('typeof:', typeof big);
console.log('as string:', String(big));
console.log('plus one:', big + 1n);
console.log('times two:', big * 2n);
console.log('Number(big):', Number(big));
console.log('from text:', BigInt('123456789012345678901234567890'));
console.log('10n == 10:', 10n == 10);
console.log('10n === 10:', 10n === 10);
node bigint.js
big: 9007199254740993n
typeof: bigint
as string: 9007199254740993
plus one: 9007199254740994n
times two: 18014398509481986n
Number(big): 9007199254740992
from text: 123456789012345678901234567890n
10n == 10: true
10n === 10: false
Number(big) came back one below the value, which is the rounding of the smaller type rather than a bug in the conversion. The two comparisons show the difference between the two equality operators: the loose one compares the numbers they mean and finds them equal, the strict one compares the types as well and finds them different. A bigint therefore never arrives in a place that expects a number by accident.
Mixing the two types
The operators refuse to guess. An addition of a bigint and a number throws a TypeError instead of converting one of them, because either conversion could lose a value without telling anybody. The same happens when a bigint is passed to a function that is defined for numbers, such as Math.max. The program catches both errors and prints the message the runtime produced.
try {
console.log(1n + 1);
} catch (error) {
console.log(error.name + ': ' + error.message);
}
try {
console.log(Math.max(1n, 2n));
} catch (error) {
console.log(error.name + ': ' + error.message);
}
console.log('explicit conversion:', 1n + BigInt(1));
console.log('explicit back:', Number(1n + 1n));
node mixing.js
TypeError: Cannot mix BigInt and other types, use explicit conversions
TypeError: Cannot convert a BigInt value to a number
explicit conversion: 2n
explicit back: 2
The messages say what the fix is: BigInt(1) when the value should stay exact, Number(value) when it may leave the range. The functions in Math are a special case, because they are defined for the number type only, so a program that counts with bigints does its rounding with its own code rather than with the Math functions.
Division and what JSON does with it
Division between two bigints is integer division: the fraction is dropped towards zero and no float is produced, whatever the operands. The power operator keeps full precision, so 2n ** 64n is the exact value that a number would round. The last part of the program is the one breakage: JSON has no bigint in its grammar, so the serialiser refuses the value instead of writing an approximation.
console.log('7 / 2:', 7 / 2);
console.log('7n / 2n:', 7n / 2n);
console.log('7n % 2n:', 7n % 2n);
console.log('-7n / 2n:', -7n / 2n);
console.log('2n ** 64n:', 2n ** 64n);
try {
console.log(JSON.stringify({ id: 1n }));
} catch (error) {
console.log(error.name + ': ' + error.message);
}
console.log('as text:', JSON.stringify({ id: String(1n) }));
node division.js
7 / 2: 3.5
7n / 2n: 3n
7n % 2n: 1n
-7n / 2n: -3n
2n ** 64n: 18446744073709551616n
TypeError: Do not know how to serialize a BigInt
as text: {"id":"1"}
The truncated quotient is the behaviour of integer division in most languages, and it is why a bigint is the right type for a counter and the wrong type for an average. The last line is the usual way out of the JSON problem: the bigint goes over the wire as a string and the reader converts it back with BigInt(text). A number would have lost the digits before the text was even written.
Exercises
- Print Number.MAX_SAFE_INTEGER + 2 in safe-range.js. Is the result even, and why is that the value the type can hold?
- Add console.log(2 ** 53 - 1 === 2 ** 53 - 2) to safe-range.js. What does it answer, and which range does the value sit in?
- Replace big * 2n with big * 2 in bigint.js. Which error arrives, and which line of the output disappears?
- Pass a bigint to JSON.stringify as the whole value rather than inside an object. Does the message change?
- Compute 10n / 3n and -10n / 3n. Which direction does each quotient round, and what does that say about the negative case?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is
Number.MAX_SAFE_INTEGER?Answer
2 ** 53 - 1
Fifty-three bits of digits hold every integer up to 2 ** 53 - 1 exactly.
-
What does this program print?
console.log(2 ** 53 === 2 ** 53 + 1);Answer
true
The addition rounds to the neighbouring even value, which is the same value the left side holds.
-
What does
typeof 10nprint?Answer
bigint
A literal with the n suffix is a bigint, and typeof names that type.
-
What does this program print?
console.log(10n == 10);Answer
true
The loose equality compares the mathematical values, and both sides mean ten.
-
What does this program print?
console.log(10n === 10);Answer
false
The strict equality also compares the types, and a bigint is not a number.
-
What does
1n + 1do?Answer
It throws a TypeError about mixing the types
The operator refuses to choose a conversion, so the program has to write BigInt(1) or Number(1n).
-
What does this program print?
console.log(7n / 2n);Answer
3n
Division between two bigints drops the fraction towards zero and stays a bigint.
-
What does this program print?
console.log(-7n / 2n);Answer
-3n
The quotient truncates towards zero, so minus three and a half becomes minus three.
-
What does
JSON.stringify({ id: 1n })do?Answer
It throws a TypeError, because JSON has no bigint
The serialiser refuses a bigint instead of writing a rounded number, and String() is the usual fix.
-
When is a bigint the right type?
Answer
For identifiers and counters that can pass the safe range
A bigint is exact but has no fractions, so it fits whole values that grow past 2 ** 53 - 1.
The code on this page was run with Node.js 24.22.1 and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev