feat: @CacheEvict에 debounceMs 옵션 추가

동일 키에 대한 캐시 무효화 요청이 짧은 시간 내에 집중될 때
debounceMs 창 내의 중복 요청을 하나로 병합하여 불필요한 evict를 방지

(cherry picked from commit 29c6c57)

Author: 77hdumat

README.ja.md

@@ -204,6 +204,10 @@ async clearAll() { ... }
 // メソッド実行前に削除
 @CacheEvict({ name: 'users', allEntries: true, beforeInvocation: true })
 async refreshUsers() { ... }
+
+// debounce削除 — 短時間に同一キーへの無効化リクエストが集中する場合に有効
+@CacheEvict({ name: 'reports', allEntries: true, debounceMs: 3000 })
+async onDataChanged() { ... }
 ```
 
 ### 組み合わせ使用
@@ -242,6 +246,7 @@ async getUser(id: string) { ... }
 | `allEntries` | `boolean` | `false` | ネームスペース全体を削除 |
 | `beforeInvocation` | `boolean` | `false` | メソッド実行前に削除 |
 | `condition` | `(...args) => boolean` | — | `false`なら削除をスキップ |
+| `debounceMs` | `number` | — | 指定した時間（ms）以内の同一キーへの重複削除リクエストを1回にまとめる |
 
 ---
 

README.ko.md

@@ -204,6 +204,10 @@ async clearAll() { ... }
 // 메서드 실행 전 삭제
 @CacheEvict({ name: 'users', allEntries: true, beforeInvocation: true })
 async refreshUsers() { ... }
+
+// debounce 삭제 — 짧은 시간 내 동일 키에 무효화 요청이 폭발적으로 들어올 때 유용
+@CacheEvict({ name: 'reports', allEntries: true, debounceMs: 3000 })
+async onDataChanged() { ... }
 ```
 
 ### 복합 사용
@@ -242,6 +246,7 @@ async getUser(id: string) { ... }
 | `allEntries` | `boolean` | `false` | 네임스페이스 전체 삭제 |
 | `beforeInvocation` | `boolean` | `false` | 메서드 실행 전 삭제 |
 | `condition` | `(...args) => boolean` | — | `false`면 삭제 건너뜀 |
+| `debounceMs` | `number` | — | 지정한 시간(ms) 내 동일 키에 대한 중복 삭제 요청을 하나로 병합 |
 
 ---
 

README.md

@@ -204,6 +204,10 @@ 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
@@ -242,6 +246,7 @@ async getUser(id: string) { ... }
 | `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 |
 
 ---
 

src/cachex/core/cache-evict-option.ts

@@ -57,4 +57,17 @@ export interface CacheEvictOption {
    * @default false
    */
   beforeInvocation?: boolean;
+
+  /**
+   * Debounce delay in milliseconds.
+   * Multiple evict calls targeting the same key(s) within this window
+   * are collapsed into a single eviction executed at the end of the window.
+   *
+   * Note: when used with `beforeInvocation: true`, the method runs immediately
+   * but the actual eviction is still deferred by `debounceMs`.
+   *
+   * @default undefined (disabled — eviction is immediate)
+   * @example debounceMs: 3000  // coalesce bursts within 3 seconds
+   */
+  debounceMs?: number;
 }

src/cachex/core/types.ts

@@ -23,6 +23,7 @@ export type CacheEvictContext = {
   keys: string[];
   cacheProvider: CacheProvider;
   allEntries?: boolean;
+  debounceMs?: number;
 };
 
 export type CacheKeyContext = {

src/cachex/support/__test__/cache-operations.spec.ts

@@ -257,6 +257,87 @@ describe('CacheOperations', () => {
       await cacheOperations.bulkEvict(context);
       expect(mockCacheProvider.evict).toHaveBeenCalledTimes(1);
     });
+
+    describe('debounceMs', () => {
+      beforeEach(() => jest.useFakeTimers());
+
+      it('should collapse multiple calls within the debounce window into one eviction', async () => {
+        const context: CacheEvictContext = {
+          keys: ['k1'],
+          cacheProvider: mockCacheProvider,
+          debounceMs: 100,
+        };
+
+        void cacheOperations.bulkEvict(context);
+        void cacheOperations.bulkEvict(context);
+        void cacheOperations.bulkEvict(context);
+
+        expect(mockCacheProvider.evict).not.toHaveBeenCalled();
+
+        jest.advanceTimersByTime(100);
+        await Promise.resolve(); // flush microtasks
+
+        expect(mockCacheProvider.evict).toHaveBeenCalledTimes(1);
+      });
+
+      it('should evict immediately when debounceMs is not set', async () => {
+        const context: CacheEvictContext = { keys: ['k1'], cacheProvider: mockCacheProvider };
+        await cacheOperations.bulkEvict(context);
+        expect(mockCacheProvider.evict).toHaveBeenCalledTimes(1);
+      });
+
+      it('should debounce independently for different key sets', async () => {
+        void cacheOperations.bulkEvict({
+          keys: ['k1'],
+          cacheProvider: mockCacheProvider,
+          debounceMs: 100,
+        });
+        void cacheOperations.bulkEvict({
+          keys: ['k2'],
+          cacheProvider: mockCacheProvider,
+          debounceMs: 100,
+        });
+
+        jest.advanceTimersByTime(100);
+        await Promise.resolve();
+
+        expect(mockCacheProvider.evict).toHaveBeenCalledTimes(2);
+      });
+
+      it('should reset the timer when called again within the window', async () => {
+        const context: CacheEvictContext = {
+          keys: ['k1'],
+          cacheProvider: mockCacheProvider,
+          debounceMs: 100,
+        };
+
+        void cacheOperations.bulkEvict(context);
+        jest.advanceTimersByTime(50);
+        void cacheOperations.bulkEvict(context); // resets timer
+
+        jest.advanceTimersByTime(50); // 100ms total elapsed, but timer was reset at 50ms
+        expect(mockCacheProvider.evict).not.toHaveBeenCalled();
+
+        jest.advanceTimersByTime(50); // 50ms after reset — timer fires now
+        await Promise.resolve();
+
+        expect(mockCacheProvider.evict).toHaveBeenCalledTimes(1);
+      });
+
+      it('should clear pending timers on module destroy without executing eviction', () => {
+        const context: CacheEvictContext = {
+          keys: ['k1'],
+          cacheProvider: mockCacheProvider,
+          debounceMs: 100,
+        };
+        void cacheOperations.bulkEvict(context);
+
+        cacheOperations.onModuleDestroy();
+        jest.advanceTimersByTime(200);
+
+        expect(mockCacheProvider.evict).not.toHaveBeenCalled();
+      });
+    });
   });
 
   it('should increase the wait time exponentially with each retry attempt', async () => {

src/cachex/support/cache-aspect-support.ts

@@ -57,6 +57,7 @@ export class CacheAspectSupport {
       keys,
       cacheProvider,
       allEntries: option.allEntries,
+      debounceMs: option.debounceMs,
     };
 
     if (option.beforeInvocation) {

src/cachex/support/cache-operations.ts

@@ -1,4 +1,4 @@
-import { Inject, Injectable, Logger } from '@nestjs/common';
+import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
 
 import type { CacheModuleConfig, CompressionConfig, SwrConfig } from '../core';
 import {
@@ -18,7 +18,7 @@ interface ResolvedSwrConfig {
 }
 
 @Injectable()
-export class CacheOperations {
+export class CacheOperations implements OnModuleDestroy {
   private readonly logger = new Logger(CacheOperations.name);
 
   private readonly globalSwrConfig: SwrConfig;
@@ -31,6 +31,9 @@ export class CacheOperations {
   /** In-process single-flight: collapses concurrent requests for the same key into one Promise. */
   private readonly inflightMap = new Map<string, Promise<unknown>>();
 
+  /** Pending debounce timers for @CacheEvict. Map key: NUL-joined cache keys. */
+  private readonly evictDebounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
   private readonly pubSubTimeoutMs: number;
 
   constructor(@Inject(CACHE_MODULE_CONFIG) config: CacheModuleConfig) {
@@ -69,17 +72,43 @@ export class CacheOperations {
   }
 
   async bulkEvict(context: CacheEvictContext): Promise<void> {
-    const { keys, cacheProvider, allEntries = false } = context;
+    const { keys, cacheProvider, allEntries = false, debounceMs } = context;
 
-    try {
-      if (allEntries) {
-        await this.deleteByPatterns(cacheProvider, keys);
-      } else {
-        await this.deleteByKeys(cacheProvider, keys);
+    const doEvict = async () => {
+      try {
+        if (allEntries) {
+          await this.deleteByPatterns(cacheProvider, keys);
+        } else {
+          await this.deleteByKeys(cacheProvider, keys);
+        }
+      } catch (error) {
+        this.logger.error('Cache eviction failed', error);
       }
-    } catch (error) {
-      this.logger.error('Cache eviction failed', error);
+    };
+
+    if (!debounceMs || debounceMs <= 0) {
+      return doEvict();
+    }
+
+    // NUL character cannot appear in Redis keys, so it is safe as a separator
+    const timerId = keys.join('\0');
+    const existing = this.evictDebounceTimers.get(timerId);
+    if (existing) clearTimeout(existing);
+
+    this.evictDebounceTimers.set(
+      timerId,
+      setTimeout(() => {
+        this.evictDebounceTimers.delete(timerId);
+        void doEvict();
+      }, debounceMs),
+    );
+  }
+
+  onModuleDestroy(): void {
+    for (const timer of this.evictDebounceTimers.values()) {
+      clearTimeout(timer);
     }
+    this.evictDebounceTimers.clear();
   }
 
   /**