Proxy.revocable()

The Proxy.revocable() static method creates a revocable Proxy object.

Syntax

js

Proxy.revocable(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 defining the behavior of proxy 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 a new Proxy(target, handler) call.

revoke

A function with no parameters to revoke (switch off) the proxy.

Description

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

The revoke function does not take any parameters, nor does it rely on the this value. The created proxy object is attached to the revoke function as a private property that the revoke function accesses on itself when called (the existence of the private property is not observable from the outside, but it has implications on how garbage collection happens). The proxy object is not captured within the closure of the revoke function (which will make garbage collection of proxy impossible if revoke is still alive).

After the revoke() function gets called, the proxy becomes unusable: any trap to a handler throws a TypeError. Once a proxy is revoked, it remains revoked, and calling revoke() again has no effect — in fact, the call to revoke() detaches the proxy object from the revoke function, so the revoke 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. The revoke function also detaches target and handler from the proxy, so if target 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 to control 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()

js

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 thrown
proxy.foo = 1; // TypeError again
delete proxy.foo; // still TypeError
typeof proxy; // "object", typeof doesn't trigger any trap

Specifications

Specification
ECMAScript Language Specification
# sec-proxy.revocable

Browser compatibility

BCD tables only load in the browser

See also