Hidden classes & object shapes

Objects can change, but they still get a fixed plan

In JavaScript you can add a property to an object at any time. You can also change it, delete it, or freeze the whole object. That makes objects very flexible.

The engine is the program that runs your JavaScript. Chrome and Node use an engine called V8. The engine wants to read a property like user.name fast. But if any object could hold any names in any order, the engine would have to search the object for name on every read. Searching is slow.

Each engine has its own word for this plan. V8 calls it a map. Firefox's engine, SpiderMonkey, calls it a shape. Safari's engine, JavaScriptCore, calls it a structure. They all do the same job. This lesson uses V8's word, map.

The Inline caches lesson showed how one line of code remembers the map it saw last time, so the next read only needs a quick check. This lesson looks inside that map.

Two kinds of facts appear in this lesson. Keep them apart:

• Language rules are what your code can see, like property order, delete, and freezing. They are the same in every engine.
• Engine facts are how V8 stores objects inside. Your code can't see them, and they can change between versions. The lesson checks them in Node 22, which uses V8 12.4.

Objects built the same way share a map

Normal JavaScript can't show you a map. But it can show one clue: the order of property names. Object.keys(obj) returns an object's property names, in the order they were added.

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

• Lines 1 to 3 make a function, makeTicket. It always builds a ticket with name, then platform, then paid.
• Lines 5 and 6 build Asha's and Ravi's tickets with it.
• Line 7 writes Meera's ticket by hand, with platform first.
• Lines 9 to 11 print name,platform,paid twice, then platform,name,paid.

Asha's and Ravi's tickets were built the same way, so V8 gives them one map. Meera's ticket has the same names in a different order, so it gets a different map. Normal code can't check this. The next code can.

V8 has special test functions whose names start with %. For example, %HaveSameMap(a, b) returns true when two objects share one map. These functions only work when you start Node with node --allow-natives-syntax. They are not part of JavaScript, so never use them in a real app.

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

• Lines 11 and 12 print the Node and V8 versions.
• Lines 5 and 6 add x, then y. Line 13 prints same order true.
• Line 7 adds y first. Line 14 prints different order false.
• Lines 8 and 9 build two objects with the Point constructor. A constructor is a function you call with new to build objects. Line 15 prints constructor start true.
• Line 16 adds y to p only. Line 17 prints after one transition false.
• Line 18 adds y to q too. Line 19 prints after both transition true.

The table below lists each engine's word for a map. Read each row as: this engine, its word, and one thing to remember.

You can read more from the engine teams. The V8 maps documentation explains maps and the lists they point to. Fast properties in V8 explains where property values are stored. Mathias Bynens and Benedikt Meurer's Shapes and Inline Caches compares the words different engines use.

Adding a property moves an object to the next map

A new, empty object starts on a first map with no names. The step-through below calls it Root. When you add a property, the object moves to a new map that has one more name. That move is called a transition.

• Add name, then score: the object goes from Root to Root.name to Root.name.score.
• Add score, then name: it goes from Root to Root.score to Root.score.name.

All these moves together form a tree that starts at Root. One path through the tree is a transition chain. Objects that add the same names in the same order follow the same chain, and end on the same map.

The step-through is a small model written in plain JavaScript. It isn't V8, but it follows the same rule. Each record keeps its map name as text in record.map. transitions is a JavaScript Map, a list of keys and values. Here it remembers every move made so far, so nextMap reuses a move another record already made.

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

Lines 19 and 20 move Asha along the chain Root.name, then Root.name.score. Ravi follows the same chain on lines 22 and 23, so line 28 prints true. Meera adds score first on lines 25 and 26, so line 29 prints false.

Now build your own tree. Add x, y, or z to a new object in any order, then save it and build another. The map names M0, M1, and so on are numbers the model makes up as it creates each map.

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 list of names behind a map

A map points to a list with one entry for each property. Each entry is called a descriptor. A descriptor holds:

• the property name,
• its settings, like whether it can be changed (the property descriptors lesson covers these),
• what kind of value it holds, like a small whole number,
• the slot where its value lives.

V8 keeps these entries in a list called a DescriptorArray. Maps on one chain can share one descriptor array. The map for { x } and the map for { x, y } can use the same array. The first map just reads fewer entries: only the first one.

The next code uses another V8 test function, %DebugPrint(obj). It prints V8's own report about an object, including its map and the address of its descriptor array. An address is the place in memory where something is stored.

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

• Lines 1 and 2 give one the map for { x }.
• Lines 3 to 5 give two the map for { x, y }, one step further along the same chain.
• Lines 8 and 10 print V8's report for each object.

This is why the name "hidden class" can mislead. It isn't a class you write in JavaScript. It is a small record inside the engine, and maps on the same chain share parts of it.

Where property values are stored

V8 keeps two kinds of properties apart:

• Named properties, like user.name. This section is about these.
• Elements, the numbered entries of an array, like list[0]. The next lesson covers those.

A named property's value can live in one of three places:

• In the object itself ("in-object"). This is the fastest place.
• In an extra list beside the object, called the properties backing store. The map still says which slot holds which name, so this is fast too.
• In a dictionary: the object keeps its own table of names and values, with no shared map to say where things are. This is flexible, but slower to read.

The first two are called fast properties. The dictionary kind is called slow properties, or dictionary mode.

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

• Lines 1 and 2 build two objects with the same three names.
• Line 3 adds city to extended afterwards.
• Lines 5 and 6 print the names. Line 7 prints true, because "city" in extended checks whether the property exists.

Nothing in this output says where V8 stored city. That stays hidden.

The table below lists the three places. Read each row as: where the value lives, what that means, and why V8 uses it.

The next code uses one more V8 test function, %HasFastProperties(obj). It returns true when the object uses fast properties, and false when it uses a dictionary.

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 spare space

When you build objects with a constructor, V8 doesn't know yet how many properties they will end up with. So the first objects get some spare in-object slots, just in case. This spare room is called slack.

After a number of objects have been built, V8 looks at how many slots were really used. Then it trims the spare ones from the map. This is slack tracking. V8's slack tracking post says the counter starts at about seven constructions.

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

• Lines 1 to 4 make the Seat constructor. It gives every seat two properties.
• Line 6 builds the first seat, and line 8 prints V8's report about it.
• Line 10 builds 12 more seats, which ends the warm-up.
• Line 11 builds one more seat, and line 13 prints its report.
• Line 14 checks whether first and later share a map.

Dictionary mode, delete, and freeze

In dictionary mode, an object keeps its own table of names and values, instead of using a shared map's slots. This isn't an error or a punishment. V8 picks it when fixed slots stop being a good fit:

• after you delete a named property, which leaves a gap in the plan,
• after you add many different names to one object, one by one.

Freezing is different. Object.freeze(obj) makes an object read-only: nothing can be added, removed, or changed. V8 moves a frozen object to a new map, but a small frozen object can keep fast properties.

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

• Line 2 removes city from row.
• Line 5 freezes settings.
• Line 7 prints id,name.
• Line 8 prints true. Object.isFrozen checks whether an object is frozen.
• Line 9 prints dark. Freezing keeps the values that were already there.

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("same map as unfrozen", %HaveSameMap({ theme: "dark", compact: false }, settings));

• Line 3 prints delete stays fast false: after the delete, the object uses a dictionary.
• Lines 6 and 8 print true before and after the freeze: the frozen object is still fast.
• Line 9 compares settings with a new unfrozen object that has the same names. It prints same map as unfrozen false: freezing moved settings to a new map.

The next code prints V8's full report for a deleted object and for a frozen object. The lesson test looks for a few words in them:

• For the deleted object: dictionary_map and NameDictionary. A NameDictionary is V8's table of names and values.
• For the frozen object: non-extensible, which means no new properties can be added, and stable_map.

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

The table below sums up these tests. Read each row as: what you do, what V8 12.4 did, and what the test saw.

Old maps get replaced: deprecation and migration

A map also remembers what kind of value each property holds. V8 has two kinds of numbers here:

• a Smi (short for "small integer") is a small whole number, like 1;
• a Double is a number with a decimal part, like 1.5.

A Smi is cheaper to store. So a new { x: 1 } gets a map that says "x is a Smi".

Now store 1.5 in x. It doesn't fit. V8 makes a new map that says "x is a Double" and moves the object there. The old map is marked deprecated, which means outdated.

Other objects still on the old map are not moved right away. Each one moves the next time it is used. That move is called migration.

The step-through is a model in plain JavaScript. Each object keeps its map name as text, like "M1:x=Smi".

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

• Line 3 prints true: a and b start on M1.
• Line 5 stores 1.5 in b.x, and line 6 moves b to M2. Line 8 prints false.
• Line 10 notices that a is still on the outdated map, and line 12 moves it. Line 14 prints true.

The real V8 code below does the same with real objects.

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

• Lines 1 to 3 build a and b, and print start same true.
• Line 5 stores 1.5 in b.x. Line 6 prints after double same false.
• Line 9 prints V8's report for a before it is used.
• Line 10 reads a.x. That read is the use that moves a.
• Line 12 prints the report again. Line 13 prints after access same true.

Habits that keep objects fast

Most of the time, you don't need to think about maps at all. A few simple habits are enough. The code below shows the first two.

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

• Lines 1 to 8 make makeCard. It builds every card with the same four properties, in the same order.
• error starts as null, which means "no error yet".
• Lines 10 and 11 build two cards. Line 12 sets Ravi's error to a message.
• Line 13 sets Asha's error to null instead of deleting it.
• Lines 15 and 16 print the same names for both cards: name,city,selected,error.

• Build similar objects with one function or constructor, so they get the same properties in the same order.
• To clear a property on an object your code uses a lot, set it to null or undefined instead of deleting it.
• Measure first. Change clear code only when a profiler, a tool that shows where your program spends its time, points at a slow spot.
• For related topics, see inline caches, prototype internals, property descriptors, and freezing and sealing.

Common misconceptions

• "Hidden classes are JavaScript classes." They are plans inside the engine. They have nothing to do with the class keyword.
• "The same property names always mean the same map." The order matters too. So do each property's settings, the kind of value it holds, and the object's prototype.
• "Deleting the last property keeps an object fast." Not in V8 12.4. The test deleted the middle property and the last one, and both objects stopped being fast.
• "Freezing makes objects slow." Freezing moves the object to a new map, but a small frozen object can keep fast properties.
• "Engine tricks matter more than clear code." Change code for maps only when a measurement shows a slow spot.

The table below lists four ideas that are easy to mix up. Read each row as: the idea, what it means, and what it is not.

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

For each question, first ask: is this a language rule your code can see, or a V8 fact? For code questions, run the lines in order in your head.

Key takeaways

• A hidden class is the engine's plan for an object. V8 calls it a map, SpiderMonkey a shape, and JavaScriptCore a structure.
• Adding a property moves an object to the next map. The same names in a different order end on a different map.
• A map points to a descriptor array, and maps on one chain can share it.
• Fast properties use fixed slots. Dictionary mode, used after a delete or many new names, uses the object's own table.
• Slack tracking trims spare slots from early objects. A value that doesn't fit, like a decimal, can replace a map, and old objects move later.
• Build similar objects the same way, avoid delete on objects you use a lot, and measure before you optimize.

You came from Symbols inside the engine. Up next: Fast arrays & elements kinds, where arrays get their own plans and transitions.