この記事はまだボランティアによって 日本語 に翻訳されていません。ぜひ MDN に参加して翻訳を手伝ってください!
Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.
Warning: The SpiderMonkey Proxy implementation is a prototype and the Proxy API and semantics specifications are unstable. The SpiderMonkey implementation may not reflect the latest specification draft. It is subject to change anytime. It is provided as an experimental feature. Do not rely on it for production code.
Introduction
Proxies are objects for which the programmer has to define the semantics in JavaScript. The default object semantics are implemented in the JavaScript engine, often written in lower-level languages like C++. Proxies let the programmer define most of the behavior of an object in JavaScript. They are said to provide a meta-programming API.
Terminology
- catch-all mechanism (or "intercession API")
- The technical term for this feature.
- handler
- The object that intercepts properties.
- proxy
- The object whose properties are being intercepted.
- proxy factory
- The object or method that creates intercessive proxies.
- traps
- The methods that provide property access. This is analogous to the concept of traps in operating systems.
Proxies can be either be trapping or fixed.
Proxy API
Catch-alls can be defined only on distinct proxy objects, controlled by a handler object. There are two kinds of proxies:
object proxies
var proxy = Proxy.create(handler, proto);
and function proxies :
var proxy = Proxy.createFunction(handler, callTrap, constructTrap);
Where:
proto
is an optional object representing the proxy’s prototype (defaults tonull
if none is provided).callTrap
is a variable-argumentfunction(args) { return any; }
that reifies “proxy(args)
”. Note: The this-binding of thecallTrap
function is the this-binding of the call-site.constructTrap
is an optional variable-argumentfunction(args) { return any-object; }
that reifies “new proxy(args)
”. The this-binding of theconstructTrap
is eitherundefined
(in strict mode) or the global object (in non-strict mode). If noconstructTrap
is provided, performingnew proxy(...args)
calls the proxy’scallTrap
withthis
bound to a new object delegating to the proxy's prototype.handler
is an object that implements the handler API.
Handler API
There are two kinds of traps: fundamental and derived traps. If one of the fundamental traps isn't implemented and the proxy is used in a way that expects the fundamental trap to be defined, then an error is thrown. If a derived trap is implemented, then that trap's code is called whenever the corresponding behavior happens on the proxy. If the derived trap is undefined, a default implementation using the fundamental traps is used. In other words: fundamental traps are required, derived traps are optional.
Fundamental traps
Emulated JavaScript code | Handler method | Description |
Object.getOwnPropertyDescriptor(proxy, name) |
getOwnPropertyDescriptor: function(name) -> PropertyDescriptor | undefined |
Should return a valid property descriptor object, or undefined to indicate that no property with name exists in the emulated object. |
Object.getPropertyDescriptor(proxy, name) |
getPropertyDescriptor: function(name) -> PropertyDescriptor | undefined |
This function doesn't exist in ECMAScript 5. Like getOwnPropertyDescriptor , but should also search the prototype chain. |
Object.getOwnPropertyNames(proxy) |
getOwnPropertyNames: function() -> Strings Array |
Return an array of all own (non-inherited) property names of the emulated object. |
Object.getPropertyNames(proxy) |
getPropertyNames: function() -> Strings Array |
This function doesn't exist in ECMAScript 5. Like getOwnPropertyNames , but should also return non-overridden inherited properties. |
Object.defineProperty(proxy,name,pd) |
defineProperty: function(name, propertyDescriptor) -> any |
Define a new property whose attributes are determined by the given propertyDescriptor . The return value of this method is ignored. |
delete proxy.name |
delete: function(name) -> boolean |
Delete the named property from the proxy. The boolean return value of this method should indicate whether or not the name property was successfully deleted. |
|
fix: function() -> PropertyDescriptor map (indexed on property names) | undefined |
Should return an object that maps property names to property descriptors. After a call to If |
Derived traps
Default implementation refers to the code that is called for that trap when the trap isn't explicitly defined. In these functions, this
refers to the handler object.
Emulated JavaScript code | Handler method | Default implementation | Description |
name in proxy |
has: function(name) -> boolean |
function(name) { return !!this.getPropertyDescriptor(name); } |
|
Object.prototype.hasOwnProperty.call(proxy, name) |
hasOwn: function(name) -> boolean |
function(name) { return !!this.getOwnPropertyDescriptor(name); } |
|
|
get: function(receiver, name) -> any |
function(receiver, name) { var desc = this.getPropertyDescriptor(name); if (desc === undefined) { return undefined; } if ('value' in desc) { return desc.value; } else { if (desc.get === undefined) { return undefined; } return desc.get.call(receiver); } } |
receiver is either the proxy or an object that inherits from the proxy. |
|
set: function(receiver, name, val) -> boolean |
function(receiver, name, val) { var desc = this.getOwnPropertyDescriptor(name); if (desc) { if ('writable' in desc) { if (desc.writable) { desc.value = val; this.defineProperty(name, desc); return true; } else { return false; } } else { // accessor if (desc.set) { desc.set.call(receiver, val); return true; } else { return false; } } } desc = this.getPropertyDescriptor(name); if (desc) { if ('writable' in desc) { if (desc.writable) { // fall through } else { return false; } } else { // accessor if (desc.set) { desc.set.call(receiver, val); return true; } else { return false; } } } this.defineProperty(name, { value: val, writable: true, enumerable: true, configurable: true}); return true; } |
receiver is either the proxy or an object that inherits from the proxy. |
for(prop in proxy){...} |
enumerate: function() -> String Array |
function() { return this.getPropertyNames().filter( function (name) { return this.getPropertyDescriptor(name).enumerable } ); } |
From the proxy user point of view, properties appear in the for..in loop in the same order as they are in the returned array. |
Object.keys(proxy) |
keys: function() -> String Array |
function() { return this.getOwnPropertyNames().filter( function (name) { return this.getOwnPropertyDescriptor(name).enumerable } ); } |
Invariants
Even though proxies provide a lot of power to users, some operations are not trapped in order to keep the language consistent:
- The triple equal (
===
) operator is not trapped.p1 === p2
if and only ifp1
andp2
refer to the same proxy. Fixing a proxy does not alter its object identity (the object “generated” by the handler during fixing does not have its own object identity; it retains the object identity of the proxy, upholding the illusion that the proxy “becomes” the object). Object.getPrototypeOf(proxy)
returns the prototype with whichproxy
was initialized for an object proxy, and returnsFunction.prototype
for a function proxy.- typeof
typeof anObjectProxy === "object"
typeof aFunctionProxy === "function"
- instanceof
anObjectProxy instanceof C === true
if and only if the prototype with whichanObjectProxy
was initialized equals or inherits fromC.prototype
aFunctionProxy instanceof Function === true
Common mistakes and misunderstanding
When starting using proxies, there are often a few beginners' mistakes and misunderstandings:
- Not implementing all traps. Proxies are, by default, "semanticless" objects. If a trap isn't implemented, then if it's a derived trap, the default implementation is used. However, if a fundamental trap is unimplemented, then a call to this trap will throw a TypeError. To make sure no error is thrown when your object is used, you have to implement at least all fundamental traps.
- Unwanted recursion. Be careful of how you use the
receiver
argument in 'get' and 'set' traps.
var p = Proxy.create({get: function(receiver, name) { print(receiver); // looks for receiver's toString method. receiver turns out to be the proxy, so calling print results in calling the get trap. return "something"; } }); var q = p.azerty; // infinite loop
- The
receiver
argument in 'get' and 'set' traps may not be the proxy itself:
var proxy; var handler = { has: function (name) { return name == 'foo'; }, get: function (rcvr, name) { if (name != 'foo') return undefined; print(proxy !== rcvr); return "bye"; }, }; proxy = Proxy.create(handler); var c = Object.create(proxy); print(c.foo); // prints: 'true' (from "proxy !== rcvr") and 'bye' (from "c.foo"). // In this example, the get trap rcvr argument is the c object while proxy is its prototype
Examples
Very simple example
A trap is called almost each time something happens to your proxy (that is used like an object). Here is an example:
var incompleteHandler = {get:function(myProxy, name){ alert('Property ' + name + ' accessed.'); return 1; } }; var p = Proxy.create(incompleteHandler); var q = p.blabla; // alerts 'Property blabla accessed' and 1 is assigned to q p.azerty = "Trying to set a property"; // throws an error since neither the set trap or the fundamental trap used in the set trap are implemented
No-op forwarding proxy
In this example, we are using a native JavaScript object to which our proxy will forward all operations that are applied to it.
function handlerMaker(obj) { return { // Fundamental traps getOwnPropertyDescriptor: function(name) { var desc = Object.getOwnPropertyDescriptor(obj, name); // a trapping proxy's properties must always be configurable if (desc !== undefined) { desc.configurable = true; } return desc; }, getPropertyDescriptor: function(name) { var desc = Object.getPropertyDescriptor(obj, name); // not in ES5 // a trapping proxy's properties must always be configurable if (desc !== undefined) { desc.configurable = true; } return desc; }, getOwnPropertyNames: function() { return Object.getOwnPropertyNames(obj); }, getPropertyNames: function() { return Object.getPropertyNames(obj); // not in ES5 }, defineProperty: function(name, desc) { Object.defineProperty(obj, name, desc); }, delete: function(name) { return delete obj[name]; }, fix: function() { if (Object.isFrozen(obj)) { return Object.getOwnPropertyNames(obj).map(function(name) { return Object.getOwnPropertyDescriptor(obj, name); }); } // As long as obj is not frozen, the proxy won't allow itself to be fixed return undefined; // will cause a TypeError to be thrown }, // derived traps has: function(name) { return name in obj; }, hasOwn: function(name) { return Object.prototype.hasOwnProperty.call(obj, name); }, get: function(receiver, name) { return obj[name]; }, set: function(receiver, name, val) { obj[name] = val; return true; }, // bad behavior when set fails in non-strict mode enumerate: function() { var result = []; for (name in obj) { result.push(name); }; return result; }, keys: function() { return Object.keys(obj) } }; } // ... var o = Object.create({}); var proxy = Proxy.create(handlerMaker(o)); proxy.blabla = 12; // Thanks to the forwarding, o now has a 'blabla' property with a value of 12 o.blabla++; // just incrementing o.blabla alert(proxy.blabla); // alerts 13: the getting operation is forwarded to o which returns 13.
See also
- "Proxies are awesome" Brendan Eich presentation at JSConf (slides)
- ECMAScript Harmony Proxy proposal page and ECMAScript Harmony proxy semantics page
- Tutorial on proxies
Licensing note
Some content (text, examples) in this page has been copied or adapted from the ECMAScript wiki which content is licensed CC 2.0 BY-NC-SA