Proxy & Reflect

Intercept and customise fundamental object operations — get, set, delete, function calls, and more — with Proxy traps and the Reflect API.

What it is, in plain English: A Proxy wraps an object and lets you intercept (trap) fundamental operations on it: reading a property, writing a property, deleting a property, calling a function, and more. For every trap you define, the corresponding operation is redirected through your handler. The Reflect API provides the default behaviour for each operation — so you can intercept, do something extra, and then delegate the real work to Reflect.

Where this bites you

A Proxy only guards the object you wrap, not the objects inside it. Reading config.db through a read-only proxy hands back the plain inner object, and writes to that object go straight through with no error. The same applies to validation and change-tracking proxies: nested changes skip your traps entirely. Object.freeze is shallow in exactly the same way.

function readonly(target) {
  return new Proxy(target, {
    set(_, key) {
      throw new TypeError(`Cannot set "${key}" — object is read-only`);
    },
    deleteProperty(_, key) {
      throw new TypeError(`Cannot delete "${key}" — object is read-only`);
    }
  });
}

const config = readonly({ endpoint: "/api", db: { password: "s3cret" } });
config.db.password = "hacked";     // no error: config.db is the plain inner object
console.log(config.db.password);
// hacked

Wrapping objects to intercept their operations

A Proxy sits in front of an object. Every time code tries to read, write, or delete a property on the proxy, your handler function gets called first — giving you a chance to validate, log, transform, or block the operation.

Creating a Proxy

// new Proxy(target, handler)
// target  — the real object being wrapped
// handler — an object with "trap" methods

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

const proxy = new Proxy(person, {
  get(target, key) {
    // Called every time proxy.someProperty is read
    console.log(`→ Reading "${key}"`);
    return target[key];  // return the actual value
  },
  set(target, key, value) {
    // Called every time proxy.someProperty = value
    console.log(`→ Writing "${key}" = ${value}`);
    target[key] = value;
    return true;   // must return true to indicate success
  }
});

proxy.name;         // logs: → Reading "name"
proxy.age = 31;     // logs: → Writing "age" = 31

The most useful trap: validation

function createValidatedUser(data) {
  return new Proxy(data, {
    set(target, key, value) {
      if (key === "age") {
        if (typeof value !== "number") throw new TypeError("age must be a number");
        if (value < 0 || value > 150)  throw new RangeError("age must be 0–150");
      }
      if (key === "email" && !value.includes("@")) {
        throw new Error("Invalid email address");
      }
      target[key] = value;
      return true;
    }
  });
}

const user = createValidatedUser({ name: "Bob" });
user.name  = "Bob";         // fine
user.age   = 25;            // fine
// user.age   = -5;         // throws: age must be 0–150
// user.email = "notvalid"; // throws: Invalid email address

Reflect — the default implementation

Inside a trap, use Reflect to perform the operation normally. This is cleaner than manually doing target[key] because Reflect handles edge cases correctly (inherited properties, getters/setters, etc.).

const handler = {
  get(target, key, receiver) {
    console.log(`Reading "${key}"`);
    return Reflect.get(target, key, receiver);  // same as: target[key]
  },
  set(target, key, value, receiver) {
    console.log(`Writing "${key}"`);
    return Reflect.set(target, key, value, receiver);  // same as: target[key] = value
  }
};

const proxy = new Proxy({ x: 1 }, handler);
proxy.x;      // "Reading x"
proxy.y = 2;  // "Writing y"

Try It Yourself

// Basic Proxy — intercept property reads and writes
const target = { name: "Alice", age: 30 };

const proxy = new Proxy(target, handler);

console.log(proxy.name);   // Reading: name → "Alice"
proxy.age = 31;            // Writing: age = 31
console.log(proxy.age);    // Reading: age → 31

try {
  proxy.age = -5;          // throws: age must be a non-negative number
} catch(e) {
  console.log(e.message);
}

// Reflect — the default behaviour for each operation
const obj = { x: 10 };
console.log(Reflect.get(obj, "x"));         // 10
Reflect.set(obj, "y", 20);
console.log(obj.y);                          // 20
console.log(Reflect.has(obj, "x"));         // true (like 'x' in obj)
Reflect.deleteProperty(obj, "x");
console.log(obj.x);                          // undefined

Practical Proxy patterns

Default values for missing properties

// Return a default instead of undefined for missing keys:
function withDefaults(target, defaults) {
  return new Proxy(target, {
    get(target, key) {
      return key in target ? target[key] : defaults[key];
    }
  });
}

const config = withDefaults({ port: 8080 }, {
  port:    3000,
  host:    "localhost",
  debug:   false,
  timeout: 5000,
});

console.log(config.port);     // 8080 (set)
console.log(config.host);     // "localhost" (default)
console.log(config.debug);    // false (default)
console.log(config.timeout);  // 5000 (default)

Readonly objects

function readonly(target) {
  return new Proxy(target, {
    set(_, key) {
      throw new TypeError(`Cannot set "${key}" — object is read-only`);
    },
    deleteProperty(_, key) {
      throw new TypeError(`Cannot delete "${key}" — object is read-only`);
    }
  });
}

const config = readonly({ apiKey: "abc123", endpoint: "/api" });
config.endpoint;          // "/api" — reading works
// config.endpoint = "x"; // TypeError: Cannot set "endpoint" — object is read-only

To make the protection deep, add a get trap that wraps any object value in the same proxy before handing it back. Every level you reach through the proxy is then guarded too. (Each read creates a new proxy, so config.db === config.db is false. Cache the proxies in a WeakMap if object identity matters.)

function readonly(target) {
  return new Proxy(target, {
    get(target, key, receiver) {
      const value = Reflect.get(target, key, receiver);
      return value !== null && typeof value === "object" ? readonly(value) : value;   // wrap nested objects on the way out
    },
    set(_, key) {
      throw new TypeError(`Cannot set "${key}" — object is read-only`);
    },
    deleteProperty(_, key) {
      throw new TypeError(`Cannot delete "${key}" — object is read-only`);
    }
  });
}

const config = readonly({ endpoint: "/api", db: { password: "s3cret" } });
try {
  config.db.password = "hacked";
} catch (e) {
  console.log(e.message);
}
console.log(config.db.password);
// Cannot set "password" — object is read-only
// s3cret

Function proxy — intercept calls

function withLogging(fn, name = fn.name) {
  return new Proxy(fn, {
    apply(target, thisArg, args) {
      console.log(`→ ${name}(${args.map(a => JSON.stringify(a)).join(", ")})`);
      const result = Reflect.apply(target, thisArg, args);
      console.log(`← ${name} returned: ${JSON.stringify(result)}`);
      return result;
    }
  });
}

function add(a, b) { return a + b; }
const loggedAdd = withLogging(add);
loggedAdd(2, 3);
// → add(2, 3)
// ← add returned: 5

Observable/reactive state

// The pattern behind Vue 3's reactivity system:
function reactive(target, onChange) {
  return new Proxy(target, {
    set(target, key, value) {
      const old = target[key];
      target[key] = value;
      if (old !== value) onChange(key, old, value);
      return true;
    }
  });
}

const state = reactive({ count: 0 }, (key, old, val) => {
  console.log(`${key}: ${old} → ${val}`);
});

state.count++;  // count: 0 → 1
state.count++;  // count: 1 → 2

All 13 traps and Proxy invariants

Complete trap list (ECMA-262 §10.5)

const handler = {
  get(target, key, receiver)         {},  // property read
  set(target, key, value, receiver)  {},  // property write
  has(target, key)                   {},  // 'key' in proxy
  deleteProperty(target, key)        {},  // delete proxy.key
  defineProperty(target, key, desc)  {},  // Object.defineProperty
  getOwnPropertyDescriptor(t, key)   {},  // Object.getOwnPropertyDescriptor
  ownKeys(target)                    {},  // Object.keys, for...in
  getPrototypeOf(target)             {},  // Object.getPrototypeOf
  setPrototypeOf(target, proto)      {},  // Object.setPrototypeOf
  isExtensible(target)               {},  // Object.isExtensible
  preventExtensions(target)          {},  // Object.preventExtensions
  apply(target, thisArg, args)       {},  // proxy() — function calls
  construct(target, args, newTarget) {},  // new proxy()
};

Proxy invariants

The spec enforces invariants that prevent traps from lying about non-configurable or non-writable properties. For example: if a property on the target is non-configurable and non-writable, the get trap must return that exact value — it cannot return a different one. These invariants preserve the integrity guarantees of Object.defineProperty.

Reflect as the complete proxy twin

The Reflect API has exactly one method per Proxy trap — same signature, same semantics. This is not a coincidence: the spec defines the internal object operations as abstract operations ([[Get]], [[Set]], [[HasProperty]], etc.) and both Proxy traps and Reflect methods map directly to these. Always use Reflect inside a trap to delegate to the default behaviour, passing the correct receiver (important for getters/setters defined on the prototype).

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.