Implicitly Passing Context in Node.js with AsyncHooks

Introduction

We all know Node.js is single‑process, asynchronous, and event‑driven. When our code encounters an asynchronous call, a callback function is passed and executed after the async operation completes. A typical user login flow looks like this:

In a real online environment, multiple users may log in simultaneously. The scenario is illustrated below:

Assuming database operations are the most time‑consuming, when user A’s request arrives and waits for a DB query, user B may issue a login request. Adding a timeline yields the following diagram:

If each request is treated as an independent context, the diagram shows three context switches:

First switch: events 2 and 3, from user A to user B

Second switch: events 4 and 5, from user B back to user A

Third switch: events 5 and 6, from user A again to user B

How do web frameworks such as Express or Egg help us identify these context switches?

Express wraps each request in a Request object, passed as the first argument to the callback.

Egg encapsulates a Context object, creating a new Context for each request.

These approaches explicitly create a local variable that is passed through the call stack, making context identification straightforward. Is there a way to pass context implicitly?

Implicit Context Passing

In Node.js, synchronous code does not cause context switches; only asynchronous callbacks can. To implicitly pass context, we first need to automatically detect asynchronous callbacks. Starting with Node.js 8.1, the AsyncHooks API provides this capability.

AsyncHooks

AsyncHooks offers four core hooks:

init

,

before

,

after

, and

destroy

.

init

fires when an asynchronous resource is created and ready.

before

runs just before the async callback is invoked.

after

runs immediately after the async callback finishes.

destroy

runs when the async resource is destroyed.

Two examples illustrate the hooks:

fs.open

– the

init

hook triggers when the file resource is ready.

net.createServer

–

init

fires when the server starts listening;

before

fires before each incoming request’s callback (e.g.,

createServer

).

Beyond the hooks, AsyncHooks provides two important IDs:

triggerAsyncId

and

asyncId

, which express the parent‑child relationship between asynchronous calls.

Tracing Context

Combining AsyncHooks with the earlier login example, we can map each async operation to its

triggerAsyncId

and

asyncId

values:

The sequence of IDs is roughly:

(1) User A sends HTTP request –

triggerAsyncId

: 0,

asyncId

: 1

(2) User A initiates DB query –

triggerAsyncId

: 1,

asyncId

: 2

(3) User B sends HTTP request –

triggerAsyncId

: 0,

asyncId

: 3

(4) User B initiates DB query –

triggerAsyncId

: 3,

asyncId

: 4

(5) User A writes session –

triggerAsyncId

: 2,

asyncId

: 5

(6) User B writes session –

triggerAsyncId

: 4,

asyncId

: 6

Note: This simplifies the real asynchronous calls for illustration.

Using the hooks and the ID relationship, we can retrieve the originating context of any asynchronous call. A complete implementation can be found in the

cls-hooked

library.

Why Isn’t This Widely Adopted?

Frederick Brooks warned that there is no silver bullet in software engineering. The limited adoption of implicit context propagation stems mainly from two reasons:

Implicit passing reduces code readability and hampers maintainability.

AsyncHooks incurs noticeable performance overhead, and its API stability is still experimental.

Conclusion

This article introduced AsyncHooks from the perspective of an asynchronous context scenario, covering its core API, basic usage, and how it enables implicit context tracking. Many APM tools leverage similar capabilities. While we did not dive deep into implementation details, the goal is to familiarize readers with the concepts.