JavaScript Proxy

Proxy traps, handler invariants, receiver forwarding, and why a Proxy around a built-in such as Map is not a security sandbox.

モジュールページの本文は現在英語です。

new Proxy(target, handler) creates an object whose operations can run traps such as get and set. When a trap is omitted, the operation is forwarded to the target, usually through Reflect.

The engine still enforces invariants on the target. If a property is non-writable and non-configurable, a get trap must return the same value or the access throws TypeError. A Proxy is not a security sandbox: it does not hide the target from code that already holds a reference, and it does not isolate privileges.

Some built-ins keep internal state in private slots, including Map, Set, Date, and Promise. A method looked up through a Proxy is often called with the proxy as this, which fails the internal brand check and throws TypeError. Binding the method to the real target can make a private-slot method work, but that is not a sandbox and it must be done with care.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
new Proxy and get/set trapsA get or set trap can log or rewrite an operation. Invariant violations, such as changing a non-writable, non-configurable value, throw TypeError.
Proxy and Map private slotsMap, Set, Date, and similar built-ins can throw TypeError when a method’s this is a Proxy. Binding the method to the target is a workaround, not a sandbox.

Traps, invariants, and receiver

get(target, key, receiver) and set(target, key, value, receiver) receive the original target and the receiver that started the operation. Forwarding with Reflect.get(target, key, receiver) and Reflect.set(...) keeps getter and setter this values consistent.

If the target property is non-writable and non-configurable, returning a different value from get violates an invariant and throws TypeError. These checks are part of the language, not an optional linter rule.

new Proxy and get/set traps

new Proxy(target, handler)
handler.get(target, property, receiver)
handler.set(target, property, value, receiver)

A get or set trap can log or rewrite an operation. Invariant violations, such as changing a non-writable, non-configurable value, throw TypeError.

ParameterDescription
targetThe object that operations are forwarded to when a trap does not override them.
handlerAn object that may define traps. An omitted trap is forwarded to the target.
receiverThe object that initiated the get or set, often the proxy itself, used as this for accessors when forwarded with Reflect.

Returns: The Proxy object. A get trap returns the property value. A set trap should return a boolean, as Reflect.set does.

Throws

  • TypeError — Thrown when a trap result violates an invariant, or when new Proxy is called with a non-object target or handler.
javascript
const logs = [];
const data = { n: 1 };
const proxy = new Proxy(data, {
  get(target, key, receiver) {
    logs.push(`get:${String(key)}`);
    return Reflect.get(target, key, receiver);
  },
  set(target, key, value, receiver) {
    logs.push(`set:${String(key)}=${value}`);
    return Reflect.set(target, key, value, receiver);
  },
});
proxy.n = 2;
console.log(proxy.n, data.n, logs.join(","));

const locked = {};
Object.defineProperty(locked, "x", { value: 1, writable: false, configurable: false });
const broken = new Proxy(locked, {
  get() {
    return 2;
  },
});
try {
  console.log(broken.x);
} catch (error) {
  console.log(error.name);
}

Expected output

2 2 set:n=2,get:n
TypeError

Related: Built-in private slots, Reflect.get and set, Official Proxy

MDN documentation →

Built-in private slots are not a sandbox

new Proxy(new Map([["a", 1]]), {}).get("a") looks up Map.prototype.get and then calls it with the proxy as this. Map methods check an internal slot that the proxy does not have, so the call throws TypeError.

Binding the method to the underlying Map, as the second example does, makes get work. That pattern still shares the real target with the trap. It is a compatibility workaround, not a security boundary. Do not describe a Proxy as a sandbox for untrusted code.

Proxy and Map private slots

new Proxy(map, handler)

Map, Set, Date, and similar built-ins can throw TypeError when a method’s this is a Proxy. Binding the method to the target is a workaround, not a sandbox.

Throws

  • TypeError — Thrown when a built-in method requires its private slot and this is the proxy rather than the branded target.
  • The empty-handler proxy still fails for mapProxy.get, because the method is invoked with the proxy as this.
  • Code that already holds the target can ignore the proxy entirely.
javascript
const mapProxy = new Proxy(new Map([["a", 1]]), {});
try {
  mapProxy.get("a");
} catch (error) {
  console.log(error.name);
}
const map = new Map([["a", 1]]);
const forwarded = new Proxy(map, {
  get(target, key, receiver) {
    const value = Reflect.get(target, key, receiver);
    return typeof value === "function" ? value.bind(target) : value;
  },
});
console.log(forwarded.get("a"));

Expected output

TypeError
1

Related: Map, Function.prototype.bind, Official Proxy handler invariants

MDN documentation →