AsyncLocalStorage

AsyncLocalStorage is a class in Node.js's async_hooks module that provides a way to associate data with the current asynchronous execution context and access that data from any point within the same chain of asynchronous calls. It is commonly used to implement per-request or per-operation context, such as correlation IDs or logging context, that must survive across asynchronous boundaries.

The API centers on an AsyncLocalStorage instance. You create one with new AsyncLocalStorage(), and you interact with it mainly through run and getStore. The run method takes a store value and a callback, and any asynchronous work started within that callback (and its descendants) can retrieve the same store by calling getStore(). The enterWith method can set the current store in the calling context without starting a new callback. The store itself can be any object, commonly a Map or plain object.

Example usage in plain terms: const als = new AsyncLocalStorage(); als.run(new Map([['requestId', '123']]), () => { // within this chain const reqId = als.getStore().get('requestId'); setTimeout(() => console.log(reqId)); }); In server frameworks like Express, a middleware can initialize the store and propagate it through asynchronous operations, enabling consistent access to contextual data across handlers and callbacks.

Limitations include that AsyncLocalStorage does not automatically propagate across worker threads or separate processes, and some libraries that create new execution contexts may affect consistency. It also requires careful management to avoid memory leaks by storing only small, relevant data and clearing it when the context ends.

---