Observe operations
Record reads or writes for debugging, auditing, or metrics.
JavaScript · Class
Proxy
The Proxy() constructor creates a proxy that wraps a target object and can intercept selected fundamental operations. A handler supplies trap functions for customizing those operations.
How it works
A Proxy wraps a target object and uses handler trap functions to intercept selected fundamental operations, such as property reads and writes. Each trap can customize the operation or delegate to the corresponding Reflect method. The target may be an object, array, function, or another proxy.
Syntax
new Proxy(target, handler)Parameters
| Name | Type | Description |
|---|---|---|
target | object | The object to wrap. It may be an array, function, or another proxy. |
handler | object | An object whose function-valued properties define the proxy's custom behavior. |
Returns
A new Proxy object that wraps target and applies the behavior defined by handler.
Key points
- Use the Proxy constructor to create an object that stands in for another object.
- Code can generally use the proxy where it would use the original target.
- The target is the object being wrapped and can be an array, function, or another proxy.
- The handler contains trap methods that define which operations are intercepted.
- Define only the traps needed for behaviors such as logging, validation, or transformation.
- Typical uses include observing access, validating assignments, and normalizing or sanitizing values.
Common mistakes
- Always use new Proxy(...); calling Proxy(...) without new throws a TypeError.
- An empty handler does not add custom behavior; it mostly mirrors the target.
Example: Log property access
const user = { name: "Ada" };
const observed = new Proxy(user, {
get(target, property, receiver) {
console.log(`Reading ${String(property)}`);
return Reflect.get(target, property, receiver);
},
});
console.log(observed.name);The proxy logs property reads, then delegates the actual lookup to Reflect.get.
When to use it
Validate data
Reject invalid assignments or enforce object invariants at runtime.
Customize access
Present computed, normalized, or virtual properties through an object-like interface.
Adapt an interface
Hide or transform selected values while exposing a compatible object API.
Related
Proxy.revocable()Reflecthandler.get()handler.set()