Cartwheel’s checkout reserves stock before charging a card, then releases the reservation if anything fails. The first version of that code looked like this:
\nfunction placeOrder(skus: string[]) {\n const reservations = skus.map((sku) => reserve(sku));\n chargeCard(); // throws on a declined card\n reservations.forEach((r) => r.release());\n}A declined card skips the last line, and the stock stays locked until a nightly job notices. The traditional fix is try/finally, nested once per resource. This lesson covers the language’s built-in answer, and then a second modern feature that keeps cross-cutting code like retries out of your business logic: standard decorators.
A using declaration is like const, with one addition: when the block it lives in exits, by return, by falling off the end, or by throw, JavaScript calls the value’s [Symbol.dispose]() method.
function reserve(sku: string): Disposable {\n log(`reserve ${sku}`);\n return { [Symbol.dispose]: () => log(`release ${sku}`) };\n}\n\nfunction placeOrder() {\n using tent = reserve('TENT-2P');\n using mug = reserve('MUG-SET');\n chargeCard(); // even if this throws…\n} // …both are released here: MUG-SET first, then TENT-2PSeveral using declarations are disposed in reverse order, exactly like nested finally blocks, so a resource is always released before the ones it was created after. If disposal itself throws while another error is in flight, both are kept in a SuppressedError rather than one silently replacing the other.
For cleanup that is asynchronous, such as closing a database transaction, use await using with an object that has [Symbol.asyncDispose]() returning a promise. And when the number of resources is dynamic, collect them in a DisposableStack (or AsyncDisposableStack), which is itself disposable:
function placeOrder(skus: string[]) {\n using stack = new DisposableStack();\n for (const sku of skus) stack.use(reserve(sku));\n chargeCard();\n} // every reservation released, in reverse orderusing arrived in TypeScript 5.2. It runs natively in Node 24, Chrome and Edge 134+ and Firefox 141+, but Safari does not support it yet (as of late 2026), so it is not Baseline. For code that ships to browsers, let TypeScript or your bundler downlevel the syntax, and make sure the runtime has Symbol.dispose (a polyfill provides it where it is missing). The types live in the esnext.disposable lib (included in "lib": ["esnext"]). The exercise playground uses the ES2022 lib, so its starter declares those two pieces itself, which is a preview of the declaration merging you will learn in the next lesson.
using pays off most when your own APIs return disposables. The emitter from Type-Safe Event Emitters and Builders returned an off function; returning an object with [Symbol.dispose] as well lets callers scope a subscription to a block:
function subscribe<K extends keyof CheckoutEvents>(event: K, handler: (p: CheckoutEvents[K]) => void): Disposable {\n const off = bus.on(event, handler);\n return { [Symbol.dispose]: off };\n}\n\nasync function waitForShipment(orderId: number) {\n using _ = subscribe('order.shipped', (e) => { if (e.orderId === orderId) notify(e); });\n await pollUntilShipped(orderId);\n} // listener removed here, however the function endsGood candidates are anything with a matching “undo”: locks and reservations, event subscriptions, timers, temporary files, database transactions (with await using). If you find yourself writing try/finally only to call a cleanup method, that resource wants a [Symbol.dispose].
A decorator is a function applied with @ to a class or class member. TypeScript 5.0 implemented the standard (TC39) decorators, and TypeScript compiles them down to ordinary function calls, so they run in any runtime. A method decorator receives the original method and a context object, and may return a replacement:
function logged<This, Args extends unknown[], Return>(\n method: (this: This, ...args: Args) => Return,\n context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,\n) {\n const name = String(context.name);\n return function (this: This, ...args: Args): Return {\n console.log(`→ ${name}`, args);\n return method.call(this, ...args);\n };\n}\n\nclass PaymentGateway {\n @logged\n charge(amountCents: number, currency: string) { /* … */ }\n}The generics make the decorator work on any method without any: This, Args and Return are inferred from the method it decorates, and the replacement keeps the same signature. Decorators that take options are decorator factories, functions that return the decorator:
function retry(times: number) {\n return function <This, Args extends unknown[], Return>(\n method: (this: This, ...args: Args) => Return,\n _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,\n ) {\n return function (this: This, ...args: Args): Return {\n for (let attempt = 1; ; attempt++) {\n try {\n return method.call(this, ...args);\n } catch (e) {\n if (attempt >= times) throw e;\n }\n }\n };\n };\n}\n\nclass PaymentGateway {\n @retry(3)\n charge(amountCents: number, currency: string) { /* … */ }\n}Stacked decorators apply from the bottom up. With @logged above @retry(3), the retry wrapper is applied to charge first and logged wraps the result, so you get one log line per call rather than one per attempt. Swap them and you log every attempt. Neither is wrong, but the order is behaviour, so choose it on purpose.
context also offers context.name, context.static, context.private and context.addInitializer(fn), which runs code when an instance is created (the usual way to write a @bound decorator that binds a method to its instance).
In the exercise you will release stock reservations with using and add a typed @retry to Cartwheel’s payment gateway. Next lesson: describing code you did not write, with declaration files.
using declaration calls the value’s [Symbol.dispose]() when the enclosing block exits, whether it returns normally or throws.","Several using declarations in one block are disposed in reverse order, like nested try/finally blocks.","await using and Symbol.asyncDispose do the same for cleanup that returns a promise.","Standard decorators (TypeScript 5.0+) are functions of (value, context) that can return a replacement; they are not the same as the older experimentalDecorators.","Type a method decorator with ClassMethodDecoratorContext and generic This, Args and Return parameters so it works on any method without any."],"further":[{"title":"using declarations (TypeScript 5.2 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html"},{"title":"Decorators (TypeScript 5.0 release notes)","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html"},{"title":"using (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using"}],"quiz":[{"q":"What does this log?
\nfunction checkout() {\n using a = reserve('TENT-2P'); // logs \"reserve TENT-2P\", disposes with \"release TENT-2P\"\n using b = reserve('MUG-SET'); // logs \"reserve MUG-SET\", disposes with \"release MUG-SET\"\n throw new Error('card declined');\n}\ntry { checkout(); } catch {}finally blocks, so b is released before a."},{"text":"reserve TENT-2P, reserve MUG-SET (nothing is released because the function threw)","why":"Releasing on every exit path, including throws, is the whole point of using."},{"text":"Nothing; using cannot be combined with throw in the same block.","why":"There is no such restriction; a throw is one of the exits using is designed for."}],"answer":0},{"q":"Which value can be bound with using?
close() method.","why":"using does not look for close(); it calls the method stored under Symbol.dispose."},{"text":"An object with a [Symbol.dispose]() method, or null/undefined.","why":"Correct. The value must be disposable; null and undefined are allowed and simply skipped."},{"text":"Only instances of DisposableStack.","why":"DisposableStack is a helper for collecting disposables, not a requirement."}],"answer":1},{"q":"How does a standard method decorator receive the method it decorates?
","options":[{"text":"As(target, propertyKey, descriptor), and it modifies the descriptor.","why":"That is the legacy experimentalDecorators signature. Standard decorators receive (value, context)."},{"text":"As a string name, and it looks the method up on this.","why":"The method itself is passed in as the first argument; the name is available on context.name."},{"text":"As (value, context), where value is the method and the decorator may return a replacement function.","why":"Correct. Returning a new function replaces the method, which is how logging and retry decorators work."}],"answer":2},{"q":"Your codebase uses NestJS-style parameter decorators like constructor(@Inject(TOKEN) svc). What does that mean for your tsconfig?
"experimentalDecorators": true, which switches the whole project to the legacy decorator semantics.","why":"Correct. The two systems cannot be mixed in one compilation; frameworks built on the legacy model need the flag."},{"text":"You must set "target": "esnext" so the runtime handles them.","why":"The target does not change which decorator system TypeScript uses; the flag does."},{"text":"You must enable emitDecoratorMetadata alone.","why":"That option only works together with experimentalDecorators; on its own it does nothing for parameter decorators."}],"answer":1}],"exercise":{"kind":"web","mode":"ts","starter":{"ts":"// ---- Playground shim (do not edit) ----\n// The playground's lib is ES2022. These lines add what lib.esnext.disposable\n// would declare, and make sure Symbol.dispose exists at runtime.\ninterface SymbolConstructor { readonly dispose: unique symbol; }\ninterface Disposable { [Symbol.dispose](): void; }\n(Symbol as { dispose?: symbol }).dispose ??= Symbol.for('Symbol.dispose');\n// ----------------------------------------\n\nconst events: string[] = [];\n\nfunction reserve(sku: string) {\n events.push(`reserve ${sku}`);\n return { sku, release: () => events.push(`release ${sku}`) };\n}\n\nclass PaymentGateway {\n calls = 0;\n failuresLeft: number;\n\n constructor(failures: number) {\n this.failuresLeft = failures;\n }\n\n // Should be retried up to 3 times in total.\n charge(amountCents: number): string {\n this.calls++;\n if (this.failuresLeft > 0) {\n this.failuresLeft--;\n throw new Error('Gateway timeout');\n }\n events.push(`charge ${amountCents}`);\n return `receipt-${amountCents}`;\n }\n}\n\nfunction placeOrder(skus: string[], gateway: PaymentGateway): string {\n const reservations = skus.map((sku) => reserve(sku));\n const receipt = gateway.charge(skus.length * 1000);\n reservations.forEach((r) => r.release());\n return receipt;\n}\n\n// ---- Type tests (do not edit) ----\ntype T1 = ExpectTwo fixes for Cartwheel’s checkout:
\nreserve return a disposable (with a [Symbol.dispose] method that logs release <sku> instead of a release method), and rewrite placeOrder with using so every reservation is released when the function exits, in reverse order, even when the charge throws.retry(times) and apply @retry(3) to PaymentGateway.charge, so a charge that throws is attempted up to 3 times in total before the error propagates. Keep charge’s signature intact.The top of the file declares Symbol.dispose and Disposable, because the playground uses the ES2022 lib. DisposableStack is not available here; if you need one, write a small class of your own.
using r = reserve('A'); releases r at the end of the block. For a dynamic list of SKUs, collect the disposables in a small class with a use(item) method and a [Symbol.dispose]() that disposes them in reverse.","A standard method decorator has the shape (method, context: ClassMethodDecoratorContext<This, …>) => replacementFunction. A factory is a function that returns one: function retry(times: number) { return function <This, Args extends unknown[], Return>(method, context) { … } }.","Inside the replacement, loop: try { return method.call(this, ...args); } catch (e) { if (attempt >= times) throw e; }."],"explanation":"using ties a resource’s lifetime to a block: whatever way placeOrder exits, the stack is disposed, and it disposes reservations last-in, first-out, so the starter’s leak on a declined charge is gone. The decorator factory captures times and returns a standard method decorator; the generic This, Args and Return are inferred from charge, so the replacement keeps its exact signature (the T2 test) and calls the original with method.call(this, ...args). The retry logic now lives in one reusable place instead of inside the payment code.
charge succeeds on the third attempt after two failures","gives-up":"charge gives up and rethrows after 3 attempts"}},"words":748,"readMinutes":4}