NestJS Cacheable

Advanced caching decorators for NestJS applications with support for TTL, conditional caching, stale-while-revalidate, and more.

Features

• 🚀 Simple Integration - Easy-to-use decorators for caching method results
• ⚡ Performance Optimized - Reduce database queries and API calls
• 🎯 Conditional Caching - Cache based on custom conditions
• 🔄 Stale-While-Revalidate - Serve stale content while refreshing in background
• 🗑️ Cache Eviction - Clear cache entries programmatically
• 📊 Event Callbacks - Monitor cache hits, misses, and errors
• 🔧 Customizable - Configure TTL, cache keys, and serialization
• 🌐 Multiple Stores - Support for Redis, Memory, and other cache stores

Installation

# Using pnpm (recommended)
pnpm add nest-cacheable

# Using npm
npm install nest-cacheable

# Using yarn
yarn add nest-cacheable

Quick Start

1. Import CacheModule

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

@Module({
  imports: [
    CacheModule.register({
      ttl: 300, // seconds
      max: 100, // maximum number of items in cache
    }),
  ],
})
export class AppModule {}

2. Use Cacheable Decorator

import { Injectable } from '@nestjs/common';
import { Cacheable, Time } from 'nest-cacheable';

@Injectable()
export class UserService {
  @Cacheable({
    ttl: 5 * Time.MINUTE,
    cacheKey: (userId) => `user:${userId}`,
  })
  async getUser(userId: string) {
    // This expensive operation will be cached
    return await this.database.findUser(userId);
  }
}

Decorators

@Cacheable

Cache method results with advanced options:

@Cacheable({
  // Cache expiration time in seconds
  ttl: 60,

  // Custom cache key
  cacheKey: (id) => `product:${id}`,

  // Conditional caching
  cacheIf: (id) => id !== 'admin',

  // Event callbacks
  onHit: (key) => console.log(`Cache hit: ${key}`),
  onMiss: (key) => console.log(`Cache miss: ${key}`),
  onError: (error) => console.error(`Cache error: ${error}`),

  // Stale-while-revalidate
  staleWhileRevalidate: 30,
  backgroundRefetch: true,

  // Background refresh interval
  refetchInterval: 60,

  // Custom serialization
  serialize: (data) => JSON.stringify(data),
  deserialize: (cached) => JSON.parse(cached),
})
async getProduct(id: string) {
  return await this.productRepository.findOne(id);
}

@CacheEvict

Clear cache entries:

@CacheEvict({
  // Cache key to evict
  cacheKey: (id) => `product:${id}`,

  // Clear before method execution
  beforeInvocation: false,

  // Clear all cache entries
  all: false,

  // Exact key match or pattern
  exact: true,
})
async updateProduct(id: string, data: UpdateProductDto) {
  return await this.productRepository.update(id, data);
}

Advanced Usage

Time Utilities

import { Time } from 'nest-cacheable';

@Cacheable({
  ttl: 2 * Time.HOUR,  // 2 hours
  // or
  ttl: 30 * Time.MINUTE,  // 30 minutes
  // or
  ttl: 7 * Time.DAY,  // 7 days
})

Multiple Cache Keys

@Cacheable({
  cacheKey: (userId, filters) => [
    `user:${userId}`,
    `filters:${JSON.stringify(filters)}`,
  ],
})
async getUserData(userId: string, filters: any) {
  // Method implementation
}

Conditional Caching

@Cacheable({
  cacheIf: async (userId) => {
    // Only cache for non-admin users
    const user = await this.getUser(userId);
    return user.role !== 'admin';
  },
})
async getSensitiveData(userId: string) {
  // Method implementation
}

Stale-While-Revalidate Pattern

@Cacheable({
  ttl: 60,  // Cache for 60 seconds
  staleWhileRevalidate: 30,  // Serve stale for 30 more seconds
  backgroundRefetch: true,  // Refresh in background
})
async getFrequentlyAccessedData() {
  // Method implementation
}

Cache Eviction Patterns

// Clear specific cache entry
@CacheEvict({
  cacheKey: (id) => `item:${id}`,
})
async deleteItem(id: string) {
  // Method implementation
}

// Clear all cache entries
@CacheEvict({
  all: true,
})
async clearAllCache() {
  // Method implementation
}

// Clear before method execution
@CacheEvict({
  cacheKey: (id) => `item:${id}`,
  beforeInvocation: true,
})
async updateItem(id: string, data: any) {
  // Method implementation
}

Redis Configuration

For production use, Redis is recommended:

import { Module } from '@nestjs/common';
import { CacheModule } from '@nestjs/cache-manager';
import { redisStore } from 'cache-manager-redis-store';

@Module({
  imports: [
    CacheModule.register({
      store: redisStore,
      host: 'localhost',
      port: 6379,
      ttl: 600,
    }),
  ],
})
export class AppModule {}

Best Practices

1. Choose appropriate TTL values - Consider data freshness requirements
2. Use meaningful cache keys - Include all parameters that affect the result
3. Monitor cache performance - Use event callbacks to track hit rates
4. Handle errors gracefully - Implement onError callbacks
5. Clear cache strategically - Use @CacheEvict after data modifications

API Reference

CacheableOptions

Option	Type	Description
ttl	number	Cache expiration time in seconds
cacheKey	string | string[] | Function	Custom cache key definition
cacheIf	Function	Condition to determine if caching should be applied
serialize	Function	Custom serialization function
deserialize	Function	Custom deserialization function
staleWhileRevalidate	number	Time to serve stale content while refreshing
backgroundRefetch	boolean	Enable background refresh
refetchInterval	number	Background refresh interval in seconds
onError	Function	Error callback
onSuccess	Function	Success callback
onHit	Function	Cache hit callback
onMiss	Function	Cache miss callback

CacheEvictOptions

Option	Type	Description
cacheKey	string | string[] | Function	Cache key(s) to evict
exact	boolean	Use exact key match or pattern
beforeInvocation	boolean	Clear cache before method execution
all	boolean	Clear all cache entries

Examples

Check the examples/ directory for complete working examples:

• Basic caching
• Redis integration
• Conditional caching
• Cache eviction patterns
• Stale-while-revalidate

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.