Synchronous resource management
Close file handles, sockets, or other synchronous resources automatically when a block ends.
TypeScript · Const
using
The using declaration creates a fixed binding like const and automatically calls the resource's Symbol.dispose method when its scope ends. Cleanup also occurs on early exits and follows last-in-first-out order.
- Since
- 5.2
How it works
A using declaration creates a fixed binding whose resource is automatically disposed when control leaves its containing scope. Cleanup happens at scope exit, including early returns or thrown errors, and multiple resources are released in last-in-first-out order.
Syntax
using variable = expression;Key points
- using creates a fixed binding, so the resource variable cannot be reassigned.
- Synchronous resources are cleaned up by invoking Symbol.dispose when the scope finishes.
- Cleanup occurs at the boundary of the containing scope rather than immediately after the last use.
- When several resources are declared, the most recently acquired one is disposed first.
Common mistakes
- Runtime support may be absent, so provide the required disposal polyfills before relying on using.
- Compilation requires an ECMAScript target of ES2022 or lower.
- The TypeScript lib configuration must include the disposable library definitions.
Example: Dispose a resource at scope exit
Symbol.dispose ??= Symbol("Symbol.dispose");
class FileHandle {
[Symbol.dispose]() {
console.log("closed");
}
}
{
using file = new FileHandle();
console.log("working");
}The binding is fixed like const, and leaving the block invokes the object's Symbol.dispose method.
When to use it
Exception-safe cleanup
Ensure cleanup runs when functions return early or throw errors.
Stack-ordered teardown
Release nested resources in reverse acquisition order.
Interview questions
QHow does using differ from const?
A using declaration is similar to const because it creates a fixed binding, but it additionally arranges for the bound object's Symbol.dispose method to run when the scope ends. This makes resource cleanup automatic.
Follow-up: What happens if the scope exits through an exception? Cleanup still runs before the exception propagates.
QWhen are using resources disposed?
Resources are disposed at the end of their containing scope and before an early return or thrown error. Multiple using declarations are cleaned up in first-in-last-out order, like a stack.
Follow-up: Why is reverse order useful? It lets later-created resources be released before resources they may depend on.
QWhat configuration is needed for older runtimes?
The feature may need polyfills for Symbol.dispose and Symbol.asyncDispose, along with other disposable-stack and suppressed-error types when those APIs are used. The compiler target should be es2022 or lower, with an appropriate disposable lib.
Follow-up: What is the minimal polyfill requirement for only using and await using? The built-in disposal symbols are generally sufficient.
Related
await usingSymbol.disposeSymbol.asyncDisposeDisposableStackAsyncDisposableStackSuppressedError