Nestjs Best Practices

NestJS 11 Best Practices

Quick Reference

Essential Patterns

Module with Providers

@Module({
  imports: [DatabaseModule],
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // Export for other modules
})
export class UsersModule {}

Controller with Validation

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }
}

DTO with Validation

import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  password: string;

  @IsOptional()
  @IsString()
  name?: string;
}

Exception Filter

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const status = exception.getStatus();

    response.status(status).json({
      statusCode: status,
      message: exception.message,
      timestamp: new Date().toISOString(),
    });
  }
}

Guard with JWT

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  canActivate(context: ExecutionContext) {
    return super.canActivate(context);
  }
}

NestJS 11 Breaking Changes

• Express v5: Wildcards must be named (e.g., *splat), optional params use braces /:file{.:ext}
• Node.js 20+: Minimum required version
• Fastify v5: Updated adapter for Fastify users
• Dynamic Modules: Same module with identical config imported multiple times = separate instances

Common Mistakes

1. Not using `forwardRef()` for circular deps - Causes "cannot resolve dependency" errors; wrap in forwardRef(() => ModuleName) 2. Throwing plain errors instead of HttpException - Loses status codes, breaks exception filters; use throw new BadRequestException('message') 3. Missing `@Injectable()` decorator - Provider won't be injectable; always decorate services 4. Global ValidationPipe without `whitelist: true` - Allows unexpected properties; set whitelist: true, forbidNonWhitelisted: true 5. Importing modules instead of exporting providers - Use exports array to share providers across modules 6. Async config without `ConfigModule.forRoot()` - ConfigService undefined; import ConfigModule in AppModule 7. Testing without `overrideProvider()` - Uses real services in unit tests; mock dependencies with overrideProvider(Service).useValue(mock) 8. E2E tests sharing database state - No isolation between tests; use transactions or truncate tables in beforeEach

Authentication & Authorization

Table of Contents

• Passport Integration
• Local Strategy
• JWT Strategy
• Refresh Tokens
• OAuth2 Strategies
• Guards and Decorators
• Role-Based Access Control

---

Passport Integration

Passport is the most popular Node.js authentication library, integrated via @nestjs/passport.

Installation

npm install @nestjs/passport passport passport-local passport-jwt
npm install -D @types/passport-local @types/passport-jwt
npm install @nestjs/jwt

Auth Module Setup

// auth/auth.module.ts
import { Module } from '@nestjs/common';
import { PassportModule } from '@nestjs/passport';
import { JwtModule } from '@nestjs/jwt';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { LocalStrategy } from './strategies/local.strategy';
import { JwtStrategy } from './strategies/jwt.strategy';
import { UsersModule } from '../users/users.module';

@Module({
  imports: [
    UsersModule,
    PassportModule.register({ defaultStrategy: 'jwt' }),
    JwtModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        secret: config.get('JWT_SECRET'),
        signOptions: { expiresIn: '15m' },
      }),
      inject: [ConfigService],
    }),
  ],
  providers: [AuthService, LocalStrategy, JwtStrategy],
  controllers: [AuthController],
  exports: [AuthService],
})
export class AuthModule {}

---

Local Strategy

Username/password authentication for login endpoints.

Strategy Implementation

// auth/strategies/local.strategy.ts
import { Strategy } from 'passport-local';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { AuthService } from '../auth.service';

@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(private authService: AuthService) {
    super({
      usernameField: 'email',  // Use email instead of username
      passwordField: 'password',
    });
  }

  async validate(email: string, password: string): Promise<any> {
    const user = await this.authService.validateUser(email, password);

    if (!user) {
      throw new UnauthorizedException('Invalid credentials');
    }

    return user;  // Attached to request.user
  }
}

Auth Service

// auth/auth.service.ts
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { UsersService } from '../users/users.service';
import * as bcrypt from 'bcrypt';

@Injectable()
export class AuthService {
  constructor(
    private usersService: UsersService,
    private jwtService: JwtService,
  ) {}

  async validateUser(email: string, password: string): Promise<any> {
    const user = await this.usersService.findByEmail(email);

    if (user && (await bcrypt.compare(password, user.password))) {
      const { password, ...result } = user;
      return result;
    }

    return null;
  }

  async login(user: any) {
    const payload = { email: user.email, sub: user.id, role: user.role };

    return {
      accessToken: this.jwtService.sign(payload),
      user: {
        id: user.id,
        email: user.email,
        role: user.role,
      },
    };
  }

  async register(createUserDto: CreateUserDto) {
    const hashedPassword = await bcrypt.hash(createUserDto.password, 10);

    const user = await this.usersService.create({
      ...createUserDto,
      password: hashedPassword,
    });

    return this.login(user);
  }
}

Local Auth Guard

// auth/guards/local-auth.guard.ts
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class LocalAuthGuard extends AuthGuard('local') {}

Login Endpoint

// auth/auth.controller.ts
@Controller('auth')
export class AuthController {
  constructor(private authService: AuthService) {}

  @Post('login')
  @UseGuards(LocalAuthGuard)
  @HttpCode(HttpStatus.OK)
  async login(@Request() req) {
    return this.authService.login(req.user);
  }

  @Post('register')
  async register(@Body() createUserDto: CreateUserDto) {
    return this.authService.register(createUserDto);
  }
}

---

JWT Strategy

Stateless authentication using JSON Web Tokens.

Strategy Implementation

// auth/strategies/jwt.strategy.ts
import { ExtractJwt, Strategy } from 'passport-jwt';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { UsersService } from '../../users/users.service';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(
    private configService: ConfigService,
    private usersService: UsersService,
  ) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get('JWT_SECRET'),
    });
  }

  async validate(payload: any) {
    // Optionally verify user still exists/is active
    const user = await this.usersService.findById(payload.sub);

    if (!user || !user.isActive) {
      throw new UnauthorizedException('User not found or inactive');
    }

    // Return value is attached to request.user
    return {
      id: payload.sub,
      email: payload.email,
      role: payload.role,
    };
  }
}

JWT Auth Guard

// auth/guards/jwt-auth.guard.ts
import {
  Injectable,
  ExecutionContext,
  UnauthorizedException,
} from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { Reflector } from '@nestjs/core';
import { IS_PUBLIC_KEY } from '../decorators/public.decorator';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(private reflector: Reflector) {
    super();
  }

  canActivate(context: ExecutionContext) {
    // Check for @Public() decorator
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (isPublic) {
      return true;
    }

    return super.canActivate(context);
  }

  handleRequest(err: any, user: any, info: any) {
    if (err || !user) {
      throw err || new UnauthorizedException('Invalid or expired token');
    }
    return user;
  }
}

Public Decorator

// auth/decorators/public.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

Global JWT Protection

// app.module.ts
@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: JwtAuthGuard,
    },
  ],
})
export class AppModule {}

// Usage - all routes protected by default
@Controller('users')
export class UsersController {
  @Get()
  findAll() {} // Protected

  @Get('public')
  @Public()  // Not protected
  findPublic() {}
}

---

Refresh Tokens

Implement token refresh for better security.

Service Methods

// auth/auth.service.ts
@Injectable()
export class AuthService {
  constructor(
    private jwtService: JwtService,
    private configService: ConfigService,
    private usersService: UsersService,
  ) {}

  async login(user: any) {
    const tokens = await this.generateTokens(user);
    await this.updateRefreshToken(user.id, tokens.refreshToken);

    return {
      ...tokens,
      user: { id: user.id, email: user.email },
    };
  }

  async generateTokens(user: any) {
    const payload = { email: user.email, sub: user.id, role: user.role };

    const [accessToken, refreshToken] = await Promise.all([
      this.jwtService.signAsync(payload, {
        secret: this.configService.get('JWT_ACCESS_SECRET'),
        expiresIn: '15m',
      }),
      this.jwtService.signAsync(payload, {
        secret: this.configService.get('JWT_REFRESH_SECRET'),
        expiresIn: '7d',
      }),
    ]);

    return { accessToken, refreshToken };
  }

  async updateRefreshToken(userId: number, refreshToken: string) {
    const hashedRefreshToken = await bcrypt.hash(refreshToken, 10);
    await this.usersService.update(userId, {
      refreshToken: hashedRefreshToken,
    });
  }

  async refreshTokens(userId: number, refreshToken: string) {
    const user = await this.usersService.findById(userId);

    if (!user || !user.refreshToken) {
      throw new ForbiddenException('Access denied');
    }

    const refreshTokenMatches = await bcrypt.compare(
      refreshToken,
      user.refreshToken,
    );

    if (!refreshTokenMatches) {
      throw new ForbiddenException('Access denied');
    }

    const tokens = await this.generateTokens(user);
    await this.updateRefreshToken(user.id, tokens.refreshToken);

    return tokens;
  }

  async logout(userId: number) {
    await this.usersService.update(userId, { refreshToken: null });
  }
}

Refresh Token Strategy

// auth/strategies/jwt-refresh.strategy.ts
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { Request } from 'express';
import { Injectable } from '@nestjs/common';

@Injectable()
export class JwtRefreshStrategy extends PassportStrategy(
  Strategy,
  'jwt-refresh',
) {
  constructor(private configService: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: configService.get('JWT_REFRESH_SECRET'),
      passReqToCallback: true,
    });
  }

  validate(req: Request, payload: any) {
    const refreshToken = req.get('Authorization').replace('Bearer', '').trim();

    return {
      ...payload,
      refreshToken,
    };
  }
}

// Guard
@Injectable()
export class JwtRefreshGuard extends AuthGuard('jwt-refresh') {}

Refresh Endpoint

@Controller('auth')
export class AuthController {
  @Post('refresh')
  @UseGuards(JwtRefreshGuard)
  refreshTokens(@Request() req) {
    const userId = req.user.sub;
    const refreshToken = req.user.refreshToken;
    return this.authService.refreshTokens(userId, refreshToken);
  }

  @Post('logout')
  @UseGuards(JwtAuthGuard)
  logout(@Request() req) {
    return this.authService.logout(req.user.id);
  }
}

---

OAuth2 Strategies

Google OAuth2

npm install passport-google-oauth20
npm install -D @types/passport-google-oauth20

// auth/strategies/google.strategy.ts
import { PassportStrategy } from '@nestjs/passport';
import { Strategy, VerifyCallback } from 'passport-google-oauth20';
import { Injectable } from '@nestjs/common';

@Injectable()
export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
  constructor(private configService: ConfigService) {
    super({
      clientID: configService.get('GOOGLE_CLIENT_ID'),
      clientSecret: configService.get('GOOGLE_CLIENT_SECRET'),
      callbackURL: configService.get('GOOGLE_CALLBACK_URL'),
      scope: ['email', 'profile'],
    });
  }

  async validate(
    accessToken: string,
    refreshToken: string,
    profile: any,
    done: VerifyCallback,
  ): Promise<any> {
    const { name, emails, photos } = profile;

    const user = {
      email: emails[0].value,
      firstName: name.givenName,
      lastName: name.familyName,
      picture: photos[0].value,
      accessToken,
    };

    done(null, user);
  }
}

// Guard
@Injectable()
export class GoogleOAuthGuard extends AuthGuard('google') {
  constructor() {
    super({
      accessType: 'offline',
      prompt: 'consent',
    });
  }
}

OAuth Controller

@Controller('auth')
export class AuthController {
  @Get('google')
  @UseGuards(GoogleOAuthGuard)
  async googleAuth() {}

  @Get('google/callback')
  @UseGuards(GoogleOAuthGuard)
  async googleAuthCallback(@Request() req, @Res() res: Response) {
    const tokens = await this.authService.loginWithOAuth(req.user);

    // Redirect to frontend with tokens
    res.redirect(
      `${this.configService.get('FRONTEND_URL')}/auth/callback?token=${tokens.accessToken}`,
    );
  }
}

GitHub OAuth2

// auth/strategies/github.strategy.ts
import { Strategy } from 'passport-github2';

@Injectable()
export class GithubStrategy extends PassportStrategy(Strategy, 'github') {
  constructor(private configService: ConfigService) {
    super({
      clientID: configService.get('GITHUB_CLIENT_ID'),
      clientSecret: configService.get('GITHUB_CLIENT_SECRET'),
      callbackURL: configService.get('GITHUB_CALLBACK_URL'),
      scope: ['user:email'],
    });
  }

  async validate(accessToken: string, refreshToken: string, profile: any) {
    const { username, emails, photos } = profile;

    return {
      email: emails[0].value,
      username,
      avatar: photos[0]?.value,
      accessToken,
    };
  }
}

---

Guards and Decorators

Current User Decorator

// auth/decorators/current-user.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const CurrentUser = createParamDecorator(
  (data: string | undefined, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;

    return data ? user?.[data] : user;
  },
);

// Usage
@Get('profile')
getProfile(@CurrentUser() user: User) {
  return user;
}

@Get('email')
getEmail(@CurrentUser('email') email: string) {
  return { email };
}

Auth Decorator (Combined)

// auth/decorators/auth.decorator.ts
import { applyDecorators, UseGuards } from '@nestjs/common';
import { ApiBearerAuth, ApiUnauthorizedResponse } from '@nestjs/swagger';

export function Auth(...roles: Role[]) {
  return applyDecorators(
    UseGuards(JwtAuthGuard, RolesGuard),
    Roles(...roles),
    ApiBearerAuth(),
    ApiUnauthorizedResponse({ description: 'Unauthorized' }),
  );
}

// Usage
@Get('admin')
@Auth(Role.Admin)
adminOnly(@CurrentUser() user: User) {
  return { message: 'Admin area', user };
}

Optional Auth Guard

// auth/guards/optional-auth.guard.ts
@Injectable()
export class OptionalAuthGuard extends AuthGuard('jwt') {
  handleRequest(err: any, user: any) {
    // Don't throw on missing/invalid token
    return user || null;
  }
}

// Usage - user may or may not be authenticated
@Get('posts')
@UseGuards(OptionalAuthGuard)
getPosts(@CurrentUser() user: User | null) {
  if (user) {
    return this.postsService.getPersonalized(user.id);
  }
  return this.postsService.getPublic();
}

---

Role-Based Access Control

Define Roles

// auth/enums/role.enum.ts
export enum Role {
  User = 'user',
  Admin = 'admin',
  SuperAdmin = 'superadmin',
}

Roles Decorator

// auth/decorators/roles.decorator.ts
import { SetMetadata } from '@nestjs/common';
import { Role } from '../enums/role.enum';

export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

Roles Guard

// auth/guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from '../decorators/roles.decorator';
import { Role } from '../enums/role.enum';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (!requiredRoles) {
      return true;
    }

    const { user } = context.switchToHttp().getRequest();

    return requiredRoles.some((role) => user.role === role);
  }
}

Permission-Based Access Control

// auth/enums/permission.enum.ts
export enum Permission {
  CreateUser = 'create:user',
  ReadUser = 'read:user',
  UpdateUser = 'update:user',
  DeleteUser = 'delete:user',
  ManageRoles = 'manage:roles',
}

// Role-Permission mapping
export const RolePermissions: Record<Role, Permission[]> = {
  [Role.User]: [Permission.ReadUser],
  [Role.Admin]: [
    Permission.CreateUser,
    Permission.ReadUser,
    Permission.UpdateUser,
  ],
  [Role.SuperAdmin]: Object.values(Permission),
};

Permissions Decorator and Guard

// auth/decorators/permissions.decorator.ts
export const PERMISSIONS_KEY = 'permissions';
export const Permissions = (...permissions: Permission[]) =>
  SetMetadata(PERMISSIONS_KEY, permissions);

// auth/guards/permissions.guard.ts
@Injectable()
export class PermissionsGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredPermissions = this.reflector.getAllAndOverride<Permission[]>(
      PERMISSIONS_KEY,
      [context.getHandler(), context.getClass()],
    );

    if (!requiredPermissions) {
      return true;
    }

    const { user } = context.switchToHttp().getRequest();
    const userPermissions = RolePermissions[user.role] || [];

    return requiredPermissions.every((permission) =>
      userPermissions.includes(permission),
    );
  }
}

// Usage
@Delete(':id')
@UseGuards(JwtAuthGuard, PermissionsGuard)
@Permissions(Permission.DeleteUser)
deleteUser(@Param('id') id: string) {
  return this.usersService.delete(id);
}

Resource Ownership Guard

// auth/guards/ownership.guard.ts
@Injectable()
export class OwnershipGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const user = request.user;
    const resourceId = request.params.id;

    // Admins bypass ownership check
    if (user.role === Role.Admin || user.role === Role.SuperAdmin) {
      return true;
    }

    // Get resource and check ownership
    // This is simplified - inject service via module
    const resource = request.resource; // Set by earlier middleware/interceptor

    return resource?.userId === user.id;
  }
}

// Usage with interceptor to load resource
@Get(':id')
@UseGuards(JwtAuthGuard, OwnershipGuard)
@UseInterceptors(LoadResourceInterceptor)
getPost(@Param('id') id: string) {
  return this.postsService.findOne(id);
}

Core Architecture

Table of Contents

• Module Organization
• Provider Types
• Dependency Injection Patterns
• Circular Dependencies
• Custom Decorators
• Dynamic Modules
• ConfigModule Patterns

---

Module Organization

Modules are the fundamental building blocks in NestJS. They organize related functionality and establish clear boundaries.

Feature Module Pattern

// users/users.module.ts
@Module({
  imports: [
    TypeOrmModule.forFeature([User]),
    CommonModule,
  ],
  controllers: [UsersController],
  providers: [UsersService, UsersRepository],
  exports: [UsersService], // Make available to other modules
})
export class UsersModule {}

Shared Module Pattern

For cross-cutting concerns used by multiple feature modules:

// common/common.module.ts
@Module({
  providers: [
    LoggerService,
    CacheService,
    { provide: 'DATE_SERVICE', useClass: DateService },
  ],
  exports: [
    LoggerService,
    CacheService,
    'DATE_SERVICE',
  ],
})
export class CommonModule {}

Core Module Pattern

For singleton services that should only be instantiated once:

// core/core.module.ts
@Global() // Makes exports available everywhere without importing
@Module({
  providers: [ConfigService, DatabaseService],
  exports: [ConfigService, DatabaseService],
})
export class CoreModule {
  constructor(@Optional() @SkipSelf() parentModule?: CoreModule) {
    if (parentModule) {
      throw new Error('CoreModule is already loaded. Import it only in AppModule.');
    }
  }
}

Module Re-exports

Re-export modules to simplify imports:

@Module({
  imports: [CommonModule, LoggingModule],
  exports: [CommonModule, LoggingModule], // Re-export for consumers
})
export class SharedModule {}

---

Provider Types

NestJS supports multiple ways to define providers for different use cases.

Standard Provider (useClass)

The most common pattern - a class decorated with @Injectable():

// Shorthand
@Module({
  providers: [UsersService],
})

// Equivalent to
@Module({
  providers: [
    {
      provide: UsersService,
      useClass: UsersService,
    },
  ],
})

Value Provider (useValue)

For injecting constant values, configuration objects, or mock objects:

@Module({
  providers: [
    {
      provide: 'API_KEY',
      useValue: process.env.API_KEY,
    },
    {
      provide: 'CONFIG',
      useValue: {
        apiUrl: 'https://api.example.com',
        timeout: 5000,
      },
    },
  ],
})
export class AppModule {}

// Injection
@Injectable()
export class ApiService {
  constructor(
    @Inject('API_KEY') private apiKey: string,
    @Inject('CONFIG') private config: { apiUrl: string; timeout: number },
  ) {}
}

Factory Provider (useFactory)

For dynamic provider creation with dependencies:

@Module({
  providers: [
    {
      provide: 'DATABASE_CONNECTION',
      useFactory: async (configService: ConfigService) => {
        const options = configService.get<DatabaseConfig>('database');
        return createConnection(options);
      },
      inject: [ConfigService], // Dependencies for factory
    },
  ],
})
export class DatabaseModule {}

Async Factory with Multiple Dependencies

@Module({
  providers: [
    {
      provide: 'CACHE_MANAGER',
      useFactory: async (
        configService: ConfigService,
        logger: LoggerService,
      ) => {
        const redisUrl = configService.get('REDIS_URL');
        logger.log(`Connecting to Redis: ${redisUrl}`);
        return new CacheManager({ url: redisUrl });
      },
      inject: [ConfigService, LoggerService],
    },
  ],
})
export class CacheModule {}

Existing Provider (useExisting)

Create an alias to an existing provider:

@Module({
  providers: [
    UsersService,
    {
      provide: 'UserServiceAlias',
      useExisting: UsersService, // Points to same instance
    },
  ],
})
export class UsersModule {}

---

Dependency Injection Patterns

Constructor Injection (Recommended)

@Injectable()
export class UsersService {
  constructor(
    private readonly usersRepository: UsersRepository,
    private readonly logger: LoggerService,
  ) {}
}

Property Injection

Use when constructor injection isn't possible (e.g., base classes):

@Injectable()
export class BaseService {
  @Inject(LoggerService)
  protected logger: LoggerService;
}

Token-Based Injection

For non-class tokens (strings, symbols):

// Define token
export const DATABASE_TOKEN = Symbol('DATABASE');

// Register provider
@Module({
  providers: [
    {
      provide: DATABASE_TOKEN,
      useFactory: () => new Database(),
    },
  ],
})

// Inject
@Injectable()
export class UsersService {
  constructor(
    @Inject(DATABASE_TOKEN) private db: Database,
  ) {}
}

Optional Dependencies

@Injectable()
export class NotificationService {
  constructor(
    @Optional() @Inject('SLACK_CLIENT') private slack?: SlackClient,
  ) {}

  notify(message: string) {
    if (this.slack) {
      this.slack.send(message);
    }
  }
}

Scope-Based Injection

// Request-scoped provider
@Injectable({ scope: Scope.REQUEST })
export class RequestContextService {
  constructor(@Inject(REQUEST) private request: Request) {}

  getUserId() {
    return this.request.user?.id;
  }
}

// Transient provider (new instance each injection)
@Injectable({ scope: Scope.TRANSIENT })
export class HelperService {}

---

Circular Dependencies

Circular dependencies occur when Module A imports Module B, and Module B imports Module A.

Symptoms

• Error: Nest cannot create the <Module> instance
• Potential causes: A circular dependency
• Cannot read properties of undefined

Solution 1: forwardRef()

Wrap the circular reference in forwardRef():

// users/users.module.ts
@Module({
  imports: [forwardRef(() => PostsModule)],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

// posts/posts.module.ts
@Module({
  imports: [forwardRef(() => UsersModule)],
  providers: [PostsService],
  exports: [PostsService],
})
export class PostsModule {}

For service-level circular dependencies:

@Injectable()
export class UsersService {
  constructor(
    @Inject(forwardRef(() => PostsService))
    private postsService: PostsService,
  ) {}
}

Solution 2: Extract Shared Module

Better long-term solution - extract shared functionality:

// BEFORE: Circular dependency
// UsersModule <-> PostsModule

// AFTER: Extract shared logic
@Module({
  providers: [UserPostLinkService],
  exports: [UserPostLinkService],
})
export class SharedModule {}

@Module({
  imports: [SharedModule],
  providers: [UsersService],
})
export class UsersModule {}

@Module({
  imports: [SharedModule],
  providers: [PostsService],
})
export class PostsModule {}

Solution 3: Event-Based Decoupling

Use EventEmitter2 to decouple modules:

// Install: npm install @nestjs/event-emitter

// users.service.ts
@Injectable()
export class UsersService {
  constructor(private eventEmitter: EventEmitter2) {}

  async deleteUser(id: number) {
    await this.usersRepository.delete(id);
    this.eventEmitter.emit('user.deleted', { userId: id });
  }
}

// posts.service.ts
@Injectable()
export class PostsService {
  @OnEvent('user.deleted')
  handleUserDeleted(payload: { userId: number }) {
    this.postsRepository.deleteByUserId(payload.userId);
  }
}

---

Custom Decorators

Parameter Decorators

Extract data from the request:

// decorators/user.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const CurrentUser = createParamDecorator(
  (data: keyof User | undefined, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;

    return data ? user?.[data] : user;
  },
);

// Usage
@Get('profile')
getProfile(@CurrentUser() user: User) {
  return user;
}

@Get('email')
getEmail(@CurrentUser('email') email: string) {
  return { email };
}

Combining Decorators

Create a single decorator that applies multiple decorators:

import { applyDecorators, UseGuards, SetMetadata } from '@nestjs/common';
import { ApiBearerAuth, ApiUnauthorizedResponse } from '@nestjs/swagger';

export function Auth(...roles: Role[]) {
  return applyDecorators(
    SetMetadata('roles', roles),
    UseGuards(JwtAuthGuard, RolesGuard),
    ApiBearerAuth(),
    ApiUnauthorizedResponse({ description: 'Unauthorized' }),
  );
}

// Usage
@Post()
@Auth(Role.Admin)
create(@Body() dto: CreateUserDto) {}

Class Decorators with Metadata

import { SetMetadata } from '@nestjs/common';

export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

// Usage
@Controller('admin')
@Roles('admin', 'superadmin')
export class AdminController {}

// Access metadata in guard
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>('roles', context.getHandler());
    if (!roles) return true;

    const request = context.switchToHttp().getRequest();
    return roles.includes(request.user?.role);
  }
}

---

Dynamic Modules

Dynamic modules allow configurable module behavior.

forRoot Pattern (Singleton Config)

// database/database.module.ts
@Module({})
export class DatabaseModule {
  static forRoot(options: DatabaseOptions): DynamicModule {
    return {
      module: DatabaseModule,
      global: true, // Optional: make globally available
      providers: [
        {
          provide: 'DATABASE_OPTIONS',
          useValue: options,
        },
        {
          provide: 'DATABASE_CONNECTION',
          useFactory: async (opts: DatabaseOptions) => {
            return createConnection(opts);
          },
          inject: ['DATABASE_OPTIONS'],
        },
      ],
      exports: ['DATABASE_CONNECTION'],
    };
  }
}

// app.module.ts
@Module({
  imports: [
    DatabaseModule.forRoot({
      host: 'localhost',
      port: 5432,
      database: 'myapp',
    }),
  ],
})
export class AppModule {}

forRootAsync Pattern (Async Config)

@Module({})
export class DatabaseModule {
  static forRootAsync(options: DatabaseAsyncOptions): DynamicModule {
    return {
      module: DatabaseModule,
      imports: options.imports || [],
      providers: [
        {
          provide: 'DATABASE_OPTIONS',
          useFactory: options.useFactory,
          inject: options.inject || [],
        },
        {
          provide: 'DATABASE_CONNECTION',
          useFactory: async (opts: DatabaseOptions) => createConnection(opts),
          inject: ['DATABASE_OPTIONS'],
        },
      ],
      exports: ['DATABASE_CONNECTION'],
    };
  }
}

// Usage with ConfigService
@Module({
  imports: [
    DatabaseModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        host: config.get('DB_HOST'),
        port: config.get('DB_PORT'),
        database: config.get('DB_NAME'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

forFeature Pattern (Per-Module Config)

@Module({})
export class TypeOrmModule {
  static forFeature(entities: EntityClassOrSchema[]): DynamicModule {
    const providers = entities.map((entity) => ({
      provide: getRepositoryToken(entity),
      useFactory: (dataSource: DataSource) => dataSource.getRepository(entity),
      inject: [DataSource],
    }));

    return {
      module: TypeOrmModule,
      providers,
      exports: providers,
    };
  }
}

// Usage in feature module
@Module({
  imports: [TypeOrmModule.forFeature([User, Profile])],
  providers: [UsersService],
})
export class UsersModule {}

---

ConfigModule Patterns

Basic Setup

// app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // No need to import in every module
      envFilePath: ['.env.local', '.env'],
      cache: true, // Cache env vars for performance
    }),
  ],
})
export class AppModule {}

With Validation

import * as Joi from 'joi';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: Joi.object({
        NODE_ENV: Joi.string()
          .valid('development', 'production', 'test')
          .default('development'),
        PORT: Joi.number().default(3000),
        DATABASE_URL: Joi.string().required(),
        JWT_SECRET: Joi.string().required().min(32),
      }),
      validationOptions: {
        abortEarly: false, // Show all validation errors
      },
    }),
  ],
})
export class AppModule {}

Custom Configuration Files

// config/database.config.ts
import { registerAs } from '@nestjs/config';

export default registerAs('database', () => ({
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT, 10) || 5432,
  name: process.env.DB_NAME,
  username: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
}));

// app.module.ts
import databaseConfig from './config/database.config';

@Module({
  imports: [
    ConfigModule.forRoot({
      load: [databaseConfig],
    }),
  ],
})
export class AppModule {}

// Usage
@Injectable()
export class DatabaseService {
  constructor(private configService: ConfigService) {
    const dbHost = this.configService.get<string>('database.host');
    // Or get entire namespace
    const dbConfig = this.configService.get('database');
  }
}

Type-Safe Configuration

// config/configuration.ts
export interface AppConfig {
  port: number;
  database: {
    host: string;
    port: number;
  };
}

export default (): AppConfig => ({
  port: parseInt(process.env.PORT, 10) || 3000,
  database: {
    host: process.env.DB_HOST || 'localhost',
    port: parseInt(process.env.DB_PORT, 10) || 5432,
  },
});

// Usage with type safety
const port = this.configService.get<number>('port');
const dbConfig = this.configService.get<AppConfig['database']>('database');

Database Integration

Table of Contents

• TypeORM
• Prisma
• Drizzle ORM
• Common Patterns

---

TypeORM

TypeORM is the most established ORM in the NestJS ecosystem with first-party support.

Installation

npm install @nestjs/typeorm typeorm pg # PostgreSQL
# or
npm install @nestjs/typeorm typeorm mysql2 # MySQL

Module Setup

// app.module.ts
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        host: config.get('DB_HOST'),
        port: config.get('DB_PORT'),
        username: config.get('DB_USER'),
        password: config.get('DB_PASSWORD'),
        database: config.get('DB_NAME'),
        entities: [__dirname + '/**/*.entity{.ts,.js}'],
        synchronize: config.get('NODE_ENV') === 'development', // Never in production
        logging: config.get('NODE_ENV') === 'development',
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Entity Definition

// users/entities/user.entity.ts
import {
  Entity,
  PrimaryGeneratedColumn,
  Column,
  CreateDateColumn,
  UpdateDateColumn,
  OneToMany,
  ManyToOne,
  Index,
} from 'typeorm';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ unique: true })
  @Index()
  email: string;

  @Column()
  password: string;

  @Column({ nullable: true })
  name: string;

  @Column({ type: 'enum', enum: ['user', 'admin'], default: 'user' })
  role: string;

  @Column({ default: true })
  isActive: boolean;

  @OneToMany(() => Post, (post) => post.author)
  posts: Post[];

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

Relations

// posts/entities/post.entity.ts
@Entity('posts')
export class Post {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  title: string;

  @Column('text')
  content: string;

  @ManyToOne(() => User, (user) => user.posts, { onDelete: 'CASCADE' })
  author: User;

  @Column()
  authorId: string;

  @ManyToMany(() => Tag)
  @JoinTable({
    name: 'posts_tags',
    joinColumn: { name: 'postId', referencedColumnName: 'id' },
    inverseJoinColumn: { name: 'tagId', referencedColumnName: 'id' },
  })
  tags: Tag[];
}

Repository Pattern

// users/users.module.ts
@Module({
  imports: [TypeOrmModule.forFeature([User])],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

// users/users.service.ts
@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private usersRepository: Repository<User>,
  ) {}

  async findAll(): Promise<User[]> {
    return this.usersRepository.find({
      relations: ['posts'],
      order: { createdAt: 'DESC' },
    });
  }

  async findOne(id: string): Promise<User> {
    const user = await this.usersRepository.findOne({
      where: { id },
      relations: ['posts'],
    });

    if (!user) {
      throw new NotFoundException(`User #${id} not found`);
    }

    return user;
  }

  async create(createUserDto: CreateUserDto): Promise<User> {
    const user = this.usersRepository.create(createUserDto);
    return this.usersRepository.save(user);
  }

  async update(id: string, updateUserDto: UpdateUserDto): Promise<User> {
    await this.usersRepository.update(id, updateUserDto);
    return this.findOne(id);
  }

  async remove(id: string): Promise<void> {
    const result = await this.usersRepository.delete(id);
    if (result.affected === 0) {
      throw new NotFoundException(`User #${id} not found`);
    }
  }
}

Query Builder

async findByFilters(filters: FilterDto): Promise<User[]> {
  const query = this.usersRepository
    .createQueryBuilder('user')
    .leftJoinAndSelect('user.posts', 'posts');

  if (filters.role) {
    query.andWhere('user.role = :role', { role: filters.role });
  }

  if (filters.search) {
    query.andWhere(
      '(user.email ILIKE :search OR user.name ILIKE :search)',
      { search: `%${filters.search}%` },
    );
  }

  if (filters.isActive !== undefined) {
    query.andWhere('user.isActive = :isActive', { isActive: filters.isActive });
  }

  return query
    .orderBy('user.createdAt', 'DESC')
    .skip((filters.page - 1) * filters.limit)
    .take(filters.limit)
    .getMany();
}

Transactions

@Injectable()
export class UsersService {
  constructor(private dataSource: DataSource) {}

  async createWithProfile(createUserDto: CreateUserDto): Promise<User> {
    const queryRunner = this.dataSource.createQueryRunner();
    await queryRunner.connect();
    await queryRunner.startTransaction();

    try {
      const user = queryRunner.manager.create(User, createUserDto);
      await queryRunner.manager.save(user);

      const profile = queryRunner.manager.create(Profile, {
        userId: user.id,
        bio: '',
      });
      await queryRunner.manager.save(profile);

      await queryRunner.commitTransaction();
      return user;
    } catch (error) {
      await queryRunner.rollbackTransaction();
      throw error;
    } finally {
      await queryRunner.release();
    }
  }
}

---

Prisma

Prisma provides type-safe database access with excellent TypeScript integration.

Installation

npm install @prisma/client
npm install -D prisma
npx prisma init

Schema Definition

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(uuid())
  email     String   @unique
  password  String
  name      String?
  role      Role     @default(USER)
  isActive  Boolean  @default(true)
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([email])
  @@map("users")
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
  authorId  String
  tags      Tag[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("posts")
}

model Tag {
  id    Int    @id @default(autoincrement())
  name  String @unique
  posts Post[]

  @@map("tags")
}

enum Role {
  USER
  ADMIN
}

Prisma Service

// prisma/prisma.service.ts
import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService
  extends PrismaClient
  implements OnModuleInit, OnModuleDestroy
{
  constructor() {
    super({
      log:
        process.env.NODE_ENV === 'development'
          ? ['query', 'info', 'warn', 'error']
          : ['error'],
    });
  }

  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }

  // Helper for transactions
  async cleanDatabase() {
    if (process.env.NODE_ENV === 'production') {
      throw new Error('cleanDatabase not allowed in production');
    }
    // Delete in correct order to respect foreign keys
    await this.post.deleteMany();
    await this.user.deleteMany();
  }
}

Prisma Module

// prisma/prisma.module.ts
import { Global, Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class PrismaModule {}

Service with Prisma

// users/users.service.ts
@Injectable()
export class UsersService {
  constructor(private prisma: PrismaService) {}

  async findAll(): Promise<User[]> {
    return this.prisma.user.findMany({
      include: { posts: true },
      orderBy: { createdAt: 'desc' },
    });
  }

  async findOne(id: string): Promise<User> {
    const user = await this.prisma.user.findUnique({
      where: { id },
      include: { posts: true },
    });

    if (!user) {
      throw new NotFoundException(`User #${id} not found`);
    }

    return user;
  }

  async create(data: CreateUserDto): Promise<User> {
    return this.prisma.user.create({
      data,
      include: { posts: true },
    });
  }

  async update(id: string, data: UpdateUserDto): Promise<User> {
    try {
      return await this.prisma.user.update({
        where: { id },
        data,
        include: { posts: true },
      });
    } catch (error) {
      if (error.code === 'P2025') {
        throw new NotFoundException(`User #${id} not found`);
      }
      throw error;
    }
  }

  async remove(id: string): Promise<void> {
    try {
      await this.prisma.user.delete({ where: { id } });
    } catch (error) {
      if (error.code === 'P2025') {
        throw new NotFoundException(`User #${id} not found`);
      }
      throw error;
    }
  }
}

Prisma Transactions

async createWithProfile(data: CreateUserDto): Promise<User> {
  return this.prisma.$transaction(async (tx) => {
    const user = await tx.user.create({
      data: {
        email: data.email,
        password: data.password,
        name: data.name,
      },
    });

    await tx.profile.create({
      data: {
        userId: user.id,
        bio: '',
      },
    });

    return user;
  });
}

// Interactive transaction with timeout
async transferCredits(fromId: string, toId: string, amount: number) {
  return this.prisma.$transaction(
    async (tx) => {
      const sender = await tx.user.update({
        where: { id: fromId },
        data: { credits: { decrement: amount } },
      });

      if (sender.credits < 0) {
        throw new BadRequestException('Insufficient credits');
      }

      await tx.user.update({
        where: { id: toId },
        data: { credits: { increment: amount } },
      });

      return { success: true };
    },
    {
      maxWait: 5000,
      timeout: 10000,
      isolationLevel: 'Serializable',
    },
  );
}

Prisma Filters and Pagination

async findByFilters(filters: FilterDto) {
  const where: Prisma.UserWhereInput = {};

  if (filters.role) {
    where.role = filters.role;
  }

  if (filters.search) {
    where.OR = [
      { email: { contains: filters.search, mode: 'insensitive' } },
      { name: { contains: filters.search, mode: 'insensitive' } },
    ];
  }

  if (filters.isActive !== undefined) {
    where.isActive = filters.isActive;
  }

  const [users, total] = await Promise.all([
    this.prisma.user.findMany({
      where,
      skip: (filters.page - 1) * filters.limit,
      take: filters.limit,
      orderBy: { createdAt: 'desc' },
      include: { posts: { take: 5 } },
    }),
    this.prisma.user.count({ where }),
  ]);

  return {
    data: users,
    meta: {
      total,
      page: filters.page,
      limit: filters.limit,
      totalPages: Math.ceil(total / filters.limit),
    },
  };
}

---

Drizzle ORM

Drizzle is a lightweight, type-safe ORM with SQL-like syntax.

Installation

npm install drizzle-orm pg
npm install -D drizzle-kit @types/pg

Schema Definition

// src/database/schema.ts
import {
  pgTable,
  serial,
  text,
  varchar,
  timestamp,
  boolean,
  integer,
  uuid,
  pgEnum,
} from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

export const roleEnum = pgEnum('role', ['user', 'admin']);

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: varchar('email', { length: 255 }).notNull().unique(),
  password: text('password').notNull(),
  name: varchar('name', { length: 100 }),
  role: roleEnum('role').default('user'),
  isActive: boolean('is_active').default(true),
  createdAt: timestamp('created_at').defaultNow(),
  updatedAt: timestamp('updated_at').defaultNow(),
});

export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  title: varchar('title', { length: 255 }).notNull(),
  content: text('content'),
  published: boolean('published').default(false),
  authorId: uuid('author_id')
    .notNull()
    .references(() => users.id, { onDelete: 'cascade' }),
  createdAt: timestamp('created_at').defaultNow(),
  updatedAt: timestamp('updated_at').defaultNow(),
});

export const tags = pgTable('tags', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 50 }).notNull().unique(),
});

export const postsTags = pgTable('posts_tags', {
  postId: integer('post_id')
    .notNull()
    .references(() => posts.id, { onDelete: 'cascade' }),
  tagId: integer('tag_id')
    .notNull()
    .references(() => tags.id, { onDelete: 'cascade' }),
});

// Relations
export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts),
}));

export const postsRelations = relations(posts, ({ one, many }) => ({
  author: one(users, {
    fields: [posts.authorId],
    references: [users.id],
  }),
  tags: many(postsTags),
}));

Drizzle Configuration

// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/database/schema.ts',
  out: './drizzle/migrations',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

Drizzle Module

// src/database/drizzle.module.ts
import { Module, Global } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { Pool } from 'pg';
import { drizzle, NodePgDatabase } from 'drizzle-orm/node-postgres';
import * as schema from './schema';

export const DRIZZLE = Symbol('drizzle-connection');

@Global()
@Module({
  providers: [
    {
      provide: DRIZZLE,
      inject: [ConfigService],
      useFactory: async (configService: ConfigService) => {
        const pool = new Pool({
          connectionString: configService.get<string>('DATABASE_URL'),
        });
        return drizzle(pool, { schema }) as NodePgDatabase<typeof schema>;
      },
    },
  ],
  exports: [DRIZZLE],
})
export class DrizzleModule {}

Service with Drizzle

// users/users.service.ts
import { Inject, Injectable, NotFoundException } from '@nestjs/common';
import { NodePgDatabase } from 'drizzle-orm/node-postgres';
import { eq, ilike, and, or, desc } from 'drizzle-orm';
import { DRIZZLE } from '../database/drizzle.module';
import * as schema from '../database/schema';

@Injectable()
export class UsersService {
  constructor(
    @Inject(DRIZZLE) private db: NodePgDatabase<typeof schema>,
  ) {}

  async findAll() {
    return this.db.query.users.findMany({
      with: { posts: true },
      orderBy: [desc(schema.users.createdAt)],
    });
  }

  async findOne(id: string) {
    const user = await this.db.query.users.findFirst({
      where: eq(schema.users.id, id),
      with: { posts: true },
    });

    if (!user) {
      throw new NotFoundException(`User #${id} not found`);
    }

    return user;
  }

  async create(createUserDto: CreateUserDto) {
    const [user] = await this.db
      .insert(schema.users)
      .values(createUserDto)
      .returning();

    return user;
  }

  async update(id: string, updateUserDto: UpdateUserDto) {
    const [user] = await this.db
      .update(schema.users)
      .set({ ...updateUserDto, updatedAt: new Date() })
      .where(eq(schema.users.id, id))
      .returning();

    if (!user) {
      throw new NotFoundException(`User #${id} not found`);
    }

    return user;
  }

  async remove(id: string) {
    const [deleted] = await this.db
      .delete(schema.users)
      .where(eq(schema.users.id, id))
      .returning({ id: schema.users.id });

    if (!deleted) {
      throw new NotFoundException(`User #${id} not found`);
    }
  }
}

Drizzle Filters and Pagination

async findByFilters(filters: FilterDto) {
  const conditions = [];

  if (filters.role) {
    conditions.push(eq(schema.users.role, filters.role));
  }

  if (filters.search) {
    conditions.push(
      or(
        ilike(schema.users.email, `%${filters.search}%`),
        ilike(schema.users.name, `%${filters.search}%`),
      ),
    );
  }

  if (filters.isActive !== undefined) {
    conditions.push(eq(schema.users.isActive, filters.isActive));
  }

  const whereClause = conditions.length > 0 ? and(...conditions) : undefined;

  const users = await this.db
    .select()
    .from(schema.users)
    .where(whereClause)
    .orderBy(desc(schema.users.createdAt))
    .limit(filters.limit)
    .offset((filters.page - 1) * filters.limit);

  const [{ count }] = await this.db
    .select({ count: sql<number>`count(*)` })
    .from(schema.users)
    .where(whereClause);

  return {
    data: users,
    meta: {
      total: Number(count),
      page: filters.page,
      limit: filters.limit,
    },
  };
}

Drizzle Transactions

async createWithProfile(data: CreateUserDto) {
  return this.db.transaction(async (tx) => {
    const [user] = await tx
      .insert(schema.users)
      .values({
        email: data.email,
        password: data.password,
        name: data.name,
      })
      .returning();

    await tx.insert(schema.profiles).values({
      userId: user.id,
      bio: '',
    });

    return user;
  });
}

---

Common Patterns

Repository Abstraction

Create a generic interface that works with any ORM:

// common/interfaces/repository.interface.ts
export interface IRepository<T> {
  findAll(): Promise<T[]>;
  findOne(id: string | number): Promise<T | null>;
  create(data: Partial<T>): Promise<T>;
  update(id: string | number, data: Partial<T>): Promise<T>;
  delete(id: string | number): Promise<void>;
}

// Implementation can use TypeORM, Prisma, or Drizzle
@Injectable()
export class UsersRepository implements IRepository<User> {
  constructor(private prisma: PrismaService) {}

  async findAll() {
    return this.prisma.user.findMany();
  }

  // ... other methods
}

Database Health Check

// health/database.health.ts
import { Injectable } from '@nestjs/common';
import {
  HealthIndicator,
  HealthIndicatorResult,
  HealthCheckError,
} from '@nestjs/terminus';
import { PrismaService } from '../prisma/prisma.service';

@Injectable()
export class DatabaseHealthIndicator extends HealthIndicator {
  constructor(private prisma: PrismaService) {
    super();
  }

  async isHealthy(key: string): Promise<HealthIndicatorResult> {
    try {
      await this.prisma.$queryRaw`SELECT 1`;
      return this.getStatus(key, true);
    } catch (error) {
      throw new HealthCheckError(
        'Database check failed',
        this.getStatus(key, false, { message: error.message }),
      );
    }
  }
}

// health/health.controller.ts
@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: DatabaseHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([
      () => this.db.isHealthy('database'),
    ]);
  }
}

Soft Delete Pattern

// TypeORM
@Entity()
export class User {
  @DeleteDateColumn()
  deletedAt?: Date;
}

// Prisma - manual implementation
model User {
  deletedAt DateTime?
}

// Service
async softDelete(id: string) {
  return this.prisma.user.update({
    where: { id },
    data: { deletedAt: new Date() },
  });
}

async findActive() {
  return this.prisma.user.findMany({
    where: { deletedAt: null },
  });
}

// Drizzle
async softDelete(id: string) {
  return this.db
    .update(schema.users)
    .set({ deletedAt: new Date() })
    .where(eq(schema.users.id, id));
}

Migrations

# TypeORM
npx typeorm migration:generate -d data-source.ts src/migrations/CreateUsers
npx typeorm migration:run -d data-source.ts

# Prisma
npx prisma migrate dev --name create_users
npx prisma migrate deploy  # Production

# Drizzle
npx drizzle-kit generate
npx drizzle-kit migrate

Microservices

Table of Contents

• Microservices Overview
• TCP Transport
• Redis Transport
• NATS Transport
• Kafka Transport
• Message and Event Patterns
• Hybrid Applications

---

Microservices Overview

NestJS microservices use a transport layer to communicate between services. Communication can be synchronous (request-response) or asynchronous (event-based).

Installation

npm install @nestjs/microservices

Key Concepts

Architecture Overview

┌─────────────────┐     Message/Event      ┌─────────────────┐
│   API Gateway   │ ──────────────────────>│  Microservice   │
│   (HTTP/REST)   │                        │   (TCP/Redis)   │
└─────────────────┘                        └─────────────────┘
         │                                          │
         │                                          │
         ▼                                          ▼
┌─────────────────┐                        ┌─────────────────┐
│     Client      │                        │    Database     │
└─────────────────┘                        └─────────────────┘

---

TCP Transport

TCP is the default transport, suitable for internal communication within a network.

Microservice Setup

// main.ts (microservice)
import { NestFactory } from '@nestjs/core';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(
    AppModule,
    {
      transport: Transport.TCP,
      options: {
        host: '0.0.0.0',
        port: 3001,
      },
    },
  );

  await app.listen();
  console.log('Microservice is listening on port 3001');
}
bootstrap();

Controller with Message Patterns

// users/users.controller.ts (microservice)
import { Controller } from '@nestjs/common';
import { MessagePattern, Payload } from '@nestjs/microservices';
import { UsersService } from './users.service';

@Controller()
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @MessagePattern({ cmd: 'get_users' })
  getUsers() {
    return this.usersService.findAll();
  }

  @MessagePattern({ cmd: 'get_user' })
  getUser(@Payload() data: { id: string }) {
    return this.usersService.findOne(data.id);
  }

  @MessagePattern({ cmd: 'create_user' })
  createUser(@Payload() data: CreateUserDto) {
    return this.usersService.create(data);
  }
}

Client Setup (API Gateway)

// app.module.ts (gateway)
import { Module } from '@nestjs/common';
import { ClientsModule, Transport } from '@nestjs/microservices';

@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'USERS_SERVICE',
        transport: Transport.TCP,
        options: {
          host: 'localhost',
          port: 3001,
        },
      },
    ]),
  ],
})
export class AppModule {}

Using the Client

// gateway/users.controller.ts
import { Controller, Get, Post, Body, Param, Inject } from '@nestjs/common';
import { ClientProxy } from '@nestjs/microservices';
import { firstValueFrom } from 'rxjs';

@Controller('users')
export class UsersController {
  constructor(
    @Inject('USERS_SERVICE') private readonly usersClient: ClientProxy,
  ) {}

  @Get()
  async getUsers() {
    return firstValueFrom(
      this.usersClient.send({ cmd: 'get_users' }, {}),
    );
  }

  @Get(':id')
  async getUser(@Param('id') id: string) {
    return firstValueFrom(
      this.usersClient.send({ cmd: 'get_user' }, { id }),
    );
  }

  @Post()
  async createUser(@Body() createUserDto: CreateUserDto) {
    return firstValueFrom(
      this.usersClient.send({ cmd: 'create_user' }, createUserDto),
    );
  }
}

---

Redis Transport

Redis provides pub/sub messaging with support for message persistence.

Installation

npm install ioredis

Microservice Setup

// main.ts (microservice)
async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(
    AppModule,
    {
      transport: Transport.REDIS,
      options: {
        host: 'localhost',
        port: 6379,
        retryAttempts: 5,
        retryDelay: 1000,
      },
    },
  );

  await app.listen();
}

Client Setup

// app.module.ts (gateway)
@Module({
  imports: [
    ClientsModule.registerAsync([
      {
        name: 'USERS_SERVICE',
        imports: [ConfigModule],
        useFactory: (configService: ConfigService) => ({
          transport: Transport.REDIS,
          options: {
            host: configService.get('REDIS_HOST'),
            port: configService.get('REDIS_PORT'),
          },
        }),
        inject: [ConfigService],
      },
    ]),
  ],
})
export class AppModule {}

Event-Based Communication

// Microservice controller
@Controller()
export class OrdersController {
  @EventPattern('order_created')
  handleOrderCreated(@Payload() data: OrderCreatedEvent) {
    console.log('Order created:', data);
    // Process the event (no response expected)
  }
}

// Gateway/Publisher
@Controller('orders')
export class OrdersController {
  constructor(
    @Inject('ORDERS_SERVICE') private ordersClient: ClientProxy,
  ) {}

  @Post()
  async createOrder(@Body() createOrderDto: CreateOrderDto) {
    const order = await this.ordersService.create(createOrderDto);

    // Emit event (fire-and-forget)
    this.ordersClient.emit('order_created', {
      orderId: order.id,
      userId: order.userId,
      items: order.items,
    });

    return order;
  }
}

---

NATS Transport

NATS is a high-performance messaging system ideal for cloud-native applications.

Installation

npm install nats

Microservice Setup

// main.ts
async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(
    AppModule,
    {
      transport: Transport.NATS,
      options: {
        servers: ['nats://localhost:4222'],
        queue: 'users_queue', // Queue group for load balancing
      },
    },
  );

  await app.listen();
}

Client Setup

@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'USERS_SERVICE',
        transport: Transport.NATS,
        options: {
          servers: ['nats://localhost:4222'],
        },
      },
    ]),
  ],
})
export class AppModule {}

NATS with Wildcards

// Microservice - subscribe to pattern
@Controller()
export class NotificationsController {
  // Matches: user.created, user.updated, user.deleted
  @MessagePattern('user.*')
  handleUserEvents(@Payload() data: any, @Ctx() context: NatsContext) {
    const subject = context.getSubject();
    console.log(`Received event on ${subject}:`, data);
  }

  // Matches: order.payment.success, order.shipping.completed
  @MessagePattern('order.>')
  handleOrderEvents(@Payload() data: any) {
    // Handle any order-related event
  }
}

---

Kafka Transport

Apache Kafka provides durable, high-throughput messaging for event streaming.

Installation

npm install kafkajs

Microservice Setup

// main.ts
async function bootstrap() {
  const app = await NestFactory.createMicroservice<MicroserviceOptions>(
    AppModule,
    {
      transport: Transport.KAFKA,
      options: {
        client: {
          clientId: 'users-service',
          brokers: ['localhost:9092'],
        },
        consumer: {
          groupId: 'users-consumer-group',
        },
      },
    },
  );

  await app.listen();
}

Controller with Kafka Topics

// users/users.controller.ts
import { Controller } from '@nestjs/common';
import { MessagePattern, Payload, Ctx, KafkaContext } from '@nestjs/microservices';

@Controller()
export class UsersController {
  @MessagePattern('users.get')
  getUsers(@Payload() message: any, @Ctx() context: KafkaContext) {
    const originalMessage = context.getMessage();
    const partition = context.getPartition();
    const topic = context.getTopic();

    console.log(`Received message on topic: ${topic}, partition: ${partition}`);

    return this.usersService.findAll();
  }

  @EventPattern('users.created')
  handleUserCreated(
    @Payload() data: UserCreatedEvent,
    @Ctx() context: KafkaContext,
  ) {
    const { offset } = context.getMessage();
    console.log(`Processing message at offset ${offset}`);

    // Process event
  }
}

Client Setup with Kafka

@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'KAFKA_SERVICE',
        transport: Transport.KAFKA,
        options: {
          client: {
            clientId: 'api-gateway',
            brokers: ['localhost:9092'],
          },
          producer: {
            allowAutoTopicCreation: true,
          },
        },
      },
    ]),
  ],
})
export class AppModule {}

// Using the client
@Injectable()
export class UsersService {
  constructor(
    @Inject('KAFKA_SERVICE') private kafkaClient: ClientKafka,
  ) {}

  async onModuleInit() {
    // Subscribe to response topics
    this.kafkaClient.subscribeToResponseOf('users.get');
    await this.kafkaClient.connect();
  }

  async getUsers() {
    return firstValueFrom(
      this.kafkaClient.send('users.get', { timestamp: Date.now() }),
    );
  }

  async emitUserCreated(user: User) {
    this.kafkaClient.emit('users.created', {
      key: user.id,
      value: { userId: user.id, email: user.email },
    });
  }
}

---

Message and Event Patterns

Message Pattern (Request-Response)

Synchronous communication where a response is expected.

// Microservice
@MessagePattern({ cmd: 'sum' })
accumulate(@Payload() data: number[]): number {
  return data.reduce((a, b) => a + b, 0);
}

// Client
const result = await firstValueFrom(
  this.client.send({ cmd: 'sum' }, [1, 2, 3, 4, 5]),
);
console.log(result); // 15

Event Pattern (Fire-and-Forget)

Asynchronous communication with no response.

// Microservice
@EventPattern('user_created')
handleUserCreated(@Payload() data: UserCreatedEvent) {
  // Send welcome email
  this.emailService.sendWelcome(data.email);
  // No return value
}

// Client
this.client.emit('user_created', { email: 'user@example.com' });
// Continues immediately, doesn't wait

Error Handling

// Microservice
@MessagePattern({ cmd: 'get_user' })
async getUser(@Payload() data: { id: string }) {
  const user = await this.usersService.findOne(data.id);

  if (!user) {
    // Return RpcException for client to catch
    throw new RpcException({
      status: 404,
      message: 'User not found',
    });
  }

  return user;
}

// Client with error handling
@Get(':id')
async getUser(@Param('id') id: string) {
  try {
    return await firstValueFrom(
      this.client.send({ cmd: 'get_user' }, { id }),
    );
  } catch (error) {
    if (error.status === 404) {
      throw new NotFoundException(error.message);
    }
    throw new InternalServerErrorException();
  }
}

Timeout Handling

import { timeout, catchError } from 'rxjs/operators';
import { TimeoutError } from 'rxjs';

@Get(':id')
async getUser(@Param('id') id: string) {
  return firstValueFrom(
    this.client.send({ cmd: 'get_user' }, { id }).pipe(
      timeout(5000), // 5 second timeout
      catchError((err) => {
        if (err instanceof TimeoutError) {
          throw new RequestTimeoutException('Service did not respond');
        }
        throw err;
      }),
    ),
  );
}

---

Hybrid Applications

Combine HTTP server with microservice transports in a single application.

Basic Hybrid Setup

// main.ts
import { NestFactory } from '@nestjs/core';
import { MicroserviceOptions, Transport } from '@nestjs/microservices';
import { AppModule } from './app.module';

async function bootstrap() {
  // Create HTTP application
  const app = await NestFactory.create(AppModule);

  // Connect microservice transport
  app.connectMicroservice<MicroserviceOptions>({
    transport: Transport.TCP,
    options: {
      host: '0.0.0.0',
      port: 3001,
    },
  });

  // Connect additional transport
  app.connectMicroservice<MicroserviceOptions>({
    transport: Transport.REDIS,
    options: {
      host: 'localhost',
      port: 6379,
    },
  });

  // Start all microservices
  await app.startAllMicroservices();

  // Start HTTP server
  await app.listen(3000);

  console.log('HTTP server on port 3000');
  console.log('TCP microservice on port 3001');
  console.log('Redis microservice connected');
}
bootstrap();

Controller with Both HTTP and Microservice

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  // HTTP endpoint
  @Get()
  findAll() {
    return this.usersService.findAll();
  }

  // Microservice message pattern
  @MessagePattern({ cmd: 'get_users' })
  getUsers() {
    return this.usersService.findAll();
  }

  // HTTP endpoint
  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

  // Microservice event pattern
  @EventPattern('user_created')
  handleUserCreated(@Payload() data: UserCreatedEvent) {
    this.usersService.sendWelcomeEmail(data.email);
  }
}

Service Discovery Pattern

// Use environment variables for service URLs
@Module({
  imports: [
    ClientsModule.registerAsync([
      {
        name: 'USERS_SERVICE',
        imports: [ConfigModule],
        useFactory: (config: ConfigService) => ({
          transport: Transport.TCP,
          options: {
            host: config.get('USERS_SERVICE_HOST', 'localhost'),
            port: config.get('USERS_SERVICE_PORT', 3001),
          },
        }),
        inject: [ConfigService],
      },
      {
        name: 'ORDERS_SERVICE',
        imports: [ConfigModule],
        useFactory: (config: ConfigService) => ({
          transport: Transport.TCP,
          options: {
            host: config.get('ORDERS_SERVICE_HOST', 'localhost'),
            port: config.get('ORDERS_SERVICE_PORT', 3002),
          },
        }),
        inject: [ConfigService],
      },
    ]),
  ],
})
export class GatewayModule {}

Health Checks for Microservices

// health/health.controller.ts
import { Controller, Get } from '@nestjs/common';
import {
  HealthCheck,
  HealthCheckService,
  MicroserviceHealthIndicator,
} from '@nestjs/terminus';
import { Transport } from '@nestjs/microservices';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private microservice: MicroserviceHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([
      () =>
        this.microservice.pingCheck('users-service', {
          transport: Transport.TCP,
          options: { host: 'localhost', port: 3001 },
        }),
      () =>
        this.microservice.pingCheck('orders-service', {
          transport: Transport.REDIS,
          options: { host: 'localhost', port: 6379 },
        }),
    ]);
  }
}

OpenAPI & GraphQL

Table of Contents

• OpenAPI/Swagger Setup
• API Decorators
• CLI Plugin
• GraphQL Code-First
• Resolvers
• Subscriptions

---

OpenAPI/Swagger Setup

The @nestjs/swagger module generates OpenAPI (Swagger) documentation automatically from your controllers and DTOs.

Installation

npm install @nestjs/swagger

Basic Setup

// main.ts
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('The API documentation')
    .setVersion('1.0')
    .addTag('users')
    .addTag('auth')
    .addBearerAuth(
      {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
        name: 'JWT',
        description: 'Enter JWT token',
        in: 'header',
      },
      'JWT-auth', // Reference name for @ApiBearerAuth()
    )
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document); // Available at /api

  await app.listen(3000);
}
bootstrap();

Advanced Configuration

const config = new DocumentBuilder()
  .setTitle('E-Commerce API')
  .setDescription('API for e-commerce platform')
  .setVersion('2.0')
  .setContact('API Support', 'https://example.com', 'support@example.com')
  .setLicense('MIT', 'https://opensource.org/licenses/MIT')
  .addServer('http://localhost:3000', 'Development')
  .addServer('https://api.example.com', 'Production')
  .addApiKey({ type: 'apiKey', name: 'X-API-KEY', in: 'header' }, 'api-key')
  .addOAuth2({
    type: 'oauth2',
    flows: {
      implicit: {
        authorizationUrl: 'https://auth.example.com/oauth/authorize',
        scopes: {
          'read:users': 'Read user data',
          'write:users': 'Modify user data',
        },
      },
    },
  })
  .build();

const document = SwaggerModule.createDocument(app, config, {
  include: [UsersModule, AuthModule], // Only include specific modules
  deepScanRoutes: true,
  operationIdFactory: (controllerKey: string, methodKey: string) =>
    `${controllerKey}_${methodKey}`,
});

// Customize Swagger UI
SwaggerModule.setup('api', app, document, {
  swaggerOptions: {
    persistAuthorization: true,
    tagsSorter: 'alpha',
    operationsSorter: 'alpha',
  },
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'My API Docs',
});

---

API Decorators

Controller and Method Decorators

import {
  ApiTags,
  ApiOperation,
  ApiResponse,
  ApiBearerAuth,
  ApiParam,
  ApiQuery,
  ApiBody,
  ApiConsumes,
  ApiProduces,
} from '@nestjs/swagger';

@ApiTags('users')
@ApiBearerAuth('JWT-auth')
@Controller('users')
export class UsersController {
  @Get()
  @ApiOperation({ summary: 'Get all users', description: 'Returns all users with pagination' })
  @ApiQuery({ name: 'page', required: false, type: Number, description: 'Page number' })
  @ApiQuery({ name: 'limit', required: false, type: Number, description: 'Items per page' })
  @ApiResponse({ status: 200, description: 'Users retrieved successfully', type: [UserResponseDto] })
  @ApiResponse({ status: 401, description: 'Unauthorized' })
  findAll(
    @Query('page') page?: number,
    @Query('limit') limit?: number,
  ) {
    return this.usersService.findAll({ page, limit });
  }

  @Get(':id')
  @ApiOperation({ summary: 'Get user by ID' })
  @ApiParam({ name: 'id', type: String, description: 'User UUID' })
  @ApiResponse({ status: 200, description: 'User found', type: UserResponseDto })
  @ApiResponse({ status: 404, description: 'User not found' })
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id);
  }

  @Post()
  @ApiOperation({ summary: 'Create a new user' })
  @ApiBody({ type: CreateUserDto })
  @ApiResponse({ status: 201, description: 'User created', type: UserResponseDto })
  @ApiResponse({ status: 400, description: 'Validation failed' })
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

  @Post('upload')
  @ApiConsumes('multipart/form-data')
  @ApiBody({
    schema: {
      type: 'object',
      properties: {
        file: {
          type: 'string',
          format: 'binary',
        },
      },
    },
  })
  @UseInterceptors(FileInterceptor('file'))
  uploadFile(@UploadedFile() file: Express.Multer.File) {
    return { filename: file.filename };
  }
}

DTO Property Decorators

import { ApiProperty, ApiPropertyOptional, ApiHideProperty } from '@nestjs/swagger';

export class CreateUserDto {
  @ApiProperty({
    example: 'user@example.com',
    description: 'User email address',
    format: 'email',
  })
  @IsEmail()
  email: string;

  @ApiProperty({
    example: 'StrongP@ss123',
    description: 'User password',
    minLength: 8,
  })
  @IsString()
  @MinLength(8)
  password: string;

  @ApiPropertyOptional({
    example: 'John Doe',
    description: 'User full name',
  })
  @IsOptional()
  @IsString()
  name?: string;

  @ApiProperty({
    enum: ['user', 'admin'],
    default: 'user',
    description: 'User role',
  })
  @IsEnum(['user', 'admin'])
  role: string;

  @ApiProperty({
    type: [String],
    example: ['tag1', 'tag2'],
    description: 'User tags',
  })
  @IsArray()
  @IsString({ each: true })
  tags: string[];
}

export class UserResponseDto {
  @ApiProperty({ example: '123e4567-e89b-12d3-a456-426614174000' })
  id: string;

  @ApiProperty({ example: 'user@example.com' })
  email: string;

  @ApiHideProperty() // Won't appear in Swagger
  password: string;

  @ApiProperty({ example: '2024-01-01T00:00:00.000Z' })
  createdAt: Date;
}

Response Schemas

export class PaginatedResponseDto<T> {
  data: T[];
  meta: PaginationMeta;
}

class PaginationMeta {
  @ApiProperty({ example: 100 })
  total: number;

  @ApiProperty({ example: 1 })
  page: number;

  @ApiProperty({ example: 10 })
  limit: number;

  @ApiProperty({ example: 10 })
  totalPages: number;
}

// Usage with generic
@Get()
@ApiOkResponse({
  schema: {
    allOf: [
      { $ref: getSchemaPath(PaginatedResponseDto) },
      {
        properties: {
          data: {
            type: 'array',
            items: { $ref: getSchemaPath(UserResponseDto) },
          },
        },
      },
    ],
  },
})
findAll() {}

---

CLI Plugin

The CLI plugin automatically adds Swagger decorators at compile time, reducing boilerplate.

Setup

// nest-cli.json
{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "classValidatorShim": true,
          "introspectComments": true,
          "dtoFileNameSuffix": [".dto.ts", ".entity.ts"]
        }
      }
    ]
  }
}

What the Plugin Does

Before (manual decorators):

export class CreateUserDto {
  @ApiProperty({ description: 'User email' })
  @IsEmail()
  email: string;

  @ApiPropertyOptional({ description: 'User name' })
  @IsOptional()
  @IsString()
  name?: string;
}

After (with plugin - decorators added automatically):

export class CreateUserDto {
  /**
   * User email
   */
  @IsEmail()
  email: string;

  /**
   * User name
   */
  @IsOptional()
  @IsString()
  name?: string;
}

The plugin reads JSDoc comments and TypeScript types to generate @ApiProperty decorators automatically.

---

GraphQL Code-First

The code-first approach generates the GraphQL schema from TypeScript classes and decorators.

Installation

npm install @nestjs/graphql @nestjs/apollo @apollo/server graphql

Module Setup

// app.module.ts
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { join } from 'path';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
      sortSchema: true,
      playground: process.env.NODE_ENV !== 'production',
      context: ({ req }) => ({ req }),
    }),
    UsersModule,
  ],
})
export class AppModule {}

Object Types

// users/entities/user.entity.ts
import { ObjectType, Field, ID, Int } from '@nestjs/graphql';

@ObjectType()
export class User {
  @Field(() => ID)
  id: string;

  @Field()
  email: string;

  @Field({ nullable: true })
  name?: string;

  @Field(() => Int)
  age: number;

  @Field(() => [Post], { nullable: 'items' })
  posts: Post[];

  @Field()
  createdAt: Date;

  // Password not exposed in GraphQL
}

@ObjectType()
export class Post {
  @Field(() => ID)
  id: number;

  @Field()
  title: string;

  @Field({ nullable: true })
  content?: string;

  @Field(() => User)
  author: User;
}

Input Types

// users/dto/create-user.input.ts
import { InputType, Field } from '@nestjs/graphql';
import { IsEmail, MinLength } from 'class-validator';

@InputType()
export class CreateUserInput {
  @Field()
  @IsEmail()
  email: string;

  @Field()
  @MinLength(8)
  password: string;

  @Field({ nullable: true })
  name?: string;
}

@InputType()
export class UpdateUserInput {
  @Field({ nullable: true })
  name?: string;

  @Field({ nullable: true })
  @IsEmail()
  email?: string;
}

Enums and Scalars

import { registerEnumType } from '@nestjs/graphql';

export enum Role {
  USER = 'user',
  ADMIN = 'admin',
}

registerEnumType(Role, {
  name: 'Role',
  description: 'User roles',
});

// Usage
@ObjectType()
export class User {
  @Field(() => Role)
  role: Role;
}

---

Resolvers

Basic Resolver

// users/users.resolver.ts
import { Resolver, Query, Mutation, Args, ID } from '@nestjs/graphql';
import { UseGuards } from '@nestjs/common';
import { User } from './entities/user.entity';
import { UsersService } from './users.service';
import { CreateUserInput } from './dto/create-user.input';
import { UpdateUserInput } from './dto/update-user.input';
import { GqlAuthGuard } from '../auth/guards/gql-auth.guard';
import { CurrentUser } from '../auth/decorators/current-user.decorator';

@Resolver(() => User)
export class UsersResolver {
  constructor(private readonly usersService: UsersService) {}

  @Query(() => [User], { name: 'users' })
  findAll() {
    return this.usersService.findAll();
  }

  @Query(() => User, { name: 'user', nullable: true })
  findOne(@Args('id', { type: () => ID }) id: string) {
    return this.usersService.findOne(id);
  }

  @Query(() => User, { name: 'me' })
  @UseGuards(GqlAuthGuard)
  me(@CurrentUser() user: User) {
    return user;
  }

  @Mutation(() => User)
  createUser(@Args('input') input: CreateUserInput) {
    return this.usersService.create(input);
  }

  @Mutation(() => User)
  @UseGuards(GqlAuthGuard)
  updateUser(
    @Args('id', { type: () => ID }) id: string,
    @Args('input') input: UpdateUserInput,
  ) {
    return this.usersService.update(id, input);
  }

  @Mutation(() => Boolean)
  @UseGuards(GqlAuthGuard)
  removeUser(@Args('id', { type: () => ID }) id: string) {
    return this.usersService.remove(id);
  }
}

Field Resolvers

@Resolver(() => User)
export class UsersResolver {
  constructor(
    private readonly usersService: UsersService,
    private readonly postsService: PostsService,
  ) {}

  @ResolveField(() => [Post])
  async posts(@Parent() user: User) {
    return this.postsService.findByAuthorId(user.id);
  }

  @ResolveField(() => Int)
  async postsCount(@Parent() user: User) {
    return this.postsService.countByAuthorId(user.id);
  }
}

DataLoader for N+1 Prevention

// users/users.loader.ts
import * as DataLoader from 'dataloader';
import { Injectable, Scope } from '@nestjs/common';
import { UsersService } from './users.service';

@Injectable({ scope: Scope.REQUEST })
export class UsersLoader {
  constructor(private usersService: UsersService) {}

  readonly batchUsers = new DataLoader<string, User>(async (ids) => {
    const users = await this.usersService.findByIds([...ids]);
    const usersMap = new Map(users.map((user) => [user.id, user]));
    return ids.map((id) => usersMap.get(id));
  });
}

// posts/posts.resolver.ts
@Resolver(() => Post)
export class PostsResolver {
  constructor(private readonly usersLoader: UsersLoader) {}

  @ResolveField(() => User)
  async author(@Parent() post: Post) {
    return this.usersLoader.batchUsers.load(post.authorId);
  }
}

GraphQL Auth Guard

// auth/guards/gql-auth.guard.ts
import { ExecutionContext, Injectable } from '@nestjs/common';
import { GqlExecutionContext } from '@nestjs/graphql';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class GqlAuthGuard extends AuthGuard('jwt') {
  getRequest(context: ExecutionContext) {
    const ctx = GqlExecutionContext.create(context);
    return ctx.getContext().req;
  }
}

// auth/decorators/current-user.decorator.ts (GraphQL version)
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { GqlExecutionContext } from '@nestjs/graphql';

export const CurrentUser = createParamDecorator(
  (data: unknown, context: ExecutionContext) => {
    const ctx = GqlExecutionContext.create(context);
    return ctx.getContext().req.user;
  },
);

---

Subscriptions

Real-time updates via WebSocket connections.

Setup

// app.module.ts
@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      autoSchemaFile: true,
      subscriptions: {
        'graphql-ws': true,
        'subscriptions-transport-ws': true, // Legacy support
      },
      context: ({ req, connection }) => {
        // For subscriptions, connection exists instead of req
        return { req: connection ? connection.context : req };
      },
    }),
  ],
})
export class AppModule {}

PubSub Setup

// pubsub/pubsub.module.ts
import { Global, Module } from '@nestjs/common';
import { PubSub } from 'graphql-subscriptions';

export const PUB_SUB = 'PUB_SUB';

@Global()
@Module({
  providers: [
    {
      provide: PUB_SUB,
      useValue: new PubSub(),
    },
  ],
  exports: [PUB_SUB],
})
export class PubSubModule {}

Subscription Resolver

// posts/posts.resolver.ts
import { Resolver, Mutation, Subscription, Args } from '@nestjs/graphql';
import { Inject } from '@nestjs/common';
import { PubSub } from 'graphql-subscriptions';
import { PUB_SUB } from '../pubsub/pubsub.module';

const POST_ADDED = 'postAdded';
const POST_UPDATED = 'postUpdated';

@Resolver(() => Post)
export class PostsResolver {
  constructor(
    private readonly postsService: PostsService,
    @Inject(PUB_SUB) private pubSub: PubSub,
  ) {}

  @Mutation(() => Post)
  async createPost(@Args('input') input: CreatePostInput) {
    const post = await this.postsService.create(input);
    this.pubSub.publish(POST_ADDED, { postAdded: post });
    return post;
  }

  @Subscription(() => Post)
  postAdded() {
    return this.pubSub.asyncIterableIterator(POST_ADDED);
  }

  // Subscription with filter
  @Subscription(() => Post, {
    filter: (payload, variables) => {
      return payload.postUpdated.authorId === variables.authorId;
    },
  })
  postUpdated(@Args('authorId') authorId: string) {
    return this.pubSub.asyncIterableIterator(POST_UPDATED);
  }

  // Subscription with resolve
  @Subscription(() => Post, {
    resolve: (payload) => payload.postAdded,
  })
  newPost() {
    return this.pubSub.asyncIterableIterator(POST_ADDED);
  }
}

Redis PubSub for Production

npm install graphql-redis-subscriptions ioredis

// pubsub/pubsub.module.ts
import { RedisPubSub } from 'graphql-redis-subscriptions';
import Redis from 'ioredis';

@Global()
@Module({
  providers: [
    {
      provide: PUB_SUB,
      useFactory: (configService: ConfigService) => {
        const options = {
          host: configService.get('REDIS_HOST'),
          port: configService.get('REDIS_PORT'),
        };

        return new RedisPubSub({
          publisher: new Redis(options),
          subscriber: new Redis(options),
        });
      },
      inject: [ConfigService],
    },
  ],
  exports: [PUB_SUB],
})
export class PubSubModule {}

Client Usage

# Subscribe to new posts
subscription {
  postAdded {
    id
    title
    author {
      name
    }
  }
}

# Subscribe with filter
subscription {
  postUpdated(authorId: "123") {
    id
    title
  }
}

Request Lifecycle

Table of Contents

• Request Lifecycle Overview
• Middleware
• Guards
• Interceptors
• Pipes
• Exception Filters
• Execution Order

---

Request Lifecycle Overview

Every incoming request flows through a specific pipeline of components:

Request
   │
   ▼
┌─────────────────┐
│   Middleware    │  ← Express/Fastify middleware
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Guards      │  ← Authorization (can proceed?)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Interceptors   │  ← Before handler (transform request)
│    (Before)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Pipes       │  ← Validation & transformation
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Controller    │  ← Route handler
│    Handler      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Interceptors   │  ← After handler (transform response)
│    (After)      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Exception     │  ← Error handling (if exception thrown)
│    Filters      │
└────────┬────────┘
         │
         ▼
Response

---

Middleware

Middleware runs before the route handler and has access to the raw request/response objects.

Class Middleware

import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const start = Date.now();

    res.on('finish', () => {
      const duration = Date.now() - start;
      console.log(`${req.method} ${req.url} ${res.statusCode} - ${duration}ms`);
    });

    next();
  }
}

Functional Middleware

For simple middleware without dependencies:

import { Request, Response, NextFunction } from 'express';

export function correlationIdMiddleware(
  req: Request,
  res: Response,
  next: NextFunction,
) {
  const correlationId = req.headers['x-correlation-id'] || crypto.randomUUID();
  req['correlationId'] = correlationId;
  res.setHeader('x-correlation-id', correlationId);
  next();
}

Applying Middleware

// In module
@Module({})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware, correlationIdMiddleware)
      .exclude(
        { path: 'health', method: RequestMethod.GET },
        { path: 'metrics', method: RequestMethod.GET },
      )
      .forRoutes('*'); // Apply to all routes
  }
}

// Route-specific
consumer
  .apply(AuthMiddleware)
  .forRoutes(
    { path: 'users', method: RequestMethod.ALL },
    { path: 'posts', method: RequestMethod.POST },
  );

// Controller-specific
consumer
  .apply(AdminMiddleware)
  .forRoutes(AdminController);

Global Middleware (main.ts)

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Apply Express middleware globally
  app.use(helmet());
  app.use(compression());
  app.use(correlationIdMiddleware);

  await app.listen(3000);
}

---

Guards

Guards determine whether a request will be handled by the route handler. Use for authorization logic.

Basic Guard

import {
  Injectable,
  CanActivate,
  ExecutionContext,
  UnauthorizedException,
} from '@nestjs/common';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean | Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = request.headers.authorization?.split(' ')[1];

    if (!token) {
      throw new UnauthorizedException('No token provided');
    }

    try {
      const payload = this.jwtService.verify(token);
      request.user = payload;
      return true;
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }
}

Role-Based Guard

import { SetMetadata } from '@nestjs/common';

export const ROLES_KEY = 'roles';
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<string[]>(
      ROLES_KEY,
      [context.getHandler(), context.getClass()],
    );

    if (!requiredRoles) {
      return true; // No roles required
    }

    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.some((role) => user.roles?.includes(role));
  }
}

// Usage
@Controller('admin')
@UseGuards(AuthGuard, RolesGuard)
export class AdminController {
  @Get('users')
  @Roles('admin', 'superadmin')
  getUsers() {}
}

Applying Guards

// Method level
@Get('profile')
@UseGuards(AuthGuard)
getProfile() {}

// Controller level
@Controller('users')
@UseGuards(AuthGuard)
export class UsersController {}

// Global level (main.ts)
app.useGlobalGuards(new AuthGuard());

// Global with DI (app.module.ts)
@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: AuthGuard,
    },
  ],
})
export class AppModule {}

ExecutionContext Utilities

@Injectable()
export class MultiContextGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    // Get context type
    const type = context.getType(); // 'http' | 'rpc' | 'ws' | 'graphql'

    if (type === 'http') {
      const request = context.switchToHttp().getRequest();
      const response = context.switchToHttp().getResponse();
    }

    if (type === 'ws') {
      const client = context.switchToWs().getClient();
      const data = context.switchToWs().getData();
    }

    if (type === 'rpc') {
      const data = context.switchToRpc().getData();
      const ctx = context.switchToRpc().getContext();
    }

    // Get handler and class metadata
    const handler = context.getHandler(); // Method reference
    const controller = context.getClass(); // Class reference

    return true;
  }
}

---

Interceptors

Interceptors can transform the result returned from a function, transform exceptions, extend basic function behavior, or override a function entirely.

Response Transformation Interceptor

import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

export interface Response<T> {
  data: T;
  statusCode: number;
  timestamp: string;
}

@Injectable()
export class TransformInterceptor<T>
  implements NestInterceptor<T, Response<T>>
{
  intercept(
    context: ExecutionContext,
    next: CallHandler,
  ): Observable<Response<T>> {
    return next.handle().pipe(
      map((data) => ({
        data,
        statusCode: context.switchToHttp().getResponse().statusCode,
        timestamp: new Date().toISOString(),
      })),
    );
  }
}

Logging Interceptor

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger(LoggingInterceptor.name);

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const { method, url, body } = request;
    const start = Date.now();

    this.logger.log(`Incoming ${method} ${url}`);

    return next.handle().pipe(
      tap({
        next: (data) => {
          const duration = Date.now() - start;
          this.logger.log(`${method} ${url} completed in ${duration}ms`);
        },
        error: (error) => {
          const duration = Date.now() - start;
          this.logger.error(`${method} ${url} failed in ${duration}ms`, error);
        },
      }),
    );
  }
}

Timeout Interceptor

import { Observable, throwError, TimeoutError } from 'rxjs';
import { catchError, timeout } from 'rxjs/operators';

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  constructor(private readonly timeoutMs: number = 5000) {}

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      timeout(this.timeoutMs),
      catchError((err) => {
        if (err instanceof TimeoutError) {
          throw new RequestTimeoutException('Request timed out');
        }
        return throwError(() => err);
      }),
    );
  }
}

Cache Interceptor

@Injectable()
export class CacheInterceptor implements NestInterceptor {
  constructor(private cacheService: CacheService) {}

  async intercept(
    context: ExecutionContext,
    next: CallHandler,
  ): Promise<Observable<any>> {
    const request = context.switchToHttp().getRequest();

    // Only cache GET requests
    if (request.method !== 'GET') {
      return next.handle();
    }

    const cacheKey = request.url;
    const cached = await this.cacheService.get(cacheKey);

    if (cached) {
      return of(cached);
    }

    return next.handle().pipe(
      tap((data) => {
        this.cacheService.set(cacheKey, data, 60); // TTL 60 seconds
      }),
    );
  }
}

Applying Interceptors

// Method level
@Get()
@UseInterceptors(LoggingInterceptor)
findAll() {}

// Controller level
@Controller('users')
@UseInterceptors(TransformInterceptor)
export class UsersController {}

// Global level (main.ts)
app.useGlobalInterceptors(new LoggingInterceptor());

// Global with DI
@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: TransformInterceptor,
    },
  ],
})
export class AppModule {}

---

Pipes

Pipes transform input data or validate it before it reaches the route handler.

Built-in Pipes

import {
  ParseIntPipe,
  ParseBoolPipe,
  ParseArrayPipe,
  ParseUUIDPipe,
  ParseEnumPipe,
  DefaultValuePipe,
  ParseFloatPipe,
} from '@nestjs/common';

@Controller('users')
export class UsersController {
  // ParseIntPipe
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }

  // ParseUUIDPipe with version
  @Get(':uuid')
  findByUuid(@Param('uuid', new ParseUUIDPipe({ version: '4' })) uuid: string) {}

  // ParseBoolPipe
  @Get()
  findAll(@Query('active', ParseBoolPipe) active: boolean) {}

  // DefaultValuePipe
  @Get()
  findPaginated(
    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
    @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
  ) {}

  // ParseArrayPipe
  @Get()
  findByIds(
    @Query('ids', new ParseArrayPipe({ items: Number, separator: ',' }))
    ids: number[],
  ) {}

  // ParseEnumPipe
  @Get()
  findByStatus(
    @Query('status', new ParseEnumPipe(UserStatus)) status: UserStatus,
  ) {}
}

Custom Validation Pipe

import {
  PipeTransform,
  Injectable,
  BadRequestException,
} from '@nestjs/common';

@Injectable()
export class ParseDatePipe implements PipeTransform<string, Date> {
  transform(value: string): Date {
    const date = new Date(value);

    if (isNaN(date.getTime())) {
      throw new BadRequestException(`Invalid date: ${value}`);
    }

    return date;
  }
}

// Usage
@Get()
findByDate(@Query('date', ParseDatePipe) date: Date) {}

Schema Validation Pipe (Zod)

import { z, ZodSchema } from 'zod';

@Injectable()
export class ZodValidationPipe implements PipeTransform {
  constructor(private schema: ZodSchema) {}

  transform(value: unknown) {
    const result = this.schema.safeParse(value);

    if (!result.success) {
      throw new BadRequestException({
        message: 'Validation failed',
        errors: result.error.format(),
      });
    }

    return result.data;
  }
}

// Usage
const createUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

@Post()
create(
  @Body(new ZodValidationPipe(createUserSchema))
  createUserDto: z.infer<typeof createUserSchema>,
) {}

Applying Pipes

// Parameter level
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {}

// Method level
@Post()
@UsePipes(ValidationPipe)
create(@Body() dto: CreateUserDto) {}

// Controller level
@Controller('users')
@UsePipes(new ValidationPipe({ transform: true }))
export class UsersController {}

// Global level (main.ts)
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }),
);

// Global with DI
@Module({
  providers: [
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({ whitelist: true }),
    },
  ],
})
export class AppModule {}

---

Exception Filters

Exception filters handle errors thrown during request processing.

Built-in HTTP Exceptions

import {
  BadRequestException,
  UnauthorizedException,
  ForbiddenException,
  NotFoundException,
  ConflictException,
  InternalServerErrorException,
  NotImplementedException,
  BadGatewayException,
  ServiceUnavailableException,
  GatewayTimeoutException,
} from '@nestjs/common';

// Throwing exceptions
throw new NotFoundException('User not found');
throw new BadRequestException('Invalid email format');
throw new UnauthorizedException();

// With custom response
throw new BadRequestException({
  message: 'Validation failed',
  errors: ['email is required', 'password must be at least 8 characters'],
});

Custom Exception Filter

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
  Logger,
} from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(HttpExceptionFilter.name);

  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    const status = exception.getStatus();
    const exceptionResponse = exception.getResponse();

    const error =
      typeof exceptionResponse === 'string'
        ? { message: exceptionResponse }
        : (exceptionResponse as object);

    const errorResponse = {
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      method: request.method,
      ...error,
    };

    this.logger.error(
      `${request.method} ${request.url} ${status}`,
      exception.stack,
    );

    response.status(status).json(errorResponse);
  }
}

Catch-All Exception Filter

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger(AllExceptionsFilter.name);

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();

    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    const message =
      exception instanceof HttpException
        ? exception.message
        : 'Internal server error';

    this.logger.error(
      `${request.method} ${request.url}`,
      exception instanceof Error ? exception.stack : 'Unknown error',
    );

    response.status(status).json({
      statusCode: status,
      message,
      timestamp: new Date().toISOString(),
      path: request.url,
    });
  }
}

Custom Exception Classes

export class BusinessException extends HttpException {
  constructor(
    public readonly code: string,
    message: string,
    status: HttpStatus = HttpStatus.BAD_REQUEST,
  ) {
    super({ code, message }, status);
  }
}

@Catch(BusinessException)
export class BusinessExceptionFilter implements ExceptionFilter {
  catch(exception: BusinessException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    response.status(exception.getStatus()).json({
      code: exception.code,
      message: exception.message,
      timestamp: new Date().toISOString(),
    });
  }
}

// Usage
throw new BusinessException('USER_EXISTS', 'User already exists');

Applying Exception Filters

// Method level
@Get(':id')
@UseFilters(HttpExceptionFilter)
findOne(@Param('id') id: string) {}

// Controller level
@Controller('users')
@UseFilters(new HttpExceptionFilter())
export class UsersController {}

// Global level (main.ts)
app.useGlobalFilters(new AllExceptionsFilter());

// Global with DI
@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: AllExceptionsFilter,
    },
  ],
})
export class AppModule {}

---

Execution Order

Understanding the exact order of execution is critical for debugging.

Global Binding Order

When multiple components are registered globally:

1. Filters - Execute in reverse order of registration (last registered = first executed) 2. Pipes - Execute in order of registration 3. Guards - Execute in order of registration 4. Interceptors - Execute in order of registration (before), reverse for after

Complete Request Flow

1. Incoming request
2. Globally bound middleware
3. Module-bound middleware
4. Global guards
5. Controller guards
6. Route guards
7. Global interceptors (before)
8. Controller interceptors (before)
9. Route interceptors (before)
10. Global pipes
11. Controller pipes
12. Route pipes
13. Route parameter pipes
14. Controller method (handler)
15. Route interceptors (after)
16. Controller interceptors (after)
17. Global interceptors (after)
18. Exception filters (if exception thrown)
    - Route filters
    - Controller filters
    - Global filters
19. Server response

Example: Multiple Components

// Global registration (main.ts)
app.useGlobalGuards(new Guard1(), new Guard2());
app.useGlobalInterceptors(new Interceptor1(), new Interceptor2());
app.useGlobalPipes(new Pipe1(), new Pipe2());
app.useGlobalFilters(new Filter1(), new Filter2());

// Controller
@Controller('users')
@UseGuards(Guard3)
@UseInterceptors(Interceptor3)
@UsePipes(Pipe3)
@UseFilters(Filter3)
export class UsersController {
  @Get(':id')
  @UseGuards(Guard4)
  @UseInterceptors(Interceptor4)
  @UsePipes(Pipe4)
  findOne(@Param('id', Pipe5) id: number) {}
}

// Execution order for GET /users/1:
// Guards: Guard1 → Guard2 → Guard3 → Guard4
// Interceptors (before): Interceptor1 → Interceptor2 → Interceptor3 → Interceptor4
// Pipes: Pipe1 → Pipe2 → Pipe3 → Pipe4 → Pipe5
// Handler
// Interceptors (after): Interceptor4 → Interceptor3 → Interceptor2 → Interceptor1
// Exception filters (if error): Filter3 → Filter2 → Filter1

Testing Patterns

Table of Contents

• Testing Module Setup
• Unit Testing Services
• Unit Testing Controllers
• E2E Testing
• Mocking Providers
• Database Testing

---

Testing Module Setup

The @nestjs/testing package provides utilities for creating isolated test modules.

Basic Setup

import { Test, TestingModule } from '@nestjs/testing';
import { UsersService } from './users.service';
import { UsersRepository } from './users.repository';

describe('UsersService', () => {
  let service: UsersService;
  let repository: UsersRepository;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UsersService,
        {
          provide: UsersRepository,
          useValue: {
            findAll: jest.fn(),
            findOne: jest.fn(),
            create: jest.fn(),
            update: jest.fn(),
            delete: jest.fn(),
          },
        },
      ],
    }).compile();

    service = module.get<UsersService>(UsersService);
    repository = module.get<UsersRepository>(UsersRepository);
  });

  it('should be defined', () => {
    expect(service).toBeDefined();
  });
});

Symptoms: Test Module Not Compiling

• "Nest can't resolve dependencies" error
• Undefined provider errors
• Circular dependency errors in tests

Fix

Ensure all dependencies are provided or mocked:

const module: TestingModule = await Test.createTestingModule({
  providers: [
    UsersService,
    // Mock all dependencies
    { provide: UsersRepository, useValue: mockRepository },
    { provide: ConfigService, useValue: mockConfigService },
    { provide: 'CACHE_MANAGER', useValue: mockCacheManager },
  ],
}).compile();

---

Unit Testing Services

Service with Repository

// users/users.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { NotFoundException } from '@nestjs/common';
import { getRepositoryToken } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UsersService } from './users.service';
import { User } from './entities/user.entity';

describe('UsersService', () => {
  let service: UsersService;
  let repository: Repository<User>;

  const mockUser: User = {
    id: '1',
    email: 'test@example.com',
    password: 'hashedPassword',
    name: 'Test User',
    role: 'user',
    isActive: true,
    posts: [],
    createdAt: new Date(),
    updatedAt: new Date(),
  };

  const mockRepository = {
    find: jest.fn(),
    findOne: jest.fn(),
    create: jest.fn(),
    save: jest.fn(),
    update: jest.fn(),
    delete: jest.fn(),
  };

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UsersService,
        {
          provide: getRepositoryToken(User),
          useValue: mockRepository,
        },
      ],
    }).compile();

    service = module.get<UsersService>(UsersService);
    repository = module.get<Repository<User>>(getRepositoryToken(User));

    // Reset mocks before each test
    jest.clearAllMocks();
  });

  describe('findAll', () => {
    it('should return an array of users', async () => {
      mockRepository.find.mockResolvedValue([mockUser]);

      const result = await service.findAll();

      expect(result).toEqual([mockUser]);
      expect(mockRepository.find).toHaveBeenCalledWith({
        relations: ['posts'],
        order: { createdAt: 'DESC' },
      });
    });
  });

  describe('findOne', () => {
    it('should return a user when found', async () => {
      mockRepository.findOne.mockResolvedValue(mockUser);

      const result = await service.findOne('1');

      expect(result).toEqual(mockUser);
      expect(mockRepository.findOne).toHaveBeenCalledWith({
        where: { id: '1' },
        relations: ['posts'],
      });
    });

    it('should throw NotFoundException when user not found', async () => {
      mockRepository.findOne.mockResolvedValue(null);

      await expect(service.findOne('999')).rejects.toThrow(NotFoundException);
    });
  });

  describe('create', () => {
    it('should create and return a user', async () => {
      const createUserDto = { email: 'new@example.com', password: 'password' };
      mockRepository.create.mockReturnValue(mockUser);
      mockRepository.save.mockResolvedValue(mockUser);

      const result = await service.create(createUserDto);

      expect(result).toEqual(mockUser);
      expect(mockRepository.create).toHaveBeenCalledWith(createUserDto);
      expect(mockRepository.save).toHaveBeenCalled();
    });
  });
});

Testing Async Methods

describe('async operations', () => {
  it('should handle async errors', async () => {
    mockRepository.findOne.mockRejectedValue(new Error('Database error'));

    await expect(service.findOne('1')).rejects.toThrow('Database error');
  });

  it('should handle concurrent operations', async () => {
    mockRepository.findOne.mockResolvedValue(mockUser);

    const results = await Promise.all([
      service.findOne('1'),
      service.findOne('2'),
      service.findOne('3'),
    ]);

    expect(mockRepository.findOne).toHaveBeenCalledTimes(3);
  });
});

---

Unit Testing Controllers

Controller with Service

// users/users.controller.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

describe('UsersController', () => {
  let controller: UsersController;
  let service: UsersService;

  const mockUser = {
    id: '1',
    email: 'test@example.com',
    name: 'Test User',
  };

  const mockUsersService = {
    findAll: jest.fn(),
    findOne: jest.fn(),
    create: jest.fn(),
    update: jest.fn(),
    remove: jest.fn(),
  };

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      controllers: [UsersController],
      providers: [
        {
          provide: UsersService,
          useValue: mockUsersService,
        },
      ],
    }).compile();

    controller = module.get<UsersController>(UsersController);
    service = module.get<UsersService>(UsersService);

    jest.clearAllMocks();
  });

  describe('findAll', () => {
    it('should return an array of users', async () => {
      mockUsersService.findAll.mockResolvedValue([mockUser]);

      const result = await controller.findAll();

      expect(result).toEqual([mockUser]);
      expect(service.findAll).toHaveBeenCalled();
    });
  });

  describe('create', () => {
    it('should create a user', async () => {
      const createUserDto: CreateUserDto = {
        email: 'new@example.com',
        password: 'password123',
      };
      mockUsersService.create.mockResolvedValue({ id: '2', ...createUserDto });

      const result = await controller.create(createUserDto);

      expect(result).toHaveProperty('id', '2');
      expect(service.create).toHaveBeenCalledWith(createUserDto);
    });
  });
});

Testing Guards on Controllers

describe('UsersController with guards', () => {
  let controller: UsersController;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      controllers: [UsersController],
      providers: [
        { provide: UsersService, useValue: mockUsersService },
      ],
    })
      .overrideGuard(JwtAuthGuard)
      .useValue({ canActivate: () => true })
      .overrideGuard(RolesGuard)
      .useValue({ canActivate: () => true })
      .compile();

    controller = module.get<UsersController>(UsersController);
  });

  it('should allow access when guards pass', async () => {
    mockUsersService.findAll.mockResolvedValue([mockUser]);

    const result = await controller.findAll();

    expect(result).toBeDefined();
  });
});

---

E2E Testing

Basic E2E Setup

// test/app.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication, ValidationPipe } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';

describe('AppController (e2e)', () => {
  let app: INestApplication;

  beforeAll(async () => {
    const moduleFixture: TestingModule = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();

    // Apply same pipes as in main.ts
    app.useGlobalPipes(
      new ValidationPipe({
        whitelist: true,
        forbidNonWhitelisted: true,
        transform: true,
      }),
    );

    await app.init();
  });

  afterAll(async () => {
    await app.close();
  });

  describe('/users (GET)', () => {
    it('should return users array', () => {
      return request(app.getHttpServer())
        .get('/users')
        .expect(200)
        .expect((res) => {
          expect(Array.isArray(res.body)).toBe(true);
        });
    });
  });

  describe('/users (POST)', () => {
    it('should create a user', () => {
      return request(app.getHttpServer())
        .post('/users')
        .send({
          email: 'test@example.com',
          password: 'password123',
        })
        .expect(201)
        .expect((res) => {
          expect(res.body).toHaveProperty('id');
          expect(res.body.email).toBe('test@example.com');
        });
    });

    it('should reject invalid email', () => {
      return request(app.getHttpServer())
        .post('/users')
        .send({
          email: 'invalid-email',
          password: 'password123',
        })
        .expect(400);
    });
  });
});

E2E with Authentication

describe('Auth E2E', () => {
  let app: INestApplication;
  let accessToken: string;

  beforeAll(async () => {
    // ... setup
  });

  describe('Authentication flow', () => {
    it('should register a new user', async () => {
      const response = await request(app.getHttpServer())
        .post('/auth/register')
        .send({
          email: 'newuser@example.com',
          password: 'password123',
        })
        .expect(201);

      expect(response.body).toHaveProperty('accessToken');
      accessToken = response.body.accessToken;
    });

    it('should login with credentials', async () => {
      const response = await request(app.getHttpServer())
        .post('/auth/login')
        .send({
          email: 'newuser@example.com',
          password: 'password123',
        })
        .expect(200);

      expect(response.body).toHaveProperty('accessToken');
      accessToken = response.body.accessToken;
    });

    it('should access protected route with token', async () => {
      return request(app.getHttpServer())
        .get('/users/profile')
        .set('Authorization', `Bearer ${accessToken}`)
        .expect(200);
    });

    it('should reject request without token', async () => {
      return request(app.getHttpServer())
        .get('/users/profile')
        .expect(401);
    });
  });
});

Symptoms: E2E Tests Sharing State

• Tests pass individually but fail when run together
• Data from previous tests affecting current test
• Flaky tests due to database state

Fix: Database Isolation

// test/test-utils.ts
import { PrismaService } from '../src/prisma/prisma.service';

export async function cleanDatabase(prisma: PrismaService) {
  // Delete in order to respect foreign keys
  await prisma.post.deleteMany();
  await prisma.user.deleteMany();
}

// In test file
describe('Users E2E', () => {
  let app: INestApplication;
  let prisma: PrismaService;

  beforeAll(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    prisma = app.get(PrismaService);
    await app.init();
  });

  beforeEach(async () => {
    await cleanDatabase(prisma);
  });

  afterAll(async () => {
    await cleanDatabase(prisma);
    await app.close();
  });
});

Using Transactions for Isolation

// test/test-utils.ts
export function withTransaction(
  prisma: PrismaService,
  fn: (tx: PrismaClient) => Promise<void>,
) {
  return async () => {
    await prisma.$transaction(async (tx) => {
      await fn(tx as any);
      throw new Error('ROLLBACK'); // Force rollback
    }).catch((e) => {
      if (e.message !== 'ROLLBACK') throw e;
    });
  };
}

---

Mocking Providers

Mock Factory

// test/mocks/users.service.mock.ts
export const mockUsersService = () => ({
  findAll: jest.fn(),
  findOne: jest.fn(),
  create: jest.fn(),
  update: jest.fn(),
  remove: jest.fn(),
});

export type MockUsersService = ReturnType<typeof mockUsersService>;

// Usage
const module = await Test.createTestingModule({
  providers: [
    {
      provide: UsersService,
      useFactory: mockUsersService,
    },
  ],
}).compile();

Override Provider

describe('with overridden provider', () => {
  let module: TestingModule;

  beforeEach(async () => {
    module = await Test.createTestingModule({
      imports: [UsersModule],
    })
      .overrideProvider(UsersService)
      .useValue({
        findAll: jest.fn().mockResolvedValue([]),
        findOne: jest.fn().mockResolvedValue(null),
      })
      .compile();
  });
});

Mocking External Services

// Mocking HttpService
const mockHttpService = {
  get: jest.fn(),
  post: jest.fn(),
  axiosRef: {
    get: jest.fn(),
    post: jest.fn(),
  },
};

const module = await Test.createTestingModule({
  providers: [
    ExternalApiService,
    {
      provide: HttpService,
      useValue: mockHttpService,
    },
  ],
}).compile();

// Test
it('should fetch external data', async () => {
  mockHttpService.get.mockReturnValue(
    of({ data: { result: 'success' } }),
  );

  const result = await service.fetchData();

  expect(result).toEqual({ result: 'success' });
});

Mocking ConfigService

const mockConfigService = {
  get: jest.fn((key: string) => {
    const config = {
      JWT_SECRET: 'test-secret',
      DATABASE_URL: 'postgresql://test:test@localhost/test',
      NODE_ENV: 'test',
    };
    return config[key];
  }),
};

const module = await Test.createTestingModule({
  providers: [
    AuthService,
    { provide: ConfigService, useValue: mockConfigService },
  ],
}).compile();

---

Database Testing

In-Memory Database (SQLite)

// test/test-database.module.ts
import { TypeOrmModule } from '@nestjs/typeorm';

export const TestDatabaseModule = TypeOrmModule.forRoot({
  type: 'sqlite',
  database: ':memory:',
  entities: [User, Post],
  synchronize: true,
  dropSchema: true,
});

// Usage
describe('UsersService Integration', () => {
  let module: TestingModule;
  let service: UsersService;

  beforeEach(async () => {
    module = await Test.createTestingModule({
      imports: [
        TestDatabaseModule,
        TypeOrmModule.forFeature([User]),
      ],
      providers: [UsersService],
    }).compile();

    service = module.get<UsersService>(UsersService);
  });

  afterEach(async () => {
    await module.close();
  });

  it('should create and retrieve a user', async () => {
    const created = await service.create({
      email: 'test@example.com',
      password: 'password',
    });

    const found = await service.findOne(created.id);

    expect(found.email).toBe('test@example.com');
  });
});

Test Containers (Docker)

// test/setup-test-db.ts
import { PostgreSqlContainer } from '@testcontainers/postgresql';

let container: StartedPostgreSqlContainer;

beforeAll(async () => {
  container = await new PostgreSqlContainer()
    .withDatabase('test_db')
    .withUsername('test')
    .withPassword('test')
    .start();

  process.env.DATABASE_URL = container.getConnectionUri();
}, 60000);

afterAll(async () => {
  await container.stop();
});

Symptoms: Test Database Connection Issues

• "Connection refused" errors
• Tests hanging on database operations
• "Too many connections" errors

Fix: Proper Connection Management

describe('Database Tests', () => {
  let app: INestApplication;
  let dataSource: DataSource;

  beforeAll(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    dataSource = app.get(DataSource);
    await app.init();
  });

  afterAll(async () => {
    // Close connections properly
    if (dataSource.isInitialized) {
      await dataSource.destroy();
    }
    await app.close();
  });

  beforeEach(async () => {
    // Use query runner for better control
    const queryRunner = dataSource.createQueryRunner();
    await queryRunner.connect();
    await queryRunner.startTransaction();

    // Store for cleanup
    (global as any).__QUERY_RUNNER__ = queryRunner;
  });

  afterEach(async () => {
    const queryRunner = (global as any).__QUERY_RUNNER__;
    if (queryRunner) {
      await queryRunner.rollbackTransaction();
      await queryRunner.release();
    }
  });
});

Repository Mock Helpers

// test/helpers/repository.mock.ts
export function createMockRepository<T>(): MockType<Repository<T>> {
  return {
    find: jest.fn(),
    findOne: jest.fn(),
    findOneBy: jest.fn(),
    save: jest.fn(),
    create: jest.fn(),
    update: jest.fn(),
    delete: jest.fn(),
    createQueryBuilder: jest.fn(() => ({
      where: jest.fn().mockReturnThis(),
      andWhere: jest.fn().mockReturnThis(),
      orderBy: jest.fn().mockReturnThis(),
      skip: jest.fn().mockReturnThis(),
      take: jest.fn().mockReturnThis(),
      getMany: jest.fn(),
      getOne: jest.fn(),
    })),
  };
}

type MockType<T> = {
  [P in keyof T]?: jest.Mock;
};