JavaScript Proxy Objects

A JavaScript Proxy is an object that intercepts fundamental operations on another object, called its target. The handler supplies traps for operations such as property access, assignment, deletion, enumeration, prototype lookup, function calls, and construction.

const observed = new Proxy(
	{ theme: "dark" },
	{
		get(target, property, receiver) {
			console.log(`read ${String(property)}`);
			return Reflect.get(target, property, receiver);
		},
	},
);

JavaScript syntax invokes internal object methods. Reading proxy.x maps to get, x in proxy maps to has, and key enumeration maps to ownKeys. Callable targets also support apply, while constructable targets support construct.

Reflect provides methods named after the traps and is the usual way to forward an operation while preserving its receiver and return value. Calling a Reflect method on the proxy from its matching trap can recurse, so forwarding normally uses the target.

Traps must preserve the target's invariants. For example, get cannot invent a value for a non-writable, non-configurable property, and ownKeys cannot omit a non-configurable key. The engine checks these rules and throws TypeError when a trap lies.

A proxy has its own identity and does not acquire the target's private fields or native internal slots. Proxies around classes, Map, or Set can therefore fail when a method receives the proxy as this. Interception is shallow, so nested values need separate proxies. Proxy.revocable() creates a proxy that can later be disabled.