V8 Hidden Classes in JavaScript: Full Tutorial

// Creating objects with the same shape
const p1 = { x: 1, y: 2 };
const p2 = { x: 3, y: 4 };
// p1 and p2 share the same hidden class: Map{x@offset0, y@offset4}
 
// V8 knows 'x' is always at offset 0 and 'y' at offset 4
// So accessing p1.x or p2.x is a direct memory read (like C struct access)
 
// Different property order creates a different hidden class
const p3 = { y: 2, x: 1 };
// p3 has a DIFFERENT hidden class: Map{y@offset0, x@offset4}
// Even though it has the same properties, the order differs
 
// Hidden class is determined by:
// 1. Property names
// 2. Property order (the order they were added)
// 3. Property attributes (writable, enumerable, configurable)
// 4. Element kind (for indexed properties)
 
// Verifying same hidden class in Node.js
// Use: node --allow-natives-syntax
// %HaveSameMap(p1, p2)  -> true
// %HaveSameMap(p1, p3)  -> false
 
// Objects constructed the same way share shapes
function Point(x, y) {
  this.x = x;  // Transition 1: {} -> {x}
  this.y = y;  // Transition 2: {x} -> {x, y}
}
 
const a = new Point(1, 2);  // Hidden class: Map{x, y}
const b = new Point(3, 4);  // Hidden class: Map{x, y} (SAME)
const c = new Point(5, 6);  // Hidden class: Map{x, y} (SAME)
// All three share one hidden class

// Step-by-step hidden class transitions
const obj = {};
// Hidden class: Map0 {} (empty object map)
 
obj.x = 1;
// Transition: Map0 -> Map1 {x}
// V8 creates Map1 with x at offset 0
 
obj.y = 2;
// Transition: Map1 -> Map2 {x, y}
// V8 creates Map2 with x at offset 0, y at offset 4
 
obj.z = 3;
// Transition: Map2 -> Map3 {x, y, z}
// V8 creates Map3 with x@0, y@4, z@8
 
// Transition tree visualization:
//
// Map0 {} ──x──> Map1 {x} ──y──> Map2 {x,y} ──z──> Map3 {x,y,z}
//         \
//          ──y──> Map4 {y} ──x──> Map5 {y,x}
//
// Different addition orders create different branches
 
// V8 CACHES transitions, so the second object is fast
const obj2 = {};    // Map0 (cached)
obj2.x = 10;       // Map0 -> Map1 (transition already exists, reuse it)
obj2.y = 20;       // Map1 -> Map2 (transition already exists)
obj2.z = 30;       // Map2 -> Map3 (transition already exists)
// obj2 shares Map3 with obj - no new hidden classes created
 
// BRANCHING transitions
const objA = {};
objA.x = 1;
objA.y = 2;  // Path: Map0 -> Map1{x} -> Map2{x,y}
 
const objB = {};
objB.x = 1;
objB.z = 3;  // Path: Map0 -> Map1{x} -> Map6{x,z}
// Map1 now has two outgoing transitions: y -> Map2, z -> Map6
// This is fine, but too many branches increases memory usage

// V8 stores properties in two ways:
// 1. IN-OBJECT: stored directly inside the object (fastest)
// 2. OUT-OF-OBJECT: stored in a separate backing store (slower)
 
// CONSTRUCTOR-ALLOCATED: Properties defined in constructors
// get in-object slots pre-allocated
class User {
  constructor(name, email, age) {
    this.name = name;   // In-object property (slot 0)
    this.email = email; // In-object property (slot 1)
    this.age = age;     // In-object property (slot 2)
  }
}
 
const user = new User("Alice", "alice@test.com", 30);
// V8 allocates the User object with 3 in-object property slots
// user.name -> direct memory offset read (fast)
 
// DYNAMICALLY-ADDED: Properties added after construction
// may spill to the out-of-object backing store
user.active = true;    // May be in-object if slack space exists
user.lastLogin = Date.now(); // May spill to backing store
 
// V8's SLACK TRACKING
// When constructing the first few instances, V8 over-allocates
// in-object slots (slack). After a few constructions, V8
// determines the final number of in-object properties and
// shrinks the allocation to fit.
 
// Example: V8 sees User always has 3 properties
// First 7 constructions: 3 properties + 4 slack slots (7 total)
// After ~7 instances: V8 finalizes at 3 in-object slots (no slack)
// Any properties added after construction go to backing store
 
// BACKING STORE (properties array)
// Objects with more properties than in-object slots use a
// separate array for overflow properties
const manyProps = {};
for (let i = 0; i < 20; i++) {
  manyProps[`prop${i}`] = i;
  // First few go in-object, rest go to backing store
}
 
// ELEMENTS (indexed properties) use a separate store
const arr = { 0: "a", 1: "b", length: 2 };
// Named properties: {length} stored via hidden class
// Indexed properties: {0, 1} stored in elements backing store
// V8 uses different storage strategies depending on the density

// When V8 cannot efficiently use hidden classes, it falls back
// to "dictionary mode" (also called "slow mode")
// Dictionary mode uses a hash table instead of offset-based access
 
// TRIGGERS FOR DICTIONARY MODE
 
// 1. Deleting properties
const obj1 = { a: 1, b: 2, c: 3 };
delete obj1.b;  // Object transitions to dictionary mode
// V8 cannot use the hidden class Map{a,b,c} anymore
// because 'b' no longer exists
 
// FIX: Set to undefined instead of deleting
const obj2 = { a: 1, b: 2, c: 3 };
obj2.b = undefined;  // Hidden class preserved, no dictionary mode
 
// 2. Too many properties added dynamically
const config = {};
for (let i = 0; i < 100; i++) {
  config[`setting_${i}`] = true;
  // After many dynamic additions, V8 may switch to dictionary mode
}
// The transition chain becomes too long and V8 gives up
 
// FIX: Define all properties in the constructor or literal
const config2 = {
  setting_0: true,
  setting_1: true,
  // ... define all up front
};
 
// 3. Computed property names in some cases
const key = "dynamic_" + Date.now();
const obj3 = {};
obj3[key] = "value"; // Computed key may trigger dictionary mode
 
// 4. Object.defineProperty with non-default attributes
const obj4 = { a: 1, b: 2 };
Object.defineProperty(obj4, "c", {
  value: 3,
  writable: false,    // Non-default attribute
  enumerable: false,  // Non-default attribute
});
// Different attributes create a new branch but don't necessarily
// trigger dictionary mode. However, many such operations can.
 
// CHECKING FOR DICTIONARY MODE (Node.js with --allow-natives-syntax)
// %HasFastProperties(obj)  -> false means dictionary mode
 
// PERFORMANCE COMPARISON
// Hidden class access: O(1) - direct memory offset
// Dictionary access:   O(1) amortized - hash table lookup
// But the constant factor is ~10x worse for dictionary mode
// Dictionary mode also prevents inline cache optimization

// ES6 classes create consistent hidden classes because
// the constructor always adds properties in the same order
 
// GOOD: Class hierarchy with stable shapes
class Shape {
  constructor(color) {
    this.color = color;    // All Shapes have 'color' at slot 0
    this.visible = true;   // All Shapes have 'visible' at slot 1
  }
}
 
class Circle extends Shape {
  constructor(color, radius) {
    super(color);
    this.radius = radius;  // All Circles have 'radius' at slot 2
  }
}
 
class Rectangle extends Shape {
  constructor(color, width, height) {
    super(color);
    this.width = width;    // All Rectangles have 'width' at slot 2
    this.height = height;  // All Rectangles have 'height' at slot 3
  }
}
 
// All Circles share one hidden class
const c1 = new Circle("red", 10);
const c2 = new Circle("blue", 20);
// Both have Map: {color, visible, radius}
 
// All Rectangles share one hidden class
const r1 = new Rectangle("green", 5, 10);
const r2 = new Rectangle("yellow", 8, 12);
// Both have Map: {color, visible, width, height}
 
// BAD: Conditional properties in constructor
class BadUser {
  constructor(name, role) {
    this.name = name;
    if (role === "admin") {
      this.permissions = ["read", "write", "delete"];
      this.adminLevel = 1;
    }
    this.email = null;
  }
}
 
// This creates different hidden classes:
const admin = new BadUser("Alice", "admin");
// Map: {name, permissions, adminLevel, email}
const regular = new BadUser("Bob", "user");
// Map: {name, email}
// These are DIFFERENT hidden classes - no sharing
 
// FIX: Always define all properties
class GoodUser {
  constructor(name, role) {
    this.name = name;
    this.permissions = role === "admin" ? ["read", "write", "delete"] : [];
    this.adminLevel = role === "admin" ? 1 : 0;
    this.email = null;
  }
}
// All instances share: Map: {name, permissions, adminLevel, email}

// STRATEGY 1: Initialize all properties in constructors
class Component {
  constructor(props) {
    // Define ALL properties the object will ever have
    this.props = props;
    this.state = {};
    this.children = [];
    this.parent = null;
    this.mounted = false;
    this.ref = null;
  }
 
  mount(parent) {
    this.parent = parent;  // No new property, just assignment
    this.mounted = true;   // No new property, just assignment
  }
}
 
// STRATEGY 2: Use factory functions with consistent shape
function createEvent(type, data) {
  return {
    type: type,
    data: data,
    timestamp: Date.now(),
    processed: false,
    result: null,
  };
  // Every event has the same shape
}
 
// STRATEGY 3: Avoid mixing property types across instances
// BAD
const items = [
  { id: 1, value: 42 },       // value is number
  { id: 2, value: "hello" },  // value is string
  { id: 3, value: [1, 2] },   // value is array
];
// Same shape BUT different field representations internally
 
// GOOD: Consistent types when possible
const items2 = [
  { id: 1, numValue: 42, strValue: null },
  { id: 2, numValue: null, strValue: "hello" },
  { id: 3, numValue: null, strValue: null },
];
 
// STRATEGY 4: Object.freeze for immutable data
const constants = Object.freeze({
  MAX_RETRIES: 3,
  TIMEOUT_MS: 5000,
  API_VERSION: "v2",
});
// V8 optimizes frozen objects: no transitions possible
// All inline caches on frozen objects are stable
 
// STRATEGY 5: Use Map for dynamic key-value data
// BAD: Using plain object as a dictionary
const userCache = {};
userCache[userId1] = userData1; // Dynamic keys -> dictionary mode
userCache[userId2] = userData2;
 
// GOOD: Use Map for dynamic keys
const userCache2 = new Map();
userCache2.set(userId1, userData1); // Map is designed for this
userCache2.set(userId2, userData2);