The heap & pointer compression

The heap is organized space

The beginner picture says JavaScript values live on a stack or a heap. That is useful, and the lessons on stack and heap and memory management explain that level. This lesson zooms into V8's heap: the managed memory area where objects, strings, arrays, functions, metadata, and code objects are placed.

We will not re-teach value tagging or Smis here; the value-representation lesson owns that. We also will not teach garbage collection algorithms here; the upcoming garbage-collection lessons, including gc-basics, own collection. Here the question is placement: where does the engine put things, and why does V8 sometimes store half-sized heap pointers?

This lesson follows Prototypes inside the engine in the same batch. After heap layout, Stack frames & calling conventions moves from managed heap memory to the machine stack used during calls.

New, old, code, and large-object spaces

A space is a region of V8's heap with one job. Fresh small objects normally begin in a young area called new space. Objects that survive long enough can end up in old space. Executable code objects live in code spaces because they have different permissions and accounting. Objects too large for regular pages go through large-object spaces.

1const v8 = require("node:v8");2const names = v8.getHeapSpaceStatistics().map((space) => space.space_name).sort();3console.log(names.join(", "));

The exact list changes as V8 evolves. For example, this Node build also exposes read-only, trusted, shared, and corresponding large-object spaces. Treat those names as V8 implementation details, not ECMAScript requirements.

Pages and bump allocation

A page is a fixed-size chunk inside a paged heap space. Current V8 source keeps the regular page size at 256 KB for the common configuration: kPageSizeBits = 18, so 1 << 18 bytes. A regular object can be up to half that size in the source constant used by the lesson, so roughly 128 KB.

1// V8 source, src/base/build_config.h:2// constexpr int kPageSizeBits = 18;3// constexpr int kRegularPageSize = 1 << kPageSizeBits;4// V8 source, src/common/globals.h:5// constexpr int kMaxRegularHeapObjectSize = (1 << (kPageSizeBits - 1));

The fast allocation path is often a bump allocation: keep a pointer named something like nextFree, return the address at nextFree, and move nextFree forward by the object size. If the object does not fit, the allocator moves to a new page or a slower path.

1const pageSize = 1024;Run2let page = 0;3let nextFree = 0;4 5function align16(bytes) {6  return Math.ceil(bytes / 16) * 16;7}8 9function allocate(label, requested) {10  const size = align16(requested);11  if (nextFree + size > pageSize) {12    page += 1;13    nextFree = 0;14  }15  const address = { page, start: nextFree, end: nextFree + size };16  nextFree += size;17  return label + ": page " + address.page + ", bytes " + address.start + "-" + address.end;18}19 20console.log(allocate("header", 120));21console.log(allocate("items", 380));22console.log(allocate("names", 460));23console.log(allocate("avatar", 180));

Line 16 in the replay is the heart of the fast path: nextFree += size. Line 12 appears only when the next object crosses the page boundary. This is a teaching model; it does not inspect your browser's actual heap.

Why very large objects get their own space

Large allocations are awkward inside regular pages. If a backing store is bigger than the maximum regular object size, it cannot fit in the normal small-object rhythm. V8's large-object spaces handle those allocations separately. The object is not automatically a leak; it is just too large for the ordinary page path.

1const v8 = require("node:v8");2if (typeof global.gc !== "function") throw new Error("run with --expose-gc");3function used(spaceName) {4  return v8.getHeapSpaceStatistics().find((space) => space.space_name === spaceName)?.space_used_size ?? 0;5}6global.gc();7const before = used("large_object_space");8global.big = new Array(20000).fill(1);9global.gc();10const after = used("large_object_space");11console.log(after > before);12console.log(after - before >= 131072);

Pointer compression and the 4 GB cage

On a normal 64-bit machine, a pointer takes eight bytes. V8's pointer-compression blog explains the saving: if every V8 heap object pointer is inside one reserved 4 GB region, memory can store a 32-bit offset instead of the full address. Generated code adds the cage base back when it needs the real address.

1const cageBase = 0x0000000400000000n;Run2const cageSize = 0x0000000100000000n;3 4function compressPointer(address) {5  if (address < cageBase || address >= cageBase + cageSize) {6    throw new RangeError("address is outside the 4 GB cage");7  }8  return Number(address - cageBase);9}10 11function decompressPointer(offset) {12  return cageBase + BigInt(offset >>> 0);13}14 15const address = cageBase + 0x12345678n;16const compressed = compressPointer(address);17console.log("0x" + compressed.toString(16).padStart(8, "0"));18console.log("0x" + decompressPointer(compressed).toString(16));

1const cageBase = 0x0000000400000000n;2const cageSize = 0x0000000100000000n;3 4function compressPointer(address) {5  if (address < cageBase || address >= cageBase + cageSize) {6    throw new RangeError("outside the cage");7  }8  return Number(address - cageBase);9}

1const cageBase = 0x0000000400000000n;2const cageSize = 0x0000000100000000n;3 4function compressPointer(address) {5  if (address < cageBase || address >= cageBase + cageSize) {6    throw new RangeError("address is outside the 4 GB cage");7  }8  return Number(address - cageBase);9}10 11function decompressPointer(offset) {12  return cageBase + BigInt(offset >>> 0);13}14 15const address = cageBase + 0x12345678n;16const compressed = compressPointer(address);17console.log("0x" + compressed.toString(16).padStart(8, "0"));18console.log("0x" + decompressPointer(compressed).toString(16));

Line 5 is the safety check in the model: an address outside the 4 GB cage cannot be represented by this compressed pointer. Line 8 stores the 32-bit offset. Line 12 decompresses by adding the cage base back. V8's real representation also interacts with tagged values and Smis; the neighboring value-representation lesson owns those details.

1console.log(%IsSmi(2 ** 31 - 1));2console.log(%IsSmi(2 ** 31));

This official Node build does not enable pointer compression, so a native V8 probe confirms that 2 ** 31 - 1 is still a Smi while 2 ** 31 is not. Chrome's pointer-compressed 64-bit V8 uses 31-bit Smi payloads, as the V8 pointer-compression article describes. The value-representation lesson owns the full tagging story.

The V8 sandbox

Pointer compression saves memory. The V8 sandbox is a security design. The V8 sandbox blog describes isolating V8 heap memory so a V8 heap corruption bug cannot directly reach the rest of the host process. In the software design, in-sandbox pointers are offsets, and references to memory outside the sandbox go through tables such as an external pointer table.

1console.log(process.config.variables.v8_enable_pointer_compression);2console.log(process.config.variables.v8_enable_sandbox);

The sandbox is not a replacement for the browser process sandbox, and it is not a promise that every bug becomes harmless. It is a defense layer: corrupted in-cage data should not be enough to read or write arbitrary process memory without a sandbox bypass.

Heap size limits

v8.getHeapStatistics().heap_size_limit reports V8's managed-heap ceiling for a Node process. It is not the same as your operating system's resident memory, and it is not an exact prediction of when a real app will fail. Still, it is useful evidence when you change a V8 heap-size flag.

1node --max-old-space-size=64 -e "console.log(require('node:v8').getHeapStatistics().heap_size_limit)"2node --max-old-space-size=256 -e "console.log(require('node:v8').getHeapStatistics().heap_size_limit)"

If a Node process runs out of heap, increasing the limit can buy time, but it does not explain why memory grows. Use heap snapshots, allocation profiles, and application knowledge to find retained data.

What developers should do

Most frontend work should not depend on V8 page sizes or build flags. Use this knowledge to interpret measurements. A giant array, image buffer, or parsed JSON payload may appear in large-object accounting. A short-lived stream of small objects may churn in new space. A retained cache can grow old space. Each clue suggests a measurement to run, not folklore to apply blindly.

• Use heap snapshots to identify what is retained, then fix ownership or cleanup.
• Measure before rewriting data structures for a page-size or pointer-compression guess.
• Avoid keeping huge arrays or strings reachable after the UI no longer needs them.
• For Node services, treat --max-old-space-size as a capacity knob, not a leak fix.

If the issue is collection behavior, continue in the garbage-collection module. If the issue is call memory, continue to stack frames next.

Common misconceptions

• “The JavaScript spec says objects are in new space or old space.” No. Spaces are V8 implementation details.
• “Pointer compression means Node always has a 4 GB heap.” Official Node builds here do not enable pointer compression.
• “A large-object allocation is a leak.” It is only a placement choice. A leak means unwanted reachability over time.
• “The sandbox and garbage collector do the same job.” The sandbox limits exploit reach; the collector reclaims unreachable objects.
• “Heap limit equals total process memory.” It covers V8 managed heap, not every native allocation or OS page.

Practice exercises

// The first page has only 48 bytes left.
// The next aligned allocation needs 192 bytes.

const base = 0x400000000n;
const address = base + 0x20n;
// Print the compressed offset as eight hex digits.

const base = 0x400000000n;
const address = base + 0x20n;
const offset = Number(address - base);
console.log("0x" + offset.toString(16).padStart(8, "0"));

Check your understanding

Key takeaways

• V8 splits managed heap memory into spaces because fresh objects, old objects, code, and huge objects need different handling.
• Regular pages are 256 KB in current V8 source for the common configuration; the maximum regular object size is half a page.
• Bump allocation is the fast path: return the current next-free pointer, then move it forward if the object fits.
• Pointer compression stores 32-bit offsets inside a 4 GB cage; official Node builds here differ from Chrome and report the feature disabled.
• The V8 sandbox is a security layer that keeps heap corruption from directly reaching the rest of the process.

Up next: Stack frames & calling conventions, where you will see what a function call puts on the machine stack.