Express.js Framework Explained — Routing, Middleware and Real-World Patterns

// userRouter.js — a self-contained router for all /users endpoints
const express = require('express');
const router = express.Router(); // create a mini-app just for user routes

// In-memory store for demo purposes — swap this for a real DB call
const users = [
  { id: 1, name: 'Alice Nguyen', role: 'admin' },
  { id: 2, name: 'Ben Okafor',  role: 'member' },
];

// GET /users — return all users
router.get('/', (req, res) => {
  // req.query.role lets callers filter: GET /users?role=admin
  const { role } = req.query;
  const result = role
    ? users.filter(u => u.role === role)
    : users;
  res.json({ success: true, data: result });
});

// GET /users/:userId — return one user by id
router.get('/:userId', (req, res) => {
  const id = parseInt(req.params.userId, 10); // params are always strings — parse them!
  const user = users.find(u => u.id === id);

  if (!user) {
    // Always use the correct HTTP status code — 404, not 200 with an error message
    return res.status(404).json({ success: false, message: 'User not found' });
  }

  res.json({ success: true, data: user });
});

// POST /users — create a new user
router.post('/', (req, res) => {
  const { name, role } = req.body; // requires express.json() middleware in app.js

  if (!name || !role) {
    return res.status(400).json({ success: false, message: 'name and role are required' });
  }

  const newUser = { id: users.length + 1, name, role };
  users.push(newUser);

  // 201 Created is semantically correct for a successful resource creation
  res.status(201).json({ success: true, data: newUser });
});

module.exports = router;

// -----------------------------------------------------------
// app.js — the main entry point that wires everything together
// -----------------------------------------------------------
const express = require('express');
const userRouter = require('./userRouter');

const app = express();
const PORT = 3000;

// Middleware: parse incoming JSON bodies BEFORE any route that needs req.body
app.use(express.json());

// Mount the user router — every route inside userRouter is now prefixed with /users
app.use('/users', userRouter);

app.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}`);
});

// middlewareChain.js — demonstrates a real-world middleware pipeline
const express = require('express');
const app = express();
const PORT = 3000;

// ── 1. APPLICATION-LEVEL MIDDLEWARE ──────────────────────────────────────────

// Parses incoming JSON bodies and adds the parsed object to req.body
app.use(express.json());

// Custom request logger — fires for EVERY request, regardless of route
app.use((req, res, next) => {
  const timestamp = new Date().toISOString();
  console.log(`[${timestamp}] ${req.method} ${req.url}`);
  next(); // MUST call next() or the request hangs here
});

// ── 2. REUSABLE AUTH MIDDLEWARE ───────────────────────────────────────────────

// In a real app this would verify a JWT. Here we check a simple header for demo.
function requireAuth(req, res, next) {
  const token = req.headers['x-api-token'];

  if (!token || token !== 'secret-token-123') {
    // Terminate the chain immediately — send 401 and do NOT call next()
    return res.status(401).json({ success: false, message: 'Unauthorised' });
  }

  // Attach user identity to req so downstream handlers can use it
  req.currentUser = { id: 42, name: 'Alice Nguyen', role: 'admin' };
  next(); // pass control to the next middleware or route handler
}

// ── 3. ROUTE-LEVEL MIDDLEWARE ─────────────────────────────────────────────────

// Public route — no auth needed
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

// Protected route — requireAuth runs first, then the handler
// Only if requireAuth calls next() does the second function execute
app.get('/dashboard', requireAuth, (req, res) => {
  res.json({
    message: `Welcome, ${req.currentUser.name}`,
    role: req.currentUser.role,
  });
});

// ── 4. ASYNC ERROR HANDLING PATTERN ──────────────────────────────────────────

// Simulate an async operation (e.g., a database call) that might fail
app.get('/report', requireAuth, async (req, res, next) => {
  try {
    // Pretend this throws when the report data is missing
    const reportData = await fetchReport(req.currentUser.id);
    res.json({ data: reportData });
  } catch (error) {
    // Forward the error to Express's error handler — do NOT handle it here
    next(error);
  }
});

async function fetchReport(userId) {
  // Simulating a failed DB query
  throw new Error(`Report data unavailable for user ${userId}`);
}

// ── 5. GLOBAL ERROR HANDLER — must have exactly 4 params ─────────────────────
// Express identifies this as an error handler because of the `err` first param
app.use((err, req, res, next) => {
  console.error(`[ERROR] ${err.message}`);

  // Never leak stack traces to clients in production
  const isDev = process.env.NODE_ENV === 'development';
  res.status(err.status || 500).json({
    success: false,
    message: err.message,
    ...(isDev && { stack: err.stack }), // only include stack in dev mode
  });
});

app.listen(PORT, () => console.log(`Server on http://localhost:${PORT}`));

// ─── Folder structure ────────────────────────────────────────────────────────
// project/
// ├── app.js              ← Express app setup (no listen here)
// ├── server.js           ← starts the HTTP server
// ├── .env                ← PORT, DB_URL, JWT_SECRET (never commit this)
// ├── routes/
// │   └── productRoutes.js
// ├── controllers/
// │   └── productController.js
// ├── services/
// │   └── productService.js
// └── middleware/
//     └── validateBody.js
// ─────────────────────────────────────────────────────────────────────────────

// services/productService.js — pure business logic, no Express imports
const productStore = [
  { id: 1, name: 'Mechanical Keyboard', price: 129.99, stock: 14 },
  { id: 2, name: 'USB-C Hub',           price: 49.99,  stock: 0  },
];

const productService = {
  getAllProducts() {
    return productStore;
  },

  getProductById(id) {
    return productStore.find(p => p.id === id) || null;
  },

  getInStockProducts() {
    return productStore.filter(p => p.stock > 0);
  },
};

module.exports = productService;

// ─────────────────────────────────────────────────────────────────────────────

// middleware/validateBody.js — factory function returns a middleware
// Usage: router.post('/', validateBody(['name','price']), controller.create)
function validateBody(requiredFields) {
  return (req, res, next) => {
    const missing = requiredFields.filter(field => !(field in req.body));

    if (missing.length > 0) {
      return res.status(400).json({
        success: false,
        message: `Missing required fields: ${missing.join(', ')}`,
      });
    }
    next();
  };
}

module.exports = validateBody;

// ─────────────────────────────────────────────────────────────────────────────

// controllers/productController.js — handles req/res, delegates to service
const productService = require('../services/productService');

const productController = {
  listProducts(req, res) {
    // Controller decides WHICH service method to call based on query params
    const products = req.query.inStock === 'true'
      ? productService.getInStockProducts()
      : productService.getAllProducts();

    res.json({ success: true, count: products.length, data: products });
  },

  getProduct(req, res) {
    const id = parseInt(req.params.productId, 10);
    const product = productService.getProductById(id);

    if (!product) {
      return res.status(404).json({ success: false, message: 'Product not found' });
    }
    res.json({ success: true, data: product });
  },
};

module.exports = productController;

// ─────────────────────────────────────────────────────────────────────────────

// routes/productRoutes.js — maps URLs to controller methods
const express = require('express');
const router = express.Router();
const productController = require('../controllers/productController');
const validateBody = require('../middleware/validateBody');

router.get('/',               productController.listProducts);
router.get('/:productId',     productController.getProduct);

module.exports = router;

// ─────────────────────────────────────────────────────────────────────────────

// app.js — wires everything together; does NOT call app.listen()
const express = require('express');
const productRoutes = require('./routes/productRoutes');

const app = express();

app.use(express.json());
app.use('/api/products', productRoutes);

// Global error handler — last middleware registered, catches all forwarded errors
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ success: false, message: 'Internal server error' });
});

module.exports = app; // export app so server.js can start it and tests can import it

// ─────────────────────────────────────────────────────────────────────────────

// server.js — single responsibility: start the server
require('dotenv').config(); // load .env file values into process.env
const app = require('./app');

const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`[${process.env.NODE_ENV}] Server listening on port ${PORT}`);
});

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

// ── Async handler wrapper (reusable) ─────────────────────────────────────────
// Wraps any async route handler to catch errors and forward them to next()
const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

// ── Custom error class with HTTP status ──────────────────────────────────────
class AppError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode = statusCode;
  }
}

// ── Route using the wrapper ───────────────────────────────────────────────────
app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await findUser(req.params.id); // might throw
  if (!user) throw new AppError('User not found', 404);
  res.json({ data: user });
}));

// ── Global error handler (must be last) ───────────────────────────────────────
app.use((err, req, res, next) => {
  // Determine status code
  const statusCode = err.statusCode || 500;
  
  // Log the full error server-side
  console.error(`[${new Date().toISOString()}] ${err.message}`, err.stack);

  // Generate unique error reference for client
  const errorRef = Date.now().toString(36) + Math.random().toString(36).substr(2, 5);

  res.status(statusCode).json({
    error: {
      message: statusCode === 500 ? 'Internal server error' : err.message,
      reference: errorRef,
      ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
    }
  });
});

async function findUser(id) {
  // Simulating DB call that could fail
  return null; // simulate not found
}

// api.test.js — integration tests for the Express API
const request = require('supertest');
const app = require('./app'); // app.js exports the Express instance (no listen())

describe('GET /api/users', () => {
  it('returns a list of users', async () => {
    const res = await request(app)
      .get('/api/users')
      .expect(200);

    expect(res.body.success).toBe(true);
    expect(Array.isArray(res.body.data)).toBe(true);
  });

  it('filters by role query parameter', async () => {
    const res = await request(app)
      .get('/api/users?role=admin')
      .expect(200);

    res.body.data.forEach(user => {
      expect(user.role).toBe('admin');
    });
  });
});

describe('GET /api/users/:id', () => {
  it('returns 200 for an existing user', async () => {
    const res = await request(app)
      .get('/api/users/1')
      .expect(200);

    expect(res.body.data.id).toBe(1);
  });

  it('returns 404 for non-existent user', async () => {
    await request(app)
      .get('/api/users/999')
      .expect(404);
  });
});

describe('POST /api/users', () => {
  it('creates a user with valid data', async () => {
    const res = await request(app)
      .post('/api/users')
      .send({ name: 'Test User', role: 'member' })
      .set('Content-Type', 'application/json')
      .expect(201);

    expect(res.body.data.name).toBe('Test User');
  });

  it('returns 400 when required fields missing', async () => {
    await request(app)
      .post('/api/users')
      .send({ name: 'No Role' })
      .set('Content-Type', 'application/json')
      .expect(400);
  });
});

describe('Error handling', () => {
  it('returns 500 with generic message in production', async () => {
    // Force the app into production mode for this test
    process.env.NODE_ENV = 'production';
    // Hit an endpoint that is known to throw (e.g., missing DB connection)
    // This assumes you have a route that throws when NODE_ENV is production
    const res = await request(app)
      .get('/api/report') // this route calls fetchReport which throws
      .expect(500);

    expect(res.body.error.message).toBe('Internal server error');
    expect(res.body.error.stack).toBeUndefined();

    // Restore environment
    process.env.NODE_ENV = 'test';
  });
});

const express = require('express');
const rateLimit = require('express-rate-limit');
const cors = require('cors');
const compression = require('compression');
const helmet = require('helmet');
const { v4: uuidv4 } = require('uuid');

const app = express();

// 1. Security headers — should be one of the first middleware
app.use(helmet());

// 2. Request compression — compress responses before sending
app.use(compression());

// 3. CORS configuration — restrict to your frontend domain
const allowedOrigins = ['https://myapp.com', 'https://admin.myapp.com'];
app.use(cors({
  origin: (origin, callback) => {
    // Allow requests with no origin (mobile apps, curl)
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

// 4. Correlation ID — attach unique request identifier
app.use((req, res, next) => {
  // Use existing header if present (e.g., from a gateway), else generate
  req.correlationId = req.headers['x-correlation-id'] || uuidv4();
  res.setHeader('x-correlation-id', req.correlationId);
  next();
});

// 5. Request logging with correlation ID
app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(
      `[${req.correlationId}] ${req.method} ${req.url} ${res.statusCode} ${duration}ms`
    );
  });
  next();
});

// 6. Rate limiting — 100 requests per 15 minutes per IP
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,
  message: { error: { message: 'Too many requests, please try again later' } },
  standardHeaders: true,
  legacyHeaders: false,
});
app.use(limiter);

// 7. Body parsing
app.use(express.json({ limit: '1mb' })); // enforce body size limit

// 8. Routes
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', correlationId: req.correlationId });
});

// 9. Error handler (last)
app.use((err, req, res, next) => {
  console.error(`[${req.correlationId}] Error:`, err.message);
  res.status(err.statusCode || 500).json({
    error: {
      message: err.statusCode === 500 ? 'Internal server error' : err.message,
      reference: req.correlationId
    }
  });
});

module.exports = app;