typescript 60 lines · 7 steps

Wrapping responses in a NestJS interceptor

A NestJS interceptor that wraps every controller response in a consistent envelope with request metadata, while allowing opt-out per route.

Explained by highlit
NestJS Intermediate interceptors rxjs response-shaping metadata reflection
1import {
2 CallHandler,
3 ExecutionContext,
4 Injectable,
5 NestInterceptor,
6} from '@nestjs/common';
7import { Reflector } from '@nestjs/core';
8import { Request } from 'express';
9import { Observable } from 'rxjs';
10import { map } from 'rxjs/operators';
11import { randomUUID } from 'crypto';
12 
13export interface ResponseEnvelope<T> {
14 success: true;
15 data: T;
16 meta: {
17 requestId: string;
18 timestamp: string;
19 path: string;
20 };
21}
22 
23@Injectable()
24export class ResponseEnvelopeInterceptor<T>
25 implements NestInterceptor<T, ResponseEnvelope<T> | T>
26{
27 constructor(private readonly reflector: Reflector) {}
28 
29 intercept(
30 context: ExecutionContext,
31 next: CallHandler<T>,
32 ): Observable<ResponseEnvelope<T> | T> {
33 const skip = this.reflector.getAllAndOverride<boolean>('skipEnvelope', [
34 context.getHandler(),
35 context.getClass(),
36 ]);
37 
38 const request = context.switchToHttp().getRequest<Request>();
39 const requestId =
40 (request.headers['x-request-id'] as string) ?? randomUUID();
41 
42 return next.handle().pipe(
43 map((data) => {
44 if (skip) {
45 return data;
46 }
47 
48 return {
49 success: true,
50 data,
51 meta: {
52 requestId,
53 timestamp: new Date().toISOString(),
54 path: request.originalUrl,
55 },
56 } satisfies ResponseEnvelope<T>;
57 }),
58 );
59 }
60}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Interceptors let you transform every outgoing response in one place instead of repeating shape logic in each controller.
  2. 2The Reflector reads custom metadata so individual routes can opt out of cross-cutting behavior.
  3. 3Operating on the RxJS stream from next.handle() means the transform runs after the handler resolves its value.

Related explainers

typescript 
type RetryOptions = {
  retries?: number;
  timeoutMs?: number;
  baseDelayMs?: number;

Retry with timeout and backoff in TypeScript

promises retry exponential-backoff
Intermediate 10 steps
typescript 
import { Pipe, PipeTransform, ChangeDetectorRef, NgZone, OnDestroy } from '@angular/core';
 
@Pipe({
  name: 'timeAgo',

A self-refreshing timeAgo pipe in Angular

impure-pipe change-detection timers
Advanced 10 steps
typescript 
const DIVISIONS: { amount: number; unit: Intl.RelativeTimeFormatUnit }[] = [
  { amount: 60, unit: "seconds" },
  { amount: 60, unit: "minutes" },
  { amount: 24, unit: "hours" },

Human-readable relative times with Intl

internationalization date-formatting lookup-table
Intermediate 7 steps
typescript 
import { Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { HttpClient } from '@angular/common/http';
import { AsyncPipe } from '@angular/common';

Reactive type-ahead search in Angular

rxjs reactive-forms debounce
Intermediate 9 steps
typescript 
function throttle<T extends (...args: any[]) => void>(
  fn: T,
  limit: number
): (...args: Parameters<T>) => void {

Building a trailing-edge throttle in TypeScript

throttling closures generics
Intermediate 7 steps
typescript 
interface TokenBucketOptions {
  capacity: number;
  refillPerSecond: number;
}

How a token bucket rate limiter works

rate-limiting token-bucket lazy-evaluation
Intermediate 7 steps

Share this explainer

Here's the card — post it anywhere.

Wrapping responses in a NestJS interceptor — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code