tomevault-io Middleware Patterns Skill
Patterns for designing reusable middleware in Express applications.
Middleware Basics
import { Request, Response, NextFunction } from 'express';
// Basic middleware signature
type Middleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
// Middleware types
// 1. Application-level: app.use(middleware)
// 2. Router-level: router.use(middleware)
// 3. Route-level: app.get('/path', middleware, handler)
// 4. Error-handling: (err, req, res, next) => {}
Common Middleware Patterns
Request Logging
function requestLogger(options: { level?: string } = {}) {
return (req: Request, res: Response, next: NextFunction) => {
const start = Date.now();
res.on('finish', () => {
const duration = Date.now() - start;
logger.log({
level: options.level || 'info',
method: req.method,
path: req.path,
statusCode: res.statusCode,
duration: `${duration}ms`,
userAgent: req.get('user-agent'),
});
});
next();
};
}
app.use(requestLogger());
Request ID
import { v4 as uuid } from 'uuid';
function requestId() {
return (req: Request, res: Response, next: NextFunction) => {
const id = req.headers['x-request-id'] as string || uuid();
req.id = id;
res.setHeader('X-Request-ID', id);
next();
};
}
// Extend Request type
declare global {
namespace Express {
interface Request {
id: string;
}
}
}
Response Time
function responseTime() {
return (req: Request, res: Response, next: NextFunction) => {
const start = process.hrtime();
res.on('finish', () => {
const [seconds, nanoseconds] = process.hrtime(start);
const ms = seconds * 1000 + nanoseconds / 1000000;
res.setHeader('X-Response-Time', `${ms.toFixed(2)}ms`);
});
next();
};
}
Validation Middleware
import { z } from 'zod';
interface ValidationSchemas {
body?: z.ZodSchema;
query?: z.ZodSchema;
params?: z.ZodSchema;
}
function validate(schemas: ValidationSchemas) {
return async (req: Request, res: Response, next: NextFunction) => {
try {
if (schemas.body) {
req.body = await schemas.body.parseAsync(req.body);
}
if (schemas.query) {
req.query = await schemas.query.parseAsync(req.query);
}
if (schemas.params) {
req.params = await schemas.params.parseAsync(req.params);
}
next();
} catch (error) {
if (error instanceof z.ZodError) {
return res.status(400).json({
error: {
code: 'VALIDATION_ERROR',
message: 'Validation failed',
details: error.errors.map(e => ({
path: e.path.join('.'),
message: e.message,
})),
},
});
}
next(error);
}
};
}
// Usage
const createUserSchema = z.object({
email: z.string().email(),
name: z.string().min(1),
});
app.post('/users',
validate({ body: createUserSchema }),
userController.create
);
Authentication
interface AuthOptions {
required?: boolean;
roles?: string[];
}
function authenticate(options: AuthOptions = { required: true }) {
return async (req: Request, res: Response, next: NextFunction) => {
const token = req.headers.authorization?.replace('Bearer ', '');
if (!token) {
if (options.required) {
return res.status(401).json({
error: { code: 'UNAUTHORIZED', message: 'Authentication required' },
});
}
return next();
}
try {
const payload = verifyToken(token);
const user = await userService.findById(payload.userId);
if (!user) {
return res.status(401).json({
error: { code: 'UNAUTHORIZED', message: 'User not found' },
});
}
// Check roles if specified
if (options.roles && !options.roles.includes(user.role)) {
return res.status(403).json({
error: { code: 'FORBIDDEN', message: 'Insufficient permissions' },
});
}
req.user = user;
next();
} catch (error) {
res.status(401).json({
error: { code: 'UNAUTHORIZED', message: 'Invalid token' },
});
}
};
}
// Usage
app.get('/profile', authenticate(), profileController.get);
app.get('/admin', authenticate({ roles: ['admin'] }), adminController.dashboard);
Rate Limiting
interface RateLimitOptions {
windowMs: number;
max: number;
keyGenerator?: (req: Request) => string;
message?: string;
}
function rateLimit(options: RateLimitOptions) {
const requests = new Map<string, { count: number; resetTime: number }>();
return (req: Request, res: Response, next: NextFunction) => {
const key = options.keyGenerator?.(req) || req.ip;
const now = Date.now();
const record = requests.get(key);
if (!record || now > record.resetTime) {
requests.set(key, { count: 1, resetTime: now + options.windowMs });
return next();
}
if (record.count >= options.max) {
const retryAfter = Math.ceil((record.resetTime - now) / 1000);
res.setHeader('Retry-After', retryAfter);
return res.status(429).json({
error: {
code: 'RATE_LIMIT_EXCEEDED',
message: options.message || 'Too many requests',
retryAfter,
},
});
}
record.count++;
next();
};
}
Caching
interface CacheOptions {
ttl: number;
key?: (req: Request) => string;
}
function cache(options: CacheOptions) {
return async (req: Request, res: Response, next: NextFunction) => {
// Only cache GET requests
if (req.method !== 'GET') {
return next();
}
const key = options.key?.(req) || `cache:${req.originalUrl}`;
try {
const cached = await redis.get(key);
if (cached) {
res.setHeader('X-Cache', 'HIT');
return res.json(JSON.parse(cached));
}
// Store original json method
const originalJson = res.json.bind(res);
// Override json to cache response
res.json = (body: any) => {
redis.setex(key, options.ttl, JSON.stringify(body));
res.setHeader('X-Cache', 'MISS');
return originalJson(body);
};
next();
} catch (error) {
next(); // Fail open - continue without cache
}
};
}
// Usage
app.get('/products', cache({ ttl: 300 }), productController.list);
Request Timeout
function timeout(ms: number) {
return (req: Request, res: Response, next: NextFunction) => {
const timer = setTimeout(() => {
if (!res.headersSent) {
res.status(503).json({
error: { code: 'TIMEOUT', message: 'Request timeout' },
});
}
}, ms);
res.on('finish', () => clearTimeout(timer));
next();
};
}
app.use(timeout(30000)); // 30 second timeout
Middleware Organization
// middleware/index.ts
export { requestId } from './requestId';
export { requestLogger } from './requestLogger';
export { authenticate } from './authenticate';
export { validate } from './validate';
export { rateLimit } from './rateLimit';
export { errorHandler } from './errorHandler';
// app.ts
import * as middleware from './middleware';
// Order matters!
app.use(middleware.requestId());
app.use(middleware.requestLogger());
app.use(helmet());
app.use(cors());
app.use(express.json());
// Routes
app.use('/api', apiRouter);
// Error handler last
app.use(middleware.errorHandler());
Conditional Middleware
function conditionalMiddleware(
condition: (req: Request) => boolean,
middleware: Middleware
) {
return (req: Request, res: Response, next: NextFunction) => {
if (condition(req)) {
return middleware(req, res, next);
}
next();
};
}
// Only authenticate API routes
app.use(conditionalMiddleware(
(req) => req.path.startsWith('/api'),
authenticate()
));
Composing Middleware
function compose(...middlewares: Middleware[]) {
return (req: Request, res: Response, next: NextFunction) => {
const dispatch = (index: number): void => {
if (index >= middlewares.length) {
return next();
}
const middleware = middlewares[index];
middleware(req, res, (err?: any) => {
if (err) return next(err);
dispatch(index + 1);
});
};
dispatch(0);
};
}
// Usage
const secureRoute = compose(
authenticate(),
rateLimit({ windowMs: 60000, max: 10 }),
validate({ body: schema })
);
app.post('/sensitive', secureRoute, handler);
Integration
Used by:
backend-developeragent- Express/Node.js stack skills
Converted and distributed by TomeVault — claim your Tome and manage your conversions.