Starting with ECMAScript 6, JavaScript gains support for the {{jsxref("Proxy")}} and {{jsxref("Reflect")}} objects allowing you to intercept and define custom behavior for fundamental language operations (e.g. property lookup, assignment, enumeration, function invocation, etc). With the help of these two objects you are able to program at the meta level of JavaScript.
Proxies
Introduced in ECMAScript 6, {{jsxref("Proxy")}} objects allow you to intercept certain operations and to implement custom behaviors. For example getting a property on an object:
var handler = { get: function(target, name){ return name in target ? target[name] : 42; }}; var p = new Proxy({}, handler); p.a = 1; console.log(p.a, p.b); // 1, 42
The Proxy
object defines a target (an object here) and a handler object in which a get
trap is implemented. Here, an object that is proxied will not return undefined
when getting undefined properties, but will instead return the number 42.
Additional examples are available on the {{jsxref("Proxy")}} reference page.
Terminology
The following terms are used when talking about the functionality of proxies.
- {{jsxref("Global_Objects/Proxy/handler","handler","","true")}}
- Placeholder object which contains traps.
- traps
- The methods that provide property access. This is analogous to the concept of traps in operating systems.
- target
- Object which the proxy virtualizes. It is often used as storage backend for the proxy. Invariants (semantics that remain unchanged) regarding object non-extensibility or non-configurable properties are verified against the target.
- invariants
- Semantics that remain unchanged when implementing custom operations are called invariants. If you violate the invariants of a handler, a {{jsxref("TypeError")}} will be thrown.
Handlers and traps
The following table summarizes the available traps available to Proxy
objects. See the reference pages for detailed explanations and examples.
Handler / trap | Interceptions | Invariants |
---|---|---|
{{jsxref("Global_Objects/Proxy/handler/getPrototypeOf", "handler.getPrototypeOf()")}} | {{jsxref("Object.getPrototypeOf()")}} {{jsxref("Reflect.getPrototypeOf()")}} {{jsxref("Object/proto", "__proto__")}} {{jsxref("Object.prototype.isPrototypeOf()")}} {{jsxref("Operators/instanceof", "instanceof")}} |
|
{{jsxref("Global_Objects/Proxy/handler/setPrototypeOf", "handler.setPrototypeOf()")}} | {{jsxref("Object.setPrototypeOf()")}} {{jsxref("Reflect.setPrototypeOf()")}} |
If target is not extensible, the prototype parameter must be the same value as Object.getPrototypeOf(target) . |
{{jsxref("Global_Objects/Proxy/handler/isExtensible", "handler.isExtensible()")}} | {{jsxref("Object.isExtensible()")}} {{jsxref("Reflect.isExtensible()")}} |
Object.isExtensible(proxy) must return the same value as Object.isExtensible(target) . |
{{jsxref("Global_Objects/Proxy/handler/preventExtensions", "handler.preventExtensions()")}} | {{jsxref("Object.preventExtensions()")}} {{jsxref("Reflect.preventExtensions()")}} |
Object.preventExtensions(proxy) only returns true if Object.isExtensible(proxy) is false . |
{{jsxref("Global_Objects/Proxy/handler/getOwnPropertyDescriptor", "handler.getOwnPropertyDescriptor()")}} | {{jsxref("Object.getOwnPropertyDescriptor()")}} {{jsxref("Reflect.getOwnPropertyDescriptor()")}} |
|
{{jsxref("Global_Objects/Proxy/handler/defineProperty", "handler.defineProperty()")}} | {{jsxref("Object.defineProperty()")}} {{jsxref("Reflect.defineProperty()")}} |
|
{{jsxref("Global_Objects/Proxy/handler/has", "handler.has()")}} | Property query: foo in proxy Inherited property query: foo in Object.create(proxy) {{jsxref("Reflect.has()")}} |
|
{{jsxref("Global_Objects/Proxy/handler/get", "handler.get()")}} | Property access: proxy[foo] and proxy.bar Inherited property access: Object.create(proxy)[foo] {{jsxref("Reflect.get()")}} |
|
{{jsxref("Global_Objects/Proxy/handler/set", "handler.set()")}} | Property assignment: proxy[foo] = bar and proxy.foo = bar Inherited property assignment: Object.create(proxy)[foo] = bar {{jsxref("Reflect.set()")}} |
|
{{jsxref("Global_Objects/Proxy/handler/deleteProperty", "handler.deleteProperty()")}} | Property deletion: delete proxy[foo] and delete proxy.foo {{jsxref("Reflect.deleteProperty()")}} |
A property cannot be deleted, if it exists as a non-configurable own property of the target object. |
{{jsxref("Global_Objects/Proxy/handler/enumerate", "handler.enumerate()")}} | Property enumeration / for...in: for (var name in proxy) {...} {{jsxref("Reflect.enumerate()")}} |
The enumerate method must return an object. |
{{jsxref("Global_Objects/Proxy/handler/ownKeys", "handler.ownKeys()")}} | {{jsxref("Object.getOwnPropertyNames()")}} {{jsxref("Object.getOwnPropertySymbols()")}} {{jsxref("Object.keys()")}} {{jsxref("Reflect.ownKeys()")}} |
|
{{jsxref("Global_Objects/Proxy/handler/apply", "handler.apply()")}} | proxy(..args) {{jsxref("Function.prototype.apply()")}} and {{jsxref("Function.prototype.call()")}} {{jsxref("Reflect.apply()")}} |
There are no invariants for the handler.apply method. |
{{jsxref("Global_Objects/Proxy/handler/construct", "handler.construct()")}} | new proxy(...args) {{jsxref("Reflect.construct()")}} |
The result must be an Object . |
Revocable Proxy
The {{jsxref("Proxy.revocable()")}} method is used to create a revocable Proxy
object. This means that the proxy can be revoked via the function revoke
and switches the proxy off. Afterwards, any operation leads on the proxy leads to a {{jsxref("TypeError")}}.
var revocable = Proxy.revocable({}, { get: function(target, name) { return "[[" + name + "]]"; } }); var proxy = revocable.proxy; console.log(proxy.foo); // "[[foo]]" revocable.revoke(); console.log(proxy.foo); // TypeError is thrown proxy.foo = 1 // TypeError again delete proxy.foo; // still TypeError typeof proxy // "object", typeof doesn't trigger any trap
Reflection
{{jsxref("Reflect")}} is a built-in object that provides methods for interceptable JavaScript operations. The methods are the same as those of the {{jsxref("Global_Objects/Proxy/handler","proxy handlers","","true")}}. Reflect
is not a function object.
Reflect
helps with forwarding default operations from the handler to the target.
With {{jsxref("Reflect.has()")}} for example, you get the in
operator as a function:
Reflect.has(Object, "assign"); // true
A better apply
function
In ES5, you typically use the {{jsxref("Function.prototype.apply()")}} method to call a function with a given this
value and arguments
provided as an array (or an array-like object).
Function.prototype.apply.call(Math.floor, undefined, [1.75]);
With {{jsxref("Reflect.apply")}} this becomes less verbose and easier to understand:
Reflect.apply(Math.floor, undefined, [1.75]); // 1; Reflect.apply(String.fromCharCode, undefined, [104, 101, 108, 108, 111]); // "hello" Reflect.apply(RegExp.prototype.exec, /ab/, ["confabulation"]).index; // 4 Reflect.apply("".charAt, "ponies", [3]); // "i"
Checking if property definition has been successful
With {{jsxref("Object.defineProperty")}}, which returns an object if successful, or throws a {{jsxref("TypeError")}} otherwise, you would use a {{jsxref("Statements/try...catch","try...catch")}} block to catch any error that occurred while defining a property. Because {{jsxref("Reflect.defineProperty")}} returns a Boolean success status, you can just use an {{jsxref("Statements/if...else","if...else")}} block here:
if (Reflect.defineProperty(target, property, attributes)) { // success } else { // failure }
{{Previous("Web/JavaScript/Guide/Iterators_and_Generators")}}