TypeScript using With AsyncDisposableStack: Coordinating Multi-Resource Teardown in Real Server Code
This article was written with the assistance of AI, under human supervision and review.
Most server-side resource leaks stem from incomplete teardown sequences when multiple async resources fail to clean up in production. A database connection closes but the Redis lock never releases. A file handle persists after the request completes because an upstream error short-circuited the cleanup chain. These failures happen silently until connection pools exhaust or disk quotas trigger alerts hours later.
The manual pattern teams reach for looks like nested try-finally blocks wrapping each resource. This approach breaks under real production conditions: errors in cleanup code prevent downstream resources from disposing, disposal order becomes implicit and fragile, and the code becomes unreadable past three resources. TypeScript's AsyncDisposableStack provides explicit coordination for multi-resource teardown with guaranteed disposal order and error aggregation that manual chains cannot match.
The solution coordinates resources through a stack that tracks every disposable and guarantees reverse-order teardown even when individual cleanup operations fail. A single await using stack = new AsyncDisposableStack() call establishes the coordinator. Each resource adoption via stack.adopt() registers the cleanup operation and ensures execution regardless of downstream failures. Errors during disposal aggregate into a SuppressedError chain that preserves all failure contexts instead of hiding them.
Key Takeaways AsyncDisposableStack coordinates multiple async resources through a single disposal point that guarantees reverse-order cleanup even when individual operations fail. Manual try-finally chains break under production error conditions because errors in cleanup code prevent downstream resources from disposing. The adopt() method registers any resource with a cleanup function, defer() delays arbitrary async work until disposal, and move() transfers ownership between stacks. Disposal always executes in reverse registration order (LIFO), and errors aggregate into SuppressedError chains that preserve every failure context. AsyncDisposableStack shines in request-scoped resource management where database connections, distributed locks, and file handles must release atomically regardless of request outcome.
AsyncDisposableStack implements the AsyncDisposable interface and provides three registration methods that teams use to build complex teardown sequences. Understanding how these methods differ determines which pattern fits a given production scenario.
The adopt() method takes a resource value and a cleanup function, returning the resource unchanged while registering the cleanup. This approach works for resources that do not implement Symbol.asyncDispose natively. The cleanup function receives the original resource value as its argument, enabling patterns like connection pool returns or lock releases that need the original reference.
The use() method registers an existing AsyncDisposable object directly, delegating to its Symbol.asyncDispose implementation. This method creates the most natural integration when resources already implement the disposal protocol. The stack calls [Symbol.asyncDispose]() on the registered object during its own disposal phase.
The defer() method schedules arbitrary async work for the disposal phase without tying it to a specific resource value. This pattern handles cleanup operations that depend on closure state or need to run regardless of whether a resource allocation succeeded. Deferred functions execute in reverse registration order alongside adopted resources.
Disposal order follows last-in-first-out semantics strictly. A stack that adopts a database connection, then a Redis lock, then a file handle will close the file handle first, release the lock second, and return the connection last. This ordering matters because later resources often depend on earlier ones remaining available during their own cleanup.
The move() method transfers all registered resources from one stack to another, leaving the source stack in a disposed state. This operation enables patterns where a function builds a resource set and returns ownership to the caller. The caller's stack assumes responsibility for cleanup, and the original stack becomes inert.
The disposed property indicates whether the stack has executed its disposal sequence. After disposal completes, any attempt to adopt new resources throws a ReferenceError. This guard prevents resource registration after cleanup has started, which would create impossible teardown guarantees.
A production API endpoint that processes uploaded files demonstrates the coordination problem AsyncDisposableStack solves. The operation needs a database transaction for metadata writes, a Redis lock to prevent concurrent processing of the same file, and a temporary file handle for staging the upload. All three resources must release atomically when the request completes or fails.
The manual approach chains try-finally blocks, creating nested error-handling contexts that become unmaintainable and fail to guarantee complete cleanup when intermediate operations error.
The failure mode here is subtle but expensive. An error in fs.unlink() prevents the lock release from executing. The lock holds for its 30-second TTL while the connection returns to the pool. Concurrent uploads to the same file block until the lock expires. The temporary file persists on disk. None of these failures surface as errors because the outer finally blocks never execute.
AsyncDisposableStack eliminates nested scopes and guarantees all cleanups execute regardless of individual failures.
When the function scope exits, the stack disposes the deferred unlink first, then releases the lock, then returns the connection. An error in any cleanup operation does not prevent the others from executing. The stack aggregates errors into a SuppressedError chain that preserves each failure context for logging and debugging.