Hidden classes & object shapes

Dynamic objects can still get a fixed layout

JavaScript lets you add, update, delete, freeze, and reorder object properties at runtime. That flexibility looks hostile to fast machine code: how can an engine load user.name quickly if every object can be a different bag of names?

V8 calls these records maps. SpiderMonkey talks about shapes. JavaScriptCore talks about structures. The names differ, but the job is similar: give dynamic objects a stable layout that inline caches and optimizers can guard. The Inline caches lesson introduced the guard; here we inspect the layout behind that guard.

We will stay honest about boundaries. JavaScript semantics come from the language: property lookup, descriptors, prototypes, freezing, and deletion. Hidden classes are implementation details. The Node-only probes use V8 12.4 diagnostics; other engines use their own data structures and can change details between releases.

Maps, shapes, and structures

Start with a tiny clue you can see in normal JavaScript: property insertion order. The three tickets below have the same names, but Meera's object inserts platform before name. Browsers do not expose hidden classes, so this snippet only prints keys. The Node probe after it checks V8 maps directly.

1function makeTicket(name) {2  return { name, platform: 2, paid: true };3}4 5const asha = makeTicket("Asha");6const ravi = makeTicket("Ravi");7const meera = { platform: 2, name: "Meera", paid: true };8 9console.log(Object.keys(asha).join(","));10console.log(Object.keys(ravi).join(","));11console.log(Object.keys(meera).join(","));

1function Point(x) {2  this.x = x;3}4 5const a = { x: 1, y: 2 };6const b = { x: 3, y: 4 };7const c = { y: 2, x: 1 };8const p = new Point(1);9const q = new Point(2);10 11console.log("node", process.version);12console.log("v8", process.versions.v8);13console.log("same order", %HaveSameMap(a, b));14console.log("different order", %HaveSameMap(a, c));15console.log("constructor start", %HaveSameMap(p, q));16p.y = 2;17console.log("after one transition", %HaveSameMap(p, q));18q.y = 3;19console.log("after both transition", %HaveSameMap(p, q));

Primary sources use these names too: the V8 maps documentation introduces maps, descriptor arrays, and transition arrays; Fast properties in V8 explains named properties and elements; and Mathias Bynens and Benedikt Meurer's Shapes and Inline Caches article compares the terminology across engines.

Transition chains and trees

A new empty object starts at a root layout. Adding a new property follows an edge to another layout. Add name, then score, and you reach one map. Add score, then name, and you reach a sibling map. That is why property order matters even when the final set of names matches.

1const transitions = new Map();2function nextMap(current, property) {3  const key = current + "->" + property;4  if (!transitions.has(key)) transitions.set(key, current + "." + property);5  return transitions.get(key);6}7 8function makeRecord(label) {9  return { label, map: "Root", slots: {} };10}11 12function store(record, property, value) {13  record.map = nextMap(record.map, property);14  record.slots[property] = value;15  return record;16}17 18const asha = makeRecord("Asha");Run19store(asha, "name", "Asha");20store(asha, "score", 10);21const ravi = makeRecord("Ravi");22store(ravi, "name", "Ravi");23store(ravi, "score", 20);24const meera = makeRecord("Meera");25store(meera, "score", 30);26store(meera, "name", "Meera");27 28console.log(asha.map === ravi.map);29console.log(asha.map === meera.map);

Line 19 and line 20 put Asha on the name → score chain. Ravi follows the same chain on lines 22 and 23, so line 28 prints true. Meera takes score → name on lines 25 and 26, so line 29 prints false.

1const asha = objectWith(["x", "y"]);2const ravi = objectWith(["x", "y"]);3const meera = objectWith(["y", "x"]);4 5console.log(asha.map === ravi.map);6console.log(asha.map === meera.map);7console.log(treeFromRoot());

Descriptor arrays: the property list behind maps

A map does not only say “this object has a shape.” It points at descriptors: metadata for each named property, such as the property name, attributes, representation, and field offset. V8's docs call this structure a DescriptorArray. Transitional maps can share a descriptor array and use a descriptor count as a prefix.

1const one = {};2one.x = 1;3const two = {};4two.x = 1;5two.y = 2;6 7console.log("ONE");8%DebugPrint(one);9console.log("TWO");10%DebugPrint(two);

That shared array is why the word “hidden class” can mislead. The layout record is not a JavaScript class body. It is a compact engine data structure that lets several related maps agree on property metadata while each map represents a different point in the tree.

In-object, fast, and slow properties

V8 separates named properties from array elements. Named properties can live directly inside the object body, or in a separate properties backing store. Both are still “fast properties” when the map and descriptors tell the engine where to look. Slow or dictionary properties trade fixed offsets for flexible updates.

1const fast = { name: "Asha", score: 0, active: true };2const extended = { name: "Ravi", score: 0, active: true };3extended.city = "Pune";4 5console.log(Object.keys(fast).join(","));6console.log(Object.keys(extended).join(","));7console.log("city" in extended);

1const removedMiddle = { a: 1, b: 2, c: 3 };2console.log("fast before delete", %HasFastProperties(removedMiddle));3delete removedMiddle.b;4console.log("fast after delete middle", %HasFastProperties(removedMiddle));5 6const removedLast = { a: 1, b: 2, c: 3 };7delete removedLast.c;8console.log("fast after delete last", %HasFastProperties(removedLast));9 10const many = {};11for (let i = 0; i < 80; i += 1) many["p" + i] = i;12console.log("fast after many", %HasFastProperties(many));13 14const frozen = { a: 1, b: 2 };15console.log("fast before freeze", %HasFastProperties(frozen));16Object.freeze(frozen);17console.log("fast after freeze", %HasFastProperties(frozen));18console.log("is frozen", Object.isFrozen(frozen));

Slack tracking trims early extra space

V8 gives new constructor instances a little extra in-object space at first. That is slack tracking: the engine leaves room in case later initialization code adds more fields, then trims unused space after enough constructions. The V8 slack-tracking post describes a construction counter initialized around seven and an extra-property allowance used during this settling period.

1function Seat(name) {2  this.name = name;3  this.paid = true;4}5 6const first = new Seat("Asha");7console.log("FIRST");8%DebugPrint(first);9 10for (let i = 0; i < 12; i += 1) new Seat("warm" + i);11const later = new Seat("Ravi");12console.log("LATER");13%DebugPrint(later);14console.log("same map after trim", %HaveSameMap(first, later));

Dictionary mode, `delete`, and `freeze`

Dictionary mode is not a punishment. It is the representation an engine can choose when fixed offsets are no longer the best fit. Deleting named properties creates holes in the descriptor-based layout. Adding many unpredictable names also starts to look like a dictionary workload. Freezing is different: it changes mutability and extensibility, but V8 can keep fast storage for small completed objects.

1const row = { id: 1, name: "Asha", city: "Pune" };2delete row.city;3 4const settings = { theme: "dark", compact: false };5Object.freeze(settings);6 7console.log(Object.keys(row).join(","));8console.log(Object.isFrozen(settings));9console.log(settings.theme);

1const removed = { id: 1, name: "Asha", city: "Pune" };2delete removed.city;3console.log("delete stays fast", %HasFastProperties(removed));4 5const settings = { theme: "dark", compact: false };6console.log("freeze before", %HasFastProperties(settings));7Object.freeze(settings);8console.log("freeze after", %HasFastProperties(settings));9console.log("frozen map differs", %HaveSameMap({ theme: "dark", compact: false }, settings));

1const dictionary = { a: 1, b: 2, c: 3 };2delete dictionary.b;3console.log("DICTIONARY");4%DebugPrint(dictionary);5 6const frozen = { a: 1, b: 2 };7Object.freeze(frozen);8console.log("FROZEN");9%DebugPrint(frozen);

Shape deprecation and migration

A map can become stale when the field representation it promised is no longer good enough. In V8, changing one object's field from a small integer to a double can create a replacement map. Other objects still on the old map may migrate lazily the next time they are accessed.

1const a = { map: "M1:x=Smi", x: 1 };Run2const b = { map: "M1:x=Smi", x: 2 };3console.log(a.map === b.map);4 5b.x = 1.5;6b.map = "M2:x=Double";7const deprecated = "M1:x=Smi";8console.log(a.map === b.map);9 10if (a.map === deprecated) {11  a.x = Number(a.x);12  a.map = "M2:x=Double";13}14console.log(a.map === b.map);

1const a = { x: 1 };2const b = { x: 2 };3console.log("start same", %HaveSameMap(a, b));4 5b.x = 1.5;6console.log("after double same", %HaveSameMap(a, b));7 8console.log("A BEFORE");9%DebugPrint(a);10console.log("access", a.x);11console.log("A AFTER");12%DebugPrint(a);13console.log("after access same", %HaveSameMap(a, b));

Practical habits for developers

Most code should not think about hidden classes all day. The useful habits are simple: initialize expected fields in the same order, avoid delete on measured hot objects, prefer null or undefined for “not present yet” when the shape should stay stable, and measure before changing clear code.

1function makeCard(name, city) {2  return {3    name,4    city,5    selected: false,6    error: null,7  };8}9 10const first = makeCard("Asha", "Pune");11const second = makeCard("Ravi", "Kochi");12second.error = "missing phone";13first.error = null;14 15console.log(Object.keys(first).join(","));16console.log(Object.keys(second).join(","));

• Use factories or constructors that create the same fields in the same order for many similar objects.
• Set a field to null or undefined instead of deleting it when the object stays hot.
• Keep object shapes boring at the edges of render loops, parsers, and data transforms you have actually profiled.
• Link this layout lesson to inline caches, prototype internals, property descriptors, and freezing and sealing rather than re-learning those topics here.

Common misconceptions

• “Hidden classes are JavaScript classes.” They are engine layout records, not language syntax.
• “Same properties always means same shape.” Order, attributes, representations, prototypes, and transitions can matter.
• “Delete is always optimized away if it removes the last field.” The V8 12.4 probe in this lesson did not show that; both deletes became slow properties.
• “Freeze makes objects slow.” Freezing changes the map, but small frozen objects can still have fast properties.
• “Engine internals should override readability.” Stable shapes are useful only when a measured hot path points there.

Practice exercises

const transitions = new Map();
function nextMap(current, property) {
  const key = current + "->" + property;
  if (!transitions.has(key)) transitions.set(key, current + "." + property);
  return transitions.get(key);
}

function makeRecord(label) {
  return { label, map: "Root", slots: {} };
}

function store(record, property, value) {
  record.map = nextMap(record.map, property);
  record.slots[property] = value;
  return record;
}

const asha = makeRecord("Asha");
store(asha, "name", "Asha");
store(asha, "score", 10);
const ravi = makeRecord("Ravi");
store(ravi, "name", "Ravi");
store(ravi, "score", 20);
const meera = makeRecord("Meera");
store(meera, "score", 30);
store(meera, "name", "Meera");

console.log(asha.map === ravi.map);
console.log(asha.map === meera.map);

function makeRow(name) {
  return { name, score: 0, active: true };
}
console.log(Object.keys(makeRow("Asha")).join(","));

function makeRow(name) {
  return { name, score: 0, active: true };
}
console.log(Object.keys(makeRow("Asha")).join(","));

const a = { map: "M1:x=Smi", x: 1 };
const b = { map: "M1:x=Smi", x: 2 };
console.log(a.map === b.map);

b.x = 1.5;
b.map = "M2:x=Double";
const deprecated = "M1:x=Smi";
console.log(a.map === b.map);

if (a.map === deprecated) {
  a.x = Number(a.x);
  a.map = "M2:x=Double";
}
console.log(a.map === b.map);

Check your understanding

Answer by separating language behavior from V8 implementation facts, then trace the small code snippets in order.

Key takeaways

• Hidden classes, maps, shapes, and structures are engine layout records for dynamic JavaScript objects.
• Adding properties creates transition chains; same names in different orders can land on different maps.
• Descriptor arrays describe properties and offsets, and maps on a transition chain can share them.
• Fast properties use fixed layouts; dictionary mode handles deletes and heavy property churn.
• Slack tracking trims early unused in-object fields, while representation changes can deprecate and migrate maps.
• Use consistent shapes naturally, avoid hot deletes, and measure before optimizing.

You came from Symbols inside the engine. Up next: Fast arrays & elements kinds, where array storage gets its own set of layouts and transitions.