NestJS course Β· Module 8: Caching and Performance

Caching - supply lockers in an application

6 min read Β·
In this lesson7

The list of provinces changes once a quarter. The request for it arrives a thousand times a minute - and each time the database does the same work to return the same result. The server is loaded not because it does a lot, but because it keeps doing the same thing.

A legion did not send a runner to Rome for every loaf of bread. It kept a supply locker by the camp: what was needed often lay to hand, and for the rest one went down to the depot. A cache is such a locker - the temporary storage of data for faster access.

Note the word "temporary". A cache is not permanent storage - the database is for that. Nor is it a compression tool or a logging tool. The data in it is meant to disappear, and that is a feature, not a fault.

Configuration

CacheModule.register() configures the cache along with its parameters - not routing, not authorisation, not logging:

@Module({
  imports: [
    CacheModule.register({
      isGlobal: true,
      ttl: 300000,
      max: 1000,
    }),
  ],
})
export class AppModule {}

ttl (Time To Live) means an entry's maximum lifetime, after which it is removed automatically - 300,000 ms here, five minutes (the current @nestjs/cache-manager takes TTL in milliseconds). It is not a number of permitted reads nor a response time; it is an expiry date.

max caps the number of entries. Once exceeded, the cache drops the least recently used - because memory is finite, and a cache without a limit will exhaust it sooner or later.

Manual read and write

We inject the cache by token. The written order: @Inject(CACHE_MANAGER), private cache:, Cache:

@Injectable()
export class ProvinceService {
  constructor(
    @Inject(CACHE_MANAGER) private cache: Cache,
    private repo: ProvinceRepository,
  ) {}

  async findAll() {
    const cached = await this.cache.get<Province[]>('provinces:all');
    if (cached) {
      return cached;
    }

    const provinces = await this.repo.findAll();
    await this.cache.set('provinces:all', provinces, 600000);

    return provinces;
  }
}

This pattern is called cache-aside (or lazy loading) and means the code fetches from the cache manually and writes to it manually. Four steps, always in this order:

  1. Check the cache (get).
  2. If there is an entry - return it to the client.
  3. If not (a miss) - fetch from the database.
  4. Store the result in the cache (set) and return it.

The name "lazy" comes from step three: the cache fills lazily, only once somebody asks for the data. The first request always goes to the database.

Automatically, through decorators

For ordinary reads you need not write those four steps:

@Controller('provinces')
export class ProvinceController {
  @Get()
  @UseInterceptors(CacheInterceptor)
  @CacheKey('provinces:all')
  @CacheTTL(600000)
  findAll() {
    return this.provinceService.findAll();
  }
}

@UseInterceptors(CacheInterceptor) automatically caches the endpoint's responses - it does not compress, log or validate them.

@CacheTTL(600000) is the decorator responsible for the lifetime of this method's data - 600,000 milliseconds, ten minutes, regardless of the default. Do not confuse it with @CacheKey, which gives the entry a name, nor with @UseInterceptors, which merely switches caching on.

By default the key comes from the URL. @CacheKey is useful when you want to set it yourself - for instance so you can later remove that same entry from a service.

Writing - two strategies

The approaches above fill the cache on a read. You can also fill it on a write, and here two variants differ by a single word:

  • Write-through writes to the cache and the database synchronously - the application waits for both. The cache is never stale, but a write takes longer.
  • Write-behind writes to the cache immediately and to the database asynchronously, later. The write is instant, but a failure between the two can lose the data.

The difference comes down to whether the application waits for the database. Choose write-through where losing a write is unacceptable; write-behind where throughput matters and one lost entry is no disaster - as with view counters.

Invalidation - three strategies

Data in a cache grows stale. The ways of dealing with that run from simplest to most elaborate:

  1. Expiration (TTL) - the entry disappears by itself after a while. You write nothing, but you show stale data for a moment.
  2. Manual - you remove a specific key when the data changes. Precise, but you must remember every place that writes.
  3. Pattern-based - you remove groups of keys matching a pattern, say everything beginning with provinces:. The most powerful, and the easiest to remove too much with.

The invalidation process after an update has three steps: update the data in the database, identify and remove the relevant keys, and the next request fetches fresh data and stores it anew.

Warming the cache

With cache-aside the first user after every restart pays the full price of a database read. You can prevent that by filling the locker before anyone asks:

@Injectable()
export class CacheWarmupService implements OnModuleInit {
  constructor(
    @Inject(CACHE_MANAGER) private cache: Cache,
    private repo: ProvinceRepository,
  ) {}

  async onModuleInit() {
    const provinces = await this.repo.findAll();
    await this.cache.set('provinces:all', provinces, 3600000);
  }
}

onModuleInit is a method NestJS calls at application startup, once the module is built. The process has three stages: identify the critical data, fetch and store it at startup, adjust the list based on what actually gets queried most.

Warm only what is both frequently needed and rarely changed. Warming everything lengthens startup and fills memory with data nobody will reach for.

Summary

The locker by the camp works, and for the rest one goes to the depot:

  • a cache is the temporary storage of data for faster access - not permanent storage, not compression, not logging,
  • CacheModule.register() configures the cache with its parameters; max caps the number of entries,
  • TTL means an entry's maximum lifetime, after which it is removed automatically,
  • injection in order: @Inject(CACHE_MANAGER), private cache:, Cache,
  • cache-aside means fetching and writing manually; four steps: check the cache β†’ return on a hit β†’ fetch from the database on a miss β†’ store and return,
  • @UseInterceptors(CacheInterceptor) automatically caches the endpoint's responses,
  • @CacheTTL(600000) sets the lifetime; @CacheKey names the entry, @UseInterceptors switches the mechanism on,
  • write-through writes to the database synchronously, write-behind asynchronously, risking loss on a failure,
  • invalidation strategies from simplest: expiration (TTL) β†’ manual (one key) β†’ pattern-based (groups of keys),
  • the process after an update: update the database β†’ identify and remove the keys β†’ the next request fetches fresh data,
  • cache warming through onModuleInit: identify the critical data β†’ fetch and store at startup β†’ adjust the list.

In the next lesson we will move the locker outside the process - into Redis, so that every application instance sees it. For now remember: a cache does not speed work up, it lets you not do it - and the whole difficulty lies in knowing when the supplies have gone stale.

Code for this lesson: src/caching-intro.ts
// Caching - Supply Vaults in the Roman Empire
import { Injectable, Inject, Module } from '@nestjs/common';
import { CACHE_MANAGER } from '@nestjs/cache-manager';
import { CacheModule } from '@nestjs/cache-manager';
import { Cache } from 'cache-manager';

// 1. CacheModule configuration in NestJS
@Module({
  imports: [
    CacheModule.register({
      ttl: 300,      // Time To Live: 300 seconds (5 minutes)
      max: 100,      // Maximum 100 elements in cache
      isGlobal: true // Available globally across the whole app
    }),
  ],
})
export class AppModule {}

// 2. Service with caching
@Injectable()
export class TributeCacheService {
  constructor(
    @Inject(CACHE_MANAGER) private cacheManager: Cache
  ) {}

  // GET - Fetch from cache or from the database
  async getTribute(id: number) {
    const cacheKey = `tribute:${id}`;

    // Check cache
    let tribute = await this.cacheManager.get(cacheKey);
    if (tribute) {
      console.log('CACHE HIT - data from the vault!');
      return tribute;
    }

    // CACHE MISS - fetch from the database
    console.log('CACHE MISS - going to the archive...');
    tribute = await this.fetchFromDatabase(id);

    // Save to cache for 5 minutes
    if (tribute) {
      await this.cacheManager.set(cacheKey, tribute, 300000);
    }
    return tribute;
  }

  // SET - Save to cache
  async cacheTribute(id: number, data: any, ttl = 300000) {
    const key = `tribute:${id}`;
    await this.cacheManager.set(key, data, ttl);
    console.log(`Tribute ${id} saved in the vault for ${ttl/1000}s`);
  }

  // DELETE - Remove from cache (invalidation)
  async invalidate(id: number) {
    await this.cacheManager.del(`tribute:${id}`);
    console.log(`Tribute ${id} removed from the vault`);
  }

  // CLEAR - Clear the entire cache
  async clearAll() {
    await this.cacheManager.reset();
    console.log('All caches cleared!');
  }

  private async fetchFromDatabase(id: number) {
    // Simulating database query
    const tributes: Record<number, any> = {
      1: { id: 1, province: 'Gallia', amount: 1000, type: 'gold' },
      2: { id: 2, province: 'Aegyptus', amount: 2000, type: 'silver' },
    };
    return tributes[id] || null;
  }
}

// Caching patterns:
// - Cache-Aside (Lazy): check cache -> if missing -> fetch -> save
// - Write-Through: Save to DB and cache simultaneously
// - Write-Behind: Save to cache, later sync with DB
// - Cache Warming: Pre-fill the cache upfront with popular data

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. Cache in a NestJS application is:

  2. 2. CacheModule.register() in NestJS configures:

These are 2 of 8 questions for this lesson. Solve the rest in the game.

Hands-on tasks in the game

  • Code editor

    Build a cache service with get and set methods for tributes

  • Click in order

    Arrange the CACHE_MANAGER injection into a service:

  • Vertical ordering

    Arrange the steps of the Cache-Aside (Lazy Loading) pattern:

  • Code editor

    Apply CacheInterceptor and CacheTTL on the GET /provinces endpoint

  • Click in order

    Arrange the cache invalidation process after a data update:

  • Code editor

    Write an update method that clears the appropriate cache key after data changes

  • Vertical ordering

    Arrange invalidation strategies from simplest to most complex:

  • Click in order

    Arrange the cache warming process (pre-loading cache on startup):

  1. QuestionWhat Is Cache in an Application
  2. QuestionCacheModule in NestJS
  3. Coding taskPractice: Basic Cache Service
  4. QuestionTTL Parameter in Cache
  5. Click in orderInjecting CACHE_MANAGER
  6. Put in orderCache-Aside Pattern
  7. QuestionCacheInterceptor in NestJS
  8. Question@CacheTTL Decorator
  9. Coding taskPractice: CacheInterceptor on a Controller
  10. QuestionCache Decorators on a Controller
  11. Click in orderCache Invalidation
  12. QuestionCache-Aside Pattern
  13. QuestionWrite-Through vs Write-Behind
  14. Coding taskPractice: Cache Invalidation
  15. Put in orderCache Invalidation Process
  16. Click in orderCache Warmer Service

Useful articles