perf(cache): add active GC sweep and maxSize eviction to TTLCache

Author: Animesh-86

lib/cache.test.ts

@@ -0,0 +1,101 @@
+// lib/cache.test.ts
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { TTLCache } from './cache';
+
+describe('TTLCache', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('basic get/set', () => {
+    it('returns null for a missing key', () => {
+      const cache = new TTLCache<string>();
+      expect(cache.get('missing')).toBeNull();
+      cache.destroy();
+    });
+
+    it('returns the value for a live key', () => {
+      const cache = new TTLCache<string>();
+      cache.set('user', 'octocat', 60_000);
+      expect(cache.get('user')).toBe('octocat');
+      cache.destroy();
+    });
+
+    it('returns null and evicts a key whose TTL has expired', () => {
+      vi.useFakeTimers();
+      const cache = new TTLCache<string>();
+      cache.set('user', 'octocat', 1_000);
+      vi.advanceTimersByTime(2_000);
+      expect(cache.get('user')).toBeNull();
+      cache.destroy();
+    });
+  });
+
+  describe('clear()', () => {
+    it('removes all entries', () => {
+      const cache = new TTLCache<number>();
+      cache.set('a', 1, 60_000);
+      cache.set('b', 2, 60_000);
+      cache.clear();
+      expect(cache.get('a')).toBeNull();
+      expect(cache.get('b')).toBeNull();
+      cache.destroy();
+    });
+  });
+
+  describe('capacity eviction (maxSize)', () => {
+    it('does not exceed maxSize — evicts the oldest key on overflow', () => {
+      const cache = new TTLCache<number>(3);
+      cache.set('a', 1, 60_000);
+      cache.set('b', 2, 60_000);
+      cache.set('c', 3, 60_000);
+      // Adding a 4th key should evict the oldest ('a')
+      cache.set('d', 4, 60_000);
+      expect(cache.get('a')).toBeNull(); // evicted
+      expect(cache.get('b')).toBe(2);
+      expect(cache.get('c')).toBe(3);
+      expect(cache.get('d')).toBe(4);
+      cache.destroy();
+    });
+
+    it('updating an existing key does not trigger eviction', () => {
+      const cache = new TTLCache<number>(2);
+      cache.set('a', 1, 60_000);
+      cache.set('b', 2, 60_000);
+      // Updating 'a' should NOT evict 'b' since size stays <= maxSize
+      cache.set('a', 99, 60_000);
+      expect(cache.get('a')).toBe(99);
+      expect(cache.get('b')).toBe(2);
+      cache.destroy();
+    });
+  });
+
+  describe('sweep() — active garbage collection', () => {
+    it('proactively removes expired keys on the next sweep interval', () => {
+      vi.useFakeTimers();
+      // 60s sweep interval (default)
+      const cache = new TTLCache<string>(1000, 60_000);
+      cache.set('stale', 'data', 1_000); // expires in 1s
+      // Advance past TTL but before sweep
+      vi.advanceTimersByTime(5_000);
+      // Advance past the sweep interval
+      vi.advanceTimersByTime(60_000);
+      // The key is gone even without a get() call
+      expect(cache.get('stale')).toBeNull();
+      cache.destroy();
+    });
+  });
+
+  describe('destroy()', () => {
+    it('clears the store and stops the interval', () => {
+      vi.useFakeTimers();
+      const clearIntervalSpy = vi.spyOn(globalThis, 'clearInterval');
+      const cache = new TTLCache<string>();
+      cache.set('x', 'y', 60_000);
+      cache.destroy();
+      expect(cache.get('x')).toBeNull();
+      expect(clearIntervalSpy).toHaveBeenCalled();
+      clearIntervalSpy.mockRestore();
+    });
+  });
+});

lib/cache.ts

@@ -5,6 +5,35 @@ type CacheItem<T> = {
 
 export class TTLCache<T> {
   private store = new Map<string, CacheItem<T>>();
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+  private readonly maxSize: number;
+
+  constructor(maxSize: number = 1000, cleanupIntervalMs: number = 60000) {
+    this.maxSize = Math.max(1, maxSize);
+    const interval = Math.max(1000, cleanupIntervalMs);
+
+    // Only run cleanup if we are in an environment that supports setInterval
+    if (typeof setInterval !== 'undefined') {
+      const timer = setInterval(() => this.sweep(), interval);
+
+      // Unref the timer so it doesn't prevent Node.js from exiting during tests or teardown
+      const nodeTimer = timer as unknown as { unref?: () => void };
+      if (nodeTimer && typeof nodeTimer.unref === 'function') {
+        nodeTimer.unref();
+      }
+
+      this.cleanupInterval = timer;
+    }
+  }
+
+  private sweep(): void {
+    const now = Date.now();
+    for (const [key, item] of this.store.entries()) {
+      if (now > item.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
 
   get(key: string): T | null {
     const hit = this.store.get(key);
@@ -19,10 +48,30 @@ export class TTLCache<T> {
   }
 
   set(key: string, value: T, ttlMs: number): void {
+    // Capacity eviction (FIFO / LRU-lite)
+    if (this.store.size >= this.maxSize && !this.store.has(key)) {
+      this.sweep(); // Remove expired entries first to free up capacity
+      if (this.store.size >= this.maxSize) {
+        // Find the oldest item (first inserted) and remove it
+        const oldestKey = this.store.keys().next().value;
+        if (oldestKey !== undefined) {
+          this.store.delete(oldestKey);
+        }
+      }
+    }
+
     this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
   }
 
   clear(): void {
     this.store.clear();
   }
+
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.clear();
+  }
 }