AsyncContext

Async context propagation and structured logging for Node.js, with first-class framework integrations.

AsyncContext helps you carry contextual data across asynchronous boundaries without passing parameters through every function. It provides a Context wrapper around AsyncLocalStorage, ready-made middleware for popular frameworks, and a structured logger that automatically includes the active context in every log entry.

Highlights

• Consistent per-request context without parameter threading.
• Simple, direct API for reading and writing context anywhere in the async flow.
• Observability-ready with correlation IDs, tenant/user data, and tracing metadata.
• Full-featured logger with levels, redaction, sampling, timers, and transports.
• DX-friendly configuration via presets and environment variables.
• Zero runtime dependencies and performance-focused design.

Installation

npm i @marceloraineri/async-context

Quick start

import crypto from "node:crypto";
import { Context } from "@marceloraineri/async-context";

await Context.run({ requestId: crypto.randomUUID() }, async () => {
  Context.addValue("user", { id: 42, name: "Ada" });
  Context.addOptions({ feature: "beta", retry: 2 });

  await Promise.resolve();

  const store = Context.getStore();
  console.log(store?.requestId); // 184fa9a3-f967-4a98-9d8f-57152e7cbe64
  console.log(store?.user); // { id: 42, name: "Ada" }
  console.log(store?.options); // { feature: "beta", retry: 2 }
});

Structured logging

The logger automatically merges the active async context and supports redaction, sampling, timers, and JSON or pretty output.

import crypto from "node:crypto";
import { Context, createLogger } from "@marceloraineri/async-context";

const logger = createLogger({
  name: "api",
  level: "info",
  contextKey: "ctx",
  redactKeys: ["ctx.token", "data.password"],
});

await Context.run({ requestId: crypto.randomUUID(), token: "secret" }, async () => {
  logger.info("request started", { route: "/ping" });
});

By default, common sensitive keys (for example password, token, authorization) are automatically redacted. You can disable this with redactDefaults: false or add extra key names with redactFieldNames.

Timers and child loggers

import { createLogger } from "@marceloraineri/async-context";

const logger = createLogger({ name: "jobs", level: "debug" });
const jobLogger = logger.child({ job: "import-users" });

const end = jobLogger.startTimer("debug");
await Promise.resolve();
end("job completed");

const noisyLogger = logger.child({ job: "debug-import" }, { level: "trace" });
noisyLogger.trace("verbose logging enabled");

JSON output or custom transports

import { createConsoleTransport, createLogger } from "@marceloraineri/async-context";

const logger = createLogger({
  level: "info",
  transports: [createConsoleTransport({ format: "json" })],
});

logger.info("structured log", { feature: "json" });

OpenAI wrapper

Capture OpenAI call metadata inside the current async context.

import OpenAI from "openai";
import { Context, withOpenAIContext } from "@marceloraineri/async-context";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

await Context.run({ requestId: "req_123" }, async () => {
  const response = await withOpenAIContext(
    "responses.create",
    { model: "gpt-4o", input: "Hello!" },
    (req) => openai.responses.create(req),
    { includeRequest: true }
  );

  console.log(response.id);
  console.log(Context.getValue("openai"));
});

By default, the wrapper appends summaries to the openai context key, and only includes safe request fields unless you explicitly allow more keys.

OpenTelemetry (optional)

Create spans, propagate trace context from headers, and sync baggage with AsyncContext when @opentelemetry/api is available.

import * as otel from "@opentelemetry/api";
import {
  Context,
  createAsyncContextExpressOpenTelemetryMiddleware,
  setOpenTelemetryBaggageFromContext,
  withOpenTelemetrySpan,
} from "@marceloraineri/async-context";

app.use(
  createAsyncContextExpressOpenTelemetryMiddleware({
    otel: {
      api: otel,
      tracerName: "api",
      contextAttributeKeys: ["requestId", "tenantId"],
    },
  })
);

await Context.run({ requestId: "req_1", tenantId: "t_123" }, async () => {
  await withOpenTelemetrySpan(
    "db.query",
    async () => Promise.resolve(),
    { api: otel, attributes: { db: "users" } }
  );

  setOpenTelemetryBaggageFromContext({
    api: otel,
    contextKeys: ["requestId", "tenantId"],
    baggagePrefix: "ctx.",
  });
});

Performance timing

Measure sync or async work and store timing data in the active context.

import { Context } from "@marceloraineri/async-context";

await Context.run({}, async () => {
  await Context.measure("db.query", async () => {
    await Promise.resolve();
  }, { data: { table: "users" } });

  console.log(Context.getValue("perf"));
});

Use key or mode to control where entries are stored.

Context.measure("cache.lookup", () => "hit", { key: "performance", mode: "overwrite" });

DX and configuration

Use presets or environment variables to configure logging without code changes.

import { createLoggerFromEnv, loggerPreset } from "@marceloraineri/async-context";

const logger = createLoggerFromEnv({
  name: "api",
  defaults: loggerPreset("production"),
});

Environment variables:

| Variable | Description | Example | | --- | --- | --- | | LOG_PRESET | development, production, or test preset | production | | LOG_LEVEL | Minimum log level | info | | LOG_FORMAT | json or pretty | json | | LOG_COLORS | Enable ANSI colors | true | | LOG_CONTEXT | Attach async context | true | | LOG_CONTEXT_KEY | Key name for context | ctx | | LOG_CONTEXT_KEYS | Comma-separated allowlist | requestId,tenantId | | LOG_REDACT_KEYS | Comma-separated redaction paths | ctx.token,data.password | | LOG_REDACT_DEFAULTS | Enable default sensitive-field redaction | true | | LOG_REDACT_FIELDS | Extra sensitive field names (comma-separated) | accessToken,creditCard | | LOG_REDACT_PLACEHOLDER | Mask value placeholder | [REDACTED] | | LOG_SAMPLE_RATE | 0..1 sampling | 0.25 | | LOG_INCLUDE_PID | Include process id | true | | LOG_INCLUDE_HOSTNAME | Include hostname | false | | LOG_TIMESTAMP | Include timestamp | true | | LOG_NAME | Logger name | api |

Framework integrations

Express

AsyncContextExpresssMiddleware (with three "s") and AsyncContextExpressMiddleware (alias) create a new context per request and seed it with a unique instance_id.

import express from "express";
import { AsyncContextExpressMiddleware, Context } from "@marceloraineri/async-context";

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

app.get("/ping", (_req, res) => {
  const store = Context.getStore();
  res.json({ instanceId: store?.instance_id ?? null });
});

app.listen(3000, () => console.log("API listening on :3000"));

If you need a custom request id or seed data, use createAsyncContextExpressMiddleware.

import express from "express";
import { createAsyncContextExpressMiddleware, Context } from "@marceloraineri/async-context";

const app = express();

app.use(
  createAsyncContextExpressMiddleware({
    idKey: "request_id",
    seed: (req) => ({ method: req.method, path: req.url }),
  })
);

app.get("/ping", (_req, res) => {
  const store = Context.getStore();
  res.json({ requestId: store?.request_id ?? null });
});

Fastify

Use the onRequest hook or the convenience registration helper.

import fastify from "fastify";
import { createAsyncContextFastifyHook, Context } from "@marceloraineri/async-context";

const app = fastify();
app.addHook("onRequest", createAsyncContextFastifyHook());

app.get("/ping", async () => {
  const store = Context.getStore();
  return { instanceId: store?.instance_id ?? null };
});

Koa

import Koa from "koa";
import { createAsyncContextKoaMiddleware, Context } from "@marceloraineri/async-context";

const app = new Koa();
app.use(createAsyncContextKoaMiddleware());

app.use(async (ctx) => {
  const store = Context.getStore();
  ctx.body = { instanceId: store?.instance_id ?? null };
});

Next.js API routes

import type { NextApiRequest, NextApiResponse } from "next";
import { createAsyncContextNextHandler, Context } from "@marceloraineri/async-context";

export default createAsyncContextNextHandler(
  async (_req: NextApiRequest, res: NextApiResponse) => {
    const store = Context.getStore();
    res.status(200).json({ instanceId: store?.instance_id ?? null });
  }
);

NestJS

AsyncContextNestMiddleware reuses the Express integration to enable async context in Nest (Express adapter).

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AsyncContextNestMiddleware } from "@marceloraineri/async-context";

@Module({})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(AsyncContextNestMiddleware).forRoutes("*");
  }
}

AdonisJS

AsyncContextAdonisMiddleware plugs into the AdonisJS pipeline and creates one context per request.

// app/Http/Middleware/AsyncContext.ts
import { AsyncContextAdonisMiddleware } from "@marceloraineri/async-context";

export default AsyncContextAdonisMiddleware;

Sentry (optional)

AsyncContext can enrich Sentry events with the active store. If @sentry/node is not installed, the helpers safely no-op. Sensitive fields are redacted by default. Disable with redactDefaults: false or add redactFieldNames.

import express from "express";
import {
  AsyncContextExpressMiddleware,
  initSentryWithAsyncContext,
  sentryAsyncContextExpressMiddleware,
  sentryErrorHandler,
} from "@marceloraineri/async-context";

initSentryWithAsyncContext({
  sentryInit: {
    dsn: process.env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  },
  redactKeys: ["async_context.token"],
});

const app = express();
app.use(AsyncContextExpressMiddleware);
app.use(sentryAsyncContextExpressMiddleware());

app.get("/ping", (_req, res) => res.json({ ok: true }));

app.use(sentryErrorHandler());

API overview

• Context.run(store, callback) and Context.run(callback)
• Context.getStore() and Context.requireStore()
• Context.getValue(key) and Context.requireValue(key)
• Context.addValue(key, value) and Context.addObjectValue(values)
• Context.runWith(values, callback)
• Context.snapshot() and Context.reset()
• createLogger(options) and new Logger(options)
• Logger.child(bindings, options?), Logger.withBindings(bindings, callback, options?), and Logger.startTimer(level?)
• createConsoleTransport(options)
• createLoggerFromEnv(options) and loggerPreset(preset)
• parseBooleanEnv(value), parseNumberEnv(value), parseCsvEnv(value), parseLogLevelEnv(value), parseLogFormatEnv(value), parseLoggerPresetEnv(value)
• createAsyncContextExpressMiddleware(options)
• createAsyncContextFastifyHook(options) and registerAsyncContextFastify(app, options)
• createAsyncContextKoaMiddleware(options)
• createAsyncContextNextHandler(handler, options)
• withOpenTelemetrySpan(name, callback, options) and recordOpenTelemetrySpan(summary, options)
• createAsyncContextExpressOpenTelemetryMiddleware(options)
• createAsyncContextFastifyOpenTelemetryHook(options)
• createAsyncContextKoaOpenTelemetryMiddleware(options)
• createAsyncContextNextOpenTelemetryHandler(handler, options)
• setOpenTelemetryBaggageFromContext(options) and mergeContextFromOpenTelemetryBaggage(options)
• extractOpenTelemetryContextFromHeaders(headers, options) and injectOpenTelemetryContextToHeaders(headers, options)
• initSentryWithAsyncContext(options) and captureExceptionWithContext(error)

Best practices

• Avoid replacing the entire store object; prefer addValue and addObjectValue.
• Long-lived contexts can retain memory; always complete the flow (next() in middleware).
• AsyncLocalStorage is per-process, so each worker maintains its own context.

Contributing

Issues and pull requests are welcome. Include repro steps, tests, or concrete usage scenarios when possible.