Backend
Engineering
with Node.js

# Initialise a new project
npm init -y

# Install production dependency
npm install express         # saves to "dependencies"

# Install development dependency
npm install --save-dev nodemon jest

# Install globally (CLI tools)
npm install -g pm2

# Lock exact version
npm install express@4.18.2

# Remove package
npm uninstall express

# See installed packages
npm list --depth=0

{
  "name": "vendorflow-api",
  "version": "1.0.0",
  "description": "REST API backend",
  "main": "src/server.js",
  "scripts": {
    "start":   "node src/server.js",
    "dev":     "nodemon src/server.js",     // auto-restart on changes
    "test":    "jest --coverage",
    "lint":    "eslint src/**/*.js",
    "migrate": "node src/db/migrate.js",
    "seed":    "node src/db/seed.js"
  },
  "dependencies": {
    "express": "^4.18.2",
    "bcryptjs": "^2.4.3",
    "jsonwebtoken": "^9.0.0",
    "sequelize": "^6.35.0",
    "mysql2": "^3.6.0",
    "dotenv": "^16.3.1",
    "joi": "^17.11.0"
  },
  "devDependencies": {
    "nodemon": "^3.0.2",
    "jest": "^29.7.0",
    "supertest": "^6.3.3"
  }
}

vendorflow-api/
├── src/
│   ├── config/
│   │   ├── database.js        # DB connection config
│   │   └── app.js             # Express app setup
│   ├── controllers/           # Request handlers (thin layer)
│   │   ├── authController.js
│   │   ├── userController.js
│   │   └── paymentController.js
│   ├── services/              # Business logic
│   │   ├── authService.js
│   │   └── paymentService.js
│   ├── models/                # Sequelize / Mongoose models
│   │   ├── User.js
│   │   └── Payment.js
│   ├── routes/                # Route definitions
│   │   ├── auth.routes.js
│   │   ├── user.routes.js
│   │   └── index.js           # Combine all routes
│   ├── middlewares/
│   │   ├── auth.middleware.js  # JWT verification
│   │   ├── validate.js         # Joi validation
│   │   └── errorHandler.js
│   ├── utils/
│   │   ├── ApiError.js
│   │   ├── logger.js
│   │   └── helpers.js
│   └── server.js              # Entry point
├── tests/
│   ├── unit/
│   └── integration/
├── .env
├── .env.example
├── .gitignore
└── package.json

const express = require('express');
const cors    = require('cors');
const helmet  = require('helmet');  // security headers
const morgan  = require('morgan'); // request logging
const routes  = require('../routes');

const app = express();

// ── GLOBAL MIDDLEWARE ───────────────────────────────────
app.use(helmet());           // Set security HTTP headers
app.use(cors({
  origin: process.env.CLIENT_URL || '*',
  credentials: true,
}));
app.use(morgan('combined'));  // Log all requests
app.use(express.json({ limit: '10mb' }));      // Parse JSON body
app.use(express.urlencoded({ extended: true })); // Parse form data

// ── ROUTES ──────────────────────────────────────────────
app.use('/api/v1', routes);

// ── HEALTH CHECK ────────────────────────────────────────
app.get('/health', (req, res) => {
  res.json({ status: 'healthy', timestamp: new Date() });
});

// ── 404 HANDLER ─────────────────────────────────────────
app.use('*', (req, res) => {
  res.status(404).json({ success: false, message: 'Route not found' });
});

module.exports = app;

const jwt = require('jsonwebtoken');

// Middleware: a function with (req, res, next) signature
// Call next() to pass control to the next middleware/route

const authenticate = (req, res, next) => {
  try {
    const authHeader = req.headers.authorization;
    if (!authHeader?.startsWith('Bearer ')) {
      return res.status(401).json({ success: false, message: 'No token provided' });
    }

    const token   = authHeader.split(' ')[1];
    const decoded = jwt.verify(token, process.env.JWT_SECRET);

    req.user = decoded;  // attach user to request
    next();            // continue to route handler
  } catch (error) {
    res.status(401).json({ success: false, message: 'Invalid or expired token' });
  }
};

// Role-based access — factory middleware
const authorize = (...roles) => (req, res, next) => {
  if (!roles.includes(req.user?.role)) {
    return res.status(403).json({ success: false, message: 'Insufficient permissions' });
  }
  next();
};

// Request logger middleware
const requestLogger = (req, res, next) => {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
  next();
};

module.exports = { authenticate, authorize, requestLogger };

const express    = require('express');
const router     = express.Router();
const controller = require('../controllers/userController');
const { authenticate, authorize } = require('../middlewares/auth.middleware');
const validate   = require('../middlewares/validate');
const { updateUserSchema } = require('../validators/user.validator');

// GET /api/v1/users?page=1&limit=10&role=admin
router.get('/', authenticate, controller.getAll);

// GET /api/v1/users/:id
router.get('/:id', authenticate, controller.getById);

// PUT /api/v1/users/:id — with validation middleware
router.put('/:id', authenticate, validate(updateUserSchema), controller.update);

// DELETE /api/v1/users/:id — admin only
router.delete('/:id', authenticate, authorize('admin'), controller.delete);

module.exports = router;

// Centralised error class — extends native Error
class ApiError extends Error {
  constructor(statusCode, message, errors = [], stack = '') {
    super(message);
    this.statusCode = statusCode;
    this.success    = false;
    this.errors     = errors;

    if (stack) {
      this.stack = stack;
    } else {
      Error.captureStackTrace(this, this.constructor);
    }
  }

  // Factory methods for common errors
  static notFound(msg = 'Resource not found')   { return new ApiError(404, msg); }
  static unauthorized(msg = 'Unauthorized')        { return new ApiError(401, msg); }
  static forbidden(msg = 'Forbidden')             { return new ApiError(403, msg); }
  static badRequest(msg = 'Bad request')           { return new ApiError(400, msg); }
  static conflict(msg = 'Resource already exists') { return new ApiError(409, msg); }
}

module.exports = { ApiError };

const { ApiError } = require('../utils/ApiError');
const logger       = require('../utils/logger');

// Express error middleware — MUST have 4 parameters
const errorHandler = (err, req, res, next) => {
  let error = { ...err };
  error.message = err.message;

  // Log all errors in development
  if (process.env.NODE_ENV === 'development') {
    logger.error(`${err.statusCode || 500} - ${err.message} - ${req.originalUrl}`);
  }

  // Sequelize validation error
  if (err.name === 'SequelizeValidationError') {
    const message = err.errors.map(e => e.message).join(', ');
    error = new ApiError(400, message);
  }

  // Sequelize unique constraint
  if (err.name === 'SequelizeUniqueConstraintError') {
    error = new ApiError(409, 'Duplicate field value');
  }

  // JWT errors
  if (err.name === 'JsonWebTokenError')   error = new ApiError(401, 'Invalid token');
  if (err.name === 'TokenExpiredError')    error = new ApiError(401, 'Token expired');

  res.status(error.statusCode || 500).json({
    success: false,
    message: error.message || 'Internal Server Error',
    errors:  error.errors  || [],
    ...(process.env.NODE_ENV === 'development' && { stack: err.stack }),
  });
};

module.exports = errorHandler;

// Register AFTER all routes in app.js:
// app.use(errorHandler);

const redis = require('ioredis');
const client = new redis(process.env.REDIS_URL);

const cache = {
  async get(key) {
    const data = await client.get(key);
    return data ? JSON.parse(data) : null;
  },
  async set(key, value, ttlSeconds = 300) {
    await client.setex(key, ttlSeconds, JSON.stringify(value));
  },
  async del(key)         { await client.del(key); },
  async invalidate(pattern) {
    const keys = await client.keys(pattern);
    if (keys.length) await client.del(...keys);
  },
};

// Cache middleware factory
const cacheMiddleware = (keyFn, ttl = 300) => async (req, res, next) => {
  const key = keyFn(req);
  const cached = await cache.get(key);

  if (cached) {
    return res.json({ ...cached, fromCache: true });
  }

  // Intercept response to cache it
  const originalJson = res.json.bind(res);
  res.json = (data) => {
    cache.set(key, data, ttl).catch(console.error);
    return originalJson(data);
  };

  next();
};

// Usage on route:
// router.get('/', cacheMiddleware(req => `users:page:${req.query.page}`, 120), controller.getAll);

module.exports = { cache, cacheMiddleware };

const rateLimit    = require('express-rate-limit');
const RedisStore   = require('rate-limit-redis');
const { client }   = require('./redis');

// Redis-backed rate limiter (works across multiple servers)
const createLimiter = (max, windowMinutes, message) => rateLimit({
  windowMs: windowMinutes * 60 * 1000,
  max,
  message:  { success: false, message },
  standardHeaders: true,
  legacyHeaders:   false,
  store: new RedisStore({ sendCommand: (...args) => client.call(...args) }),
  keyGenerator: (req) => req.user?.id || req.ip, // per-user when authenticated
});

module.exports = {
  globalLimiter: createLimiter(100, 15, 'Too many requests'),
  authLimiter:   createLimiter(5,   15, 'Too many auth attempts'),
  apiLimiter:    createLimiter(30,  1,  'API rate limit exceeded'),
};