Middleware

1What Middleware Is

Middleware is a function that sits between the server receiving a request and your route handler running. Each middleware gets the request, can read or modify it, and then either passes control on (next()) or ends the request itself by sending a response.

// Express signature: (req, res, next)
function requestTimer(req: Request, res: Response, next: NextFunction) {
  const start = Date.now();
  res.on("finish", () => console.log(`${req.method} ${req.url} ${res.statusCode} ${Date.now() - start}ms`));
  next(); // hand off to the next middleware / the route handler
}

app.use(requestTimer);

Middleware is how cross-cutting concerns — things every (or most) routes need — are written once instead of copy-pasted into every handler: logging, CORS, body parsing, authentication (12-authentication_authorization/), rate limiting, compression, request IDs.

2The Chain: Order Is Everything

Middleware runs in registration order. Each one decides whether the request continues:

app.use(express.json());          // 1. parse body -> req.body
app.use(requestId);               // 2. attach req.id
app.use(requestTimer);            // 3. start timing
app.use("/admin", requireAdmin);  // 4. only for paths under /admin
app.get("/admin/stats", statsHandler);

• A middleware that calls next() passes control down the chain.
• A middleware that sends a response (res.status(401).json(...)) and does not call next() short-circuits — nothing after it runs.
• A middleware that does neither leaves the request hanging until the client times out.

Because order matters, putting requireAdmin before express.json() means it can't see the body; putting a logger after the router means it never sees requests the router already answered.

3The "Onion": Code Before and After next()

When next() returns (or its promise resolves, in Koa/Nest/async-style frameworks), the downstream handler has finished. Code after next() therefore runs on the way out:

// Koa-style async middleware
app.use(async (ctx, next) => {
  const start = Date.now();       // inbound: before the handler
  await next();                   // everything downstream runs here
  ctx.set("X-Response-Time", `${Date.now() - start}ms`); // outbound: after the handler
});

This gives every middleware two hooks — before and after — around everything nested inside it, like the layers of an onion. Express's classic callback next() doesn't return a promise you can await, which is why Express code uses res.on("finish") for "after" logic instead.

4Error-Handling Middleware

Express recognizes middleware with four parameters as an error handler. Calling next(err) (or throwing, in Express 5 async handlers) skips all regular middleware and jumps to the next error handler:

app.get("/orders/:id", async (req, res, next) => {
  try {
    res.json(await ordersService.findById(req.params.id));
  } catch (err) {
    next(err); // skip to error-handling middleware
  }
});

// registered LAST, after all routes
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  res.status(500).json({ error: "internal error" });
});

11-exception_handling/ builds the full mapping of error types to status codes on top of this.

5Scoping: Global, Path, Router, Route

app.use(cors());                          // global: every request
app.use("/api", apiRateLimiter);          // path-scoped: /api/**
const admin = express.Router();
admin.use(requireAdmin);                  // router-scoped: only routes on this router
admin.get("/stats", statsHandler);
app.use("/admin", admin);
app.post("/upload", multerSingle("file"), uploadHandler); // route-level: just this route

Apply middleware at the narrowest scope that's correct: an expensive multipart parser belongs on the upload route only, not globally.

6NestJS: Middleware vs Guards vs Interceptors vs Pipes

Nest splits Express's single "middleware" idea into specialized stages that run in a fixed order:

The practical difference: a guard knows which controller method is about to run (and can read its @Roles() metadata); plain middleware doesn't. 07-request_response_lifecycle/ walks a request through this whole pipeline.

Under the HoodHow next Is Implemented▾

Express keeps an array of layers (each with a path matcher and a handler). Dispatch is a tiny recursive function closed over an index:

tsCopy

function handle(req, res, stack, done) {
  let idx = 0;
  function next(err?) {
    const layer = stack[idx++];
    if (!layer) return done(err);                    // ran off the end -> 404 / final handler
    if (!layer.matches(req.path)) return next(err);  // not for this path, skip
    const isErrorHandler = layer.handle.length === 4; // arity check!
    if (err && !isErrorHandler) return next(err);    // in error mode, skip normal middleware
    if (!err && isErrorHandler) return next();       // in normal mode, skip error handlers
    try {
      err ? layer.handle(err, req, res, next) : layer.handle(req, res, next);
    } catch (e) {
      next(e);                                       // sync throw -> error mode
    }
  }
  next();
}

Three consequences fall straight out of this:

1. Arity matters. An error handler written (err, req, res) => ... (3 params) is not treated as an error handler, because Express checks fn.length === 4.
2. "Calling next twice" is a real bug. Each call advances idx — a middleware that calls next() and then also sends a response will run the rest of the chain and respond, causing "Cannot set headers after they are sent."
3. Composition is just function nesting. Koa's koa-compose does the same with dispatch(i) => Promise.resolve(fn(ctx, () => dispatch(i + 1))), which is why await next() naturally gives you the onion.

⚠️ Common Pitfalls

1. Forgetting to call next() (and not responding) — the request hangs until timeout.
2. Calling next() and also sending a response — "Cannot set headers after they are sent to the client."
3. Wrong order — auth after the route, body parser after a middleware that reads the body, error handler registered before routes.
4. Error handler with 3 parameters — silently treated as normal middleware.
5. Unhandled promise rejections in Express 4 async middleware — a rejected promise is not routed to next(err) automatically; wrap handlers or upgrade to Express 5.
6. Global heavy middleware — parsing multipart or decompressing bodies on every route wastes CPU; scope it.

📋 Quick Reference

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: fw_middleware_theory.md · generated by tools/build_lessons.py