Proxy
The Proxy
object enables you to create a proxy for another object, which can intercept and redefine fundamental operations for that object.
Description
The Proxy
object allows you to create an object that can be used in place of the original object, but which may redefine fundamental Object
operations like getting, setting, and defining properties. Proxy objects are commonly used to log property accesses, validate, format, or sanitize inputs, and so on.
You create a Proxy
with two parameters:
target
: the original object which you want to proxyhandler
: an object that defines which operations will be intercepted and how to redefine intercepted operations.
For example, this code defines a simple target with just two properties, and an even simpler handler with no properties:
const target = {
message1: "hello",
message2: "everyone"
};
const handler1 = {};
const proxy1 = new Proxy(target, handler1);
Because the handler is empty, this proxy behaves just like the original target:
console.log(proxy1.message1); // hello
console.log(proxy1.message2); // everyone
To customize the proxy, we define functions on the handler object:
const target = {
message1: "hello",
message2: "everyone"
};
const handler2 = {
get(target, prop, receiver) {
return "world";
}
};
const proxy2 = new Proxy(target, handler2);
Here we've provided an implementation of the get()
handler, which intercepts attempts to access properties in the target.
Handler functions are sometimes called traps, presumably because they trap calls to the target object. The very simple trap in handler2
above redefines all property accessors:
console.log(proxy2.message1); // world
console.log(proxy2.message2); // world
With the help of the Reflect
class we can give some accessors the original behavior and redefine others:
const target = {
message1: "hello",
message2: "everyone"
};
const handler3 = {
get(target, prop, receiver) {
if (prop === "message2") {
return "world";
}
return Reflect.get(...arguments);
},
};
const proxy3 = new Proxy(target, handler3);
console.log(proxy3.message1); // hello
console.log(proxy3.message2); // world
Constructor
Proxy()
-
Creates a new
Proxy
object.
Static methods
Proxy.revocable()
-
Creates a revocable
Proxy
object.
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.
const handler = {
get(obj, prop) {
return prop in obj ?
obj[prop] :
37;
}
};
const 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.
const target = {};
const 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.
Validation
With a Proxy
, you can easily validate the passed value for an object. This example uses the set()
handler.
let validator = {
set(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;
}
};
const 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) {
base.prototype = Object.create(sup.prototype);
base.prototype.constructor = new Proxy(base, {
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);
}
});
return base.prototype.constructor;
}
var Person = function(name) {
this.name = name;
};
var Boy = extend(Person, function(name, age) {
this.age = age;
});
Boy.prototype.gender = 'M';
var Peter = new Boy('Peter', 13);
console.log(Peter.gender); // "M"
console.log(Peter.name); // "Peter"
console.log(Peter.age); // 13
Manipulating DOM nodes
In this example we use Proxy
to toggle an attribute of two different elements: so when we set the attribute on one element, the attribute is unset on the other one.
We create a view
object which is a proxy for an object with a selected
property. The proxy handler defines the set()
handler.
When we assign an HTML element to view.selected
, the element's 'aria-selected'
attribute is set to true
. If we then assign a different element to view.selected
, this element's 'aria-selected'
attribute is set to true
and the previous element's 'aria-selected'
attribute is automatically set to false
.
const view = new Proxy({
selected: null
},
{
set(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;
}
});
const item1 = document.getElementById('item-1');
const item2 = document.getElementById('item-2');
// select item1:
view.selected = item1;
console.log(`item1: ${item1.getAttribute('aria-selected')}`);
// item1: true
// selecting item2 de-selects item1:
view.selected = item2;
console.log(`item1: ${item1.getAttribute('aria-selected')}`);
// item1: false
console.log(`item2: ${item2.getAttribute('aria-selected')}`);
// item2: 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(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(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(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 a simple cookie framework.
/*
var docCookies = ... get the "docCookies" object here:
https://reference.codeproject.com/dom/document/cookie/simple_document.cookie_framework
*/
var docCookies = new Proxy(docCookies, {
get (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);
},
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 |
---|
ECMAScript Language Specification # sec-proxy-objects |
Browser compatibility
BCD tables only load in the browser