Proxy

Proxies in one sentence

A Proxy is an object that stands in front of another object. The object behind it is called the target. The target can also be a function. Your code talks to the proxy, not to the target.

The proxy has a handler. The handler is a plain object with rules in it. A rule can catch an action before the action reaches the target. These are some of the actions a rule can catch:

• reading a property, like proxy.name
• writing a property, like proxy.name = "Mina"
• checking a property with in
• deleting a property
• listing the keys
• calling a function, or using new

This lesson uses ideas from four earlier lessons:

• Property flags & descriptors
• Getters & setters
• The prototype chain
• Private fields & methods

A getter or setter controls one property. A proxy can watch the whole object.

Code that changes how other code works with an object is called metaprogramming. A proxy is one tool for it. People use proxies to:

• check values before they are saved
• write down every action in a log
• update the page when data changes
• limit what other code is allowed to do

Proxies are easy to overuse, so this lesson also shows their limits.

Every proxy has two parts:

• The target: the real object the proxy stands in front of.
• The handler: a plain object with methods in it.

The handler's method names are special. A method named get runs when someone reads a property. A method named set runs when someone writes a property. Each of these methods is called a trap, because the action falls into it before it reaches the target.

A proxy is not the only way to control an object. The table compares it with two tools from earlier lessons. Read each row as: "this tool catches this, it is good for this, and watch out for this."

A trap often needs to do the normal action too, after its own work. The Reflect object has one method for each trap, with the same name. Each method does the normal action. For example, Reflect.get(target, property, receiver) does a normal property read. Handing the action on to the target like this is called forwarding. The next lesson, Reflect, covers these methods.

const account = {
  first: "Asha",
  last: "Khan",
  get label() {
    return this.first + " " + this.last;
  },
};
const proxy = new Proxy(account, {
  get(target, property, receiver) {
    return Reflect.get(target, property, receiver);
  },
});
console.log(proxy.label);

A get trap receives three values:

• target: the real object, here account.
• property: the name being read, here "label".
• receiver: the object the read started from. Here it is the proxy.

Line 4 makes a getter: a method that runs when you read a property. It uses this. Line 10 passes the receiver on, so inside the getter this is the proxy. Line 13 prints Asha Khan.

If you leave the receiver out, this inside the getter becomes the target. Then the reads inside the getter skip the proxy and its traps.

JavaScript has exactly 13 traps. The first 11 work on any object. The last two only work when the target is a function:

• apply runs when you call the proxy, like proxy(2, 3).
• construct runs when you use new on the proxy, like new proxy("Ada").

Read each row of the table as: "this trap runs when you write this code, and it must give back this."

const settings = { theme: "light" };
const proxy = new Proxy(settings, {
  get(target, property, receiver) {
    return Reflect.has(target, property)
      ? Reflect.get(target, property, receiver)
      : "not set";
  },
});
console.log(proxy.theme);
console.log(proxy.language);

The get trap first checks if the setting exists. Reflect.has does the same check as the in operator.

• Line 9 reads theme. It exists, so the trap passes the read on, and the line prints light.
• Line 10 reads language. It does not exist, so the trap gives back not set instead.

The target never gets a language property. The value only shows up when you read it through the proxy.

The playground below is the main experiment of this lesson. Its handler has all 13 traps. Each trap writes a note, then passes the action on. Press a button to run one action and see which traps ran, in order.

Some actions run more than one trap. For example, Object.keys(proxy) first runs ownKeys to get the list of keys. Then it runs getOwnPropertyDescriptor for each key. That reads the key's settings, so Object.keys can keep only the keys that show up in loops. Those keys are called enumerable.

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 doesn't need all 13 traps. If a trap is missing, the action goes to the target and works as usual. Real proxy code often has just one or two traps, and uses Reflect inside them.

const user = { name: "Asha", role: "editor" };
const accessLog = [];
const proxy = new Proxy(user, {
  get(target, property, receiver) {
    accessLog.push(String(property));
    return Reflect.get(target, property, receiver);
  },
});
proxy.name;
proxy.role;
console.log(accessLog.join(", "));

Each read runs the get trap. Line 5 adds the property name to accessLog. Line 6 passes the read on. Lines 9 and 10 read name and role, so line 11 prints name, role.

A log like this helps you find reads you didn't expect. But a trap that runs on every read also makes the code slower and harder to debug.

The set trap runs before a new value goes into the object. So it is a good place to check the value first. Checking values like this is called validation.

A set trap must also report if the write worked:

• Return true when the write worked.
• Return false when it did not.

In strict mode, a false answer makes JavaScript throw a TypeError. Strict mode is the stricter version of JavaScript that the line "use strict" turns on. Forgetting to return anything counts as false too. The trap then returns undefined, which is falsy: a value that acts like false.

The code below checks age in a set trap. Choose a value, then step through it.

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 like a setter from the Getters & setters lesson, but it can do more. One set trap can check many property names, log every change, or refuse names it doesn't know. The cost: someone who reads userProxy.age = 36 can't tell that a trap runs there.

"use strict";
const profile = { name: "Asha" };
const readOnly = new Proxy(profile, {
  get(target, property, receiver) {
    return Reflect.get(target, property, receiver);
  },
  set() {
    return false;
  },
});
console.log(readOnly.name);
try {
  readOnly.name = "Mina";
} catch (error) {
  console.log(error.name);
}

The set trap on line 7 always returns false. So every write is refused, and profile does not change. The code is in strict mode, so line 13 throws a TypeError. The catch block prints its name. The output is Asha, then TypeError.

A read-only proxy is useful when you want one on purpose. If only one property needs protection, a property flag (writable: false) or a copy of the data is often clearer.

A proxy can watch for writes and deletes, then tell another part of your program about them. An object watched like this is called an observable object.

The lab below puts a proxy in front of a cart. Each change goes into a change log, and the cart summary is drawn again.

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 libraries that update a page when data changes do more than this lab:

• They track which parts of the page use which properties.
• They group many changes into one update.
• They stop a change from setting off another change, over and over.

But they start with the same three steps as the lab:

1. Catch the action in a trap.
2. Pass it on to the target.
3. Tell the code that cares about the change.

Sometimes a proxy should stop working. For example, a plugin is removed, a permission runs out, or a short-term view of an object must be closed. Proxy.revocable(target, handler) makes a proxy you can turn off. It returns an object with two properties:

• proxy: the proxy to use.
• revoke: a function that turns the proxy off.

After revoke() runs, any action on the proxy throws a TypeError. You can't turn it back on.

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 must keep some promises the language makes. These promises are called invariants: rules JavaScript always checks, even when a trap runs. Here are two of them:

• If a property on the target is locked, the get trap must give back its real value. Locked means two things: it can't be changed (writable: false), and it can't be removed or reset (configurable: false).
• If the target can't get new properties, the traps can't make up extra keys. Such a target is called non-extensible.

When a trap breaks one of these rules, JavaScript throws a TypeError.

The lab below runs four cases. Each one shows something a proxy can't change. Each case is explained again after the lab.

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 date = new Date("2026-01-01T00:00:00Z");2const proxy = new Proxy(date, {});3try {4  console.log(proxy.getUTCFullYear());5} catch (error) {6  console.log(error.name);7}8const fixed = new Proxy(date, {9  get(target, property, receiver) {10    const value = Reflect.get(target, property, receiver);11    return typeof value === "function" ? value.bind(target) : value;12  },13});14console.log(fixed.getUTCFullYear());

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

Where you’ll use this

Most app code doesn't need proxies. You will mostly meet them inside libraries:

• state libraries that update the page when data changes
• clients that talk to a server's API
• code that checks values before they are saved
• plugin systems and testing helpers

Some security tools build a membrane: a wall of proxies around a group of objects. Outside code only gets proxies, never the real objects. So every action that crosses the wall can be logged, limited, or turned off.

These are the four jobs proxies do most often:

• Checking values: refuse bad writes before they reach an object that other code shares.
• Watching: record every write and delete, so the page can update.
• Made-up values: work out a value only when someone reads it, or show data that is stored somewhere else.
• Limiting access: show other code only a safe part of a bigger object, sometimes with Proxy.revocable.

Every trap adds extra work to each action. It also makes error messages longer and harder to read. Keep code that runs very often simple. Measure real use before you swap plain objects for proxies.

const drinks = ["tea", "coffee", "water"];
const proxy = new Proxy(drinks, {
  get(target, property, receiver) {
    const index = Number(property);
    if (Number.isInteger(index) && index < 0) {
      return Reflect.get(target, target.length + index, receiver);
    }
    return Reflect.get(target, property, receiver);
  },
});
console.log(proxy[-1]);
console.log(proxy[-2]);

Property names reach the trap as strings, so -1 arrives as "-1".

• Line 4 turns the property name into a number.
• Line 5 checks for a whole number below 0.
• Line 6 adds it to the length. For -1, that is 3 + (-1) = 2, the last item.

So line 11 prints water, and line 12 prints coffee. The array never gets a -1 property. Keep a trick like this small and well explained, so it doesn't surprise other people who read your code.

Common misconceptions

Try each answer before you read the explanations. Small details matter with proxies.

Key takeaways

• A proxy stands in front of a target. A handler object holds its rules.
• The handler's methods are called traps. Each trap catches one kind of action. If a trap is missing, the action goes to the target as usual.
• There are 13 traps: 11 for any object, plus apply and construct for functions.
• Use Reflect inside a trap to do the normal action and give back the right answer.
• Traps must keep the language's rules (invariants). If a trap lies about a locked property, JavaScript throws a TypeError.
• Private fields, Map and Date methods, and === still see the proxy as a different object from its target.

Up next: Reflect, the object with one method for each trap. It makes passing actions on to the target simple and safe.