What are interceptors?

Question

Accepted Answer

**Interceptors** wrap the execution of a route handler, letting you run logic **before and after** it — and transform the request or response. They're inspired by aspect-oriented programming, ideal for cross-cutting concerns like logging, response transformation, caching, and timing.

## The structure: before + after via RxJS

```ts
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log("Before handler");          // runs BEFORE the route handler
    const now = Date.now();

return next.handle().pipe(               // next.handle() = invoke the handler
      tap(() => console.log(`After: ${Date.now() - now}ms`)),   // runs AFTER
    );
  }
}
```

An interceptor implements `intercept()`. Code before `next.handle()` runs **before** the handler; `next.handle()` returns an RxJS `Observable` of the response, and operators like `tap`/`map` let you act on the response **after** the handler completes.

## Transforming the response (a common use)

```ts
@Injectable()
export class TransformInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(
      map(data => ({ success: true, data, timestamp: new Date().toISOString() })),
      // wraps EVERY response in a consistent envelope: { success, data, timestamp }
    );
  }
}
```

Using `map`, an interceptor can reshape every response — e.g. wrapping all responses in a standard envelope, a very common pattern for consistent API responses.

## Other powerful uses

```ts
// caching — return a cached response, skipping the handler entirely
// timeout — fail requests taking too long
return next.handle().pipe(timeout(5000));

// error mapping — transform exceptions
return next.handle().pipe(catchError(err => throwError(() => new BadGatewayException())));

// excluding fields (serialization) — ClassSerializerInterceptor strips @Exclude() fields
```

```text
Common interceptor uses:
  ✓ Logging / timing requests (before + after)
  ✓ Transforming responses (consistent envelopes, field exclusion)
  ✓ Caching responses
  ✓ Adding timeouts
  ✓ Mapping/handling errors
```

## Applying interceptors

```ts
@UseInterceptors(LoggingInterceptor)   // method or controller level
app.useGlobalInterceptors(new TransformInterceptor());   // global
```

## Interceptors vs middleware vs guards

```text
Middleware  → runs BEFORE everything, with raw req/res (can't easily touch the response)
Guard       → AUTHORIZATION decision (allow/block) before the handler
Interceptor → wraps the handler — runs BEFORE and AFTER, can TRANSFORM the response
```

The defining feature: interceptors can run logic **after** the handler and **transform the response** — which middleware and guards cannot do cleanly.

## Why it matters

Interceptors are a powerful NestJS feature for handling **cross-cutting concerns** elegantly, and their distinguishing capability — running logic both before *and after* the handler, and transforming the response — makes them the right tool for needs that middleware and guards can't address.

Understanding them is important because many common requirements map naturally to interceptors: consistent response formatting (wrapping all responses in a standard `{ success, data }` envelope), logging/timing (measuring handler duration), caching (returning cached responses), timeouts, error transformation, and serialization (excluding sensitive fields).

Knowing the structure (the `next.handle()` Observable, with `tap`/`map`/`catchError` to act before/after), the common use cases, and especially **how interceptors differ from middleware and guards** (the ability to wrap and transform the response) is a key part of NestJS architectural competence.

Interceptors keep cross-cutting logic DRY and centralized rather than duplicated across handlers, making them a frequently-used, important tool for building clean, maintainable NestJS applications.