Merge pull request #24 from BadlyDrawnBoy/codex/replace-map-with-lru-cache-in-cache.ts

Add configurable LRU caching with eviction metrics

Author: mad-sol-dev

src/utils/cache.ts

@@ -18,8 +18,93 @@ interface CacheEntry<T> {
   createdAt: number;
 }
 
-const textCache = new Map<string, CacheEntry<PdfPageText>>();
-const ocrCache = new Map<string, CacheEntry<CachedOcrResult>>();
+interface CacheOptions {
+  maxEntries: number;
+  ttlMs?: number;
+}
+
+class LruCache<T> {
+  private store = new Map<string, CacheEntry<T>>();
+  private evictions = 0;
+
+  constructor(private readonly options: CacheOptions) {}
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  get evictionCount(): number {
+    return this.evictions;
+  }
+
+  getKeys(): string[] {
+    return Array.from(this.store.keys());
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  private isExpired(entry: CacheEntry<T>): boolean {
+    if (!this.options.ttlMs) return false;
+    return Date.now() - entry.createdAt > this.options.ttlMs;
+  }
+
+  private markRecentlyUsed(key: string, entry: CacheEntry<T>): void {
+    this.store.delete(key);
+    this.store.set(key, entry);
+  }
+
+  private trimToMaxEntries(): void {
+    while (this.store.size > this.options.maxEntries) {
+      const oldestKey = this.store.keys().next().value;
+      if (!oldestKey) return;
+      this.store.delete(oldestKey);
+      this.evictions += 1;
+    }
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+
+    if (this.isExpired(entry)) {
+      this.store.delete(key);
+      this.evictions += 1;
+      return undefined;
+    }
+
+    this.markRecentlyUsed(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    const entry: CacheEntry<T> = { value, createdAt: Date.now() };
+    if (this.store.has(key)) {
+      this.store.delete(key);
+    }
+
+    this.store.set(key, entry);
+    this.trimToMaxEntries();
+  }
+}
+
+type CacheScope = 'text' | 'ocr';
+
+const DEFAULT_CACHE_OPTIONS: Record<CacheScope, CacheOptions> = {
+  text: { maxEntries: 500 },
+  ocr: { maxEntries: 500 },
+};
+
+let cacheOptions: Record<CacheScope, CacheOptions> = {
+  text: { ...DEFAULT_CACHE_OPTIONS.text },
+  ocr: { ...DEFAULT_CACHE_OPTIONS.ocr },
+};
+
+const buildCache = <T>(scope: CacheScope): LruCache<T> => new LruCache<T>(cacheOptions[scope]);
+
+let textCache = buildCache<PdfPageText>('text');
+let ocrCache = buildCache<CachedOcrResult>('ocr');
 
 const buildPageKey = (fingerprint: string, page: number, options: PageCacheOptions): string => {
   const serializedOptions = JSON.stringify({
@@ -52,7 +137,7 @@ export const getCachedPageText = (
   options: PageCacheOptions
 ): PdfPageText | undefined => {
   if (!fingerprint) return undefined;
-  return textCache.get(buildPageKey(fingerprint, page, options))?.value;
+  return textCache.get(buildPageKey(fingerprint, page, options));
 };
 
 export const setCachedPageText = (
@@ -62,15 +147,15 @@ export const setCachedPageText = (
   value: PdfPageText
 ): void => {
   if (!fingerprint) return;
-  textCache.set(buildPageKey(fingerprint, page, options), { value, createdAt: Date.now() });
+  textCache.set(buildPageKey(fingerprint, page, options), value);
 };
 
 export const getCachedOcrText = (
   fingerprint: string | undefined,
   target: string
 ): CachedOcrResult | undefined => {
   if (!fingerprint) return undefined;
-  return ocrCache.get(buildOcrKey(fingerprint, target))?.value;
+  return ocrCache.get(buildOcrKey(fingerprint, target));
 };
 
 export const setCachedOcrText = (
@@ -79,19 +164,28 @@ export const setCachedOcrText = (
   value: CachedOcrResult
 ): void => {
   if (!fingerprint) return;
-  ocrCache.set(buildOcrKey(fingerprint, target), { value, createdAt: Date.now() });
+  ocrCache.set(buildOcrKey(fingerprint, target), value);
 };
 
 export const getCacheStats = (): {
   text_entries: number;
   ocr_entries: number;
   text_keys: string[];
   ocr_keys: string[];
+  text_evictions: number;
+  ocr_evictions: number;
+  config: typeof cacheOptions;
 } => ({
   text_entries: textCache.size,
   ocr_entries: ocrCache.size,
-  text_keys: Array.from(textCache.keys()),
-  ocr_keys: Array.from(ocrCache.keys()),
+  text_keys: textCache.getKeys(),
+  ocr_keys: ocrCache.getKeys(),
+  text_evictions: textCache.evictionCount,
+  ocr_evictions: ocrCache.evictionCount,
+  config: {
+    text: { ...cacheOptions.text },
+    ocr: { ...cacheOptions.ocr },
+  },
 });
 
 export const clearCache = (
@@ -110,3 +204,28 @@ export const clearCache = (
 
   return { cleared_text: clearText, cleared_ocr: clearOcr };
 };
+
+export const configureCache = (scope: CacheScope, options: Partial<CacheOptions>): void => {
+  cacheOptions = { ...cacheOptions, [scope]: { ...cacheOptions[scope], ...options } } as Record<
+    CacheScope,
+    CacheOptions
+  >;
+
+  if (scope === 'text') {
+    textCache = buildCache<PdfPageText>('text');
+  } else {
+    ocrCache = buildCache<CachedOcrResult>('ocr');
+  }
+};
+
+export const resetCacheConfig = (): void => {
+  cacheOptions = {
+    text: { ...DEFAULT_CACHE_OPTIONS.text },
+    ocr: { ...DEFAULT_CACHE_OPTIONS.ocr },
+  };
+
+  textCache = buildCache<PdfPageText>('text');
+  ocrCache = buildCache<CachedOcrResult>('ocr');
+};
+
+export const getCacheConfig = (): Record<CacheScope, CacheOptions> => cacheOptions;

test/utils/cache.test.ts

@@ -1,12 +1,24 @@
-import { afterEach, describe, expect, it } from 'vitest';
-import { buildOcrProviderKey, clearCache, getCachedOcrText, setCachedOcrText } from '../../src/utils/cache.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  buildOcrProviderKey,
+  clearCache,
+  configureCache,
+  getCachedOcrText,
+  getCachedPageText,
+  getCacheStats,
+  resetCacheConfig,
+  setCachedOcrText,
+  setCachedPageText,
+} from '../../src/utils/cache.js';
 
 const fingerprint = 'fingerprint-123';
 const targetBase = 'image-1-0';
 
 describe('OCR cache provider awareness', () => {
   afterEach(() => {
-    clearCache('ocr');
+    clearCache('all');
+    resetCacheConfig();
+    vi.useRealTimers();
   });
 
   it('creates distinct cache entries for different providers', () => {
@@ -35,4 +47,52 @@ describe('OCR cache provider awareness', () => {
     expect(getCachedOcrText(fingerprint, keyWithDifferentScale)).toBeUndefined();
     expect(getCachedOcrText(fingerprint, keyWithScale)?.text).toBe('scaled');
   });
+
+  it('evicts least recently used entries when exceeding max size', () => {
+    configureCache('ocr', { maxEntries: 2 });
+
+    const firstKey = `${targetBase}-a`;
+    const secondKey = `${targetBase}-b`;
+    const thirdKey = `${targetBase}-c`;
+
+    setCachedOcrText(fingerprint, firstKey, { text: 'first' });
+    setCachedOcrText(fingerprint, secondKey, { text: 'second' });
+
+    // Access the first key to make it most recently used
+    expect(getCachedOcrText(fingerprint, firstKey)?.text).toBe('first');
+
+    setCachedOcrText(fingerprint, thirdKey, { text: 'third' });
+
+    expect(getCachedOcrText(fingerprint, secondKey)).toBeUndefined();
+    expect(getCachedOcrText(fingerprint, firstKey)?.text).toBe('first');
+    expect(getCachedOcrText(fingerprint, thirdKey)?.text).toBe('third');
+
+    const stats = getCacheStats();
+    expect(stats.ocr_entries).toBe(2);
+    expect(stats.ocr_evictions).toBe(1);
+  });
+
+  it('expires entries after TTL duration', () => {
+    vi.useFakeTimers();
+    configureCache('text', { maxEntries: 3, ttlMs: 1000 });
+
+    const pageOptions = {
+      includeImageIndexes: false,
+      preserveWhitespace: false,
+      trimLines: true,
+    } as const;
+
+    setCachedPageText(fingerprint, 1, pageOptions, {
+      page_number: 1,
+      page_index: 0,
+      page_label: null,
+      lines: [],
+      text: 'temporary',
+    });
+
+    vi.advanceTimersByTime(1500);
+
+    expect(getCachedPageText(fingerprint, 1, pageOptions)).toBeUndefined();
+    expect(getCacheStats().text_evictions).toBe(1);
+  });
 });