What a Map really is: opening the hidden class

The object is almost empty; the Map holds the knowledge

You saw the overview in browser/03-v8-internals/03-hidden-classes: objects sharing a hidden class share the fast inline-cache path. Here we open that box. The single most important structural fact in V8 is this: a JavaScript object carries almost no metadata of its own. A plain object’s body in memory is just a small contiguous block:

[ map pointer ][ properties pointer ][ elements pointer ][ in-object slot 0 ][ slot 1 ] ...

The first word is a pointer to a Map (V8’s name for the hidden class; Shape in SpiderMonkey, Structure in JavaScriptCore). Everything that tells V8 what this object is — which property names exist, where each one lives, what type each holds — is not in the object. It is in the Map. The object only stores the values, packed into anonymous slots at fixed byte offsets. The names and offsets live one indirection away, in the shared Map.

That is the whole trick. Because the layout knowledge is factored out into the Map, a property read p.x can compile to: load the map pointer, compare it to the map the inline cache expects, and on a match load the slot at a hard-coded offset. No name comparison, no hash lookup — the name x was resolved to an offset once, at the Map level, and reused for every object that shares that Map.

Inside the DescriptorArray

Before you can read the DescriptorArray correctly, ask yourself: what exactly do you need to know per property to compile a property access to a single load? The answer lives here.

The heart of the Map is the DescriptorArray — the table that turns a property name into everything V8 needs to read or write it. One entry per named (string-keyed) own property, in declaration order. Each descriptor records:

• The key — the (usually interned) property name, e.g. "x". Interned names compare by pointer, so finding a descriptor is a pointer scan, not a string compare.
• The field index — which slot holds the value, and whether that slot is in-object (inline in the object body) or out-of-object (in a separate PropertyArray). We open this fully in lesson 03.
• The representation — what kind of value the field is statically known to hold: Smi (small integer, unboxed), Double (an unboxed 64-bit float stored in a “mutable HeapNumber” slot), HeapObject (a pointer to any heap object), or Tagged (anything — the most general). Narrower representations let TurboFan skip boxing and type checks.
• Constness — const if the field has only ever been assigned one value across all instances of this Map (so the compiler may inline the value), or mutable once a second value appears.
• Attributes — the property’s writable / enumerable / configurable bits, plus whether it is a plain data field, a const data slot folded into the descriptor, or an accessor (getter/setter) pair.

Together these five fields mean that once the Map is shared, V8 knows exactly how to read or write any property without touching the object itself — if you remove any one of them (say, representation), the compiler can no longer skip boxing or choose the right instruction; without field index, it cannot find the slot at all.

// Logical contents of the DescriptorArray for an object built as { x: 1, y: 2.5 }:
// index 0:  key="x"  field#=0  rep=Smi      const=true  attrs=W,E,C  storage=in-object
// index 1:  key="y"  field#=1  rep=Double   const=true  attrs=W,E,C  storage=in-object

Crucially, two different Maps can share the same DescriptorArray — a parent Map and a child Map that only added one property at the end can point at the same backing descriptor array, with the child declaring it owns one more descriptor than the parent. This is why building a tree of related shapes is cheap: most of the descriptor data is reused, not copied.

The back-pointer and transitions: a Map knows its neighbours

A Map is a node in a tree, and it stores the edges:

• The back-pointer points to the Map this one was derived from — the layout before the last property was added. V8 walks back-pointers to find a common ancestor when reconciling shapes, and (as we will see in lesson 02) to migrate deprecated layouts.
• The transitions pointer points forward, into a TransitionArray keyed by {property name, attributes}, to the child Maps reached by adding the next property. Adding "y" to a Map-for-{x} follows (or creates) the "y" transition edge to the Map-for-{x,y}.

So a Map is simultaneously a description of the current layout and a router to neighbouring layouts. That dual role is what makes shape transitions O(1) amortised and what makes the whole shape graph shareable across the isolate.

You can see all of this directly. In d8 --allow-natives-syntax, %DebugPrint(obj) prints the object’s Map address, its DescriptorArray with each property’s representation and field index, the elements kind, and the prototype. Two objects that “share a hidden class” print the same Map address; two that diverged print different ones.