Middleware in Express.js Explained — How It Works, Why It Matters, and Real-World Patterns

const express = require('express');
const app = express();

// ─── Middleware 1: Request Logger ───────────────────────────────────────────
// Runs on EVERY incoming request regardless of route
app.use((req, res, next) => {
  const timestamp = new Date().toISOString();
  console.log(`[${timestamp}] Incoming: ${req.method} ${req.url}`);

  // Attach a custom property to req so later middleware/routes can use it
  req.requestTime = timestamp;

  // CRITICAL: call next() or the request dies here
  next();
});

// ─── Middleware 2: Parse JSON request bodies ─────────────────────────────────
// Without this, req.body is undefined for POST/PUT requests
app.use(express.json());

// ─── Middleware 3: Simple API Key Guard ─────────────────────────────────────
// Only runs if the two middleware above have already called next()
app.use((req, res, next) => {
  const apiKey = req.headers['x-api-key'];

  if (!apiKey || apiKey !== 'my-secret-key-123') {
    // Short-circuit: respond directly, do NOT call next()
    return res.status(401).json({
      error: 'Unauthorized',
      message: 'A valid x-api-key header is required'
    });
  }

  next(); // Key is valid — pass control to the route handler
});

// ─── Route Handler: only reached if all middleware above called next() ────────
app.get('/products', (req, res) => {
  res.json({
    message: 'Here are your products!',
    requestReceivedAt: req.requestTime // set by our logger middleware above
  });
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

const express = require('express');
const app = express();

// ✅ CORRECT ORDER — this is the pattern used in production apps

// STEP 1: Logging first — captures every request including failures
app.use((req, res, next) => {
  console.log(`LOG: ${req.method} ${req.path} at ${Date.now()}ms`);
  next();
});

// STEP 2: Body parsing before any route that needs req.body
app.use(express.json());
app.use(express.urlencoded({ extended: true })); // for HTML form submissions

// STEP 3: Authentication — after body parsing, before protected routes
const authenticateUser = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1]; // Bearer <token>

  if (!token) {
    return res.status(401).json({ error: 'No auth token provided' });
  }

  // In real apps you'd verify a JWT here. We'll simulate it.
  req.currentUser = { id: 42, name: 'Alex', role: 'admin' };
  next();
};

// STEP 4: Mount routes — these only run after the above middleware
app.post('/orders', authenticateUser, (req, res) => {
  // req.body is available because express.json() ran first
  // req.currentUser is available because authenticateUser ran
  const { productId, quantity } = req.body;

  res.status(201).json({
    message: `Order created by ${req.currentUser.name}`,
    order: { productId, quantity }
  });
});

// STEP 5: Error handler MUST be last and MUST have 4 parameters
// Express identifies error middleware by the 4-argument signature
app.use((err, req, res, next) => {
  console.error('Unhandled error:', err.message);
  res.status(500).json({ error: 'Something went wrong on our end' });
});

app.listen(3000);

const express = require('express');
const app = express();
app.use(express.json());

// ─── PATTERN 1: The Enricher ─────────────────────────────────────────────────
// Simulates a DB lookup and attaches the user to every request
const attachUserToRequest = async (req, res, next) => {
  const userId = req.headers['x-user-id'];

  if (!userId) {
    return next(); // No user ID? Fine — downstream routes can handle it
  }

  try {
    // Simulate async database call
    const fakeDbUser = await Promise.resolve({
      id: userId,
      name: 'Jordan Lee',
      role: 'editor',
      plan: 'pro'
    });

    req.currentUser = fakeDbUser; // Attach once, use everywhere
    next();
  } catch (dbError) {
    next(dbError); // Pass errors to the error-handling middleware
  }
};

// ─── PATTERN 2: The Guard ────────────────────────────────────────────────────
// Role-based access control — only 'admin' users can proceed
const requireAdminRole = (req, res, next) => {
  if (!req.currentUser) {
    return res.status(401).json({ error: 'Authentication required' });
  }

  if (req.currentUser.role !== 'admin') {
    return res.status(403).json({
      error: 'Forbidden',
      message: `Your role '${req.currentUser.role}' cannot access this resource`
    });
  }

  next();
};

// ─── PATTERN 3: The Transformer ──────────────────────────────────────────────
// Wraps ALL JSON responses in a consistent { success, data } envelope
const responseEnvelope = (req, res, next) => {
  const originalJson = res.json.bind(res); // Save the original method

  res.json = (payload) => {
    // If the payload already has an 'error' key, don't wrap it
    if (payload && payload.error) {
      return originalJson(payload);
    }
    return originalJson({ success: true, data: payload });
  };

  next();
};

// ─── Wire everything together ────────────────────────────────────────────────
app.use(attachUserToRequest); // Runs globally — enriches req for all routes
app.use(responseEnvelope);    // Runs globally — wraps all success responses

// Public route — no guard needed
app.get('/articles', (req, res) => {
  const greeting = req.currentUser
    ? `Hello ${req.currentUser.name}!`
    : 'Hello, guest!';

  res.json({ articles: ['Intro to Node', 'Express Deep Dive'], greeting });
});

// Protected route — guard middleware applied only here
app.delete('/articles/:id', requireAdminRole, (req, res) => {
  res.json({ deleted: true, articleId: req.params.id });
});

// Error handler (always last)
app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ error: 'Internal server error' });
});

app.listen(3000, () => console.log('Running on port 3000'));

const express = require('express');
const app = express();
app.use(express.json());

// ─── Custom Error Class ──────────────────────────────────────────────────────
// Create typed errors so your error handler can respond intelligently
class AppError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode = statusCode;
    this.isOperational = true; // Distinguishes expected errors from bugs
  }
}

// ─── Route that deliberately throws a known error ────────────────────────────
app.get('/users/:id', async (req, res, next) => {
  try {
    const userId = parseInt(req.params.id, 10);

    if (isNaN(userId) || userId <= 0) {
      // Throw a known operational error — not a bug, just bad input
      throw new AppError('User ID must be a positive integer', 400);
    }

    // Simulate: user not found in database
    if (userId > 100) {
      throw new AppError(`No user found with ID ${userId}`, 404);
    }

    res.json({ id: userId, name: 'Sam Rivera', email: 'sam@example.com' });

  } catch (err) {
    // Forward ALL errors to the error-handling middleware below
    next(err);
  }
});

// ─── 404 Handler — catches requests for routes that don't exist ──────────────
// Must come AFTER all your real routes
app.use((req, res, next) => {
  next(new AppError(`Route ${req.method} ${req.path} not found`, 404));
});

// ─── Global Error Handler — MUST have 4 parameters ──────────────────────────
// MUST be registered last, after all routes and other middleware
app.use((err, req, res, next) => {
  // Log everything — even handled errors are worth knowing about
  console.error(`[ERROR] ${err.message}`, {
    statusCode: err.statusCode,
    path: req.path,
    stack: err.isOperational ? undefined : err.stack
  });

  // Operational errors: send specific, safe message to client
  if (err.isOperational) {
    return res.status(err.statusCode).json({
      error: err.message
    });
  }

  // Programmer errors (bugs): never leak stack traces to clients
  res.status(500).json({
    error: 'An unexpected error occurred. Our team has been notified.'
  });
});

app.listen(3000);