Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 42 ยท Building Real APIs

Caching, Throttling and Scheduling

Speed up and protect a NestJS API: CacheModule and cache-manager, ThrottlerGuard rate limits, and cron jobs with @nestjs/schedule, plus runnable stand-ins.

Three problems show up in almost every production API. Some answers are expensive to compute and rarely change, so you want to cache them. Some clients call too often, by accident or on purpose, so you want to throttle them. And some work has to happen on a clock rather than on a request, such as clearing expired sessions every night, so you want to schedule it.

Nest has an official answer to each: CacheModule (with cache-manager underneath), @nestjs/throttler, and @nestjs/schedule. This lesson shows how each is wired in and, more importantly, what each one does inside. The real packages need Node and npm, so those snippets are read-only. The runnable parts are small stand-ins with a fake clock, which makes time-based behavior (expiry, refill, schedules) fully deterministic.

Three tools, three problems

Cache Skip repeated expensive work.
Throttle Limit calls per client.
Schedule Run jobs on a clock.

All three are modules you import.

1 / 2

Caching with CacheModule

Install @nestjs/cache-manager and cache-manager, then register the module. Setting isGlobal makes the cache injectable everywhere:

TypeScript
import { CacheModule } from '@nestjs/cache-manager';

@Module({
  imports: [
    CacheModule.register({
      isGlobal: true,
      ttl: 30_000, // milliseconds in current cache-manager versions
    }),
  ],
})
export class AppModule {}

The TTL unit has changed between versions of cache-manager (seconds in older ones, milliseconds in newer ones), so check the version you install. With no store configured, the cache lives in the memory of one process.

There are two ways to use it. The first is manual: inject the cache and decide yourself what to store.

TypeScript
@Injectable()
export class ProductsService {
  constructor(
    @Inject(CACHE_MANAGER) private readonly cache: Cache,
    private readonly repo: ProductsRepository,
  ) {}

  async findOne(id: number) {
    const key = `product:${id}`;
    const cached = await this.cache.get<Product>(key);
    if (cached) {
      return cached;
    }
    const product = await this.repo.findOneOrFail(id);
    await this.cache.set(key, product, 60_000);
    return product;
  }

  async update(id: number, dto: UpdateProductDto) {
    const product = await this.repo.update(id, dto);
    await this.cache.del(`product:${id}`); // invalidate
    return product;
  }
}

This is the cache-aside pattern: look in the cache, fall back to the source, store the result. Note update deletes the key. Cache invalidation is the hard part of caching: every write path that changes the data must also clear or refresh the cached copy.

The second way is automatic, with CacheInterceptor (an interceptor that caches the responses of GET handlers):

TypeScript
@Controller('products')
@UseInterceptors(CacheInterceptor)
export class ProductsController {
  @Get()
  @CacheTTL(10_000)
  @CacheKey('all-products')
  findAll() {
    return this.products.findAll();
  }
}

By default the key is the request URL, so /products?page=2 and /products?page=3 are cached separately. Automatic caching is convenient for public, identical-for-everyone data. It is dangerous for anything that depends on the caller: if a response varies per user but the key is only the URL, one user can receive another user's data.

In-memory vs Redis

An in-memory cache is private to one process. If you run three copies of the app, each has its own cache, invalidation in one copy does not reach the others, and a restart empties it. For shared caches, plug a Redis store into cache-manager (for example through the @keyv/redis adapter, whose exact setup depends on the version you use). Then all instances see the same data and an invalidation is global.

The stand-in: a TTL cache

Here is a cache with expiry and the cache-aside helper. The clock is a plain number you move forward yourself.

JS A TTL cache with cache-aside

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Five calls cost three database reads. With a busy endpoint and a sensible TTL the saving is much larger, but notice the price: for up to one TTL, readers may see old data.

Throttling with @nestjs/throttler

Rate limiting protects your API from abuse, brute-force logins and runaway clients. Register the module with one or more limits and a global guard:

TypeScript
import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';

@Module({
  imports: [
    ThrottlerModule.forRoot([
      { name: 'short', ttl: 1000, limit: 5 },
      { name: 'long', ttl: 60_000, limit: 100 },
    ]),
  ],
  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
})
export class AppModule {}

This allows at most 5 requests per second and 100 per minute, per client (the default tracker is the client IP). A request over the limit gets 429 Too Many Requests. Override per route with decorators:

TypeScript
@Controller('auth')
export class AuthController {
  @Post('login')
  @Throttle({ short: { limit: 3, ttl: 60_000 } }) // stricter for login
  login() {}

  @Get('status')
  @SkipThrottle() // exempt, for example a health check
  status() {}
}

Two cautions. Behind a reverse proxy or CDN, every request may appear to come from the proxy's IP unless you configure the app to trust the proxy headers, which would put all users in one bucket. And the default storage is in memory per instance, so with several instances the effective limit multiplies; for a shared limit use a Redis-backed storage. Also see Security and Hardening.

The stand-in: a token bucket

The throttler package counts requests in time windows. A popular alternative algorithm, the token bucket, shows the same idea more visibly: a bucket holds up to N tokens, each request takes one, and tokens refill at a steady rate. Bursts are allowed up to the bucket size, then the sustained rate applies.

JS A token-bucket rate limiter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Alice burns her three tokens immediately and is refused the fourth, Bob has his own bucket, and after two seconds Alice has earned two tokens back. The retryAfter value is what a real server would send in the Retry-After header so well-behaved clients know when to come back.

Scheduling with @nestjs/schedule

Some work is driven by time. Install @nestjs/schedule, import ScheduleModule.forRoot() once, and decorate methods of any provider:

TypeScript
import { Cron, CronExpression, Interval, Timeout } from '@nestjs/schedule';

@Injectable()
export class CleanupService {
  private readonly logger = new Logger(CleanupService.name);

  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
  async removeExpiredSessions() {
    const removed = await this.sessions.deleteExpired();
    this.logger.log(`Removed ${removed} expired sessions`);
  }

  @Interval(60_000)
  heartbeat() {
    this.logger.debug('still alive');
  }

  @Timeout(5_000)
  warmUp() {
    this.logger.log('Warm-up finished 5 seconds after boot');
  }
}

@Cron takes a cron expression with five or six fields (a leading seconds field is supported). For example 0 30 3 * * 1 means 03:30:00 every Monday. @Interval(ms) repeats every N milliseconds and @Timeout(ms) runs once after a delay. Cron jobs accept a timeZone option, which matters when "midnight" has to mean a specific region.

Scheduling pitfalls

  • Every instance runs the job. With three copies of the app, a nightly cleanup runs three times. Either run scheduled work in one dedicated instance, or take a distributed lock (a Redis key, a database row) so only one copy proceeds. Idempotent jobs, which are safe to run twice, make this far less painful.
  • Overlapping runs. If a job takes longer than its interval, a second run may start before the first ends. Guard it with a flag or a lock.
  • Errors. An exception inside a job must not vanish. Catch and log it, or the problem stays invisible.
  • Heavy work blocks the event loop. For long or retryable work, enqueue a job to a worker instead of doing it in the scheduler callback. See Queues and Events.

The stand-in: a tiny scheduler

This scheduler supports every(ms) and after(ms) tasks on a fake clock that you advance manually. Real schedulers use timers; the logic of "which tasks are due now" is the same.

JS A tiny interval and timeout scheduler

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Over four simulated seconds the heartbeat fires four times, the warm-up fires once and disappears (it is a timeout, not an interval), and the cleanup fires once at 3 seconds. When two tasks are due at the same moment they run in the order they were registered.

Putting the three together

A common combination: cache a public, expensive list endpoint for 30 seconds, throttle everything globally with a stricter limit on login, and run a nightly job that deletes expired data and refreshes caches. Start simple, measure, and add a layer only when a real problem justifies it. A cache you cannot invalidate correctly is worse than no cache.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In the cache-aside pattern, what must a write operation do?

    Reads fill the cache, so any write that changes the data should delete or update the matching key, otherwise readers see old values until the TTL expires.
  2. 2. Why is an in-memory cache a problem when you run several instances of the app?

    An in-memory store belongs to a single process. A shared store such as Redis gives every instance the same view.
  3. 3. What status code does ThrottlerGuard send when a client exceeds the limit?

    429 is the standard response for rate limiting, often paired with a Retry-After header.
  4. 4. A @Cron job runs in an app deployed as three identical instances. What is the likely result?

    @nestjs/schedule has no built-in coordination between processes. Use a dedicated instance or a distributed lock.
  5. 5. What is the main risk of CacheInterceptor with a response that depends on the logged-in user?

    The default key is the URL. Without a key that includes the user, private data can leak across users.

Summary

  • CacheModule gives you a cache you use manually (cache-aside, with explicit invalidation) or automatically with CacheInterceptor for public GET routes.
  • An in-memory cache is per process; use Redis for a cache shared by several instances.
  • ThrottlerModule with ThrottlerGuard limits requests per client and answers 429; tighten sensitive routes with @Throttle and exempt others with @SkipThrottle.
  • Behind a proxy, make sure the real client IP is used, or everyone shares one limit.
  • @nestjs/schedule offers @Cron, @Interval and @Timeout; with multiple instances, coordinate so a job runs once.
  • Time-based logic is easy to test with a fake clock, as the stand-ins show.

Continue with Microservices and Transports to go beyond HTTP.