Master Node.js Async Hooks: Decode Execution Contexts & Debug Async Tasks

Async execution in Node.js is fundamental, but an "Uncaught Exception" with ECONNRESET can be confusing.

[node:12345] Uncaught Exception: Error: read ECONNRESET
    at TLSWrap.onStreamRead (internal/stream_base_commons.js:111:27)
    // really gone

Asynchronous Continuation Model

Node.js uses a single‑threaded JavaScript execution model, simplifying many problems. To prevent I/O blocking the JavaScript thread, I/O operations are handed off to the background after a callback is attached. When the I/O completes, its callback is queued for execution in the JavaScript thread.

This model has many benefits but also a key challenge: managing the context of asynchronous resources and operations. The asynchronous context tells us why a particular async operation was triggered and what subsequent async operations it may trigger.

Key concepts:

Execution Frame – The period from when a successor function is pushed onto the call stack until that frame is popped. Not every function is a successor; a specific successor can be called multiple times, each creating an independent execution frame.

Continuation – A JavaScript function created inside an execution frame that will later be executed as an async callback. For example, setTimeout(function c(){}, 1000) calls setTimeout within a frame and passes c as the continuation. When the timer fires, a new execution frame for c begins, and when c finishes, that frame ends.

Continuation Point – A function that accepts another function as a parameter and invokes it asynchronously (e.g., setTimeout , Promise.then ). Not every function that receives a callback is a continuation point; the callback must be invoked later, not in the current frame (e.g., Array.prototype.forEach is not a continuation point).

Link Point – When a continuation point is called, a logical link is created between the current execution frame and the continuation, establishing context binding.

Ready Point – A previously linked continuation is marked as ready for execution. This usually occurs after a link point, but promises can create ready points earlier when they are resolved.

These concepts translate into the following events:

executionBegin : An execution frame starts.

link : A continuation point is called, linking a continuation to the queue.

ready : A ready point is triggered.

executionEnd : An execution frame finishes.

Example code illustrating the event flow:

console.log('starting');
Promise p = new Promise((reject, resolve) => {
  setTimeout(function f1() {
    console.log('resolving promise');
    resolve();
  }, 100);
});
p.then(function f2() {
  console.log('in then');
});

{ "event": "executionBegin", "executeID": 0 } // program start
{ "event": "link", "executeID": 0, "linkID": 1 } // f1 linked to setTimeout
{ "event": "link", "executeID": 0, "linkID": 2 } // f2 linked to p.then
{ "event": "executionEnd", "executeID": 0 } // outer code finished
{ "event": "ready", "executeID": 0, "linkID": 1, "readyID": 3 } // timer fires
{ "event": "executionBegin", "executeID": 4, "readyID": 3 } // f1 starts
{ "event": "ready", "executeID": 4, "linkID": 2, "readyID": 5 } // promise resolved
{ "event": "executionEnd", "executeID": 4 } // f1 ends
{ "event": "executionBegin", "executeID": 6, "readyID": 5 } // f2 starts
{ "event": "executionEnd", "executeID": 6 } // f2 ends

Existing Technology

async_hooks

The async_hooks module implements the model described above. Its API provides hooks for various async life‑cycle stages:

init(asyncId, type, triggerAsyncId, resource) – Called when an async resource (the async context) is initialized.

before(asyncId) – Called just before an async callback starts executing; any new async resources created inside the callback are linked to the current asyncId.

after(asyncId) – Called after the async callback finishes.

destroy(asyncId) – Called when the async resource is reclaimed.

Difference from domain

The deprecated domain module focuses on async error handling, while async_hooks only describes async resource events without providing error‑handling APIs. Because domain predates async_hooks, its semantics are vague and can lead to hard‑to‑debug errors. Modern Node.js implementations migrate domain functionality to use async_hooks (see PR link).

Node.js Add‑on Compatibility

C/C++ add‑ons that call napi_call_function are not automatically treated as new execution frames. To keep the async‑hooks chain intact, add‑ons should register async resources at the appropriate hook points. N‑API provides napi_threadsafe_function, which binds the callback to an async resource automatically.

#include <assert.h>
#include <node_api.h>

void async_call_js(napi_env env, napi_value js_callback, void* context, void* data) {
  napi_status status;
  // Convert data to a JavaScript value
  napi_value value = transform(env, data);
  napi_value recv;
  status = napi_get_null(env, &recv);
  assert(status == napi_ok);
  napi_value ret;
  status = napi_call_function(env, recv, js_callback, 1, &value, &ret);
  assert(status == napi_ok);
}

void do_work(napi_threadsafe_function tsfn) {
  /** work, work. */
  napi_status status = napi_call_threadsafe_function(tsfn, data, napi_tsfn_nonblocking);
  assert(status == napi_ok);
}

napi_value some_module_method(napi_env env, napi_callback_info info) {
  napi_status status;
  // Create a ThreadSafe Function bound to an AsyncResource
  napi_threadsafe_function tsfn;
  status = napi_create_threadsafe_function(env, func, async_resource, async_resource_name,
                                            max_queue_size, initial_thread_count,
                                            finalize_data, finalize_cb, context,
                                            call_js_cb, &tsfn);
  assert(status == napi_ok);
  // Create worker thread
  create_worker(tsfn, /** other args */);
  napi_value ret;
  status = napi_get_null(env, &ret);
  assert(status == napi_ok);
  return ret;
}

Use Cases

Async Task Scheduling

In unit tests, stray async tasks can leak the test’s execution frame, causing premature termination or affecting subsequent tests. By using async_hooks to track all async resources created during a test, we can detect dangling resources after the test finishes.

it('should wait for async test', () => {
  setTimeout(() => {
    Promise.resolve(0).then(() => {
      // only after this code executes will the test complete.
      console.log('wait for me');
    });
  }, 0);
});

const assert = require('assert');
const { createHook, AsyncLocalStorage } = require('async_hooks');

const als = new AsyncLocalStorage();
const backlog = new Map();
createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    const test = als.getStore();
    if (test === null) return;
    backlog.set(asyncId, { type, triggerAsyncId, resource });
  },
  destroy(asyncId) { backlog.delete(asyncId); },
  promiseResolve(asyncId) { backlog.delete(asyncId); }
}).enable();

const queue = [];
function test(name, callback) { queue.push({ name, callback }); }
function run() {
  if (queue.length === 0) return;
  const { name, callback } = queue.pop();
  als.run(name, async () => {
    try { await callback(); }
    finally {
      als.exit(() => {
        setImmediate(() => {
          assert(backlog.size === 0, `${name} ended with dangling async tasks.`);
          run();
        });
      });
    }
  });
}
process.nextTick(run);

/** test start */
test('foo', async () => {
  await new Promise(res => setTimeout(res, 100));
});

test('bar', async () => {
  setTimeout(res, 100);
  // Assertion fails: 'bar' ended with dangling async tasks.
});

This pattern registers an AsyncLocalStorage for each test, captures all async resources via async_hooks, and asserts that no resources remain after the test.

Async Call Stack / Performance Diagnosis

Traditional profiling tools only show synchronous call stacks. By stitching together async call stacks using async_hooks, developers can visualize the time spent in each async operation, generate flame graphs, or build APM‑style request tracing.

AsyncLocalStorage

Just as thread‑local storage holds data per thread, async_hooks.AsyncLocalStorage (introduced in Node.js v13.10.0) lets you store data that is scoped to the current asynchronous execution context, such as request‑specific information in an HTTP server.

Future Directions

Beyond Node.js, browsers also need richer async timeline diagnostics as JavaScript applications grow more complex. However, the async_hooks API exposes low‑level async resource properties that are powerful but not easy to use directly, so higher‑level abstractions are needed.

Links

Node.js Event Loop: https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/

Semantics of Asynchronous JavaScript: https://www.microsoft.com/en-us/research/wp-content/uploads/2017/08/NodeAsyncContext.pdf

Domain re‑implementation over async_hook: https://github.com/nodejs/node/pull/16222