Request and response headers play a crucial role in HTTP communication. TypeScript can help ensure they’re properly typed.

Typing Request Headers

Headers arrive as strings or undefined:

// Define expected authorization header

interface AuthHeaders {
  authorization?: string;
}

app.get('/protected', (req: Request<{}, {}, {}, {}, AuthHeaders>, res: Response) => {
  const authHeader = req.headers.authorization;

  if (!authHeader) {
    return res.status(401).send('Unauthorized');
  }

  // Process authorization header

  const token = authHeader.replace('Bearer ', '');

  // …
});

But the fifth generic parameter of Request is less commonly used. A more practical approach is to use type assertions or header validation:

// Header validation middleware

function requireHeader(headerName: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.headers[headerName]) {
      return res.status(400).json({
        error: `Missing required header: ${headerName}`,
      });
    }

    next();
  };
}

// Using the middleware

app.get('/protected', requireHeader('authorization'), (req: Request, res: Response) => {
  // We can now safely assert this exists

  const authHeader = req.headers.authorization as string;

  // …
});

Setting Response Headers

For response headers, TypeScript’s help is more limited because headers are set imperatively:

app.get('/api/data', (req: Request, res: Response) => {
  // Set headers

  res.setHeader('Content-Type', 'application/json');

  res.setHeader('Cache-Control', 'no-cache');

  // Send response

  res.json({ data: 'example' });
});

We can improve this with constants and helper functions:

// Define header constants

const HEADERS = {
  CONTENT_TYPE: 'Content-Type',

  CACHE_CONTROL: 'Cache-Control',

  AUTHORIZATION: 'Authorization',
} as const;

// Define header value constants

const CONTENT_TYPES = {
  JSON: 'application/json',

  HTML: 'text/html',

  XML: 'application/xml',
} as const;

// Helper function for setting common headers

function setStandardHeaders(res: Response): void {
  res.setHeader(HEADERS.CONTENT_TYPE, CONTENT_TYPES.JSON);

  res.setHeader(HEADERS.CACHE_CONTROL, 'no-cache');
}

// Usage

app.get('/api/data', (req: Request, res: Response) => {
  setStandardHeaders(res);

  // Additional custom headers

  res.setHeader('X-Custom-Header', 'value');

  res.json({ data: 'example' });
});

Working with Cookies

Cookies add another layer of complexity. The popular cookie-parser middleware extends the request object:

import cookieParser from 'cookie-parser';

// Setup cookie parser

app.use(cookieParser());

// Define expected cookies

interface AuthCookies {
  sessionId?: string;
}

// Create a middleware to validate required cookies

function requireCookie(cookieName: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.cookies?.[cookieName]) {
      return res.status(400).json({
        error: `Missing required cookie: ${cookieName}`,
      });
    }

    next();
  };
}

// Use it in routes

app.get('/dashboard', requireCookie('sessionId'), (req: Request, res: Response) => {
  // Safe to assert this cookie exists

  const sessionId = req.cookies.sessionId as string;

  // Use the session ID

  // …

  res.send('Dashboard');
});

// Setting cookies

app.post('/login', (req: Request, res: Response) => {
  // Authentication logic

  // …

  // Set cookie

  res.cookie('sessionId', 'abc123', {
    httpOnly: true,

    secure: process.env.NODE_ENV === 'production',

    maxAge: 24 * 60 * 60 * 1000, // 24 hours
  });

  res.json({ success: true });
});

The cookie-parser types are included with @types/cookie-parser, which extends the Express Request interface.