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().
import { AsyncResource } from 'node:async_hooks'; const resource = new AsyncResource('MyQueueItem'); resource.runInAsyncScope(() => { /* runs in the creator's context */ });
Try it
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.
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
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 passedrequireManualDestroy: true, and never call it twice. - Context vs identity:
AsyncLocalStoragevalues follow the resource, so a bound callback sees the store from where the resource was created. - For event emitters,
EventEmitterAsyncResourceis a ready-made subclass that gives eachemit()its own context. - Overhead: every resource adds hook work when hooks are enabled; do not create them for trivial synchronous callbacks.