0Pricing
Node.js Backend Development Bootcamp · Lezione

Propagazione del contesto con AsyncLocalStorage

Trasporti lo stato relativo alla richiesta oltre i confini asincroni senza prop drilling, usando AsyncLocalStorage.

Propagazione del contesto con AsyncLocalStorage è una lezione Node.js Backend Development Bootcamp gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Node.js Backend Development Bootcamp, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Node.js Backend Development Bootcamp include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

The Prop-Drilling Problem

In a backend service, request-scoped data such as a request ID, the authenticated user, or a tenant ID is needed deep inside your call stack: in repositories, loggers, and outbound HTTP clients.

The naive fix is prop drilling — threading a ctx argument through every function:

  • Every function signature gets polluted with a ctx parameter.
  • One missed hand-off and a downstream call loses context.
  • Library code you don't own can't receive your ctx at all.

We need a way to carry per-request state implicitly, surviving every await and callback. That is exactly what AsyncLocalStorage provides.

async function handler(ctx, req) {
  const user = await loadUser(ctx, req.userId);
  return await renderPage(ctx, user);
}

async function loadUser(ctx, id) {
  log(ctx, 'loading user');         // ctx passed again
  return await db.find(ctx, id);    // and again...
}

// Every layer must accept and forward ctx by hand.

What AsyncLocalStorage Is

AsyncLocalStorage lives in the built-in node:async_hooks module. Think of it as thread-local storage for the async world: a store that stays attached to a logical chain of asynchronous operations.

You call als.run(store, callback) to establish a store, then anywhere inside that callback — no matter how many awaits, Promise chains, setTimeouts, or event emitters deep — als.getStore() returns the same store.

  • Each concurrent request gets its own isolated store.
  • No globals, no race conditions between requests.
  • Powered by Node's async context tracking under the hood.
import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

als.run({ requestId: 'abc-123' }, () => {
  setTimeout(() => {
    const store = als.getStore();
    console.log(store.requestId); // 'abc-123'
  }, 10);
});

run() Establishes a Context

The core API is als.run(store, fn, ...args). It executes fn synchronously, but binds store to the entire async tree spawned from it.

  • The store can be any value — most often a plain object or a Map.
  • run() returns whatever fn returns (including a Promise).
  • Outside the callback, getStore() returns undefined.

This snippet shows that the store survives across an await on a real timer.

import { AsyncLocalStorage } from 'node:async_hooks';
import { setTimeout as sleep } from 'node:timers/promises';

const als = new AsyncLocalStorage();

async function deep() {
  await sleep(5);
  return als.getStore()?.requestId;
}

await als.run({ requestId: 'r-42' }, async () => {
  const id = await deep();
  console.log('inside run:', id);   // 'r-42'
});

console.log('outside run:', als.getStore()); // undefined

Wiring It Into an HTTP Server

The pattern in a real server: wrap the per-request work in als.run() at the very edge, seeding the store with a fresh request ID. Everything downstream can then read it.

Below uses only the built-in node:http module, so there is no framework dependency. Each incoming request gets its own store, isolated from concurrent requests.

import http from 'node:http';
import { randomUUID } from 'node:crypto';
import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

function currentRequestId() {
  return als.getStore()?.requestId ?? 'no-context';
}

const server = http.createServer((req, res) => {
  als.run({ requestId: randomUUID() }, async () => {
    // deep call needs no ctx argument
    await Promise.resolve();
    res.end('request id: ' + currentRequestId());
  });
});

server.listen(3000, () => console.log('listening on 3000'));

Express Middleware Pattern

In Express the idiomatic place to call als.run() is a middleware mounted first. It must call next() inside the callback so the rest of the chain inherits the store.

  • Read an incoming x-request-id header if a proxy or upstream service supplied one; otherwise generate a fresh UUID.
  • Every later handler, service, and logger can read the store without receiving it as an argument.
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

export const als = new AsyncLocalStorage();

export function contextMiddleware(req, res, next) {
  const store = {
    requestId: req.headers['x-request-id'] || randomUUID(),
    startedAt: Date.now(),
  };
  als.run(store, () => next()); // next() runs inside the context
}

export function getStore() {
  const store = als.getStore();
  if (!store) throw new Error('No request context');
  return store;
}

Context-Aware Structured Logging

The biggest payoff: a logger that automatically stamps every line with the request ID — no caller ever passes it.

The logger reads the store itself. If there is no active context (e.g. startup code), it degrades gracefully.

import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

function log(level, msg, extra = {}) {
  const store = als.getStore();
  const line = {
    ts: new Date().toISOString(),
    level,
    msg,
    requestId: store?.requestId ?? null,
    ...extra,
  };
  console.log(JSON.stringify(line));
}

als.run({ requestId: 'req-7' }, () => {
  log('info', 'user fetched', { userId: 99 });
});

log('warn', 'no request context here');

Mutating the Store Mid-Request

Because the store is a reference (object or Map), you can enrich it after authentication resolves. Later log lines automatically pick up the new fields.

  • Seed with minimal data at the edge (request ID).
  • After auth middleware runs, attach userId and tenantId to the same store object.
  • Prefer a Map if you want a clear key-based API; a plain object is fine and slightly faster.
import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

function set(key, value) {
  const store = als.getStore();
  if (store) store.set(key, value);
}
function get(key) {
  return als.getStore()?.get(key);
}

als.run(new Map([['requestId', 'r-1']]), () => {
  // ... later, after authenticating:
  set('userId', 42);
  set('tenantId', 'acme');
  console.log(get('requestId'), get('userId'), get('tenantId'));
});

enterWith vs run

There are two ways to set a store:

  • als.run(store, fn) — scopes the store to fn and its async descendants. When fn settles, the context is gone. Prefer this.
  • als.enterWith(store) — sets the store for the current sync execution and everything after it in the same async resource, with no automatic exit.

enterWith is sharp: if you call it in a long-lived async resource it can leak into unrelated later work. Use run unless you have a specific reason (e.g. you cannot wrap a callback).

import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

// Scoped and safe — context ends with the callback:
als.run({ id: 'A' }, () => {
  console.log(als.getStore().id); // 'A'
});
console.log(als.getStore());      // undefined

// enterWith persists with no clear boundary — easy to leak:
als.enterWith({ id: 'B' });
console.log(als.getStore().id);   // 'B' (and stays set!)

Where Context Can Break

AsyncLocalStorage follows native promises, async/await, timers, and most event emitters. But context can be lost in a few situations:

  • Work scheduled before run() — e.g. a connection pool or queue created at startup runs its callbacks outside any request store.
  • Some older libraries that pool or reuse resources across requests can carry a stale store.
  • Manually detached callbacks stored in a global array and invoked later.

The fix when integrating such code is als.bind(fn) (or AsyncResource.bind), which snapshots the current context and re-applies it whenever the function is later called.

import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();
const queue = [];

als.run({ requestId: 'r-9' }, () => {
  // bind captures the current store for later execution
  queue.push(als.bind(() => {
    console.log('later:', als.getStore()?.requestId);
  }));
});

// Runs outside the run() callback, but context is preserved:
queue.forEach((fn) => fn()); // later: r-9

A Reusable Context Module

In practice you centralize the store in one small module so the rest of the codebase only imports helpers — never touching the AsyncLocalStorage instance directly.

This keeps the API tidy: runWithContext() at the edge, requestId() / getUser() everywhere else.

import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

const als = new AsyncLocalStorage();

export function runWithContext(seed, fn) {
  const store = { requestId: randomUUID(), ...seed };
  return als.run(store, fn);
}

export function context() {
  return als.getStore() ?? null;
}

export function requestId() {
  return context()?.requestId ?? null;
}

export function setUser(user) {
  const store = als.getStore();
  if (store) store.user = user;
}

Performance & Good Hygiene

AsyncLocalStorage in modern Node (v16+) is backed by an efficient native implementation and the overhead is small — acceptable for virtually all web workloads. Still, follow some hygiene:

  • Use one long-lived AsyncLocalStorage instance per concern, not one per request.
  • Keep the store small; it is request-scoped state, not a cache.
  • Don't store secrets you wouldn't want appearing in logs that read the store.
  • Prefer run() over enterWith() to get automatic cleanup.
  • Always handle the undefined store case for code that may run outside a request.

Quick Check

Test your understanding of how to establish request context safely.

Recap

You learned how to propagate request-scoped state across async boundaries without prop drilling:

  • AsyncLocalStorage from node:async_hooks is thread-local storage for the async world.
  • als.run(store, fn) binds a store to fn and all its async descendants; als.getStore() reads it anywhere; outside the run it is undefined.
  • Wire it once at the edge (HTTP server or first middleware), seeding a request ID, then enrich the store after auth.
  • A context-aware logger can stamp every line with the request ID automatically.
  • Prefer run() over enterWith() for automatic cleanup, and use als.bind() / AsyncResource.bind() to preserve context across detached callbacks.
  • Keep the store small, handle the no-context case, and centralize access in one module.

Domande Frequenti

La lezione «Propagazione del contesto con AsyncLocalStorage» è gratuita?

Sì — il testo completo di «Propagazione del contesto con AsyncLocalStorage» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Node.js Backend Development Bootcamp, passa a CoddyKit PRO. Il corso Node.js Backend Development Bootcamp include 4 lezioni in totale.

Cosa imparerò in «Propagazione del contesto con AsyncLocalStorage»?

Trasporti lo stato relativo alla richiesta oltre i confini asincroni senza prop drilling, usando AsyncLocalStorage. Eserciti Node.js Backend Development Bootcamp con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Node.js Backend Development Bootcamp?

Non è richiesta alcuna esperienza precedente. Node.js Backend Development Bootcamp su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Propagazione del contesto con AsyncLocalStorage»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Node.js Backend Development Bootcamp?

Sì. Ogni lezione Node.js Backend Development Bootcamp include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Logging strutturato con ID di correlazione
  2. Distributed tracing con gli span di OpenTelemetry
  3. Esposizione delle metriche applicative e metodo RED
  4. Propagazione del contesto con AsyncLocalStorage
← Torna a Node.js Backend Development Bootcamp