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}`);
});