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.
{
using file = openFile("log.txt");
file.write("hello");
} // file[Symbol.dispose]() runs here
Try it
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.
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
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:
usingcannot be used at the top level of a script, in acaseclause without a block, or withvarorlet. Declare it inside a block, function or module.- If both the body and a disposal throw, a
SuppressedErroris created that holds the later error and the earlier one inerrorandsuppressed. - 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.disposablelibrary, and you need a runtime that providesSymbol.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 = nullis legal and does nothing, which suits optional resources.- Do not return a
usingvariable from its scope; it will already be disposed. - Use
await usingfor I/O cleanup such as closing connections, andusingfor synchronous work such as locks. - A
DisposableStackis useful when the number of resources is dynamic or when you need to hand cleanup ownership to the caller withmove().