TypeScripttypescriptmiddlewarepipelinedesign-patternsproduction-ready
Composable Middleware Chain
A type-safe middleware pipeline pattern for processing requests through ordered handlers with early termination and context passing.
interface Context {
request: Request;
response: ResponseInit & { body?: unknown };
state: Map<string, unknown>;
startTime: number;
}
type NextFunction = () => Promise<void>;
type Middleware = (ctx: Context, next: NextFunction) => Promise<void>;
export class MiddlewareChain {
private middlewares: Middleware[] = [];
use(middleware: Middleware): this {
this.middlewares.push(middleware);
return this;
}
async execute(request: Request): Promise<Response> {
const ctx: Context = {
request,
response: { status: 200, headers: {} },
state: new Map(),
startTime: Date.now(),
};
let index = 0;
const next: NextFunction = async () => {
if (index < this.middlewares.length) {
const middleware = this.middlewares[index++];
await middleware(ctx, next);
}
};
try {
await next();
} catch (error) {
ctx.response.status = 500;
ctx.response.body = {
error: error instanceof Error ? error.message : "Internal Server Error",
};
}
return new Response(
ctx.response.body ? JSON.stringify(ctx.response.body) : null,
{ status: ctx.response.status, headers: ctx.response.headers as HeadersInit }
);
}
}
// Built-in middlewares
export const logging: Middleware = async (ctx, next) => {
const method = ctx.request.method;
const url = new URL(ctx.request.url).pathname;
console.log(`--> ${method} ${url}`);
await next();
const duration = Date.now() - ctx.startTime;
console.log(`<-- ${method} ${url} ${ctx.response.status} ${duration}ms`);
};
export const cors = (origins: string[]): Middleware => async (ctx, next) => {
const origin = ctx.request.headers.get("origin") ?? "";
if (origins.includes(origin) || origins.includes("*")) {
(ctx.response.headers as Record<string, string>)["Access-Control-Allow-Origin"] = origin;
(ctx.response.headers as Record<string, string>)["Access-Control-Allow-Methods"] = "GET,POST,PUT,DELETE";
(ctx.response.headers as Record<string, string>)["Access-Control-Allow-Headers"] = "Content-Type,Authorization";
}
if (ctx.request.method === "OPTIONS") {
ctx.response.status = 204;
return; // Don't call next - early termination
}
await next();
};
export const auth = (verifyToken: (token: string) => Promise<{ userId: string } | null>): Middleware =>
async (ctx, next) => {
const header = ctx.request.headers.get("authorization");
if (!header?.startsWith("Bearer ")) {
ctx.response.status = 401;
ctx.response.body = { error: "Missing authorization header" };
return;
}
const user = await verifyToken(header.slice(7));
if (!user) {
ctx.response.status = 401;
ctx.response.body = { error: "Invalid token" };
return;
}
ctx.state.set("userId", user.userId);
await next();
};title: "Composable Middleware Chain" description: "A type-safe middleware pipeline pattern for processing requests through ordered handlers with early termination and context passing." category: "TypeScript" language: "typescript" tags: ["typescript", "middleware", "pipeline", "design-patterns", "production-ready"] createdAt: "2025-03-10" updatedAt: "2025-03-30"
Overview
An onion-model middleware chain where each middleware can perform work before and after calling next(). This pattern enables cross-cutting concerns like logging, authentication, and CORS to be composed independently without coupling to specific route handlers.
Code
const app = new MiddlewareChain();
app.use(logging).use(cors(["*"])).use(auth(verify)).use(handler);
const response = await app.execute(request);Notes
- Each middleware controls flow by calling or skipping
next()(early termination for auth failures, OPTIONS) - The
stateMap passes data between middlewares without type coupling - Error boundaries are automatic since the chain catches exceptions from any middleware
- Middleware execution follows the "onion" model: pre-processing wraps post-processing
- This pattern is used by Koa, Hono, and other modern Node.js frameworks