Explicit resource management

Why cleanup needs help

JavaScript frees memory for you. When no code can reach an object any more, the garbage collector removes it. You don't know when that happens.

Some things need more than freed memory. An open file must be closed. A lock must be released, so other code can take it. A click listener must be removed. The garbage collector does none of this at the moment you are done.

These things are called resources. Your code holds a small object for each one, called a handle. The handle lets you use the resource and then give it back. Giving it back is called disposing of it, or cleanup.

The usual tool for cleanup is try/finally. The code in finally runs however the try block ends. It works, but with several resources the cleanup code gets long and easy to get wrong.

These are common resources that need cleanup:

• open files
• locks
• database connections
• subscriptions to updates
• timers
• short-lived event listeners
• blob URLs made with URL.createObjectURL()

const events = [];
try {
  events.push("work");
  throw new Error("failed");
} catch (error) {
  events.push(error.message);
} finally {
  events.push("close");
}
console.log(events.join(" -> "));

Line 3 records work. Line 4 throws an error. The catch block records the message, failed. Then the finally block records close. The output is work -> failed -> close.

try/finally is still useful. Use it in older browsers, or for cleanup that doesn't belong to one object.

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 11 opens the file. Line 12 opens the lock. Lines 15 and 16 close them again, in the opposite order: the lock first, then the file. You must remember to write both lines. Line 19 prints open file -> open lock -> work -> close lock -> close file.

Add a third resource, an if, or an early return, and the cleanup code starts to hide the real work. There is one more problem. If lock.close() throws, line 16 never runs, so the file stays open. To be sure both close, you need one try/finally inside another.

const events = [];
function openSecond() { throw new Error("second open failed"); }
try {
  using first = { [Symbol.dispose]() { events.push("close first"); } };
  using second = openSecond();
} catch (error) {
  events.push(error.message);
}
console.log(events.join(" -> "));

Line 4 creates first with using, so JavaScript already knows to clean it up. Line 5 tries to open a second resource, but openSecond() throws. JavaScript cleans up first before the catch runs. The output is close first -> second open failed.

The lesson: hand each resource to using as soon as you get it. Don't wait until you have all of them.

The table compares four cleanup tools. Read each row as: what the tool is good for, and what it costs.

An object can be cleaned up by using when it has a method named [Symbol.dispose]. Symbol.dispose is a built-in symbol: a special, unique property key that JavaScript itself knows about. The square brackets mean "use this symbol as the method name".

The line using file = openFile() does two things:

• It creates the variable file, which you can use inside the block.
• It tells JavaScript to call file[Symbol.dispose]() when the code leaves the block.

The cleanup runs even if the block throws an error or returns early. With two using lines, the one written last is cleaned up first. Step through the code below. Pick each of the three ways out, and watch the order of the events.

const events = [];
{
  using maybeLock = null;
  using lock = { [Symbol.dispose]() { events.push("unlock"); } };
  events.push("work");
}
console.log(events.join(" -> "));

Line 3 sets maybeLock to null, so there is nothing to clean up. JavaScript simply skips it. Line 4 creates a real lock. When the block ends, the lock is cleaned up, so the code prints work -> unlock.

So a resource that might be missing is fine. A normal object with no cleanup method is not; you'll see why below.

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}

Lines 2 and 3 are allowed and do nothing. Line 4 creates an object with a cleanup method, so it prints disposed handle when the block ends.

Line 13 is the mistake. {} is not null or undefined, and it has no cleanup method. JavaScript throws a TypeError instead of guessing. Lines 16 and 17 print true and TypeError.

let saved;
{
  using handle = {
    closed: false,
    [Symbol.dispose]() { this.closed = true; },
  };
  saved = handle;
}
console.log(saved.closed);

Line 7 saves the handle in saved, a variable outside the block. That copies the reference, but the block still owns the resource. The block closes the handle when it ends, so line 9 prints true.

Don't return or save a handle from a using block. Return the data you read from it instead.

Some cleanup takes time. Closing a database connection, saving the last data in a stream, or undoing a half-finished database change all return a promise: an object that finishes later.

For these resources, give the object an [Symbol.asyncDispose]() method and create the variable with await using. The block does not finish until each of these cleanup promises has finished.

(async () => {
  const events = [];
  {
    await using lock = { [Symbol.dispose]() { events.push("unlock"); } };
    events.push("work");
  }
  console.log(events.join(" -> "));
})();

The lock on line 4 has only [Symbol.dispose], the normal cleanup method. That's fine: when there is no [Symbol.asyncDispose], await using uses [Symbol.dispose] instead. It still pauses for a moment when the block ends. The output is work -> unlock.

The other way round doesn't work. A plain using can't use an object that only has [Symbol.asyncDispose].

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 last log on line 20 is outside the block on purpose. It runs only after the stream has closed and then the database has closed. The order is still reversed: the stream was opened last, so it closes first.

(async () => {
  const events = [];
  async function open() {
    events.push("open");
    return { async [Symbol.asyncDispose]() { events.push("close"); } };
  }
  {
    await using connection = await open();
    events.push("work");
  }
  console.log(events.join(" -> "));
})();

Line 8 has two waits, at two different times:

• await open() waits right away, until the connection is open.
• await using waits later, at the end of the block, until the cleanup is done.

The output is open -> work -> close.

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(" -> "));

Line 18 is for (using row of rows()). Each turn of the loop gets a new row variable, created with using. The row is cleaned up at the end of its turn, before the loop reads the next row. Line 22 prints read A -> close A -> read B -> close B.

This helps when only one resource may be open at a time, such as one page of database results.

Sometimes a block gets its resources from different places. One helper function creates a URL. Another takes a lock. A third adds a callback, but only if a setting is on. Writing a using line for each one is hard.

A DisposableStack collects all the cleanup in one place. Each time you get a resource, you add its cleanup to the stack. At the end, you clean up the stack once, and it cleans up everything in it.

const events = [];
{
  using stack = new DisposableStack();
  stack.defer(() => events.push("remove listener"));
  events.push("listening");
}
console.log(events.join(" -> "));

Line 3 creates the stack with using, so the stack is cleaned up when the block ends. Line 4 adds one cleanup callback right away. The output is listening -> remove listener.

A stack does not clean itself up. Create it with using, or call its dispose() method yourself.

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(" -> "));

A stack has a few methods and one property:

• use(value) adds an object that already has a [Symbol.dispose] method.
• adopt(value, onDispose) adds a plain value, plus a function that cleans it up.
• defer(fn) adds a cleanup function on its own.
• move() moves all the cleanup to a new stack, and marks the old stack as done.
• dispose() runs all the cleanup, last added first.
• disposed is true once the stack has been cleaned up.

const stack = new DisposableStack();
let closes = 0;
stack.defer(() => closes++);
stack.dispose();
stack.dispose();
console.log(closes, stack.disposed);

Lines 4 and 5 both call dispose(), but the callback runs only once. The second call does nothing. Line 6 prints 1 true.

When you open a new handle, add it to the stack in the same line: stack.use(open()). Then no code can run between opening the handle and adding it.

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 some cleanup returns a promise. Create it with await using on line 4, so JavaScript waits for the whole stack when the block ends. Lines 5, 6, and 9 add three cleanups. Line 10 records inside. When the block ends, the three cleanups run in reverse order. Line 12 prints inside -> rollback transaction -> close socket -> defer metrics.

Cleanup can fail too. Closing a file can throw an error. Undoing a database change can fail. Removing a listener can hit a browser error.

Sometimes the block is already ending because of an error, and then the cleanup throws a second error. JavaScript doesn't drop either one. It throws a new error, a SuppressedError, that holds both.

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}

Line 8 throws work failed. As the block ends, the cleanup method on line 4 runs and throws cleanup failed. The catch on line 10 receives one error that holds both:

• Line 11 prints true: the caught error is a SuppressedError.
• Line 12 prints cleanup failed: the error property holds the cleanup failure.
• Line 13 prints work failed: the suppressed property holds the earlier work failure.

You practiced the same habit in custom errors and error handling strategies: keep every error that explains what went wrong, instead of replacing one with another.

try {
  using first = { [Symbol.dispose]() { throw Error("first close"); } };
  using second = { [Symbol.dispose]() { throw Error("second close"); } };
  throw Error("work");
} catch (error) {
  console.log(error.error.message);
  console.log(error.suppressed.error.message);
  console.log(error.suppressed.suppressed.message);
}

Line 4 throws work. Then second is cleaned up first, and it throws. first is still cleaned up after that, and it throws too. Each failure wraps the one before it. Lines 6 to 8 print first close, second close, and then work.

To find an earlier error, follow the suppressed property one step at a time. When you report the error, keep all of them.

A good pattern is a small helper function that returns an object with a cleanup method. The helper sets the resource up and also knows how to clean it up. The code that calls the helper can't pair the wrong cleanup with the wrong setup.

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");

Line 1 defines listen(). It adds a listener on line 2. Its cleanup method on line 4 removes the same listener on line 5.

Line 14 adds a click listener with using. The click on line 15 logs clicked, because the listener is still there. When the block ends, the listener is removed. So the click on line 18 logs nothing, and line 19 prints listener removed.

Use this for any listener you need only for a short time, such as while the user drags something across the page.

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}

URL.createObjectURL() on line 2 makes a blob: URL that points at data in memory, such as a picked photo. The browser keeps that data until you call URL.revokeObjectURL() or the page closes. If you forget, the data stays in memory the whole time.

The cleanup method on line 5 revokes the URL on line 6. Line 13 creates the preview with using, and line 14 prints true. Then the block ends, and the code prints revoked object URL.

In a real app, revoke a preview URL when the preview is replaced or removed. Don't let a short function revoke it while an image on the page still shows it. This example only logs the URL. It doesn't run in the editor sandbox, because a blob URL belongs to the page that created it.

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}

A transaction is a group of database changes that either all happen or none do. Closing one takes time, so this example uses await using on line 12.

• If insert throws, the transaction is still open, so the cleanup on line 6 undoes it with rollback().
• If commit() on line 14 succeeds, the transaction is closed, so the cleanup does nothing.

According to MDN's browser data, these support explicit resource management:

• Chrome and Edge 134 and later
• Firefox 141 and later
• Node.js 24 and later
• Safari Technology Preview, Apple's test version of Safari

That doesn't mean every visitor's browser supports it. Check the runtime, the program that really runs your code, such as a browser or Node. For older runtimes, let TypeScript rewrite the code into older JavaScript.

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

The first table lists what supports the feature. Read each row as: where, which versions, and what to remember.

The second table lists where you may write using. Read each row as: the place, whether it works, and an example.

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>

A classic script is a plain <script> tag. Line 3 puts using at its top level, outside any block, so it fails. Line 8 is the same line in a module script, <script type="module">, and it works. Line 14 puts the line inside { }, which works in a classic script too.

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);

In modern Node, a file handle has an [Symbol.asyncDispose]() method, so line 4 uses await using. A timer handle has a [Symbol.dispose]() method, so line 7 uses using.

Watch the version. Node 22 already has Symbol.dispose and Symbol.asyncDispose, but it can't read the using keyword. Node 24 and later can.

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.

TypeScript can rewrite using into older code with try/finally. The rewritten code still needs Symbol.dispose or Symbol.asyncDispose to exist when it runs. If you use DisposableStack, the runtime needs that too, or a polyfill: a small script that adds a missing feature. Check the runtime as well as the TypeScript version.

Common misconceptions and comparisons

• “The garbage collector will close it.” The garbage collector frees memory. It doesn't promise to close files, release locks, stop timers, remove listeners, or revoke blob URLs when you need it to.
• “FinalizationRegistry can do the cleanup.” A FinalizationRegistry calls a function some time after an object is removed from memory. It may run late, or never. Use it only as a backup. See WeakRef & FinalizationRegistry.
• “using catches errors.” It doesn't. It cleans up as the code leaves the block. Then the return or the error carries on as normal.
• “The first resource closes first.” It closes last. The resource added last is cleaned up first.
• “If Symbol.dispose exists, I can write using.” Not always. Node 22 has the symbol, but it can't read the using keyword.
• “No other language does this.” C# has using and Python has with for the same job. JavaScript's version uses built-in symbols, with one method for normal cleanup and one for cleanup that takes time.

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.

Line 1 creates the registry. Line 6 asks it to call the function after image is removed from memory. As line 10 says, you can't know when that happens, or whether it happens at all.

The table compares three ways to clean up. Read each column as one tool, and each row as one question.

The method names come from Symbols and well-known symbols. JavaScript uses built-in symbols to let your objects take part in language features.

Key takeaways

• using calls [Symbol.dispose]() when the code leaves the block.
• await using waits for [Symbol.asyncDispose]() when the code leaves the block.
• The resource created last is cleaned up first, even after an error or an early return.
• DisposableStack and AsyncDisposableStack collect cleanup from many places in one spot.
• SuppressedError keeps both the cleanup error and the error that came before it.
• FinalizationRegistry may run late or never, so use it only as a backup.

This is the last lesson in Binary data & memory, and in the Advanced language features stage. Next, Professional JavaScript starts with npm and package.json.