Mantendo o Contexto Entre Chamadas Assíncronas no Node.js

Você está três chamadas assíncronas dentro do tratamento de uma requisição HTTP. Precisa do request ID para o seu logger, do user ID para a sua consulta ao banco de dados e do tenant ID para a sua chave de cache. Você passa todos eles por cada assinatura de função? Isso fica bagunçado rapidamente.

O Node.js tem uma solução elegante já embutida: AsyncLocalStorage.

O Problema da Propagação de Contexto Assíncrono

Em código síncrono, é possível usar uma simples pilha global para rastrear o contexto. Mas funções assíncronas quebram esse modelo. Quando um setTimeout dispara ou uma Promise é resolvida, a pilha de chamadas original já não existe. Uma variável global comum seria compartilhada entre todas as requisições concorrentes — um bug sério à espera de acontecer em qualquer servidor de API real.

Antes de AsyncLocalStorage se tornar estável, desenvolvedores recorriam a bibliotecas como cls-hooked ou a soluções caseiras utilizando o módulo de baixo nível async_hooks. Ambas as abordagens são frágeis. A API bruta de async_hooks é intencionalmente de baixo nível e traz um custo real de desempenho quando mal utilizada. Você não deveria construir aplicações diretamente sobre ela.

AsyncLocalStorage, parte de node:async_hooks, é a API de alto nível recomendada. Está estável desde o Node.js 16.4.0 e é o que frameworks como o AdonisJS utilizam internamente para gerenciar o contexto HTTP.

Como o AsyncLocalStorage Funciona

O AsyncLocalStorage funciona como o thread-local storage de outras linguagens — exceto que o Node.js é single-threaded, então a “thread” é substituída por um contexto de execução assíncrono. Qualquer operação assíncrona iniciada dentro de uma chamada run() herda esse contexto automaticamente, incluindo setTimeout, cadeias de Promise e chamadas await.

import { AsyncLocalStorage } from 'node:async_hooks';

const requestContext = new AsyncLocalStorage();

Você cria uma instância (tipicamente como um singleton em nível de módulo) e então usa run() para estabelecer um contexto no ponto de entrada de cada requisição.

Um Exemplo Realista de Logging por Requisição

Aqui está um middleware Express mínimo que anexa um request ID a cada linha de log — sem passar nada através de argumentos de função:

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

const requestContext = new AsyncLocalStorage();

// Middleware: establish context for each request
function contextMiddleware(req, res, next) {
  const store = { requestId: randomUUID(), userId: req.headers['x-user-id'] };
  requestContext.run(store, next);
}

// Logger: reads context without any arguments
function log(message) {
  const ctx = requestContext.getStore();
  const prefix = ctx ? `[${ctx.requestId}]` : '[no-context]';
  console.log(`${prefix} ${message}`);
}

// Simulated async database query
async function someDbQuery() {
  return new Promise((resolve) => setTimeout(resolve, 50));
}

// Route handler: calls async functions freely
async function fetchUserData() {
  log('Fetching user data');         // ✅ has request ID
  await someDbQuery();
  log('Fetched user data');          // ✅ still has request ID
}

const app = express();
app.use(contextMiddleware);

app.get('/user', async (req, res) => {
  log('Request received');
  await fetchUserData();
  res.json({ ok: true });
});

app.listen(3000);

O insight principal: fetchUserData nunca recebe o request ID como parâmetro. O contexto se propaga automaticamente através da fronteira assíncrona porque foi estabelecido com run().

O Que Armazenar no Contexto

AsyncLocalStorage funciona bem para preocupações transversais que sejam específicas da requisição, mas não façam parte da sua lógica de negócio:

• Request IDs para tracing distribuído e correlação de logs
• Metadados de usuário autenticado ou tenant para aplicações multi-tenant
• Contexto de trace para ferramentas como o OpenTelemetry
• Feature flags resolvidas em tempo de requisição

Evite armazenar objetos grandes ou qualquer coisa que mude com frequência. Mantenha o store pequeno e trate-o como majoritariamente apenas para leitura após a inicialização.

Um Detalhe: Perda de Contexto

O contexto pode ser perdido ao utilizar implementações de promises não nativas ou algumas APIs antigas baseadas em callbacks. Se getStore() retornar undefined onde você não esperaria, verifique se a operação assíncrona foi iniciada dentro de uma chamada run(). Envolver código baseado em callbacks com util.promisify() frequentemente ajuda, embora alguns recursos assíncronos customizados possam exigir o uso de AsyncResource.

Conclusão

AsyncLocalStorage resolve um problema real de forma elegante. Em vez de passar metadados da requisição por cada chamada de função, você estabelece o contexto uma vez na fronteira da requisição e o lê onde for necessário. É a ferramenta certa para logging por requisição, tracing e contexto de autenticação em qualquer API Node.js ou aplicação SSR.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.