Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท node:sqlite and Runtime Services

Node.js AsyncResource class

Reference for AsyncResource in node:async_hooks: runInAsyncScope, bind, asyncId and triggerAsyncId, for libraries that queue callbacks and must keep async context.

AsyncResource represents one unit of asynchronous work in your own code. Node tracks async context (for AsyncLocalStorage and async_hooks) automatically for its built-in operations. When a library keeps callbacks in its own queue or pool and calls them later, that tracking is lost, because the callback runs from the library's context, not the caller's.

Creating an AsyncResource when the callback is registered, then calling it with runInAsyncScope(), restores the context that was active at creation. It is a tool for library authors; application code usually uses AsyncLocalStorage.bind().

NODE
import { AsyncResource } from 'node:async_hooks';

const resource = new AsyncResource('MyQueueItem');
resource.runInAsyncScope(() => { /* runs in the creator's context */ });

Try it

Node.js A queue that keeps the caller's context

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js runInAsyncScope() and the resource ids

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new AsyncResource(type: string, options?: {
  triggerAsyncId?: number,
  requireManualDestroy?: boolean,
})
resource.runInAsyncScope<R>(fn: (...args) => R, thisArg?: any, ...args): R
resource.bind<F extends Function>(fn: F, thisArg?: any): F
AsyncResource.bind<F extends Function>(fn: F, type?: string, thisArg?: any): F
resource.asyncId(): number
resource.triggerAsyncId(): number
resource.emitDestroy(): this
Name Description
type A name for the kind of resource, used by async_hooks. Libraries conventionally prefix it with their package name.
options.triggerAsyncId The id of the execution that caused this resource. Defaults to the current execution id.
options.requireManualDestroy If true, the resource is not marked destroyed when it is garbage collected; you must call emitDestroy().
runInAsyncScope(fn, thisArg, ...args) Calls fn inside the resource's context and returns its result.
bind(fn) Returns a function that calls fn through runInAsyncScope().
emitDestroy() Marks the resource as finished and fires the destroy hook. Call it once.

Errors: a TypeError (ERR_INVALID_ARG_TYPE) if type is not a string or fn is not a function. Exceptions thrown by fn propagate.

Usage notes

  • Create the resource at registration time, where the right context is active, not at the moment the callback runs.
  • One resource can run its callback multiple times (for example an event listener); one resource per call is fine for one-shot callbacks.
  • AsyncResource.bind() is the shortcut for "create a resource and bind this function to it" and covers most library needs.
  • Destruction: by default the destroy hook fires when the object is garbage collected. Do not call emitDestroy() yourself unless you passed requireManualDestroy: true, and never call it twice.
  • Context vs identity: AsyncLocalStorage values follow the resource, so a bound callback sees the store from where the resource was created.
  • For event emitters, EventEmitterAsyncResource is a ready-made subclass that gives each emit() its own context.
  • Overhead: every resource adds hook work when hooks are enabled; do not create them for trivial synchronous callbacks.