65. Elements kinds

Two arrays that look the same

To JavaScript, these hold the same kind of thing. typeof says 'number' for every element of both:

const a = [1, 2, 3];
const b = [1, 2, 3.5];

V8 sees two different arrays. Chapter 22 showed that it stores small integers as Smis and other numbers as doubles. If V8 knows an array holds only Smis, it can optimize operations on it for exactly that case^[1]. One stray 3.5 changes how the whole array is stored, and what the optimizing compiler may assume.

V8 keeps elements, the values at integer indices, apart from an object’s named properties^[3]. And for each array it tracks what kind of elements it holds^[1].

Three kinds, one way down

There are three basic kinds. SMI means every element is a small integer. DOUBLE means every element is a number, stored as a raw 64-bit double. ELEMENTS means anything goes: each slot is an ordinary tagged value. Each new value can push the array to a more general kind. Step through one array’s life:

const a = [1, 2, 3];
a.push(4.56);
a[3] = 4;
a.push('x');
a[9] = 1;

You can watch this happen. Node has a debugging function, %DebugPrint, hidden behind a flag (chapter 72 shows more of these tools). Run the first four lines of the stepper with %DebugPrint(a) after each one, and keep the lines that name the kind. Real output, Node v22.23.4 (V8 12.4):

$ node --allow-natives-syntax kinds.js \
    | grep 'elements kind'
 - elements kind: PACKED_SMI_ELEMENTS
 - elements kind: PACKED_DOUBLE_ELEMENTS
 - elements kind: PACKED_ELEMENTS
 - elements kind: HOLEY_ELEMENTS

The same output shows where the kind lives. It is part of the array’s map, the shape of chapter 63, and the change to a holey kind is listed as a map transition (addresses shortened):

 - map: 0x… <Map[32](PACKED_SMI_ELEMENTS)>
 …
   (transition to HOLEY_SMI_ELEMENTS)

It also names the backing store: a FixedArray for Smis and general values, a FixedDoubleArray once the array went DOUBLE.

Holes

Every kind comes in two flavours: PACKED and HOLEY. A hole is an index below the length with nothing in it:

const xs = [0, , 2];  // a hole at 1
const ys = [];
ys[3] = 'x';          // holes at 0, 1, 2

A hole is not the same as storing undefined. Reading one makes JavaScript look further, at the object the array inherits from, Array.prototype. Usually nothing is there and you get undefined. But try this:

const xs = [0, , 2];
console.log(xs.length);
console.log(Object.hasOwn(xs, 1));
console.log(xs[1]);

Array.prototype[1] = 'from proto';
console.log(xs[1]);
delete Array.prototype[1];

That is why holes are costly. For a packed array, V8 knows every index below the length has its own element. For a holey one, a read needs extra checks and may have to search the prototype chain^[1].

new Array(3) starts holey, because its three slots are empty. Filling them with integers leaves it HOLEY_SMI_ELEMENTS (V8 12.4 again). The post that describes the lattice adds a 2025 update: fill is now an exception to this rule^[1], a change too recent for Node 22. Starting from [] and pushing never makes a hole.

Kinds meet inline caches

Elements kinds matter most to optimized code. An element load like xs[i] has an inline cache (chapter 64), and it remembers the kinds it has seen. A helper called with arrays of Smis, of doubles and of strings sees three kinds. Its loads become polymorphic and must check which case they are in every time^[1]. One kind per call site keeps them monomorphic.

Your turn

function isSmi(v) {
  return Number.isInteger(v) &&
    !Object.is(v, -0) &&
    v >= -(2 ** 31) && v < 2 ** 31;
}

function kindAfter(start, ops) {
  // track the base kind, holes, length
  return 'PACKED_SMI_ELEMENTS';
}

function join(a, b) {
  return a;
}

What you learned

• Every array has an elements kind: SMI, DOUBLE or ELEMENTS, each PACKED or HOLEY.
• The kinds form a lattice, and an array only moves to more general kinds. Overwriting a double with an integer doesn’t move it back.
• -0, NaN, Infinity and large integers are doubles, not Smis.
• A holey array has empty indices. Reading a hole can reach the prototype chain, so holey arrays need extra checks. Build arrays with literals or push.
• The kind lives in the array’s map, and element loads’ inline caches see it: one kind per call site keeps them monomorphic.