63. Shapes in depth

Same keys, different objects

Here are four objects with the same two properties, and a V8 internal, %HaveSameMap, that asks whether two objects have the same shape:

// node --allow-natives-syntax shapes.js
const a = { x: 1, y: 2 };
const b = { x: 5, y: 6 };
const c = { y: 2, x: 1 };
const d = {}; d.x = 1; d.y = 2;
const e = {}; e.x = 7; e.y = 8;
console.log(%HaveSameMap(a, b));
console.log(%HaveSameMap(a, c));
console.log(%HaveSameMap(d, e));
console.log(%HaveSameMap(a, d));

Node v22.23.4, V8 12.4.254.21
true
false
true
false

a and b match. a and c don’t, though they differ only in order. And a and d don’t either, though they have the same keys in the same order. By the end of this chapter all four answers will be obvious.

A shape is a shared description

Chapter 22 showed that every V8 object starts with a pointer to its hidden class. Engine writers also say shape, and V8’s own name is map^[2]. The map holds the layout: which named properties exist, in what order, and where each value is stored. The names themselves live in the map’s descriptor array, not in the object^[1]. The object holds only the values.

Compare Drip. In chapter 59 every Drip instance kept its own hash table of fields, names and all. Ten thousand Drip particles meant ten thousand tables, each storing "x" and "y" again. V8 stores the names once, in a map, and shares it.

Shapes form a tree

JavaScript has no fixed classes: any object can gain a property at any time. So V8 can’t know a shape in advance. Instead, each time an object gets a new property, it moves to a new shape, and V8 links the shapes together^[1]. Step through it:

const a = {};
a.x = 1;
a.y = 2;
const b = {};
b.x = 5;
b.y = 6;
const c = {};
c.y = 2;
c.x = 1;

The tree is what makes sharing work. A second object built the same way follows the same transitions and ends at the same shape. An object built in a different order walks down a different branch. In V8’s source each map keeps a back pointer to the map it came from^[3], and you can see it in V8’s debug output:

// %DebugPrint(d), trimmed to fit
DebugPrint: 0x37f774024609: [JS_OBJECT_TYPE]
 - map: 0x36122091bff1 <Map[56]...>
     [FastProperties]
 - All own properties ...: {
    #x: 1 (const data field 0) ...
    #y: 2 (const data field 1) ...
 }
0x36122091bff1: [Map] in OldSpace
 - instance size: 56
 - inobject properties: 4
 - unused property fields: 2
 - back pointer: 0x36122091bfa9 <Map[56]...>

That explains a against c. And a against d? Look at d’s map above: four in-object slots, two of them unused. d started as {}, and in this run V8 gave the empty object room for four properties. The literal { x: 1, y: 2 } got exactly two slots: %DebugPrint(a) in the same session showed inobject properties: 2. Different layouts, so different maps.

const a = { x: 1, y: 2 };
const c = { y: 2, x: 1 };
console.log(Object.keys(a));
console.log(Object.keys(c));
console.log(JSON.stringify(a));
console.log(JSON.stringify(c));
// Code can see the order, so an
// engine must remember it: that is
// why order is part of a shape.

Room to grow: slack tracking

Objects made by a constructor get the same trick, more generously. In 2020 the V8 team described slack tracking: a new object gets extra in-object space, and after seven constructions V8 shrinks the shape to what was actually used. The starting estimate is the properties the compiler expects, plus eight^[2]. You can watch it:

function P(x, y) { this.x = x; this.y = y; }
%DebugPrint(new P(1, 2));
for (let i = 0; i < 10; i++) new P(i, i);
%DebugPrint(new P(3, 4));

Node v22.23.4, V8 12.4.254.21
// first object
 - instance size: 104
 - inobject properties: 10
 - unused property fields: 8
 - construction counter: 6
// after eleven more
 - instance size: 40
 - inobject properties: 2
 - unused property fields: 0
 - construction counter: 0

Ten slots (two expected, plus eight), then two: 104 bytes per object became 40.

When V8 gives up: dictionary mode

Shapes pay off when many objects share a few layouts. If a program keeps adding and deleting properties, maintaining all those shapes costs more than it saves. So V8 can switch an object to slow properties: a self-contained hash table that holds names and values together, like a Drip instance^[1].

const p = { x: 1, y: 2, z: 3 };
p.z = undefined;
console.log(%HasFastProperties(p));
delete p.z;
console.log(%HasFastProperties(p));

let last = true;
for (let n = 1; n <= 40; n++) {
  const o = {};
  for (let i = 0; i < n; i++) {
    o['k' + i] = i;
  }
  const f = %HasFastProperties(o);
  if (f !== last) console.log(n, f);
  last = f;
}

Node v22.23.4, V8 12.4.254.21
true
false
20 false

Setting p.z to undefined kept the shape. delete turned p into a dictionary, and its map now says dictionary_map. Adding properties under computed names turned an object into a dictionary at 20 properties in this version. Don’t memorize that number: it is an engine detail.

Your turn

const ROOT = {
  keys: [], next: new Map(),
};

function addProp(shape, key) {
  return {
    keys: [...shape.keys, key],
    next: new Map(),
  };
}

function shapeOf(keys) {
  let s = ROOT;
  for (const k of keys) {
    s = addProp(s, k);
  }
  return s;
}
function slotOf(shape, key) {
  return shape.keys.indexOf(key);
}

function orderMismatches(objs) {
  return [];
}

What you learned

• A shape (V8’s map) describes an object’s layout once; objects that share it store only their values.
• Shapes form a transition tree: adding a property follows or creates an edge, so the order of additions decides the shape.
• How an object is made matters too: literals, {} plus additions and constructors get different in-object space, and constructors shrink theirs after a few objects (slack tracking).
• Dictionary mode replaces the shared shape with a per-object hash table. delete triggers it here; reads get slower.
• Build objects of one kind the same way, in the same order, and don’t delete their fields.

Next: how V8 uses shapes to make o.x fast at one particular line of code.