TypeScript `using` in Real Codebases: Database Connections, File Handles, and Async Disposal Done Right

A developer outlines how the `using` and `await using` declarations in ES2026 and TypeScript 5.2 guarantee deterministic resource disposal at scope exit, eliminating leaked database connections and file handles. The writeup explains that `Symbol.dispose` and `Symbol.asyncDispose` are called automatically on normal return, throw, or break, with resources disposed in reverse declaration order and errors aggregated via `SuppressedError`.

using in Real Codebases: Database Connections, File Handles, and Async Disposal Done Right This article was written with the assistance of AI, under human supervision and review. Most resource leak bugs stem from a single assumption: developers remember to close what they open. Production codebases overflow with database connections held open by early returns, file handles left dangling after exceptions, and transaction scopes rolled back inconsistently because the cleanup logic sits five functions away from the acquisition site. The using keyword shipped in ES2026 and TypeScript 5.2 eliminates this entire class of failure by guaranteeing disposal at scope exit. When a resource marked with using goes out of scope, the runtime calls its Symbol.dispose method automatically. No try/finally scaffolding. No manual cleanup tracking. No leaked connections because an engineer forgot to close a stream in the error path. Traditional resource management requires explicit cleanup in every exit path. Miss one and the connection leaks. Add a new return statement and the leak reappears. The cognitive load compounds in async contexts where finally blocks must await disposal calls and race conditions turn subtle. The using declaration makes disposal deterministic. The connection closes when the block ends, whether by normal return, throw, or break. The disposal happens in the correct order when multiple resources stack. Async disposal via await using handles asynchronous cleanup without race conditions. The pattern scales from file handles to distributed locks without new footguns. await using handles async disposal correctly by awaiting the Symbol.asyncDispose method before continuing execution, preventing race conditions in asynchronous resource cleanup. The using keyword marks a variable declaration as disposable. When the containing block exits, the runtime calls the Symbol.dispose method on the value. The disposal happens synchronously. If the method throws, the error propagates after the block completes. class FileHandle { constructor private fd: number {} Symbol.dispose { // Called automatically at scope exit closeSync this.fd ; } } function processFile path: string { using handle = new FileHandle openSync path ; // Use the file handle // Disposal happens here when scope ends } The await using variant handles asynchronous disposal. The Symbol.asyncDispose method returns a promise. The runtime awaits it before continuing. This matters for network connections, database transactions, and distributed locks where cleanup requires async operations. class DatabaseConnection { constructor private conn: Connection {} async Symbol.asyncDispose { // Called automatically at scope exit await this.conn.close ; } } async function runQuery sql: string { await using conn = await pool.acquire ; return await conn.query sql ; // Disposal awaited here before function returns } The disposal order matters. When multiple using declarations exist in the same scope, they dispose in reverse order of declaration. This matches the stack-unwinding semantics developers expect from nested resource acquisition. The disposal happens even when exceptions occur. If the block throws, the runtime calls Symbol.dispose on all declared resources before propagating the error. If disposal itself throws, the runtime aggregates the errors using SuppressedError . The original error remains the primary exception and the disposal error attaches as the suppressed property. Database connection leaks destroy production systems. A connection held open for ten seconds too long under load means hundreds of requests queued behind it. Teams add connection pool monitoring, implement timeouts, and still find connections leaking in error paths because manual cleanup logic lives three layers away from the acquisition site. The disposable connection pattern wraps pool connections with automatic release. The wrapper acquires a connection on construction and releases it in Symbol.asyncDispose . When the connection goes out of scope, it returns to the pool immediately. No timeouts. No manual release calls. No leaked connections because an engineer forgot to call release in the error handler. class DisposableConnection { private constructor private conn: PoolConnection, private pool: Pool {} static async acquire pool: Pool : Promise<DisposableConnection { const conn = await pool.connect ; return new DisposableConnection conn, pool ; } async query<T sql: string, params?: unknown : Promise<T { return await this.conn.query<T sql, params ; } async Symbol.asyncDispose { await this.pool.release this.conn ; } } async function fetchUsers ids: number : Promise<User { await using conn = await DisposableConnection.acquire pool ; return await conn.query 'SELECT FROM users WHERE id = ANY $1 ', ids ; // Connection released here automatically } The pattern eliminates the try/finally ceremony. Traditional code requires explicit release in every exit path. Add a new return statement and the release disappears. Throw an exception and the connection leaks unless the finally block catches it. The disposable wrapper makes leaks impossible by construction. Transaction scopes become simpler. A transaction wrapper handles begin, commit, rollback, and connection release as a single disposable resource. The transaction commits on normal scope exit and rolls back on exception. The connection returns to the pool in both cases. class Transaction { private committed = false; private constructor private conn: DisposableConnection, private pool: Pool {} static async begin pool: Pool : Promise<Transaction { const conn = await DisposableConnection.acquire pool ; await conn.query 'BEGIN' ; return new Transaction conn, pool ; } async query<T sql: string, params?: unknown : Promise<T { return await this.conn.query<T sql, params ; } async commit : Promise<void { await this.conn.query 'COMMIT' ; this.committed = true; } async Symbol.asyncDispose { if this.committed { await this.conn.query 'ROLLBACK' ; } await this.conn Symbol.asyncDispose ; } } async function transferFunds from: number, to: number, amount: number { await using tx = await Transaction.begin pool ; await tx.query 'UPDATE accounts SET balance = balance - $1 WHERE id = $2', amount, from ; await tx.query 'UPDATE accounts SET balance = balance + $1 WHERE id = $2', amount, to ; await tx.commit ; // Rollback happens automatically if commit not called } The transaction commits only when explicitly called. If any query throws or the function returns early, the transaction rolls back. The connection returns to the pool after rollback completes. The pattern guarantees cleanup without manual error handling scaffolding. File handle leaks manifest as "too many open files" errors under load. A stream left open after an exception means one less available file descriptor. Multiply by concurrent requests and the process hits ulimit within seconds. Teams add manual close calls, wrap operations in try/finally, and still find handles leaking when new error paths appear. The disposable stream pattern makes leaks impossible. The wrapper opens the stream on construction and closes it in Symbol.dispose . When the stream goes out of scope, it closes immediately. No try/finally. No manual tracking. No handle leaks because an engineer forgot to close in the error path. class DisposableReadStream { private constructor private stream: ReadStream {} static open path: string : DisposableReadStream { return new DisposableReadStream createReadStream path ; } async read : Promise<Buffer { const chunks: Buffer = ; for await const chunk of this.stream { chunks.push chunk ; } return Buffer.concat chunks ; } Symbol.dispose { this.stream.destroy ; } } function processLogFile path: string : void { using stream = DisposableReadStream.open path ; const content = await stream.read ; // Process content // Stream closed here automatically } The pattern works for write streams with buffering guarantees. A disposable write stream flushes and closes in disposal. The flush completes before disposal returns, ensuring data reaches disk before the function exits. Traditional code requires explicit flush calls before close, creating another footgun. class DisposableWriteStream { private constructor private stream: WriteStream {} static open path: string : DisposableWriteStream { return new DisposableWriteStream createWriteStream path ; } write data: string | Buffer : void { this.stream.write data ; } async Symbol.asyncDispose { return new Promise<void resolve, reject = { this.stream.end err = { if err reject err ; else resolve ; } ; } ; } } async function writeReport path: string, data: ReportData : Promise<void { await using stream = DisposableWriteStream.open path ; stream.write JSON.stringify data ; // Stream flushed and closed here automatically } The async disposal ensures the flush completes. If the flush fails, the error propagates. If the function throws before disposal, the stream still flushes and closes. The pattern eliminates the entire class of bugs where data sits in buffers because the stream closed without flushing. Temporary file management becomes simpler. A disposable temporary file creates the file on construction and deletes it in disposal. The file disappears when it goes out of scope, whether by normal return or exception. No manual cleanup. No leaked temp files because an engineer forgot to delete in the error path. class TemporaryFile { readonly path: string; constructor { this.path = join tmpdir , temp-${randomUUID }.tmp ; writeFileSync this.path, '' ; } Symbol.dispose { unlinkSync this.path ; } } function processWithTempFile data: Buffer : Result { using temp = new TemporaryFile ; writeFileSync temp.path, data ; // Process the file return result; // Temp file deleted here automatically } Distributed locks require precise acquisition and release timing. Hold a lock too long and throughput collapses. Release too early and race conditions appear. Traditional lock management wraps acquisition in try/finally blocks and hopes engineers remember to release in every exit path. Add an early return and the lock leaks. Throw an exception and the release disappears. The disposable lock pattern guarantees release at scope exit. The lock acquires on construction and releases in Symbol.asyncDispose . When the lock goes out of scope, it releases immediately. No manual release calls. No leaked locks because an engineer forgot to release in an error handler. class DistributedLock { private constructor private key: string, private redis: Redis {} static async acquire redis: Redis, key: string : Promise<DistributedLock { const acquired = await redis.set key, '1', 'NX', 'EX', 10 ; if acquired { throw new Error 'Lock already held' ; } return new DistributedLock key, redis ; } async Symbol.asyncDispose { await this.redis.del this.key ; } } async function processExclusively userId: number : Promise<void { await using lock = await DistributedLock.acquire redis, user:${userId} ; // Critical section here // Lock released here automatically } The disposal happens even when exceptions occur. If the critical section throws, the lock releases before the error propagates. If the lock acquisition fails, no disposal occurs because the lock never entered scope. The pattern eliminates the entire class of deadlocks caused by locks held after exceptions. Worker thread pools benefit from the same pattern. A disposable worker acquires a thread on construction and releases it in disposal. When the worker goes out of scope, the thread returns to the pool. No manual release. No thread leaks because an engineer forgot to terminate in an error path. class DisposableWorker { private constructor private worker: Worker {} static async spawn script: string : Promise<DisposableWorker { const worker = new Worker script ; await new Promise resolve = worker.once 'online', resolve ; return new DisposableWorker worker ; } async execute<T task: Task : Promise<T { return new Promise resolve, reject = { this.worker.postMessage task ; this.worker.once 'message', resolve ; this.worker.once 'error', reject ; } ; } async Symbol.asyncDispose { await this.worker.terminate ; } } async function processInWorker data: Buffer : Promise<Result { await using worker = await DisposableWorker.spawn './worker.js' ; return await worker.execute { type: 'process', data } ; // Worker terminated here automatically } The pattern scales to nested resource acquisition. Multiple using declarations stack naturally. Each resource disposes in reverse order of acquisition when the scope ends. Disposal order matches the dependency graph automatically. The using keyword eliminates manual cleanup but introduces new failure modes. Developers expect disposal to happen at function exit, not at block exit. When a using declaration sits inside a conditional or loop, disposal happens when the block ends, not when the function returns. This creates surprising behavior when resources outlive their intended scope. js async function processItems items: Item : Promise<void { for const item of items { await using lock = await DistributedLock.acquire redis, item.id ; // Lock released here at end of loop iteration await processItem item ; } // Locks already released, not here } The lock releases at the end of each loop iteration, not at function exit. If the processing requires the lock to persist across iterations, the pattern breaks. Developers must explicitly widen the scope by moving the declaration outside the loop or restructuring the logic to acquire once. Nested scopes compound the confusion. When a using declaration sits inside a try block, disposal happens when the try block ends, not when the function returns. If the catch block needs the resource, it no longer exists. If the finally block expects to clean up the resource, disposal already happened. async function attemptOperation : Promise<void { try { await using conn = await DisposableConnection.acquire pool ; await conn.query 'SELECT 1' ; // Connection released here when try block ends } catch error { // Connection already disposed, cannot use here console.error 'Operation failed' ; } } The solution requires moving the using declaration outside the try block. This widens the disposal scope to encompass the entire function. The connection remains available in the catch block. Disposal happens after the catch block completes. Disposal order guarantees matter in complex scenarios. Multiple using declarations dispose in reverse order of declaration. If disposal order encodes business logic or synchronization requirements, the declaration order becomes load-bearing. Reorder declarations and the disposal order changes, potentially breaking correctness. async function nestedResources : Promise<void { await using lock = await DistributedLock.acquire redis, 'key' ; await using conn = await DisposableConnection.acquire pool ; // Operations here // conn disposes first, then lock } The connection disposes before the lock. If the connection disposal requires the lock to remain held, the order breaks. Developers must structure declarations to match the required disposal order explicitly. The compiler provides no warnings when disposal order matters for correctness. Early returns inside using scopes behave correctly but require mental model adjustment. When a function returns early from a block containing using declarations, disposal happens before the return completes. The disposal runs synchronously for using and awaits for await using . This guarantees cleanup happens before the function exits but changes the execution order developers expect from traditional try/finally patterns. Migrating existing resource management to using patterns requires careful attention to disposal timing. Production code encodes subtle contracts around when cleanup happens. Change disposal timing and race conditions appear. Change disposal order and synchronization breaks. The safest migration path converts one resource type at a time. Start with leaf resources that have no dependencies on other cleanup. Database connections, file handles, and temporary files make good initial candidates because their disposal rarely depends on other resources being alive. The disposable wrapper sits alongside existing cleanup code during migration. Both paths coexist. Call sites convert incrementally. The wrapper includes assertions to catch double-disposal bugs where manual cleanup runs alongside automatic disposal. class MigrationConnection { private disposed = false; constructor private conn: PoolConnection, private pool: Pool {} async query<T sql: string, params?: unknown : Promise<T { if this.disposed { throw new Error 'Connection already disposed' ; } return await this.conn.query<T sql, params ; } async release : Promise<void { // Legacy manual cleanup path await this Symbol.asyncDispose ; } async Symbol.asyncDispose { if this.disposed return; this.disposed = true; await this.pool.release this.conn ; } } The migration wrapper supports both manual and automatic cleanup. Call sites using manual cleanup continue working. Call sites using await using work correctly. The disposed flag prevents double-cleanup. Once all call sites convert, the manual cleanup method disappears. Disposal order migration requires mapping existing cleanup sequences. If manual cleanup runs in a specific order to prevent race conditions, the using declarations must appear in the same order. The compiler provides no validation. Teams must document disposal order requirements explicitly. js // Before: manual cleanup order matters const lockA = await acquireLockA ; const lockB = await acquireLockB ; try { // operations } finally { await releaseLockB lockB ; // Must release B before A await releaseLockA lockA ; } // After: declaration order encodes disposal order await using lockA = await DisposableLockA.acquire ; await using lockB = await DisposableLockB.acquire ; // lockB disposes before lockA automatically The disposal order reverses declaration order. When manual cleanup required releasing B before A, the using declarations must declare A before B. This inversion confuses engineers familiar with the manual cleanup order. Documentation must highlight the reversal explicitly. Testing disposal behavior requires synthetic scope boundaries. Production disposal happens at scope exit, which occurs at unpredictable times. Tests must force disposal by creating explicit blocks or using dispose helpers that trigger disposal manually. js test 'connection disposes on scope exit', async = { let disposed = false; { await using conn = new TestConnection = { disposed = true; } ; expect disposed .toBe false ; } expect disposed .toBe true ; } ; The test creates a synthetic block to trigger disposal. The disposal callback sets a flag. The test verifies the flag transitions at the expected time. Without the explicit block, disposal timing becomes non-deterministic and the test flakes. No. A using declaration inside a loop body creates a new resource instance on each iteration and disposes it when the iteration completes. If the resource must persist across iterations, move the declaration outside the loop or restructure the logic to acquire once and reuse. Yes. When a scope containing await using exits, execution suspends until the Symbol.asyncDispose method completes. This ensures cleanup finishes before control returns to the caller. If disposal takes significant time, it delays subsequent operations. Profile disposal timing in production to catch unexpectedly slow cleanup. If a block exits normally and disposal throws, the disposal error propagates as the primary exception. If the block exits via throw and disposal also throws, the runtime creates a SuppressedError containing both the original exception and the disposal error. The original error remains primary and the disposal error attaches as the suppressed property. Yes, but disposal runs multiple times. Each using declaration tracks disposal independently. If multiple declarations reference the same object, Symbol.dispose runs once per declaration. Implement idempotent disposal or track disposed state internally to prevent double-cleanup bugs. Symbol.dispose when used with TypeScript 5.2+ requires the type to implement the Disposable or AsyncDisposable interface when used with using or await using . The compiler errors if the symbol method is missing. This catches usage errors at compile time instead of runtime. Older TypeScript versions provide no type safety and fail at runtime if the method is absent. The using keyword eliminates resource leak footguns in scenarios where disposal timing maps to scope boundaries. Database connections, file handles, distributed locks, and transaction scopes benefit immediately. The pattern guarantees cleanup happens in the correct order at the correct time without manual scaffolding. Traditional patterns still win when disposal timing decouples from scope boundaries. Long-lived resources managed by external lifecycles, resources shared across multiple scopes, and cleanup that depends on runtime conditions outside block structure require explicit control. The using keyword cannot express "close this resource after the third call" or "dispose when the metric crosses a threshold". Those scenarios still need manual cleanup. The migration decision reduces to a simple heuristic: if acquisition and disposal map to entry and exit of a single block, convert to using . If cleanup timing depends on anything else, keep manual control. Apply this in production and the difference will be immediate. Resource leaks disappear. Cleanup code shrinks. The cognitive load of tracking disposal across error paths evaporates. That covers the essential patterns for TypeScript resource management with using . Apply these in production and the difference will be immediate.