@aitytech/agentkits-memory 1.0.0 → 2.0.0

package/src/__tests__/cache-manager.test.ts

@@ -0,0 +1,499 @@
+/**
+ * Tests for CacheManager
+ *
+ * Tests LRU cache functionality, TTL expiration, memory pressure handling,
+ * and cache statistics.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { CacheManager, TieredCacheManager } from '../cache-manager.js';
+
+describe('CacheManager', () => {
+  let cache: CacheManager<string>;
+
+  beforeEach(() => {
+    cache = new CacheManager<string>({
+      maxSize: 100,
+      ttl: 60000, // 1 minute
+    });
+  });
+
+  afterEach(() => {
+    cache.shutdown();
+  });
+
+  describe('basic operations', () => {
+    it('should set and get values', () => {
+      cache.set('key1', 'value1');
+      expect(cache.get('key1')).toBe('value1');
+    });
+
+    it('should return null for missing keys', () => {
+      expect(cache.get('nonexistent')).toBeNull();
+    });
+
+    it('should delete values', () => {
+      cache.set('key1', 'value1');
+      expect(cache.delete('key1')).toBe(true);
+      expect(cache.get('key1')).toBeNull();
+    });
+
+    it('should return false when deleting nonexistent key', () => {
+      expect(cache.delete('nonexistent')).toBe(false);
+    });
+
+    it('should check if key exists', () => {
+      cache.set('key1', 'value1');
+      expect(cache.has('key1')).toBe(true);
+      expect(cache.has('nonexistent')).toBe(false);
+    });
+
+    it('should clear all entries', () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+      cache.clear();
+      expect(cache.size).toBe(0);
+      expect(cache.get('key1')).toBeNull();
+    });
+
+    it('should return all keys', () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+      const keys = cache.keys();
+      expect(keys).toContain('key1');
+      expect(keys).toContain('key2');
+    });
+
+    it('should update existing entries', () => {
+      cache.set('key1', 'value1');
+      cache.set('key1', 'value2');
+      expect(cache.get('key1')).toBe('value2');
+      expect(cache.size).toBe(1);
+    });
+  });
+
+  describe('LRU eviction', () => {
+    it('should evict least recently used when at capacity', () => {
+      const smallCache = new CacheManager<string>({ maxSize: 3, ttl: 60000 });
+
+      smallCache.set('key1', 'value1');
+      smallCache.set('key2', 'value2');
+      smallCache.set('key3', 'value3');
+
+      // Access key1 to make it recently used
+      smallCache.get('key1');
+
+      // Add new entry, should evict key2 (LRU)
+      smallCache.set('key4', 'value4');
+
+      expect(smallCache.get('key1')).toBe('value1');
+      expect(smallCache.get('key2')).toBeNull(); // Evicted
+      expect(smallCache.get('key3')).toBe('value3');
+      expect(smallCache.get('key4')).toBe('value4');
+
+      smallCache.shutdown();
+    });
+
+    it('should move accessed items to front of LRU', () => {
+      const smallCache = new CacheManager<string>({ maxSize: 3, ttl: 60000 });
+
+      smallCache.set('key1', 'value1');
+      smallCache.set('key2', 'value2');
+      smallCache.set('key3', 'value3');
+
+      // Access key1 multiple times
+      smallCache.get('key1');
+      smallCache.get('key1');
+
+      // Add two new entries
+      smallCache.set('key4', 'value4');
+      smallCache.set('key5', 'value5');
+
+      // key1 should still exist, key2 and key3 should be evicted
+      expect(smallCache.get('key1')).toBe('value1');
+      expect(smallCache.has('key2')).toBe(false);
+      expect(smallCache.has('key3')).toBe(false);
+
+      smallCache.shutdown();
+    });
+  });
+
+  describe('TTL expiration', () => {
+    it('should expire entries after TTL', async () => {
+      const shortTtlCache = new CacheManager<string>({
+        maxSize: 100,
+        ttl: 50, // 50ms TTL
+      });
+
+      shortTtlCache.set('key1', 'value1');
+      expect(shortTtlCache.get('key1')).toBe('value1');
+
+      // Wait for expiration
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(shortTtlCache.get('key1')).toBeNull();
+
+      shortTtlCache.shutdown();
+    });
+
+    it('should respect custom TTL per entry', async () => {
+      cache.set('short', 'value1', 50); // 50ms TTL
+      cache.set('long', 'value2', 5000); // 5s TTL
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(cache.get('short')).toBeNull(); // Expired
+      expect(cache.get('long')).toBe('value2'); // Still valid
+    });
+
+    it('should not return expired entries via has()', async () => {
+      const shortTtlCache = new CacheManager<string>({
+        maxSize: 100,
+        ttl: 50,
+      });
+
+      shortTtlCache.set('key1', 'value1');
+      expect(shortTtlCache.has('key1')).toBe(true);
+
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      expect(shortTtlCache.has('key1')).toBe(false);
+
+      shortTtlCache.shutdown();
+    });
+  });
+
+  describe('memory pressure', () => {
+    it('should evict when memory limit exceeded', () => {
+      const memoryCache = new CacheManager<string>({
+        maxSize: 1000,
+        maxMemory: 100, // Very small memory limit
+        ttl: 60000,
+      });
+
+      // Add entries until memory is exceeded
+      for (let i = 0; i < 10; i++) {
+        memoryCache.set(`key${i}`, 'a'.repeat(20)); // Each ~40 bytes
+      }
+
+      // Should have evicted some entries
+      expect(memoryCache.size).toBeLessThan(10);
+
+      memoryCache.shutdown();
+    });
+  });
+
+  describe('statistics', () => {
+    it('should track hits and misses', () => {
+      cache.set('key1', 'value1');
+
+      cache.get('key1'); // Hit
+      cache.get('key1'); // Hit
+      cache.get('nonexistent'); // Miss
+
+      const stats = cache.getStats();
+      expect(stats.hits).toBe(2);
+      expect(stats.misses).toBe(1);
+      expect(stats.hitRate).toBeCloseTo(2 / 3);
+    });
+
+    it('should track evictions', () => {
+      const smallCache = new CacheManager<string>({ maxSize: 2, ttl: 60000 });
+
+      smallCache.set('key1', 'value1');
+      smallCache.set('key2', 'value2');
+      smallCache.set('key3', 'value3'); // Evicts key1
+
+      const stats = smallCache.getStats();
+      expect(stats.evictions).toBe(1);
+
+      smallCache.shutdown();
+    });
+
+    it('should track size and memory usage', () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+
+      const stats = cache.getStats();
+      expect(stats.size).toBe(2);
+      expect(stats.memoryUsage).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getOrSet', () => {
+    it('should return cached value if exists', async () => {
+      cache.set('key1', 'cached');
+
+      const loader = vi.fn().mockResolvedValue('loaded');
+      const result = await cache.getOrSet('key1', loader);
+
+      expect(result).toBe('cached');
+      expect(loader).not.toHaveBeenCalled();
+    });
+
+    it('should load and cache value if not exists', async () => {
+      const loader = vi.fn().mockResolvedValue('loaded');
+      const result = await cache.getOrSet('key1', loader);
+
+      expect(result).toBe('loaded');
+      expect(loader).toHaveBeenCalledTimes(1);
+      expect(cache.get('key1')).toBe('loaded');
+    });
+  });
+
+  describe('prefetch', () => {
+    it('should load missing keys in batch', async () => {
+      cache.set('key1', 'existing');
+
+      const loader = vi.fn().mockResolvedValue(
+        new Map([
+          ['key2', 'loaded2'],
+          ['key3', 'loaded3'],
+        ])
+      );
+
+      await cache.prefetch(['key1', 'key2', 'key3'], loader);
+
+      // Loader should only be called for missing keys
+      expect(loader).toHaveBeenCalledWith(['key2', 'key3']);
+      expect(cache.get('key1')).toBe('existing');
+      expect(cache.get('key2')).toBe('loaded2');
+      expect(cache.get('key3')).toBe('loaded3');
+    });
+
+    it('should not call loader if all keys exist', async () => {
+      cache.set('key1', 'value1');
+      cache.set('key2', 'value2');
+
+      const loader = vi.fn();
+      await cache.prefetch(['key1', 'key2'], loader);
+
+      expect(loader).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('warmUp', () => {
+    it('should populate cache with initial data', () => {
+      cache.warmUp([
+        { key: 'key1', data: 'value1' },
+        { key: 'key2', data: 'value2' },
+        { key: 'key3', data: 'value3', ttl: 1000 },
+      ]);
+
+      expect(cache.get('key1')).toBe('value1');
+      expect(cache.get('key2')).toBe('value2');
+      expect(cache.get('key3')).toBe('value3');
+      expect(cache.size).toBe(3);
+    });
+  });
+
+  describe('invalidatePattern', () => {
+    it('should invalidate keys matching string pattern', () => {
+      cache.set('user:1', 'value1');
+      cache.set('user:2', 'value2');
+      cache.set('post:1', 'value3');
+
+      const count = cache.invalidatePattern('user:');
+
+      expect(count).toBe(2);
+      expect(cache.has('user:1')).toBe(false);
+      expect(cache.has('user:2')).toBe(false);
+      expect(cache.has('post:1')).toBe(true);
+    });
+
+    it('should invalidate keys matching regex pattern', () => {
+      cache.set('cache:session:abc', 'value1');
+      cache.set('cache:session:def', 'value2');
+      cache.set('cache:data:xyz', 'value3');
+
+      const count = cache.invalidatePattern(/cache:session:/);
+
+      expect(count).toBe(2);
+      expect(cache.has('cache:session:abc')).toBe(false);
+      expect(cache.has('cache:data:xyz')).toBe(true);
+    });
+  });
+
+  describe('events', () => {
+    it('should emit cache:hit event', () => {
+      const handler = vi.fn();
+      cache.on('cache:hit', handler);
+
+      cache.set('key1', 'value1');
+      cache.get('key1');
+
+      expect(handler).toHaveBeenCalledWith({ key: 'key1' });
+    });
+
+    it('should emit cache:miss event', () => {
+      const handler = vi.fn();
+      cache.on('cache:miss', handler);
+
+      cache.get('nonexistent');
+
+      expect(handler).toHaveBeenCalledWith({ key: 'nonexistent' });
+    });
+
+    it('should emit cache:set event', () => {
+      const handler = vi.fn();
+      cache.on('cache:set', handler);
+
+      cache.set('key1', 'value1');
+
+      expect(handler).toHaveBeenCalledWith({ key: 'key1', ttl: 60000 });
+    });
+
+    it('should emit cache:delete event', () => {
+      const handler = vi.fn();
+      cache.on('cache:delete', handler);
+
+      cache.set('key1', 'value1');
+      cache.delete('key1');
+
+      expect(handler).toHaveBeenCalledWith({ key: 'key1' });
+    });
+  });
+
+  describe('shutdown', () => {
+    it('should clear cache and stop cleanup timer', () => {
+      cache.set('key1', 'value1');
+      cache.shutdown();
+
+      expect(cache.size).toBe(0);
+    });
+  });
+});
+
+describe('TieredCacheManager', () => {
+  let tieredCache: TieredCacheManager<string>;
+  let l2Store: Map<string, string>;
+
+  beforeEach(() => {
+    l2Store = new Map();
+
+    tieredCache = new TieredCacheManager<string>(
+      { maxSize: 10, ttl: 60000 },
+      {
+        loader: async (key) => l2Store.get(key) ?? null,
+        writer: async (key, value) => {
+          l2Store.set(key, value);
+        },
+      }
+    );
+  });
+
+  afterEach(() => {
+    tieredCache.shutdown();
+  });
+
+  describe('tiered caching', () => {
+    it('should store in L1 cache and write through to L2', async () => {
+      await tieredCache.set('key1', 'value1');
+      const result = await tieredCache.get('key1');
+      expect(result).toBe('value1');
+      expect(l2Store.get('key1')).toBe('value1');
+    });
+
+    it('should fall back to L2 when L1 misses', async () => {
+      // Directly set in L2 (simulating data loaded from storage)
+      l2Store.set('key1', 'value1');
+
+      // Should find in L2
+      const result = await tieredCache.get('key1');
+      expect(result).toBe('value1');
+    });
+
+    it('should promote L2 hits to L1', async () => {
+      // Set in L2 only
+      l2Store.set('key1', 'value1');
+
+      // First access loads from L2
+      await tieredCache.get('key1');
+
+      // Now should be in L1 (faster subsequent access)
+      const stats = tieredCache.getStats();
+      expect(stats.size).toBe(1);
+    });
+
+    it('should delete from L1', async () => {
+      await tieredCache.set('key1', 'value1');
+      expect(tieredCache.delete('key1')).toBe(true);
+
+      // Should miss in L1, but L2 still has it
+      expect(l2Store.has('key1')).toBe(true);
+    });
+
+    it('should clear L1 cache', async () => {
+      await tieredCache.set('key1', 'value1');
+      await tieredCache.set('key2', 'value2');
+
+      tieredCache.clear();
+
+      const stats = tieredCache.getStats();
+      expect(stats.size).toBe(0);
+    });
+  });
+
+  describe('without L2', () => {
+    it('should work with L1 only', async () => {
+      const l1Only = new TieredCacheManager<string>({ maxSize: 10, ttl: 60000 });
+
+      await l1Only.set('key1', 'value1');
+      const result = await l1Only.get('key1');
+      expect(result).toBe('value1');
+
+      l1Only.shutdown();
+    });
+
+    it('should return null for missing keys without L2', async () => {
+      const l1Only = new TieredCacheManager<string>({ maxSize: 10, ttl: 60000 });
+
+      const result = await l1Only.get('nonexistent');
+      expect(result).toBeNull();
+
+      l1Only.shutdown();
+    });
+  });
+
+  describe('statistics', () => {
+    it('should return L1 statistics', async () => {
+      await tieredCache.set('key1', 'value1');
+      await tieredCache.get('key1');
+
+      const stats = tieredCache.getStats();
+      expect(stats.hits).toBeGreaterThanOrEqual(1);
+      expect(stats.size).toBe(1);
+    });
+  });
+
+  describe('events', () => {
+    it('should emit l1:hit event', async () => {
+      const handler = vi.fn();
+      tieredCache.on('l1:hit', handler);
+
+      await tieredCache.set('key1', 'value1');
+      await tieredCache.get('key1');
+
+      expect(handler).toHaveBeenCalled();
+    });
+
+    it('should emit l2:hit event', async () => {
+      const handler = vi.fn();
+      tieredCache.on('l2:hit', handler);
+
+      l2Store.set('key1', 'value1');
+      await tieredCache.get('key1');
+
+      expect(handler).toHaveBeenCalledWith({ key: 'key1' });
+    });
+
+    it('should emit l2:write event', async () => {
+      const handler = vi.fn();
+      tieredCache.on('l2:write', handler);
+
+      await tieredCache.set('key1', 'value1');
+
+      expect(handler).toHaveBeenCalledWith({ key: 'key1' });
+    });
+  });
+});