BigInt inside the engine

A BigInt is a list of digits in memory

A BigInt is JavaScript's type for whole numbers of any size, with no rounding. You write one with an n at the end, like 10n. This lesson looks at how V8 keeps a BigInt in memory. V8 is the JavaScript engine inside Chrome and Node.js. Every fact here was checked on V8 version 12.4, the version inside Node 22.

V8 keeps each BigInt on the heap. The heap is the part of memory where the engine keeps objects. A stored BigInt has three parts:

• The sign: is the number negative or not?
• The length: how many digits the number uses.
• The digits: the number cut into 64-bit pieces. One 64-bit piece holds any whole number from 0 up to 2⁶⁴ − 1, about 18 quintillion. V8 calls each piece a digit.

This lesson builds on the beginner BigInt lesson and Tagged values, Smis & heap numbers. It is not about how to write BigInt code. It is about how V8 stores BigInts and what each operation costs:

• why math on a BigInt always makes a new BigInt,
• why V8 multiplies in different ways for different sizes,
• why turning a BigInt into decimal text takes work,
• and how fixed 64-bit tools, like BigInt64Array, fit in.

Sign, length, and 64-bit digits

The main source is V8's file src/objects/bigint.h. It describes BigIntBase, the shape every BigInt has:

• The sign and the length share one small field. The sign is 1 for a negative number and 0 for any other number.
• Each digit has the type digit_t. It is as wide as a memory address on the machine (uintptr_t). On the 64-bit Node 22 build used by the tests, that is 64 bits.
• The digits come right after, in a list that is as long as the number needs.

So 2n ** 64n, which is one more than the biggest 64-bit digit, needs two digits: 0x0 first, then 0x1. The 0x means the digit is written in hexadecimal (base 16). The low digit comes first. This order is called little-endian.

Each row of the table is one part of a stored BigInt. Read across: the part, what V8 shows, and what that means.

%DebugPrint is a debug command built into V8. It prints how a value is stored. It only works in Node, and only when you start Node with the --allow-natives-syntax flag. So this code does not run in the browser.

1// Runs only in Node started with --allow-natives-syntax.2for (const [label, value] of [3  ["ten", 10n],4  ["two64", 2n ** 64n],5  ["negative", -5n],6  ["zero", 0n],7]) {8  process.stdout.write("@@" + label + "\n");9  %DebugPrint(value);10}

Lines 3 to 6 list four BigInts: 10n, 2n ** 64n, -5n, and 0n. Line 8 prints a label before each one, so the output is easy to split. Line 9 prints how the BigInt is stored. The lesson test checks only the parts that stay the same from run to run:

• [BigInt] and BIG_INT_BASE_TYPE: the kind of object.
• instance size: variable: the size depends on how many digits there are.
• The length, the sign, and the digit lines.

It does not check memory addresses or exact sizes, because those change. Chrome runs a newer V8 that also squeezes addresses into 32 bits (this is called pointer compression), so the addresses there look different.

1const value = 2n ** 64n;2const mask = (1n << 64n) - 1n;3const sign = value < 0n ? "negative" : "positive";4const lowDigit = value & mask;5const nextDigit = (value >> 64n) & mask;6 7console.log(sign);8console.log("0x" + lowDigit.toString(16));9console.log("0x" + nextDigit.toString(16));

The playground finds the same digits with ordinary BigInt math:

• value & 0xffffffffffffffffn keeps only the lowest 64 bits. That is the low digit.
• value >> 64n drops those 64 bits, so the next digit moves down to the bottom.
• It repeats until nothing is left. Zero has nothing to store, so it has length 0 and no digits.

The byte count it shows is a simple teaching estimate: 24 bytes plus 8 bytes per digit. It is not a real measurement of memory.

1const cache = new Map([[1n, "a"]]);2const set = new Set([1n, BigInt("1")]);3 4console.log(1n === 1n);5console.log(cache.get(1n));6console.log(set.size);

Each BigInt lives in its own heap object, but it still acts like a plain value, the way a number does. In plain words, line by line:

1. Line 1 makes a Map with one key, 1n, that holds "a".
2. Line 2 makes a Set from 1n and BigInt("1"). BigInt("1") turns the text "1" into a BigInt.
3. Line 4 prints true. === compares the two numbers, not where they are stored.
4. Line 5 prints a. A Map finds a BigInt key by its value.
5. Line 6 prints 1. The Set keeps one copy, because both items are the same value.

Adding goes one digit at a time

V8 adds two BigInts the way you add long numbers on paper, column by column. It adds the two low digits first. If the sum is too big for one digit, it keeps the low part and carries 1 into the next digit. Subtraction works the same way, but it borrows instead of carrying.

So the work grows with the number of digits. Adding two one-digit BigInts is quick. Adding two 1,000-digit BigInts takes about 1,000 steps.

A BigInt can never be changed after it is made. So every sum is a new BigInt, and V8 must find new memory for it. In some narrow cases, V8's optimizing compiler can skip that step.

The step-through below runs a small copy of this method, written in JavaScript. Each item in the left and right lists is one 64-bit digit, low digit first.

1const BIGINT_BASE = 1n << 64n;2const DIGIT_MASK = BIGINT_BASE - 1n;3 4function fromDigits(digits) {5  let value = 0n;6  for (let index = digits.length - 1; index >= 0; index -= 1) {7    value = value * BIGINT_BASE + digits[index];8  }9  return value;10}11 12function addDigits(left, right) {13  const out = [];14  let carry = 0n;15  const length = Math.max(left.length, right.length);16  for (let index = 0; index < length; index += 1) {17    const sum = (left[index] ?? 0n) + (right[index] ?? 0n) + carry;18    out[index] = sum & DIGIT_MASK;19    carry = sum >> 64n;20  }21  if (carry) out.push(carry);22  return out;23}24 25const left = [0xffffffffffffffffn, 0x1n];Run26const right = [0x2n];27const digits = addDigits(left, right);28console.log(digits.map((digit) => "0x" + digit.toString(16)).join(", "));29console.log(fromDigits(digits) === fromDigits(left) + fromDigits(right));

The main work happens on three lines:

1. Line 17 adds one digit from left, one digit from right, and the carry. A missing digit counts as 0n.
2. Line 18 keeps only the low 64 bits of that sum, using DIGIT_MASK. That is the new digit.
3. Line 19 shifts the sum right by 64 bits. What is left is the carry for the next digit.

Line 28 prints the new digits, 0x1, 0x2. Line 29 turns the digit lists back into BigInts with fromDigits and compares the answer with JavaScript's own +. It prints true.

Multiplying picks a method by size

Multiplying is more work than adding. The school method multiplies every digit of one number by every digit of the other. Two numbers with 100 digits each need 100 × 100 = 10,000 small multiplications. For long numbers, V8 switches to smarter methods that need fewer of them. Most are named after the people who found them:

• Schoolbook: the method you learned at school.
• Karatsuba: splits each number into two halves and saves one multiplication at each split.
• Toom-Cook: splits each number into three parts.
• FFT (fast Fourier transform): turns the multiplication into a different math problem that is quicker for huge numbers. V8's file says this method comes from Schönhage and Strassen.

V8 decides by counting the digits of the shorter number. The size where a new method starts is called a threshold. The thresholds are set in bigint-internal.h, and bigint-internal.cc uses them to choose. The 2018 V8 BigInt article describes the first version, which used only the school method.

Each line below is a constant copied from V8's source: a name and a digit count.

1V8 12.4.254.21 src/bigint/bigint-internal.h:2kKaratsubaThreshold = 34 digits3kToomThreshold      = 193 digits4kFftThreshold       = 1500 digits5kFftInnerThreshold  = 200 digits6kBurnikelThreshold  = 57 digits7kBarrettThreshold   = 13310 digits8kToStringFastThreshold = 43 digits9kFromStringLargeThreshold = 300 digits

Lines 2 to 4 are the multiplication thresholds. Line 5 is used inside the FFT method. Lines 6 and 7 are for division, and lines 8 and 9 are for strings. Both come later in this lesson.

The table turns the thresholds into ranges. Read each row as: this method runs when the shorter number has this many digits. In the third column, n is the number of digits.

A build setting, v8_advanced_bigint_algorithms, turns on Toom-Cook and FFT. It is on by default, except on Android. When it is off, V8 uses Karatsuba for all large products.

The step-through below does one Karatsuba split on 123456n * 789012n.

1const SPLIT_BASE = 1000n;2 3function karatsubaOneLevel(x, y) {4  const xLow = x % SPLIT_BASE;5  const xHigh = x / SPLIT_BASE;6  const yLow = y % SPLIT_BASE;7  const yHigh = y / SPLIT_BASE;8  const z0 = xLow * yLow;9  const z2 = xHigh * yHigh;10  const z1 = (xLow + xHigh) * (yLow + yHigh) - z2 - z0;11  return z2 * SPLIT_BASE * SPLIT_BASE + z1 * SPLIT_BASE + z0;12}13 14const product = karatsubaOneLevel(123456n, 789012n);Run15console.log(product === 123456n * 789012n);16console.log(product.toString());

Multiplying two split numbers the school way takes four multiplications of halves. Karatsuba needs only three:

1. Line 8 multiplies the two low halves. That is z0.
2. Line 9 multiplies the two high halves. That is z2.
3. Line 10 adds each number's two halves, multiplies the two sums once, then subtracts z2 and z0. That leaves the middle part, z1.
4. Line 11 puts the three parts back together into the full product.

The example splits at 1000n, so you can read the halves in decimal. V8 splits along its 64-bit digits instead.

Division also has several methods. Read each row as: the method, when V8 uses it, and what to remember.

Turning BigInts into text and back

A BigInt stores its value as 64-bit binary digits, not as decimal text. So toString() must work out the decimal characters, and BigInt(text) must work out the binary digits. V8 does this in two files:

• tostring.cc turns a BigInt into text. For a base that is a power of two, like 16, it just regroups the bits. For other bases, like 10, it splits a large number by dividing it again and again.
• fromstring.cc reads text into a BigInt. For long text, it joins neighboring chunks in pairs, so the fast multiplication methods can help.

Read each row as: the kind of conversion, what V8 does, and why it matters.

1const decimal = "900719925474099312345";2const id = BigInt(decimal);3const hex = id.toString(16);4 5console.log(hex);6console.log(BigInt("0x" + hex) === id);

In plain words, line by line:

1. Line 1 holds a long number as decimal text.
2. Line 2 reads the text into a BigInt.
3. Line 3 writes the BigInt as base 16 text.
4. Line 5 prints 30d40000000001b6d9.
5. Line 6 reads the base 16 text back. The "0x" in front tells BigInt() it is base 16. It prints true, so no part of the value was lost.

Printing a huge BigInt in decimal is slow because each base-10 character has to be worked out from the binary digits. No decimal text is stored ready to print.

Fixed 64-bit values and BigInt64Array

A normal BigInt grows as big as it needs. Some data has a fixed size instead: exactly 64 bits, like a number field in a network message. JavaScript has tools for that:

• BigInt.asIntN(64, value) keeps only the low 64 bits and reads them as a signed number, one that can be negative.
• BigInt.asUintN(64, value) keeps only the low 64 bits and reads them as an unsigned number, one that is never negative.
• BigInt64Array and BigUint64Array are typed arrays: rows of fixed-size slots inside an ArrayBuffer, which is a block of raw bytes. Each slot is 64 bits. Reading a slot gives you a BigInt.

1const buffer = new ArrayBuffer(16);2const signed = new BigInt64Array(buffer);3const bytes = new Uint8Array(buffer);4 5signed[0] = -1n;6signed[1] = (1n << 63n) - 1n;7 8console.log(signed[0]);9console.log(bytes.slice(0, 8).every((byte) => byte === 255));10console.log(BigInt.asUintN(64, -1n));

In plain words, line by line:

1. Line 1 makes a buffer of 16 bytes. That is room for two 64-bit slots.
2. Line 2 views the buffer as signed 64-bit slots that hold BigInts.
3. Line 3 views the same bytes one at a time, as numbers from 0 to 255.
4. Line 5 writes -1n into slot 0.
5. Line 6 writes the biggest signed 64-bit value, 2⁶³ − 1, into slot 1.
6. Line 8 prints -1n. Reading a slot gives a BigInt, not a Number.
7. Line 9 prints true. The first 8 bytes are all 255, so every bit is 1.
8. Line 10 prints 18446744073709551615n. Those same 64 bits, read as unsigned, are 2⁶⁴ − 1.

The biggest BigInt

A BigInt can hold very large numbers, but not endless ones. V8 sets BigInt::kMaxLengthBits to 1 << 30, which is 2³⁰ bits, about one billion bits. The limit is in src/objects/bigint.h. A note there says V8 picks the same limit on every platform, a little below what it could handle.

1// Run in Node. V8 checks the size first, so it throws before it uses the memory.2try {3  2n ** (2n ** 30n);4} catch (error) {5  console.log(error.name + ": " + error.message);6}

Line 3 asks for 2 to the power of 2³⁰. The answer would need more than 2³⁰ bits, so V8 throws an error. Line 4 catches it, and line 5 prints its name and message.

How other engines store BigInts

Every engine follows the same ECMAScript BigInt rules, which say how a BigInt behaves. But each engine may store BigInts in its own way. Your code can't see the difference, so don't rely on it.

Read each row as: the engine, how it stores BigInts, and what its source code shows.

• JavaScriptCore is Safari's engine. Its file JSCJSValue.h has a short form for small BigInts, with EncodeAsBigInt32 and a BigInt32Tag. It sits behind a switch called USE(BIGINT32). Right now WebKit turns that switch off with USE_BIGINT32 0.
• SpiderMonkey is Firefox's engine. Its file BigIntType.h defines InlineDigitsLength. A small BigInt keeps its digits inside the BigInt itself. Only a bigger one gets a separate list of digits.

Practical use

Use a Number when:

• the values stay below Number.MAX_SAFE_INTEGER, about 9 quadrillion,
• you need decimals, like 2.5,
• or you need Math functions, like Math.round().

Use a BigInt for exact large whole numbers, such as:

• database IDs,
• math for cryptography (the codes that keep data secret),
• bit masks, which are numbers used as rows of on/off switches,
• counters that go past 2⁵³,
• and 64-bit fields in network messages or file formats.

1const fromProtocol = BigInt.asUintN(64, 18446744073709551616n + 5n);2const smallCount = 42n;3 4console.log(fromProtocol);5console.log(Number(smallCount));

Line 1 wraps 2⁶⁴ + 5 into 64 bits. Only 5n is left, because the 2⁶⁴ part does not fit. Line 4 prints 5n. Line 5 turns the small BigInt 42n into a Number on purpose and prints 42.

• Keep Number math and BigInt math apart. Convert on purpose, where data comes in or goes out.
• When a value has a fixed 64-bit size, use BigInt.asUintN(64, value) or BigInt.asIntN(64, value).
• Read a large decimal ID with BigInt(text). Don't turn it into a Number first, because that can round it.
• Measure slow code before you change it. The thresholds and 64-bit shortcuts are facts about V8, not promises about speed.

Common misconceptions

• “Small BigInts are stored without a heap object.” Not in V8 12.4. The tests show that 10n is a [BigInt] heap object.
• “BigInt has no maximum.” V8 has a largest number of bits. Past it, V8 throws a RangeError.
• “BigInt64Array keeps BigInt objects in its buffer.” The buffer holds raw 64-bit slots. Reading a slot makes a BigInt.
• “Printing a BigInt in decimal is free.” Turning binary digits into decimal characters is real work.

Each row shows an idea, what is true, and the mistake people often make.

Practice exercises

const value = 2n ** 64n;
const mask = (1n << 64n) - 1n;
console.log("0x" + (value & mask).toString(16));
console.log("0x" + ((value >> 64n) & mask).toString(16));

const value = 2n ** 64n;
const mask = (1n << 64n) - 1n;
console.log("0x" + (value & mask).toString(16));
console.log("0x" + ((value >> 64n) & mask).toString(16));

const cache = new Map([[1n, "a"]]);
console.log(cache.get(BigInt("1")));

const cache = new Map([[1n, "a"]]);
console.log(cache.get(BigInt("1")));

const mask = (1n << 64n) - 1n;
const sum = 0xffffffffffffffffn + 2n;
console.log("0x" + (sum & mask).toString(16));
console.log(sum >> 64n);

const mask = (1n << 64n) - 1n;
const sum = 0xffffffffffffffffn + 2n;
console.log("0x" + (sum & mask).toString(16));
console.log(sum >> 64n);

console.log((123456n * 789012n).toString());

console.log((123456n * 789012n).toString());

console.log(BigInt.asUintN(64, -1n));

console.log(BigInt.asUintN(64, -1n));

console.log(BigInt.asUintN(64, 18446744073709551616n + 5n));

console.log(BigInt.asUintN(64, 18446744073709551616n + 5n));

Quiz

Key takeaways

• V8 stores every BigInt as a heap object with a sign, a length, and 64-bit digits, low digit first.
• Zero has length 0. 2n ** 64n has two digits: 0x0, then 0x1.
• Adding takes one step per digit. Multiplying switches from Schoolbook to Karatsuba, Toom-Cook, and FFT as the numbers get longer.
• Turning a BigInt into text, or text into a BigInt, is real work, most of all for long decimal numbers.
• Use BigInt for exact large whole numbers. Use asUintN(64) or asIntN(64) for fixed 64-bit values.

One-line definition: A BigInt is an exact whole number that V8 stores as a heap object with a sign, a length, and 64-bit digits, and never changes.

Up next: Symbols inside the engine.