Monomorphism discipline

One principle, six rules

When you know where deopts and megamorphic sites come from, the next question is: what habits prevent them in the first place? The answer is surprisingly compact.

V8’s optimised code is speculative: TurboFan compiles a function assuming the shapes and types it has seen so far keep arriving. Break that assumption and you pay — a deopt, a polymorphic IC, a dictionary-mode fall, a Smi-overflow bail-out. The discipline below is just “do not surprise the optimiser”. Each rule maps to a mechanism you have already met in this track (mono/poly/mega ICs, shape transitions, element kinds, Smi vs HeapNumber); here they become a checklist.

Rule 1 — construct with all fields in a fixed order

Build objects so every instance walks the same hidden-class transition path: declare all fields in a constructor or factory, in a constant order, with no conditional additions. Two objects with the same fields added in different orders are different shapes; a field added only sometimes creates a second shape. The fix for absent data is a default value, not omission:

// DON'T — conditional + late fields → many shapes
function makeRow(r) {
  const o = {};
  o.id = r.id;
  if (r.name) o.name = r.name;     // shape A vs shape B
  o.score = r.score;
  if (r.flagged) o.flag = true;    // shape C, D...
  return o;
}

// DO — one shape, every time
function makeRow(r) {
  return {
    id: r.id,
    name: r.name ?? null,
    score: r.score,
    flag: r.flagged === true,
  };
}

This single rule prevents the most common production regression: a hot access site going megamorphic because objects were built in input-key order. (See mono/poly/mega ICs for what megamorphic costs.)

Rule 2 — never delete; assign null

delete obj.x cannot just clear a slot — it forces the object out of its fixed-offset layout into dictionary mode, a hashmap-backed representation where every property access takes the slow generic path (~50–100 cycles vs 1) and the object never recovers. The memory you “save” is tiny; the slowdown is permanent. Set the field to null instead and the shape stays intact.

Rule 3 — keep an array one element kind

V8 tracks each array’s element kind and only widens it (one-way): PACKED_SMI_ELEMENTS (fastest) → PACKED_DOUBLE_ELEMENTS → PACKED_ELEMENTS (any type) → the HOLEY_* variants (add a hole-check on every access). Mixing a 1.5 into an array of integers widens it forever; writing past length or new Array(n) makes it HOLEY. Habits that keep it tight:

• Prefer [] + push over new Array(n) or index-beyond-length (both create HOLEY).
• Prefer Array.from({length}, fn) over new Array(n).fill() when you need a sized PACKED array.
• Do not store mixed types (Smi, double, object) in one hot array; split by kind or use a typed array.

Rule 4 — feed hot functions consistently-shaped arguments

A function’s inline caches key off the shapes and types of its arguments. Call render(node) with one node shape and the ICs stay monomorphic; call it with five different shapes and they go megamorphic, and TurboFan cannot specialise. If a hot function must accept variants, split it into shape-specific functions or normalise inputs to one shape before the hot loop.

Rule 5 — keep numbers in Smi range (or go typed)

A small integer (Smi, ±2^31 on 64-bit) lives inline in a pointer slot with arithmetic in one instruction; cross that boundary even once and the value becomes a heap-allocated HeapNumber, and a TurboFan loop that assumed Smi deopts with reason: Smi. Bound counters and ids inside the Smi range, or commit to doubles from the start with a Float64Array so the optimiser specialises on double and never has to bail. (See Smis and doubles for the Smi/HeapNumber boundary.)

Rule 6 — keep dispatch stable

A call site that invokes the same function (or one of a few stable functions) optimises well. A site that calls many different functions — a giant switch dispatching to dozens of handlers, or a method called polymorphically across many subclasses — goes megamorphic and loses inlining. Prefer a small, stable set of callees on hot paths; a Map of typed handlers built once beats rebuilding closures per call.