Interceptors & the Request Lifecycle

Introduction

Interceptors let you run logic both before and after a route handler, and even change what the handler returns. They are perfect for cross-cutting concerns such as measuring response time, wrapping every response in a standard envelope, or removing sensitive fields like passwords.

What is an Interceptor?

An interceptor implements NestInterceptor and its intercept(context, next) method. next.handle() calls the route handler and returns an RxJS Observable of its result. Code before next.handle() runs before the handler; RxJS operators piped onto the Observable run after it.

A Timing Interceptor

// src/common/interceptors/timing.interceptor.ts
import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable, tap } from 'rxjs';

@Injectable()
export class TimingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const handler = `${context.getClass().name}.${context.getHandler().name}`;
    const start = Date.now();

    return next
      .handle()
      .pipe(tap(() => console.log(`${handler} took ${Date.now() - start}ms`)));
  }
}

Notice the interceptor knows exactly which controller class and method ran — something middleware cannot tell you.

Transforming Responses

Many teams want every successful response in the same envelope. An interceptor with map() does this for the whole API at once:

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

export interface ApiResponse<T> {
  success: true;
  data: T;
}

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
  intercept(context: ExecutionContext, next: CallHandler<T>): Observable<ApiResponse<T>> {
    return next.handle().pipe(map((data) => ({ success: true, data })));
  }
}

Hiding Fields with Serialization

Returning a user object straight from the database risks leaking its password hash. Nest's built-in ClassSerializerInterceptor uses class-transformer to apply @Exclude() and @Expose() rules on the way out — as long as you return class instances, not plain objects:

// src/users/entities/user.entity.ts
import { Exclude } from 'class-transformer';

export class UserEntity {
  id: number;
  email: string;

  @Exclude()
  passwordHash: string;

  constructor(partial: Partial<UserEntity>) {
    Object.assign(this, partial);
  }
}

// src/users/users.controller.ts
@UseInterceptors(ClassSerializerInterceptor)
@Get(':id')
async findOne(@Param('id', ParseIntPipe) id: number) {
  return new UserEntity(await this.usersService.findOne(id));
}

Binding Interceptors

// route or controller level
@UseInterceptors(TimingInterceptor)

// globally, without DI (main.ts)
app.useGlobalInterceptors(new TimingInterceptor());

// globally, with DI (any module's providers)
{ provide: APP_INTERCEPTOR, useClass: TimingInterceptor }

The Full Request Lifecycle

You have now met every piece of Nest's request pipeline. Here is the order in which they run for a single request:

A quick way to remember it: middleware prepares the request, guards decide if it may continue, interceptors wrap the handler, pipes clean the arguments, the handler does the work, and filters catch anything that goes wrong along the way.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

You now know every stage of Nest's request pipeline and when to use each one. Next, you will make your application configurable across environments — development, testing and production — with @nestjs/config.