Guards, Interceptors, and Pipes

Relevant source files

• integration/hello-world/e2e/force-console.spec.ts
• packages/common/interfaces/http/http-server.interface.ts
• packages/common/interfaces/nest-application-context-options.interface.ts
• packages/core/adapters/http-adapter.ts
• packages/core/nest-application.ts
• packages/core/nest-factory.ts
• packages/core/test/utils/noop-adapter.spec.ts
• packages/microservices/exceptions/index.ts
• packages/microservices/exceptions/kafka-retriable-exception.ts
• packages/microservices/microservices-module.ts
• packages/microservices/nest-microservice.ts
• packages/platform-express/adapters/express-adapter.ts
• packages/platform-express/interfaces/nest-express-application.interface.ts
• packages/platform-express/interfaces/serve-static-options.interface.ts
• packages/platform-fastify/adapters/fastify-adapter.ts
• packages/platform-fastify/interfaces/nest-fastify-application.interface.ts
• packages/websockets/exceptions/index.ts
• sample/01-cats-app/package.json
• sample/11-swagger/package.json
• sample/19-auth-jwt/package.json
• sample/20-cache/package.json
• sample/21-serializer/package.json
• sample/25-dynamic-modules/package.json
• sample/26-queues/package.json
• sample/27-scheduling/package.json

Purpose and Scope

This document explains the three core request enhancement mechanisms in NestJS: Guards, Interceptors, and Pipes. These components form an Aspect-Oriented Programming (AOP) pipeline that processes requests before they reach route handlers and responses before they are sent to clients. Together, they enable cross-cutting concerns such as authorization, logging, caching, transformation, and validation.

For exception handling that wraps this pipeline, see Exception Handling. For middleware that executes before this pipeline, see Middleware Pipeline. For data validation patterns using class-validator, see Data Validation and Transformation.

Request Enhancement Pipeline Architecture

The Guards, Interceptors, and Pipes system forms a layered execution pipeline where each layer has a specific responsibility:

Sources: Diagram 5 from high-level architecture, packages/core/nest-application.ts396-448

The pipeline executes in a specific order:

1. Middleware - Platform-level request/response manipulation
2. Guards - Determine if request should proceed (authorization checks)
3. Interceptors (before) - Pre-process request, add AOP logic
4. Pipes - Transform and validate input data
5. Route Handler - Execute business logic
6. Interceptors (after) - Post-process response, transform output
7. Exception Filters - Handle any errors thrown during processing

Core Interfaces and Implementation

Guards: CanActivate Interface

Guards implement the CanActivate interface and determine whether a request should be processed by the route handler. They are primarily used for authentication and authorization logic:

Sources: packages/core/nest-application.ts438-448 packages/microservices/nest-microservice.ts237-253 packages/microservices/microservices-module.ts47-48

Guards are registered globally using useGlobalGuards():

Application Type	Registration Method	File Reference
HTTP Application	app.useGlobalGuards(...guards)	packages/core/nest-application.ts438-448
Microservice	app.useGlobalGuards(...guards)	packages/microservices/nest-microservice.ts237-253

The registration applies instance decorators if configured and tracks guards in the GraphInspector:

Sources: packages/core/nest-application.ts438-448 packages/microservices/nest-microservice.ts237-253

Interceptors: NestInterceptor Interface

Interceptors implement the NestInterceptor interface and provide AOP capabilities. They can execute logic both before and after the route handler using RxJS operators:

Sources: packages/core/nest-application.ts424-436 packages/microservices/nest-microservice.ts217-235 packages/microservices/microservices-module.ts49-50

Interceptors can:

• Transform the result returned from a function
• Transform exceptions thrown from a function
• Extend basic function behavior
• Completely override a function depending on specific conditions (e.g., caching)

The interceptor registration follows the same pattern as guards:

Sources: packages/core/nest-application.ts424-436 packages/microservices/nest-microservice.ts217-235

Pipes: PipeTransform Interface

Pipes implement the PipeTransform<any> interface and perform data transformation and validation:

Sources: packages/core/nest-application.ts410-422 packages/microservices/nest-microservice.ts192-210 packages/microservices/microservices-module.ts45-46

Pipes are commonly used with class-validator and class-transformer:

Package	Purpose	Sample Reference
class-validator	Validate DTOs using decorators	sample/01-cats-app/package.json26 sample/11-swagger/package.json27
class-transformer	Transform plain objects to class instances	sample/01-cats-app/package.json25 sample/11-swagger/package.json26

Sources: sample/01-cats-app/package.json25-26 sample/11-swagger/package.json26-27 sample/20-cache/package.json27-28

Global Registration Patterns

HTTP Applications

In HTTP applications, enhancers are registered through the NestApplication class:

Sources: packages/core/nest-application.ts396-448 packages/core/nest-factory.ts59-113

The registration process:

1. Applies instance decorators if configured via instrument.instanceDecorator option
2. Stores enhancers in ApplicationConfig
3. Tracks them in GraphInspector as orphaned enhancers with appropriate subtypes

Sources: packages/core/nest-application.ts488-496 packages/core/nest-application.ts396-448

Microservice Applications

Microservices support the same enhancer registration through NestMicroservice:

Sources: packages/microservices/nest-microservice.ts167-253 packages/microservices/microservices-module.ts31-66

The microservices context creates dedicated context creators and consumers for RPC pattern handlers:

• RpcContextCreator coordinates all enhancers
• ExceptionFiltersContext handles RPC exceptions
• Pipes, Guards, and Interceptors use the same consumer/creator pattern as HTTP

Sources: packages/microservices/microservices-module.ts38-51

Instance Decorator Pattern

Both HTTP and microservice applications support instance decoration, allowing instrumentation of all enhancer instances:

Configuration Option	Purpose	Application Point
instrument.instanceDecorator	Function to decorate instances	packages/core/nest-application.ts488-496
Applied to	Guards, Pipes, Interceptors, Filters	packages/core/nest-application.ts396-448

The decorator is applied during registration:

Sources: packages/core/nest-application.ts488-496 packages/microservices/nest-microservice.ts372-380

Integration with Application Context

Initialization Timing

The enhancers are configured during application initialization but warnings are logged if registration occurs after initialization:

Sources: packages/microservices/nest-microservice.ts167-234

In microservices specifically:

• Guards and Interceptors cannot be applied after initialization (warning logged)
• Pipes can be registered after initialization but warning indicates they won't be applied

Sources: packages/microservices/nest-microservice.ts167-234

HTTP Application Context

In HTTP applications, enhancers are registered during the initialization phase:

Sources: packages/core/nest-application.ts176-197

The initialization sequence:

1. applyOptions() - Apply CORS and other options
2. httpAdapter.init() - Initialize platform adapter
3. registerParserMiddleware() - Register body parsers
4. registerModules() - Register WebSocket and microservices modules
5. registerRouter() - Register middleware and routes
6. callInitHook() - Call OnModuleInit lifecycle hooks
7. registerRouterHooks() - Register exception handlers
8. callBootstrapHook() - Call OnApplicationBootstrap lifecycle hooks

Sources: packages/core/nest-application.ts176-216

Platform Adapter Integration

HTTP Server Hooks

Both Express and Fastify adapters support request/response hooks that integrate with the enhancer pipeline:

Adapter	Hook Methods	Implementation
ExpressAdapter	setOnRequestHook(), setOnResponseHook()	packages/platform-express/adapters/express-adapter.ts84-101
FastifyAdapter	setOnRequestHook(), setOnResponseHook()	packages/platform-fastify/adapters/fastify-adapter.ts284-302

Express Implementation:

The Express adapter registers hooks as middleware that wraps all requests:

Sources: packages/platform-express/adapters/express-adapter.ts67-82

Fastify Implementation:

The Fastify adapter uses Fastify's native hook system:

Sources: packages/platform-fastify/adapters/fastify-adapter.ts267-282

AbstractHttpAdapter Contract

The base AbstractHttpAdapter defines the hook interface:

Sources: packages/core/adapters/http-adapter.ts158-160

These hooks are placeholders in the abstract class, implemented by concrete adapters to provide platform-specific integration points for the enhancer pipeline.

Sources: packages/core/adapters/http-adapter.ts1-193

Execution Context and Dependency Injection

Context Creator Pattern

Each enhancer type has a dedicated context creator that handles dependency injection and metadata resolution:

Sources: packages/microservices/microservices-module.ts42-51

The context creators:

• Access the NestContainer for dependency resolution
• Read ApplicationConfig for global enhancer configuration
• Create instances with proper dependency injection
• Pass resolved instances to consumers for execution

Sources: packages/microservices/microservices-module.ts31-66

RPC Context Integration

For microservices, the RpcContextCreator coordinates all enhancers:

Sources: packages/microservices/microservices-module.ts42-51

This creates a unified pipeline for message pattern handlers similar to HTTP route handlers.

Sources: packages/microservices/microservices-module.ts18-19

Sample Application Usage

Several sample applications demonstrate Guards, Interceptors, and Pipes in practice:

Sample	Features Demonstrated	Dependencies
19-auth-jwt	Guards for JWT authentication	@nestjs/passport, @nestjs/jwt
20-cache	Interceptors for caching	@nestjs/cache-manager
01-cats-app	Pipes for validation	class-validator, class-transformer
11-swagger	DTO validation with pipes	class-validator, class-transformer, @nestjs/swagger

Sources: sample/19-auth-jwt/package.json1-69 sample/20-cache/package.json1-57 sample/01-cats-app/package.json1-71 sample/11-swagger/package.json1-54

Authentication Sample (19-auth-jwt)

Demonstrates guards for authentication and authorization using Passport strategies:

Sources: sample/19-auth-jwt/package.json25-26

Caching Sample (20-cache)

Demonstrates interceptors for caching responses using cache-manager:

Sources: sample/20-cache/package.json22-26

Validation Samples (01-cats-app, 11-swagger)

Demonstrate pipes for input validation and transformation using class-validator and class-transformer:

Sources: sample/01-cats-app/package.json25-26 sample/11-swagger/package.json26-27

Configuration and Options

Application Options

The application options interface supports enhancer configuration:

Sources: packages/common/interfaces/nest-application-context-options.interface.ts1-77

Key options affecting enhancers:

• preview - When true, providers/controllers are not instantiated, affecting enhancer execution
• instrument.instanceDecorator - Function to decorate all instances including enhancers
• abortOnError - Affects error handling in the enhancer pipeline

Sources: packages/common/interfaces/nest-application-context-options.interface.ts34-69

Initialization Preview Mode

When preview mode is enabled, the application skips certain initialization steps:

Sources: packages/microservices/nest-microservice.ts125-128

This mode is useful for introspecting application structure without fully initializing it, which affects how enhancers are registered and executed.

Sources: packages/core/nest-factory.ts209-211

Cross-Platform Compatibility

Guards, Interceptors, and Pipes work consistently across:

1. HTTP Applications (Express, Fastify)
2. Microservices (TCP, Redis, RabbitMQ, Kafka, NATS, MQTT, gRPC)
3. WebSocket Gateways (Socket.IO, WS)
4. Hybrid Applications (combinations of above)

The same interfaces and registration patterns apply regardless of transport:

Sources: packages/core/nest-application.ts396-448 packages/microservices/nest-microservice.ts167-253

This unified approach allows business logic in enhancers to remain transport-agnostic while the framework handles protocol-specific details through the respective context creators and consumers.

Sources: packages/microservices/microservices-module.ts1-122