Explicit resource management

Why cleanup needs help

Garbage collection reclaims memory when objects become unreachable. It does not close a file descriptor, release a mutex, roll back a transaction, unsubscribe from a feed, cancel a timer, remove a temporary DOM listener, or revoke a blob URL at the exact moment your code stops needing it.

Those are resources: handles to something outside ordinary JavaScript memory. They need a deterministic release step. Before explicit resource management, the reliable answer was try/finally. That works, but several resources make it verbose and easy to get wrong.

• file handles
• locks
• database connections
• subscriptions
• timers
• temporary DOM listeners
• object URLs

1const events = [];2let file;3let lock;4 5function open(name) {6  events.push(`open ${name}`);7  return { close: () => events.push(`close ${name}`) };8}9 10try {11  file = open("file");12  lock = open("lock");13  events.push("work");14} finally {15  if (lock) lock.close();16  if (file) file.close();17}18 19console.log(events.join(" -> "));

Line 10 opens the file and line 11 acquires the lock. Lines 14 and 15 must remember to release them in reverse order. Add a third resource, a conditional branch, or an early return, and the cleanup bookkeeping starts to hide the work you meant to describe.

A synchronous disposable object has a method named by the well-known symbol Symbol.dispose. The declaration using file = openFile() says: keep file visible in this scope, then call file[Symbol.dispose]() when the scope exits.

Disposal happens even if the block throws or returns early. Multiple declarations are disposed in reverse declaration order. Step through the same source with three exit paths and watch the trace prove it.

1const events = [];Run2 3function resource(name) {4  events.push(`acquire ${name}`);5  return {6    [Symbol.dispose]() {7      events.push(`dispose ${name}`);8    },9  };10}11 12function work() {13  using file = resource("file");14  using lock = resource("lock");15  events.push("work");16  if ("normal" === "throw") throw new Error("write failed");17  if ("normal" === "return") return "returned early";18  events.push("done");19  return "finished";20}21 22try {23  console.log(work());24} catch (error) {25  console.log(error.message);26}27console.log(events.join(" -> "));

1{2  using nothing = null;3  using alsoNothing = undefined;4  using handle = {5    [Symbol.dispose]() {6      console.log("disposed handle");7    },8  };9}10 11try {12  {13    using broken = {};14  }15} catch (error) {16  console.log(error instanceof TypeError);17  console.log(error.name);18}

Line 1 and line 2 are legal no-ops. Line 3 creates a real disposable object, so its method runs when the block ends. Line 12 shows the sharp edge: is not nullish and has no dispose method, so JavaScript throws TypeError instead of guessing.

Some cleanup is asynchronous: flushing a stream, closing a database connection, releasing a remote lock, or rolling back a transaction. For those resources, implement [Symbol.asyncDispose]() and declare them with await using. The scope does not finish until each async disposer has been awaited.

1(async () => {2  const events = [];Run3  function connection(name) {4    events.push(`open ${name}`);5    return {6      async [Symbol.asyncDispose]() {7        events.push(`start close ${name}`);8        await Promise.resolve();9        events.push(`closed ${name}`);10      },11    };12  }13 14  {15    await using db = connection("db");16    await using stream = connection("stream");17    events.push("query");18  }19 20  console.log(events.join(" -> "));21})();

The source deliberately logs after the block. That final log only runs after the stream closes and then the database closes. Reverse order still matters; the newer stream closes before the older connection.

1const events = [];2 3function* rows() {4  yield {5    name: "A",6    [Symbol.dispose]() {7      events.push("close A");8    },9  };10  yield {11    name: "B",12    [Symbol.dispose]() {13      events.push("close B");14    },15  };16}17 18for (using row of rows()) {19  events.push(`read ${row.name}`);20}21 22console.log(events.join(" -> "));

for (using row of rows()) creates a fresh disposable binding for each loop iteration. The row from one iteration closes before the next row is read, which is useful for cursors, paged handles, and temporary locks that should not overlap.

A block can acquire resources through helper branches: one URL here, one lock there, a cache callback only if an option is enabled. A stack gives that scattered code one owner. Register every cleanup as it is acquired, then dispose the stack once.

1const events = [];Run2const stack = new DisposableStack();3stack.defer(() => events.push("defer cache"));4stack.use({5  [Symbol.dispose]() { events.push("close file"); },6});7stack.adopt("lock", (name) => events.push(`release ${name}`));8const moved = stack.move();9console.log(stack.disposed);10moved.dispose();11console.log(moved.disposed);12console.log(events.join(" -> "));

The stack API has a small vocabulary. use(value) registers a value that is already disposable. adopt(value, onDispose) wraps a plain value and cleanup function. defer(fn) schedules a callback. move() transfers ownership to a new stack. dispose() runs cleanup, and disposed tells you whether the stack is closed.

1(async () => {2  const events = [];3  {4    await using stack = new AsyncDisposableStack();5    stack.defer(async () => events.push("defer metrics"));6    stack.use({7      async [Symbol.asyncDispose]() { events.push("close socket"); },8    });9    stack.adopt("transaction", async (value) => events.push(`rollback ${value}`));10    events.push("inside");11  }12  console.log(events.join(" -> "));13})();

Use AsyncDisposableStack when one or more cleanup callbacks return promises. Put it behind await using so the stack itself is awaited at scope exit.

Cleanup can fail. A file close may throw, a rollback may reject, or a listener removal may hit a host error. If that happens while another error is already leaving the block, JavaScript throws a SuppressedError so neither failure is lost.

1try {2  {3    using handle = {4      [Symbol.dispose]() {5        throw new Error("cleanup failed");6      },7    };8    throw new Error("work failed");9  }10} catch (error) {11  console.log(error instanceof SuppressedError);12  console.log(error.error.message);13  console.log(error.suppressed.message);14}

The printed output proves the shape: the caught value is a SuppressedError. Its error property is the cleanup failure (cleanup failed), and its suppressed property is the earlier work failure (work failed). That is the same debugging instinct you practiced in custom errors and error handling strategies: preserve the causal chain instead of overwriting it.

The smallest useful helper returns a disposable object. That keeps acquisition and release in the same function, so call sites cannot forget which cleanup function matches which setup function.

1function listen(target, type, handler, options) {2  target.addEventListener(type, handler, options);3  return {4    [Symbol.dispose]() {5      target.removeEventListener(type, handler, options);6    },7  };8}9 10const button = document.querySelector("#save") ??11  document.body.appendChild(document.createElement("button"));12 13{14  using click = listen(button, "click", () => console.log("clicked"));15  button.click();16}17 18button.click();19console.log("listener removed");

The first click logs because the listener is alive inside the block. The second click logs nothing because line 4 removed the listener when the block exited. This pattern works for temporary focus traps, one-off measurements, and listeners attached during a drag gesture.

1function objectUrlFor(blob) {2  const url = URL.createObjectURL(blob);3  return {4    url,5    [Symbol.dispose]() {6      URL.revokeObjectURL(url);7      console.log("revoked object URL");8    },9  };10}11 12{13  using preview = objectUrlFor(new Blob(["hello"], { type: "text/plain" }));14  console.log(preview.url.startsWith("blob:"));15}

Object URLs are a common browser leak. A photo preview can create a URL, assign it to an image, and revoke it when the preview scope ends. The wrapper makes URL.revokeObjectURL impossible to miss. This example is not run in the sandboxed editor because object URL lifetimes belong to the preview document that owns the blob.

1async function enterTransaction(db) {2  const transaction = await db.begin();3  return {4    transaction,5    async [Symbol.asyncDispose]() {6      if (transaction.open) await transaction.rollback();7    },8  };9}10 11async function saveInvoice(db, invoice) {12  await using scope = await enterTransaction(db);13  await scope.transaction.insert(invoice);14  await scope.transaction.commit();15}

Locks and transactions often need await using. If insert throws, the transaction is still open, so the disposer rolls it back. If commit closes it first, the disposer becomes a safe no-op.

MDN browser data lists explicit resource management as available in Chrome and Edge 134+, Firefox 141+, Node.js 24+, and Safari Technology Preview. That is not the same as saying every user's browser supports it. Feature-detect before offering runnable examples, and use TypeScript downleveling when you need older runtimes.

1function supportsUsingSyntax() {2  try {3    new Function("{ using x = null; }");4    return true;5  } catch {6    return false;7  }8}9 10console.log(supportsUsingSyntax());

1<script>2  // SyntaxError in a classic script's top level.3  using handle = openHandle();4</script>5 6<script type="module">7  // Module top level is allowed.8  using handle = openHandle();9</script>10 11<script>12  // Blocks and functions are allowed in classic scripts.13  {14    using handle = openHandle();15  }16</script>

1import { open } from "node:fs/promises";2import { setTimeout as delay } from "node:timers/promises";3 4await using file = await open("report.txt", "r");5const text = await file.readFile("utf8");6 7using timer = setTimeout(() => console.log("too slow"), 5000);8await delay(10);9console.log(text.length);

Modern Node file handles expose [Symbol.asyncDispose](), and timer handles expose [Symbol.dispose](). The important version boundary is parsing: Node 22 has Symbol.dispose and Symbol.asyncDispose, but it does not parse using. Node 24+ does.

1// TypeScript 5.2+ accepts this syntax.2{3  using stack = new DisposableStack();4  const file = stack.use(openFile());5  stack.defer(() => console.log("always runs"));6}7 8// For older targets, TypeScript emits helper code with try/finally9// and calls Symbol.dispose / Symbol.asyncDispose for you.

Common misconceptions and comparisons

• “Garbage collection will close it.” Garbage collection frees memory. It does not promise to release file descriptors, locks, subscriptions, timers, or blob URLs at the moment you need.
• “FinalizationRegistry is a cleanup replacement.” It is a backup notification mechanism. Its callback timing is deliberately not guaranteed. Review WeakRef & FinalizationRegistry for the non-deterministic model.
• “using catches errors.” It does not catch. It cleans up while control leaves the scope, then the return or throw continues.
• “The first resource closes first.” Cleanup is reverse declaration or registration order.
• “If Symbol.dispose exists, syntax is safe.” Node 22 proves otherwise: the symbols exist, but the parser rejects using.
• “This is brand new in programming.” The idea is familiar from C# using and Python with; JavaScript's version uses well-known symbols and separate sync/async protocols.

1const registry = new FinalizationRegistry((id) => {2  console.log("maybe later", id);3});4 5function cacheImage(image) {6  registry.register(image, image.id);7  return new WeakRef(image);8}9 10// You cannot predict when, or whether, the callback runs.

The symbol names also connect back to Symbols and well-known symbols: JavaScript uses built-in symbols as opt-in hooks for language behavior.

Key takeaways

• using calls [Symbol.dispose]() at scope exit.
• await using awaits [Symbol.asyncDispose]() at scope exit.
• Cleanup runs in reverse declaration or registration order, even on throw or early return.
• DisposableStack and AsyncDisposableStack group scattered cleanup under one owner.
• SuppressedError preserves both a cleanup failure and an original failure.
• Use FinalizationRegistry only as a non-deterministic backup, not as resource cleanup.

This is the last lesson in Binary data & memory and the Advanced language features stage. Up next: Professional JavaScript begins with npm and package.json.