BigInt inside the engine

BigInts are heap digit arrays

A JavaScript BigInt is the language's exact integer value. Inside V8 12.4, the value is represented by a heap object whose payload is a sign plus an array of machine-word digits. The V8 blog's original BigInt article describes the same idea as storing a large integer in register-sized chunks called digits, with the sign stored separately.

This lesson builds on the beginner BigInt lesson and Tagged values, Smis & heap numbers. We focus on storage and costs, not syntax: why arithmetic creates new immutable results, why multiplication changes algorithms, why decimal strings are work, and how fixed-width 64-bit APIs fit into the picture.

Sign, length, and 64-bit digits

The primary source is V8's src/objects/bigint.h. BigIntBase stores sign and length in one atomic bitfield, defines digit_t = uintptr_t, and exposes a flexible digit array. On the Node 22 build used by the tests, uintptr_t is 64 bits, so 2n ** 64n prints two digits: 0x0 then 0x1.

1// Node-only: run 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}

The test asserts only stable text: [BigInt], BIG_INT_BASE_TYPE, instance size: variable, length, sign, and digit lines. It does not assert addresses or exact object sizes. Node 22 here uses V8 12.4 without pointer compression; Chrome uses pointer compression, the sandbox, and a newer V8, so address-looking details differ.

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 computes the same little-endian digits with real BigInt operations: mask with 0xffffffffffffffffn, then shift by 64n. Its byte count is labelled as a teaching model so it does not pretend to be a heap inspector.

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);

1n === 1n compares the BigInt value. The Map lookup and the Set size show that BigInt keys use value hashing, not heap-object identity.

Addition is digit-by-digit

Addition and subtraction walk the digit arrays with carries or borrows. A one-digit add is cheap; a thousand-digit add touches roughly a thousand digits. V8 creates a fresh BigInt result because BigInt values are immutable. The public value is primitive, but the internal result storage still has to be allocated unless the compiler can avoid it in a narrower optimized path.

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));

Line 17 in the walkthrough is the whole trick: add one 64-bit lane from the left, one from the right, and the carry. Line 18 stores the low 64 bits, and line 19 carries the overflow into the next digit. The final line checks the teaching implementation against native BigInt addition.

Multiplication algorithms

V8's bigint-internal.h sets the thresholds. The operation dispatcher in bigint-internal.cc chooses based on the shorter operand's digit count. The 2018 V8 BigInt blog explains the original schoolbook implementation; V8 12.4 also ships Karatsuba, Toom-Cook-3, and FFT files.

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

The FFT file says the algorithm is due to Schönhage and Strassen. The build flag v8_advanced_bigint_algorithms is enabled by default except on Android; without it, the source falls back to Karatsuba for larger products.

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());

Karatsuba saves work by replacing two cross multiplications with one product of sums and two subtractions. The walkthrough uses base 1000n so the split is readable; V8 splits in machine-word digits.

Converting to and from strings

BigInt values store binary digits, not decimal text. tostring.cc uses a special base-power-of-two path for radices like 16, and a divide-and-conquer path for large non-power radices. fromstring.cc parses large inputs by combining neighboring chunks so fast multiplication can help.

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

Printing a huge decimal BigInt is expensive because the engine must convert from base 2**64 digits to base 10 characters. That is useful work, not a cached property read.

BigInt64 fast paths and typed arrays

Fixed-width APIs are different from arbitrary-precision BigInt arithmetic. BigInt.asIntN(64, value) and BigInt.asUintN(64, value) keep the low 64 bits. BigInt64Array and BigUint64Array store raw 64-bit lanes in an ArrayBuffer; reading an element gives JavaScript a BigInt value.

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));

The byte view proves the buffer holds raw bytes: writing -1n to a signed lane fills the first eight bytes with 255. The read still returns a BigInt primitive, not a Number.

Maximum BigInt size

BigInt means arbitrary precision, not infinite precision. V8's BigInt::kMaxLengthBits is 1 << 30, about one billion bits. That value is in src/objects/bigint.h, beside the note that V8 chooses a platform-independent limit below the implementation maximum.

1// Node-only guard: V8 rejects the result length before allocating the value.2try {3  2n ** (2n ** 30n);4} catch (error) {5  console.log(error.name + ": " + error.message);6}

Other engine layouts

The language rules are shared by the ECMAScript BigInt specification, but engines can choose different private storage. These source snapshots are useful comparisons, not portability hooks.

JavaScriptCore's JSCJSValue.h has EncodeAsBigInt32 and a BigInt32Tag under USE(BIGINT32), but WebKit's platform header currently defines USE_BIGINT32 0. SpiderMonkey's BigIntType.h defines InlineDigitsLength and uses inline digits until the value needs heap digit storage.

Practical use

Use Number when values fit inside Number.MAX_SAFE_INTEGER, when decimals matter, or when you need Math APIs. Use BigInt for exact large integers: database IDs, cryptographic math, bit masks, counters that cross 53 bits, and 64-bit protocol fields.

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

• Keep Number and BigInt arithmetic separate; convert deliberately at boundaries.
• Use BigInt.asUintN(64, value) or BigInt.asIntN(64, value) when the domain is fixed-width.
• Do not convert a large decimal ID through Number first; parse the string with BigInt(text).
• Measure hot paths. Algorithm thresholds and BigInt64 lowering are engine facts, not universal timing claims.

Common misconceptions

• “Small BigInts are immediate values.” Not in V8 12.4. The tests prove 10n is a [BigInt] heap object.
• “BigInt has no maximum.” V8 sets a maximum bit length and throws a RangeError when the result would exceed it.
• “BigInt64Array stores BigInt objects in the buffer.” The buffer stores raw 64-bit lanes; reads produce BigInt values.
• “Decimal printing is free.” Converting binary digits to decimal characters is an algorithm with real cost.

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 BigInts are heap objects with a sign, a length, and little-endian machine-word digits.
• Zero has length zero; 2n ** 64n has digits 0x0 and 0x1 on the verified 64-bit build.
• Addition is linear in digit count; multiplication switches from schoolbook to Karatsuba, Toom-Cook, and FFT at verified thresholds.
• String conversion and parsing are real algorithms, especially for large decimal inputs.
• Use BigInt for exact large integers, and use asUintN(64)/asIntN(64) for fixed-width lanes.

One-line definition: A BigInt is an exact integer value that V8 stores as an immutable heap object containing sign, length, and machine-word digits.

Up next: Symbols inside the engine.