Asynchronous Context Tracking in Node.js

1. AsyncLocalStorage

The AsyncLocalStorage class creates storage that remains consistent across asynchronous operations. It is the recommended way to manage context because it is performant and memory-safe compared to custom implementations.

Example: Request Logger

const { AsyncLocalStorage } = require('node:async_hooks');
const http = require('node:http');

const asyncLocalStorage = new AsyncLocalStorage();

function logWithId(msg) {
  const id = asyncLocalStorage.getStore();
  console.log(`${id !== undefined ? id : '-'}:`, msg);
}

let idSeq = 0;
http.createServer((req, res) => {
  asyncLocalStorage.run(idSeq++, () => {
    logWithId('start');
    setImmediate(() => {
      logWithId('finish');
      res.end();
    });
  });
}).listen(8080);

Each instance of AsyncLocalStorage maintains its own independent context, so multiple instances can coexist safely.

2. Key AsyncLocalStorage Methods

• run(store, callback): Runs a function within a given context.
• getStore(): Retrieves the current store.
• enterWith(store): Enters a context for synchronous execution.
• exit(callback): Exits the context and runs a function outside of it.
• disable(): Disables the instance for garbage collection.
• bind(fn) and snapshot(): Bind or capture the current context.

3. AsyncResource

The AsyncResource class is designed to be extended for custom asynchronous resources. It allows developers to trigger lifecycle events and associate operations with the correct execution context.

Key Features:

• runInAsyncScope(fn, thisArg, ...args): Executes a function in the resource’s context.
• emitDestroy(): Calls destroy hooks.
• asyncId(): Returns the unique ID of the resource.
• triggerAsyncId(): Returns the ID of the resource that created it.

Example:

class DBQuery extends AsyncResource {
  constructor(db) {
    super('DBQuery');
    this.db = db;
  }

  getInfo(query, callback) {
    this.db.get(query, (err, data) => {
      this.runInAsyncScope(callback, null, err, data);
    });
  }

  close() {
    this.db = null;
    this.emitDestroy();
  }
}

4. Worker Pool Example

AsyncResource can be used to track tasks in a Worker pool, ensuring callbacks are correctly associated with tasks rather than worker creation.

class WorkerPoolTaskInfo extends AsyncResource {
  constructor(callback) {
    super('WorkerPoolTaskInfo');
    this.callback = callback;
  }

  done(err, result) {
    this.runInAsyncScope(this.callback, null, err, result);
    this.emitDestroy();
  }
}

This model can be applied to database connection pools or other resource pools.

5. Integration with EventEmitter

EventEmitter listeners may run in a different context than the one active when on() was called. Using AsyncResource.bind() ensures listeners run in the correct context.

req.on('close', AsyncResource.bind(() => {
  // Execution context bound correctly
}));

Conclusion

The async_hooks module in Node.js is a powerful tool for managing asynchronous contexts. With AsyncLocalStorage and AsyncResource, developers can propagate state across async operations, build custom resources, and prevent context loss. These capabilities are vital for building scalable and reliable web applications.