English | 한국어 | 日本語

nestjs-cachex

A decorator-based caching module for NestJS.

SWR, Single-flight, msgpack + zstd, and multi-level cache — all in one package.

Introduction

Most caching modules work well as long as the cache is alive. The moment TTL expires, every subsequent request hits the DB or external API directly, and under load, this leads to Cache Stampede.

nestjs-cachex solves this at the root.

• SWR — Even after TTL expires, the stale data is returned immediately while the cache is refreshed in the background.
• Single-flight — A Redis distributed lock and Pub/Sub ensure that only one refresh runs per key, even across multiple instances.
• Multi-level cache — L1 (in-memory) and L2 (Redis) in a layered structure, eliminating unnecessary network overhead.

| Feature | @nestjs/cache-manager | nestjs-cachex | |---|---|---| | SWR | ✗ | ✓ | | Single-flight | ✗ | ✓ | | Distributed lock | ✗ | ✓ | | msgpack serialization | ✗ | ✓ | | zstd compression | ✗ | ✓ | | Multi-level cache | ✗ | ✓ |

Quick Start

import { Cacheable, CacheEvict } from 'nestjs-cachex';

@Injectable()
export class UserService {
  @Cacheable({ ttl: 60, name: 'users', key: (id: string) => id })
  async findUser(id: string) {
    return this.userRepository.findOne(id);
  }

  @CacheEvict({ name: 'users', key: (id: string) => id })
  async updateUser(id: string, data: UpdateUserDto) {
    return this.userRepository.update(id, data);
  }
}

Features

• Decorator-based — Separate caching logic from business code entirely with @Cacheable and @CacheEvict
• SWR — Instant response even on cache expiry. Revalidation happens in the background
• Single-flight — Distributed lock + Pub/Sub guarantees a single refresh per key, even across instances
• Jitter — Random TTL offset prevents synchronized expiration and Cache Stampede
• msgpack — Binary serialization instead of JSON — smaller payload, faster throughput
• zstd compression — Data exceeding the threshold is compressed automatically
• Multi-level cache — L1 hit skips Redis entirely. L1 miss falls through to L2 with Write-back
• Dynamic keys — Generate keys from a static string or a function per request
• Conditional caching — Fine-grained control with condition and unless
• Full TypeScript support — Type inference on all options

Requirements

• Node.js 18+
• NestJS 9+
• Redis 6+ (optional, for Redis / Multi-level cache)

Installation

npm install nestjs-cachex
# or
yarn add nestjs-cachex
# or
pnpm add nestjs-cachex

If you're using Redis, install ioredis as well.

npm install ioredis
# or
yarn add ioredis
# or
pnpm add ioredis

Usage

Module Registration

Static registration

import { CacheXModule, CacheManager } from 'nestjs-cachex';

@Module({
  imports: [
    CacheXModule.forRoot({
      defaults: {
        ttl: 300,
        cacheManager: CacheManager.REDIS,
      },
    }),
  ],
})
export class AppModule {}

Async registration

CacheXModule.forRootAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  redisToken: REDIS_CLIENT,
  subscriberToken: REDIS_SUBSCRIBER,
  useFactory: async (config: ConfigService) => ({
    defaults: {
      ttl: config.get('CACHE_TTL'),
      cacheManager: CacheManager.REDIS,
    },
    swr: {
      enabled: true,
      defaultStaleMultiplier: 5, // ttl × 5 when staleTtl is not set
      pubSubTimeoutMs: 2000,
    },
    compression: {
      enabled: true,
      threshold: 20 * 1024, // compress only if >= 20KB
      level: 3,
    },
  }),
})

Redis client setup

Pub/Sub requires a dedicated connection. Make sure to inject it separately from the main connection.

export const REDIS_CLIENT = 'REDIS_CLIENT';
export const REDIS_SUBSCRIBER = 'REDIS_SUBSCRIBER';

@Module({
  providers: [
    { provide: REDIS_CLIENT, useFactory: () => new Redis({ host: 'localhost', port: 6379 }) },
    { provide: REDIS_SUBSCRIBER, useFactory: () => new Redis({ host: 'localhost', port: 6379 }) },
  ],
  exports: [REDIS_CLIENT, REDIS_SUBSCRIBER],
})
export class RedisModule {}

@Cacheable

// SWR pattern
@Cacheable({
  ttl: 10,       // fresh for 10s
  staleTtl: 290, // serve stale for 290s + background refresh
  name: 'dashboard',
  key: (userId: string) => userId,
})
async getDashboard(userId: string) { ... }

// Conditional caching
@Cacheable({
  ttl: 60,
  name: 'items',
  condition: (id: string) => id !== 'guest', // skip cache if false
  unless: (result) => result === null,        // skip storing if true
})
async findItem(id: string) { ... }

// Multi-level cache
@Cacheable({ ttl: 60, name: 'hot-data', cacheManager: CacheManager.MULTI })
async getHotData(id: string) { ... }

@CacheEvict

// Evict a specific entry
@CacheEvict({ name: 'users', key: (id: string) => id })
async updateUser(id: string, data: UpdateUserDto) { ... }

// Evict entire namespace
@CacheEvict({ name: 'users', allEntries: true })
async deleteAllUsers() { ... }

// Evict multiple namespaces
@CacheEvict({ name: ['users', 'profiles', 'sessions'], allEntries: true })
async clearAll() { ... }

// Evict before method execution
@CacheEvict({ name: 'users', allEntries: true, beforeInvocation: true })
async refreshUsers() { ... }

// Debounce eviction — useful when the same key may be invalidated many times in quick succession
@CacheEvict({ name: 'reports', allEntries: true, debounceMs: 3000 })
async onDataChanged() { ... }

Combined usage

@Cacheable({ ttl: 60, name: 'user-detail', key: (id: string) => id })
@CacheEvict({ name: 'user-list', allEntries: true })
async getUser(id: string) { ... }

API

@Cacheable

| Option | Type | Default | Description | |--------|------|---------|-------------| | ttl | number | defaults.ttl | Cache TTL in seconds | | staleTtl | number | ttl × staleMultiplier | Stale window after TTL expires (seconds) | | swr | boolean | module config | SWR enabled override | | name | string \| (...args) => string | auto-generated | Cache namespace | | key | string \| (...args) => string | auto-hash | Cache key | | cacheManager | CacheManager | REDIS | REDIS | MEMORY | MULTI | | condition | (...args) => boolean | — | Skip cache lookup/store if false | | unless | (result, ...args) => boolean | — | Skip storing if true | | compression | boolean \| { threshold?, level? } | module config | Compression override |

@CacheEvict

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string \| string[] \| (...args) => string \| string[] | auto-generated | Namespace(s) to evict | | key | string \| (...args) => string | auto-hash | Key to evict. Ignored if allEntries: true | | cacheManager | CacheManager | REDIS | Target backend | | allEntries | boolean | false | Evict entire namespace | | beforeInvocation | boolean | false | Evict before method execution | | condition | (...args) => boolean | — | Skip eviction if false | | debounceMs | number | — | Collapse bursts: multiple evictions for the same key within this window (ms) are merged into one |

How It Works

SWR + Single-flight

Request
   │
   ├─[Fresh]───────────────────────────────────────────► Return immediately
   │
   ├─[Stale]───► Return stale data immediately
   │              └─ Background:
   │                  tryLock ──[OK]──► fetch → store → Pub/Sub notify
   │                           └[fail]─ skip (another instance is handling it)
   │
   └─[Miss]────► tryLock ──[OK]──► fetch → store ──────────────────► Return
                           └[fail]─ Pub/Sub wait
                                      ├─[notified]──► get cache ───► Return
                                      └─[timeout]───► polling (exp. backoff)
                                                        └─[max retries]─► direct fetch

Cache Key Format

{name}::{key}          cache data
lock:{name}::{key}     distributed lock
pending:{name}::{key}  Pub/Sub channel

License

MIT