JavaScript using declarations: automatic cleanup without finally

JavaScript's using declaration runs a cleanup method automatically when a block ends, whether it ends normally, with return, or with an exception. You give an object a [Symbol.dispose]() method, declare it with using instead of const, and the language calls that method for you. It replaces many try...finally blocks, and it works today in Chrome, Edge and Firefox, but not yet in a released version of Safari.

This tutorial shows how the feature behaves, how to write disposable objects for everyday browser code (event listeners, timers, observers and abortable work), when to reach for DisposableStack, and how to adopt it safely while Safari catches up. Every example was run on Node.js 24, which ships the same V8 implementation as Chrome.

Why cleanup code goes wrong

Front-end code acquires plenty of things that must be released: event listeners, intervals, MutationObserver and ResizeObserver instances, AbortControllers, object URLs, locks and stream readers. The traditional pattern is try...finally:

const id = setInterval(poll, 5000);
try {
  await runWizard();
} finally {
  clearInterval(id);
}

That works for one resource. With three, you nest three try blocks, or you write one finally that has to know which resources were actually acquired before the error. Cleanup also ends up far away from acquisition, so it is easy to forget when someone edits the code later. using keeps acquisition and cleanup on the same line.

The basics: Symbol.dispose and using

An object is disposable when it has a method under the well-known symbol Symbol.dispose. Here is a small wrapper that removes an event listener when it goes out of scope:

class TempListener {
  constructor(target, type, handler) {
    this.target = target;
    this.type = type;
    this.handler = handler;
    target.addEventListener(type, handler);
  }
  [Symbol.dispose]() {
    this.target.removeEventListener(this.type, this.handler);
  }
}

const target = new EventTarget();
{
  using listener = new TempListener(target, 'ping', () => console.log('ping received'));
  target.dispatchEvent(new Event('ping')); // "ping received"
} // listener removed here

target.dispatchEvent(new Event('ping')); // nothing happens

A using variable behaves like const: it must be initialised, cannot be reassigned and is block-scoped. The rules MDN documents are worth knowing before you start:

• Reverse order. With several declarations in one scope, disposers run in the reverse order of declaration, like unwinding a stack.
• Always runs. Disposal happens on every exit path, exactly like a finally block.
• Null is allowed. The value may be null or undefined, which makes optional resources easy. Any other value without a callable [Symbol.dispose] throws a TypeError at the declaration.
• No destructuring. using { a, b } = obj is a syntax error; declare the whole object.
• Where it is allowed. Inside blocks, function bodies, class static blocks, at the top level of a module and in for, for...of and for await...of initialisers. It is not allowed at the top level of a classic script, at the top level of a switch statement, or in a for...in loop.

const res = (name) => ({ [Symbol.dispose]() { console.log(`dispose ${name}`); } });
{
  using a = res('a');
  using b = res('b');
  console.log('body');
}
// body
// dispose b
// dispose a

Recipes for browser code

A timer that cannot leak

function timeout(ms, callback) {
  const id = setTimeout(callback, ms);
  return { [Symbol.dispose]() { clearTimeout(id); } };
}

function showToastWhileSaving(save) {
  using slowHint = timeout(800, () => showToast('Still saving...'));
  return save(); // fast saves never show the toast
}

If save() throws synchronously, the timer is still cleared. Note that for an async save() you need to await inside the block; otherwise the block ends as soon as the promise is returned.

Observers that disconnect themselves

function observe(element, callback) {
  const observer = new ResizeObserver(callback);
  observer.observe(element);
  return { [Symbol.dispose]: () => observer.disconnect() };
}

Loops where each item owns a resource

for (using item of openItems()) {
  process(item);
} // each item is disposed at the end of its own iteration

await using for asynchronous cleanup

Some cleanup is asynchronous: flushing a write queue, closing a connection, releasing a lock held by a server. For those, implement [Symbol.asyncDispose]() and declare the variable with await using inside an async function or a module:

async function openSession() {
  const session = await api.startSession();
  return {
    session,
    async [Symbol.asyncDispose]() {
      await api.endSession(session.id);
    },
  };
}

async function exportReport() {
  await using s = await openSession();
  return await s.session.download('report.csv');
} // endSession() is awaited before exportReport() settles

Two details from MDN catch people out. First, await using falls back to [Symbol.dispose] when there is no async disposer, but a promise returned by that sync method is not awaited. Second, a scope with an await using declaration always awaits at least once on exit, even when the value is null, so the timing of the function does not change depending on whether the resource existed.

DisposableStack: many resources, one owner

using covers resources you declare one by one. When you acquire a dynamic number of them, or need to hand ownership to someone else, use DisposableStack (or AsyncDisposableStack):

The classic case is a setup function: if step three fails, steps one and two must be undone, but if everything succeeds the caller becomes responsible for cleanup.

function mountWidget(element) {
  using stack = new DisposableStack();

  const controller = stack.adopt(new AbortController(), (c) => c.abort());
  element.addEventListener('click', onClick, { signal: controller.signal });
  window.addEventListener('resize', onResize, { signal: controller.signal });

  const url = URL.createObjectURL(new Blob(['...']));
  stack.defer(() => URL.revokeObjectURL(url));

  renderInto(element, url); // if this throws, everything above is undone

  return stack.move(); // success: hand ownership to the caller
}

const widget = mountWidget(document.querySelector('#chart'));
// later, for example when the user navigates away:
widget.dispose();

Because move() leaves the original stack marked as disposed, the using stack declaration does nothing on the success path. MDN also recommends wrapping the acquisition expression directly in use() or adopt(), as above, so no code can run between acquiring a resource and registering it.

When cleanup itself fails: SuppressedError

If the block throws and a disposer also throws, you would lose one of the two errors with a hand-written finally. using keeps both in a SuppressedError: the earlier error goes in suppressed, the later one in error.

try {
  using r = { [Symbol.dispose]() { throw new Error('cleanup failed'); } };
  throw new Error('work failed');
} catch (e) {
  console.log(e.name);              // "SuppressedError"
  console.log(e.error.message);     // "cleanup failed"
  console.log(e.suppressed.message); // "work failed"
}

Make sure your error reporting reads both properties; a logger that only prints message will show "An error was suppressed during disposal" and hide the real cause.

Browser support and adopting it today

According to MDN's browser compatibility data (version 8.1.5, 8 October 2026), using, await using, DisposableStack, AsyncDisposableStack and SuppressedError are supported from:

On the standards side, TC39's list of finished proposals includes Explicit Resource Management with an expected publication year of 2027, so the semantics are settled even though one engine has not shipped yet.

The Symbol.dispose protocol and DisposableStack are ordinary built-ins and can be polyfilled. The using keyword is new syntax: a browser that does not understand it rejects the whole script file, so a polyfill cannot help. Your options are:

1. Write disposable objects now, call them manually. Implement [Symbol.dispose]() on your helpers (guarding with Symbol.dispose ??= Symbol('Symbol.dispose') or a polyfill) and call obj[Symbol.dispose]() from finally. You can switch to using later without changing the helpers.
2. Compile the syntax. TypeScript and Babel can transform using into try...finally code for older targets.
3. Use it natively where you control the runtime, for example in Chrome-only internal tools, browser extensions for Chromium and Firefox, or Node.js 24 build scripts.

Gotchas

• Closures outlive the block. A callback that captures a using variable may run after disposal and work with a closed resource. Pass ownership with DisposableStack.move() instead.
• Do not export disposed values. export using is a syntax error, and exporting a module-level using variable gives importers a resource that is already disposed.
• Forgetting await in the block. using disposes when the block ends, not when a promise you returned settles.
• Classic scripts. Top-level using works only in modules (<script type="module">).

What to do next

• Pick one helper that has a matching "stop" or "close" function (a subscription, a timer, an observer) and give it a [Symbol.dispose]() method.
• Replace a multi-resource setup function with DisposableStack and move().
• Check your analytics for Safari share before shipping uncompiled using syntax to the public web.

The payoff is code where every acquisition visibly owns its cleanup, and where a failure halfway through setup no longer leaves listeners, timers and object URLs behind.