Proxy.revocable()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨December 2017⁩.

TheProxy.revocable() static method creates a revocableProxy object.

Syntax

Proxy.revocable(target, handler)

Parameters

target: A target object to wrap withProxy. It can be any sort of object, including a native array, a function, or even another proxy.
handler: An object whose properties are functions defining the behavior ofproxy when an operation is performed on it.

Return value

A plain object with the following two properties:

proxy: A Proxy object exactly the same as one created with anew Proxy(target, handler) call.
revoke: A function with no parameters to revoke (switch off) theproxy.

TheProxy.revocable() factory function is the same as theProxy() constructor, except that in addition to creating a proxy object, it also creates arevoke function that can be called to disable the proxy. The proxy object and therevoke function are wrapped in a plain object.

Therevoke function does not take any parameters, nor does it rely on thethis value. The createdproxy object is attached to therevoke function as aprivate field that therevoke function accesses on itself when called (the existence of the private field is not observable from the outside, but it has implications on how garbage collection happens). Theproxy object isnot captured within theclosure of therevoke function (which will make garbage collection ofproxy impossible ifrevoke is still alive).

After therevoke() function gets called, the proxy becomes unusable: any trap to a handler throws aTypeError. Once a proxy is revoked, it remains revoked, and callingrevoke() again has no effect — in fact, the call torevoke() detaches theproxy object from therevoke function, so therevoke function will not be able to access the proxy again at all. If the proxy is not referenced elsewhere, it will then be eligible for garbage collection. Therevoke function also detachestarget andhandler from theproxy, so iftarget is not referenced elsewhere, it will also be eligible for garbage collection, even when its proxy is still alive, since there's no longer a way to meaningfully interact with the target object.

Letting users interact with an object through a revocable proxy allows you tocontrol the lifetime of the object exposed to the user — you can make the object garbage-collectable even when the user is still holding a reference to its proxy.

Examples

Using Proxy.revocable()

const revocable = Proxy.revocable(  {},  {    get(target, name) {      return `[[${name}]]`;    },  },);const proxy = revocable.proxy;console.log(proxy.foo); // "[[foo]]"revocable.revoke();console.log(proxy.foo); // TypeError is thrownproxy.foo = 1; // TypeError againdelete proxy.foo; // still TypeErrortypeof proxy; // "object", typeof doesn't trigger any trap