Interceptors

Guards decide before a handler runs; filters act after one throws. Between them is a gap: code that runs around a handler on the way in and on the way out, with access to what the handler returned. That is an interceptor. It is the tool for concerns that wrap handlers: timing and logging, response envelopes, mapping errors, caching, timeouts. It knows the handler, like a guard, and it sees the result, which nothing else in the pipeline does.

The interface

@Injectable()
export class TimingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const started = Date.now();
    return next.handle().pipe(tap(() => console.log(`took ${Date.now() - started}ms`)));
  }
}

intercept() receives two things. The ExecutionContext is the one from lesson 8, so context.getClass() and context.getHandler() name the controller and the method, and context.switchToHttp().getResponse() reaches the response, on which setHeader(name, value) adds a header before the body goes out. next.handle() calls the handler and returns its result as a stream.

Nothing runs until you call next.handle(). An interceptor that never calls it never runs the handler, which is how a cache interceptor answers from memory: it returns of(cachedValue) instead.

The stream

next.handle() returns an RxJS Observable. You do not need to know RxJS for this lesson; one idea is enough. An Observable is a value that will arrive later, like a Promise, except that it can be transformed with operators through .pipe(), and each operator describes what to do with the value when it comes:

• tap(fn) runs fn with the value and passes the value on unchanged. Logging, timing, metrics.
• map(fn) replaces the value with whatever fn returns. Envelopes, renaming, stripping fields.
• catchError(fn) runs when the handler threw, and can replace the error with another or with a value.
• timeout(ms) fails the stream if the handler takes too long.

Here is the docs' interceptor that replaces null results with an empty string:

return next.handle().pipe(map((value) => (value === null ? '' : value)));

map receives exactly what the handler returned and its return value becomes the response body. The status code is untouched. Two things a map never sees: a thrown exception, because an error is not a value on the stream, so error responses keep their shape unless catchError handles them; and handlers that write the response themselves through @Res(), because there is no return value to map.

Binding

@UseInterceptors(TimingInterceptor) on a handler or on a controller class; app.useGlobalInterceptors(new TimingInterceptor()) in main.ts for everything; the APP_INTERCEPTOR token for a global interceptor that needs dependencies. Several interceptors nest: the first one bound runs first on the way in and last on the way out.

Where it sits

Interceptors run after guards and before pipes on the way in, then again after the handler on the way out, before the response is sent. A guard's refusal never reaches an interceptor. A handler's exception passes through catchError, if there is one, on its way to the exceptions layer.

Your task

The starter has two interceptors, both incomplete.

1. LoggingInterceptor already times the handler. Make it also name the handler in an x-handler response header, as ClassName#method, for instance CatsController#findAll, and bind it to CatsController.
2. TransformInterceptor should wrap whatever a handler returns in an envelope, { data: ... }. Bind it to the whole application.

The tests check the envelope on successes, the header on every response, and that a 404 keeps Nest's error body while still carrying the header, because the interceptor ran before the handler threw.

When it fails

• The header is missing: it is set after next.handle() resolved, when the response has already gone. Set it before returning the stream.
• The header reads CatsController#: getHandler().name is empty because the method lost its name; in this editor that does not happen, but it is what a minifier does to unnamed functions.
• The 404 body is { "data": ... }: something turned the error into a value. map should not; catchError returning a value would.
• Bodies are not wrapped: TransformInterceptor is not bound globally, or map returns data itself instead of an object containing it.

Remember

• An interceptor wraps the handler: code before next.handle() runs on the way in, operators on the stream run on the way out.
• tap observes, map replaces, catchError handles errors, timeout bounds.
• Errors are not values on the stream; map never sees them.
• The ExecutionContext names the class and the handler, and reaches the response for headers.