# TypeScript `using` in Real Codebases: Database Connections, File Handles, and Async Disposal Done Right 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. ```mermaid flowchart LR A("Acquire database connection") B("Execute query") C("Early return on error") D("Connection stays open") style D stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` 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. ```mermaid flowchart LR A("Acquire database connection") B("using connection = pool.acquire()") C("Execute query") D("Scope ends, dispose called") style D stroke:#34d399,fill:#0b3b2e,color:#d1fae5 style B stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px ``` 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. ## Key Takeaways - The `using` keyword guarantees disposal at scope exit, eliminating the entire class of resource leaks caused by missed cleanup in early-return or exception paths. - `await using` handles async disposal correctly by awaiting the `Symbol.asyncDispose` method before continuing execution, preventing race conditions in asynchronous resource cleanup. - Database connection pools, file streams, and transaction scopes become dramatically simpler when implemented as disposable resources instead of manual try/finally scaffolding. - Multiple `using` declarations in the same scope dispose in reverse order of declaration, matching the stack-unwinding semantics developers expect from nested resource acquisition. - Migration to `using` patterns requires careful attention to existing disposal timing contracts, especially in codebases where manual cleanup order encodes business logic or synchronization guarantees. ## The `using` and `await using` Keywords: Syntax and Symbol.dispose Fundamentals 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. ```typescript 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. ```typescript 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. ```mermaid sequenceDiagram participant Code participant Runtime participant Resource1 participant Resource2 Code->>Resource1: using r1 = acquire() Code->>Resource2: using r2 = acquire() Note over Code: Scope ends Runtime->>Resource2: Symbol.dispose() Resource2-->>Runtime: disposed Runtime->>Resource1: Symbol.dispose() Resource1-->>Runtime: disposed ``` 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 Pools: Implementing Disposable Connection Wrappers 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. ```typescript class DisposableConnection { private constructor( private conn: PoolConnection, private pool: Pool ) {} static async acquire(pool: Pool): Promise { const conn = await pool.connect(); return new DisposableConnection(conn, pool); } async query(sql: string, params?: unknown[]): Promise { return await this.conn.query(sql, params); } async [Symbol.asyncDispose]() { await this.pool.release(this.conn); } } async function fetchUsers(ids: number[]): Promise { 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. ```typescript class Transaction { private committed = false; private constructor( private conn: DisposableConnection, private pool: Pool ) {} static async begin(pool: Pool): Promise { const conn = await DisposableConnection.acquire(pool); await conn.query('BEGIN'); return new Transaction(conn, pool); } async query(sql: string, params?: unknown[]): Promise { return await this.conn.query(sql, params); } async commit(): Promise { 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 Handles and Stream Management: When `using` Beats try/finally 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. ```typescript class DisposableReadStream { private constructor(private stream: ReadStream) {} static open(path: string): DisposableReadStream { return new DisposableReadStream(createReadStream(path)); } async read(): Promise { 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. ```typescript 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((resolve, reject) => { this.stream.end((err) => { if (err) reject(err); else resolve(); }); }); } } async function writeReport(path: string, data: ReportData): Promise { 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. ```typescript 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 } ``` ## Async Disposal Patterns: Lock Management, Transaction Scopes, and Worker Threads 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. ```typescript class DistributedLock { private constructor( private key: string, private redis: Redis ) {} static async acquire(redis: Redis, key: string): Promise { 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 { await using lock = await DistributedLock.acquire(redis, `user:${userId}`); // Critical section here // Lock released here automatically } ``` ```mermaid flowchart LR A("Request arrives") B("await using lock = acquire()") C("Execute critical section") D("Scope ends") E("Lock released to redis") F("Next request unblocked") style B stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` 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. ```typescript class DisposableWorker { private constructor(private worker: Worker) {} static async spawn(script: string): Promise { const worker = new Worker(script); await new Promise((resolve) => worker.once('online', resolve)); return new DisposableWorker(worker); } async execute(task: Task): Promise { 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 { 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. ## Common Pitfalls: Early Returns, Nested Scopes, and Disposal Order Guarantees 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. ```typescript async function processItems(items: Item[]): Promise { 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. ```mermaid flowchart LR A("Start loop iteration") B("using lock = acquire()") C("Process item") D("Block ends") E("Lock released") F("Next iteration starts") style E stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` 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. ```typescript async function attemptOperation(): Promise { 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. ```typescript async function nestedResources(): Promise { 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. ```mermaid flowchart LR A("Declare resource A") B("Declare resource B") C("Scope ends") D("B disposes first") E("A disposes second") F("Order mismatch breaks correctness") style F stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` 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. ## Migration Strategy: Converting Existing Resource Code to `using` Without Breaking Production 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. ```mermaid flowchart LR A("Identify leaf resource") B("Implement Symbol.dispose") C("Deploy disposable wrapper") D("Convert call sites incrementally") E("Remove manual cleanup") style C stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` 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. ```typescript class MigrationConnection { private disposed = false; constructor(private conn: PoolConnection, private pool: Pool) {} async query(sql: string, params?: unknown[]): Promise { if (this.disposed) { throw new Error('Connection already disposed'); } return await this.conn.query(sql, params); } async release(): Promise { // 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. ```typescript // 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. ```typescript 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. ## Frequently Asked Questions ### Can `using` declarations appear in loops without causing disposal on each iteration? 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. ### Does `await using` block the event loop during disposal? 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. ### What happens when disposal itself throws an exception? 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. ### Can multiple `using` declarations reference the same resource instance? 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. ### Does TypeScript enforce that a class implements `Symbol.dispose` when used with `using`? 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. ## Conclusion: When to Reach for `using` and When Traditional Patterns Still Win 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.

Posts tagged “instrumentation”

Next.js 16 instrumentation.ts Is Stable: Wiring OpenTelemetry, Sentry, and Custom Spans Without a Wrapper