Proxy.revocable(target, handler) creates a Proxy that can be switched off. It returns an object with two parts: proxy, which works like a normal Proxy, and revoke, a function that turns the Proxy off for good.
After you call revoke(), every use of the Proxy throws a TypeError. This is useful when you want to lend an object to some code for a short time and then take the access back. The original object is not changed or harmed.
Remember
const { proxy, revoke } = Proxy.revocable(target, handler);
proxy → works like new Proxy(target, handler)
revoke() → switches the proxy off, for good
After revoke(): any use of the proxy throws TypeError
The target object itself is not affected
Calling revoke() again does nothing
Syntax
Use destructuring to take the two parts out of the result.
JavaScript
const user = { name: "Ann" };
const { proxy, revoke } = Proxy.revocable(user, {});
console.log(proxy.name); // Ann
revoke();
// proxy.name would now throw a TypeError
Call
What it does
Proxy.revocable(target, handler)
Create a Proxy and a revoke function. Returns { proxy, revoke }.
revoke()
Switch the Proxy off. It takes no arguments and returns undefined.
new Proxy(target, handler)
A normal Proxy. It can never be switched off.
Proxy.revocable(target, {})
An empty handler: the Proxy just passes everything through to the target.
// ECMAScript 2015 (ES6)
Proxy.revocable(target, handler)
// target : an object (or a function)
// handler : an object that holds the traps (it can be empty)
// returns : { proxy, revoke }
// throws : TypeError if target or handler is not an object
Parameters
Parameter
Description
target
Required. The object (or function) that the Proxy wraps. A number, a string or null throws a TypeError.
handler
Required. An object that holds the traps, such as get or set. Use {} if you do not need any traps.
Return Value
Return Value
Description
Object
A plain object with two properties: proxy (the Proxy) and revoke (a function with no arguments).
TypeError (thrown)
target or handler is not an object.
JavaScript Examples
Example 1 — Create a Proxy and Switch It Off
Use the proxy, call revoke(), and see that the proxy stops working while the original object is still fine. The catch block prints the error type only.
A watching handler. The get trap saves a note for each read and then forwards the read with Reflect.get(). The destructuring { proxy: view, revoke } renames the proxy to view.
One read, one note. While the proxy is alive, view.token returns the value and the log gets one entry.
No more traps. After revoke(), the read throws a TypeError before your trap can run, so the log still has only one entry. This is how you can lend an object for a short time.
Compatibility
Browser & Runtime Support
Proxy.revocable() is part of ES2015 (ES6), together with the Proxy object and the Reflect object. Every current browser and Node.js has it.
✓ ES2015 · Widely supported
Proxy.revocable()
Supported in Chrome 49+, Edge 12+, Firefox 49+, Safari 10+, Opera 36+ and Node.js 6+. Internet Explorer never got it.
ES2015Standard since
Google Chrome49+ · Desktop & Mobile
Full support
Microsoft Edge12+ · Chromium and legacy
Full support
Mozilla Firefox49+ · Desktop & Mobile
Full support
Apple Safari10+ · macOS & iOS
Full support
Opera36+ · Chromium based
Full support
Samsung InternetRecent versions · Android
Supported
Android WebView49+ · Chromium based
Supported
Node.js6+ · Server runtime
Supported
DenoSupported · JavaScript runtime
Supported
BunSupported · JavaScript runtime
Supported
Internet ExplorerNo native support
Not supported
Proxy.revocable()Excellent
Bottom line: Safe to use in every current browser and in Node.js. A Proxy cannot be faked in old browsers, so do not use it where Internet Explorer must work.
Frequently Asked Questions
It creates a Proxy together with a revoke function. You use the proxy like any other Proxy, and when you call revoke(), the proxy is switched off and every use of it throws a TypeError.
Both make a Proxy that wraps a target with a handler. new Proxy() returns only the proxy, which stays alive. Proxy.revocable() returns an object with the proxy and a revoke function, so you can end its life.
No. A revoked proxy stays dead for good. If you need access again, call Proxy.revocable() to create a new proxy for the same target.
When you give an object to code that you do not fully control, for a limited time, for example a plugin or a temporary session. After you revoke it, the code can no longer reach your object through the proxy.
No. It only switches off the proxy. The target keeps all its properties and values, and any code that holds the target directly can still use it.