BigInt

BigInt in one sentence

BigInt is a JavaScript type for whole numbers that stay exact, however big they get. A whole number, also called an integer, has no decimal part, like 7 or -20.

You write a BigInt like a normal number with an n on the end: 10n. The n is called a suffix, because it goes at the end. It tells JavaScript: "keep every digit of this whole number."

Why do you need it? The Data types lesson listed bigint as one of the eight basic value types. The Numbers lesson showed a problem with the normal Number type:

• Number is great for everyday math: prices, percentages, decimals, and the Math tools.
• Number keeps whole numbers exact only up to Number.MAX_SAFE_INTEGER, which is 9007199254740991.
• Past that, Number starts to skip some whole numbers. It rounds them to a number nearby.

BigInt never skips. Every digit stays exact.

In this lesson you will:

• see where Number stops being exact,
• write BigInts with the n suffix,
• do exact math with BigInts, step by step,
• fix the common error "Cannot mix BigInt and other types",
• use BigInt.asIntN and BigInt.asUintN to fit a number into a fixed size.

A safe integer is a whole number that Number stores exactly. With safe integers, adding 1 always gives the next whole number, and two different numbers never look the same.

The largest safe integer is 9007199254740991. JavaScript keeps it in Number.MAX_SAFE_INTEGER, so you don't have to remember the digits. Above it, Number can't store every whole number. Some are rounded to a number next to them.

Try the explorer below. Line 1 saves the largest safe integer as max. Lines 3 to 5 add 1, 2, and 3 to it. Look closely at max + 1 and max + 2: Number prints the same value for both. Line 8 does the same addition with BigInt, and the answer stays exact.

1const max = Number.MAX_SAFE_INTEGER;2console.log(max);3console.log(max + 1);4console.log(max + 2);5console.log(max + 3);6console.log(2 ** 53 + 1 === 2 ** 53);7console.log(Number.isSafeInteger(max + 1));8console.log(BigInt(max) + 1n);

The code uses three tools you may not know yet:

• 2 ** 53 means 2 to the power of 53. The ** operator raises a number to a power. Line 6 prints true, because 2 ** 53 + 1 is rounded to the same value as 2 ** 53.
• Number.isSafeInteger(value) gives true if the value is a safe integer, and false if not. Line 7 uses it.
• BigInt(max) on line 8 turns the Number max into a BigInt. That is fine here, because max is still exact.

A simple rule:

• Use Number for everyday values: counts on a page, loop counters, positions on the screen, percentages, and decimals.
• Think about BigInt when the value is a whole number, every digit matters, and it might grow past Number.MAX_SAFE_INTEGER.

The n suffix: how to write a BigInt

The easiest way to make a BigInt is to write a whole number with n at the end. A value written straight into your code is called a literal. So 10 is a Number literal, and 10n is a BigInt literal.

The n only works on whole numbers. You can't write 1.5n, because a BigInt has no decimal part.

1const exact = 10n;2console.log(typeof exact);3console.log(exact + 5n);4console.log(Boolean(0n));

Line by line:

1. Line 1 makes a BigInt, 10n, and saves it as exact.
2. Line 2 asks for its type with typeof, which gives a value's type as text. It prints bigint.
3. Line 3 adds 5n. Both sides are BigInts, so this works. It prints 15n.
4. Line 4 prints false. Boolean(value) tells you whether a value counts as true or false. 0n counts as false, just like the Number 0. A value that counts as false is called falsy.

Every BigInt except 0n counts as true, even -1n.

const fromText = BigInt("123");
console.log(fromText);
console.log(fromText + 1n);

Line 1 turns the text "123" into the BigInt 123n. The digits never pass through Number, so none of them can be rounded. Line 2 prints 123n. Line 3 adds 1n and prints 124n, which shows the result really is a BigInt.

console.log(BigInt(1.5));

This line throws a RangeError. That is the error JavaScript throws when a value is outside what is allowed. A BigInt can't hold the .5.

BigInt works with the math operators you already know:

• + adds, - subtracts, and * multiplies.
• ** raises a number to a power.
• / divides.
• % gives the remainder: what is left over after dividing.

There is one rule: both values must be BigInts. The values on each side of an operator are called operands. In 7n / 2n, the operands are 7n and 2n.

There is also one surprise: division. A BigInt can't have a decimal part, so division cuts the decimal part off.

Press Step to walk through the replay. Line 1 works out 10n ** 20n, which is 1 followed by 20 zeros, exactly. Then pick other values for lines 2 and 3, and compare 7n / 2n, -7n / 2n, and 25n / 4n.

1const power = 10n ** 20n;Run2const a = 7n;3const b = 2n;4console.log(power);5console.log(a / b);6console.log(a % b);7console.log(typeof 10n);

So BigInt is a good fit for exact whole-number work, such as:

• factorials, like 5!, which means 1 × 2 × 3 × 4 × 5,
• counters and IDs that grow very large,
• hash values, which are long numbers worked out from some data.

BigInt is not for decimals. If your math needs a half, a tenth, or a percentage, use Number.

BigInt and Number are two different types. JavaScript lets you compare one with the other. But it won't do math that mixes them, like 1n + 1. It throws a TypeError instead. A TypeError is the error JavaScript throws when a value has the wrong type for a job.

This error helps you. Without it, JavaScript would have to guess what you wanted: an exact BigInt answer, or a Number answer that can have decimals. So it asks you to choose.

Step through the replay below. It runs seven lines, one at a time:

• Lines 1 to 3 compare a BigInt with a Number.
• Lines 4 and 5 change a value from one type to the other, on purpose. Number(value) turns a value into a Number.
• Lines 6 and 7 throw errors.

1console.log(1n == 1);Run2console.log(1n === 1);3console.log(2n > 1);4console.log(BigInt("123"));5console.log(Number(9007199254740993n));6console.log(BigInt(1.5));7console.log(1n + 1);

The table sums up the replay. Read each row as: "when I write this, I get this result, for this reason."

A few more things don't work with BigInt:

• +10n throws. A + in front of a value turns it into a Number, and BigInt refuses.
• Math.max(1n) throws, because the Math tools only take Numbers.
• Sorting a list that mixes BigInts and Numbers needs care. You'll see how further down this page.

Computers store numbers as bits. A bit is a single 0 or 1. With 8 bits you can make 256 different patterns, so 8 bits can count from 0 to 255.

Most of the time in JavaScript, you never choose how many bits a number uses. But some other systems fix the size. For example, a database ID, a hash value, or a file format may say "this number is exactly 64 bits." BigInt has two tools for this:

• BigInt.asUintN(bits, value) keeps only the given number of bits and reads them as unsigned: zero or positive only.
• BigInt.asIntN(bits, value) keeps the same bits but reads them as signed: the top half of the patterns stand for negative numbers.

The table shows three calls. Read each row as: "this call gives this result, and here is why."

1console.log(BigInt.asUintN(8, 257n));2console.log(BigInt.asIntN(8, 255n));3console.log(BigInt.asUintN(64, -1n));

You won't need these tools for normal counting. Use them when your code works with another system that uses fixed-size numbers: binary file formats, 64-bit hash values, or database IDs. A later lesson on typed arrays uses them too.

Where you will use BigInt

Most JavaScript math should still use Number. Choose BigInt only when all three of these are true:

• the value is a whole number,
• every digit must be exact,
• the value might grow past Number.MAX_SAFE_INTEGER.

Here is where BigInt shows up in real code:

• Large IDs. Servers often send 64-bit IDs as text, so the browser doesn't round them. Turn one into a BigInt only if you need to do math with it.
• Factorials and counting combinations. Values like 30! are whole numbers that grow very fast.
• Money counted in cents, at huge sizes. If you store money as whole cents and totals can get enormous, BigInt keeps them exact. It still can't store 19.99 directly.
• Security code, hash values, and binary data. These often use fixed-size numbers, where asIntN and asUintN matter.

const idText = "9007199254740993";
const id = BigInt(idText);
console.log(id + 1n);

Line 1 holds the ID as text. Line 2 turns the text straight into a BigInt, so every digit is kept. Line 3 adds 1n and prints 9007199254740994n.

Common BigInt misconceptions

const record = { id: 1n };
console.log(JSON.stringify(record));

console.log(Math.max(1n));

Both blocks above throw a TypeError when you run them.

const values = [2n, 10, 1n];
values.sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
console.log(values);

Line by line:

1. Line 1 makes a list with two BigInts and one Number.
2. Line 2 sorts the list. .sort() calls your function with two items at a time, left and right. The function gives -1 if left should come first, 1 if right should come first, and 0 if they are equal. The ? : is a short if/else: a ? b : c means "if a, then b, else c".
3. Line 3 prints [ 1n, 2n, 10 ].

The function uses only < and >, which can compare a BigInt with a Number. The common shortcut left - right would mix the types and throw.

For each code question, first find the type of each value: BigInt or Number. Then work out the answer. Read the explanation for each choice, too.

Key takeaways

• Number.MAX_SAFE_INTEGER is 9007199254740991. Above it, Number may skip whole numbers.
• Put n after a whole number to make a BigInt, like 10n. typeof 10n is "bigint".
• BigInt math is exact for whole numbers. Division cuts off the decimal part, toward zero. 0n is falsy.
• Math can't mix BigInt and Number. Change one side on purpose. Be careful: a huge BigInt can lose digits when it becomes a Number.
• BigInt.asIntN and BigInt.asUintN fit a value into a fixed number of bits, signed or unsigned.

Up next: Type conversion. You will learn String(), Number(), and Boolean(), and when JavaScript changes a value's type on its own.