Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Keywords and Declarations

The using and await using declarations

Reference for TypeScript using and await using: automatic cleanup with Symbol.dispose and Symbol.asyncDispose, disposal order, and error handling.

using declares a block-scoped constant like const, with one extra rule: when the surrounding block exits, the runtime calls the value's [Symbol.dispose]() method. await using does the same for [Symbol.asyncDispose]() and awaits the result. The cleanup runs on normal exit, return, break, continue and thrown errors.

The value must be an object with the right method, or null or undefined (which are skipped). Several using declarations in one block are disposed in reverse order, like a stack. TypeScript has supported the syntax since 5.2 and lowers it for older targets.

TypeScript
{
  using file = openFile("log.txt");
  file.write("hello");
} // file[Symbol.dispose]() runs here

Try it

TypeScript Disposal order and early exit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript await using and DisposableStack

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
using name = expression;
using a = x, b = y;
await using name = expression;
for (using item of items) {}
for await (await using item of source) {}

interface Disposable { [Symbol.dispose](): void }
interface AsyncDisposable { [Symbol.asyncDispose](): PromiseLike<void> }
Part Description
using Needs a Disposable, null or undefined. Binding is const-like and cannot be reassigned.
await using Needs an AsyncDisposable or Disposable. Allowed only where await is allowed.
DisposableStack / AsyncDisposableStack Collect cleanups and disposables to run in reverse order.

Edge cases and errors:

  • using cannot be used at the top level of a script, in a case clause without a block, or with var or let. Declare it inside a block, function or module.
  • If both the body and a disposal throw, a SuppressedError is created that holds the later error and the earlier one in error and suppressed.
  • All remaining disposals still run even if one throws.
  • Using a value without the dispose method is a compile-time error.
  • The types come from the esnext.disposable library, and you need a runtime that provides Symbol.dispose (Node 20 and later does).

Usage notes

  • Disposal order is last declared, first disposed, so a resource can depend on one declared earlier.
  • using x = null is legal and does nothing, which suits optional resources.
  • Do not return a using variable from its scope; it will already be disposed.
  • Use await using for I/O cleanup such as closing connections, and using for synchronous work such as locks.
  • A DisposableStack is useful when the number of resources is dynamic or when you need to hand cleanup ownership to the caller with move().