Caching

npm install @nestjs/cache-manager cache-manager

import { Module } from '@nestjs/common';
import { CacheModule } from '@nestjs/cache-manager';
import { BooksController } from './books.controller.js';
import { BooksRepository } from './books.repository.js';
import { BooksService } from './books.service.js';

@Module({
  imports: [CacheModule.register({ ttl: 10_000, isGlobal: true })],
  controllers: [BooksController],
  providers: [BooksRepository, BooksService],
  exports: [BooksService, BooksRepository],
})
export class BooksCachingModule {}

import { Injectable } from '@nestjs/common';

export interface Book {
  id: number;
  title: string;
  createdAt: Date;
}

/** Stands in for a TypeORM repository; `calls` counts "database" round trips. */
@Injectable()
export class BooksRepository {
  calls = 0;
  private readonly books = new Map<number, Book>([
    [1, { id: 1, title: 'Dune', createdAt: new Date('2026-01-01T00:00:00Z') }],
    [2, { id: 2, title: 'Emma', createdAt: new Date('2026-02-01T00:00:00Z') }],
  ]);

  async findAll(): Promise<Book[]> {
    this.calls++;
    return [...this.books.values()];
  }

  async findOne(id: number): Promise<Book | undefined> {
    this.calls++;
    return this.books.get(id);
  }

  async update(id: number, title: string): Promise<Book | undefined> {
    const book = this.books.get(id);
    if (book) {
      book.title = title;
    }
    return book;
  }

  async remove(id: number): Promise<void> {
    this.books.delete(id);
  }
}

import { Inject, Injectable } from '@nestjs/common';
import { Cache, CACHE_MANAGER } from '@nestjs/cache-manager';
import { Book, BooksRepository } from './books.repository.js';

const BOOK_TTL_MS = 30_000; // cache-manager TTLs are in milliseconds
const bookKey = (id: number) => `book:${id}`;
const LIST_KEY = 'books:list';

@Injectable()
export class BooksService {
  constructor(
    @Inject(CACHE_MANAGER) private readonly cache: Cache,
    private readonly books: BooksRepository,
  ) {}

  /** Cache-aside, written by hand. A miss is `undefined` (cache-manager 7). */
  async findOne(id: number): Promise<Book | undefined> {
    const cached = await this.cache.get<Book>(bookKey(id));
    if (cached !== undefined && cached !== null) {
      return cached;
    }
    const book = await this.books.findOne(id);
    if (book) {
      await this.cache.set(bookKey(id), book, BOOK_TTL_MS);
    }
    return book;
  }

  /** The same pattern with cache.wrap(): get, call the loader on a miss, set. */
  findOneWrapped(id: number): Promise<Book | undefined> {
    return this.cache.wrap(bookKey(id), () => this.books.findOne(id), BOOK_TTL_MS);
  }

  async findAll(): Promise<Book[]> {
    return this.cache.wrap(LIST_KEY, () => this.books.findAll(), BOOK_TTL_MS);
  }

  /** Write-through for the entity, invalidation for the derived list. */
  async rename(id: number, title: string): Promise<Book | undefined> {
    const book = await this.books.update(id, title);
    if (book) {
      await this.cache.set(bookKey(id), book, BOOK_TTL_MS);
    }
    await this.cache.del(LIST_KEY);
    return book;
  }

  /** Delete: invalidate both keys. */
  async remove(id: number): Promise<void> {
    await this.books.remove(id);
    await Promise.all([this.cache.del(bookKey(id)), this.cache.del(LIST_KEY)]);
  }
}

import { Injectable } from '@nestjs/common';
import { Cache } from '@nestjs/cache-manager';

@Injectable()
export class RecommendationsService {
  constructor(private readonly cache: Cache) {}
}

import { Body, Controller, Get, Param, ParseIntPipe, Patch, Post, UseInterceptors } from '@nestjs/common';
import { CacheInterceptor, CacheKey, CacheTTL } from '@nestjs/cache-manager';
import { BooksRepository } from './books.repository.js';
import { BooksService } from './books.service.js';

@Controller('books')
@UseInterceptors(CacheInterceptor) // caches every GET in this controller
@CacheTTL(5_000) // controller-level TTL, milliseconds
export class BooksController {
  constructor(
    private readonly books: BooksService,
    private readonly repo: BooksRepository,
  ) {}

  @Get()
  list() {
    return this.books.findAll();
  }

  @Get('featured')
  @CacheKey('books:featured') // fixed key instead of the URL
  @CacheTTL(60_000) // method-level TTL wins over the controller's
  featured() {
    return this.repo.findOne(1);
  }

  @Get('stable')
  @CacheTTL(0) // 0 stores the entry without expiry (docs: "never expires")
  stable() {
    return { at: Date.now() };
  }

  @Get(':id')
  one(@Param('id', ParseIntPipe) id: number) {
    return this.repo.findOne(id);
  }

  @Post()
  create(@Body() body: { title: string }) {
    return { created: body.title, at: Date.now() }; // POST is never cached by default
  }

  @Patch(':id')
  rename(@Param('id', ParseIntPipe) id: number, @Body() body: { title: string }) {
    return this.books.rename(id, body.title);
  }
}

curl -si localhost:3000/books | grep -i x-cache
curl -si localhost:3000/books | grep -i x-cache
curl -si "localhost:3000/books/1?x=1" | grep -i x-cache   # MISS
curl -si "localhost:3000/books/1?x=2" | grep -i x-cache   # MISS: another URL, another key
curl -si "localhost:3000/books/1?x=1" | grep -i x-cache   # HIT

X-Cache: MISS
X-Cache: HIT

import { Controller, Module, UseInterceptors } from '@nestjs/common';
import { CacheInterceptor, CacheKey, CacheModule, CacheTTL } from '@nestjs/cache-manager';
import { MessagePattern } from '@nestjs/microservices';
import { TransportCacheInterceptor } from './transport-cache.interceptor.js';
import { SubscribeMessage, WebSocketGateway } from '@nestjs/websockets';

let gatewayCalls = 0;
let rpcCalls = 0;

@WebSocketGateway()
export class BooksGateway {
  @CacheKey('events') // required: there is no URL to derive a key from
  @CacheTTL(5_000)
  @UseInterceptors(CacheInterceptor)
  @SubscribeMessage('events')
  handleEvent(): string[] {
    return [`call-${++gatewayCalls}`];
  }

  @CacheKey('events-fixed')
  @CacheTTL(5_000)
  @UseInterceptors(TransportCacheInterceptor)
  @SubscribeMessage('events-fixed')
  handleFixed(): string[] {
    return [`call-${++gatewayCalls}`];
  }
}

@Controller()
export class CatalogController {
  @CacheKey('catalog:count')
  @CacheTTL(5_000)
  @UseInterceptors(CacheInterceptor)
  @MessagePattern({ cmd: 'count' })
  count(): number {
    return ++rpcCalls;
  }

  @CacheKey('catalog:count-fixed')
  @CacheTTL(5_000)
  @UseInterceptors(TransportCacheInterceptor)
  @MessagePattern({ cmd: 'count-fixed' })
  countFixed(): number {
    return ++rpcCalls;
  }
}

@Module({ imports: [CacheModule.register()], providers: [BooksGateway] })
export class GatewayModule {}

@Module({ imports: [CacheModule.register()], controllers: [CatalogController] })
export class CatalogModule {}

import { ExecutionContext, Injectable } from '@nestjs/common';
import { CacheInterceptor } from '@nestjs/cache-manager';

/**
 * CacheInterceptor tries to set an X-Cache header through the HTTP adapter. In a
 * WebSocket or RPC handler there is no HTTP response, the call throws, the interceptor
 * swallows it and silently skips caching. Skipping the header outside HTTP fixes that.
 */
@Injectable()
export class TransportCacheInterceptor extends CacheInterceptor {
  protected override setHeadersWhenHttp(context: ExecutionContext, value: unknown): void {
    if (context.getType() === 'http') {
      super.setHeadersWhenHttp(context, value);
    }
  }
}