JavaScript Proxy and Reflect

Proxies are commonly applied in various libraries and several browser frameworks.

A Proxy object is used for wrapping another object and intercepting operations such as writing and reading properties, dealing with them, or transparently making the object to handle them.

Proxy

The first thing to know is the syntax of proxy, which looks as follows:

let proxy = new Proxy(target, handler)

This syntax includes a target and a handler. The target is the object that is going to be wrapped. It can be functions, and so on. The handler is the configuration of the proxy.

In case there is a trap in the handler, then it runs, and the proxy can handle it. In another way, the operation will be implemented on the target.

As a starting point, let’s consider an example of a proxy without traps:

Javascript proxy without traps

let target = {}; let proxy = new Proxy(target, {}); // empty handler proxy.test = 7; // writing proxy (1) console.log(target.test); // 7, property appeared in the target console.log(proxy.test); // 7, we can read this from a proxy (2) for (let key in proxy) console.log(key); // test, iteration works (3)

Run > Reset

In case there isn’t any trap, the operations are passed to the target. It is necessary to add traps for activating more capabilities.

In JavaScript, there is a so-called “internal method” for most object operations, describing how it works at the lowest level. For example, the [[Get]] method is used for reading a property, [[Set]] - for writing a property. Anyway, such kinds of methods can not be called by name.

Further, we will cover operations with some of the methods and traps. JavaScript imposes invariants: those are conditions that must be carried out by the internal methods and traps.

For example,[[Set]] , [[Delete]] , and others return values. In the case of using [[Delete]], it should return true once the value was deleted, and, otherwise, it will return false.

Other types of variants also exist. For example, when [[GetPrototypeOf]] is inserted to the proxy object, it must return the same value as [[GetPrototypeOf]], attached to the target object of the proxy.

Default Value with “get” Trap

The most frequently used traps are for writing and reading properties. For intercepting reading, the handler should include a get method. It occurs once a property is read, along with the target (the target object), property (the property name), and the receiver (if the target property is a getter, then the object is the receiver).

For using get to perform default values for an object, it is necessary to make a numeric array, which returns 0 for nonexistent values.

As a rule, trying to get a non-existing array item leads to undefined. However, you can wrap a regular array into the proxy that returns 0, like here:

Javascript proxy without traps

let numbers = [11, 22, 33]; numbers = new Proxy(numbers, { get(target, prop) { if (prop in target) { return target[prop]; } else { return 0; } } }); console.log(numbers[1]); // 22 console.log(numbers[12]); // 0, no such item

Run > Reset

Validation with “set” Trap

Imagine that you need to get an array numbers. Adding another value type will cause an error.

The set trap occurs when a property is written. It includes target, property, value, and receiver.

So, the set trap returns true when the setting is done successfully, and false, otherwise.

Javascript proxy with traps

let numbers = []; numbers = new Proxy(numbers, { // (*) set(target, prop, value) { // intercept property record if (typeof value == 'number') { target[prop] = value; return true; } else { return false; } } }); numbers.push(11); // added successfully numbers.push(22); // added successfully console.log("Length is: " + numbers.length); // 2 numbers.push("test"); // TypeError ,'set' on proxy returns false console.log("Error in the line above,this line is never reached ");

Run > Reset

Also consider that the built-in functionality of arrays still works. With push, it is possible to add values.

Value-adding methods such as push and unshift shouldn’t be overridden.

Protected Properties with “deleteProperty” and Other Traps

It is known that properties and methods that are prefixed by an underscore _ are considered internal. It is not possible to access them outside the object.

Let’s see how it is possible technically:

Javascript proxy with traps

let user = { name: "Jack", _userPassword: "secret" }; console.log(user._userPassword); // secret

Run > Reset

So, proxies are used for preventing any access to the properties that begin with _.

The necessary traps are as follows:

• get - for throwing an error while reading a property like that.
• set - for throwing an error while writing.
• deleteProperty - for throwing an error while deleting.
• ownKeys - for excluding properties that begin with _ from for..in and methods such as Object.keys.

The code will look like this:

Javascript proxy with traps

console.log(1 / 0); // Infinity let user = { userName: "Jack", _userPassword: "***" }; user = new Proxy(user, { get(target, prop) { if (prop.startsWith('_')) { throw new Error("Access denied"); } let value = target[prop]; return (typeof value === 'function') ? value.bind(target) : value; // (*) }, set(target, prop, value) { // to intercept property writing if (prop.startsWith('_')) { throw new Error("Access denied"); } else { target[prop] = value; return true; } }, deleteProperty(target, prop) { // to intercept property deletion if (prop.startsWith('_')) { throw new Error("Access denied"); } else { delete target[prop]; return true; } }, ownKeys(target) { // to intercept property list return Object.keys(target).filter(key => !key.startsWith('_')); } }); // "get" doesn't allow to read _userPassword try { console.log(user._userPassword); // Error: Access denied } catch (e) { console.log(e.message); } // "set" doesn't allow to write _userPassword try { user._userPassword = "test"; // Error: Access denied } catch (e) { console.log(e.message); } // "deleteProperty" doesn't allow to delete _userPassword try { delete user._userPassword; // Error: Access denied } catch (e) { console.log(e.message); } // "ownKeys" filters out _userPassword for (let key in user) console.log(key); // userName

Run > Reset

In the line (*), there is an important detail:

get(target, prop) {
  // ...
  let val = target[prop];
  return (typeof val === 'function') ? val.bind(target) : val; // (*)
}

So, a function is necessary to call value.bind(target) because object methods like user.checkPassword() should be able to access _password, like this:

user = {
  // ...
  checkPassword(val) {
    // object method should be able to read _userPassword
    return val === this._userPassword;
  }
}

Wrapping Functions: "apply"

It is possible to wrap a proxy around a function, too.

The oapply(target, thisArg, args) trap can handle calling a proxy as a function. It includes target (the target object), thisArg (the value of this), and args (a list of arguments).

For instance, imagine recalling the delay(fn, ms) decorator. It returns a function, which forwards all the calls to fn after ms milliseconds.

The function-based performance will look like this:

Javascript proxy with call function a timeout

function delay(fn, ms) { // return wrapper that passes fn call after timeout return function () { // (*) setTimeout(() => fn.apply(this, arguments), ms); }; } function sayWelcome(siteName) { console.log(`Welcome to ${siteName}!`); } // after this wrapping, sayWelcome calls will be delayed for 2 seconds sayWelcome = delay(sayWelcome, 2000); sayWelcome("W3Docs"); // Welcome to W3Docs (after 2 seconds)

Run > Reset

It is noticeable that the wrapper function (*) makes the call after a timeout. But the wrapper function isn’t capable of forwarding write and read operations, and so on. And, when the wrapping is implemented, the access to the properties will be lost:

Javascript proxy with call function a timeout

function delay(f, ms) { return function () { setTimeout(() => f.apply(this, arguments), ms); }; } function sayWelcome(siteName) { console.log(`Welcome to ${siteName}!`); } console.log(sayWelcome.length); // 1 (function length is the count of arguments in the declaration) sayWelcome = delay(sayWelcome, 2000); console.log(sayWelcome.length); // 0 (wrapper declaration has zero arguments)

Run > Reset

Luckily, the proxy can forward anything to the target object. So, it is recommended to use proxy rather than the wrapping function. Here is an example of using the proxy:

Javascript proxy forward the target object

function delay(f, ms) { return new Proxy(f, { apply(target, thisArg, args) { setTimeout(() => target.apply(thisArg, args), ms); } }); } function sayWelcome(siteName) { console.log(`Welcome to ${siteName}!`); } sayWelcome = delay(sayWelcome, 2000); console.log(sayWelcome.length); // 1 (*) proxy forwarded "get length" operation to target sayWelcome("W3Docs"); // Welcome to W3Docs (after 2 seconds)

Run > Reset

Reflect

Reflect is the term used for specifying a built-in object, which simplifies the proxy creation.

As it was noted above, the internal methods such as [[Set]],[[Get]] , and others can’t be called directly. Reflect can be used for making it possible.

Let’s see an example of using reflect:

Javascript proxy with reflect a built-in object

let site = {}; Reflect.set(site, 'siteName', 'W3Docs'); console.log(site.siteName); //

Run > Reset

For each internal method, that is trapped by proxy, there is a matching method in reflect. It has the same name and arguments as the proxy trap.

So, reflect is used for forwarding an operation to the original object.

Let’s check out another example:

Javascript proxy trap with reflect object

let site = { name: "W3Docs", }; site = new Proxy(site, { get(target, prop, receiver) { console.log(`GET ${prop}`); return Reflect.get(target, prop, receiver); // (1) }, set(target, prop, val, receiver) { console.log(`SET ${prop}=${val}`); return Reflect.set(target, prop, val, receiver); // (2) } }); let name = site.name; // shows "GET name" site.name = "W3Docs"; // shows "SET name=W3Docs"

Run > Reset

In this example, an object property is read by Reflect.get. Also, Reflect.set writes an object property, returning true if successful, and false, otherwise.

Proxy Limitations

Of course, proxies are a unique and handy way for altering or tweaking the behavior of the existing objects at the lowest level. But, it can’t handle anything and has limitations. Below, we will look through the main proxy limitations.

Built-in objects: internal slots

Most of the built-in objects such as Set, Map, Date, and so on work with internal slots.

Those are similar to properties but reserved for internal purposes. For instance, Map embraces items in the internal slot [[MapData]] . The built-in methods are capable of accessing them directly and not through the [[Get]]/[[Set]] methods. So, it can’t be intercepted by the proxy.

An essential issue here is that after a built-in object gets proxied, the proxy doesn’t include the slots, so an error occurs, like this:

Javascript proxy with built-in objects

let map = new Map(); let proxy = new Proxy(map, {}); console.log(proxy.set('testArg', 1)); // Error

Run > Reset

Let’s see another case. A Map encloses all the data in the [[MapData]] internal slot. Then, the Map.prototype.set method attempts to access the internal this.[[MapData]]. As a result, it will not be found in the proxy.

But there is a way of fixing it:

Javascript proxy with Map method

let map = new Map(); let proxy = new Proxy(map, { get(target, prop, receiver) { let value = Reflect.get(...arguments); return typeof value == 'function' ? value.bind(target) : value; } }); proxy.set('test', 10); console.log(proxy.get('test')); // 10

Run > Reset

Please, take into consideration a notable exception: the built-in Array never uses internal slots.

Private Fields

Something similar takes place with private fields. For instance, the getName() method can access the #name and break after proxying, like this:

Javascript proxy with private fields

class Site { #name = "W3Docs"; getName() { return this.#name; } } let site = new Site(); site = new Proxy(site, {}); console.log(site.getName()); // Error

Run > Reset

That happens because private fields are performed by applying internal slots. While accessing them, JavaScript doesn’t use [[Get]]/[[Set]] .

Calling getName() the proxied user is the value of this . It doesn’t have the slot with private fields.

Let’s have a look at the solution, which will make it work:

Javascript proxy with private fields

class Site { #name = "W3Docs"; getName() { return this.#name; } } let site = new Site(); site = new Proxy(site, { get(target, prop, receiver) { let value = Reflect.get(...arguments); return typeof value == 'function' ? value.bind(target) : value; } }); console.log(site.getName()); // W3Docs

Run > Reset

Proxy != target

The original object and the proxy are considered different objects.

Having the original object as a key, proxying it, then it won’t be found, like here:

Javascript proxy are considered different objects

let allBooks = new Set(); class Book { constructor(name) { this.name = name; allBooks.add(this); } } let book = new Book("Javascript"); console.log(allBooks.has(book)); // true book = new Proxy(book, {}); console.log(allBooks.has(book)); // false

Run > Reset

It is noticeable that the user can’t be found in the allUsers after proxying. That’s because it’s a different object.

Please, also note that proxies don’t intercept various operators like new, delete and more. All the operations and built-in classes comparing objects for equality, differentiate between the proxy and the object.

Revocable Proxies

A proxy that can be disabled is called a revocable proxy.

Imagine having a resource and want to close access to it at any time. It is necessary to wrap it to a revocable proxy without using traps. A proxy like that will forward operations to object. It can be disabled at any moment.

The syntax is the following:

let {
  proxy,
  revoke
} = Proxy.revocable(target, handler)

Now, let’s see an example of the call returning an object with the proxy and revoke function for disabling it:

Javascript revocable proxy

let object = { data: "Valued data" }; let { proxy, revoke } = Proxy.revocable(object, {}); // pass proxy somewhere instead of an object console.log(proxy.data); // Valued data // later revoke(); // the proxy doesn't work (revoked) console.log(proxy.data); // Error

Run > Reset

Calling revoke() deletes all the internal references to the target object. So, there is not connection between them.

Also, revoke can be stored in WeakMap. That makes it easier to detect it using a proxy object, like this:

Javascript proxy with traps

let revokes = new WeakMap(); let object = { data: "Valued data" }; let { proxy, revoke } = Proxy.revocable(object, {}); revokes.set(proxy, revoke); // later revoke = revokes.get(proxy); revoke(); console.log(proxy.data); // Error (revoked)

Run > Reset

The primary benefit here is that it’s not necessary to carry revoke anymore. To sum up, we can state that a Proxy is a wrapper, surrounding an object, which forwards operations on it to the object. Some of them can optionally by trapped. Any type of object can be wrapped, including functions and classes.

Proxy doesn’t include own methods and properties. It will trap the operation when there is a trap. Otherwise, it will be forwarded to target the object.

To complement proxy, an API, called reflect is created. For each proxy trap, you can find a corresponding reflect, using the same arguments.