Hidden classes, transition trees, and memory layout

Two objects have the same properties. One was built with {x:1, y:2}, the other with {y:2, x:1}. To your code they look identical. To V8 they are different shapes — and whichever one ends up in a hot function first decides whether that function runs fast or slow.

What a hidden class is

JavaScript objects are dynamic — properties can be added, deleted, reordered — but V8 internally represents each object as a pointer to a hidden class (called “Map” in V8 source, “Shape” in SpiderMonkey) plus a sequence of property slots. Two objects with the same property names added in the same order share one hidden class.

When you add a property to an existing object, V8 transitions to a new hidden class along a “transition tree”. Adding “x” then “y” goes to one class; adding “y” then “x” goes to a different one — even though both objects have the same logical contents. The inline cache keys off the hidden class pointer. Stable hidden classes are the foundation of V8 performance.

Rules:

• Construct objects with all properties up front (in constructors or factory functions).
• Avoid delete on object properties — it forces a transition to a dictionary-mode object that is permanently slow.

The transition tree

const p = {}; p.x = 1; p.y = 2;
// HC path: HC_empty → HC_x → HC_x+y

const q = {}; q.x = 1; q.y = 2;
// Same path — q ends at same HC as p. ✓ monomorphic

const r = {}; r.y = 2; r.x = 1;
// HC path: HC_empty → HC_y → HC_y+x
// Different leaf — different HC from p and q. ✗ polymorphic at shared call site

The transition tree is shared across all objects in the V8 isolate. Pathological code that adds properties in dynamic order (JSON parsers writing properties in arbitrary input order, generated code) creates many leaf nodes — the same shape never repeats, ICs are perpetually polymorphic or megamorphic.

In-object vs out-of-object properties

V8 stores the first ~8 properties of an object inline in the object’s memory block. Subsequent properties go to an out-of-object PropertyArray pointed to by the object. Access to in-object properties is a single memory load; out-of-object adds one pointer dereference.

The in-object slot count is fixed at hidden class creation. For perf-critical objects, declare the most-accessed properties first in the constructor so they land in-object.

Dictionary mode: objects with too many properties (~32+) or many deletions transition to a HashMap-backed representation where every access goes through the slow generic path. Once in dictionary mode, the object is permanently slow — %HasFastProperties(obj) in d8 reports false.

Array element kinds

V8 tracks the “kind” of each array based on what it stores. Transitions are one-way — once you move to a wider kind, you cannot go back:

new Array(1000) creates a HOLEY array from the start. Array.from({length:1000}, () => 0) creates a PACKED array. Same logical result, 2–3× different access speed.

To keep an array PACKED_SMI: pre-allocate with [], add via push, never assign at indices above the current length.

Numeric specialisation: Smi, HeapNumber, double

V8 represents small integers (Smi) inline in a 64-bit pointer slot with the low bit cleared — no allocation, no indirection, arithmetic in one CPU instruction. Numbers outside the Smi range (±2³¹ on 64-bit) become HeapNumbers — boxed in a heap-allocated cell with a double inside. The Smi-to-HeapNumber transition is V8’s most common deopt trigger: a TurboFan-compiled loop assumes Smi, the value overflows once, deopt cascade. The fix: bound the integer range, or use Math.fround / explicit Float64Array.