Fast arrays & elements kinds

Arrays keep their numbered values in a separate store

An array can hold any mix of values: numbers, strings, and objects. It can even have empty places. That makes arrays very flexible.

The engine is the program that runs your JavaScript. Chrome and Node use an engine called V8. V8 wants to read list[0] fast. So it keeps an array's numbered values in their own store, apart from named properties like list.name.

• The numbered values are called elements.
• The number in the square brackets, like the 0 in list[0], is called the index.

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

• Language rules are what your code can see, like an array's values and its length. They are the same in every engine.
• Engine facts are how V8 stores arrays 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.

This lesson follows the V8 team's article Elements kinds in V8. The Hidden classes lesson covered named properties. This one covers numbered elements. For how arrays behave in normal code, see array basics, iterating arrays, and typed arrays.

Packed arrays and holes

An array is packed when every index from 0 to length - 1 has a value. It is holey when at least one of those indexes has nothing at all. An index with nothing is called a hole.

A hole is not the same as undefined. After arr[0] = undefined, index 0 exists and holds the value undefined. A hole means index 0 does not exist at all.

The code below uses the in operator. 0 in arr is true when index 0 exists in arr, and false when it doesn't.

1const packed = ["Asha", "Ravi", "Meera"];2const holey = new Array(3);3holey[1] = "Ravi";4 5console.log(0 in packed);6console.log(0 in holey);7console.log(holey.length);

• Line 1 makes packed with three values, at indexes 0, 1, and 2.
• Line 2 makes holey with new Array(3). This sets the length to 3 but puts no values in. All three indexes are holes.
• Line 3 puts "Ravi" at index 1. Indexes 0 and 2 are still holes.
• Line 5 prints true: index 0 exists in packed.
• Line 6 prints false: index 0 is a hole in holey.
• Line 7 prints 3. The length counts the holes too.

Why does V8 care? When it reads from a packed array, it knows a value is there. When it reads from a holey array, it must check first.

If the index is a hole, JavaScript keeps looking in the array's prototype. That is the object the array gets its methods from, Array.prototype. This extra search costs time on every read.

V8 also remembers that an array was holey. If you fill the holes later, the label stays holey. It does not switch back to packed.

The table lists the labels this lesson uses. Read each row as: the label, how an array gets it, and what it means for speed.

Small whole numbers, any numbers, or any values

The second part of the label says what values the array holds. V8 has three groups:

• Smi, short for "small integer": small whole numbers like 1, 2, and 3. V8 can store these straight in the array with no extra work.
• Double: any number, including decimals like 2.5. "Double" is the name of the number format JavaScript uses for all its numbers.
• Generic: any value at all, such as strings, objects, and numbers mixed together. V8's label for this group has no middle word: PACKED_ELEMENTS or HOLEY_ELEMENTS.

Some numbers look simple but are not Smis:

• -0 is negative zero. JavaScript keeps it apart from 0, so V8 can't store it as a Smi.
• NaN means "not a number". It is the result of maths that fails, like 0 / 0.
• Infinity is bigger than every other number.

1const counts = [1, 2, 3];2counts.push(-0);3counts.push(NaN);4counts.push(Infinity);5 6console.log(Object.is(counts[3], -0));7console.log(Number.isNaN(counts[4]));8console.log(counts[5] === Infinity);

• Line 1 starts with three Smis.
• Line 2 pushes -0. push adds a value at the end of the array.
• Lines 3 and 4 push NaN and Infinity. All three new values need the double group.
• Line 6 prints true. Object.is(a, b) checks whether two values are exactly the same, and it can tell -0 from 0.
• Line 7 prints true. Number.isNaN(x) is true only when x is NaN.
• Line 8 prints true: counts[5] is Infinity.

Normal JavaScript can't show the label. Node can, with special V8 test functions whose names start with %. For example, %HasSmiElements(arr) returns true when arr has a Smi label.

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 label(array) {2  if (%HasDictionaryElements(array)) return "DICTIONARY_ELEMENTS";3  const prefix = %HasHoleyElements(array) ? "HOLEY" : "PACKED";4  if (%HasSmiElements(array)) return prefix + "_SMI_ELEMENTS";5  if (%HasDoubleElements(array)) return prefix + "_DOUBLE_ELEMENTS";6  if (%HasObjectElements(array)) return prefix + "_ELEMENTS";7  return "OTHER_ELEMENTS";8}9 10function report(name, array) {11  console.log(name + ": " + label(array));12}13 14console.log("Node " + process.version);15console.log("V8 " + process.versions.v8.split(".").slice(0, 2).join("."));16const values = [1, 2, 3];17report("packed smi", values);18values.push(4.5);19report("after double", values);20values.push("x");21report("after string", values);22values.pop();23values.pop();24report("after popping back", values);25const holey = new Array(3);26report("new Array", holey);27holey[0] = 1;28holey[1] = 2;29holey[2] = 3;30report("filled holey", holey);31const short = [1, 2, 3];32short[10] = 1;33report("write index 10", short);34const minusZero = [1, 2, 3];35minusZero.push(-0);36report("minus zero", minusZero);37const notANumber = [1, 2, 3];38notANumber.push(NaN);39report("NaN", notANumber);40const infinity = [1, 2, 3];41infinity.push(Infinity);42report("Infinity", infinity);43const sparse = [];44sparse[1e6] = 1;45report("sparse", sparse);

• Lines 1 to 8 make a function, label, that asks V8 for an array's label. It checks for a dictionary first, then for holes, then for each group of values.
• Lines 10 to 12 make report, which prints a name and the label.
• Lines 14 and 15 print the Node and V8 versions.
• Line 17 prints packed smi: PACKED_SMI_ELEMENTS.
• Line 18 pushes 4.5. Line 19 prints after double: PACKED_DOUBLE_ELEMENTS.
• Line 20 pushes "x". Line 21 prints after string: PACKED_ELEMENTS.
• Lines 22 and 23 take both new values off again. pop removes the last value. Line 24 still prints after popping back: PACKED_ELEMENTS.
• Line 26 prints HOLEY_SMI_ELEMENTS for new Array(3). Lines 27 to 29 fill every hole, but line 30 still prints HOLEY_SMI_ELEMENTS.
• Line 32 writes index 10 into a three-value array. Line 33 prints HOLEY_SMI_ELEMENTS: indexes 3 to 9 are holes.
• Lines 34 to 42 push -0, NaN, and Infinity into new arrays. Each prints PACKED_DOUBLE_ELEMENTS.
• Line 44 writes index 1e6, which means one million, into an empty array. Line 45 prints sparse: DICTIONARY_ELEMENTS. A later section explains this label.

How big can a Smi be? That depends on how V8 was built. One build setting is called pointer compression. It saves memory, and Chrome usually turns it on. Node 22 turns it off.

With pointer compression off, the biggest Smi is 2 ** 31 - 1, which is 2,147,483,647. The ** operator means "to the power of".

1console.log("Node " + process.version);2console.log("V8 " + process.versions.v8.split(".").slice(0, 2).join("."));3console.log("pointer compression", process.config.variables.v8_enable_pointer_compression);4console.log("2**31 - 1", %IsSmi(2 ** 31 - 1));5console.log("2**31", %IsSmi(2 ** 31));

• Lines 1 and 2 print the Node and V8 versions.
• Line 3 prints pointer compression 0. The 0 means the setting is off.
• Line 4 prints 2**31 - 1 true. %IsSmi(n) says whether V8 can store n as a Smi.
• Line 5 prints 2**31 false. One more is too big.

A label only moves one way

When you add a value that doesn't fit the current label, V8 moves the array to a label that holds more types of values. It only moves in this order:

• Smi, then double, then generic.
• Packed, then holey.

V8 does not move a label back. To do that, it would have to check every value in the array again after each change, and that would cost more time than it saves.

1const fares = [1, 2, 3];Run2fares.push(4.5);3fares.push("₹");4fares.pop();5fares.pop();6console.log(fares.join(","));7console.log(fares.length);

• Line 1 starts fares with small whole numbers. Its label is PACKED_SMI_ELEMENTS.
• Line 2 pushes 4.5, a decimal. The label moves to PACKED_DOUBLE_ELEMENTS.
• Line 3 pushes the string "₹", the rupee sign. The label moves to PACKED_ELEMENTS.
• Lines 4 and 5 pop the string and the decimal off again.
• Line 6 prints 1,2,3 and line 7 prints 3. The values look like the start again, but V8 keeps the PACKED_ELEMENTS label. The Node test earlier proves this on its lines 22 to 24.

%DebugPrint(value) is another V8 test function. It prints everything V8 knows about a value, and one of its lines is the label.

1const arr = [1, 2, 3];2%DebugPrint(arr);

1const model = createElementsKindModel();2model.push(1);       // PACKED_SMI_ELEMENTS3model.push(2.5);     // PACKED_DOUBLE_ELEMENTS4model.push("₹");     // PACKED_ELEMENTS5model.writePastEnd(); // HOLEY_ELEMENTS6model.push(-0);      // still HOLEY_ELEMENTS

The playground does not look inside your browser. It follows V8's rules in a small model written for this lesson. The lesson test runs the same steps in Node with the % functions and checks that the labels match.

Very spread-out arrays become dictionaries

An array is sparse when most of its indexes are holes. A few holes are fine: V8 keeps a holey list. But if you write one value at index one million, a list would need a million empty places first.

So V8 switches to a dictionary. A dictionary is a table that keeps only the indexes that exist, each with its value. V8's label for it is DICTIONARY_ELEMENTS. Reading from a dictionary is slower than reading from a list, because V8 has to look the index up in the table.

1const sparse = [];2sparse[1_000_000] = "Jaipur";3 4console.log(sparse.length);5console.log(0 in sparse);6console.log(1_000_000 in sparse);

• Line 1 makes an empty array, sparse.
• Line 2 writes "Jaipur" at index 1_000_000. The underscores only make the number easier to read. It is one million.
• Line 4 prints 1000001. The length is always the highest index plus one.
• Line 5 prints false: index 0 is a hole.
• Line 6 prints true: index one million exists.

If your numbers are really IDs, not places in a list, an array is the wrong tool. A Map is a built-in object that stores pairs of a key and a value. A Map or a plain object says what you mean, and it has no million-long gap.

Arrays keep spare room

An array's length is the number your code sees. Behind it, V8 keeps a store with room for the elements:

• This store is called the backing store.
• The number of places in it is its capacity.

Making a bigger store means copying every value into it. If V8 did that on every push, adding values would be slow. So when the store is full, V8 makes a bigger one with spare places. The next pushes go into the spare places, with no copying.

1const orders = [];Run2orders.push(1);3for (let ticket = 2; ticket <= 18; ticket += 1) {4  orders.push(ticket);5}6orders.push(19);7console.log(orders.length);

• Line 1 starts with an empty array: length 0 and capacity 0.
• Line 2 pushes 1. V8 makes a store with 17 places.
• Lines 3 to 5 push 2 to 18. The 18th value doesn't fit in 17 places, so V8 makes a new store with 43 places.
• Line 6 pushes 19. It fits, so the capacity stays 43.
• Line 7 prints 19. Your code only ever sees the length.

How does V8 pick 17 and 43? Its source code has a function, NewElementsCapacity, that takes the number of places needed now, adds half of it, and then adds 16 more. Here is that rule written in JavaScript:

1function newElementsCapacity(requestedCapacity) {2  return requestedCapacity + (requestedCapacity >> 1) + 16;3}4 5console.log(newElementsCapacity(1));6console.log(newElementsCapacity(18));7console.log(newElementsCapacity(44));

• Line 1 takes requestedCapacity: the number of places needed now, which is the new length.
• Line 2 is the whole rule. requestedCapacity >> 1 halves the number and drops any remainder, so 18 >> 1 is 9.
• Line 5 prints 17: 1 + 0 + 16.
• Line 6 prints 43: 18 + 9 + 16.
• Line 7 prints 82: 44 + 22 + 16.

The table shows the three moments when the store grew. Read each row from left to right. The test checked each capacity with %DebugPrint.

Array-like objects are not arrays

An array-like object has number keys and a length, but it is not a real array. Common examples:

• arguments: an object inside every normal function (not arrow functions). It holds the values the function was called with.
• Older browser lists, like the one document.getElementsByTagName("p") returns.
• Objects you build yourself, like { 0: "Asha", length: 1 }.

Array.isArray(value) tells you whether a value is a real array. Most array-likes have no array methods such as forEach. You can borrow one with .call: Array.prototype.forEach.call(list, fn) runs forEach with list as the array it works on. It works, but V8's fast paths are made for real arrays.

1function logArguments() {2  console.log(Array.isArray(arguments));3  console.log(arguments.length);4}5 6logArguments("Asha", "Ravi");7 8const list = { 0: "Asha", 1: "Ravi", length: 2 };9Array.prototype.forEach.call(list, (name, index) => {10  console.log(index + ":" + name);11});12console.log(Array.from(list).join("|"));

• Lines 1 to 4 make logArguments, which prints two facts about arguments.
• Line 6 calls it with "Asha" and "Ravi". Line 2 prints false: arguments is not an array. Line 3 prints 2.
• Line 8 makes list, an object with the keys 0 and 1 and a length of 2.
• Lines 9 to 11 borrow forEach with .call. They print 0:Asha and 1:Ravi.
• Line 12 uses Array.from(list), which builds a real array from list. Then join("|") prints Asha|Ravi.

The table compares a real array with two kinds of array-like values. Read each row from left to right.

Use this in real code, carefully

Elements kinds explain why some array code is slow. They are not a reason to write strange code. Work in this order:

1. Write clear code with normal arrays.
2. Measure the part users wait for. A profiler is a browser tool that shows where the time goes.
3. If the profiler points at array code, try one change, such as removing holes. Then measure again.

One easy habit: check values once, where they come into your program. Then the array only ever gets the values you expect.

1const readings = [];2for (const value of [18, 19, 20]) {3  if (Number.isFinite(value) && !Object.is(value, -0)) {4    readings.push(value);5  }6}7 8console.log(readings.join(","));

• Line 1 starts with an empty array, readings.
• Line 2 loops over the numbers 18, 19, and 20.
• Line 3 lets a number in only if Number.isFinite(value) is true, so it is not NaN or Infinity, and it is not -0.
• Line 4 pushes the number. Line 5 closes the check.
• Line 8 prints 18,19,20.

Habits that keep arrays on V8's fast path:

• Build arrays with [...] or push. new Array(n) starts with holes, and the label stays holey.
• Keep out -0, NaN, and Infinity only when your data really should be whole numbers.
• Don't read past the end, like items[3] in a three-value array. V8 has to search the prototype for index 3, and the answer is just undefined.
• Use a Map or an object for far-apart IDs. Use an array for places in a list.
• For large lists of numbers, consider a typed array. A typed array, like Float64Array, holds only one type of number.
• Measure before and after a change. V8's exact rules can change between versions.

Common misconceptions

• "A hole is just undefined." No. A hole is an index that doesn't exist, so 0 in array can be false. An undefined value is a value that does exist.
• "Popping the odd value makes the array fast again." No. The values change, but V8 does not move the label back.
• "Any gap turns an array into a dictionary." No. A few holes give a holey list. The lesson shows a dictionary only for one value at index one million.
• "Elements kinds are JavaScript types." No. They are labels inside V8. Other engines store arrays in their own ways, with their own names.
• "Knowing the engine means rewriting all my arrays." No. Write clear code, then measure. Change array code only where a profiler shows it is slow.

The table lists four pairs of ideas that are easy to mix up. Read each row from left to right.

Practice exercises

const fares = [1, 2, 3];
fares.push(4.5);
fares.push("₹");
fares.pop();
fares.pop();
console.log(fares.join(","));
console.log(fares.length);

const seats = new Array(3);
console.log(0 in seats);
seats[0] = "Asha";
console.log(seats[0]);

const list = { 0: "Asha", 1: "Ravi", length: 2 };
console.log(Array.from(list).join("|"));

const names = Array.from(list);
console.log(names.join("|"));

const items = [10, 20, 30];
let total = 0;
for (let i = 0; i <= items.length; i += 1) {
  total += items[i] ?? 0;
}
console.log(total);

for (let i = 0; i < items.length; i += 1) {
  total += items[i];
}

Check your understanding

Key takeaways

• V8 keeps an array's numbered values, its elements, apart from named properties.
• A packed array has a value at every index. A holey array has holes, so each read must check first.
• The label moves from Smi to double to generic, and from packed to holey. It does not move back.
• One value far from the start can turn an array into a dictionary. Array-like objects are not real arrays.
• Arrays grow with spare room. The exact numbers belong to V8, so measure before you change code.

In one line: arrays with no holes and one type of value are fast. Holes, mixed values, and far-apart indexes give V8 more work.

Next, Functions & closures inside the engine looks at how V8 stores functions, and how it keeps the variables a closure still needs.