1# NestJS Best Practices
2 
3**Version 1.1.0**
4NestJS Best Practices
5January 2026
6 
7> **Note:**
8> This document is mainly for agents and LLMs to follow when maintaining,
9> generating, or refactoring NestJS codebases. Humans may also find it
10> useful, but guidance here is optimized for automation and consistency
11> by AI-assisted workflows.
12 
13---
14 
15## Abstract
16 
17Comprehensive best practices and architecture guide for NestJS applications, designed for AI agents and LLMs. Contains 40 rules across 10 categories, prioritized by impact from critical (architecture, dependency injection) to incremental (DevOps patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
18 
19---
20 
21## Table of Contents
22 
231. [Architecture](#1-architecture) — **CRITICAL**
24   - 1.1 [Avoid Circular Dependencies](#11-avoid-circular-dependencies)
25   - 1.2 [Organize by Feature Modules](#12-organize-by-feature-modules)
26   - 1.3 [Use Proper Module Sharing Patterns](#13-use-proper-module-sharing-patterns)
27   - 1.4 [Single Responsibility for Services](#14-single-responsibility-for-services)
28   - 1.5 [Use Event-Driven Architecture for Decoupling](#15-use-event-driven-architecture-for-decoupling)
29   - 1.6 [Use Repository Pattern for Data Access](#16-use-repository-pattern-for-data-access)
302. [Dependency Injection](#2-dependency-injection) — **CRITICAL**
31   - 2.1 [Avoid Service Locator Anti-Pattern](#21-avoid-service-locator-anti-pattern)
32   - 2.2 [Apply Interface Segregation Principle](#22-apply-interface-segregation-principle)
33   - 2.3 [Honor Liskov Substitution Principle](#23-honor-liskov-substitution-principle)
34   - 2.4 [Prefer Constructor Injection](#24-prefer-constructor-injection)
35   - 2.5 [Understand Provider Scopes](#25-understand-provider-scopes)
36   - 2.6 [Use Injection Tokens for Interfaces](#26-use-injection-tokens-for-interfaces)
373. [Error Handling](#3-error-handling) — **HIGH**
38   - 3.1 [Handle Async Errors Properly](#31-handle-async-errors-properly)
39   - 3.2 [Throw HTTP Exceptions from Services](#32-throw-http-exceptions-from-services)
40   - 3.3 [Use Exception Filters for Error Handling](#33-use-exception-filters-for-error-handling)
414. [Security](#4-security) — **HIGH**
42   - 4.1 [Implement Secure JWT Authentication](#41-implement-secure-jwt-authentication)
43   - 4.2 [Implement Rate Limiting](#42-implement-rate-limiting)
44   - 4.3 [Sanitize Output to Prevent XSS](#43-sanitize-output-to-prevent-xss)
45   - 4.4 [Use Guards for Authentication and Authorization](#44-use-guards-for-authentication-and-authorization)
46   - 4.5 [Validate All Input with DTOs and Pipes](#45-validate-all-input-with-dtos-and-pipes)
475. [Performance](#5-performance) — **HIGH**
48   - 5.1 [Use Async Lifecycle Hooks Correctly](#51-use-async-lifecycle-hooks-correctly)
49   - 5.2 [Use Lazy Loading for Large Modules](#52-use-lazy-loading-for-large-modules)
50   - 5.3 [Optimize Database Queries](#53-optimize-database-queries)
51   - 5.4 [Use Caching Strategically](#54-use-caching-strategically)
526. [Testing](#6-testing) — **MEDIUM-HIGH**
53   - 6.1 [Use Supertest for E2E Testing](#61-use-supertest-for-e2e-testing)
54   - 6.2 [Mock External Services in Tests](#62-mock-external-services-in-tests)
55   - 6.3 [Use Testing Module for Unit Tests](#63-use-testing-module-for-unit-tests)
567. [Database & ORM](#7-database-orm) — **MEDIUM-HIGH**
57   - 7.1 [Avoid N+1 Query Problems](#71-avoid-n-1-query-problems)
58   - 7.2 [Use Database Migrations](#72-use-database-migrations)
59   - 7.3 [Use Transactions for Multi-Step Operations](#73-use-transactions-for-multi-step-operations)
608. [API Design](#8-api-design) — **MEDIUM**
61   - 8.1 [Use DTOs and Serialization for API Responses](#81-use-dtos-and-serialization-for-api-responses)
62   - 8.2 [Use Interceptors for Cross-Cutting Concerns](#82-use-interceptors-for-cross-cutting-concerns)
63   - 8.3 [Use Pipes for Input Transformation](#83-use-pipes-for-input-transformation)
64   - 8.4 [Use API Versioning for Breaking Changes](#84-use-api-versioning-for-breaking-changes)
659. [Microservices](#9-microservices) — **MEDIUM**
66   - 9.1 [Implement Health Checks for Microservices](#91-implement-health-checks-for-microservices)
67   - 9.2 [Use Message and Event Patterns Correctly](#92-use-message-and-event-patterns-correctly)
68   - 9.3 [Use Message Queues for Background Jobs](#93-use-message-queues-for-background-jobs)
6910. [DevOps & Deployment](#10-devops-deployment) — **LOW-MEDIUM**
70   - 10.1 [Implement Graceful Shutdown](#101-implement-graceful-shutdown)
71   - 10.2 [Use ConfigModule for Environment Configuration](#102-use-configmodule-for-environment-configuration)
72   - 10.3 [Use Structured Logging](#103-use-structured-logging)
73 
74---
75 
76## 1. Architecture
77 
78**Section Impact: CRITICAL**
79 
80### 1.1 Avoid Circular Dependencies
81 
82**Impact: CRITICAL** — "#1 cause of runtime crashes"
83 
84Circular dependencies occur when Module A imports Module B, and Module B imports Module A (directly or transitively). NestJS can sometimes resolve these through forward references, but they indicate architectural problems and should be avoided. This is the #1 cause of runtime crashes in NestJS applications.
85 
86**Incorrect (circular module imports):**
87 
88```typescript
89// users.module.ts
90@Module({
91  imports: [OrdersModule], // Orders needs Users, Users needs Orders = circular
92  providers: [UsersService],
93  exports: [UsersService],
94})
95export class UsersModule {}
96 
97// orders.module.ts
98@Module({
99  imports: [UsersModule], // Circular dependency!
100  providers: [OrdersService],
101  exports: [OrdersService],
102})
103export class OrdersModule {}
104```
105 
106**Correct (extract shared logic or use events):**
107 
108```typescript
109// Option 1: Extract shared logic to a third module
110// shared.module.ts
111@Module({
112  providers: [SharedService],
113  exports: [SharedService],
114})
115export class SharedModule {}
116 
117// users.module.ts
118@Module({
119  imports: [SharedModule],
120  providers: [UsersService],
121})
122export class UsersModule {}
123 
124// orders.module.ts
125@Module({
126  imports: [SharedModule],
127  providers: [OrdersService],
128})
129export class OrdersModule {}
130 
131// Option 2: Use events for decoupled communication
132// users.service.ts
133@Injectable()
134export class UsersService {
135  constructor(private eventEmitter: EventEmitter2) {}
136 
137  async createUser(data: CreateUserDto) {
138    const user = await this.userRepo.save(data);
139    this.eventEmitter.emit('user.created', user);
140    return user;
141  }
142}
143 
144// orders.service.ts
145@Injectable()
146export class OrdersService {
147  @OnEvent('user.created')
148  handleUserCreated(user: User) {
149    // React to user creation without direct dependency
150  }
151}
152```
153 
154Reference: [NestJS Circular Dependency](https://docs.nestjs.com/fundamentals/circular-dependency)
155 
156---
157 
158### 1.2 Organize by Feature Modules
159 
160**Impact: CRITICAL** — "3-5x faster onboarding and development"
161 
162Organize your application into feature modules that encapsulate related functionality. Each feature module should be self-contained with its own controllers, services, entities, and DTOs. Avoid organizing by technical layer (all controllers together, all services together). This enables 3-5x faster onboarding and feature development.
163 
164**Incorrect (technical layer organization):**
165 
166```typescript
167// Technical layer organization (anti-pattern)
168src/
169├── controllers/
170│   ├── users.controller.ts
171│   ├── orders.controller.ts
172│   └── products.controller.ts
173├── services/
174│   ├── users.service.ts
175│   ├── orders.service.ts
176│   └── products.service.ts
177├── entities/
178│   ├── user.entity.ts
179│   ├── order.entity.ts
180│   └── product.entity.ts
181└── app.module.ts  // Imports everything directly
182```
183 
184**Correct (feature module organization):**
185 
186```typescript
187// Feature module organization
188src/
189├── users/
190│   ├── dto/
191│   │   ├── create-user.dto.ts
192│   │   └── update-user.dto.ts
193│   ├── entities/
194│   │   └── user.entity.ts
195│   ├── users.controller.ts
196│   ├── users.service.ts
197│   ├── users.repository.ts
198│   └── users.module.ts
199├── orders/
200│   ├── dto/
201│   ├── entities/
202│   ├── orders.controller.ts
203│   ├── orders.service.ts
204│   └── orders.module.ts
205├── shared/
206│   ├── guards/
207│   ├── interceptors/
208│   ├── filters/
209│   └── shared.module.ts
210└── app.module.ts
211 
212// users.module.ts
213@Module({
214  imports: [TypeOrmModule.forFeature([User])],
215  controllers: [UsersController],
216  providers: [UsersService, UsersRepository],
217  exports: [UsersService], // Only export what others need
218})
219export class UsersModule {}
220 
221// app.module.ts
222@Module({
223  imports: [
224    ConfigModule.forRoot(),
225    TypeOrmModule.forRoot(),
226    UsersModule,
227    OrdersModule,
228    SharedModule,
229  ],
230})
231export class AppModule {}
232```
233 
234Reference: [NestJS Modules](https://docs.nestjs.com/modules)
235 
236---
237 
238### 1.3 Use Proper Module Sharing Patterns
239 
240**Impact: CRITICAL** — Prevents duplicate instances, memory leaks, and state inconsistency
241 
242NestJS modules are singletons by default. When a service is properly exported from a module and that module is imported elsewhere, the same instance is shared. However, providing a service in multiple modules creates separate instances, leading to memory waste, state inconsistency, and confusing behavior. Always encapsulate services in dedicated modules, export them explicitly, and import the module where needed.
243 
244**Incorrect (service provided in multiple modules):**
245 
246```typescript
247// StorageService provided directly in multiple modules - WRONG
248// storage.service.ts
249@Injectable()
250export class StorageService {
251  private cache = new Map(); // Each instance has separate state!
252 
253  store(key: string, value: any) {
254    this.cache.set(key, value);
255  }
256}
257 
258// app.module.ts
259@Module({
260  providers: [StorageService], // Instance #1
261  controllers: [AppController],
262})
263export class AppModule {}
264 
265// videos.module.ts
266@Module({
267  providers: [StorageService], // Instance #2 - different from AppModule!
268  controllers: [VideosController],
269})
270export class VideosModule {}
271 
272// Problems:
273// 1. Two separate StorageService instances exist
274// 2. cache.set() in VideosModule doesn't affect AppModule's cache
275// 3. Memory wasted on duplicate instances
276// 4. Debugging nightmares when state doesn't sync
277```
278 
279**Correct (dedicated module with exports):**
280 
281```typescript
282// storage/storage.module.ts
283@Module({
284  providers: [StorageService],
285  exports: [StorageService], // Make available to importers
286})
287export class StorageModule {}
288 
289// videos/videos.module.ts
290@Module({
291  imports: [StorageModule], // Import the module, not the service
292  controllers: [VideosController],
293  providers: [VideosService],
294})
295export class VideosModule {}
296 
297// channels/channels.module.ts
298@Module({
299  imports: [StorageModule], // Same instance shared
300  controllers: [ChannelsController],
301  providers: [ChannelsService],
302})
303export class ChannelsModule {}
304 
305// app.module.ts
306@Module({
307  imports: [
308    StorageModule, // Only if AppModule itself needs StorageService
309    VideosModule,
310    ChannelsModule,
311  ],
312})
313export class AppModule {}
314 
315// Now all modules share the SAME StorageService instance
316```
317 
318**When to use @Global() (sparingly):**
319 
320```typescript
321// ONLY for truly cross-cutting concerns
322@Global()
323@Module({
324  providers: [ConfigService, LoggerService],
325  exports: [ConfigService, LoggerService],
326})
327export class CoreModule {}
328 
329// Import once in AppModule
330@Module({
331  imports: [CoreModule], // Registered globally, available everywhere
332})
333export class AppModule {}
334 
335// Other modules don't need to import CoreModule
336@Module({
337  controllers: [UsersController],
338  providers: [UsersService], // Can inject ConfigService without importing
339})
340export class UsersModule {}
341 
342// WARNING: Don't make everything global!
343// - Hides dependencies (can't see what a module needs from imports)
344// - Makes testing harder
345// - Reserve for: config, logging, database connections
346```
347 
348**Module re-exporting pattern:**
349 
350```typescript
351// common.module.ts - shared utilities
352@Module({
353  providers: [DateService, ValidationService],
354  exports: [DateService, ValidationService],
355})
356export class CommonModule {}
357 
358// core.module.ts - re-exports common for convenience
359@Module({
360  imports: [CommonModule, DatabaseModule],
361  exports: [CommonModule, DatabaseModule], // Re-export for consumers
362})
363export class CoreModule {}
364 
365// feature.module.ts - imports CoreModule, gets both
366@Module({
367  imports: [CoreModule], // Gets CommonModule + DatabaseModule
368  controllers: [FeatureController],
369})
370export class FeatureModule {}
371```
372 
373Reference: [NestJS Modules](https://docs.nestjs.com/modules#shared-modules)
374 
375---
376 
377### 1.4 Single Responsibility for Services
378 
379**Impact: CRITICAL** — "40%+ improvement in testability"
380 
381Each service should have a single, well-defined responsibility. Avoid "god services" that handle multiple unrelated concerns. If a service name includes "And" or handles more than one domain concept, it likely violates single responsibility. This reduces complexity and improves testability by 40%+.
382 
383**Incorrect (god service anti-pattern):**
384 
385```typescript
386// God service anti-pattern
387@Injectable()
388export class UserAndOrderService {
389  constructor(
390    private userRepo: UserRepository,
391    private orderRepo: OrderRepository,
392    private mailer: MailService,
393    private payment: PaymentService,
394  ) {}
395 
396  async createUser(dto: CreateUserDto) {
397    const user = await this.userRepo.save(dto);
398    await this.mailer.sendWelcome(user);
399    return user;
400  }
401 
402  async createOrder(userId: string, dto: CreateOrderDto) {
403    const order = await this.orderRepo.save({ userId, ...dto });
404    await this.payment.charge(order);
405    await this.mailer.sendOrderConfirmation(order);
406    return order;
407  }
408 
409  async calculateOrderStats(userId: string) {
410    // Stats logic mixed in
411  }
412 
413  async validatePayment(orderId: string) {
414    // Payment logic mixed in
415  }
416}
417```
418 
419**Correct (focused services with single responsibility):**
420 
421```typescript
422// Focused services with single responsibility
423@Injectable()
424export class UsersService {
425  constructor(private userRepo: UserRepository) {}
426 
427  async create(dto: CreateUserDto): Promise<User> {
428    return this.userRepo.save(dto);
429  }
430 
431  async findById(id: string): Promise<User> {
432    return this.userRepo.findOneOrFail({ where: { id } });
433  }
434}
435 
436@Injectable()
437export class OrdersService {
438  constructor(private orderRepo: OrderRepository) {}
439 
440  async create(userId: string, dto: CreateOrderDto): Promise<Order> {
441    return this.orderRepo.save({ userId, ...dto });
442  }
443 
444  async findByUser(userId: string): Promise<Order[]> {
445    return this.orderRepo.find({ where: { userId } });
446  }
447}
448 
449@Injectable()
450export class OrderStatsService {
451  constructor(private orderRepo: OrderRepository) {}
452 
453  async calculateForUser(userId: string): Promise<OrderStats> {
454    // Focused stats calculation
455  }
456}
457 
458// Orchestration in controller or dedicated orchestrator
459@Controller('orders')
460export class OrdersController {
461  constructor(
462    private orders: OrdersService,
463    private payment: PaymentService,
464    private notifications: NotificationService,
465  ) {}
466 
467  @Post()
468  async create(@CurrentUser() user: User, @Body() dto: CreateOrderDto) {
469    const order = await this.orders.create(user.id, dto);
470    await this.payment.charge(order);
471    await this.notifications.sendOrderConfirmation(order);
472    return order;
473  }
474}
475```
476 
477Reference: [NestJS Providers](https://docs.nestjs.com/providers)
478 
479---
480 
481### 1.5 Use Event-Driven Architecture for Decoupling
482 
483**Impact: MEDIUM-HIGH** — Enables async processing and modularity
484 
485Use `@nestjs/event-emitter` for intra-service events and message brokers for inter-service communication. Events allow modules to react to changes without direct dependencies, improving modularity and enabling async processing.
486 
487**Incorrect (direct service coupling):**
488 
489```typescript
490// Direct service coupling
491@Injectable()
492export class OrdersService {
493  constructor(
494    private inventoryService: InventoryService,
495    private emailService: EmailService,
496    private analyticsService: AnalyticsService,
497    private notificationService: NotificationService,
498    private loyaltyService: LoyaltyService,
499  ) {}
500 
501  async createOrder(dto: CreateOrderDto): Promise<Order> {
502    const order = await this.repo.save(dto);
503 
504    // Tight coupling - OrdersService knows about all consumers
505    await this.inventoryService.reserve(order.items);
506    await this.emailService.sendConfirmation(order);
507    await this.analyticsService.track('order_created', order);
508    await this.notificationService.push(order.userId, 'Order placed');
509    await this.loyaltyService.addPoints(order.userId, order.total);
510 
511    // Adding new behavior requires modifying this service
512    return order;
513  }
514}
515```
516 
517**Correct (event-driven decoupling):**
518 
519```typescript
520// Use EventEmitter for decoupling
521import { EventEmitter2 } from '@nestjs/event-emitter';
522 
523// Define event
524export class OrderCreatedEvent {
525  constructor(
526    public readonly orderId: string,
527    public readonly userId: string,
528    public readonly items: OrderItem[],
529    public readonly total: number,
530  ) {}
531}
532 
533// Service emits events
534@Injectable()
535export class OrdersService {
536  constructor(
537    private eventEmitter: EventEmitter2,
538    private repo: Repository<Order>,
539  ) {}
540 
541  async createOrder(dto: CreateOrderDto): Promise<Order> {
542    const order = await this.repo.save(dto);
543 
544    // Emit event - no knowledge of consumers
545    this.eventEmitter.emit(
546      'order.created',
547      new OrderCreatedEvent(order.id, order.userId, order.items, order.total),
548    );
549 
550    return order;
551  }
552}
553 
554// Listeners in separate modules
555@Injectable()
556export class InventoryListener {
557  @OnEvent('order.created')
558  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
559    await this.inventoryService.reserve(event.items);
560  }
561}
562 
563@Injectable()
564export class EmailListener {
565  @OnEvent('order.created')
566  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
567    await this.emailService.sendConfirmation(event.orderId);
568  }
569}
570 
571@Injectable()
572export class AnalyticsListener {
573  @OnEvent('order.created')
574  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
575    await this.analyticsService.track('order_created', {
576      orderId: event.orderId,
577      total: event.total,
578    });
579  }
580}
581```
582 
583Reference: [NestJS Events](https://docs.nestjs.com/techniques/events)
584 
585---
586 
587### 1.6 Use Repository Pattern for Data Access
588 
589**Impact: HIGH** — Decouples business logic from database
590 
591Create custom repositories to encapsulate complex queries and database logic. This keeps services focused on business logic, makes testing easier with mock repositories, and allows changing database implementations without affecting business code.
592 
593**Incorrect (complex queries in services):**
594 
595```typescript
596// Complex queries in services
597@Injectable()
598export class UsersService {
599  constructor(
600    @InjectRepository(User) private repo: Repository<User>,
601  ) {}
602 
603  async findActiveWithOrders(minOrders: number): Promise<User[]> {
604    // Complex query logic mixed with business logic
605    return this.repo
606      .createQueryBuilder('user')
607      .leftJoinAndSelect('user.orders', 'order')
608      .where('user.isActive = :active', { active: true })
609      .andWhere('user.deletedAt IS NULL')
610      .groupBy('user.id')
611      .having('COUNT(order.id) >= :min', { min: minOrders })
612      .orderBy('user.createdAt', 'DESC')
613      .getMany();
614  }
615 
616  // Service becomes bloated with query logic
617}
618```
619 
620**Correct (custom repository with encapsulated queries):**
621 
622```typescript
623// Custom repository with encapsulated queries
624@Injectable()
625export class UsersRepository {
626  constructor(
627    @InjectRepository(User) private repo: Repository<User>,
628  ) {}
629 
630  async findById(id: string): Promise<User | null> {
631    return this.repo.findOne({ where: { id } });
632  }
633 
634  async findByEmail(email: string): Promise<User | null> {
635    return this.repo.findOne({ where: { email } });
636  }
637 
638  async findActiveWithMinOrders(minOrders: number): Promise<User[]> {
639    return this.repo
640      .createQueryBuilder('user')
641      .leftJoinAndSelect('user.orders', 'order')
642      .where('user.isActive = :active', { active: true })
643      .andWhere('user.deletedAt IS NULL')
644      .groupBy('user.id')
645      .having('COUNT(order.id) >= :min', { min: minOrders })
646      .orderBy('user.createdAt', 'DESC')
647      .getMany();
648  }
649 
650  async save(user: User): Promise<User> {
651    return this.repo.save(user);
652  }
653}
654 
655// Clean service with business logic only
656@Injectable()
657export class UsersService {
658  constructor(private usersRepo: UsersRepository) {}
659 
660  async getActiveUsersWithOrders(): Promise<User[]> {
661    return this.usersRepo.findActiveWithMinOrders(1);
662  }
663 
664  async create(dto: CreateUserDto): Promise<User> {
665    const existing = await this.usersRepo.findByEmail(dto.email);
666    if (existing) {
667      throw new ConflictException('Email already registered');
668    }
669 
670    const user = new User();
671    user.email = dto.email;
672    user.name = dto.name;
673    return this.usersRepo.save(user);
674  }
675}
676```
677 
678Reference: [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)
679 
680---
681 
682## 2. Dependency Injection
683 
684**Section Impact: CRITICAL**
685 
686### 2.1 Avoid Service Locator Anti-Pattern
687 
688**Impact: HIGH** — Hides dependencies and breaks testability
689 
690Avoid using `ModuleRef.get()` or global containers to resolve dependencies at runtime. This hides dependencies, makes code harder to test, and breaks the benefits of dependency injection. Use constructor injection instead.
691 
692**Incorrect (service locator anti-pattern):**
693 
694```typescript
695// Use ModuleRef to get dependencies dynamically
696@Injectable()
697export class OrdersService {
698  constructor(private moduleRef: ModuleRef) {}
699 
700  async createOrder(dto: CreateOrderDto): Promise<Order> {
701    // Dependencies are hidden - not visible in constructor
702    const usersService = this.moduleRef.get(UsersService);
703    const inventoryService = this.moduleRef.get(InventoryService);
704    const paymentService = this.moduleRef.get(PaymentService);
705 
706    const user = await usersService.findOne(dto.userId);
707    // ... rest of logic
708  }
709}
710 
711// Global singleton container
712class ServiceContainer {
713  private static instance: ServiceContainer;
714  private services = new Map<string, any>();
715 
716  static getInstance(): ServiceContainer {
717    if (!this.instance) {
718      this.instance = new ServiceContainer();
719    }
720    return this.instance;
721  }
722 
723  get<T>(key: string): T {
724    return this.services.get(key);
725  }
726}
727```
728 
729**Correct (constructor injection with explicit dependencies):**
730 
731```typescript
732// Use constructor injection - dependencies are explicit
733@Injectable()
734export class OrdersService {
735  constructor(
736    private usersService: UsersService,
737    private inventoryService: InventoryService,
738    private paymentService: PaymentService,
739  ) {}
740 
741  async createOrder(dto: CreateOrderDto): Promise<Order> {
742    const user = await this.usersService.findOne(dto.userId);
743    const inventory = await this.inventoryService.check(dto.items);
744    // Dependencies are clear and testable
745  }
746}
747 
748// Easy to test with mocks
749describe('OrdersService', () => {
750  let service: OrdersService;
751 
752  beforeEach(async () => {
753    const module = await Test.createTestingModule({
754      providers: [
755        OrdersService,
756        { provide: UsersService, useValue: mockUsersService },
757        { provide: InventoryService, useValue: mockInventoryService },
758        { provide: PaymentService, useValue: mockPaymentService },
759      ],
760    }).compile();
761 
762    service = module.get(OrdersService);
763  });
764});
765 
766// VALID: Factory pattern for dynamic instantiation
767@Injectable()
768export class HandlerFactory {
769  constructor(private moduleRef: ModuleRef) {}
770 
771  getHandler(type: string): Handler {
772    switch (type) {
773      case 'email':
774        return this.moduleRef.get(EmailHandler);
775      case 'sms':
776        return this.moduleRef.get(SmsHandler);
777      default:
778        return this.moduleRef.get(DefaultHandler);
779    }
780  }
781}
782```
783 
784Reference: [NestJS Module Reference](https://docs.nestjs.com/fundamentals/module-ref)
785 
786---
787 
788### 2.2 Apply Interface Segregation Principle
789 
790**Impact: HIGH** — Reduces coupling and improves testability by 30-50%
791 
792Clients should not be forced to depend on interfaces they don't use. In NestJS, this means keeping interfaces small and focused on specific capabilities rather than creating "fat" interfaces that bundle unrelated methods. When a service only needs to send emails, it shouldn't depend on an interface that also includes SMS, push notifications, and logging. Split large interfaces into role-based ones.
793 
794**Incorrect (fat interface forcing unused dependencies):**
795 
796```typescript
797// Fat interface - forces all consumers to depend on everything
798interface NotificationService {
799  sendEmail(to: string, subject: string, body: string): Promise<void>;
800  sendSms(phone: string, message: string): Promise<void>;
801  sendPush(userId: string, notification: PushPayload): Promise<void>;
802  sendSlack(channel: string, message: string): Promise<void>;
803  logNotification(type: string, payload: any): Promise<void>;
804  getDeliveryStatus(id: string): Promise<DeliveryStatus>;
805  retryFailed(id: string): Promise<void>;
806  scheduleNotification(dto: ScheduleDto): Promise<string>;
807}
808 
809// Consumer only needs email, but must mock everything for tests
810@Injectable()
811export class OrdersService {
812  constructor(
813    private notifications: NotificationService, // Depends on 8 methods, uses 1
814  ) {}
815 
816  async confirmOrder(order: Order): Promise<void> {
817    await this.notifications.sendEmail(
818      order.customer.email,
819      'Order Confirmed',
820      `Your order ${order.id} has been confirmed.`,
821    );
822  }
823}
824 
825// Testing is painful - must mock unused methods
826const mockNotificationService = {
827  sendEmail: jest.fn(),
828  sendSms: jest.fn(),           // Never used, but required
829  sendPush: jest.fn(),          // Never used, but required
830  sendSlack: jest.fn(),         // Never used, but required
831  logNotification: jest.fn(),   // Never used, but required
832  getDeliveryStatus: jest.fn(), // Never used, but required
833  retryFailed: jest.fn(),       // Never used, but required
834  scheduleNotification: jest.fn(), // Never used, but required
835};
836```
837 
838**Correct (segregated interfaces by capability):**
839 
840```typescript
841// Segregated interfaces - each focused on one capability
842interface EmailSender {
843  sendEmail(to: string, subject: string, body: string): Promise<void>;
844}
845 
846interface SmsSender {
847  sendSms(phone: string, message: string): Promise<void>;
848}
849 
850interface PushSender {
851  sendPush(userId: string, notification: PushPayload): Promise<void>;
852}
853 
854interface NotificationLogger {
855  logNotification(type: string, payload: any): Promise<void>;
856}
857 
858interface NotificationScheduler {
859  scheduleNotification(dto: ScheduleDto): Promise<string>;
860}
861 
862// Implementation can implement multiple interfaces
863@Injectable()
864export class NotificationService implements EmailSender, SmsSender, PushSender {
865  async sendEmail(to: string, subject: string, body: string): Promise<void> {
866    // Email implementation
867  }
868 
869  async sendSms(phone: string, message: string): Promise<void> {
870    // SMS implementation
871  }
872 
873  async sendPush(userId: string, notification: PushPayload): Promise<void> {
874    // Push implementation
875  }
876}
877 
878// Or separate implementations
879@Injectable()
880export class SendGridEmailService implements EmailSender {
881  async sendEmail(to: string, subject: string, body: string): Promise<void> {
882    // SendGrid-specific implementation
883  }
884}
885 
886// Consumer depends only on what it needs
887@Injectable()
888export class OrdersService {
889  constructor(
890    @Inject(EMAIL_SENDER) private emailSender: EmailSender, // Minimal dependency
891  ) {}
892 
893  async confirmOrder(order: Order): Promise<void> {
894    await this.emailSender.sendEmail(
895      order.customer.email,
896      'Order Confirmed',
897      `Your order ${order.id} has been confirmed.`,
898    );
899  }
900}
901 
902// Testing is simple - only mock what's used
903const mockEmailSender: EmailSender = {
904  sendEmail: jest.fn(),
905};
906 
907// Module registration with tokens
908export const EMAIL_SENDER = Symbol('EMAIL_SENDER');
909export const SMS_SENDER = Symbol('SMS_SENDER');
910 
911@Module({
912  providers: [
913    { provide: EMAIL_SENDER, useClass: SendGridEmailService },
914    { provide: SMS_SENDER, useClass: TwilioSmsService },
915  ],
916  exports: [EMAIL_SENDER, SMS_SENDER],
917})
918export class NotificationModule {}
919```
920 
921**Combining interfaces when needed:**
922 
923```typescript
924// Sometimes a consumer legitimately needs multiple capabilities
925interface EmailAndSmsSender extends EmailSender, SmsSender {}
926 
927// Or use intersection types
928type MultiChannelSender = EmailSender & SmsSender & PushSender;
929 
930// Consumer that genuinely needs multiple channels
931@Injectable()
932export class AlertService {
933  constructor(
934    @Inject(MULTI_CHANNEL_SENDER)
935    private sender: EmailSender & SmsSender,
936  ) {}
937 
938  async sendCriticalAlert(user: User, message: string): Promise<void> {
939    await Promise.all([
940      this.sender.sendEmail(user.email, 'Critical Alert', message),
941      this.sender.sendSms(user.phone, message),
942    ]);
943  }
944}
945```
946 
947Reference: [Interface Segregation Principle](https://en.wikipedia.org/wiki/Interface_segregation_principle)
948 
949---
950 
951### 2.3 Honor Liskov Substitution Principle
952 
953**Impact: HIGH** — Ensures implementations are truly interchangeable without breaking callers
954 
955Subtypes must be substitutable for their base types without altering program correctness. In NestJS with dependency injection, this means any implementation of an interface or abstract class must honor the contract completely. A mock payment service used in tests must behave like a real payment service (return similar shapes, handle errors the same way). Violating LSP causes subtle bugs when swapping implementations.
956 
957**Incorrect (implementation violates the contract):**
958 
959```typescript
960// Base interface with clear contract
961interface PaymentGateway {
962  /**
963   * Charges the specified amount.
964   * @returns PaymentResult on success
965   * @throws PaymentFailedException on payment failure
966   */
967  charge(amount: number, currency: string): Promise<PaymentResult>;
968}
969 
970// Production implementation - follows the contract
971@Injectable()
972export class StripeService implements PaymentGateway {
973  async charge(amount: number, currency: string): Promise<PaymentResult> {
974    const response = await this.stripe.charges.create({ amount, currency });
975    return { success: true, transactionId: response.id, amount };
976  }
977}
978 
979// Mock that violates LSP - different behavior!
980@Injectable()
981export class MockPaymentService implements PaymentGateway {
982  async charge(amount: number, currency: string): Promise<PaymentResult> {
983    // VIOLATION 1: Throws for valid input (contract says return PaymentResult)
984    if (amount > 1000) {
985      throw new Error('Mock does not support large amounts');
986    }
987 
988    // VIOLATION 2: Returns null instead of PaymentResult
989    if (currency !== 'USD') {
990      return null as any; // Real service would convert or reject properly
991    }
992 
993    // VIOLATION 3: Missing required field
994    return { success: true } as PaymentResult; // Missing transactionId!
995  }
996}
997 
998// Consumer trusts the contract
999@Injectable()
1000export class OrdersService {
1001  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
1002 
1003  async checkout(order: Order): Promise<void> {
1004    const result = await this.payment.charge(order.total, order.currency);
1005    // These fail with MockPaymentService:
1006    await this.saveTransaction(result.transactionId); // undefined!
1007    await this.sendReceipt(result); // might be null!
1008  }
1009}
1010```
1011 
1012**Correct (implementations honor the contract):**
1013 
1014```typescript
1015// Well-defined interface with documented behavior
1016interface PaymentGateway {
1017  /**
1018   * Charges the specified amount.
1019   * @param amount - Amount in smallest currency unit (cents)
1020   * @param currency - ISO 4217 currency code
1021   * @returns PaymentResult with transactionId, success status, and amount
1022   * @throws PaymentFailedException if charge is declined
1023   * @throws InvalidCurrencyException if currency is not supported
1024   */
1025  charge(amount: number, currency: string): Promise<PaymentResult>;
1026 
1027  /**
1028   * Refunds a previous charge.
1029   * @throws TransactionNotFoundException if transactionId is invalid
1030   */
1031  refund(transactionId: string, amount?: number): Promise<RefundResult>;
1032}
1033 
1034// Production implementation
1035@Injectable()
1036export class StripeService implements PaymentGateway {
1037  async charge(amount: number, currency: string): Promise<PaymentResult> {
1038    try {
1039      const response = await this.stripe.charges.create({ amount, currency });
1040      return {
1041        success: true,
1042        transactionId: response.id,
1043        amount: response.amount,
1044      };
1045    } catch (error) {
1046      if (error.type === 'card_error') {
1047        throw new PaymentFailedException(error.message);
1048      }
1049      throw error;
1050    }
1051  }
1052 
1053  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
1054    // Implementation...
1055  }
1056}
1057 
1058// Mock that honors LSP - same contract, same behavior shape
1059@Injectable()
1060export class MockPaymentService implements PaymentGateway {
1061  private transactions = new Map<string, PaymentResult>();
1062 
1063  async charge(amount: number, currency: string): Promise<PaymentResult> {
1064    // Honor the contract: validate currency like real service would
1065    if (!['USD', 'EUR', 'GBP'].includes(currency)) {
1066      throw new InvalidCurrencyException(`Unsupported currency: ${currency}`);
1067    }
1068 
1069    // Simulate decline for specific test scenarios
1070    if (amount === 99999) {
1071      throw new PaymentFailedException('Card declined (test scenario)');
1072    }
1073 
1074    // Return same shape as production
1075    const result: PaymentResult = {
1076      success: true,
1077      transactionId: `mock_${Date.now()}_${Math.random().toString(36)}`,
1078      amount,
1079    };
1080 
1081    this.transactions.set(result.transactionId, result);
1082    return result;
1083  }
1084 
1085  async refund(transactionId: string, amount?: number): Promise<RefundResult> {
1086    // Honor the contract: throw if transaction not found
1087    if (!this.transactions.has(transactionId)) {
1088      throw new TransactionNotFoundException(transactionId);
1089    }
1090 
1091    return {
1092      success: true,
1093      refundId: `refund_${transactionId}`,
1094      amount: amount ?? this.transactions.get(transactionId)!.amount,
1095    };
1096  }
1097}
1098 
1099// Consumer can swap implementations safely
1100@Injectable()
1101export class OrdersService {
1102  constructor(@Inject(PAYMENT_GATEWAY) private payment: PaymentGateway) {}
1103 
1104  async checkout(order: Order): Promise<Order> {
1105    try {
1106      const result = await this.payment.charge(order.total, order.currency);
1107      // Works with both StripeService and MockPaymentService
1108      order.transactionId = result.transactionId;
1109      order.status = 'paid';
1110      return order;
1111    } catch (error) {
1112      if (error instanceof PaymentFailedException) {
1113        order.status = 'payment_failed';
1114        return order;
1115      }
1116      throw error;
1117    }
1118  }
1119}
1120```
1121 
1122**Testing LSP compliance:**
1123 
1124```typescript
1125// Shared test suite that any implementation must pass
1126function testPaymentGatewayContract(
1127  createGateway: () => PaymentGateway,
1128) {
1129  describe('PaymentGateway contract', () => {
1130    let gateway: PaymentGateway;
1131 
1132    beforeEach(() => {
1133      gateway = createGateway();
1134    });
1135 
1136    it('returns PaymentResult with all required fields', async () => {
1137      const result = await gateway.charge(1000, 'USD');
1138      expect(result).toHaveProperty('success');
1139      expect(result).toHaveProperty('transactionId');
1140      expect(result).toHaveProperty('amount');
1141      expect(typeof result.transactionId).toBe('string');
1142    });
1143 
1144    it('throws InvalidCurrencyException for unsupported currency', async () => {
1145      await expect(gateway.charge(1000, 'INVALID'))
1146        .rejects.toThrow(InvalidCurrencyException);
1147    });
1148 
1149    it('throws TransactionNotFoundException for invalid refund', async () => {
1150      await expect(gateway.refund('nonexistent'))
1151        .rejects.toThrow(TransactionNotFoundException);
1152    });
1153  });
1154}
1155 
1156// Run against all implementations
1157describe('StripeService', () => {
1158  testPaymentGatewayContract(() => new StripeService(mockStripeClient));
1159});
1160 
1161describe('MockPaymentService', () => {
1162  testPaymentGatewayContract(() => new MockPaymentService());
1163});
1164```
1165 
1166Reference: [Liskov Substitution Principle](https://en.wikipedia.org/wiki/Liskov_substitution_principle)
1167 
1168---
1169 
1170### 2.4 Prefer Constructor Injection
1171 
1172**Impact: CRITICAL** — Required for proper DI and testing
1173 
1174Always use constructor injection over property injection. Constructor injection makes dependencies explicit, enables TypeScript type checking, ensures dependencies are available when the class is instantiated, and improves testability. This is required for proper DI, testing, and TypeScript support.
1175 
1176**Incorrect (property injection with hidden dependencies):**
1177 
1178```typescript
1179// Property injection - avoid unless necessary
1180@Injectable()
1181export class UsersService {
1182  @Inject()
1183  private userRepo: UserRepository; // Hidden dependency
1184 
1185  @Inject('CONFIG')
1186  private config: ConfigType; // Also hidden
1187 
1188  async findAll() {
1189    return this.userRepo.find();
1190  }
1191}
1192 
1193// Problems:
1194// 1. Dependencies not visible in constructor
1195// 2. Service can be instantiated without dependencies in tests
1196// 3. TypeScript can't enforce dependency types at instantiation
1197```
1198 
1199**Correct (constructor injection with explicit dependencies):**
1200 
1201```typescript
1202// Constructor injection - explicit and testable
1203@Injectable()
1204export class UsersService {
1205  constructor(
1206    private readonly userRepo: UserRepository,
1207    @Inject('CONFIG') private readonly config: ConfigType,
1208  ) {}
1209 
1210  async findAll(): Promise<User[]> {
1211    return this.userRepo.find();
1212  }
1213}
1214 
1215// Testing is straightforward
1216describe('UsersService', () => {
1217  let service: UsersService;
1218  let mockRepo: jest.Mocked<UserRepository>;
1219 
1220  beforeEach(() => {
1221    mockRepo = {
1222      find: jest.fn(),
1223      save: jest.fn(),
1224    } as any;
1225 
1226    service = new UsersService(mockRepo, { dbUrl: 'test' });
1227  });
1228 
1229  it('should find all users', async () => {
1230    mockRepo.find.mockResolvedValue([{ id: '1', name: 'Test' }]);
1231    const result = await service.findAll();
1232    expect(result).toHaveLength(1);
1233  });
1234});
1235 
1236// Only use property injection for optional dependencies
1237@Injectable()
1238export class LoggingService {
1239  @Optional()
1240  @Inject('ANALYTICS')
1241  private analytics?: AnalyticsService;
1242 
1243  log(message: string) {
1244    console.log(message);
1245    this.analytics?.track('log', message); // Optional enhancement
1246  }
1247}
1248```
1249 
1250Reference: [NestJS Providers](https://docs.nestjs.com/providers)
1251 
1252---
1253 
1254### 2.5 Understand Provider Scopes
1255 
1256**Impact: CRITICAL** — Prevents data leaks and performance issues
1257 
1258NestJS has three provider scopes: DEFAULT (singleton), REQUEST (per-request instance), and TRANSIENT (new instance for each injection). Most providers should be singletons. Request-scoped providers have performance implications as they bubble up through the dependency tree. Understanding scopes prevents memory leaks and incorrect data sharing.
1259 
1260**Incorrect (wrong scope usage):**
1261 
1262```typescript
1263// Request-scoped when not needed (performance hit)
1264@Injectable({ scope: Scope.REQUEST })
1265export class UsersService {
1266  // This creates a new instance for EVERY request
1267  // All dependencies also become request-scoped
1268  async findAll() {
1269    return this.userRepo.find();
1270  }
1271}
1272 
1273// Singleton with mutable request state
1274@Injectable() // Default: singleton
1275export class RequestContextService {
1276  private userId: string; // DANGER: Shared across all requests!
1277 
1278  setUser(userId: string) {
1279    this.userId = userId; // Overwrites for all concurrent requests
1280  }
1281 
1282  getUser() {
1283    return this.userId; // Returns wrong user!
1284  }
1285}
1286```
1287 
1288**Correct (appropriate scope for each use case):**
1289 
1290```typescript
1291// Singleton for stateless services (default, most common)
1292@Injectable()
1293export class UsersService {
1294  constructor(private readonly userRepo: UserRepository) {}
1295 
1296  async findById(id: string): Promise<User> {
1297    return this.userRepo.findOne({ where: { id } });
1298  }
1299}
1300 
1301// Request-scoped ONLY when you need request context
1302@Injectable({ scope: Scope.REQUEST })
1303export class RequestContextService {
1304  private userId: string;
1305 
1306  setUser(userId: string) {
1307    this.userId = userId;
1308  }
1309 
1310  getUser(): string {
1311    return this.userId;
1312  }
1313}
1314 
1315// Better: Use NestJS built-in request context
1316import { REQUEST } from '@nestjs/core';
1317import { Request } from 'express';
1318 
1319@Injectable({ scope: Scope.REQUEST })
1320export class AuditService {
1321  constructor(@Inject(REQUEST) private request: Request) {}
1322 
1323  log(action: string) {
1324    console.log(`User ${this.request.user?.id} performed ${action}`);
1325  }
1326}
1327 
1328// Best: Use ClsModule for async context (no scope bubble-up)
1329import { ClsService } from 'nestjs-cls';
1330 
1331@Injectable() // Stays singleton!
1332export class AuditService {
1333  constructor(private cls: ClsService) {}
1334 
1335  log(action: string) {
1336    const userId = this.cls.get('userId');
1337    console.log(`User ${userId} performed ${action}`);
1338  }
1339}
1340```
1341 
1342Reference: [NestJS Injection Scopes](https://docs.nestjs.com/fundamentals/injection-scopes)
1343 
1344---
1345 
1346### 2.6 Use Injection Tokens for Interfaces
1347 
1348**Impact: HIGH** — Enables interface-based DI at runtime
1349 
1350TypeScript interfaces are erased at compile time and can't be used as injection tokens. Use string tokens, symbols, or abstract classes when you want to inject implementations of interfaces. This enables swapping implementations for testing or different environments.
1351 
1352**Incorrect (interface can't be used as token):**
1353 
1354```typescript
1355// Interface can't be used as injection token
1356interface PaymentGateway {
1357  charge(amount: number): Promise<PaymentResult>;
1358}
1359 
1360@Injectable()
1361export class StripeService implements PaymentGateway {
1362  charge(amount: number) { /* ... */ }
1363}
1364 
1365@Injectable()
1366export class OrdersService {
1367  // This WON'T work - PaymentGateway doesn't exist at runtime
1368  constructor(private payment: PaymentGateway) {}
1369}
1370```
1371 
1372**Correct (symbol tokens or abstract classes):**
1373 
1374```typescript
1375// Option 1: String/Symbol tokens (most flexible)
1376export const PAYMENT_GATEWAY = Symbol('PAYMENT_GATEWAY');
1377 
1378export interface PaymentGateway {
1379  charge(amount: number): Promise<PaymentResult>;
1380}
1381 
1382@Injectable()
1383export class StripeService implements PaymentGateway {
1384  async charge(amount: number): Promise<PaymentResult> {
1385    // Stripe implementation
1386  }
1387}
1388 
1389@Injectable()
1390export class MockPaymentService implements PaymentGateway {
1391  async charge(amount: number): Promise<PaymentResult> {
1392    return { success: true, id: 'mock-id' };
1393  }
1394}
1395 
1396// Module registration
1397@Module({
1398  providers: [
1399    {
1400      provide: PAYMENT_GATEWAY,
1401      useClass: process.env.NODE_ENV === 'test'
1402        ? MockPaymentService
1403        : StripeService,
1404    },
1405  ],
1406  exports: [PAYMENT_GATEWAY],
1407})
1408export class PaymentModule {}
1409 
1410// Injection
1411@Injectable()
1412export class OrdersService {
1413  constructor(
1414    @Inject(PAYMENT_GATEWAY) private payment: PaymentGateway,
1415  ) {}
1416 
1417  async createOrder(dto: CreateOrderDto) {
1418    await this.payment.charge(dto.amount);
1419  }
1420}
1421 
1422// Option 2: Abstract class (carries runtime type info)
1423export abstract class PaymentGateway {
1424  abstract charge(amount: number): Promise<PaymentResult>;
1425}
1426 
1427@Injectable()
1428export class StripeService extends PaymentGateway {
1429  async charge(amount: number): Promise<PaymentResult> {
1430    // Implementation
1431  }
1432}
1433 
1434// No @Inject needed with abstract class
1435@Injectable()
1436export class OrdersService {
1437  constructor(private payment: PaymentGateway) {}
1438}
1439```
1440 
1441Reference: [NestJS Custom Providers](https://docs.nestjs.com/fundamentals/custom-providers)
1442 
1443---
1444 
1445## 3. Error Handling
1446 
1447**Section Impact: HIGH**
1448 
1449### 3.1 Handle Async Errors Properly
1450 
1451**Impact: HIGH** — Prevents process crashes from unhandled rejections
1452 
1453NestJS automatically catches errors from async route handlers, but errors from background tasks, event handlers, and manually created promises can crash your application. Always handle async errors explicitly and use global handlers as a safety net.
1454 
1455**Incorrect (fire-and-forget without error handling):**
1456 
1457```typescript
1458// Fire-and-forget without error handling
1459@Injectable()
1460export class UsersService {
1461  async createUser(dto: CreateUserDto): Promise<User> {
1462    const user = await this.repo.save(dto);
1463 
1464    // Fire and forget - if this fails, error is unhandled!
1465    this.emailService.sendWelcome(user.email);
1466 
1467    return user;
1468  }
1469}
1470 
1471// Unhandled promise in event handler
1472@Injectable()
1473export class OrdersService {
1474  @OnEvent('order.created')
1475  handleOrderCreated(event: OrderCreatedEvent) {
1476    // This returns a promise but it's not awaited!
1477    this.processOrder(event);
1478    // Errors will crash the process
1479  }
1480 
1481  private async processOrder(event: OrderCreatedEvent): Promise<void> {
1482    await this.inventoryService.reserve(event.items);
1483    await this.notificationService.send(event.userId);
1484  }
1485}
1486 
1487// Missing try-catch in scheduled tasks
1488@Cron('0 0 * * *')
1489async dailyCleanup(): Promise<void> {
1490  await this.cleanupService.run();
1491  // If this throws, no error handling
1492}
1493```
1494 
1495**Correct (explicit async error handling):**
1496 
1497```typescript
1498// Handle fire-and-forget with explicit catch
1499@Injectable()
1500export class UsersService {
1501  private readonly logger = new Logger(UsersService.name);
1502 
1503  async createUser(dto: CreateUserDto): Promise<User> {
1504    const user = await this.repo.save(dto);
1505 
1506    // Explicitly catch and log errors
1507    this.emailService.sendWelcome(user.email).catch((error) => {
1508      this.logger.error('Failed to send welcome email', error.stack);
1509      // Optionally queue for retry
1510    });
1511 
1512    return user;
1513  }
1514}
1515 
1516// Properly handle async event handlers
1517@Injectable()
1518export class OrdersService {
1519  private readonly logger = new Logger(OrdersService.name);
1520 
1521  @OnEvent('order.created')
1522  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
1523    try {
1524      await this.processOrder(event);
1525    } catch (error) {
1526      this.logger.error('Failed to process order', { event, error });
1527      // Don't rethrow - would crash the process
1528      await this.deadLetterQueue.add('order.created', event);
1529    }
1530  }
1531}
1532 
1533// Safe scheduled tasks
1534@Injectable()
1535export class CleanupService {
1536  private readonly logger = new Logger(CleanupService.name);
1537 
1538  @Cron('0 0 * * *')
1539  async dailyCleanup(): Promise<void> {
1540    try {
1541      await this.cleanupService.run();
1542      this.logger.log('Daily cleanup completed');
1543    } catch (error) {
1544      this.logger.error('Daily cleanup failed', error.stack);
1545      // Alert or retry logic
1546    }
1547  }
1548}
1549 
1550// Global unhandled rejection handler in main.ts
1551async function bootstrap() {
1552  const app = await NestFactory.create(AppModule);
1553  const logger = new Logger('Bootstrap');
1554 
1555  process.on('unhandledRejection', (reason, promise) => {
1556    logger.error('Unhandled Rejection at:', promise, 'reason:', reason);
1557  });
1558 
1559  process.on('uncaughtException', (error) => {
1560    logger.error('Uncaught Exception:', error);
1561    process.exit(1);
1562  });
1563 
1564  await app.listen(3000);
1565}
1566```
1567 
1568Reference: [Node.js Unhandled Rejections](https://nodejs.org/api/process.html#event-unhandledrejection)
1569 
1570---
1571 
1572### 3.2 Throw HTTP Exceptions from Services
1573 
1574**Impact: HIGH** — Keeps controllers thin and simplifies error handling
1575 
1576It's acceptable (and often preferable) to throw `HttpException` subclasses from services in HTTP applications. This keeps controllers thin and allows services to communicate appropriate error states. For truly layer-agnostic services, use domain exceptions that map to HTTP status codes.
1577 
1578**Incorrect (return error objects instead of throwing):**
1579 
1580```typescript
1581// Return error objects instead of throwing
1582@Injectable()
1583export class UsersService {
1584  async findById(id: string): Promise<{ user?: User; error?: string }> {
1585    const user = await this.repo.findOne({ where: { id } });
1586    if (!user) {
1587      return { error: 'User not found' }; // Controller must check this
1588    }
1589    return { user };
1590  }
1591}
1592 
1593@Controller('users')
1594export class UsersController {
1595  @Get(':id')
1596  async findOne(@Param('id') id: string) {
1597    const result = await this.usersService.findById(id);
1598    if (result.error) {
1599      throw new NotFoundException(result.error);
1600    }
1601    return result.user;
1602  }
1603}
1604```
1605 
1606**Correct (throw exceptions directly from service):**
1607 
1608```typescript
1609// Throw exceptions directly from service
1610@Injectable()
1611export class UsersService {
1612  constructor(private readonly repo: UserRepository) {}
1613 
1614  async findById(id: string): Promise<User> {
1615    const user = await this.repo.findOne({ where: { id } });
1616    if (!user) {
1617      throw new NotFoundException(`User #${id} not found`);
1618    }
1619    return user;
1620  }
1621 
1622  async create(dto: CreateUserDto): Promise<User> {
1623    const existing = await this.repo.findOne({
1624      where: { email: dto.email },
1625    });
1626    if (existing) {
1627      throw new ConflictException('Email already registered');
1628    }
1629    return this.repo.save(dto);
1630  }
1631 
1632  async update(id: string, dto: UpdateUserDto): Promise<User> {
1633    const user = await this.findById(id); // Throws if not found
1634    Object.assign(user, dto);
1635    return this.repo.save(user);
1636  }
1637}
1638 
1639// Controller stays thin
1640@Controller('users')
1641export class UsersController {
1642  @Get(':id')
1643  findOne(@Param('id') id: string): Promise<User> {
1644    return this.usersService.findById(id);
1645  }
1646 
1647  @Post()
1648  create(@Body() dto: CreateUserDto): Promise<User> {
1649    return this.usersService.create(dto);
1650  }
1651}
1652 
1653// For layer-agnostic services, use domain exceptions
1654export class EntityNotFoundException extends Error {
1655  constructor(
1656    public readonly entity: string,
1657    public readonly id: string,
1658  ) {
1659    super(`${entity} with ID "${id}" not found`);
1660  }
1661}
1662 
1663// Map to HTTP in exception filter
1664@Catch(EntityNotFoundException)
1665export class EntityNotFoundFilter implements ExceptionFilter {
1666  catch(exception: EntityNotFoundException, host: ArgumentsHost) {
1667    const ctx = host.switchToHttp();
1668    const response = ctx.getResponse<Response>();
1669 
1670    response.status(404).json({
1671      statusCode: 404,
1672      message: exception.message,
1673      entity: exception.entity,
1674      id: exception.id,
1675    });
1676  }
1677}
1678```
1679 
1680Reference: [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)
1681 
1682---
1683 
1684### 3.3 Use Exception Filters for Error Handling
1685 
1686**Impact: HIGH** — Consistent, centralized error handling
1687 
1688Never catch exceptions and manually format error responses in controllers. Use NestJS exception filters to handle errors consistently across your application. Create custom exception filters for specific error types and a global filter for unhandled exceptions.
1689 
1690**Incorrect (manual error handling in controllers):**
1691 
1692```typescript
1693// Manual error handling in controllers
1694@Controller('users')
1695export class UsersController {
1696  @Get(':id')
1697  async findOne(@Param('id') id: string, @Res() res: Response) {
1698    try {
1699      const user = await this.usersService.findById(id);
1700      if (!user) {
1701        return res.status(404).json({
1702          statusCode: 404,
1703          message: 'User not found',
1704        });
1705      }
1706      return res.json(user);
1707    } catch (error) {
1708      console.error(error);
1709      return res.status(500).json({
1710        statusCode: 500,
1711        message: 'Internal server error',
1712      });
1713    }
1714  }
1715}
1716```
1717 
1718**Correct (exception filters with consistent handling):**
1719 
1720```typescript
1721// Use built-in and custom exceptions
1722@Controller('users')
1723export class UsersController {
1724  @Get(':id')
1725  async findOne(@Param('id') id: string): Promise<User> {
1726    const user = await this.usersService.findById(id);
1727    if (!user) {
1728      throw new NotFoundException(`User #${id} not found`);
1729    }
1730    return user;
1731  }
1732}
1733 
1734// Custom domain exception
1735export class UserNotFoundException extends NotFoundException {
1736  constructor(userId: string) {
1737    super({
1738      statusCode: 404,
1739      error: 'Not Found',
1740      message: `User with ID "${userId}" not found`,
1741      code: 'USER_NOT_FOUND',
1742    });
1743  }
1744}
1745 
1746// Custom exception filter for domain errors
1747@Catch(DomainException)
1748export class DomainExceptionFilter implements ExceptionFilter {
1749  catch(exception: DomainException, host: ArgumentsHost) {
1750    const ctx = host.switchToHttp();
1751    const response = ctx.getResponse<Response>();
1752    const request = ctx.getRequest<Request>();
1753 
1754    const status = exception.getStatus?.() || 400;
1755 
1756    response.status(status).json({
1757      statusCode: status,
1758      code: exception.code,
1759      message: exception.message,
1760      timestamp: new Date().toISOString(),
1761      path: request.url,
1762    });
1763  }
1764}
1765 
1766// Global exception filter for unhandled errors
1767@Catch()
1768export class AllExceptionsFilter implements ExceptionFilter {
1769  constructor(private readonly logger: Logger) {}
1770 
1771  catch(exception: unknown, host: ArgumentsHost) {
1772    const ctx = host.switchToHttp();
1773    const response = ctx.getResponse<Response>();
1774    const request = ctx.getRequest<Request>();
1775 
1776    const status =
1777      exception instanceof HttpException
1778        ? exception.getStatus()
1779        : HttpStatus.INTERNAL_SERVER_ERROR;
1780 
1781    const message =
1782      exception instanceof HttpException
1783        ? exception.message
1784        : 'Internal server error';
1785 
1786    this.logger.error(
1787      `${request.method} ${request.url}`,
1788      exception instanceof Error ? exception.stack : exception,
1789    );
1790 
1791    response.status(status).json({
1792      statusCode: status,
1793      message,
1794      timestamp: new Date().toISOString(),
1795      path: request.url,
1796    });
1797  }
1798}
1799 
1800// Register globally in main.ts
1801app.useGlobalFilters(
1802  new AllExceptionsFilter(app.get(Logger)),
1803  new DomainExceptionFilter(),
1804);
1805 
1806// Or via module
1807@Module({
1808  providers: [
1809    {
1810      provide: APP_FILTER,
1811      useClass: AllExceptionsFilter,
1812    },
1813  ],
1814})
1815export class AppModule {}
1816```
1817 
1818Reference: [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)
1819 
1820---
1821 
1822## 4. Security
1823 
1824**Section Impact: HIGH**
1825 
1826### 4.1 Implement Secure JWT Authentication
1827 
1828**Impact: CRITICAL** — Essential for secure APIs
1829 
1830Use `@nestjs/jwt` with `@nestjs/passport` for authentication. Store secrets securely, use appropriate token lifetimes, implement refresh tokens, and validate tokens properly. Never expose sensitive data in JWT payloads.
1831 
1832**Incorrect (insecure JWT implementation):**
1833 
1834```typescript
1835// Hardcode secrets
1836@Module({
1837  imports: [
1838    JwtModule.register({
1839      secret: 'my-secret-key', // Exposed in code
1840      signOptions: { expiresIn: '7d' }, // Too long
1841    }),
1842  ],
1843})
1844export class AuthModule {}
1845 
1846// Store sensitive data in JWT
1847async login(user: User): Promise<{ accessToken: string }> {
1848  const payload = {
1849    sub: user.id,
1850    email: user.email,
1851    password: user.password, // NEVER include password!
1852    ssn: user.ssn, // NEVER include sensitive data!
1853    isAdmin: user.isAdmin, // Can be tampered if not verified
1854  };
1855  return { accessToken: this.jwtService.sign(payload) };
1856}
1857 
1858// Skip token validation
1859@Injectable()
1860export class JwtStrategy extends PassportStrategy(Strategy) {
1861  constructor() {
1862    super({
1863      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
1864      secretOrKey: 'my-secret',
1865    });
1866  }
1867 
1868  async validate(payload: any): Promise<any> {
1869    return payload; // No validation of user existence
1870  }
1871}
1872```
1873 
1874**Correct (secure JWT with refresh tokens):**
1875 
1876```typescript
1877// Secure JWT configuration
1878@Module({
1879  imports: [
1880    JwtModule.registerAsync({
1881      imports: [ConfigModule],
1882      inject: [ConfigService],
1883      useFactory: (config: ConfigService) => ({
1884        secret: config.get<string>('JWT_SECRET'),
1885        signOptions: {
1886          expiresIn: '15m', // Short-lived access tokens
1887          issuer: config.get<string>('JWT_ISSUER'),
1888          audience: config.get<string>('JWT_AUDIENCE'),
1889        },
1890      }),
1891    }),
1892    PassportModule.register({ defaultStrategy: 'jwt' }),
1893  ],
1894})
1895export class AuthModule {}
1896 
1897// Minimal JWT payload
1898@Injectable()
1899export class AuthService {
1900  async login(user: User): Promise<TokenResponse> {
1901    // Only include necessary, non-sensitive data
1902    const payload: JwtPayload = {
1903      sub: user.id,
1904      email: user.email,
1905      roles: user.roles,
1906      iat: Math.floor(Date.now() / 1000),
1907    };
1908 
1909    const accessToken = this.jwtService.sign(payload);
1910    const refreshToken = await this.createRefreshToken(user.id);
1911 
1912    return { accessToken, refreshToken, expiresIn: 900 };
1913  }
1914 
1915  private async createRefreshToken(userId: string): Promise<string> {
1916    const token = randomBytes(32).toString('hex');
1917    const hashedToken = await bcrypt.hash(token, 10);
1918 
1919    await this.refreshTokenRepo.save({
1920      userId,
1921      token: hashedToken,
1922      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
1923    });
1924 
1925    return token;
1926  }
1927}
1928 
1929// Proper JWT strategy with validation
1930@Injectable()
1931export class JwtStrategy extends PassportStrategy(Strategy) {
1932  constructor(
1933    private config: ConfigService,
1934    private usersService: UsersService,
1935  ) {
1936    super({
1937      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
1938      secretOrKey: config.get<string>('JWT_SECRET'),
1939      ignoreExpiration: false,
1940      issuer: config.get<string>('JWT_ISSUER'),
1941      audience: config.get<string>('JWT_AUDIENCE'),
1942    });
1943  }
1944 
1945  async validate(payload: JwtPayload): Promise<User> {
1946    // Verify user still exists and is active
1947    const user = await this.usersService.findById(payload.sub);
1948 
1949    if (!user || !user.isActive) {
1950      throw new UnauthorizedException('User not found or inactive');
1951    }
1952 
1953    // Verify token wasn't issued before password change
1954    if (user.passwordChangedAt) {
1955      const tokenIssuedAt = new Date(payload.iat * 1000);
1956      if (tokenIssuedAt < user.passwordChangedAt) {
1957        throw new UnauthorizedException('Token invalidated by password change');
1958      }
1959    }
1960 
1961    return user;
1962  }
1963}
1964```
1965 
1966Reference: [NestJS Authentication](https://docs.nestjs.com/security/authentication)
1967 
1968---
1969 
1970### 4.2 Implement Rate Limiting
1971 
1972**Impact: HIGH** — Protects against abuse and ensures fair resource usage
1973 
1974Use `@nestjs/throttler` to limit request rates per client. Apply different limits for different endpoints - stricter for auth endpoints, more relaxed for read operations. Consider using Redis for distributed rate limiting in clustered deployments.
1975 
1976**Incorrect (no rate limiting on sensitive endpoints):**
1977 
1978```typescript
1979// No rate limiting on sensitive endpoints
1980@Controller('auth')
1981export class AuthController {
1982  @Post('login')
1983  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
1984    // Attackers can brute-force credentials
1985    return this.authService.login(dto);
1986  }
1987 
1988  @Post('forgot-password')
1989  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
1990    // Can be abused to spam users with emails
1991    return this.authService.sendResetEmail(dto.email);
1992  }
1993}
1994 
1995// Same limits for all endpoints
1996@UseGuards(ThrottlerGuard)
1997@Controller('api')
1998export class ApiController {
1999  @Get('public-data')
2000  async getPublic() {} // Should allow more requests
2001 
2002  @Post('process-payment')
2003  async payment() {} // Should be more restrictive
2004}
2005```
2006 
2007**Correct (configured throttler with endpoint-specific limits):**
2008 
2009```typescript
2010// Configure throttler globally with multiple limits
2011import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
2012 
2013@Module({
2014  imports: [
2015    ThrottlerModule.forRoot([
2016      {
2017        name: 'short',
2018        ttl: 1000, // 1 second
2019        limit: 3, // 3 requests per second
2020      },
2021      {
2022        name: 'medium',
2023        ttl: 10000, // 10 seconds
2024        limit: 20, // 20 requests per 10 seconds
2025      },
2026      {
2027        name: 'long',
2028        ttl: 60000, // 1 minute
2029        limit: 100, // 100 requests per minute
2030      },
2031    ]),
2032  ],
2033  providers: [
2034    {
2035      provide: APP_GUARD,
2036      useClass: ThrottlerGuard,
2037    },
2038  ],
2039})
2040export class AppModule {}
2041 
2042// Override limits per endpoint
2043@Controller('auth')
2044export class AuthController {
2045  @Post('login')
2046  @Throttle({ short: { limit: 5, ttl: 60000 } }) // 5 attempts per minute
2047  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
2048    return this.authService.login(dto);
2049  }
2050 
2051  @Post('forgot-password')
2052  @Throttle({ short: { limit: 3, ttl: 3600000 } }) // 3 per hour
2053  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
2054    return this.authService.sendResetEmail(dto.email);
2055  }
2056}
2057 
2058// Skip throttling for certain routes
2059@Controller('health')
2060export class HealthController {
2061  @Get()
2062  @SkipThrottle()
2063  check(): string {
2064    return 'OK';
2065  }
2066}
2067 
2068// Custom throttle per user type
2069@Injectable()
2070export class CustomThrottlerGuard extends ThrottlerGuard {
2071  protected async getTracker(req: Request): Promise<string> {
2072    // Use user ID if authenticated, IP otherwise
2073    return req.user?.id || req.ip;
2074  }
2075 
2076  protected async getLimit(context: ExecutionContext): Promise<number> {
2077    const request = context.switchToHttp().getRequest();
2078 
2079    // Higher limits for authenticated users
2080    if (request.user) {
2081      return request.user.isPremium ? 1000 : 200;
2082    }
2083 
2084    return 50; // Anonymous users
2085  }
2086}
2087```
2088 
2089Reference: [NestJS Throttler](https://docs.nestjs.com/security/rate-limiting)
2090 
2091---
2092 
2093### 4.3 Sanitize Output to Prevent XSS
2094 
2095**Impact: HIGH** — XSS vulnerabilities can compromise user sessions and data
2096 
2097While NestJS APIs typically return JSON (which browsers don't execute), XSS risks exist when rendering HTML, storing user content, or when frontend frameworks improperly handle API responses. Sanitize user-generated content before storage and use proper Content-Type headers.
2098 
2099**Incorrect (storing raw HTML without sanitization):**
2100 
2101```typescript
2102// Store raw HTML from users
2103@Injectable()
2104export class CommentsService {
2105  async create(dto: CreateCommentDto): Promise<Comment> {
2106    // User can inject: <script>steal(document.cookie)</script>
2107    return this.repo.save({
2108      content: dto.content, // Raw, unsanitized
2109      authorId: dto.authorId,
2110    });
2111  }
2112}
2113 
2114// Return HTML without sanitization
2115@Controller('pages')
2116export class PagesController {
2117  @Get(':slug')
2118  @Header('Content-Type', 'text/html')
2119  async getPage(@Param('slug') slug: string): Promise<string> {
2120    const page = await this.pagesService.findBySlug(slug);
2121    // If page.content contains user input, XSS is possible
2122    return `<html><body>${page.content}</body></html>`;
2123  }
2124}
2125 
2126// Reflect user input in errors
2127@Get(':id')
2128async findOne(@Param('id') id: string): Promise<User> {
2129  const user = await this.repo.findOne({ where: { id } });
2130  if (!user) {
2131    // XSS if id contains malicious content and error is rendered
2132    throw new NotFoundException(`User ${id} not found`);
2133  }
2134  return user;
2135}
2136```
2137 
2138**Correct (sanitize content and use proper headers):**
2139 
2140```typescript
2141// Sanitize HTML content before storage
2142import * as sanitizeHtml from 'sanitize-html';
2143 
2144@Injectable()
2145export class CommentsService {
2146  private readonly sanitizeOptions: sanitizeHtml.IOptions = {
2147    allowedTags: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
2148    allowedAttributes: {
2149      a: ['href', 'title'],
2150    },
2151    allowedSchemes: ['http', 'https', 'mailto'],
2152  };
2153 
2154  async create(dto: CreateCommentDto): Promise<Comment> {
2155    return this.repo.save({
2156      content: sanitizeHtml(dto.content, this.sanitizeOptions),
2157      authorId: dto.authorId,
2158    });
2159  }
2160}
2161 
2162// Use validation pipe to strip HTML
2163import { Transform } from 'class-transformer';
2164 
2165export class CreatePostDto {
2166  @IsString()
2167  @MaxLength(1000)
2168  @Transform(({ value }) => sanitizeHtml(value, { allowedTags: [] }))
2169  title: string;
2170 
2171  @IsString()
2172  @Transform(({ value }) =>
2173    sanitizeHtml(value, {
2174      allowedTags: ['p', 'br', 'b', 'i', 'a'],
2175      allowedAttributes: { a: ['href'] },
2176    }),
2177  )
2178  content: string;
2179}
2180 
2181// Set proper Content-Type headers
2182@Controller('api')
2183export class ApiController {
2184  @Get('data')
2185  @Header('Content-Type', 'application/json')
2186  async getData(): Promise<DataResponse> {
2187    // JSON response - browser won't execute scripts
2188    return this.service.getData();
2189  }
2190}
2191 
2192// Sanitize error messages
2193@Get(':id')
2194async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
2195  const user = await this.repo.findOne({ where: { id } });
2196  if (!user) {
2197    // UUID validation ensures safe format
2198    throw new NotFoundException('User not found');
2199  }
2200  return user;
2201}
2202 
2203// Use Helmet for CSP headers
2204import helmet from 'helmet';
2205 
2206async function bootstrap() {
2207  const app = await NestFactory.create(AppModule);
2208 
2209  app.use(
2210    helmet({
2211      contentSecurityPolicy: {
2212        directives: {
2213          defaultSrc: ["'self'"],
2214          scriptSrc: ["'self'"],
2215          styleSrc: ["'self'", "'unsafe-inline'"],
2216          imgSrc: ["'self'", 'data:', 'https:'],
2217        },
2218      },
2219    }),
2220  );
2221 
2222  await app.listen(3000);
2223}
2224```
2225 
2226Reference: [OWASP XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
2227 
2228---
2229 
2230### 4.4 Use Guards for Authentication and Authorization
2231 
2232**Impact: HIGH** — Enforces access control before handlers execute
2233 
2234Guards determine whether a request should be handled based on authentication state, roles, permissions, or other conditions. They run after middleware but before pipes and interceptors, making them ideal for access control. Use guards instead of manual checks in controllers.
2235 
2236**Incorrect (manual auth checks in every handler):**
2237 
2238```typescript
2239// Manual auth checks in every handler
2240@Controller('admin')
2241export class AdminController {
2242  @Get('users')
2243  async getUsers(@Request() req) {
2244    if (!req.user) {
2245      throw new UnauthorizedException();
2246    }
2247    if (!req.user.roles.includes('admin')) {
2248      throw new ForbiddenException();
2249    }
2250    return this.adminService.getUsers();
2251  }
2252 
2253  @Delete('users/:id')
2254  async deleteUser(@Request() req, @Param('id') id: string) {
2255    if (!req.user) {
2256      throw new UnauthorizedException();
2257    }
2258    if (!req.user.roles.includes('admin')) {
2259      throw new ForbiddenException();
2260    }
2261    return this.adminService.deleteUser(id);
2262  }
2263}
2264```
2265 
2266**Correct (guards with declarative decorators):**
2267 
2268```typescript
2269// JWT Auth Guard
2270@Injectable()
2271export class JwtAuthGuard implements CanActivate {
2272  constructor(
2273    private jwtService: JwtService,
2274    private reflector: Reflector,
2275  ) {}
2276 
2277  async canActivate(context: ExecutionContext): Promise<boolean> {
2278    // Check for @Public() decorator
2279    const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [
2280      context.getHandler(),
2281      context.getClass(),
2282    ]);
2283    if (isPublic) return true;
2284 
2285    const request = context.switchToHttp().getRequest();
2286    const token = this.extractToken(request);
2287 
2288    if (!token) {
2289      throw new UnauthorizedException('No token provided');
2290    }
2291 
2292    try {
2293      request.user = await this.jwtService.verifyAsync(token);
2294      return true;
2295    } catch {
2296      throw new UnauthorizedException('Invalid token');
2297    }
2298  }
2299 
2300  private extractToken(request: Request): string | undefined {
2301    const [type, token] = request.headers.authorization?.split(' ') ?? [];
2302    return type === 'Bearer' ? token : undefined;
2303  }
2304}
2305 
2306// Roles Guard
2307@Injectable()
2308export class RolesGuard implements CanActivate {
2309  constructor(private reflector: Reflector) {}
2310 
2311  canActivate(context: ExecutionContext): boolean {
2312    const requiredRoles = this.reflector.getAllAndOverride<Role[]>('roles', [
2313      context.getHandler(),
2314      context.getClass(),
2315    ]);
2316 
2317    if (!requiredRoles) return true;
2318 
2319    const { user } = context.switchToHttp().getRequest();
2320    return requiredRoles.some((role) => user.roles?.includes(role));
2321  }
2322}
2323 
2324// Decorators
2325export const Public = () => SetMetadata('isPublic', true);
2326export const Roles = (...roles: Role[]) => SetMetadata('roles', roles);
2327 
2328// Register guards globally
2329@Module({
2330  providers: [
2331    { provide: APP_GUARD, useClass: JwtAuthGuard },
2332    { provide: APP_GUARD, useClass: RolesGuard },
2333  ],
2334})
2335export class AppModule {}
2336 
2337// Clean controller
2338@Controller('admin')
2339@Roles(Role.Admin) // Applied to all routes
2340export class AdminController {
2341  @Get('users')
2342  getUsers(): Promise<User[]> {
2343    return this.adminService.getUsers();
2344  }
2345 
2346  @Delete('users/:id')
2347  deleteUser(@Param('id') id: string): Promise<void> {
2348    return this.adminService.deleteUser(id);
2349  }
2350 
2351  @Public() // Override: no auth required
2352  @Get('health')
2353  health() {
2354    return { status: 'ok' };
2355  }
2356}
2357```
2358 
2359Reference: [NestJS Guards](https://docs.nestjs.com/guards)
2360 
2361---
2362 
2363### 4.5 Validate All Input with DTOs and Pipes
2364 
2365**Impact: HIGH** — First line of defense against attacks
2366 
2367Always validate incoming data using class-validator decorators on DTOs and the global ValidationPipe. Never trust user input. Validate all request bodies, query parameters, and route parameters before processing.
2368 
2369**Incorrect (trust raw input without validation):**
2370 
2371```typescript
2372// Trust raw input without validation
2373@Controller('users')
2374export class UsersController {
2375  @Post()
2376  create(@Body() body: any) {
2377    // body could contain anything - SQL injection, XSS, etc.
2378    return this.usersService.create(body);
2379  }
2380 
2381  @Get()
2382  findAll(@Query() query: any) {
2383    // query.limit could be "'; DROP TABLE users; --"
2384    return this.usersService.findAll(query.limit);
2385  }
2386}
2387 
2388// DTOs without validation decorators
2389export class CreateUserDto {
2390  name: string;    // No validation
2391  email: string;   // Could be "not-an-email"
2392  age: number;     // Could be "abc" or -999
2393}
2394```
2395 
2396**Correct (validated DTOs with global ValidationPipe):**
2397 
2398```typescript
2399// Enable ValidationPipe globally in main.ts
2400async function bootstrap() {
2401  const app = await NestFactory.create(AppModule);
2402 
2403  app.useGlobalPipes(
2404    new ValidationPipe({
2405      whitelist: true,              // Strip unknown properties
2406      forbidNonWhitelisted: true,   // Throw on unknown properties
2407      transform: true,              // Auto-transform to DTO types
2408      transformOptions: {
2409        enableImplicitConversion: true,
2410      },
2411    }),
2412  );
2413 
2414  await app.listen(3000);
2415}
2416 
2417// Create well-validated DTOs
2418import {
2419  IsString,
2420  IsEmail,
2421  IsInt,
2422  Min,
2423  Max,
2424  IsOptional,
2425  MinLength,
2426  MaxLength,
2427  Matches,
2428  IsNotEmpty,
2429} from 'class-validator';
2430import { Transform, Type } from 'class-transformer';
2431 
2432export class CreateUserDto {
2433  @IsString()
2434  @IsNotEmpty()
2435  @MinLength(2)
2436  @MaxLength(100)
2437  @Transform(({ value }) => value?.trim())
2438  name: string;
2439 
2440  @IsEmail()
2441  @Transform(({ value }) => value?.toLowerCase().trim())
2442  email: string;
2443 
2444  @IsInt()
2445  @Min(0)
2446  @Max(150)
2447  age: number;
2448 
2449  @IsString()
2450  @MinLength(8)
2451  @MaxLength(100)
2452  @Matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, {
2453    message: 'Password must contain uppercase, lowercase, and number',
2454  })
2455  password: string;
2456}
2457 
2458// Query DTO with defaults and transformation
2459export class FindUsersQueryDto {
2460  @IsOptional()
2461  @IsString()
2462  @MaxLength(100)
2463  search?: string;
2464 
2465  @IsOptional()
2466  @Type(() => Number)
2467  @IsInt()
2468  @Min(1)
2469  @Max(100)
2470  limit: number = 20;
2471 
2472  @IsOptional()
2473  @Type(() => Number)
2474  @IsInt()
2475  @Min(0)
2476  offset: number = 0;
2477}
2478 
2479// Param validation
2480export class UserIdParamDto {
2481  @IsUUID('4')
2482  id: string;
2483}
2484 
2485@Controller('users')
2486export class UsersController {
2487  @Post()
2488  create(@Body() dto: CreateUserDto): Promise<User> {
2489    // dto is guaranteed to be valid
2490    return this.usersService.create(dto);
2491  }
2492 
2493  @Get()
2494  findAll(@Query() query: FindUsersQueryDto): Promise<User[]> {
2495    // query.limit is a number, query.search is sanitized
2496    return this.usersService.findAll(query);
2497  }
2498 
2499  @Get(':id')
2500  findOne(@Param() params: UserIdParamDto): Promise<User> {
2501    // params.id is a valid UUID
2502    return this.usersService.findById(params.id);
2503  }
2504}
2505```
2506 
2507Reference: [NestJS Validation](https://docs.nestjs.com/techniques/validation)
2508 
2509---
2510 
2511## 5. Performance
2512 
2513**Section Impact: HIGH**
2514 
2515### 5.1 Use Async Lifecycle Hooks Correctly
2516 
2517**Impact: HIGH** — Improper async handling blocks application startup
2518 
2519NestJS lifecycle hooks (`onModuleInit`, `onApplicationBootstrap`, etc.) support async operations. However, misusing them can block application startup or cause race conditions. Understand the lifecycle order and use hooks appropriately.
2520 
2521**Incorrect (fire-and-forget async without await):**
2522 
2523```typescript
2524// Fire-and-forget async without await
2525@Injectable()
2526export class DatabaseService implements OnModuleInit {
2527  onModuleInit() {
2528    // This runs but doesn't block - app starts before DB is ready!
2529    this.connect();
2530  }
2531 
2532  private async connect() {
2533    await this.pool.connect();
2534    console.log('Database connected');
2535  }
2536}
2537 
2538// Heavy blocking operations in constructor
2539@Injectable()
2540export class ConfigService {
2541  private config: Config;
2542 
2543  constructor() {
2544    // BLOCKS entire module instantiation synchronously
2545    this.config = fs.readFileSync('config.json');
2546  }
2547}
2548```
2549 
2550**Correct (return promises from async hooks):**
2551 
2552```typescript
2553// Return promise from async hooks
2554@Injectable()
2555export class DatabaseService implements OnModuleInit {
2556  private pool: Pool;
2557 
2558  async onModuleInit(): Promise<void> {
2559    // NestJS waits for this to complete before continuing
2560    await this.pool.connect();
2561    console.log('Database connected');
2562  }
2563 
2564  async onModuleDestroy(): Promise<void> {
2565    // Clean up resources on shutdown
2566    await this.pool.end();
2567    console.log('Database disconnected');
2568  }
2569}
2570 
2571// Use onApplicationBootstrap for cross-module dependencies
2572@Injectable()
2573export class CacheWarmerService implements OnApplicationBootstrap {
2574  constructor(
2575    private cache: CacheService,
2576    private products: ProductsService,
2577  ) {}
2578 
2579  async onApplicationBootstrap(): Promise<void> {
2580    // All modules are initialized, safe to warm cache
2581    const products = await this.products.findPopular();
2582    await this.cache.warmup(products);
2583  }
2584}
2585 
2586// Heavy init in async hooks, not constructor
2587@Injectable()
2588export class ConfigService implements OnModuleInit {
2589  private config: Config;
2590 
2591  constructor() {
2592    // Keep constructor synchronous and fast
2593  }
2594 
2595  async onModuleInit(): Promise<void> {
2596    // Async loading in lifecycle hook
2597    this.config = await this.loadConfig();
2598  }
2599 
2600  private async loadConfig(): Promise<Config> {
2601    const file = await fs.promises.readFile('config.json');
2602    return JSON.parse(file.toString());
2603  }
2604 
2605  get<T>(key: string): T {
2606    return this.config[key];
2607  }
2608}
2609 
2610// Enable shutdown hooks in main.ts
2611async function bootstrap() {
2612  const app = await NestFactory.create(AppModule);
2613  app.enableShutdownHooks(); // Enable SIGTERM/SIGINT handling
2614  await app.listen(3000);
2615}
2616```
2617 
2618Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
2619 
2620---
2621 
2622### 5.2 Use Lazy Loading for Large Modules
2623 
2624**Impact: MEDIUM** — Improves startup time for large applications
2625 
2626NestJS supports lazy-loading modules, which defers initialization until first use. This is valuable for large applications where some features are rarely used, serverless deployments where cold start time matters, or when certain modules have heavy initialization costs.
2627 
2628**Incorrect (loading everything eagerly):**
2629 
2630```typescript
2631// Load everything eagerly in a large app
2632@Module({
2633  imports: [
2634    UsersModule,
2635    OrdersModule,
2636    PaymentsModule,
2637    ReportsModule, // Heavy, rarely used
2638    AnalyticsModule, // Heavy, rarely used
2639    AdminModule, // Only admins use this
2640    LegacyModule, // Migration module, rarely used
2641    BulkImportModule, // Used once a month
2642  ],
2643})
2644export class AppModule {}
2645 
2646// All modules initialize at startup, even if never used
2647// Slow cold starts in serverless
2648// Memory wasted on unused modules
2649```
2650 
2651**Correct (lazy load rarely-used modules):**
2652 
2653```typescript
2654// Use LazyModuleLoader for optional modules
2655import { LazyModuleLoader } from '@nestjs/core';
2656 
2657@Injectable()
2658export class ReportsService {
2659  constructor(private lazyModuleLoader: LazyModuleLoader) {}
2660 
2661  async generateReport(type: string): Promise<Report> {
2662    // Load module only when needed
2663    const { ReportsModule } = await import('./reports/reports.module');
2664    const moduleRef = await this.lazyModuleLoader.load(() => ReportsModule);
2665 
2666    const reportsService = moduleRef.get(ReportsGeneratorService);
2667    return reportsService.generate(type);
2668  }
2669}
2670 
2671// Lazy load admin features with caching
2672@Injectable()
2673export class AdminService {
2674  private adminModule: ModuleRef | null = null;
2675 
2676  constructor(private lazyModuleLoader: LazyModuleLoader) {}
2677 
2678  private async getAdminModule(): Promise<ModuleRef> {
2679    if (!this.adminModule) {
2680      const { AdminModule } = await import('./admin/admin.module');
2681      this.adminModule = await this.lazyModuleLoader.load(() => AdminModule);
2682    }
2683    return this.adminModule;
2684  }
2685 
2686  async runAdminTask(task: string): Promise<void> {
2687    const moduleRef = await this.getAdminModule();
2688    const taskRunner = moduleRef.get(AdminTaskRunner);
2689    await taskRunner.run(task);
2690  }
2691}
2692 
2693// Reusable lazy loader service
2694@Injectable()
2695export class ModuleLoaderService {
2696  private loadedModules = new Map<string, ModuleRef>();
2697 
2698  constructor(private lazyModuleLoader: LazyModuleLoader) {}
2699 
2700  async load<T>(
2701    key: string,
2702    importFn: () => Promise<{ default: Type<T> } | Type<T>>,
2703  ): Promise<ModuleRef> {
2704    if (!this.loadedModules.has(key)) {
2705      const module = await importFn();
2706      const moduleType = 'default' in module ? module.default : module;
2707      const moduleRef = await this.lazyModuleLoader.load(() => moduleType);
2708      this.loadedModules.set(key, moduleRef);
2709    }
2710    return this.loadedModules.get(key)!;
2711  }
2712}
2713 
2714// Preload modules in background after startup
2715@Injectable()
2716export class ModulePreloader implements OnApplicationBootstrap {
2717  constructor(private lazyModuleLoader: LazyModuleLoader) {}
2718 
2719  async onApplicationBootstrap(): Promise<void> {
2720    setTimeout(async () => {
2721      await this.preloadModule(() => import('./reports/reports.module'));
2722    }, 5000); // 5 seconds after startup
2723  }
2724 
2725  private async preloadModule(importFn: () => Promise<any>): Promise<void> {
2726    try {
2727      const module = await importFn();
2728      const moduleType = module.default || Object.values(module)[0];
2729      await this.lazyModuleLoader.load(() => moduleType);
2730    } catch (error) {
2731      console.warn('Failed to preload module', error);
2732    }
2733  }
2734}
2735```
2736 
2737Reference: [NestJS Lazy Loading Modules](https://docs.nestjs.com/fundamentals/lazy-loading-modules)
2738 
2739---
2740 
2741### 5.3 Optimize Database Queries
2742 
2743**Impact: HIGH** — Database queries are typically the largest source of latency
2744 
2745Select only needed columns, use proper indexes, avoid over-fetching relations, and consider query performance when designing your data access. Most API slowness traces back to inefficient database queries.
2746 
2747**Incorrect (over-fetching data and missing indexes):**
2748 
2749```typescript
2750// Select everything when you need few fields
2751@Injectable()
2752export class UsersService {
2753  async findAllEmails(): Promise<string[]> {
2754    const users = await this.repo.find();
2755    // Fetches ALL columns for ALL users
2756    return users.map((u) => u.email);
2757  }
2758 
2759  async getUserSummary(id: string): Promise<UserSummary> {
2760    const user = await this.repo.findOne({
2761      where: { id },
2762      relations: ['posts', 'posts.comments', 'posts.comments.author', 'followers'],
2763    });
2764    // Over-fetches massive relation tree
2765    return { name: user.name, postCount: user.posts.length };
2766  }
2767}
2768 
2769// No indexes on frequently queried columns
2770@Entity()
2771export class Order {
2772  @Column()
2773  userId: string; // No index - full table scan on every lookup
2774 
2775  @Column()
2776  status: string; // No index - slow status filtering
2777}
2778```
2779 
2780**Correct (select only needed data with proper indexes):**
2781 
2782```typescript
2783// Select only needed columns
2784@Injectable()
2785export class UsersService {
2786  async findAllEmails(): Promise<string[]> {
2787    const users = await this.repo.find({
2788      select: ['email'], // Only fetch email column
2789    });
2790    return users.map((u) => u.email);
2791  }
2792 
2793  // Use QueryBuilder for complex selections
2794  async getUserSummary(id: string): Promise<UserSummary> {
2795    return this.repo
2796      .createQueryBuilder('user')
2797      .select('user.name', 'name')
2798      .addSelect('COUNT(post.id)', 'postCount')
2799      .leftJoin('user.posts', 'post')
2800      .where('user.id = :id', { id })
2801      .groupBy('user.id')
2802      .getRawOne();
2803  }
2804 
2805  // Fetch relations only when needed
2806  async getFullProfile(id: string): Promise<User> {
2807    return this.repo.findOne({
2808      where: { id },
2809      relations: ['posts'], // Only immediate relation
2810      select: {
2811        id: true,
2812        name: true,
2813        email: true,
2814        posts: {
2815          id: true,
2816          title: true,
2817        },
2818      },
2819    });
2820  }
2821}
2822 
2823// Add indexes on frequently queried columns
2824@Entity()
2825@Index(['userId'])
2826@Index(['status'])
2827@Index(['createdAt'])
2828@Index(['userId', 'status']) // Composite index for common query pattern
2829export class Order {
2830  @PrimaryGeneratedColumn('uuid')
2831  id: string;
2832 
2833  @Column()
2834  userId: string;
2835 
2836  @Column()
2837  status: string;
2838 
2839  @CreateDateColumn()
2840  createdAt: Date;
2841}
2842 
2843// Always paginate large datasets
2844@Injectable()
2845export class OrdersService {
2846  async findAll(page = 1, limit = 20): Promise<PaginatedResult<Order>> {
2847    const [items, total] = await this.repo.findAndCount({
2848      skip: (page - 1) * limit,
2849      take: limit,
2850      order: { createdAt: 'DESC' },
2851    });
2852 
2853    return {
2854      items,
2855      meta: {
2856        page,
2857        limit,
2858        total,
2859        totalPages: Math.ceil(total / limit),
2860      },
2861    };
2862  }
2863}
2864```
2865 
2866Reference: [TypeORM Query Builder](https://typeorm.io/select-query-builder)
2867 
2868---
2869 
2870### 5.4 Use Caching Strategically
2871 
2872**Impact: HIGH** — Dramatically reduces database load and response times
2873 
2874Implement caching for expensive operations, frequently accessed data, and external API calls. Use NestJS CacheModule with appropriate TTLs and cache invalidation strategies. Don't cache everything - focus on high-impact areas.
2875 
2876**Incorrect (no caching or caching everything):**
2877 
2878```typescript
2879// No caching for expensive, repeated queries
2880@Injectable()
2881export class ProductsService {
2882  async getPopular(): Promise<Product[]> {
2883    // Runs complex aggregation query EVERY request
2884    return this.productsRepo
2885      .createQueryBuilder('p')
2886      .leftJoin('p.orders', 'o')
2887      .select('p.*, COUNT(o.id) as orderCount')
2888      .groupBy('p.id')
2889      .orderBy('orderCount', 'DESC')
2890      .limit(20)
2891      .getMany();
2892  }
2893}
2894 
2895// Cache everything without thought
2896@Injectable()
2897export class UsersService {
2898  @CacheKey('users')
2899  @CacheTTL(3600)
2900  @UseInterceptors(CacheInterceptor)
2901  async findAll(): Promise<User[]> {
2902    // Caching user list for 1 hour is wrong if data changes frequently
2903    return this.usersRepo.find();
2904  }
2905}
2906```
2907 
2908**Correct (strategic caching with proper invalidation):**
2909 
2910```typescript
2911// Setup caching module
2912@Module({
2913  imports: [
2914    CacheModule.registerAsync({
2915      imports: [ConfigModule],
2916      inject: [ConfigService],
2917      useFactory: (config: ConfigService) => ({
2918        stores: [
2919          new KeyvRedis(config.get('REDIS_URL')),
2920        ],
2921        ttl: 60 * 1000, // Default 60s
2922      }),
2923    }),
2924  ],
2925})
2926export class AppModule {}
2927 
2928// Manual caching for granular control
2929@Injectable()
2930export class ProductsService {
2931  constructor(
2932    @Inject(CACHE_MANAGER) private cache: Cache,
2933    private productsRepo: ProductRepository,
2934  ) {}
2935 
2936  async getPopular(): Promise<Product[]> {
2937    const cacheKey = 'products:popular';
2938 
2939    // Try cache first
2940    const cached = await this.cache.get<Product[]>(cacheKey);
2941    if (cached) return cached;
2942 
2943    // Cache miss - fetch and cache
2944    const products = await this.fetchPopularProducts();
2945    await this.cache.set(cacheKey, products, 5 * 60 * 1000); // 5 min TTL
2946    return products;
2947  }
2948 
2949  // Invalidate cache on changes
2950  async updateProduct(id: string, dto: UpdateProductDto): Promise<Product> {
2951    const product = await this.productsRepo.save({ id, ...dto });
2952    await this.cache.del('products:popular'); // Invalidate
2953    return product;
2954  }
2955}
2956 
2957// Decorator-based caching with auto-interceptor
2958@Controller('categories')
2959@UseInterceptors(CacheInterceptor)
2960export class CategoriesController {
2961  @Get()
2962  @CacheTTL(30 * 60 * 1000) // 30 minutes - categories rarely change
2963  findAll(): Promise<Category[]> {
2964    return this.categoriesService.findAll();
2965  }
2966 
2967  @Get(':id')
2968  @CacheTTL(60 * 1000) // 1 minute
2969  @CacheKey('category')
2970  findOne(@Param('id') id: string): Promise<Category> {
2971    return this.categoriesService.findOne(id);
2972  }
2973}
2974 
2975// Event-based cache invalidation
2976@Injectable()
2977export class CacheInvalidationService {
2978  constructor(@Inject(CACHE_MANAGER) private cache: Cache) {}
2979 
2980  @OnEvent('product.created')
2981  @OnEvent('product.updated')
2982  @OnEvent('product.deleted')
2983  async invalidateProductCaches(event: ProductEvent) {
2984    await Promise.all([
2985      this.cache.del('products:popular'),
2986      this.cache.del(`product:${event.productId}`),
2987    ]);
2988  }
2989}
2990```
2991 
2992Reference: [NestJS Caching](https://docs.nestjs.com/techniques/caching)
2993 
2994---
2995 
2996## 6. Testing
2997 
2998**Section Impact: MEDIUM-HIGH**
2999 
3000### 6.1 Use Supertest for E2E Testing
3001 
3002**Impact: HIGH** — Validates the full request/response cycle
3003 
3004End-to-end tests use Supertest to make real HTTP requests against your NestJS application. They test the full stack including middleware, guards, pipes, and interceptors. E2E tests catch integration issues that unit tests miss.
3005 
3006**Incorrect (no proper E2E setup or teardown):**
3007 
3008```typescript
3009// Only unit test controllers
3010describe('UsersController', () => {
3011  it('should return users', async () => {
3012    const service = { findAll: jest.fn().mockResolvedValue([]) };
3013    const controller = new UsersController(service as any);
3014 
3015    const result = await controller.findAll();
3016 
3017    expect(result).toEqual([]);
3018    // Doesn't test: routes, guards, pipes, serialization
3019  });
3020});
3021 
3022// E2E tests without proper setup/teardown
3023describe('Users API', () => {
3024  it('should create user', async () => {
3025    const app = await NestFactory.create(AppModule);
3026    // No proper initialization
3027    // No cleanup after test
3028    // Hits real database
3029  });
3030});
3031```
3032 
3033**Correct (proper E2E setup with Supertest):**
3034 
3035```typescript
3036// Proper E2E test setup
3037import { Test, TestingModule } from '@nestjs/testing';
3038import { INestApplication, ValidationPipe } from '@nestjs/common';
3039import * as request from 'supertest';
3040import { AppModule } from '../src/app.module';
3041 
3042describe('UsersController (e2e)', () => {
3043  let app: INestApplication;
3044 
3045  beforeAll(async () => {
3046    const moduleFixture: TestingModule = await Test.createTestingModule({
3047      imports: [AppModule],
3048    }).compile();
3049 
3050    app = moduleFixture.createNestApplication();
3051 
3052    // Apply same config as production
3053    app.useGlobalPipes(
3054      new ValidationPipe({
3055        whitelist: true,
3056        transform: true,
3057        forbidNonWhitelisted: true,
3058      }),
3059    );
3060 
3061    await app.init();
3062  });
3063 
3064  afterAll(async () => {
3065    await app.close();
3066  });
3067 
3068  describe('/users (POST)', () => {
3069    it('should create a user', () => {
3070      return request(app.getHttpServer())
3071        .post('/users')
3072        .send({ name: 'John', email: '[email protected]' })
3073        .expect(201)
3074        .expect((res) => {
3075          expect(res.body).toHaveProperty('id');
3076          expect(res.body.name).toBe('John');
3077          expect(res.body.email).toBe('[email protected]');
3078        });
3079    });
3080 
3081    it('should return 400 for invalid email', () => {
3082      return request(app.getHttpServer())
3083        .post('/users')
3084        .send({ name: 'John', email: 'invalid-email' })
3085        .expect(400)
3086        .expect((res) => {
3087          expect(res.body.message).toContain('email');
3088        });
3089    });
3090  });
3091 
3092  describe('/users/:id (GET)', () => {
3093    it('should return 404 for non-existent user', () => {
3094      return request(app.getHttpServer())
3095        .get('/users/non-existent-id')
3096        .expect(404);
3097    });
3098  });
3099});
3100 
3101// Testing with authentication
3102describe('Protected Routes (e2e)', () => {
3103  let app: INestApplication;
3104  let authToken: string;
3105 
3106  beforeAll(async () => {
3107    const moduleFixture = await Test.createTestingModule({
3108      imports: [AppModule],
3109    }).compile();
3110 
3111    app = moduleFixture.createNestApplication();
3112    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
3113    await app.init();
3114 
3115    // Get auth token
3116    const loginResponse = await request(app.getHttpServer())
3117      .post('/auth/login')
3118      .send({ email: '[email protected]', password: 'password' });
3119 
3120    authToken = loginResponse.body.accessToken;
3121  });
3122 
3123  it('should return 401 without token', () => {
3124    return request(app.getHttpServer())
3125      .get('/users/me')
3126      .expect(401);
3127  });
3128 
3129  it('should return user profile with valid token', () => {
3130    return request(app.getHttpServer())
3131      .get('/users/me')
3132      .set('Authorization', `Bearer ${authToken}`)
3133      .expect(200)
3134      .expect((res) => {
3135        expect(res.body.email).toBe('[email protected]');
3136      });
3137  });
3138});
3139 
3140// Database isolation for E2E tests
3141describe('Orders API (e2e)', () => {
3142  let app: INestApplication;
3143  let dataSource: DataSource;
3144 
3145  beforeAll(async () => {
3146    const moduleFixture = await Test.createTestingModule({
3147      imports: [
3148        ConfigModule.forRoot({
3149          envFilePath: '.env.test', // Test database config
3150        }),
3151        AppModule,
3152      ],
3153    }).compile();
3154 
3155    app = moduleFixture.createNestApplication();
3156    dataSource = moduleFixture.get(DataSource);
3157    await app.init();
3158  });
3159 
3160  beforeEach(async () => {
3161    // Clean database between tests
3162    await dataSource.synchronize(true);
3163  });
3164 
3165  afterAll(async () => {
3166    await dataSource.destroy();
3167    await app.close();
3168  });
3169});
3170```
3171 
3172Reference: [NestJS E2E Testing](https://docs.nestjs.com/fundamentals/testing#end-to-end-testing)
3173 
3174---
3175 
3176### 6.2 Mock External Services in Tests
3177 
3178**Impact: HIGH** — Ensures fast, reliable, deterministic tests
3179 
3180Never call real external services (APIs, databases, message queues) in unit tests. Mock them to ensure tests are fast, deterministic, and don't incur costs. Use realistic mock data and test edge cases like timeouts and errors.
3181 
3182**Incorrect (calling real APIs and databases):**
3183 
3184```typescript
3185// Call real APIs in tests
3186describe('PaymentService', () => {
3187  it('should process payment', async () => {
3188    const service = new PaymentService(new StripeClient(realApiKey));
3189    // Hits real Stripe API!
3190    const result = await service.charge('tok_visa', 1000);
3191    // Slow, costs money, flaky
3192  });
3193});
3194 
3195// Use real database
3196describe('UsersService', () => {
3197  beforeEach(async () => {
3198    await connection.query('DELETE FROM users'); // Modifies real DB
3199  });
3200 
3201  it('should create user', async () => {
3202    const user = await service.create({ email: '[email protected]' });
3203    // Side effects on shared database
3204  });
3205});
3206 
3207// Incomplete mocks
3208const mockHttpService = {
3209  get: jest.fn().mockResolvedValue({ data: {} }),
3210  // Missing error scenarios, missing other methods
3211};
3212```
3213 
3214**Correct (mock all external dependencies):**
3215 
3216```typescript
3217// Mock HTTP service properly
3218describe('WeatherService', () => {
3219  let service: WeatherService;
3220  let httpService: jest.Mocked<HttpService>;
3221 
3222  beforeEach(async () => {
3223    const module = await Test.createTestingModule({
3224      providers: [
3225        WeatherService,
3226        {
3227          provide: HttpService,
3228          useValue: {
3229            get: jest.fn(),
3230            post: jest.fn(),
3231          },
3232        },
3233      ],
3234    }).compile();
3235 
3236    service = module.get(WeatherService);
3237    httpService = module.get(HttpService);
3238  });
3239 
3240  it('should return weather data', async () => {
3241    const mockResponse = {
3242      data: { temperature: 72, humidity: 45 },
3243      status: 200,
3244      statusText: 'OK',
3245      headers: {},
3246      config: {},
3247    };
3248 
3249    httpService.get.mockReturnValue(of(mockResponse));
3250 
3251    const result = await service.getWeather('NYC');
3252 
3253    expect(result).toEqual({ temperature: 72, humidity: 45 });
3254  });
3255 
3256  it('should handle API timeout', async () => {
3257    httpService.get.mockReturnValue(
3258      throwError(() => new Error('ETIMEDOUT')),
3259    );
3260 
3261    await expect(service.getWeather('NYC')).rejects.toThrow('Weather service unavailable');
3262  });
3263 
3264  it('should handle rate limiting', async () => {
3265    httpService.get.mockReturnValue(
3266      throwError(() => ({
3267        response: { status: 429, data: { message: 'Rate limited' } },
3268      })),
3269    );
3270 
3271    await expect(service.getWeather('NYC')).rejects.toThrow(TooManyRequestsException);
3272  });
3273});
3274 
3275// Mock repository instead of database
3276describe('UsersService', () => {
3277  let service: UsersService;
3278  let repo: jest.Mocked<Repository<User>>;
3279 
3280  beforeEach(async () => {
3281    const mockRepo = {
3282      find: jest.fn(),
3283      findOne: jest.fn(),
3284      save: jest.fn(),
3285      delete: jest.fn(),
3286      createQueryBuilder: jest.fn(),
3287    };
3288 
3289    const module = await Test.createTestingModule({
3290      providers: [
3291        UsersService,
3292        { provide: getRepositoryToken(User), useValue: mockRepo },
3293      ],
3294    }).compile();
3295 
3296    service = module.get(UsersService);
3297    repo = module.get(getRepositoryToken(User));
3298  });
3299 
3300  it('should find user by id', async () => {
3301    const mockUser = { id: '1', name: 'John', email: '[email protected]' };
3302    repo.findOne.mockResolvedValue(mockUser);
3303 
3304    const result = await service.findById('1');
3305 
3306    expect(result).toEqual(mockUser);
3307    expect(repo.findOne).toHaveBeenCalledWith({ where: { id: '1' } });
3308  });
3309});
3310 
3311// Create mock factory for complex SDKs
3312function createMockStripe(): jest.Mocked<Stripe> {
3313  return {
3314    paymentIntents: {
3315      create: jest.fn(),
3316      retrieve: jest.fn(),
3317      confirm: jest.fn(),
3318      cancel: jest.fn(),
3319    },
3320    customers: {
3321      create: jest.fn(),
3322      retrieve: jest.fn(),
3323    },
3324  } as any;
3325}
3326 
3327// Mock time for time-dependent tests
3328describe('TokenService', () => {
3329  beforeEach(() => {
3330    jest.useFakeTimers();
3331    jest.setSystemTime(new Date('2024-01-15'));
3332  });
3333 
3334  afterEach(() => {
3335    jest.useRealTimers();
3336  });
3337 
3338  it('should expire token after 1 hour', async () => {
3339    const token = await service.createToken();
3340 
3341    // Fast-forward time
3342    jest.advanceTimersByTime(61 * 60 * 1000);
3343 
3344    expect(await service.isValid(token)).toBe(false);
3345  });
3346});
3347```
3348 
3349Reference: [Jest Mocking](https://jestjs.io/docs/mock-functions)
3350 
3351---
3352 
3353### 6.3 Use Testing Module for Unit Tests
3354 
3355**Impact: HIGH** — Enables proper isolated testing with mocked dependencies
3356 
3357Use `@nestjs/testing` module to create isolated test environments with mocked dependencies. This ensures your tests run fast, don't depend on external services, and properly test your business logic in isolation.
3358 
3359**Incorrect (manual instantiation bypassing DI):**
3360 
3361```typescript
3362// Instantiate services manually without DI
3363describe('UsersService', () => {
3364  it('should create user', async () => {
3365    // Manual instantiation bypasses DI
3366    const repo = new UserRepository(); // Real repo!
3367    const service = new UsersService(repo);
3368 
3369    const user = await service.create({ name: 'Test' });
3370    // This hits the real database!
3371  });
3372});
3373 
3374// Test implementation details
3375describe('UsersController', () => {
3376  it('should call service', async () => {
3377    const service = { create: jest.fn() };
3378    const controller = new UsersController(service as any);
3379 
3380    await controller.create({ name: 'Test' });
3381 
3382    expect(service.create).toHaveBeenCalled(); // Tests implementation, not behavior
3383  });
3384});
3385```
3386 
3387**Correct (use Test.createTestingModule with mocked dependencies):**
3388 
3389```typescript
3390// Use Test.createTestingModule for proper DI
3391import { Test, TestingModule } from '@nestjs/testing';
3392 
3393describe('UsersService', () => {
3394  let service: UsersService;
3395  let repo: jest.Mocked<UserRepository>;
3396 
3397  beforeEach(async () => {
3398    const module: TestingModule = await Test.createTestingModule({
3399      providers: [
3400        UsersService,
3401        {
3402          provide: UserRepository,
3403          useValue: {
3404            save: jest.fn(),
3405            findOne: jest.fn(),
3406            find: jest.fn(),
3407          },
3408        },
3409      ],
3410    }).compile();
3411 
3412    service = module.get<UsersService>(UsersService);
3413    repo = module.get(UserRepository);
3414  });
3415 
3416  afterEach(() => {
3417    jest.clearAllMocks();
3418  });
3419 
3420  describe('create', () => {
3421    it('should save and return user', async () => {
3422      const dto = { name: 'John', email: '[email protected]' };
3423      const expectedUser = { id: '1', ...dto };
3424 
3425      repo.save.mockResolvedValue(expectedUser);
3426 
3427      const result = await service.create(dto);
3428 
3429      expect(result).toEqual(expectedUser);
3430      expect(repo.save).toHaveBeenCalledWith(dto);
3431    });
3432 
3433    it('should throw on duplicate email', async () => {
3434      repo.findOne.mockResolvedValue({ id: '1', email: '[email protected]' });
3435 
3436      await expect(
3437        service.create({ name: 'Test', email: '[email protected]' }),
3438      ).rejects.toThrow(ConflictException);
3439    });
3440  });
3441 
3442  describe('findById', () => {
3443    it('should return user when found', async () => {
3444      const user = { id: '1', name: 'John' };
3445      repo.findOne.mockResolvedValue(user);
3446 
3447      const result = await service.findById('1');
3448 
3449      expect(result).toEqual(user);
3450    });
3451 
3452    it('should throw NotFoundException when not found', async () => {
3453      repo.findOne.mockResolvedValue(null);
3454 
3455      await expect(service.findById('999')).rejects.toThrow(NotFoundException);
3456    });
3457  });
3458});
3459 
3460// Testing guards and interceptors
3461describe('RolesGuard', () => {
3462  let guard: RolesGuard;
3463  let reflector: Reflector;
3464 
3465  beforeEach(async () => {
3466    const module = await Test.createTestingModule({
3467      providers: [RolesGuard, Reflector],
3468    }).compile();
3469 
3470    guard = module.get<RolesGuard>(RolesGuard);
3471    reflector = module.get<Reflector>(Reflector);
3472  });
3473 
3474  it('should allow when no roles required', () => {
3475    const context = createMockExecutionContext({ user: { roles: [] } });
3476    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(undefined);
3477 
3478    expect(guard.canActivate(context)).toBe(true);
3479  });
3480 
3481  it('should allow admin for admin-only route', () => {
3482    const context = createMockExecutionContext({ user: { roles: ['admin'] } });
3483    jest.spyOn(reflector, 'getAllAndOverride').mockReturnValue(['admin']);
3484 
3485    expect(guard.canActivate(context)).toBe(true);
3486  });
3487});
3488 
3489function createMockExecutionContext(request: Partial<Request>): ExecutionContext {
3490  return {
3491    switchToHttp: () => ({
3492      getRequest: () => request,
3493    }),
3494    getHandler: () => jest.fn(),
3495    getClass: () => jest.fn(),
3496  } as ExecutionContext;
3497}
3498```
3499 
3500Reference: [NestJS Testing](https://docs.nestjs.com/fundamentals/testing)
3501 
3502---
3503 
3504## 7. Database & ORM
3505 
3506**Section Impact: MEDIUM-HIGH**
3507 
3508### 7.1 Avoid N+1 Query Problems
3509 
3510**Impact: HIGH** — N+1 queries are one of the most common performance killers
3511 
3512N+1 queries occur when you fetch a list of entities, then make an additional query for each entity to load related data. Use eager loading with `relations`, query builder joins, or DataLoader to batch queries efficiently.
3513 
3514**Incorrect (lazy loading in loops causes N+1):**
3515 
3516```typescript
3517// Lazy loading in loops causes N+1
3518@Injectable()
3519export class OrdersService {
3520  async getOrdersWithItems(userId: string): Promise<Order[]> {
3521    const orders = await this.orderRepo.find({ where: { userId } });
3522    // 1 query for orders
3523 
3524    for (const order of orders) {
3525      // N additional queries - one per order!
3526      order.items = await this.itemRepo.find({ where: { orderId: order.id } });
3527    }
3528 
3529    return orders;
3530  }
3531}
3532 
3533// Accessing lazy relations without loading
3534@Controller('users')
3535export class UsersController {
3536  @Get()
3537  async findAll(): Promise<User[]> {
3538    const users = await this.userRepo.find();
3539    // If User.posts is lazy-loaded, serializing triggers N queries
3540    return users; // Each user.posts access = 1 query
3541  }
3542}
3543```
3544 
3545**Correct (use relations for eager loading):**
3546 
3547```typescript
3548// Use relations option for eager loading
3549@Injectable()
3550export class OrdersService {
3551  async getOrdersWithItems(userId: string): Promise<Order[]> {
3552    // Single query with JOIN
3553    return this.orderRepo.find({
3554      where: { userId },
3555      relations: ['items', 'items.product'],
3556    });
3557  }
3558}
3559 
3560// Use QueryBuilder for complex joins
3561@Injectable()
3562export class UsersService {
3563  async getUsersWithPostCounts(): Promise<UserWithPostCount[]> {
3564    return this.userRepo
3565      .createQueryBuilder('user')
3566      .leftJoin('user.posts', 'post')
3567      .select('user.id', 'id')
3568      .addSelect('user.name', 'name')
3569      .addSelect('COUNT(post.id)', 'postCount')
3570      .groupBy('user.id')
3571      .getRawMany();
3572  }
3573 
3574  async getActiveUsersWithPosts(): Promise<User[]> {
3575    return this.userRepo
3576      .createQueryBuilder('user')
3577      .leftJoinAndSelect('user.posts', 'post')
3578      .leftJoinAndSelect('post.comments', 'comment')
3579      .where('user.isActive = :active', { active: true })
3580      .andWhere('post.status = :status', { status: 'published' })
3581      .getMany();
3582  }
3583}
3584 
3585// Use find options for specific fields
3586async getOrderSummaries(userId: string): Promise<OrderSummary[]> {
3587  return this.orderRepo.find({
3588    where: { userId },
3589    relations: ['items'],
3590    select: {
3591      id: true,
3592      total: true,
3593      status: true,
3594      items: {
3595        id: true,
3596        quantity: true,
3597        price: true,
3598      },
3599    },
3600  });
3601}
3602 
3603// Use DataLoader for GraphQL to batch and cache queries
3604import DataLoader from 'dataloader';
3605 
3606@Injectable({ scope: Scope.REQUEST })
3607export class PostsLoader {
3608  constructor(private postsService: PostsService) {}
3609 
3610  readonly batchPosts = new DataLoader<string, Post[]>(async (userIds) => {
3611    // Single query for all users' posts
3612    const posts = await this.postsService.findByUserIds([...userIds]);
3613 
3614    // Group by userId
3615    const postsMap = new Map<string, Post[]>();
3616    for (const post of posts) {
3617      const userPosts = postsMap.get(post.userId) || [];
3618      userPosts.push(post);
3619      postsMap.set(post.userId, userPosts);
3620    }
3621 
3622    // Return in same order as input
3623    return userIds.map((id) => postsMap.get(id) || []);
3624  });
3625}
3626 
3627// In resolver
3628@ResolveField()
3629async posts(@Parent() user: User): Promise<Post[]> {
3630  // DataLoader batches multiple calls into single query
3631  return this.postsLoader.batchPosts.load(user.id);
3632}
3633 
3634// Enable query logging in development to detect N+1
3635TypeOrmModule.forRoot({
3636  logging: ['query', 'error'],
3637  logger: 'advanced-console',
3638});
3639```
3640 
3641Reference: [TypeORM Relations](https://typeorm.io/relations)
3642 
3643---
3644 
3645### 7.2 Use Database Migrations
3646 
3647**Impact: HIGH** — Enables safe, repeatable database schema changes
3648 
3649Never use `synchronize: true` in production. Use migrations for all schema changes. Migrations provide version control for your database, enable safe rollbacks, and ensure consistency across all environments.
3650 
3651**Incorrect (using synchronize or manual SQL):**
3652 
3653```typescript
3654// Use synchronize in production
3655TypeOrmModule.forRoot({
3656  type: 'postgres',
3657  synchronize: true, // DANGEROUS in production!
3658  // Can drop columns, tables, or data
3659});
3660 
3661// Manual SQL in production
3662@Injectable()
3663export class DatabaseService {
3664  async addColumn(): Promise<void> {
3665    await this.dataSource.query('ALTER TABLE users ADD COLUMN age INT');
3666    // No version control, no rollback, inconsistent across envs
3667  }
3668}
3669 
3670// Modify entities without migration
3671@Entity()
3672export class User {
3673  @Column()
3674  email: string;
3675 
3676  @Column() // Added without migration
3677  newField: string; // Will crash in production if synchronize is false
3678}
3679```
3680 
3681**Correct (use migrations for all schema changes):**
3682 
3683```typescript
3684// Configure TypeORM for migrations
3685// data-source.ts
3686export const dataSource = new DataSource({
3687  type: 'postgres',
3688  host: process.env.DB_HOST,
3689  port: parseInt(process.env.DB_PORT),
3690  username: process.env.DB_USERNAME,
3691  password: process.env.DB_PASSWORD,
3692  database: process.env.DB_NAME,
3693  entities: ['dist/**/*.entity.js'],
3694  migrations: ['dist/migrations/*.js'],
3695  synchronize: false, // Always false in production
3696  migrationsRun: true, // Run migrations on startup
3697});
3698 
3699// app.module.ts
3700TypeOrmModule.forRootAsync({
3701  inject: [ConfigService],
3702  useFactory: (config: ConfigService) => ({
3703    type: 'postgres',
3704    host: config.get('DB_HOST'),
3705    synchronize: config.get('NODE_ENV') === 'development', // Only in dev
3706    migrations: ['dist/migrations/*.js'],
3707    migrationsRun: true,
3708  }),
3709});
3710 
3711// migrations/1705312800000-AddUserAge.ts
3712import { MigrationInterface, QueryRunner } from 'typeorm';
3713 
3714export class AddUserAge1705312800000 implements MigrationInterface {
3715  name = 'AddUserAge1705312800000';
3716 
3717  public async up(queryRunner: QueryRunner): Promise<void> {
3718    // Add column with default to handle existing rows
3719    await queryRunner.query(`
3720      ALTER TABLE "users" ADD "age" integer DEFAULT 0
3721    `);
3722 
3723    // Add index for frequently queried columns
3724    await queryRunner.query(`
3725      CREATE INDEX "IDX_users_age" ON "users" ("age")
3726    `);
3727  }
3728 
3729  public async down(queryRunner: QueryRunner): Promise<void> {
3730    // Always implement down for rollback
3731    await queryRunner.query(`DROP INDEX "IDX_users_age"`);
3732    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "age"`);
3733  }
3734}
3735 
3736// Safe column rename (two-step)
3737export class RenameNameToFullName1705312900000 implements MigrationInterface {
3738  public async up(queryRunner: QueryRunner): Promise<void> {
3739    // Step 1: Add new column
3740    await queryRunner.query(`
3741      ALTER TABLE "users" ADD "full_name" varchar(255)
3742    `);
3743 
3744    // Step 2: Copy data
3745    await queryRunner.query(`
3746      UPDATE "users" SET "full_name" = "name"
3747    `);
3748 
3749    // Step 3: Add NOT NULL constraint
3750    await queryRunner.query(`
3751      ALTER TABLE "users" ALTER COLUMN "full_name" SET NOT NULL
3752    `);
3753 
3754    // Step 4: Drop old column (after verifying app works)
3755    await queryRunner.query(`
3756      ALTER TABLE "users" DROP COLUMN "name"
3757    `);
3758  }
3759 
3760  public async down(queryRunner: QueryRunner): Promise<void> {
3761    await queryRunner.query(`ALTER TABLE "users" ADD "name" varchar(255)`);
3762    await queryRunner.query(`UPDATE "users" SET "name" = "full_name"`);
3763    await queryRunner.query(`ALTER TABLE "users" DROP COLUMN "full_name"`);
3764  }
3765}
3766```
3767 
3768Reference: [TypeORM Migrations](https://typeorm.io/migrations)
3769 
3770---
3771 
3772### 7.3 Use Transactions for Multi-Step Operations
3773 
3774**Impact: HIGH** — Ensures data consistency in multi-step operations
3775 
3776When multiple database operations must succeed or fail together, wrap them in a transaction. This prevents partial updates that leave your data in an inconsistent state. Use TypeORM's transaction APIs or the DataSource query runner for complex scenarios.
3777 
3778**Incorrect (multiple saves without transaction):**
3779 
3780```typescript
3781// Multiple saves without transaction
3782@Injectable()
3783export class OrdersService {
3784  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
3785    // If any step fails, data is inconsistent
3786    const order = await this.orderRepo.save({ userId, status: 'pending' });
3787 
3788    for (const item of items) {
3789      await this.orderItemRepo.save({ orderId: order.id, ...item });
3790      await this.inventoryRepo.decrement({ productId: item.productId }, 'stock', item.quantity);
3791    }
3792 
3793    await this.paymentService.charge(order.id);
3794    // If payment fails, order and inventory are already modified!
3795 
3796    return order;
3797  }
3798}
3799```
3800 
3801**Correct (use DataSource.transaction for automatic rollback):**
3802 
3803```typescript
3804// Use DataSource.transaction() for automatic rollback
3805@Injectable()
3806export class OrdersService {
3807  constructor(private dataSource: DataSource) {}
3808 
3809  async createOrder(userId: string, items: OrderItem[]): Promise<Order> {
3810    return this.dataSource.transaction(async (manager) => {
3811      // All operations use the same transactional manager
3812      const order = await manager.save(Order, { userId, status: 'pending' });
3813 
3814      for (const item of items) {
3815        await manager.save(OrderItem, { orderId: order.id, ...item });
3816        await manager.decrement(
3817          Inventory,
3818          { productId: item.productId },
3819          'stock',
3820          item.quantity,
3821        );
3822      }
3823 
3824      // If this throws, everything rolls back
3825      await this.paymentService.chargeWithManager(manager, order.id);
3826 
3827      return order;
3828    });
3829  }
3830}
3831 
3832// QueryRunner for manual transaction control
3833@Injectable()
3834export class TransferService {
3835  constructor(private dataSource: DataSource) {}
3836 
3837  async transfer(fromId: string, toId: string, amount: number): Promise<void> {
3838    const queryRunner = this.dataSource.createQueryRunner();
3839    await queryRunner.connect();
3840    await queryRunner.startTransaction();
3841 
3842    try {
3843      // Debit source account
3844      await queryRunner.manager.decrement(
3845        Account,
3846        { id: fromId },
3847        'balance',
3848        amount,
3849      );
3850 
3851      // Verify sufficient funds
3852      const source = await queryRunner.manager.findOne(Account, {
3853        where: { id: fromId },
3854      });
3855      if (source.balance < 0) {
3856        throw new BadRequestException('Insufficient funds');
3857      }
3858 
3859      // Credit destination account
3860      await queryRunner.manager.increment(
3861        Account,
3862        { id: toId },
3863        'balance',
3864        amount,
3865      );
3866 
3867      // Log the transaction
3868      await queryRunner.manager.save(TransactionLog, {
3869        fromId,
3870        toId,
3871        amount,
3872        timestamp: new Date(),
3873      });
3874 
3875      await queryRunner.commitTransaction();
3876    } catch (error) {
3877      await queryRunner.rollbackTransaction();
3878      throw error;
3879    } finally {
3880      await queryRunner.release();
3881    }
3882  }
3883}
3884 
3885// Repository method with transaction support
3886@Injectable()
3887export class UsersRepository {
3888  constructor(
3889    @InjectRepository(User) private repo: Repository<User>,
3890    private dataSource: DataSource,
3891  ) {}
3892 
3893  async createWithProfile(
3894    userData: CreateUserDto,
3895    profileData: CreateProfileDto,
3896  ): Promise<User> {
3897    return this.dataSource.transaction(async (manager) => {
3898      const user = await manager.save(User, userData);
3899      await manager.save(Profile, { ...profileData, userId: user.id });
3900      return user;
3901    });
3902  }
3903}
3904```
3905 
3906Reference: [TypeORM Transactions](https://typeorm.io/transactions)
3907 
3908---
3909 
3910## 8. API Design
3911 
3912**Section Impact: MEDIUM**
3913 
3914### 8.1 Use DTOs and Serialization for API Responses
3915 
3916**Impact: MEDIUM** — Response DTOs prevent accidental data exposure and ensure consistency
3917 
3918Never return entity objects directly from controllers. Use response DTOs with class-transformer's `@Exclude()` and `@Expose()` decorators to control exactly what data is sent to clients. This prevents accidental exposure of sensitive fields and provides a stable API contract.
3919 
3920**Incorrect (returning entities directly or manual spreading):**
3921 
3922```typescript
3923// Return entities directly
3924@Controller('users')
3925export class UsersController {
3926  @Get(':id')
3927  async findOne(@Param('id') id: string): Promise<User> {
3928    return this.usersService.findById(id);
3929    // Returns: { id, email, passwordHash, ssn, internalNotes, ... }
3930    // Exposes sensitive data!
3931  }
3932}
3933 
3934// Manual object spreading (error-prone)
3935@Get(':id')
3936async findOne(@Param('id') id: string) {
3937  const user = await this.usersService.findById(id);
3938  return {
3939    id: user.id,
3940    email: user.email,
3941    name: user.name,
3942    // Easy to forget to exclude sensitive fields
3943    // Hard to maintain across endpoints
3944  };
3945}
3946```
3947 
3948**Correct (use class-transformer with @Exclude and response DTOs):**
3949 
3950```typescript
3951// Enable class-transformer globally
3952async function bootstrap() {
3953  const app = await NestFactory.create(AppModule);
3954  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
3955  await app.listen(3000);
3956}
3957 
3958// Entity with serialization control
3959@Entity()
3960export class User {
3961  @PrimaryGeneratedColumn('uuid')
3962  id: string;
3963 
3964  @Column()
3965  email: string;
3966 
3967  @Column()
3968  name: string;
3969 
3970  @Column()
3971  @Exclude() // Never include in responses
3972  passwordHash: string;
3973 
3974  @Column({ nullable: true })
3975  @Exclude()
3976  ssn: string;
3977 
3978  @Column({ default: false })
3979  @Exclude({ toPlainOnly: true }) // Exclude from response, allow in requests
3980  isAdmin: boolean;
3981 
3982  @CreateDateColumn()
3983  createdAt: Date;
3984 
3985  @Column()
3986  @Exclude()
3987  internalNotes: string;
3988}
3989 
3990// Now returning entity is safe
3991@Controller('users')
3992export class UsersController {
3993  @Get(':id')
3994  async findOne(@Param('id') id: string): Promise<User> {
3995    return this.usersService.findById(id);
3996    // Returns: { id, email, name, createdAt }
3997    // Sensitive fields excluded automatically
3998  }
3999}
4000 
4001// For different response shapes, use explicit DTOs
4002export class UserResponseDto {
4003  @Expose()
4004  id: string;
4005 
4006  @Expose()
4007  email: string;
4008 
4009  @Expose()
4010  name: string;
4011 
4012  @Expose()
4013  @Transform(({ obj }) => obj.posts?.length || 0)
4014  postCount: number;
4015 
4016  constructor(partial: Partial<User>) {
4017    Object.assign(this, partial);
4018  }
4019}
4020 
4021export class UserDetailResponseDto extends UserResponseDto {
4022  @Expose()
4023  createdAt: Date;
4024 
4025  @Expose()
4026  @Type(() => PostResponseDto)
4027  posts: PostResponseDto[];
4028}
4029 
4030// Controller with explicit DTOs
4031@Controller('users')
4032export class UsersController {
4033  @Get()
4034  @SerializeOptions({ type: UserResponseDto })
4035  async findAll(): Promise<UserResponseDto[]> {
4036    const users = await this.usersService.findAll();
4037    return users.map(u => plainToInstance(UserResponseDto, u));
4038  }
4039 
4040  @Get(':id')
4041  async findOne(@Param('id') id: string): Promise<UserDetailResponseDto> {
4042    const user = await this.usersService.findByIdWithPosts(id);
4043    return plainToInstance(UserDetailResponseDto, user, {
4044      excludeExtraneousValues: true,
4045    });
4046  }
4047}
4048 
4049// Groups for conditional serialization
4050export class UserDto {
4051  @Expose()
4052  id: string;
4053 
4054  @Expose()
4055  name: string;
4056 
4057  @Expose({ groups: ['admin'] })
4058  email: string;
4059 
4060  @Expose({ groups: ['admin'] })
4061  createdAt: Date;
4062 
4063  @Expose({ groups: ['admin', 'owner'] })
4064  settings: UserSettings;
4065}
4066 
4067@Controller('users')
4068export class UsersController {
4069  @Get()
4070  @SerializeOptions({ groups: ['public'] })
4071  async findAllPublic(): Promise<UserDto[]> {
4072    // Returns: { id, name }
4073  }
4074 
4075  @Get('admin')
4076  @UseGuards(AdminGuard)
4077  @SerializeOptions({ groups: ['admin'] })
4078  async findAllAdmin(): Promise<UserDto[]> {
4079    // Returns: { id, name, email, createdAt }
4080  }
4081 
4082  @Get('me')
4083  @SerializeOptions({ groups: ['owner'] })
4084  async getProfile(@CurrentUser() user: User): Promise<UserDto> {
4085    // Returns: { id, name, settings }
4086  }
4087}
4088```
4089 
4090Reference: [NestJS Serialization](https://docs.nestjs.com/techniques/serialization)
4091 
4092---
4093 
4094### 8.2 Use Interceptors for Cross-Cutting Concerns
4095 
4096**Impact: MEDIUM-HIGH** — Interceptors provide clean separation for cross-cutting logic
4097 
4098Interceptors can transform responses, add logging, handle caching, and measure performance without polluting your business logic. They wrap the route handler execution, giving you access to both the request and response streams.
4099 
4100**Incorrect (logging and transformation in every method):**
4101 
4102```typescript
4103// Logging in every controller method
4104@Controller('users')
4105export class UsersController {
4106  @Get()
4107  async findAll(): Promise<User[]> {
4108    const start = Date.now();
4109    this.logger.log('findAll called');
4110 
4111    const users = await this.usersService.findAll();
4112 
4113    this.logger.log(`findAll completed in ${Date.now() - start}ms`);
4114    return users;
4115  }
4116 
4117  @Get(':id')
4118  async findOne(@Param('id') id: string): Promise<User> {
4119    const start = Date.now();
4120    this.logger.log(`findOne called with id: ${id}`);
4121 
4122    const user = await this.usersService.findOne(id);
4123 
4124    this.logger.log(`findOne completed in ${Date.now() - start}ms`);
4125    return user;
4126  }
4127  // Repeated in every method!
4128}
4129 
4130// Manual response wrapping
4131@Get()
4132async findAll(): Promise<{ data: User[]; meta: Meta }> {
4133  const users = await this.usersService.findAll();
4134  return {
4135    data: users,
4136    meta: { timestamp: new Date(), count: users.length },
4137  };
4138}
4139```
4140 
4141**Correct (use interceptors for cross-cutting concerns):**
4142 
4143```typescript
4144// Logging interceptor
4145@Injectable()
4146export class LoggingInterceptor implements NestInterceptor {
4147  private readonly logger = new Logger('HTTP');
4148 
4149  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
4150    const request = context.switchToHttp().getRequest();
4151    const { method, url, body } = request;
4152    const now = Date.now();
4153 
4154    return next.handle().pipe(
4155      tap({
4156        next: (data) => {
4157          const response = context.switchToHttp().getResponse();
4158          this.logger.log(
4159            `${method} ${url} ${response.statusCode} - ${Date.now() - now}ms`,
4160          );
4161        },
4162        error: (error) => {
4163          this.logger.error(
4164            `${method} ${url} ${error.status || 500} - ${Date.now() - now}ms`,
4165            error.stack,
4166          );
4167        },
4168      }),
4169    );
4170  }
4171}
4172 
4173// Response transformation interceptor
4174@Injectable()
4175export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
4176  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
4177    return next.handle().pipe(
4178      map((data) => ({
4179        data,
4180        meta: {
4181          timestamp: new Date().toISOString(),
4182          path: context.switchToHttp().getRequest().url,
4183        },
4184      })),
4185    );
4186  }
4187}
4188 
4189// Timeout interceptor
4190@Injectable()
4191export class TimeoutInterceptor implements NestInterceptor {
4192  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
4193    return next.handle().pipe(
4194      timeout(5000),
4195      catchError((err) => {
4196        if (err instanceof TimeoutError) {
4197          throw new RequestTimeoutException('Request timed out');
4198        }
4199        throw err;
4200      }),
4201    );
4202  }
4203}
4204 
4205// Apply globally or per-controller
4206@Module({
4207  providers: [
4208    { provide: APP_INTERCEPTOR, useClass: LoggingInterceptor },
4209    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },
4210  ],
4211})
4212export class AppModule {}
4213 
4214// Or per-controller
4215@Controller('users')
4216@UseInterceptors(LoggingInterceptor)
4217export class UsersController {
4218  @Get()
4219  async findAll(): Promise<User[]> {
4220    // Clean business logic only
4221    return this.usersService.findAll();
4222  }
4223}
4224 
4225// Custom cache interceptor with TTL
4226@Injectable()
4227export class HttpCacheInterceptor implements NestInterceptor {
4228  constructor(
4229    private cacheManager: Cache,
4230    private reflector: Reflector,
4231  ) {}
4232 
4233  async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
4234    const request = context.switchToHttp().getRequest();
4235 
4236    // Only cache GET requests
4237    if (request.method !== 'GET') {
4238      return next.handle();
4239    }
4240 
4241    const cacheKey = this.generateKey(request);
4242    const ttl = this.reflector.get<number>('cacheTTL', context.getHandler()) || 300;
4243 
4244    const cached = await this.cacheManager.get(cacheKey);
4245    if (cached) {
4246      return of(cached);
4247    }
4248 
4249    return next.handle().pipe(
4250      tap((response) => {
4251        this.cacheManager.set(cacheKey, response, ttl);
4252      }),
4253    );
4254  }
4255 
4256  private generateKey(request: Request): string {
4257    return `cache:${request.url}:${JSON.stringify(request.query)}`;
4258  }
4259}
4260 
4261// Usage with custom TTL
4262@Get()
4263@SetMetadata('cacheTTL', 600)
4264@UseInterceptors(HttpCacheInterceptor)
4265async findAll(): Promise<User[]> {
4266  return this.usersService.findAll();
4267}
4268 
4269// Error mapping interceptor
4270@Injectable()
4271export class ErrorMappingInterceptor implements NestInterceptor {
4272  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
4273    return next.handle().pipe(
4274      catchError((error) => {
4275        if (error instanceof EntityNotFoundError) {
4276          throw new NotFoundException(error.message);
4277        }
4278        if (error instanceof QueryFailedError) {
4279          if (error.message.includes('duplicate')) {
4280            throw new ConflictException('Resource already exists');
4281          }
4282        }
4283        throw error;
4284      }),
4285    );
4286  }
4287}
4288```
4289 
4290Reference: [NestJS Interceptors](https://docs.nestjs.com/interceptors)
4291 
4292---
4293 
4294### 8.3 Use Pipes for Input Transformation
4295 
4296**Impact: MEDIUM** — Pipes ensure clean, validated data reaches your handlers
4297 
4298Use built-in pipes like `ParseIntPipe`, `ParseUUIDPipe`, and `DefaultValuePipe` for common transformations. Create custom pipes for business-specific transformations. Pipes separate validation/transformation logic from controllers.
4299 
4300**Incorrect (manual type parsing in handlers):**
4301 
4302```typescript
4303// Manual type parsing in handlers
4304@Controller('users')
4305export class UsersController {
4306  @Get(':id')
4307  async findOne(@Param('id') id: string): Promise<User> {
4308    // Manual validation in every handler
4309    const uuid = id.trim();
4310    if (!isUUID(uuid)) {
4311      throw new BadRequestException('Invalid UUID');
4312    }
4313    return this.usersService.findOne(uuid);
4314  }
4315 
4316  @Get()
4317  async findAll(
4318    @Query('page') page: string,
4319    @Query('limit') limit: string,
4320  ): Promise<User[]> {
4321    // Manual parsing and defaults
4322    const pageNum = parseInt(page) || 1;
4323    const limitNum = parseInt(limit) || 10;
4324    return this.usersService.findAll(pageNum, limitNum);
4325  }
4326}
4327 
4328// Type coercion without validation
4329@Get()
4330async search(@Query('price') price: string): Promise<Product[]> {
4331  const priceNum = +price; // NaN if invalid, no error
4332  return this.productsService.findByPrice(priceNum);
4333}
4334```
4335 
4336**Correct (use built-in and custom pipes):**
4337 
4338```typescript
4339// Use built-in pipes for common transformations
4340@Controller('users')
4341export class UsersController {
4342  @Get(':id')
4343  async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
4344    // id is guaranteed to be a valid UUID
4345    return this.usersService.findOne(id);
4346  }
4347 
4348  @Get()
4349  async findAll(
4350    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
4351    @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
4352  ): Promise<User[]> {
4353    // Automatic defaults and type conversion
4354    return this.usersService.findAll(page, limit);
4355  }
4356 
4357  @Get('by-status/:status')
4358  async findByStatus(
4359    @Param('status', new ParseEnumPipe(UserStatus)) status: UserStatus,
4360  ): Promise<User[]> {
4361    return this.usersService.findByStatus(status);
4362  }
4363}
4364 
4365// Custom pipe for business logic
4366@Injectable()
4367export class ParseDatePipe implements PipeTransform<string, Date> {
4368  transform(value: string): Date {
4369    const date = new Date(value);
4370    if (isNaN(date.getTime())) {
4371      throw new BadRequestException('Invalid date format');
4372    }
4373    return date;
4374  }
4375}
4376 
4377@Get('reports')
4378async getReports(
4379  @Query('from', ParseDatePipe) from: Date,
4380  @Query('to', ParseDatePipe) to: Date,
4381): Promise<Report[]> {
4382  return this.reportsService.findBetween(from, to);
4383}
4384 
4385// Custom transformation pipes
4386@Injectable()
4387export class NormalizeEmailPipe implements PipeTransform<string, string> {
4388  transform(value: string): string {
4389    if (!value) return value;
4390    return value.trim().toLowerCase();
4391  }
4392}
4393 
4394// Parse comma-separated values
4395@Injectable()
4396export class ParseArrayPipe implements PipeTransform<string, string[]> {
4397  transform(value: string): string[] {
4398    if (!value) return [];
4399    return value.split(',').map((v) => v.trim()).filter(Boolean);
4400  }
4401}
4402 
4403@Get('products')
4404async findProducts(
4405  @Query('ids', ParseArrayPipe) ids: string[],
4406  @Query('email', NormalizeEmailPipe) email: string,
4407): Promise<Product[]> {
4408  // ids is already an array, email is normalized
4409  return this.productsService.findByIds(ids);
4410}
4411 
4412// Sanitize HTML input
4413@Injectable()
4414export class SanitizeHtmlPipe implements PipeTransform<string, string> {
4415  transform(value: string): string {
4416    if (!value) return value;
4417    return sanitizeHtml(value, { allowedTags: [] });
4418  }
4419}
4420 
4421// Global validation pipe with transformation
4422app.useGlobalPipes(
4423  new ValidationPipe({
4424    whitelist: true, // Strip non-DTO properties
4425    transform: true, // Auto-transform to DTO types
4426    transformOptions: {
4427      enableImplicitConversion: true, // Convert query strings to numbers
4428    },
4429    forbidNonWhitelisted: true, // Throw on extra properties
4430  }),
4431);
4432 
4433// DTO with transformation decorators
4434export class FindProductsDto {
4435  @IsOptional()
4436  @Type(() => Number)
4437  @IsInt()
4438  @Min(1)
4439  page?: number = 1;
4440 
4441  @IsOptional()
4442  @Type(() => Number)
4443  @IsInt()
4444  @Min(1)
4445  @Max(100)
4446  limit?: number = 10;
4447 
4448  @IsOptional()
4449  @Transform(({ value }) => value?.toLowerCase())
4450  @IsString()
4451  search?: string;
4452 
4453  @IsOptional()
4454  @Transform(({ value }) => value?.split(','))
4455  @IsArray()
4456  @IsString({ each: true })
4457  categories?: string[];
4458}
4459 
4460@Get()
4461async findAll(@Query() dto: FindProductsDto): Promise<Product[]> {
4462  // dto is already transformed and validated
4463  return this.productsService.findAll(dto);
4464}
4465 
4466// Pipe error customization
4467@Injectable()
4468export class CustomParseIntPipe extends ParseIntPipe {
4469  constructor() {
4470    super({
4471      exceptionFactory: (error) =>
4472        new BadRequestException(`${error} must be a valid integer`),
4473    });
4474  }
4475}
4476 
4477// Or use options on built-in pipes
4478@Get(':id')
4479async findOne(
4480  @Param(
4481    'id',
4482    new ParseIntPipe({
4483      errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE,
4484      exceptionFactory: () => new NotAcceptableException('ID must be numeric'),
4485    }),
4486  )
4487  id: number,
4488): Promise<Item> {
4489  return this.itemsService.findOne(id);
4490}
4491```
4492 
4493Reference: [NestJS Pipes](https://docs.nestjs.com/pipes)
4494 
4495---
4496 
4497### 8.4 Use API Versioning for Breaking Changes
4498 
4499**Impact: MEDIUM** — Versioning allows you to evolve APIs without breaking existing clients
4500 
4501Use NestJS built-in versioning when making breaking changes to your API. Choose a versioning strategy (URI, header, or media type) and apply it consistently. This allows old clients to continue working while new clients use updated endpoints.
4502 
4503**Incorrect (breaking changes without versioning):**
4504 
4505```typescript
4506// Breaking changes without versioning
4507@Controller('users')
4508export class UsersController {
4509  @Get(':id')
4510  async findOne(@Param('id') id: string): Promise<User> {
4511    // Original response: { id, name, email }
4512    // Later changed to: { id, firstName, lastName, emailAddress }
4513    // Old clients break!
4514    return this.usersService.findOne(id);
4515  }
4516}
4517 
4518// Manual versioning in routes
4519@Controller('v1/users')
4520export class UsersV1Controller {}
4521 
4522@Controller('v2/users')
4523export class UsersV2Controller {}
4524// Inconsistent, error-prone, hard to maintain
4525```
4526 
4527**Correct (use NestJS built-in versioning):**
4528 
4529```typescript
4530// Enable versioning in main.ts
4531async function bootstrap() {
4532  const app = await NestFactory.create(AppModule);
4533 
4534  // URI versioning: /v1/users, /v2/users
4535  app.enableVersioning({
4536    type: VersioningType.URI,
4537    defaultVersion: '1',
4538  });
4539 
4540  // Or header versioning: X-API-Version: 1
4541  app.enableVersioning({
4542    type: VersioningType.HEADER,
4543    header: 'X-API-Version',
4544    defaultVersion: '1',
4545  });
4546 
4547  // Or media type: Accept: application/json;v=1
4548  app.enableVersioning({
4549    type: VersioningType.MEDIA_TYPE,
4550    key: 'v=',
4551    defaultVersion: '1',
4552  });
4553 
4554  await app.listen(3000);
4555}
4556 
4557// Version-specific controllers
4558@Controller('users')
4559@Version('1')
4560export class UsersV1Controller {
4561  @Get(':id')
4562  async findOne(@Param('id') id: string): Promise<UserV1Response> {
4563    const user = await this.usersService.findOne(id);
4564    // V1 response format
4565    return {
4566      id: user.id,
4567      name: user.name,
4568      email: user.email,
4569    };
4570  }
4571}
4572 
4573@Controller('users')
4574@Version('2')
4575export class UsersV2Controller {
4576  @Get(':id')
4577  async findOne(@Param('id') id: string): Promise<UserV2Response> {
4578    const user = await this.usersService.findOne(id);
4579    // V2 response format with breaking changes
4580    return {
4581      id: user.id,
4582      firstName: user.firstName,
4583      lastName: user.lastName,
4584      emailAddress: user.email,
4585      createdAt: user.createdAt,
4586    };
4587  }
4588}
4589 
4590// Per-route versioning - different versions for different routes
4591@Controller('users')
4592export class UsersController {
4593  @Get()
4594  @Version('1')
4595  findAllV1(): Promise<UserV1Response[]> {
4596    return this.usersService.findAllV1();
4597  }
4598 
4599  @Get()
4600  @Version('2')
4601  findAllV2(): Promise<UserV2Response[]> {
4602    return this.usersService.findAllV2();
4603  }
4604 
4605  @Get(':id')
4606  @Version(['1', '2']) // Same handler for multiple versions
4607  findOne(@Param('id') id: string): Promise<User> {
4608    return this.usersService.findOne(id);
4609  }
4610 
4611  @Post()
4612  @Version(VERSION_NEUTRAL) // Available in all versions
4613  create(@Body() dto: CreateUserDto): Promise<User> {
4614    return this.usersService.create(dto);
4615  }
4616}
4617 
4618// Shared service with version-specific logic
4619@Injectable()
4620export class UsersService {
4621  async findOne(id: string, version: string): Promise<any> {
4622    const user = await this.repo.findOne({ where: { id } });
4623 
4624    if (version === '1') {
4625      return this.toV1Response(user);
4626    }
4627    return this.toV2Response(user);
4628  }
4629 
4630  private toV1Response(user: User): UserV1Response {
4631    return {
4632      id: user.id,
4633      name: `${user.firstName} ${user.lastName}`,
4634      email: user.email,
4635    };
4636  }
4637 
4638  private toV2Response(user: User): UserV2Response {
4639    return {
4640      id: user.id,
4641      firstName: user.firstName,
4642      lastName: user.lastName,
4643      emailAddress: user.email,
4644      createdAt: user.createdAt,
4645    };
4646  }
4647}
4648 
4649// Controller extracts version
4650@Controller('users')
4651export class UsersController {
4652  @Get(':id')
4653  async findOne(
4654    @Param('id') id: string,
4655    @Headers('X-API-Version') version: string = '1',
4656  ): Promise<any> {
4657    return this.usersService.findOne(id, version);
4658  }
4659}
4660 
4661// Deprecation strategy - mark old versions as deprecated
4662@Controller('users')
4663@Version('1')
4664@UseInterceptors(DeprecationInterceptor)
4665export class UsersV1Controller {
4666  // All V1 routes will include deprecation warning
4667}
4668 
4669@Injectable()
4670export class DeprecationInterceptor implements NestInterceptor {
4671  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
4672    const response = context.switchToHttp().getResponse();
4673    response.setHeader('Deprecation', 'true');
4674    response.setHeader('Sunset', 'Sat, 1 Jan 2025 00:00:00 GMT');
4675    response.setHeader('Link', '</v2/users>; rel="successor-version"');
4676 
4677    return next.handle();
4678  }
4679}
4680```
4681 
4682Reference: [NestJS Versioning](https://docs.nestjs.com/techniques/versioning)
4683 
4684---
4685 
4686## 9. Microservices
4687 
4688**Section Impact: MEDIUM**
4689 
4690### 9.1 Implement Health Checks for Microservices
4691 
4692**Impact: MEDIUM-HIGH** — Health checks enable orchestrators to manage service lifecycle
4693 
4694Implement liveness and readiness probes using `@nestjs/terminus`. Liveness checks determine if the service should be restarted. Readiness checks determine if the service can accept traffic. Proper health checks enable Kubernetes and load balancers to route traffic correctly.
4695 
4696**Incorrect (simple ping that doesn't check dependencies):**
4697 
4698```typescript
4699// Simple ping that doesn't check dependencies
4700@Controller('health')
4701export class HealthController {
4702  @Get()
4703  check(): string {
4704    return 'OK'; // Service might be unhealthy but returns OK
4705  }
4706}
4707 
4708// Health check that blocks on slow dependencies
4709@Controller('health')
4710export class HealthController {
4711  @Get()
4712  async check(): Promise<string> {
4713    // If database is slow, health check times out
4714    await this.userRepo.findOne({ where: { id: '1' } });
4715    await this.redis.ping();
4716    await this.externalApi.healthCheck();
4717    return 'OK';
4718  }
4719}
4720```
4721 
4722**Correct (use @nestjs/terminus for comprehensive health checks):**
4723 
4724```typescript
4725// Use @nestjs/terminus for comprehensive health checks
4726import {
4727  HealthCheckService,
4728  HttpHealthIndicator,
4729  TypeOrmHealthIndicator,
4730  HealthCheck,
4731  DiskHealthIndicator,
4732  MemoryHealthIndicator,
4733} from '@nestjs/terminus';
4734 
4735@Controller('health')
4736export class HealthController {
4737  constructor(
4738    private health: HealthCheckService,
4739    private http: HttpHealthIndicator,
4740    private db: TypeOrmHealthIndicator,
4741    private disk: DiskHealthIndicator,
4742    private memory: MemoryHealthIndicator,
4743  ) {}
4744 
4745  // Liveness probe - is the service alive?
4746  @Get('live')
4747  @HealthCheck()
4748  liveness() {
4749    return this.health.check([
4750      // Basic checks only
4751      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024), // 200MB
4752    ]);
4753  }
4754 
4755  // Readiness probe - can the service handle traffic?
4756  @Get('ready')
4757  @HealthCheck()
4758  readiness() {
4759    return this.health.check([
4760      () => this.db.pingCheck('database'),
4761      () =>
4762        this.http.pingCheck('redis', 'http://redis:6379', { timeout: 1000 }),
4763      () =>
4764        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
4765    ]);
4766  }
4767 
4768  // Deep health check for debugging
4769  @Get('deep')
4770  @HealthCheck()
4771  deepCheck() {
4772    return this.health.check([
4773      () => this.db.pingCheck('database'),
4774      () => this.memory.checkHeap('memory_heap', 200 * 1024 * 1024),
4775      () => this.memory.checkRSS('memory_rss', 300 * 1024 * 1024),
4776      () =>
4777        this.disk.checkStorage('disk', { path: '/', thresholdPercent: 0.9 }),
4778      () =>
4779        this.http.pingCheck('external-api', 'https://api.example.com/health'),
4780    ]);
4781  }
4782}
4783 
4784// Custom indicator for business-specific health
4785@Injectable()
4786export class QueueHealthIndicator extends HealthIndicator {
4787  constructor(private queueService: QueueService) {
4788    super();
4789  }
4790 
4791  async isHealthy(key: string): Promise<HealthIndicatorResult> {
4792    const queueStats = await this.queueService.getStats();
4793 
4794    const isHealthy = queueStats.failedCount < 100;
4795    const result = this.getStatus(key, isHealthy, {
4796      waiting: queueStats.waitingCount,
4797      active: queueStats.activeCount,
4798      failed: queueStats.failedCount,
4799    });
4800 
4801    if (!isHealthy) {
4802      throw new HealthCheckError('Queue unhealthy', result);
4803    }
4804 
4805    return result;
4806  }
4807}
4808 
4809// Redis health indicator
4810@Injectable()
4811export class RedisHealthIndicator extends HealthIndicator {
4812  constructor(@InjectRedis() private redis: Redis) {
4813    super();
4814  }
4815 
4816  async isHealthy(key: string): Promise<HealthIndicatorResult> {
4817    try {
4818      const pong = await this.redis.ping();
4819      return this.getStatus(key, pong === 'PONG');
4820    } catch (error) {
4821      throw new HealthCheckError('Redis check failed', this.getStatus(key, false));
4822    }
4823  }
4824}
4825 
4826// Use custom indicators
4827@Get('ready')
4828@HealthCheck()
4829readiness() {
4830  return this.health.check([
4831    () => this.db.pingCheck('database'),
4832    () => this.redis.isHealthy('redis'),
4833    () => this.queue.isHealthy('job-queue'),
4834  ]);
4835}
4836 
4837// Graceful shutdown handling
4838@Injectable()
4839export class GracefulShutdownService implements OnApplicationShutdown {
4840  private isShuttingDown = false;
4841 
4842  isShutdown(): boolean {
4843    return this.isShuttingDown;
4844  }
4845 
4846  async onApplicationShutdown(signal: string): Promise<void> {
4847    this.isShuttingDown = true;
4848    console.log(`Shutting down on ${signal}`);
4849 
4850    // Wait for in-flight requests
4851    await new Promise((resolve) => setTimeout(resolve, 5000));
4852  }
4853}
4854 
4855// Health check respects shutdown state
4856@Get('ready')
4857@HealthCheck()
4858readiness() {
4859  if (this.shutdownService.isShutdown()) {
4860    throw new ServiceUnavailableException('Shutting down');
4861  }
4862 
4863  return this.health.check([
4864    () => this.db.pingCheck('database'),
4865  ]);
4866}
4867```
4868 
4869### Kubernetes Configuration
4870 
4871```yaml
4872# Kubernetes deployment with probes
4873apiVersion: apps/v1
4874kind: Deployment
4875metadata:
4876  name: api-service
4877spec:
4878  template:
4879    spec:
4880      containers:
4881        - name: api
4882          image: api-service:latest
4883          ports:
4884            - containerPort: 3000
4885          livenessProbe:
4886            httpGet:
4887              path: /health/live
4888              port: 3000
4889            initialDelaySeconds: 30
4890            periodSeconds: 10
4891            timeoutSeconds: 5
4892            failureThreshold: 3
4893          readinessProbe:
4894            httpGet:
4895              path: /health/ready
4896              port: 3000
4897            initialDelaySeconds: 5
4898            periodSeconds: 5
4899            timeoutSeconds: 3
4900            failureThreshold: 3
4901          startupProbe:
4902            httpGet:
4903              path: /health/live
4904              port: 3000
4905            initialDelaySeconds: 0
4906            periodSeconds: 5
4907            failureThreshold: 30
4908```
4909 
4910Reference: [NestJS Terminus](https://docs.nestjs.com/recipes/terminus)
4911 
4912---
4913 
4914### 9.2 Use Message and Event Patterns Correctly
4915 
4916**Impact: MEDIUM** — Proper patterns ensure reliable microservice communication
4917 
4918NestJS microservices support two communication patterns: request-response (MessagePattern) and event-based (EventPattern). Use MessagePattern when you need a response, and EventPattern for fire-and-forget notifications. Understanding the difference prevents communication bugs.
4919 
4920**Incorrect (using wrong pattern for use case):**
4921 
4922```typescript
4923// Use @MessagePattern for fire-and-forget
4924@Controller()
4925export class NotificationsController {
4926  @MessagePattern('user.created')
4927  async handleUserCreated(data: UserCreatedEvent) {
4928    // This WAITS for response, blocking the sender
4929    await this.emailService.sendWelcome(data.email);
4930    // If email fails, sender gets an error (coupling!)
4931  }
4932}
4933 
4934// Use @EventPattern expecting a response
4935@Controller()
4936export class OrdersController {
4937  @EventPattern('inventory.check')
4938  async checkInventory(data: CheckInventoryDto) {
4939    const available = await this.inventory.check(data);
4940    return available; // This return value is IGNORED with @EventPattern!
4941  }
4942}
4943 
4944// Tight coupling in client
4945@Injectable()
4946export class UsersService {
4947  async createUser(dto: CreateUserDto): Promise<User> {
4948    const user = await this.repo.save(dto);
4949 
4950    // Blocks until notification service responds
4951    await this.client.send('user.created', user).toPromise();
4952    // If notification service is down, user creation fails!
4953 
4954    return user;
4955  }
4956}
4957```
4958 
4959**Correct (use MessagePattern for request-response, EventPattern for fire-and-forget):**
4960 
4961```typescript
4962// MessagePattern: Request-Response (when you NEED a response)
4963@Controller()
4964export class InventoryController {
4965  @MessagePattern({ cmd: 'check_inventory' })
4966  async checkInventory(data: CheckInventoryDto): Promise<InventoryResult> {
4967    const result = await this.inventoryService.check(data.productId, data.quantity);
4968    return result; // Response sent back to caller
4969  }
4970}
4971 
4972// Client expects response
4973@Injectable()
4974export class OrdersService {
4975  async createOrder(dto: CreateOrderDto): Promise<Order> {
4976    // Check inventory - we NEED this response to proceed
4977    const inventory = await firstValueFrom(
4978      this.inventoryClient.send<InventoryResult>(
4979        { cmd: 'check_inventory' },
4980        { productId: dto.productId, quantity: dto.quantity },
4981      ),
4982    );
4983 
4984    if (!inventory.available) {
4985      throw new BadRequestException('Insufficient inventory');
4986    }
4987 
4988    return this.repo.save(dto);
4989  }
4990}
4991 
4992// EventPattern: Fire-and-Forget (for notifications, side effects)
4993@Controller()
4994export class NotificationsController {
4995  @EventPattern('user.created')
4996  async handleUserCreated(data: UserCreatedEvent): Promise<void> {
4997    // No return value needed - just process the event
4998    await this.emailService.sendWelcome(data.email);
4999    await this.analyticsService.track('user_signup', data);
5000    // If this fails, it doesn't affect the sender
5001  }
5002}
5003 
5004// Client emits event without waiting
5005@Injectable()
5006export class UsersService {
5007  async createUser(dto: CreateUserDto): Promise<User> {
5008    const user = await this.repo.save(dto);
5009 
5010    // Fire and forget - doesn't block, doesn't wait
5011    this.eventClient.emit('user.created', {
5012      userId: user.id,
5013      email: user.email,
5014      timestamp: new Date(),
5015    });
5016 
5017    return user; // User creation succeeds regardless of event handling
5018  }
5019}
5020 
5021// Hybrid pattern for critical events
5022@Injectable()
5023export class OrdersService {
5024  async createOrder(dto: CreateOrderDto): Promise<Order> {
5025    const order = await this.repo.save(dto);
5026 
5027    // Critical: inventory reservation (use MessagePattern)
5028    const reserved = await firstValueFrom(
5029      this.inventoryClient.send({ cmd: 'reserve_inventory' }, {
5030        orderId: order.id,
5031        items: dto.items,
5032      }),
5033    );
5034 
5035    if (!reserved.success) {
5036      await this.repo.delete(order.id);
5037      throw new BadRequestException('Could not reserve inventory');
5038    }
5039 
5040    // Non-critical: notifications (use EventPattern)
5041    this.eventClient.emit('order.created', {
5042      orderId: order.id,
5043      userId: dto.userId,
5044      total: dto.total,
5045    });
5046 
5047    return order;
5048  }
5049}
5050 
5051// Error handling patterns
5052// MessagePattern errors propagate to caller
5053@MessagePattern({ cmd: 'get_user' })
5054async getUser(userId: string): Promise<User> {
5055  const user = await this.repo.findOne({ where: { id: userId } });
5056  if (!user) {
5057    throw new RpcException('User not found'); // Received by caller
5058  }
5059  return user;
5060}
5061 
5062// EventPattern errors should be handled locally
5063@EventPattern('order.created')
5064async handleOrderCreated(data: OrderCreatedEvent): Promise<void> {
5065  try {
5066    await this.processOrder(data);
5067  } catch (error) {
5068    // Log and potentially retry - don't throw
5069    this.logger.error('Failed to process order event', error);
5070    await this.deadLetterQueue.add(data);
5071  }
5072}
5073```
5074 
5075Reference: [NestJS Microservices](https://docs.nestjs.com/microservices/basics)
5076 
5077---
5078 
5079### 9.3 Use Message Queues for Background Jobs
5080 
5081**Impact: MEDIUM-HIGH** — Queues enable reliable background processing
5082 
5083Use `@nestjs/bullmq` for background job processing. Queues decouple long-running tasks from HTTP requests, enable retry logic, and distribute workload across workers. Use them for emails, file processing, notifications, and any task that shouldn't block user requests.
5084 
5085**Incorrect (long-running tasks in HTTP handlers):**
5086 
5087```typescript
5088// Long-running tasks in HTTP handlers
5089@Controller('reports')
5090export class ReportsController {
5091  @Post()
5092  async generate(@Body() dto: GenerateReportDto): Promise<Report> {
5093    // This blocks the request for potentially minutes
5094    const data = await this.fetchLargeDataset(dto);
5095    const report = await this.processData(data); // Slow!
5096    await this.sendEmail(dto.email, report); // Can fail!
5097    return report; // Client times out
5098  }
5099}
5100 
5101// Fire-and-forget without retry
5102@Injectable()
5103export class EmailService {
5104  async sendWelcome(email: string): Promise<void> {
5105    // If this fails, email is never sent
5106    await this.mailer.send({ to: email, template: 'welcome' });
5107    // No retry, no tracking, no visibility
5108  }
5109}
5110 
5111// Use setInterval for scheduled tasks
5112setInterval(async () => {
5113  await cleanupOldRecords();
5114}, 60000); // No error handling, memory leaks
5115```
5116 
5117**Correct (use BullMQ for background processing):**
5118 
5119```typescript
5120// Configure BullMQ
5121import { BullModule } from '@nestjs/bullmq';
5122 
5123@Module({
5124  imports: [
5125    BullModule.forRoot({
5126      connection: {
5127        host: 'localhost',
5128        port: 6379,
5129      },
5130      defaultJobOptions: {
5131        removeOnComplete: 1000,
5132        removeOnFail: 5000,
5133        attempts: 3,
5134        backoff: {
5135          type: 'exponential',
5136          delay: 1000,
5137        },
5138      },
5139    }),
5140    BullModule.registerQueue(
5141      { name: 'email' },
5142      { name: 'reports' },
5143      { name: 'notifications' },
5144    ),
5145  ],
5146})
5147export class QueueModule {}
5148 
5149// Producer: Add jobs to queue
5150@Injectable()
5151export class ReportsService {
5152  constructor(
5153    @InjectQueue('reports') private reportsQueue: Queue,
5154  ) {}
5155 
5156  async requestReport(dto: GenerateReportDto): Promise<{ jobId: string }> {
5157    // Return immediately, process in background
5158    const job = await this.reportsQueue.add('generate', dto, {
5159      priority: dto.urgent ? 1 : 10,
5160      delay: dto.scheduledFor ? Date.parse(dto.scheduledFor) - Date.now() : 0,
5161    });
5162 
5163    return { jobId: job.id };
5164  }
5165 
5166  async getJobStatus(jobId: string): Promise<JobStatus> {
5167    const job = await this.reportsQueue.getJob(jobId);
5168    return {
5169      status: await job.getState(),
5170      progress: job.progress,
5171      result: job.returnvalue,
5172    };
5173  }
5174}
5175 
5176// Consumer: Process jobs
5177@Processor('reports')
5178export class ReportsProcessor {
5179  private readonly logger = new Logger(ReportsProcessor.name);
5180 
5181  @Process('generate')
5182  async generateReport(job: Job<GenerateReportDto>): Promise<Report> {
5183    this.logger.log(`Processing report job ${job.id}`);
5184 
5185    // Update progress
5186    await job.updateProgress(10);
5187 
5188    const data = await this.fetchData(job.data);
5189    await job.updateProgress(50);
5190 
5191    const report = await this.processData(data);
5192    await job.updateProgress(90);
5193 
5194    await this.saveReport(report);
5195    await job.updateProgress(100);
5196 
5197    return report;
5198  }
5199 
5200  @OnQueueActive()
5201  onActive(job: Job) {
5202    this.logger.log(`Processing job ${job.id}`);
5203  }
5204 
5205  @OnQueueCompleted()
5206  onCompleted(job: Job, result: any) {
5207    this.logger.log(`Job ${job.id} completed`);
5208  }
5209 
5210  @OnQueueFailed()
5211  onFailed(job: Job, error: Error) {
5212    this.logger.error(`Job ${job.id} failed: ${error.message}`);
5213  }
5214}
5215 
5216// Email queue with retry
5217@Processor('email')
5218export class EmailProcessor {
5219  @Process('send')
5220  async sendEmail(job: Job<SendEmailDto>): Promise<void> {
5221    const { to, template, data } = job.data;
5222 
5223    try {
5224      await this.mailer.send({
5225        to,
5226        template,
5227        context: data,
5228      });
5229    } catch (error) {
5230      // BullMQ will retry based on job options
5231      throw error;
5232    }
5233  }
5234}
5235 
5236// Usage
5237@Injectable()
5238export class NotificationService {
5239  constructor(@InjectQueue('email') private emailQueue: Queue) {}
5240 
5241  async sendWelcome(user: User): Promise<void> {
5242    await this.emailQueue.add(
5243      'send',
5244      {
5245        to: user.email,
5246        template: 'welcome',
5247        data: { name: user.name },
5248      },
5249      {
5250        attempts: 5,
5251        backoff: { type: 'exponential', delay: 5000 },
5252      },
5253    );
5254  }
5255}
5256 
5257// Scheduled jobs
5258@Injectable()
5259export class ScheduledJobsService implements OnModuleInit {
5260  constructor(@InjectQueue('maintenance') private queue: Queue) {}
5261 
5262  async onModuleInit(): Promise<void> {
5263    // Clean up old reports daily at midnight
5264    await this.queue.add(
5265      'cleanup',
5266      {},
5267      {
5268        repeat: { cron: '0 0 * * *' },
5269        jobId: 'daily-cleanup', // Prevent duplicates
5270      },
5271    );
5272 
5273    // Send digest every hour
5274    await this.queue.add(
5275      'digest',
5276      {},
5277      {
5278        repeat: { every: 60 * 60 * 1000 },
5279        jobId: 'hourly-digest',
5280      },
5281    );
5282  }
5283}
5284 
5285@Processor('maintenance')
5286export class MaintenanceProcessor {
5287  @Process('cleanup')
5288  async cleanup(): Promise<void> {
5289    await this.cleanupOldReports();
5290    await this.cleanupExpiredSessions();
5291  }
5292 
5293  @Process('digest')
5294  async sendDigest(): Promise<void> {
5295    const users = await this.getUsersForDigest();
5296    for (const user of users) {
5297      await this.emailQueue.add('send', { to: user.email, template: 'digest' });
5298    }
5299  }
5300}
5301 
5302// Queue monitoring with Bull Board
5303import { BullBoardModule } from '@bull-board/nestjs';
5304import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
5305 
5306@Module({
5307  imports: [
5308    BullBoardModule.forRoot({
5309      route: '/admin/queues',
5310      adapter: ExpressAdapter,
5311    }),
5312    BullBoardModule.forFeature({
5313      name: 'email',
5314      adapter: BullMQAdapter,
5315    }),
5316    BullBoardModule.forFeature({
5317      name: 'reports',
5318      adapter: BullMQAdapter,
5319    }),
5320  ],
5321})
5322export class AdminModule {}
5323```
5324 
5325Reference: [NestJS Queues](https://docs.nestjs.com/techniques/queues)
5326 
5327---
5328 
5329## 10. DevOps & Deployment
5330 
5331**Section Impact: LOW-MEDIUM**
5332 
5333### 10.1 Implement Graceful Shutdown
5334 
5335**Impact: MEDIUM-HIGH** — Proper shutdown handling ensures zero-downtime deployments
5336 
5337Handle SIGTERM and SIGINT signals to gracefully shutdown your NestJS application. Stop accepting new requests, wait for in-flight requests to complete, close database connections, and clean up resources. This prevents data loss and connection errors during deployments.
5338 
5339**Incorrect (ignoring shutdown signals):**
5340 
5341```typescript
5342// Ignore shutdown signals
5343async function bootstrap() {
5344  const app = await NestFactory.create(AppModule);
5345  await app.listen(3000);
5346  // App crashes immediately on SIGTERM
5347  // In-flight requests fail
5348  // Database connections are abruptly closed
5349}
5350 
5351// Long-running tasks without cancellation
5352@Injectable()
5353export class ProcessingService {
5354  async processLargeFile(file: File): Promise<void> {
5355    // No way to interrupt this during shutdown
5356    for (let i = 0; i < file.chunks.length; i++) {
5357      await this.processChunk(file.chunks[i]);
5358      // May run for minutes, blocking shutdown
5359    }
5360  }
5361}
5362```
5363 
5364**Correct (enable shutdown hooks and handle cleanup):**
5365 
5366```typescript
5367// Enable shutdown hooks in main.ts
5368async function bootstrap() {
5369  const app = await NestFactory.create(AppModule);
5370 
5371  // Enable shutdown hooks
5372  app.enableShutdownHooks();
5373 
5374  // Optional: Add timeout for forced shutdown
5375  const server = await app.listen(3000);
5376  server.setTimeout(30000); // 30 second timeout
5377 
5378  // Handle graceful shutdown
5379  const signals = ['SIGTERM', 'SIGINT'];
5380  signals.forEach((signal) => {
5381    process.on(signal, async () => {
5382      console.log(`Received ${signal}, starting graceful shutdown...`);
5383 
5384      // Stop accepting new connections
5385      server.close(async () => {
5386        console.log('HTTP server closed');
5387        await app.close();
5388        process.exit(0);
5389      });
5390 
5391      // Force exit after timeout
5392      setTimeout(() => {
5393        console.error('Forced shutdown after timeout');
5394        process.exit(1);
5395      }, 30000);
5396    });
5397  });
5398}
5399 
5400// Lifecycle hooks for cleanup
5401@Injectable()
5402export class DatabaseService implements OnApplicationShutdown {
5403  private readonly connections: Connection[] = [];
5404 
5405  async onApplicationShutdown(signal?: string): Promise<void> {
5406    console.log(`Database service shutting down on ${signal}`);
5407 
5408    // Close all connections gracefully
5409    await Promise.all(
5410      this.connections.map((conn) => conn.close()),
5411    );
5412 
5413    console.log('All database connections closed');
5414  }
5415}
5416 
5417// Queue processor with graceful shutdown
5418@Injectable()
5419export class QueueService implements OnApplicationShutdown, OnModuleDestroy {
5420  private isShuttingDown = false;
5421 
5422  onModuleDestroy(): void {
5423    this.isShuttingDown = true;
5424  }
5425 
5426  async onApplicationShutdown(): Promise<void> {
5427    // Wait for current jobs to complete
5428    await this.queue.close();
5429  }
5430 
5431  async processJob(job: Job): Promise<void> {
5432    if (this.isShuttingDown) {
5433      throw new Error('Service is shutting down');
5434    }
5435    await this.doWork(job);
5436  }
5437}
5438 
5439// WebSocket gateway cleanup
5440@WebSocketGateway()
5441export class EventsGateway implements OnApplicationShutdown {
5442  @WebSocketServer()
5443  server: Server;
5444 
5445  async onApplicationShutdown(): Promise<void> {
5446    // Notify all connected clients
5447    this.server.emit('shutdown', { message: 'Server is shutting down' });
5448 
5449    // Close all connections
5450    this.server.disconnectSockets();
5451  }
5452}
5453 
5454// Health check integration
5455@Injectable()
5456export class ShutdownService {
5457  private isShuttingDown = false;
5458 
5459  startShutdown(): void {
5460    this.isShuttingDown = true;
5461  }
5462 
5463  isShutdown(): boolean {
5464    return this.isShuttingDown;
5465  }
5466}
5467 
5468@Controller('health')
5469export class HealthController {
5470  constructor(private shutdownService: ShutdownService) {}
5471 
5472  @Get('ready')
5473  @HealthCheck()
5474  readiness(): Promise<HealthCheckResult> {
5475    // Return 503 during shutdown - k8s stops sending traffic
5476    if (this.shutdownService.isShutdown()) {
5477      throw new ServiceUnavailableException('Shutting down');
5478    }
5479 
5480    return this.health.check([
5481      () => this.db.pingCheck('database'),
5482    ]);
5483  }
5484}
5485 
5486// Integrate with shutdown
5487@Injectable()
5488export class AppShutdownService implements OnApplicationShutdown {
5489  constructor(private shutdownService: ShutdownService) {}
5490 
5491  async onApplicationShutdown(): Promise<void> {
5492    // Mark as unhealthy first
5493    this.shutdownService.startShutdown();
5494 
5495    // Wait for k8s to update endpoints
5496    await this.sleep(5000);
5497 
5498    // Then proceed with cleanup
5499  }
5500}
5501 
5502// Request tracking for in-flight requests
5503@Injectable()
5504export class RequestTracker implements NestMiddleware, OnApplicationShutdown {
5505  private activeRequests = 0;
5506  private isShuttingDown = false;
5507  private shutdownPromise: Promise<void> | null = null;
5508  private resolveShutdown: (() => void) | null = null;
5509 
5510  use(req: Request, res: Response, next: NextFunction): void {
5511    if (this.isShuttingDown) {
5512      res.status(503).send('Service Unavailable');
5513      return;
5514    }
5515 
5516    this.activeRequests++;
5517 
5518    res.on('finish', () => {
5519      this.activeRequests--;
5520      if (this.isShuttingDown && this.activeRequests === 0 && this.resolveShutdown) {
5521        this.resolveShutdown();
5522      }
5523    });
5524 
5525    next();
5526  }
5527 
5528  async onApplicationShutdown(): Promise<void> {
5529    this.isShuttingDown = true;
5530 
5531    if (this.activeRequests > 0) {
5532      console.log(`Waiting for ${this.activeRequests} requests to complete`);
5533      this.shutdownPromise = new Promise((resolve) => {
5534        this.resolveShutdown = resolve;
5535      });
5536 
5537      // Wait with timeout
5538      await Promise.race([
5539        this.shutdownPromise,
5540        new Promise((resolve) => setTimeout(resolve, 30000)),
5541      ]);
5542    }
5543 
5544    console.log('All requests completed');
5545  }
5546}
5547```
5548 
5549Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)
5550 
5551---
5552 
5553### 10.2 Use ConfigModule for Environment Configuration
5554 
5555**Impact: LOW-MEDIUM** — Proper configuration prevents deployment failures
5556 
5557Use `@nestjs/config` for environment-based configuration. Validate configuration at startup to fail fast on misconfigurations. Use namespaced configuration for organization and type safety.
5558 
5559**Incorrect (accessing process.env directly):**
5560 
5561```typescript
5562// Access process.env directly
5563@Injectable()
5564export class DatabaseService {
5565  constructor() {
5566    // No validation, can fail at runtime
5567    this.connection = new Pool({
5568      host: process.env.DB_HOST,
5569      port: parseInt(process.env.DB_PORT), // NaN if missing
5570      password: process.env.DB_PASSWORD, // undefined if missing
5571    });
5572  }
5573}
5574 
5575// Scattered env access
5576@Injectable()
5577export class EmailService {
5578  sendEmail() {
5579    // Different services access env differently
5580    const apiKey = process.env.SENDGRID_API_KEY || 'default';
5581    // Typos go unnoticed: process.env.SENDGRID_API_KY
5582  }
5583}
5584```
5585 
5586**Correct (use @nestjs/config with validation):**
5587 
5588```typescript
5589// Setup validated configuration
5590import { ConfigModule, ConfigService, registerAs } from '@nestjs/config';
5591import * as Joi from 'joi';
5592 
5593// config/database.config.ts
5594export const databaseConfig = registerAs('database', () => ({
5595  host: process.env.DB_HOST,
5596  port: parseInt(process.env.DB_PORT, 10),
5597  username: process.env.DB_USERNAME,
5598  password: process.env.DB_PASSWORD,
5599  database: process.env.DB_NAME,
5600}));
5601 
5602// config/app.config.ts
5603export const appConfig = registerAs('app', () => ({
5604  port: parseInt(process.env.PORT, 10) || 3000,
5605  environment: process.env.NODE_ENV || 'development',
5606  apiPrefix: process.env.API_PREFIX || 'api',
5607}));
5608 
5609// config/validation.schema.ts
5610export const validationSchema = Joi.object({
5611  NODE_ENV: Joi.string()
5612    .valid('development', 'production', 'test')
5613    .default('development'),
5614  PORT: Joi.number().default(3000),
5615  DB_HOST: Joi.string().required(),
5616  DB_PORT: Joi.number().default(5432),
5617  DB_USERNAME: Joi.string().required(),
5618  DB_PASSWORD: Joi.string().required(),
5619  DB_NAME: Joi.string().required(),
5620  JWT_SECRET: Joi.string().min(32).required(),
5621  REDIS_URL: Joi.string().uri().required(),
5622});
5623 
5624// app.module.ts
5625@Module({
5626  imports: [
5627    ConfigModule.forRoot({
5628      isGlobal: true, // Available everywhere without importing
5629      load: [databaseConfig, appConfig],
5630      validationSchema,
5631      validationOptions: {
5632        abortEarly: true, // Stop on first error
5633        allowUnknown: true, // Allow other env vars
5634      },
5635    }),
5636    TypeOrmModule.forRootAsync({
5637      inject: [ConfigService],
5638      useFactory: (config: ConfigService) => ({
5639        type: 'postgres',
5640        host: config.get('database.host'),
5641        port: config.get('database.port'),
5642        username: config.get('database.username'),
5643        password: config.get('database.password'),
5644        database: config.get('database.database'),
5645        autoLoadEntities: true,
5646      }),
5647    }),
5648  ],
5649})
5650export class AppModule {}
5651 
5652// Type-safe configuration access
5653export interface AppConfig {
5654  port: number;
5655  environment: 'development' | 'production' | 'test';
5656  apiPrefix: string;
5657}
5658 
5659export interface DatabaseConfig {
5660  host: string;
5661  port: number;
5662  username: string;
5663  password: string;
5664  database: string;
5665}
5666 
5667// Type-safe access
5668@Injectable()
5669export class AppService {
5670  constructor(private config: ConfigService) {}
5671 
5672  getPort(): number {
5673    // Type-safe with generic
5674    return this.config.get<number>('app.port');
5675  }
5676 
5677  getDatabaseConfig(): DatabaseConfig {
5678    return this.config.get<DatabaseConfig>('database');
5679  }
5680}
5681 
5682// Inject namespaced config directly
5683@Injectable()
5684export class DatabaseService {
5685  constructor(
5686    @Inject(databaseConfig.KEY)
5687    private dbConfig: ConfigType<typeof databaseConfig>,
5688  ) {
5689    // Full type inference!
5690    const host = this.dbConfig.host; // string
5691    const port = this.dbConfig.port; // number
5692  }
5693}
5694 
5695// Environment files support
5696ConfigModule.forRoot({
5697  envFilePath: [
5698    `.env.${process.env.NODE_ENV}.local`,
5699    `.env.${process.env.NODE_ENV}`,
5700    '.env.local',
5701    '.env',
5702  ],
5703});
5704 
5705// .env.development
5706// DB_HOST=localhost
5707// DB_PORT=5432
5708 
5709// .env.production
5710// DB_HOST=prod-db.example.com
5711// DB_PORT=5432
5712```
5713 
5714Reference: [NestJS Configuration](https://docs.nestjs.com/techniques/configuration)
5715 
5716---
5717 
5718### 10.3 Use Structured Logging
5719 
5720**Impact: MEDIUM-HIGH** — Structured logging enables effective debugging and monitoring
5721 
5722Use NestJS Logger with structured JSON output in production. Include contextual information (request ID, user ID, operation) to trace requests across services. Avoid console.log and implement proper log levels.
5723 
5724**Incorrect (using console.log in production):**
5725 
5726```typescript
5727// Use console.log in production
5728@Injectable()
5729export class UsersService {
5730  async createUser(dto: CreateUserDto): Promise<User> {
5731    console.log('Creating user:', dto);
5732    // Not structured, no levels, lost in production logs
5733 
5734    try {
5735      const user = await this.repo.save(dto);
5736      console.log('User created:', user.id);
5737      return user;
5738    } catch (error) {
5739      console.log('Error:', error); // Using log for errors
5740      throw error;
5741    }
5742  }
5743}
5744 
5745// Log sensitive data
5746console.log('Login attempt:', { email, password }); // SECURITY RISK!
5747 
5748// Inconsistent log format
5749logger.log('User ' + userId + ' created at ' + new Date());
5750// Hard to parse, no structure
5751```
5752 
5753**Correct (use structured logging with context):**
5754 
5755```typescript
5756// Configure logger in main.ts
5757async function bootstrap() {
5758  const app = await NestFactory.create(AppModule, {
5759    logger:
5760      process.env.NODE_ENV === 'production'
5761        ? ['error', 'warn', 'log']
5762        : ['error', 'warn', 'log', 'debug', 'verbose'],
5763  });
5764}
5765 
5766// Use NestJS Logger with context
5767@Injectable()
5768export class UsersService {
5769  private readonly logger = new Logger(UsersService.name);
5770 
5771  async createUser(dto: CreateUserDto): Promise<User> {
5772    this.logger.log('Creating user', { email: dto.email });
5773 
5774    try {
5775      const user = await this.repo.save(dto);
5776      this.logger.log('User created', { userId: user.id });
5777      return user;
5778    } catch (error) {
5779      this.logger.error('Failed to create user', error.stack, {
5780        email: dto.email,
5781      });
5782      throw error;
5783    }
5784  }
5785}
5786 
5787// Custom logger for JSON output
5788@Injectable()
5789export class JsonLogger implements LoggerService {
5790  log(message: string, context?: object): void {
5791    console.log(
5792      JSON.stringify({
5793        level: 'info',
5794        timestamp: new Date().toISOString(),
5795        message,
5796        ...context,
5797      }),
5798    );
5799  }
5800 
5801  error(message: string, trace?: string, context?: object): void {
5802    console.error(
5803      JSON.stringify({
5804        level: 'error',
5805        timestamp: new Date().toISOString(),
5806        message,
5807        trace,
5808        ...context,
5809      }),
5810    );
5811  }
5812 
5813  warn(message: string, context?: object): void {
5814    console.warn(
5815      JSON.stringify({
5816        level: 'warn',
5817        timestamp: new Date().toISOString(),
5818        message,
5819        ...context,
5820      }),
5821    );
5822  }
5823 
5824  debug(message: string, context?: object): void {
5825    console.debug(
5826      JSON.stringify({
5827        level: 'debug',
5828        timestamp: new Date().toISOString(),
5829        message,
5830        ...context,
5831      }),
5832    );
5833  }
5834}
5835 
5836// Request context logging with ClsModule
5837import { ClsModule, ClsService } from 'nestjs-cls';
5838 
5839@Module({
5840  imports: [
5841    ClsModule.forRoot({
5842      global: true,
5843      middleware: {
5844        mount: true,
5845        generateId: true,
5846      },
5847    }),
5848  ],
5849})
5850export class AppModule {}
5851 
5852// Middleware to set request context
5853@Injectable()
5854export class RequestContextMiddleware implements NestMiddleware {
5855  constructor(private cls: ClsService) {}
5856 
5857  use(req: Request, res: Response, next: NextFunction): void {
5858    const requestId = req.headers['x-request-id'] || randomUUID();
5859    this.cls.set('requestId', requestId);
5860    this.cls.set('userId', req.user?.id);
5861 
5862    res.setHeader('x-request-id', requestId);
5863    next();
5864  }
5865}
5866 
5867// Logger that includes request context
5868@Injectable()
5869export class ContextLogger {
5870  constructor(private cls: ClsService) {}
5871 
5872  log(message: string, data?: object): void {
5873    console.log(
5874      JSON.stringify({
5875        level: 'info',
5876        timestamp: new Date().toISOString(),
5877        requestId: this.cls.get('requestId'),
5878        userId: this.cls.get('userId'),
5879        message,
5880        ...data,
5881      }),
5882    );
5883  }
5884 
5885  error(message: string, error: Error, data?: object): void {
5886    console.error(
5887      JSON.stringify({
5888        level: 'error',
5889        timestamp: new Date().toISOString(),
5890        requestId: this.cls.get('requestId'),
5891        userId: this.cls.get('userId'),
5892        message,
5893        error: error.message,
5894        stack: error.stack,
5895        ...data,
5896      }),
5897    );
5898  }
5899}
5900 
5901// Pino integration for high-performance logging
5902import { LoggerModule } from 'nestjs-pino';
5903 
5904@Module({
5905  imports: [
5906    LoggerModule.forRoot({
5907      pinoHttp: {
5908        level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
5909        transport:
5910          process.env.NODE_ENV !== 'production'
5911            ? { target: 'pino-pretty' }
5912            : undefined,
5913        redact: ['req.headers.authorization', 'req.body.password'],
5914        serializers: {
5915          req: (req) => ({
5916            method: req.method,
5917            url: req.url,
5918            query: req.query,
5919          }),
5920          res: (res) => ({
5921            statusCode: res.statusCode,
5922          }),
5923        },
5924      },
5925    }),
5926  ],
5927})
5928export class AppModule {}
5929 
5930// Usage with Pino
5931@Injectable()
5932export class UsersService {
5933  constructor(private logger: PinoLogger) {
5934    this.logger.setContext(UsersService.name);
5935  }
5936 
5937  async findOne(id: string): Promise<User> {
5938    this.logger.info({ userId: id }, 'Finding user');
5939    // Pino uses first arg for data, second for message
5940  }
5941}
5942```
5943 
5944Reference: [NestJS Logger](https://docs.nestjs.com/techniques/logger)
5945 
5946---
5947 
5948## References
5949 
5950- https://docs.nestjs.com
5951- https://github.com/nestjs/nest
5952- https://typeorm.io
5953- https://github.com/typestack/class-validator
5954- https://github.com/goldbergyoni/nodebestpractices
5955 
5956---
5957 
5958*Generated by build-agents.ts on 2026-01-16*
5959