JavaScript Reference ยท JSON, Errors and Reflection
The Proxy object
Reference for the JavaScript Proxy object: wrap a target with a handler to intercept reads, writes and more, with validation, defaults, revocable proxies and pitfalls.
A Proxy wraps another object (the target) and lets you intercept the operations performed on it: reading a property, assigning one, checking in, deleting, enumerating keys, calling a function and more. You describe the interceptions in a handler object whose methods are called traps. Any operation without a trap passes straight through to the target.
Proxies power validation layers, default values, logging, change tracking and reactive frameworks. They are a tool for building abstractions, not for everyday code: a proxy adds indirection and makes behavior harder to follow.
const proxy = new Proxy({}, { get(target, key) { return key in target ? target[key] : "none"; }, });
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
new Proxy(target, handler) Proxy.revocable(target, handler)
| Name | Description |
|---|---|
target |
The object to wrap: any object, including arrays, functions and other proxies. |
handler |
An object whose methods are the traps. An empty object {} makes a transparent proxy. See Proxy handler traps. |
Return value: new Proxy() returns the proxy. Proxy.revocable() returns { proxy, revoke }; calling revoke() makes every later operation on the proxy throw a TypeError.
Exceptions: TypeError if target or handler is not an object, or if Proxy is called without new. A trap that breaks an invariant (see below) also throws a TypeError.
Usage notes
- A proxy is a different object from its target.
proxy === targetis false; writing through the proxy changes the target, but code that holds the target directly bypasses all traps. - Return
truefrom asettrap. Returning a falsy value makes the assignment throw aTypeErrorin strict mode (modules and classes) and fail silently otherwise. - Invariants are enforced. For example, a
gettrap cannot report a different value for a non-writable, non-configurable target property. This protects frozen objects. - Use
Reflectinside traps to forward the default behavior correctly, including thereceiver. SeeReflect. - Built-ins with internal slots break. Methods of
Map,Set,Dateand objects with private fields (#x) require the real object asthis, so calling them through a proxy throws aTypeError. Bind the method to the target in agettrap. - Type checks look through the proxy:
Array.isArray(new Proxy([], {}))is true, andtypeofis that of the target. - Performance. Every intercepted operation runs your JavaScript, so avoid proxies on hot paths.
- Not polyfillable. A proxy cannot be emulated in older engines.
- Nested objects are not wrapped automatically. To track deep changes, return another proxy from the
gettrap.
Browser support
Proxy is supported in every current browser and in Node.js. It cannot be polyfilled for older browsers.