contextflow-elsolya

AsyncLocalStorage-based request context for Node.js applications.

What this package solves

contextflow-elsolya gives you request-scoped values (request IDs, tenant IDs, user IDs, and more) across asynchronous call chains without manually threading arguments through every function.

Installation

npm install contextflow-elsolya

Requirements

• Node.js >= 20
• TypeScript 5+ recommended

Five-minute quick start

import { createRequestContext, createRequestId } from "contextflow-elsolya";

interface AppContext {
  requestId: string;
  userId?: string;
}

const context = createRequestContext<AppContext>();

await context.run({ requestId: createRequestId(), userId: "user_1" }, async () => {
  console.log(context.require("requestId"));
  await doWork();
});

Core API

• createRequestContext()
• run, get, require, getStore, requireStore
• set, update, withValues, bind, snapshot
• serialize({ allow }) / runFromCarrier(carrier, fn)
• createLoggerProxy(logger, { keys })
• createRequestId(), extractRequestContext(), injectRequestContextHeaders()

Configuration reference

Header extraction supports:

• x-request-id
• x-correlation-id
• x-tenant-id
• traceparent

Sanitization and validation callbacks are available. Identity headers are never blindly trusted for authorization decisions.

Framework integrations

import { createExpressRequestContextMiddleware } from "contextflow-elsolya/express";
import { createFastifyRequestContextPlugin } from "contextflow-elsolya/fastify";
import { createKoaRequestContextMiddleware } from "contextflow-elsolya/koa";
import { createHonoRequestContextMiddleware } from "contextflow-elsolya/hono";
import { createNestRequestContextInterceptor } from "contextflow-elsolya/nest";
import { withNextRequestContext } from "contextflow-elsolya/next";

Storage adapters

Not applicable. Context is process-local via AsyncLocalStorage.

Security considerations

• Never serialize the full context automatically; use explicit allow lists.
• Do not treat client-supplied identity headers as authenticated identity.
• Snapshots are frozen to reduce accidental mutation bugs.

Failure behavior

Accessing require / requireStore / set / update / serialize outside run() throws ContextFlowError with stable codes.

Edge cases

• Nested withValues creates a child store and restores the parent afterward.
• bind captures the current store for later callback execution.
• Concurrent requests remain isolated (verified with 1,000 parallel operations).

TypeScript examples

const requestId = context.get("requestId"); // string | undefined
const required = context.require("requestId"); // string

Testing examples

const context = createRequestContext<{ requestId: string }>();
await context.run({ requestId: "test" }, async () => {
  expect(context.require("requestId")).toBe("test");
});

Migration notes

This package is independently versioned. Installing contextflow-elsolya does not install other Elsolya packages.

FAQ

Does importing the core load Express? No. Framework adapters are separate subpath exports.

Can I propagate context into background jobs? Yes, via serialize({ allow }) and runFromCarrier.