Proxy

Proxies in one sentence

A Proxy is an object that stands in front of another object or function, called the target. Code talks to the proxy. The proxy’s handler can intercept operations such as reading a property, writing a property, checking in, deleting, listing keys, calling a function, or using new.

This lesson builds directly on Property flags & descriptors, Getters & setters, The prototype chain, and Private fields & methods. A proxy is broader than a getter or setter: it can watch an entire object, not just one property name.

Proxies are a metaprogramming feature. They let code change how other code interacts with an object. That power is useful for validation, logging, reactive state, access control, and wrappers around APIs. It is also easy to overuse, so this lesson is careful about the limits.

A proxy always has two pieces: a target and a handler. The handler is an ordinary object. Its method names are special: get catches property reads, set catches property writes, and so on. Each method is called a trap because the operation falls into it before it reaches the target.

The safest trap usually forwards to the matching Reflect method. For example, Reflect.get(target, property, receiver) performs the normal property read and preserves important details such as getters and the receiver. The next lesson, Reflect, is the companion API for this forwarding pattern.

JavaScript defines exactly 13 proxy traps. Most targets are plain objects, so the first 11 cover object operations. The last two, apply and construct, work only when the target is callable or constructable.

The logger below is the heart of the lesson. Press each operation and watch the trap sequence. Notice that high-level tools may call more than one trap: Object.keys(proxy) asks for ownKeys, then checks descriptors so it can return only enumerable string keys.

1const target = { name: "Ada", role: "admin" };2const handler = {3  get(target, property, receiver) {4    return Reflect.get(target, property, receiver);5  },6  set(target, property, value, receiver) {7    return Reflect.set(target, property, value, receiver);8  },9  has(target, property) {10    return Reflect.has(target, property);11  },12  deleteProperty(target, property) {13    return Reflect.deleteProperty(target, property);14  },15  ownKeys(target) {16    return Reflect.ownKeys(target);17  },18  getOwnPropertyDescriptor(target, property) {19    return Reflect.getOwnPropertyDescriptor(target, property);20  },21  defineProperty(target, property, descriptor) {22    return Reflect.defineProperty(target, property, descriptor);23  },24  getPrototypeOf(target) {25    return Reflect.getPrototypeOf(target);26  },27  setPrototypeOf(target, prototype) {28    return Reflect.setPrototypeOf(target, prototype);29  },30  isExtensible(target) {31    return Reflect.isExtensible(target);32  },33  preventExtensions(target) {34    return Reflect.preventExtensions(target);35  },36  apply(target, thisArg, args) {37    return Reflect.apply(target, thisArg, args);38  },39  construct(target, args, newTarget) {40    return Reflect.construct(target, args, newTarget);41  },42};43const proxy = new Proxy(target, handler);

1proxy.name;

A handler does not have to define every trap. Missing traps are transparent: JavaScript performs the target’s ordinary behavior. Professional proxy code often defines only one or two traps and forwards everything else with Reflect.

The set trap is a natural place to validate data before it enters an object. In strict mode, a successful set trap must return a truthy value. Returning false, or forgetting to return anything, means the assignment failed and strict code throws a TypeError.

1"use strict";2const user = { age: 0 };Run3const userProxy = new Proxy(user, {4  set(target, property, value, receiver) {5    if (property === "age") {6      if (typeof value !== "number") {7        throw new TypeError("age must be a number");8      }9      if (value < 0) {10        throw new TypeError("age must be non-negative");11      }12    }13    return Reflect.set(target, property, value, receiver);14  },15});16 17userProxy.age = 36;18console.log(user.age);

This is similar to a setter from Getters & setters, but wider. One set trap can validate many property names, log every change, or block unknown fields. The trade-off is clarity: someone reading userProxy.age = 36 has to know a proxy stands in the middle.

A proxy can watch writes and deletions, then notify another part of your program. This pattern is called an observable object. The small lab below wraps a cart, records changes, and re-renders a tiny summary each time.

1const cart = { apples: 1, pears: 2 };2const changes = [];3const observed = new Proxy(cart, {4  set(target, property, value, receiver) {5    const before = target[property];6    const ok = Reflect.set(target, property, value, receiver);7    changes.push({ type: "set", property, before, after: value });8    render();9    return ok;10  },11  deleteProperty(target, property) {12    const before = target[property];13    const ok = Reflect.deleteProperty(target, property);14    changes.push({ type: "delete", property, before });15    render();16    return ok;17  },18});

Real reactive systems are more sophisticated. They track which views depend on which properties, batch updates, avoid infinite loops, and integrate with scheduling. But the first idea is the same as the lab: intercept the operation, forward it, then notify interested code.

Sometimes a wrapper should stop working: a plugin unloads, a permission expires, or a temporary API view must be closed. Proxy.revocable creates exactly that. It returns an object with proxy and revoke. After revoke(), every later operation on the proxy throws a TypeError.

1const target = { secret: "draft" };2const { proxy, revoke } = Proxy.revocable(target, {3  get(target, property, receiver) {4    return Reflect.get(target, property, receiver);5  },6});7 8console.log(proxy.secret);9revoke();10console.log(proxy.secret);

A proxy is powerful, but it is not allowed to break the language’s promises. These promises are called invariants. If a target has a non-configurable, non-writable data property, the get trap cannot pretend its value is different. If the target is non-extensible, traps cannot invent extra own keys. When a trap breaks an invariant, JavaScript throws a TypeError.

1const target = {};2Object.defineProperty(target, "answer", {3  value: 42,4  writable: false,5  configurable: false,6});7const liar = new Proxy(target, {8  get() {9    return 43;10  },11});12liar.answer;

1const target = {};2Object.defineProperty(target, "answer", {3  value: 42,4  writable: false,5  configurable: false,6});7const liar = new Proxy(target, {8  get() {9    return 43;10  },11});12liar.answer;

1class SecretBox {2  #secret = "safe";3  read() {4    return this.#secret;5  }6}7const box = new SecretBox();8const proxy = new Proxy(box, {});9proxy.read();

1const map = new Map([["score", 10]]);2const proxy = new Proxy(map, {});3proxy.get("score");4 5const fixed = new Proxy(map, {6  get(target, property, receiver) {7    const value = Reflect.get(target, property, receiver);8    return typeof value === "function" ? value.bind(target) : value;9  },10});11fixed.get("score");

1const target = { id: 1 };2const proxy = new Proxy(target, {});3console.log(proxy === target);

Where you’ll use this

Proxies are usually library tools rather than everyday application tools. You will meet them in state libraries, API clients, validation layers, plugin systems, testing helpers, and security membranes. A membrane is a wrapper boundary: outside code receives proxies instead of direct objects, so every crossing can be logged, limited, or revoked.

• Validation: reject invalid writes before they enter a shared model.
• Observation: record every set and delete so a view can update.
• Virtual objects: compute values lazily or represent data that lives somewhere else.
• Access control: expose a safe subset of a larger object, sometimes with Proxy.revocable.

Common misconceptions

Try the answer first, then read the explanations. Proxy details reward careful wording.

Key takeaways

• A proxy is a wrapper around a target, controlled by a handler object.
• Traps are handler methods named after operation categories; missing traps pass through.
• There are 13 traps: 11 object traps plus apply and construct for function targets.
• Use Reflect to forward ordinary behavior and return the right trap result.
• Invariants are enforced with TypeError; proxies cannot lie about locked target facts.
• Private fields, internal slots, and identity do not magically forward through proxies.

Up next: Reflect, the companion API for forwarding proxy operations cleanly and predictably.