NestJS course ยท Module 8: Caching and Performance

Compression and Response Optimization - speeding up the Empire's messengers

8 min read ยท
In this lesson6

Commander of the legions! The endpoint with the list of legions sends two megabytes of JSON, including fields no client should ever see. Imagine the Empire's messengers carrying huge scrolls of parchment between provinces. A wise praetorian compresses the messages: instead of full chronicles he sends concise reports. In NestJS compression and response optimization are the same art - we shrink responses so they reach the client faster.

Compression Middleware - gzip/deflate compression

Compression is the simplest way to speed up HTTP responses. The compression middleware compresses responses on its own according to the client's Accept-Encoding header:

// main.ts - adding compression
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import compression from 'compression';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Enable compression (gzip, deflate and, since version 1.8, brotli)
  app.use(compression({
    filter: (req, res) => {
      // Do not compress responses with the x-no-compression header
      if (req.headers['x-no-compression']) {
        return false;
      }
      // Default filter - compress text/html, application/json, etc.
      return compression.filter(req, res);
    },
    threshold: 1024,  // Compress responses > 1KB
    level: 6,         // zlib compression level (0-9, default -1, i.e. 6)
  }));

  await app.listen(3000);
}

bootstrap();

The package supports deflate, gzip and, since version 1.8, also brotli: in a test a client accepting gzip, deflate, br got brotli. The middleware also adds the Vary: Accept-Encoding header. The zlib level is a number from 0 to 9, and the default -1 currently means 6. The NestJS documentation advises moving compression to a reverse proxy such as Nginx under heavy traffic.

Response Serialization with class-transformer

class-transformer lets you control which fields of an object leave in the response. It is like a censor of the Empire who decides what information may leave the walls of the Senate:

// legion.entity.ts
import { Exclude, Expose, Transform } from 'class-transformer';

export class LegionResponseDto {
  @Expose()
  id: number;

  @Expose()
  name: string;

  @Expose()
  province: string;

  // Hide internal data - do not send it outside the Empire's walls!
  @Exclude()
  internalCode: string;

  @Exclude()
  secretOrders: string;

  // Transformation - convert to a format citizens can read
  @Transform(({ value }) => Math.round(value), { toPlainOnly: true })
  @Expose()
  soldiers: number;

  @Transform(({ value }) => new Date(value).toLocaleDateString('pl-PL'), { toPlainOnly: true })
  @Expose()
  foundedAt: string;

  // Conditional hiding - show only if the user has the rank
  @Expose({ groups: ['admin', 'senator'] })
  budget: number;
}

@Exclude() hides a field, @Expose() shows it, and @Expose({ groups }) shows it only when the request has one of the groups. @Transform() changes a value, and { toPlainOnly: true } limits the change to sending. Without this option the transformation runs twice for objects coming from the database, and in the test the date turned into "Invalid Date".

ClassSerializerInterceptor

Serialization is performed by ClassSerializerInterceptor. We register it globally:

// app.module.ts - a global serialization interceptor
import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';
import { ClassSerializerInterceptor } from '@nestjs/common';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: ClassSerializerInterceptor,
    },
  ],
})
export class AppModule {}

Instead of the global registration you can put @UseInterceptors(ClassSerializerInterceptor) on a controller - one or the other, because together they serialize twice. Watch out for a catch: the interceptor works only on class instances. A plain object, e.g. from lean(), passes through untouched - in the test internalCode and secretOrders leaked. The type option helps:

// legion.controller.ts - usage in a controller
import { Controller, Get, SerializeOptions } from '@nestjs/common';
import { LegionResponseDto } from './legion.entity';
import { LegionService } from './legion.service';

@Controller('legions')
@SerializeOptions({ type: LegionResponseDto }) // plain objects become DTO instances
export class LegionController {
  constructor(private readonly legionService: LegionService) {}

  @Get()
  findAll(): Promise<LegionResponseDto[]> {
    // Fields with @Exclude() are removed from the response automatically
    return this.legionService.findAll();
  }

  @Get('admin')
  @SerializeOptions({ type: LegionResponseDto, groups: ['admin'] })
  findAllAdmin(): Promise<LegionResponseDto[]> {
    // Fields with @Expose({ groups: ['admin'] }) will be visible
    return this.legionService.findAll();
  }
}

@SerializeOptions({ type }) turns plain objects into DTO instances before serialization. Method options replace class options, which is why we repeat type next to groups.

Pagination - paging responses

Instead of sending all records at once, like the whole army down one road, we split the response into pages. The parameters arrive in the query as text, so a DTO validates them:

// pagination.dto.ts
import { Type } from 'class-transformer';
import { IsIn, IsInt, IsOptional, Max, Min } from 'class-validator';

export class PaginationDto {
  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  page?: number = 1;

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(100)
  limit?: number = 20;

  @IsOptional()
  @IsIn(['id', 'name', 'province'])
  sortBy?: string = 'id';

  @IsOptional()
  @IsIn(['ASC', 'DESC'])
  sortOrder?: 'ASC' | 'DESC' = 'ASC';
}

export class PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
}

@Type(() => Number) turns text into a number when the global ValidationPipe has transform: true. @Max(100) blocks limit=1000000, and @IsIn lets through only known sort fields - sorting by a hidden field, such as a password hash, would reveal its order.

The service fetches the page and the total number of records in parallel:

// legion.service.ts
import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model } from 'mongoose';

@Injectable()
export class LegionService {
  constructor(@InjectModel(Legion.name) private legionModel: Model<Legion>) {}

  async findPaginated(pagination: PaginationDto): Promise<PaginatedResponse<any>> {
    const { page, limit, sortBy, sortOrder } = pagination;
    const skip = (page - 1) * limit;

    // MongoDB with Mongoose
    const [data, total] = await Promise.all([
      this.legionModel
        .find()
        .sort({ [sortBy]: sortOrder === 'ASC' ? 1 : -1 })
        .skip(skip)
        .limit(limit)
        .lean()      // lean() returns a POJO instead of a Mongoose Document - faster!
        .exec(),
      this.legionModel.countDocuments(),
    ]);

    const totalPages = Math.ceil(total / limit);

    return {
      data,
      meta: {
        page,
        limit,
        total,
        totalPages,
        hasNextPage: page < totalPages,
        hasPreviousPage: page > 1,
      },
    };
  }
}

lean() returns plain objects, so the type option from the previous section comes in handy during serialization. On large collections countDocuments() can be slow, and skip slows down on distant pages - then the cursor from the optimization lesson helps.

Response Caching Headers

Cache headers let browsers and CDNs keep responses locally. An interceptor sets them on the way back:

// cache-headers.interceptor.ts
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from '@nestjs/common';
import { createHash } from 'node:crypto';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';
import { Response } from 'express';

@Injectable()
export class CacheHeadersInterceptor implements NestInterceptor {
  constructor(
    private readonly maxAge: number = 300, // 5 minutes by default
  ) {}

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const response = context.switchToHttp().getResponse<Response>();

    return next.handle().pipe(
      tap((body) => {
        // Cache-Control - how long a messenger may keep a copy
        response.setHeader(
          'Cache-Control',
          `public, max-age=${this.maxAge}, s-maxage=${this.maxAge * 2}`
        );

        // ETag - the resource version identifier, computed from the content
        // The browser sends it back in If-None-Match and gets 304 Not Modified
        response.setHeader('ETag', this.generateETag(body));
      }),
    );
  }

  private generateETag(body: unknown): string {
    // Same content = same ETag; W/ marks a weak ETag
    const hash = createHash('sha1').update(JSON.stringify(body)).digest('base64url');
    return `W/"${hash}"`;
  }
}

max-age applies to the browser, s-maxage to shared caches such as a CDN. Use public only for data shared by everyone; user data gets private. The first version computed the ETag from Date.now(), so it changed on every request and a 304 never happened. Express assigns a weak ETag and answers 304 by itself, so your own ETag makes sense when you can compute it more cheaply, e.g. from updatedAt.

The interceptor has a maxAge parameter, so we create it ourselves with new:

// Usage in a controller
@Controller('provinces')
export class ProvinceController {
  constructor(private readonly provinceService: ProvinceService) {}

  @Get()
  @UseInterceptors(new CacheHeadersInterceptor(600)) // 10 minutes of cache
  findAll() {
    return this.provinceService.findAll();
  }

  @Get(':id')
  @UseInterceptors(new CacheHeadersInterceptor(3600)) // 1 hour of cache
  findOne(@Param('id') id: string) {
    return this.provinceService.findOne(id);
  }
}

With @UseInterceptors(CacheHeadersInterceptor) NestJS would try to inject a number into the constructor. Cache headers are worth learning in this order: Cache-Control is the foundation, ETag adds a version identifier, Vary: Accept-Encoding separates copies in intermediate caches, and If-None-Match is sent by the browser when it asks again.

The @Exclude, @Expose and @Transform decorators - a summary

Three key decorators from class-transformer:

  • @Exclude() - hides a field from the response (like Caesar's secret order),
  • @Expose() - explicitly marks a field to be sent (like a public edict),
  • @Transform() - modifies a value before sending (like the Empire's interpreter).

A complete example combines all three:

// Complete example
import { Exclude, Expose, Transform } from 'class-transformer';

export class SoldierResponse {
  @Expose()
  id: number;

  @Expose()
  name: string;

  @Expose()
  rank: string;

  @Exclude()
  passwordHash: string;     // Never send the password!

  @Exclude()
  internalNotes: string;    // Internal notes

  @Transform(({ value }) => value > 1000 ? 'Veteranus' : 'Tiro', { toPlainOnly: true })
  @Expose()
  experienceLevel: string;  // Number -> text transformation

  @Transform(({ value }) => value?.toISOString(), { toPlainOnly: true })
  @Expose()
  enlistedAt: string;       // Date in ISO format
}

passwordHash disappears only when the serializer receives a class instance, though - with a plain object the password travels to the client. I recommend a rule: send out only DTOs, never raw entities. In the next lesson the messengers get queues.

Remember: a wise praetor does not send full chronicles when a concise report will do - and never attaches the secret orders to it.

Code for this lesson: src/compression-optimization.ts
// Compression i Response Optimization
import { Injectable } from '@nestjs/common';
import { Exclude, Expose, Transform } from 'class-transformer';

// ===========================================
// 1. Response DTO with serialization
// ===========================================

class LegionResponseDto {
  @Expose()
  id: number;

  @Expose()
  name: string;

  @Expose()
  province: string;

  // Hidden fields - don't send them beyond the walls of the Empire!
  @Exclude()
  internalCode: string;

  @Exclude()
  secretOrders: string;

  @Transform(({ value }) => Math.round(value))
  @Expose()
  soldiers: number;

  @Expose({ groups: ['admin'] })
  budget: number;
}

// ===========================================
// 2. Pagination pattern
// ===========================================

interface PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNextPage: boolean;
  };
}

@Injectable()
class PaginationService {
  paginate<T>(items: T[], page: number, limit: number): PaginatedResponse<T> {
    const total = items.length;
    const totalPages = Math.ceil(total / limit);
    const start = (page - 1) * limit;
    const data = items.slice(start, start + limit);

    return {
      data,
      meta: {
        page,
        limit,
        total,
        totalPages,
        hasNextPage: page < totalPages,
      },
    };
  }
}

// ===========================================
// 3. Demonstration
// ===========================================

const service = new PaginationService();
const legions = Array.from({ length: 50 }, (_, i) => ({
  id: i + 1,
  name: 'Legion ' + (i + 1),
  province: ['Gallia', 'Hispania', 'Britannia'][i % 3],
  soldiers: Math.floor(Math.random() * 5000) + 1000,
}));

const page1 = service.paginate(legions, 1, 10);
const page2 = service.paginate(legions, 2, 10);

console.log('=== Compression & Response Optimization ===');
console.log('Page 1:', page1.data.length, 'records');
console.log('Page 2:', page2.data.length, 'records');
console.log('Total:', page1.meta.total);
console.log('Pages:', page1.meta.totalPages);
console.log('');
console.log('@Exclude() - hides a field from the response');
console.log('@Expose() - explicitly marks a field');
console.log('@Transform() - modifies the value');
console.log('compression() - gzip/deflate middleware');
console.log('Cache-Control, ETag - HTTP cache headers');

Docs entries used in this lesson

Spotted a mistake in this lesson?

Useful articles