Interceptors in NestJS

This chapter follows Guards in NestJS.

Middleware and guards only see the request. Pipes only see one argument. An interceptor is the one stage that surrounds the handler call itself: it decides when the handler runs and receives its result as a stream it can change. That makes it the place for logging with timings, wrapping every response in the same envelope, timeouts, caching, and mapping errors from a library into HTTP exceptions.

The NestInterceptor contract

An interceptor implements NestInterceptor. Its intercept() method receives the ExecutionContext and a CallHandler. Calling next.handle() runs the rest of the pipeline (the pipes and the handler) and returns an RxJS Observable of the result. Code before next.handle() runs on the way in, and operators on the returned stream run on the way out.

1
import { CallHandler, ExecutionContext, Injectable, Logger, NestInterceptor } from '@nestjs/common';
2
import type { Request } from 'express';
3
import { Observable, tap } from 'rxjs';
4

5
@Injectable()
6
export class LoggingInterceptor implements NestInterceptor {
7
  private readonly logger = new Logger('HTTP');
8

9
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
10
    const { method, originalUrl } = context.switchToHttp().getRequest<Request>();
11
    const started = Date.now();
12

13
    return next.handle().pipe(
14
      tap(() => this.logger.log(`${method} ${originalUrl} ${Date.now() - started}ms`)),
15
    );
16
  }
17
}

The handler does not have to return an Observable for this to work. Nest wraps a plain value or a Promise in one before the interceptor sees it. If intercept() never calls next.handle(), the handler never runs, which is how a cache interceptor returns a stored response.

Changing the response

map() replaces the value the handler returned. A response envelope is the usual example:

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

4
@Injectable()
5
export class EnvelopeInterceptor<T> implements NestInterceptor<T, { data: T }> {
6
  intercept(context: ExecutionContext, next: CallHandler<T>): Observable<{ data: T }> {
7
    return next.handle().pipe(map((data) => ({ data })));
8
  }
9
}

Every route bound to this interceptor now answers { "data": ... }. A handler that injects @Res() without passthrough sends its own response, so its result never reaches map().

Timeouts and error mapping

Because the result is a stream, the RxJS error and time operators apply directly. This interceptor gives every request five seconds and turns the RxJS timeout into a 408:

1
import {
2
  CallHandler,
3
  ExecutionContext,
4
  Injectable,
5
  NestInterceptor,
6
  RequestTimeoutException,
7
} from '@nestjs/common';
8
import { catchError, Observable, throwError, timeout, TimeoutError } from 'rxjs';
9

10
@Injectable()
11
export class TimeoutInterceptor implements NestInterceptor {
12
  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
13
    return next.handle().pipe(
14
      timeout(5000),
15
      catchError((err) =>
16
        throwError(() => (err instanceof TimeoutError ? new RequestTimeoutException() : err)),
17
      ),
18
    );
19
  }
20
}

The timeout stops waiting, not the work. The handler’s database query keeps running in the background until it finishes. The same catchError shape maps library errors, for example a duplicate-key error from the database driver, to a ConflictException, although an exception filter is often the clearer place for that. If RxJS is new to you, Observables in JavaScript covers the model.

Binding interceptors

Interceptors bind like guards: @UseInterceptors() on a controller or a method, app.useGlobalInterceptors() in main.ts, or a provider with the APP_INTERCEPTOR token, which can inject dependencies.

1
import { APP_INTERCEPTOR } from '@nestjs/core';
2

3
@Module({
4
  providers: [
5
    { provide: APP_INTERCEPTOR, useClass: LoggingInterceptor },
6
    { provide: APP_INTERCEPTOR, useClass: TimeoutInterceptor },
7
  ],
8
})
9
export class AppModule {}

On the way in, global interceptors run before controller ones, and controller ones before route ones. On the way out the order reverses. The LoggingInterceptor registered first above is the outermost layer, so its timing includes the time spent in TimeoutInterceptor and in the handler.

Built-in interceptors

Nest ships two interceptors that cover common needs:

• ClassSerializerInterceptor from @nestjs/common runs the handler’s result through class-transformer. Properties decorated with @Exclude(), such as a password hash, are removed from the JSON. It only works when the handler returns class instances, not plain objects.
• CacheInterceptor from @nestjs/cache-manager caches GET responses by URL. @CacheTTL() sets the lifetime per route. It is only safe for responses that are the same for every caller, because the cache key does not include the user.

1
import { Exclude } from 'class-transformer';
2

3
export class UserEntity {
4
  id: string;
5
  email: string;
6

7
  @Exclude()
8
  passwordHash: string;
9

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

Next: Pipes and validation in NestJS.