Vullnetarët tanë s’e kanë përkthyer ende në Shqip këtë artikull. Merrni pjesë dhe ndihmoni të mbarohet kjo punë!
Mund ta lexoni artikullin edhe në English (US).
The Proxy object is used to define custom behavior for fundamental operations (e.g. property lookup, assignment, enumeration, function invocation, etc).
Terminology
- handler
- 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.
Syntax
var p = new Proxy(target, handler);
Parameters
target
- A target object to wrap with
Proxy
. It can be any sort of object, including a native array, a function or even another proxy. handler
- An object whose properties are functions which define the behavior of the proxy when an operation is performed on it.
Methods
Proxy.revocable()
- Creates a revocable
Proxy
object.
Methods of the handler object
The handler object is a placeholder object which contains traps for Proxy
.
All traps are optional. If a trap has not been defined, the default behavior is to forward the operation to the target.
handler.getPrototypeOf()
- A trap for
Object.getPrototypeOf
. handler.setPrototypeOf()
- A trap for
Object.setPrototypeOf
. handler.isExtensible()
- A trap for
Object.isExtensible
. handler.preventExtensions()
- A trap for
Object.preventExtensions
. handler.getOwnPropertyDescriptor()
- A trap for
Object.getOwnPropertyDescriptor
. handler.defineProperty()
- A trap for
Object.defineProperty
. handler.has()
- A trap for the
in
operator. handler.get()
- A trap for getting property values.
handler.set()
- A trap for setting property values.
handler.deleteProperty()
- A trap for the
delete
operator. handler.ownKeys()
- A trap for
Object.getOwnPropertyNames
andObject.getOwnPropertySymbols
. handler.apply()
- A trap for a function call.
handler.construct()
- A trap for the
new
operator.
Some non-standard traps are obsolete and have been removed.
Examples
Basic example
In this simple example the number 37
gets returned as the default value when the property name is not in the object. It is using the get
handler.
var handler = { get: function(obj, prop) { return prop in obj ? obj[prop] : 37; } }; var p = new Proxy({}, handler); p.a = 1; p.b = undefined; console.log(p.a, p.b); // 1, undefined console.log('c' in p, p.c); // false, 37
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.
var target = {}; var p = new Proxy(target, {}); p.a = 37; // operation forwarded to the target console.log(target.a); // 37. The operation has been properly forwarded
Note that while this "no-op" works for JavaScript objects it does not work for native browser objects like DOM Elements. See this for one solution.
Validation
With a Proxy
, you can easily validate the passed value for an object. This example uses the set
handler.
let validator = { set: function(obj, prop, value) { if (prop === 'age') { if (!Number.isInteger(value)) { throw new TypeError('The age is not an integer'); } if (value > 200) { throw new RangeError('The age seems invalid'); } } // The default behavior to store the value obj[prop] = value; // Indicate success return true; } }; let person = new Proxy({}, validator); person.age = 100; console.log(person.age); // 100 person.age = 'young'; // Throws an exception person.age = 300; // Throws an exception
Extending constructor
A function proxy could easily extend a constructor with a new constructor. This example uses the construct
and apply
handlers.
function extend(sup, base) { var descriptor = Object.getOwnPropertyDescriptor( base.prototype, 'constructor' ); base.prototype = Object.create(sup.prototype); var handler = { construct: function(target, args) { var obj = Object.create(base.prototype); this.apply(target, obj, args); return obj; }, apply: function(target, that, args) { sup.apply(that, args); base.apply(that, args); } }; var proxy = new Proxy(base, handler); descriptor.value = proxy; Object.defineProperty(base.prototype, 'constructor', descriptor); return proxy; } var Person = function(name) { this.name = name; }; var Boy = extend(Person, function(name, age) { this.age = age; }); Boy.prototype.sex = 'M'; var Peter = new Boy('Peter', 13); console.log(Peter.sex); // "M" console.log(Peter.name); // "Peter" console.log(Peter.age); // 13
Manipulating DOM nodes
Sometimes you want to toggle the attribute or class name of two different elements. Here's how using the set
handler.
let view = new Proxy({ selected: null }, { set: function(obj, prop, newval) { let oldval = obj[prop]; if (prop === 'selected') { if (oldval) { oldval.setAttribute('aria-selected', 'false'); } if (newval) { newval.setAttribute('aria-selected', 'true'); } } // The default behavior to store the value obj[prop] = newval; // Indicate success return true; } }); let i1 = view.selected = document.getElementById('item-1'); console.log(i1.getAttribute('aria-selected')); // 'true' let i2 = view.selected = document.getElementById('item-2'); console.log(i1.getAttribute('aria-selected')); // 'false' console.log(i2.getAttribute('aria-selected')); // 'true'
Value correction and an extra property
The products
proxy object evaluates the passed value and converts it to an array if needed. The object also supports an extra property called latestBrowser
both as a getter and a setter.
let products = new Proxy({ browsers: ['Internet Explorer', 'Netscape'] }, { get: function(obj, prop) { // An extra property if (prop === 'latestBrowser') { return obj.browsers[obj.browsers.length - 1]; } // The default behavior to return the value return obj[prop]; }, set: function(obj, prop, value) { // An extra property if (prop === 'latestBrowser') { obj.browsers.push(value); return true; } // Convert the value if it is not an array if (typeof value === 'string') { value = [value]; } // The default behavior to store the value obj[prop] = value; // Indicate success return true; } }); console.log(products.browsers); // ['Internet Explorer', 'Netscape'] products.browsers = 'Firefox'; // pass a string (by mistake) console.log(products.browsers); // ['Firefox'] <- no problem, the value is an array products.latestBrowser = 'Chrome'; console.log(products.browsers); // ['Firefox', 'Chrome'] console.log(products.latestBrowser); // 'Chrome'
Finding an array item object by its property
This proxy extends an array with some utility features. As you see, you can flexibly "define" properties without using Object.defineProperties
. This example can be adapted to find a table row by its cell. In that case, the target will be table.rows
.
let products = new Proxy([ { name: 'Firefox', type: 'browser' }, { name: 'SeaMonkey', type: 'browser' }, { name: 'Thunderbird', type: 'mailer' } ], { get: function(obj, prop) { // The default behavior to return the value; prop is usually an integer if (prop in obj) { return obj[prop]; } // Get the number of products; an alias of products.length if (prop === 'number') { return obj.length; } let result, types = {}; for (let product of obj) { if (product.name === prop) { result = product; } if (types[product.type]) { types[product.type].push(product); } else { types[product.type] = [product]; } } // Get a product by name if (result) { return result; } // Get products by type if (prop in types) { return types[prop]; } // Get product types if (prop === 'types') { return Object.keys(types); } return undefined; } }); console.log(products[0]); // { name: 'Firefox', type: 'browser' } console.log(products['Firefox']); // { name: 'Firefox', type: 'browser' } console.log(products['Chrome']); // undefined console.log(products.browser); // [{ name: 'Firefox', type: 'browser' }, { name: 'SeaMonkey', type: 'browser' }] console.log(products.types); // ['browser', 'mailer'] console.log(products.number); // 3
A complete traps
list example
Now in order to create a complete sample traps
list, for didactic purposes, we will try to proxify a non native object that is particularly suited to this type of operation: the docCookies
global object created by the "little framework" published on the document.cookie
page.
/* var docCookies = ... get the "docCookies" object here: https://developer.mozilla.org/en-US/docs/DOM/document.cookie#A_little_framework.3A_a_complete_cookies_reader.2Fwriter_with_full_unicode_support */ var docCookies = new Proxy(docCookies, { get: function (oTarget, sKey) { return oTarget[sKey] || oTarget.getItem(sKey) || undefined; }, set: function (oTarget, sKey, vValue) { if (sKey in oTarget) { return false; } return oTarget.setItem(sKey, vValue); }, deleteProperty: function (oTarget, sKey) { if (sKey in oTarget) { return false; } return oTarget.removeItem(sKey); }, enumerate: function (oTarget, sKey) { return oTarget.keys(); }, ownKeys: function (oTarget, sKey) { return oTarget.keys(); }, has: function (oTarget, sKey) { return sKey in oTarget || oTarget.hasItem(sKey); }, defineProperty: function (oTarget, sKey, oDesc) { if (oDesc && 'value' in oDesc) { oTarget.setItem(sKey, oDesc.value); } return oTarget; }, getOwnPropertyDescriptor: function (oTarget, sKey) { var vValue = oTarget.getItem(sKey); return vValue ? { value: vValue, writable: true, enumerable: true, configurable: false } : undefined; }, }); /* Cookies test */ console.log(docCookies.my_cookie1 = 'First value'); console.log(docCookies.getItem('my_cookie1')); docCookies.setItem('my_cookie1', 'Changed value'); console.log(docCookies.my_cookie1);
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Proxy' in that specification. |
Standard | Initial definition. |
ECMAScript 2016 (ECMA-262) The definition of 'Proxy' in that specification. |
Standard | |
ECMAScript 2017 (ECMA-262) The definition of 'Proxy' in that specification. |
Standard | |
ECMAScript Latest Draft (ECMA-262) The definition of 'Proxy' in that specification. |
Draft |
Browser compatibility
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Basic support | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
revocable | Chrome Full support 63 | Edge Full support Yes | Firefox Full support 34 | IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support 63 | Chrome Android Full support 63 | Edge Mobile Full support Yes | Firefox Android Full support 34 | Opera Android Full support Yes | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs Full support 6.0.0 |
handler.apply | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.construct | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.defineProperty | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.deleteProperty | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.enumerate | Chrome No support No | Edge No support No | Firefox No support 37 — 47 | IE No support No | Opera No support No | Safari No support No | WebView Android No support No | Chrome Android No support No | Edge Mobile No support No | Firefox Android No support 37 — 47 | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs No support No |
handler.get | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.getOwnPropertyDescriptor | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.getPrototypeOf | Chrome No support No | Edge No support No | Firefox Full support 49 | IE No support No | Opera No support No | Safari No support No | WebView Android No support No | Chrome Android No support No | Edge Mobile No support No | Firefox Android Full support 49 | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs Full support 6.0.0 |
handler.has | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.isExtensible | Chrome ? | Edge ? | Firefox Full support 31 | IE No support No | Opera ? | Safari ? | WebView Android ? | Chrome Android ? | Edge Mobile ? | Firefox Android Full support 31 | Opera Android ? | Safari iOS ? | Samsung Internet Android ? | nodejs Full support 6.0.0 |
handler.ownKeys | Chrome Full support 49 | Edge Full support 12 | Firefox
Full support
18
| IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android
Full support
18
| Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.preventExtensions | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 22 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 22 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.set | Chrome Full support 49 | Edge Full support 12 | Firefox Full support 18 | IE No support No | Opera Full support 36 | Safari Full support 10 | WebView Android Full support 49 | Chrome Android Full support 49 | Edge Mobile Full support Yes | Firefox Android Full support 18 | Opera Android Full support 36 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 | nodejs Full support 6.0.0 |
handler.setPrototypeOf | Chrome ? | Edge ? | Firefox Full support 49 | IE No support No | Opera ? | Safari ? | WebView Android ? | Chrome Android ? | Edge Mobile ? | Firefox Android Full support 49 | Opera Android ? | Safari iOS ? | Samsung Internet Android ? | nodejs Full support 6.0.0 |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- Non-standard. Expect poor cross-browser support.
- Non-standard. Expect poor cross-browser support.
- Deprecated. Not for use in new websites.
- Deprecated. Not for use in new websites.
- See implementation notes.
- See implementation notes.
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
- SpiderMonkey specific Old Proxy API
Object.watch()
is a non-standard feature but has been supported in Gecko for a long time.
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.