JavaScript Meta Programming: Meta Programming Concepts · Reflect API · Proxy API · Complete Reference

// ❌ Manual approach — tedious and doesn't scale:
const user = {
  _name: "Alice",
  get name() {
    console.log("name was read");    // Only works for known properties
    return this._name;
  },
  set name(val) {
    console.log("name was written"); // Must write this for EVERY property
    this._name = val;
  }
};

const person = { name: "Alice", age: 30 };

// Traditional:
console.log(person.name);           // Output: Alice
console.log(person["age"]);         // Output: 30

// Reflect:
console.log(Reflect.get(person, "name"));   // Output: Alice
console.log(Reflect.get(person, "age"));    // Output: 30

const obj = {
  _value: 42,
  get value() { return this._value; }
};

const other = { _value: 99 };

// Read obj's 'value' getter, but with 'other' as 'this':
console.log(Reflect.get(obj, "value", other));   // Output: 99

const car = { brand: "Toyota", speed: 0 };

const success = Reflect.set(car, "speed", 60);
console.log(success);       // Output: true
console.log(car.speed);     // Output: 60

// On a frozen object — returns false instead of throwing:
const frozen = Object.freeze({ x: 1 });
const result = Reflect.set(frozen, "x", 99);
console.log(result);    // Output: false  ← did not succeed
console.log(frozen.x);  // Output: 1     ← unchanged

const book = { title: "1984", author: "Orwell" };

console.log("title"  in book);               // Output: true
console.log(Reflect.has(book, "title"));      // Output: true
console.log(Reflect.has(book, "publisher"));  // Output: false

// Also checks prototype chain, just like 'in':
console.log(Reflect.has(book, "toString"));   // Output: true  ← from Object.prototype

const config = { host: "localhost", port: 3000, debug: true };

console.log(Reflect.deleteProperty(config, "debug"));   // Output: true
console.log(config);   // Output: { host: 'localhost', port: 3000 }

// On a non-configurable property — returns false:
const obj = {};
Object.defineProperty(obj, "id", { value: 1, configurable: false });
console.log(Reflect.deleteProperty(obj, "id"));   // Output: false
console.log(obj.id);                               // Output: 1  ← still there

function greet(greeting, punctuation) {
  return greeting + ", " + this.name + punctuation;
}

const person = { name: "Alice" };

// Old way:
const result1 = Function.prototype.apply.call(greet, person, ["Hello", "!"]);

// Reflect way — much cleaner:
const result2 = Reflect.apply(greet, person, ["Hello", "!"]);

console.log(result1);   // Output: Hello, Alice!
console.log(result2);   // Output: Hello, Alice!

class Point {
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }
}

// Traditional:
const p1 = new Point(3, 4);

// Reflect:
const p2 = Reflect.construct(Point, [3, 4]);

console.log(p1);   // Output: Point { x: 3, y: 4 }
console.log(p2);   // Output: Point { x: 3, y: 4 }

class Base {
  constructor(value) { this.value = value; }
}

class Derived extends Base {}

// Create an instance whose prototype chain follows 'Derived',
// but initialised using 'Base's constructor:
const obj = Reflect.construct(Base, [42], Derived);

console.log(obj instanceof Derived);  // Output: true
console.log(obj.value);               // Output: 42

const obj = {};

const success = Reflect.defineProperty(obj, "id", {
  value:        1001,
  writable:     false,
  enumerable:   true,
  configurable: false
});

console.log(success);   // Output: true
console.log(obj.id);    // Output: 1001

const user = { name: "Alice" };

const desc = Reflect.getOwnPropertyDescriptor(user, "name");
console.log(desc);
// Output: { value: 'Alice', writable: true, enumerable: true, configurable: true }

class Animal {}
class Dog extends Animal {}

const rex = new Dog();

// Get:
console.log(Reflect.getPrototypeOf(rex) === Dog.prototype);      // Output: true
console.log(Reflect.getPrototypeOf(Dog.prototype) === Animal.prototype); // Output: true

// Set:
const base = { type: "generic" };
const child = { name: "child" };

Reflect.setPrototypeOf(child, base);
console.log(child.type);   // Output: generic  ← inherited

const sym = Symbol("id");
const obj = {
  name:  "Alice",
  age:   30,
  [sym]: 9999
};

Object.defineProperty(obj, "hidden", { value: "secret", enumerable: false });

console.log(Object.keys(obj));           // Output: ['name', 'age']           ← enumerable only
console.log(Reflect.ownKeys(obj));       // Output: ['name', 'age', 'hidden', Symbol(id)]  ← everything

const obj = { x: 1 };

console.log(Reflect.isExtensible(obj));   // Output: true

Reflect.preventExtensions(obj);

console.log(Reflect.isExtensible(obj));   // Output: false
Reflect.set(obj, "y", 2);                 // Fails silently
console.log(obj.y);                       // Output: undefined

Code ──► Proxy (traps run here) ──► Target Object
                │
          You control what
          happens at each step

const proxy = new Proxy(target, handler);

const target = { name: "Alice", age: 30 };
const proxy  = new Proxy(target, {});   // Empty handler = no interception

console.log(proxy.name);   // Output: Alice  ← just like accessing target directly
proxy.age = 31;
console.log(target.age);   // Output: 31  ← changes flow through to target

const handler = {
  get(target, property, receiver) {
    console.log(`GET: "${property}" was read`);
    return Reflect.get(target, property, receiver);   // Perform the default operation
  }
};

const user = new Proxy({ name: "Alice", role: "admin" }, handler);

console.log(user.name);
// GET: "name" was read
// Output: Alice

console.log(user.role);
// GET: "role" was read
// Output: admin

const withDefaults = new Proxy({}, {
  get(target, property) {
    if (property in target) {
      return target[property];
    }
    return `[Property "${property}" not found — returning default]`;
  }
});

withDefaults.name = "Alice";
console.log(withDefaults.name);        // Output: Alice
console.log(withDefaults.age);         // Output: [Property "age" not found — returning default]
console.log(withDefaults.anything);    // Output: [Property "anything" not found — returning default]

const handler = {
  set(target, property, value, receiver) {
    console.log(`SET: "${property}" = ${JSON.stringify(value)}`);

    // Validation example:
    if (property === "age" && (typeof value !== "number" || value < 0 || value > 150)) {
      throw new TypeError(`Invalid age: ${value}`);
    }

    return Reflect.set(target, property, value, receiver);   // Perform the actual set
  }
};

const person = new Proxy({}, handler);

person.name = "Alice";
// SET: "name" = "Alice"

person.age = 30;
// SET: "age" = 30

person.age = -5;
// ❌ TypeError: Invalid age: -5

const hiddenRange = new Proxy({ min: 1, max: 100 }, {
  has(target, property) {
    // Pretend any number between min and max "exists" in the object:
    const num = Number(property);
    if (!isNaN(num)) {
      return num >= target.min && num <= target.max;
    }
    return Reflect.has(target, property);
  }
});

console.log(50  in hiddenRange);   // Output: true   (50 is between 1 and 100)
console.log(150 in hiddenRange);   // Output: false
console.log("min" in hiddenRange); // Output: true   (actual property)

const protectedObj = new Proxy(
  { name: "Alice", _secret: "password123" },
  {
    deleteProperty(target, property) {
      if (property.startsWith("_")) {
        throw new Error(`Cannot delete protected property: "${property}"`);
      }
      console.log(`Deleting "${property}"`);
      return Reflect.deleteProperty(target, property);
    }
  }
);

delete protectedObj.name;
// Deleting "name"

delete protectedObj._secret;
// ❌ Error: Cannot delete protected property: "_secret"

function multiply(a, b) {
  return a * b;
}

const timedMultiply = new Proxy(multiply, {
  apply(target, thisArg, argumentsList) {
    const start  = performance.now();
    const result = Reflect.apply(target, thisArg, argumentsList);
    const end    = performance.now();
    console.log(`multiply(${argumentsList}) = ${result} [${(end - start).toFixed(3)}ms]`);
    return result;
  }
});

timedMultiply(6, 7);    // multiply(6,7) = 42 [0.012ms]
timedMultiply(100, 50); // multiply(100,50) = 5000 [0.004ms]

class User {
  constructor(name, email) {
    this.name  = name;
    this.email = email;
  }
}

const TrackedUser = new Proxy(User, {
  construct(target, argumentsList, newTarget) {
    console.log(`New ${target.name} created: ${argumentsList[0]}`);
    const instance = Reflect.construct(target, argumentsList, newTarget);
    instance.createdAt = new Date().toISOString();
    return instance;
  }
});

const u = new TrackedUser("Alice", "alice@example.com");
// New User created: Alice
console.log(u.name);       // Output: Alice
console.log(u.createdAt);  // Output: current ISO timestamp

const obj = { name: "Alice", _private: "secret", id: 1 };

const filtered = new Proxy(obj, {
  ownKeys(target) {
    // Hide properties starting with '_':
    return Reflect.ownKeys(target).filter(key => !String(key).startsWith("_"));
  },
  getOwnPropertyDescriptor(target, prop) {
    // Required: tell the engine all returned keys are "real" properties
    return { value: target[prop], enumerable: true, configurable: true, writable: true };
  }
});

console.log(Object.keys(filtered));   // Output: ['name', 'id']  ← _private is hidden
for (const key in filtered) {
  console.log(key);   // Output: name, id  ← _private not enumerated
}

const strict = new Proxy({}, {
  defineProperty(target, property, descriptor) {
    if (descriptor.value !== undefined && typeof descriptor.value === "function") {
      throw new TypeError(`Functions cannot be stored on this object.`);
    }
    console.log(`Defining "${property}"`);
    return Reflect.defineProperty(target, property, descriptor);
  }
});

strict.name = "Alice";     // Defining "name"
strict.age  = 30;          // Defining "age"

strict.greet = function() { return "Hi"; };
// ❌ TypeError: Functions cannot be stored on this object.

const obj = {};

const liar = new Proxy(obj, {
  getPrototypeOf(target) {
    return Array.prototype;   // Pretend to be an array
  }
});

console.log(Object.getPrototypeOf(liar) === Array.prototype);  // Output: true
console.log(liar instanceof Array);                             // Output: true  ← it's lying!

const { proxy, revoke } = Proxy.revocable(
  { name: "Alice", balance: 1000 },
  {
    get(target, prop) {
      return Reflect.get(target, prop);
    }
  }
);

console.log(proxy.name);     // Output: Alice
console.log(proxy.balance);  // Output: 1000

revoke();   // Disconnect the proxy

console.log(proxy.name);
// ❌ TypeError: Cannot perform 'get' on a proxy that has been revoked

const target = {
  _count: 0,
  get count() { return this._count; }   // 'this' needs to be the proxy to work correctly
};

const handler = {
  get(target, property, receiver) {
    console.log(`Reading: ${property}`);
    return Reflect.get(target, property, receiver);
    //                                    ↑ Pass receiver to Reflect.get
    //                                      so 'this' inside getters is the proxy
  }
};

const proxy = new Proxy(target, handler);
console.log(proxy.count);
// Reading: count       ← getter intercepted
// Reading: _count      ← getter's 'this._count' also intercepted!
// Output: 0

class Range {
  constructor(from, to) {
    this.from = from;
    this.to   = to;
  }

  // Symbol.iterator — makes Range work in for...of loops:
  [Symbol.iterator]() {
    let current = this.from;
    const last  = this.to;
    return {
      next() {
        return current <= last
          ? { value: current++, done: false }
          : { value: undefined, done: true };
      }
    };
  }

  // Symbol.toPrimitive — controls type coercion:
  [Symbol.toPrimitive](hint) {
    if (hint === "number") return this.to - this.from + 1;  // Length of range
    if (hint === "string") return `Range(${this.from}–${this.to})`;
    return true;
  }

  // Symbol.hasInstance — controls instanceof behaviour:
  static [Symbol.hasInstance](instance) {
    return typeof instance === "number";
  }
}

const r = new Range(1, 5);

for (const n of r) process.stdout.write(n + " ");
// Output: 1 2 3 4 5

console.log(`${r}`);     // Output: Range(1–5)
console.log(+r);         // Output: 5  (number of items)
console.log(3 instanceof Range);  // Output: true  (3 is a number!)

// Profile proxy overhead:
const plain  = { x: 1 };
const proxied = new Proxy({ x: 1 }, {
  get: (t, k) => Reflect.get(t, k)
});

console.time("plain");
for (let i = 0; i < 1_000_000; i++) plain.x;
console.timeEnd("plain");    // e.g. ~2ms

console.time("proxied");
for (let i = 0; i < 1_000_000; i++) proxied.x;
console.timeEnd("proxied");  // e.g. ~15ms  ← ~7x slower

// --- Dependency tracking ---
// Which "effect" (subscriber function) is currently running?
let activeEffect = null;
const dependencyMap = new WeakMap();  // target → Map(key → Set(effects))

function track(target, key) {
  if (!activeEffect) return;   // Nothing is watching right now

  if (!dependencyMap.has(target)) {
    dependencyMap.set(target, new Map());
  }
  const keyMap = dependencyMap.get(target);

  if (!keyMap.has(key)) {
    keyMap.set(key, new Set());
  }
  keyMap.get(key).add(activeEffect);   // Record: this effect depends on target[key]
}

function trigger(target, key, oldValue, newValue) {
  if (!dependencyMap.has(target)) return;
  const keyMap = dependencyMap.get(target);
  if (!keyMap.has(key)) return;

  const effects = keyMap.get(key);
  effects.forEach(effect => {
    if (effect !== activeEffect) {   // Don't trigger the currently-running effect
      effect();
    }
  });
}

// --- Reactive Proxy Handler ---
function createReactiveHandler(options = {}) {
  const { readonly = false, debug = false } = options;

  return {
    get(target, key, receiver) {
      const value = Reflect.get(target, key, receiver);

      // Track this access if an effect is watching:
      if (typeof key === "string" || typeof key === "symbol") {
        track(target, key);
      }

      if (debug) {
        console.log(`[REACTIVE GET] ${String(key)} =`, value);
      }

      // If the value is an object, wrap it in a reactive proxy too (deep reactivity):
      if (value !== null && typeof value === "object" && !isProxy(value)) {
        return createReactive(value, options);
      }

      return value;
    },

    set(target, key, value, receiver) {
      if (readonly) {
        console.warn(`[REACTIVE] Attempted to write "${String(key)}" on read-only state.`);
        return false;
      }

      const oldValue = Reflect.get(target, key, receiver);

      if (Object.is(oldValue, value)) return true;   // No actual change

      const success = Reflect.set(target, key, value, receiver);

      if (success) {
        if (debug) {
          console.log(`[REACTIVE SET] ${String(key)}: ${JSON.stringify(oldValue)} → ${JSON.stringify(value)}`);
        }
        trigger(target, key, oldValue, value);   // Notify dependents
      }

      return success;
    },

    deleteProperty(target, key) {
      if (readonly) {
        console.warn(`[REACTIVE] Attempted to delete "${String(key)}" on read-only state.`);
        return false;
      }

      const hadKey    = Reflect.has(target, key);
      const oldValue  = Reflect.get(target, key);
      const success   = Reflect.deleteProperty(target, key);

      if (success && hadKey) {
        trigger(target, key, oldValue, undefined);
      }

      return success;
    },

    has(target, key) {
      track(target, key);
      return Reflect.has(target, key);
    },

    ownKeys(target) {
      track(target, Symbol.for("__ownKeys__"));   // Track enumeration
      return Reflect.ownKeys(target);
    }
  };
}

// Track which objects are already proxied (avoid double-wrapping):
const proxySet = new WeakSet();

function isProxy(obj) {
  return proxySet.has(obj);
}

function createReactive(raw, options = {}) {
  const proxy = new Proxy(raw, createReactiveHandler(options));
  proxySet.add(proxy);
  return proxy;
}

class Store {
  #raw;
  #state;
  #readonlyState;
  #computedCache;
  #debug;

  constructor(initialState, debug = false) {
    this.#raw           = { ...initialState };
    this.#debug         = debug;
    this.#computedCache = new Map();

    // Main reactive state:
    this.#state = createReactive(this.#raw, { debug });

    // Read-only view for safe sharing:
    const { proxy: roProxy, revoke } = Proxy.revocable(
      this.#state,
      createReactiveHandler({ readonly: true, debug })
    );
    this.#readonlyState = roProxy;
    this._revokeReadonly = revoke;   // Store revoke for cleanup
  }

  // Access reactive state:
  get state()   { return this.#state; }

  // Access read-only view:
  get readonly(){ return this.#readonlyState; }

  // Register a side effect that runs whenever its dependencies change:
  effect(fn) {
    const wrappedEffect = () => {
      const prev   = activeEffect;
      activeEffect = wrappedEffect;   // Mark this as the active tracker
      try {
        fn(this.#state);
      } finally {
        activeEffect = prev;          // Restore previous tracker
      }
    };

    wrappedEffect();   // Run once immediately to collect dependencies
    return wrappedEffect;
  }

  // Computed property — cached, recomputes when dependencies change:
  computed(key, computeFn) {
    let cachedValue;
    let dirty = true;   // Flag: needs recomputation

    const recompute = () => { dirty = true; };

    const getter = () => {
      if (dirty) {
        const prev   = activeEffect;
        activeEffect = recompute;   // Track what this computed depends on
        try {
          cachedValue = computeFn(this.#state);
        } finally {
          activeEffect = prev;
        }
        dirty = false;
      }
      return cachedValue;
    };

    this.#computedCache.set(key, getter);
    return getter;
  }

  // Batch multiple mutations — only trigger effects once at the end:
  batch(mutations) {
    const pending = new Set();

    // Temporarily override trigger to collect effects:
    // (Simplified — a production version would queue all triggers)
    mutations(this.#state);
    // Effects fire after the synchronous mutations block completes
  }

  // Snapshot of current state as plain object:
  snapshot() {
    return JSON.parse(JSON.stringify(this.#raw));
  }

  // Clean up — revoke read-only proxy:
  destroy() {
    this._revokeReadonly();
    if (this.#debug) console.log("[STORE] Destroyed — read-only access revoked.");
  }
}

// --- Create a store for a shopping cart ---
const cart = new Store({
  items: [],
  discount: 0,
  user: { name: "Alice", premium: false }
}, true /* debug mode */);

// --- Register an effect: re-render the cart total whenever items or discount change ---
cart.effect(state => {
  const subtotal = state.items.reduce((sum, item) => sum + item.price * item.qty, 0);
  const total    = subtotal * (1 - state.discount);
  console.log(`[CART] ${state.items.length} items | Subtotal: £${subtotal.toFixed(2)} | Total: £${total.toFixed(2)}`);
});
// Runs immediately:
// [CART] 0 items | Subtotal: £0.00 | Total: £0.00

// --- Register an effect: show welcome message when user changes ---
cart.effect(state => {
  console.log(`[USER] Welcome, ${state.user.name} (${state.user.premium ? "Premium" : "Standard"})`);
});
// Runs immediately:
// [USER] Welcome, Alice (Standard)

// --- Computed: item count ---
const itemCount = cart.computed("itemCount", state =>
  state.items.reduce((sum, item) => sum + item.qty, 0)
);

// --- Mutate state ---
cart.state.items.push({ name: "Laptop", price: 899, qty: 1 });
// Triggers cart effect:
// [CART] 1 items | Subtotal: £899.00 | Total: £899.00

cart.state.discount = 0.1;
// Triggers cart effect:
// [CART] 1 items | Subtotal: £899.00 | Total: £809.10

cart.state.user.name = "Bob";
// Triggers user effect:
// [USER] Welcome, Bob (Standard)

console.log("Item count:", itemCount());  // Output: Item count: 1

// --- Read-only view ---
const safeView = cart.readonly;
console.log(safeView.discount);    // Output: 0.1  ← read works
safeView.discount = 0.5;           // [REACTIVE] Attempted to write "discount" on read-only state.
console.log(safeView.discount);    // Output: 0.1  ← unchanged

// --- Snapshot for serialisation ---
const snap = cart.snapshot();
console.log(snap.discount);   // Output: 0.1  ← plain object, safe to serialise

// --- Cleanup ---
cart.destroy();
// [STORE] Destroyed — read-only access revoked.
safeView.discount;
// ❌ TypeError: Cannot perform 'get' on a proxy that has been revoked

function createValidatedStore(schema, initialState) {
  // First validate the initial state:
  for (const [key, type] of Object.entries(schema)) {
    if (key in initialState && typeof initialState[key] !== type) {
      throw new TypeError(`Initial state: "${key}" must be of type "${type}"`);
    }
  }

  const store = new Store(initialState);

  // Wrap the state proxy in a validation layer:
  const validatedState = new Proxy(store.state, {
    set(target, key, value, receiver) {
      if (key in schema && typeof value !== schema[key]) {
        throw new TypeError(
          `"${String(key)}" must be of type "${schema[key]}", got "${typeof value}"`
        );
      }
      return Reflect.set(target, key, value, receiver);
    }
  });

  return { state: validatedState, store };
}

// Usage:
const { state, store } = createValidatedStore(
  { username: "string", score: "number", active: "boolean" },
  { username: "Alice",  score: 0,       active: true }
);

state.score    = 100;      // ✅
state.username = "Bob";    // ✅
state.score    = "high";   // ❌ TypeError: "score" must be of type "number", got "string"

const logged = new Proxy(obj, {
  get(target, property, receiver) {
    const value = Reflect.get(target, property, receiver);
    console.log(`GET "${String(property)}" = ${JSON.stringify(value)}`);
    return value;
  }
});