1# nodejs-backend-patterns — detailed patterns and worked examples
2 
3## Core Frameworks
4 
5### Express.js - Minimalist Framework
6 
7**Basic Setup:**
8 
9```typescript
10import express, { Request, Response, NextFunction } from "express";
11import helmet from "helmet";
12import cors from "cors";
13import compression from "compression";
14 
15const app = express();
16 
17// Security middleware
18app.use(helmet());
19app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(",") }));
20app.use(compression());
21 
22// Body parsing
23app.use(express.json({ limit: "10mb" }));
24app.use(express.urlencoded({ extended: true, limit: "10mb" }));
25 
26// Request logging
27app.use((req: Request, res: Response, next: NextFunction) => {
28  console.log(`${req.method} ${req.path}`);
29  next();
30});
31 
32const PORT = process.env.PORT || 3000;
33app.listen(PORT, () => {
34  console.log(`Server running on port ${PORT}`);
35});
36```
37 
38### Fastify - High Performance Framework
39 
40**Basic Setup:**
41 
42```typescript
43import Fastify from "fastify";
44import helmet from "@fastify/helmet";
45import cors from "@fastify/cors";
46import compress from "@fastify/compress";
47 
48const fastify = Fastify({
49  logger: {
50    level: process.env.LOG_LEVEL || "info",
51    transport: {
52      target: "pino-pretty",
53      options: { colorize: true },
54    },
55  },
56});
57 
58// Plugins
59await fastify.register(helmet);
60await fastify.register(cors, { origin: true });
61await fastify.register(compress);
62 
63// Type-safe routes with schema validation
64fastify.post<{
65  Body: { name: string; email: string };
66  Reply: { id: string; name: string };
67}>(
68  "/users",
69  {
70    schema: {
71      body: {
72        type: "object",
73        required: ["name", "email"],
74        properties: {
75          name: { type: "string", minLength: 1 },
76          email: { type: "string", format: "email" },
77        },
78      },
79    },
80  },
81  async (request, reply) => {
82    const { name, email } = request.body;
83    return { id: "123", name };
84  },
85);
86 
87await fastify.listen({ port: 3000, host: "0.0.0.0" });
88```
89 
90## Architectural Patterns
91 
92### Pattern 1: Layered Architecture
93 
94**Structure:**
95 
96```
97src/
98├── controllers/     # Handle HTTP requests/responses
99├── services/        # Business logic
100├── repositories/    # Data access layer
101├── models/          # Data models
102├── middleware/      # Express/Fastify middleware
103├── routes/          # Route definitions
104├── utils/           # Helper functions
105├── config/          # Configuration
106└── types/           # TypeScript types
107```
108 
109**Controller Layer:**
110 
111```typescript
112// controllers/user.controller.ts
113import { Request, Response, NextFunction } from "express";
114import { UserService } from "../services/user.service";
115import { CreateUserDTO, UpdateUserDTO } from "../types/user.types";
116 
117export class UserController {
118  constructor(private userService: UserService) {}
119 
120  async createUser(req: Request, res: Response, next: NextFunction) {
121    try {
122      const userData: CreateUserDTO = req.body;
123      const user = await this.userService.createUser(userData);
124      res.status(201).json(user);
125    } catch (error) {
126      next(error);
127    }
128  }
129 
130  async getUser(req: Request, res: Response, next: NextFunction) {
131    try {
132      const { id } = req.params;
133      const user = await this.userService.getUserById(id);
134      res.json(user);
135    } catch (error) {
136      next(error);
137    }
138  }
139 
140  async updateUser(req: Request, res: Response, next: NextFunction) {
141    try {
142      const { id } = req.params;
143      const updates: UpdateUserDTO = req.body;
144      const user = await this.userService.updateUser(id, updates);
145      res.json(user);
146    } catch (error) {
147      next(error);
148    }
149  }
150 
151  async deleteUser(req: Request, res: Response, next: NextFunction) {
152    try {
153      const { id } = req.params;
154      await this.userService.deleteUser(id);
155      res.status(204).send();
156    } catch (error) {
157      next(error);
158    }
159  }
160}
161```
162 
163**Service Layer:**
164 
165```typescript
166// services/user.service.ts
167import { UserRepository } from "../repositories/user.repository";
168import { CreateUserDTO, UpdateUserDTO, User } from "../types/user.types";
169import { NotFoundError, ValidationError } from "../utils/errors";
170import bcrypt from "bcrypt";
171 
172export class UserService {
173  constructor(private userRepository: UserRepository) {}
174 
175  async createUser(userData: CreateUserDTO): Promise<User> {
176    // Validation
177    const existingUser = await this.userRepository.findByEmail(userData.email);
178    if (existingUser) {
179      throw new ValidationError("Email already exists");
180    }
181 
182    // Hash password
183    const hashedPassword = await bcrypt.hash(userData.password, 10);
184 
185    // Create user
186    const user = await this.userRepository.create({
187      ...userData,
188      password: hashedPassword,
189    });
190 
191    // Remove password from response
192    const { password, ...userWithoutPassword } = user;
193    return userWithoutPassword as User;
194  }
195 
196  async getUserById(id: string): Promise<User> {
197    const user = await this.userRepository.findById(id);
198    if (!user) {
199      throw new NotFoundError("User not found");
200    }
201    const { password, ...userWithoutPassword } = user;
202    return userWithoutPassword as User;
203  }
204 
205  async updateUser(id: string, updates: UpdateUserDTO): Promise<User> {
206    const user = await this.userRepository.update(id, updates);
207    if (!user) {
208      throw new NotFoundError("User not found");
209    }
210    const { password, ...userWithoutPassword } = user;
211    return userWithoutPassword as User;
212  }
213 
214  async deleteUser(id: string): Promise<void> {
215    const deleted = await this.userRepository.delete(id);
216    if (!deleted) {
217      throw new NotFoundError("User not found");
218    }
219  }
220}
221```
222 
223**Repository Layer:**
224 
225```typescript
226// repositories/user.repository.ts
227import { Pool } from "pg";
228import { CreateUserDTO, UpdateUserDTO, UserEntity } from "../types/user.types";
229 
230export class UserRepository {
231  constructor(private db: Pool) {}
232 
233  async create(
234    userData: CreateUserDTO & { password: string },
235  ): Promise<UserEntity> {
236    const query = `
237      INSERT INTO users (name, email, password)
238      VALUES ($1, $2, $3)
239      RETURNING id, name, email, password, created_at, updated_at
240    `;
241    const { rows } = await this.db.query(query, [
242      userData.name,
243      userData.email,
244      userData.password,
245    ]);
246    return rows[0];
247  }
248 
249  async findById(id: string): Promise<UserEntity | null> {
250    const query = "SELECT * FROM users WHERE id = $1";
251    const { rows } = await this.db.query(query, [id]);
252    return rows[0] || null;
253  }
254 
255  async findByEmail(email: string): Promise<UserEntity | null> {
256    const query = "SELECT * FROM users WHERE email = $1";
257    const { rows } = await this.db.query(query, [email]);
258    return rows[0] || null;
259  }
260 
261  async update(id: string, updates: UpdateUserDTO): Promise<UserEntity | null> {
262    const fields = Object.keys(updates);
263    const values = Object.values(updates);
264 
265    const setClause = fields
266      .map((field, idx) => `${field} = $${idx + 2}`)
267      .join(", ");
268 
269    const query = `
270      UPDATE users
271      SET ${setClause}, updated_at = CURRENT_TIMESTAMP
272      WHERE id = $1
273      RETURNING *
274    `;
275 
276    const { rows } = await this.db.query(query, [id, ...values]);
277    return rows[0] || null;
278  }
279 
280  async delete(id: string): Promise<boolean> {
281    const query = "DELETE FROM users WHERE id = $1";
282    const { rowCount } = await this.db.query(query, [id]);
283    return rowCount > 0;
284  }
285}
286```
287 
288### Pattern 2: Dependency Injection
289 
290Use a DI container to wire up repositories, services, and controllers. For a full container implementation, see [references/advanced-patterns.md](references/advanced-patterns.md).
291 
292## Middleware Patterns
293 
294### Authentication Middleware
295 
296```typescript
297// middleware/auth.middleware.ts
298import { Request, Response, NextFunction } from "express";
299import jwt from "jsonwebtoken";
300import { UnauthorizedError } from "../utils/errors";
301 
302interface JWTPayload {
303  userId: string;
304  email: string;
305}
306 
307declare global {
308  namespace Express {
309    interface Request {
310      user?: JWTPayload;
311    }
312  }
313}
314 
315export const authenticate = async (
316  req: Request,
317  res: Response,
318  next: NextFunction,
319) => {
320  try {
321    const token = req.headers.authorization?.replace("Bearer ", "");
322 
323    if (!token) {
324      throw new UnauthorizedError("No token provided");
325    }
326 
327    const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload;
328 
329    req.user = payload;
330    next();
331  } catch (error) {
332    next(new UnauthorizedError("Invalid token"));
333  }
334};
335 
336export const authorize = (...roles: string[]) => {
337  return async (req: Request, res: Response, next: NextFunction) => {
338    if (!req.user) {
339      return next(new UnauthorizedError("Not authenticated"));
340    }
341 
342    // Check if user has required role
343    const hasRole = roles.some((role) => req.user?.roles?.includes(role));
344 
345    if (!hasRole) {
346      return next(new UnauthorizedError("Insufficient permissions"));
347    }
348 
349    next();
350  };
351};
352```
353 
354### Validation Middleware
355 
356```typescript
357// middleware/validation.middleware.ts
358import { Request, Response, NextFunction } from "express";
359import { AnyZodObject, ZodError } from "zod";
360import { ValidationError } from "../utils/errors";
361 
362export const validate = (schema: AnyZodObject) => {
363  return async (req: Request, res: Response, next: NextFunction) => {
364    try {
365      await schema.parseAsync({
366        body: req.body,
367        query: req.query,
368        params: req.params,
369      });
370      next();
371    } catch (error) {
372      if (error instanceof ZodError) {
373        const errors = error.errors.map((err) => ({
374          field: err.path.join("."),
375          message: err.message,
376        }));
377        next(new ValidationError("Validation failed", errors));
378      } else {
379        next(error);
380      }
381    }
382  };
383};
384 
385// Usage with Zod
386import { z } from "zod";
387 
388const createUserSchema = z.object({
389  body: z.object({
390    name: z.string().min(1),
391    email: z.string().email(),
392    password: z.string().min(8),
393  }),
394});
395 
396router.post("/users", validate(createUserSchema), userController.createUser);
397```
398 
399### Rate Limiting Middleware
400 
401```typescript
402// middleware/rate-limit.middleware.ts
403import rateLimit from "express-rate-limit";
404import RedisStore from "rate-limit-redis";
405import Redis from "ioredis";
406 
407const redis = new Redis({
408  host: process.env.REDIS_HOST,
409  port: parseInt(process.env.REDIS_PORT || "6379"),
410});
411 
412export const apiLimiter = rateLimit({
413  store: new RedisStore({
414    client: redis,
415    prefix: "rl:",
416  }),
417  windowMs: 15 * 60 * 1000, // 15 minutes
418  max: 100, // Limit each IP to 100 requests per windowMs
419  message: "Too many requests from this IP, please try again later",
420  standardHeaders: true,
421  legacyHeaders: false,
422});
423 
424export const authLimiter = rateLimit({
425  store: new RedisStore({
426    client: redis,
427    prefix: "rl:auth:",
428  }),
429  windowMs: 15 * 60 * 1000,
430  max: 5, // Stricter limit for auth endpoints
431  skipSuccessfulRequests: true,
432});
433```
434 
435### Request Logging Middleware
436 
437```typescript
438// middleware/logger.middleware.ts
439import { Request, Response, NextFunction } from "express";
440import pino from "pino";
441 
442const logger = pino({
443  level: process.env.LOG_LEVEL || "info",
444  transport: {
445    target: "pino-pretty",
446    options: { colorize: true },
447  },
448});
449 
450export const requestLogger = (
451  req: Request,
452  res: Response,
453  next: NextFunction,
454) => {
455  const start = Date.now();
456 
457  // Log response when finished
458  res.on("finish", () => {
459    const duration = Date.now() - start;
460    logger.info({
461      method: req.method,
462      url: req.url,
463      status: res.statusCode,
464      duration: `${duration}ms`,
465      userAgent: req.headers["user-agent"],
466      ip: req.ip,
467    });
468  });
469 
470  next();
471};
472 
473export { logger };
474```
475 
476## Error Handling
477 
478### Custom Error Classes
479 
480```typescript
481// utils/errors.ts
482export class AppError extends Error {
483  constructor(
484    public message: string,
485    public statusCode: number = 500,
486    public isOperational: boolean = true,
487  ) {
488    super(message);
489    Object.setPrototypeOf(this, AppError.prototype);
490    Error.captureStackTrace(this, this.constructor);
491  }
492}
493 
494export class ValidationError extends AppError {
495  constructor(
496    message: string,
497    public errors?: any[],
498  ) {
499    super(message, 400);
500  }
501}
502 
503export class NotFoundError extends AppError {
504  constructor(message: string = "Resource not found") {
505    super(message, 404);
506  }
507}
508 
509export class UnauthorizedError extends AppError {
510  constructor(message: string = "Unauthorized") {
511    super(message, 401);
512  }
513}
514 
515export class ForbiddenError extends AppError {
516  constructor(message: string = "Forbidden") {
517    super(message, 403);
518  }
519}
520 
521export class ConflictError extends AppError {
522  constructor(message: string) {
523    super(message, 409);
524  }
525}
526```
527 
528### Global Error Handler
529 
530```typescript
531// middleware/error-handler.ts
532import { Request, Response, NextFunction } from "express";
533import { AppError } from "../utils/errors";
534import { logger } from "./logger.middleware";
535 
536export const errorHandler = (
537  err: Error,
538  req: Request,
539  res: Response,
540  next: NextFunction,
541) => {
542  if (err instanceof AppError) {
543    return res.status(err.statusCode).json({
544      status: "error",
545      message: err.message,
546      ...(err instanceof ValidationError && { errors: err.errors }),
547    });
548  }
549 
550  // Log unexpected errors
551  logger.error({
552    error: err.message,
553    stack: err.stack,
554    url: req.url,
555    method: req.method,
556  });
557 
558  // Don't leak error details in production
559  const message =
560    process.env.NODE_ENV === "production"
561      ? "Internal server error"
562      : err.message;
563 
564  res.status(500).json({
565    status: "error",
566    message,
567  });
568};
569 
570// Async error wrapper
571export const asyncHandler = (
572  fn: (req: Request, res: Response, next: NextFunction) => Promise<any>,
573) => {
574  return (req: Request, res: Response, next: NextFunction) => {
575    Promise.resolve(fn(req, res, next)).catch(next);
576  };
577};
578```
579 
580## Database Patterns
581 
582Node.js supports both SQL and NoSQL databases. Use connection pooling for all production databases.
583 
584Key patterns covered in [references/advanced-patterns.md](references/advanced-patterns.md):
585- **PostgreSQL with connection pool** — `pg` Pool configuration and graceful shutdown
586- **MongoDB with Mongoose** — connection management and schema definition
587- **Transaction pattern** — `BEGIN`/`COMMIT`/`ROLLBACK` with `pg` client
588 
589## Authentication & Authorization
590 
591JWT-based auth with access tokens (short-lived, 15m) and refresh tokens (7d). Full `AuthService` implementation with `bcrypt` password comparison in [references/advanced-patterns.md](references/advanced-patterns.md).
592 
593## Caching Strategies
594 
595Redis-backed `CacheService` with get/set/delete/invalidatePattern, plus a `@Cacheable` decorator for method-level caching. See [references/advanced-patterns.md](references/advanced-patterns.md).
596 
597## API Response Format
598 
599Standardized `ApiResponse` helper with `success`, `error`, and `paginated` static methods. See [references/advanced-patterns.md](references/advanced-patterns.md).
600