Skip to content
Tutorials Center
My learning

Topics

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

Node.js AsyncLocalStorage class

Reference for AsyncLocalStorage in node:async_hooks: run, exit, getStore, enterWith, disable and the static bind and snapshot helpers for async context.

AsyncLocalStorage stores a value that follows the asynchronous flow of your program. You call als.run(store, fn), and inside fn, and in everything fn starts through promises, await, timers and callbacks, als.getStore() returns that same store. Code outside never sees it, and concurrent flows keep their own values.

It is how request-scoped data such as a correlation ID, the current user or a transaction handle can reach deep code without being passed as an argument. It is exported from node:async_hooks.

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

const als = new AsyncLocalStorage();
als.run({ id: 1 }, () => console.log(als.getStore()));

Try it

Node.js run(), getStore() and exit()

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 bind() and snapshot() keep context for later calls

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 AsyncLocalStorage()
als.run<R>(store: any, callback: (...args) => R, ...args): R
als.exit<R>(callback: (...args) => R, ...args): R
als.getStore(): any
als.enterWith(store: any): void
als.disable(): void
AsyncLocalStorage.bind<F extends Function>(fn: F): F
AsyncLocalStorage.snapshot(): <R>(fn: (...args) => R, ...args) => R
Name Description
run(store, fn, ...args) Calls fn with store active for it and everything it starts asynchronously. Returns the callback's result.
exit(fn, ...args) Calls fn with no store active, then restores the previous one.
getStore() The current store, or undefined when called outside run().
enterWith(store) Sets the store for the rest of the current synchronous execution and everything it starts, without a callback.
disable() Turns the instance off; getStore() returns undefined until run() or enterWith() is used again.
AsyncLocalStorage.bind(fn) Returns a function that always runs fn in the context captured at bind time.
AsyncLocalStorage.snapshot() Captures the current context of all instances; the returned function runs a callback inside it.

Errors: an exception thrown by the callback of run() or exit() propagates to the caller and the previous store is restored.

Usage notes

  • Create one instance per kind of context, usually at module level. Each instance holds one store at a time.
  • The store can be any value. Objects and Maps are common, so code can add fields during the flow. A primitive store cannot be mutated.
  • Prefer run() over enterWith(). enterWith() leaks the value into the remaining synchronous code of the caller, which makes control flow hard to follow.
  • Callbacks run later may lose context when a library queues them itself (connection pools, hand-written queues). Wrap them with AsyncLocalStorage.bind(), or use AsyncResource in the library.
  • Event emitters: a listener runs in the context of the code that calls emit(), not the code that called on(). Use bind() or EventEmitterAsyncResource to change that.
  • Performance cost is small but real. The context is propagated for every async operation; avoid creating huge numbers of instances.
  • Not tied to threads. A worker thread has its own, empty context.
  • Stable since Node.js 16.4.0; snapshot() and the static bind() arrived in later versions.