Smis, doubles, and HeapNumbers

The Smi: an integer that costs nothing

Recall from the previous lesson that a value word is 64 bits and the low bit is the tag. For a Smi, the tag bit is 0 and the integer lives in the upper 32 bits of the word. That leaves room for a 31-bit signed integer on 64-bit V8 — a range of roughly ±2³⁰, i.e. about ±1.07 billion. (The bottom 32 bits are zero; this is sometimes described as the value being “shifted left by 32”.)

Why does this matter so much? Because a Smi needs no heap allocation and no dereference. The number is in the word. Adding two Smis is essentially one CPU instruction — the engine can use native integer arithmetic and just keep the tag arithmetic-friendly. No object is created, no memory is touched, no garbage is produced. This is the single fastest representation of a number JavaScript has, and it is why integer-heavy loops can rival C.

let sum = 0;
for (let i = 0; i < 1000; i++) sum += i;
// i and sum stay well inside Smi range:
// every += is integer math on a tagged word, zero allocations.

The HeapNumber: a box on the heap

The moment a number does not fit the Smi mould, V8 must represent it as a full IEEE-754 double (64 bits). But a double does not leave room for a tag bit in the same trick. So V8 boxes it: it allocates a HeapNumber — a tiny HeapObject whose payload is the 64-bit double — and the value word becomes a pointer to that box.

A number becomes a HeapNumber when it is any of:

• Outside the Smi range — magnitude beyond roughly ±2³⁰ (e.g. 2 ** 31, a large timestamp in milliseconds, a big counter).
• Not an integer — anything with a fractional part, like 0.5 or Math.PI.
• A special double — NaN, Infinity, -0.

Together these three cases mean that any number carrying real-world identity — a UTC timestamp, a floating-point sensor reading, a special sentinel — will always be a boxed HeapNumber. If you see one appearing in a tight loop, that is your allocation budget draining.

Now reading the number costs what every HeapObject costs: a pointer dereference and a memory load, plus the original allocation cost and the future GC cost of collecting the box. A HeapNumber is not catastrophic for a one-off value, but in a hot loop, allocating one per iteration is a real tax.

Unboxed doubles: V8’s escape hatch

If every fractional number meant a HeapNumber allocation, numeric arrays would be unusable. V8 avoids this with unboxed doubles. When V8 knows a storage location will only ever hold doubles, it stores the raw 64-bit double directly, with no box and no pointer:

• A PACKED_DOUBLE_ELEMENTS array (created when every element is a double) stores raw doubles back-to-back, like a C double[].
• A double field on an object: when a property has only ever held doubles, V8 stores the raw double inline in the object (a MutableHeapNumber / double-field representation), updating it in place instead of re-boxing.
• A Float64Array (a typed array) stores raw doubles by definition — there is never a HeapNumber.

The catch with object double-fields: because the storage is the raw double, not a tagged word, the object’s hidden class records “this field is a double”. If you later store a non-number there, V8 has to migrate the object’s shape — another reason to keep field types stable.

The classic deopt: Smi overflow in a hot loop

Here is the war story. TurboFan watches a hot loop, sees that a variable has always been a Smi, and compiles specialised integer machine code with a guard: “assume this stays a Smi.” That code is fast precisely because it skips the float path entirely.

Then one value overflows ±2³⁰. The guard fails. V8 deoptimises: it throws away the specialised code, falls back to the interpreter (Ignition), and the value becomes a HeapNumber. If the overflow keeps happening, V8 may re-optimise on the double path — but you have paid the deopt, and you are now allocating HeapNumbers.

// --trace-deopt would show a bailout the first time `acc` overflows Smi range.
function hash(arr) {
  let acc = 0;
  for (let i = 0; i < arr.length; i++) {
    acc = (acc * 31 + arr[i]);  // acc grows past 2**30 fast -> Smi overflow -> deopt
  }
  return acc;
}

The fixes, in order of preference:

• Bound the integer range. Keep accumulators within Smi range — e.g. mask with | 0 / >>> 0 or take a modulus each step so the value never overflows (acc = (acc * 31 + arr[i]) | 0 keeps it a 32-bit int; V8 handles | 0 results efficiently).
• Specialise on double from the start. If the data is genuinely floating-point, store it in a Float64Array or seed the array with a double so V8 picks PACKED_DOUBLE_ELEMENTS immediately and never assumes Smi.
• Use Math.fround when you want 32-bit float semantics, which also signals V8 to specialise on float rather than oscillate between Smi and double.

You can confirm any of this with node --trace-deopt --trace-opt your.js, or in d8 with %OptimizeFunctionOnNextCall(fn) + %GetOptimizationStatus(fn) under --allow-natives-syntax.