How do you type middleware?

Why Not Just Use any?

Sometimes developers default to typing middleware parameters as any to quickly bypass TypeScript errors. While this might speed up initial development, it defeats the purpose of using TypeScript and can lead to runtime bugs. For example, if you assume req.user exists but it doesn’t, your app might crash.

Best Practices for Typing Middleware

• Use framework-provided types: Always start with the official types from libraries like @types/express or the framework’s own types. They cover most cases and keep your code consistent.
• Extend interfaces when adding custom properties: Don’t mutate the original types directly. Instead, create new interfaces that extend the base ones.
• Be explicit about optional properties: If a property might not exist (like req.user before authentication), mark it as optional to avoid false assumptions.
• Type the next function correctly: The next function can accept an error argument (next(err)), so its type reflects that. Using the official NextFunction type covers this.
• Use generics when available: Some frameworks or libraries allow you to pass generics to customize request/response types, improving type safety across the app.

Common Mistakes When Typing Middleware

• Ignoring the next function type: Typing next as () => void instead of (err?: any) => void can cause issues when handling errors.
• Mutating global types: Modifying the global Request interface without declaration merging can lead to confusing errors or conflicts.
• Not handling async middleware properly: Async middleware should return a Promise or call next appropriately. Forgetting to type async functions or mixing callbacks and promises can cause unexpected behavior.
• Overusing any: This reduces type safety and defeats the purpose of TypeScript.

Performance and Scalability Considerations

Typing middleware itself doesn’t impact runtime performance since TypeScript types are erased during compilation. However, well-typed middleware improves maintainability and scalability by preventing bugs early and making it easier to refactor or onboard new developers.

In large applications, you might have dozens of middleware functions. Using consistent and clear types helps avoid confusion about what data is available on req or res at each stage. This can prevent subtle bugs that only show up under certain conditions.

Security Considerations

Middleware often handles sensitive data, like authentication tokens or user information. Proper typing can help enforce security best practices by making it clear when certain properties are available or required.

For example, if your middleware adds a user object to the request, typing it explicitly helps ensure downstream code checks for its presence before accessing sensitive fields. This reduces the risk of null reference errors or unauthorized access.

Interview Tips: How to Talk About Typing Middleware

• Explain the middleware signature clearly: request, response, and next function.
• Mention the importance of using official types from the framework.
• Discuss extending interfaces to add custom properties safely.
• Bring up common pitfalls like incorrect next typing or overusing any.
• Show awareness of async middleware and error handling.
• Give examples from your own experience where typing middleware prevented bugs or improved code quality.

Comparison: Typing Middleware in Express vs Koa

Express and Koa are two popular Node.js frameworks, but their middleware typing differs due to their design:

For Koa, typing middleware looks like this:

import Koa, { Context, Next } from 'koa';

async function myMiddleware(ctx: Context, next: Next) {
  // do something with ctx.request or ctx.response
  await next();
}

Here, you typically extend the Context interface if you want to add custom properties, similar to Express.

Practical Production Scenario: Authentication Middleware

Imagine you’re building an API with Express and need middleware to authenticate users via JWT tokens. You want to add the decoded user info to the request object so downstream handlers can access it.

A typed middleware might look like this:

import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';

interface UserPayload {
  id: string;
  email: string;
  roles: string[];
}

interface AuthenticatedRequest extends Request {
  user?: UserPayload;
}

function authenticateJWT(req: AuthenticatedRequest, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;
  if (!authHeader) {
    return res.status(401).send('Missing authorization header');
  }

  const token = authHeader.split(' ')[1];
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET!) as UserPayload;
    req.user = decoded;
    next();
  } catch (err) {
    res.status(403).send('Invalid token');
  }
}

This approach ensures that any handler after authenticateJWT can safely access req.user with proper type information, reducing runtime errors and improving developer confidence.