A Proxy is a built-in JavaScript object that stands in front of another object. You use the Proxy instead of the original object, and every action on it (reading a property, writing a value, deleting, calling a function and more) first goes through code that you write. That code can log the action, check it, change it or block it.
You make a Proxy with new Proxy(target, handler). The target is the real object (or function). The handler is a plain object that holds traps: small methods such as get and set, each one catching one kind of action. A trap that you leave out simply lets the action pass to the target.
Proxy is a constructor and cannot be copied for old browsers.
Always create it with new, as in new Proxy(target, handler). It works in every modern browser and in Node.js, but Internet Explorer does not have it, and no script can add it. Inside traps, use the matching Reflect method to do the normal action.
Syntax
JavaScript Syntax
Create a Proxy with a target and a handler that has one trap:
JavaScript
const user = { name: "Ann", age: 30 };
const proxy = new Proxy(user, {
get(target, key, receiver) {
console.log("Reading " + String(key));
return Reflect.get(target, key, receiver);
}
});
console.log(proxy.name);
// Reading name
// Ann
Reference
Core Ideas
Ideas every Proxy tutorial in this series builds on:
Idea
Example
Remember
Proxy
new Proxy(target, handler)
An object that stands in front of another object and catches actions
Target
const target = { name: "Ann" }
The real object (or function) that the Proxy wraps
Handler
const handler = { get() {} }
A plain object that holds the traps
Trap
get(target, key, receiver)
A handler method that catches one kind of action
Reflect
Reflect.get(target, key, receiver)
The usual way to do the normal action inside a trap
Invariant
A frozen value must stay the same
A rule that traps cannot break, or JavaScript throws a TypeError
Revocable Proxy
Proxy.revocable(target, handler)
A Proxy that you can switch off with revoke()
Compare
Proxy vs Getters and Setters
Before Proxy, the way to watch a property was Object.defineProperty() with a getter and setter. A Proxy can do much more:
Task
Getters and setters
Proxy
Watch a property that exists
Yes, one property at a time
Yes, all properties with one trap
Watch a property added later
No
Yes
Watch delete
No
Yes, with deleteProperty
Watch in and Object.keys()
No
Yes, with has and ownKeys
Watch function calls
No
Yes, with apply and construct
Old browsers
Works in Internet Explorer 9 and up
Not supported in Internet Explorer
Use a plain object when you only need to store data. Use getters and setters for one or two special properties. Use a Proxy when you want to watch or guard everything about an object, such as in validation, logging or default values. A Proxy is a little slower than a plain object, so do not wrap objects that your code uses in tight loops.
Behavior
How a Proxy Works
Use the proxy, not the target
The trick only works when your code talks to the Proxy. The original object still works normally, and anyone who holds it directly bypasses the traps.
Each action has a trap
Reading calls get, writing calls set, the in operator calls has, delete calls deleteProperty, and a function call calls apply. There are 13 traps in total.
Missing traps pass through
If the handler has no trap for an action, the action goes straight to the target. An empty handler {} makes a Proxy that behaves exactly like the target.
Reflect does the normal thing
Inside a trap, Reflect has a method with the same name and arguments, such as Reflect.get() and Reflect.set(). Call it to perform the default action after your own code.
Traps cannot break the rules
JavaScript checks the answer of a trap against the target. For example, a trap cannot report a different value for a frozen property. If it does, a TypeError is thrown.
Practice
Real-Life Uses
A Proxy is a powerful tool. Common uses:
Use
How Proxy helps
Validation
Check every value before it is stored, and throw a clear error for bad data, with the set trap.
Default values
Return a helpful value for a missing property instead of undefined, with the get trap.
Logging and debugging
Record every read, write or function call to see how your data is used.
Protecting data
Hide private names from Object.keys(), block deleting and make some properties read-only.
Temporary access
Lend an object for a short time with Proxy.revocable() and take the access back later.
Code
JavaScript Examples
Three short programs. Each one prints plain text that is the same every time you run it, and they all run in Node.js.
Example 1 — Watch Reads and Writes of an Object
Wrap an object so that every read and write leaves a note. The traps use Reflect to do the normal work.
A Proxy is a built-in object that stands in front of another object (the target). Actions on the Proxy, such as reading, writing, deleting or calling, first go through traps that you write in a handler object, and the traps can log, check, change or block the action.
The target is the real object (or function) that the Proxy wraps. The handler is a plain object that holds the traps, such as get and set. A trap that is missing lets the action pass to the target.
A trap is a method of the handler that catches one kind of action. There are 13: apply, construct, defineProperty, deleteProperty, get, getOwnPropertyDescriptor, getPrototypeOf, has, isExtensible, ownKeys, preventExtensions, set and setPrototypeOf.
Reflect has a method with the same name and arguments as each trap. Calling it, for example Reflect.get(target, key, receiver), performs the normal action, so your trap can add its own code and still keep the default behaviour.
It works in every current browser (Chrome, Edge, Firefox, Safari and Opera) and in Node.js. It does not work in Internet Explorer, and it cannot be added to old browsers with a script.