[raon0211]

Closes #2011

Summary

Implements defer and deferAsync proposed in #2011. They wrap a cleanup callback in a Disposable / AsyncDisposable object, so cleanup code registered with using / await using declarations (Explicit Resource Management) runs when the enclosing scope exits, even on errors.

import { defer, deferAsync } from 'es-toolkit/util';

function processFile() {
  const file = openFile('data.txt');
  using cleanup = defer(() => file.close());
  return file.read(); // file is closed on return or throw
}

async function main() {
  const connection = await connect();
  await using cleanup = deferAsync(() => connection.close());
  await connection.query('SELECT 1');
}

They live in es-toolkit/util, next to attempt / attemptAsync: language-level control-flow helpers that come as a sync/async pair and fit no data-type category. function transforms functions into functions, and promise coordinates promises, so neither fits — defer returns a Disposable, not a function or a promise.

On the "replaceable by TC39 Stage 3+" principle: the proposal's own DisposableStack#defer covers this, but using cleanup = defer(fn) is far more ergonomic than allocating a stack for a single callback, and DisposableStack is still missing from most runtimes, while these helpers only need the Symbol.dispose well-known symbols that transpiled using requires anyway.

Changes

• Add src/util/defer.ts and src/util/deferAsync.ts with specs; re-export from src/util/index.ts (the root barrel picks them up via export *).
• Docs in all four languages under reference/util/.
• tests/browser-compat/skip-list.json: override the two JSDoc examples to dispose via Symbol.dispose / Symbol.asyncDispose directly, since no browser in the matrix (Chrome 51/80/98, WebKit 14.1/15.4) parses using declarations. The node-check completeness gate passes with the overrides (1386/1386 locally).

Notes

• The spec files also call [Symbol.dispose]() directly instead of using using declarations: Prettier 3.2.5 (current devDependency) cannot parse the syntax, which breaks yarn lint on those files. Once Prettier is bumped to ≥ 3.3, the tests can be rewritten with literal using blocks.
• No benchmark is included: lodash has no counterpart, same as mutex / semaphore.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
es-toolkit	Ready	Preview	Aug 17, 2026 10:45am