22. How JavaScript stores numbers and objects

Two classes that look the same

Here are two TypeScript classes for a particle. Read them carefully:

class P {
  x: number;
  constructor(x: number) {
    this.x = x;
  }
}

class K {
  declare x: number;
  constructor(x: number) {
    this.x = x;
  }
}

They hold the same data and run the same constructor. Yet in this book’s benchmarks, moving particles made from the first class was several times slower. By the end of this chapter you’ll know exactly why, and it starts with how a single number is stored.

Every number is a double

The language says every JavaScript number is a 64-bit floating-point value in the IEEE 754 double format: 1 sign bit, 11 exponent bits and 52 mantissa bits^[1]. You met these as float64 in chapter 16.

But the language only fixes what numbers behave like. An engine may store them however it likes, as long as nobody can tell the difference^[2].

Small integers live in the slot

Loop counters, array indexes and lengths are small whole numbers, and they are everywhere. Wrapping each one in a 64-bit double on the heap would be wasteful, so V8 uses a trick called pointer tagging: a slot that normally holds an address can hold a small integer instead, and the lowest bit says which one it is^[3].

let a = 42;
let b = 4.2;
b = b + 1;
let c = 2 ** 30;

How big a Smi can be depends on how V8 was built. With pointer compression, which the V8 team built to save memory in Chrome, slots are 32 bits and a Smi carries 31 bits including its sign. A 64-bit build without it uses 32-bit Smi payloads^[3].

What an object looks like

An object is a block of memory too. V8’s blog describes its start: the first word points to the object’s hidden class (its shape: which properties it has and where they sit), followed by pointers to a store for extra properties and a store for indexed elements. After that come the in-object properties, the fastest kind^[4].

So a particle { x, y, vx, vy, mass, health } is not six numbers in a row. It is a header, then six slots, and each slot holding a non-Smi number points somewhere else again. That overhead is exactly what chapter 23 will measure.

A field that always holds doubles gets the Double representation. In the design the V8 team described, its value sits in a box that only this object can see, so V8 can update it in place without allocating. If a field starts as one representation and then receives a value that doesn’t fit, V8 widens it to a more general one^[2]. The most general, Tagged, keeps doubles as ordinary immutable HeapNumbers.

Back to the two classes

In modern JavaScript, x; inside a class body is a real class field. Fields are added before the constructor body runs, and a field without an initializer starts as undefined^[5]. You can watch it happen:

class P {
  x;
  constructor(x) {
    console.log('before:', this.x);
    console.log('has x?', 'x' in this);
    this.x = x;
  }
}
const p = new P(0.5);
console.log('after:', p.x);

TypeScript turns x: number; into exactly that kind of field when the target is ES2022 or later^[6]. Writing declare x: number; instead emits nothing at all, so the field appears only when the constructor first stores a number^[7]. Step through what that does to the field:

class P {
  x: number; // a real field
  constructor(x: number) {
    this.x = x;
  }
}
const p = new P(0.5);
p.x += 0.1;

This isn’t guesswork. Running the benchmark with V8’s --trace-generalization flag printed this line for class P:

x:h{Any;const}->t{Any;mutable}

h is the heap-object representation (the undefined) and t is Tagged. Here is what that costs:

In this book’s benchmark run, the class with field declarations was roughly 3 to 7 times slower than the object literal and the constructor-only class, depending on the number of particles. The V8 blog gives the same advice in plain JavaScript: don’t start numeric fields as null, because it defeats representation tracking^[2].

Your turn

function smiFits(n) {
  // your code here
}

console.log(smiFits(42), smiFits(4.2));

function exponentBits(x) {
  const f = new Float64Array([x]);
  const u = new Uint32Array(f.buffer);
  // your code here
}

console.log(exponentBits(1));

What you learned

• Every JavaScript number behaves like an IEEE 754 double: sign, exponent, mantissa, 64 bits.
• V8 stores small integers as Smis, right inside the slot, marked by a tag bit. Other numbers become immutable HeapNumbers on the heap.
• Every object starts with an object header: a hidden-class pointer plus pointers to its properties and elements stores.
• Each field has a field representation (such as Smi, Double or Tagged), and V8 widens it when a value doesn’t fit.
• A TypeScript field declaration starts a field as undefined, so storing doubles generalizes it to Tagged, and every update allocates.

Next: AoS against SoA, measured properly, across seven kinds of loop.