@od-oneapp/ai-platform 0.1.0

package/src/caching/strategies/index.ts

@@ -0,0 +1,1008 @@
+/**
+ * @fileoverview Pluggable cache eviction strategies (LRU, LFU, TTL, FIFO, Adaptive).
+ * @module @od-oneapp/ai-platform/caching/strategies
+ *
+ * Pluggable eviction strategies for cache management:
+ * - LRU (Least Recently Used) - evicts least recently accessed items
+ * - LFU (Least Frequently Used) - evicts least frequently accessed items
+ * - TTL (Time To Live) - evicts items after expiration
+ * - FIFO (First In First Out) - evicts oldest items first
+ * - Adaptive - dynamically switches between strategies based on access patterns
+ *
+ * @module @od-oneapp/ai-platform/caching/strategies
+ *
+ * @example
+ * ```typescript
+ * import { createLRUStrategy, createAdaptiveStrategy } from '@od-oneapp/ai-platform/caching/strategies';
+ *
+ * // LRU with max 1000 items
+ * const lru = createLRUStrategy({ maxSize: 1000 });
+ * lru.set('key1', 'value1');
+ * const val = lru.get('key1'); // Updates access time
+ *
+ * // Adaptive strategy
+ * const adaptive = createAdaptiveStrategy({ maxSize: 1000 });
+ * ```
+ */
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+/** Eviction strategy type */
+export type EvictionStrategy = 'lru' | 'lfu' | 'ttl' | 'fifo' | 'adaptive';
+
+/** Base strategy configuration */
+export interface StrategyConfig {
+  /** Maximum number of items */
+  maxSize: number;
+  /** Default TTL in milliseconds (for TTL strategy) */
+  defaultTtlMs?: number;
+  /** Callback when item is evicted */
+  onEvict?: (key: string, value: unknown) => void;
+}
+
+/** Cache entry metadata */
+export interface CacheEntryMeta {
+  /** When the entry was created */
+  createdAt: number;
+  /** When the entry was last accessed */
+  lastAccessedAt: number;
+  /** Number of times accessed */
+  accessCount: number;
+  /** When the entry expires (if TTL set) */
+  expiresAt?: number;
+  /** Size estimate in bytes */
+  sizeBytes?: number;
+}
+
+/** Cache entry with metadata */
+export interface CacheEntry<T = unknown> {
+  key: string;
+  value: T;
+  meta: CacheEntryMeta;
+}
+
+/** Strategy statistics */
+export interface StrategyStats {
+  hits: number;
+  misses: number;
+  evictions: number;
+  currentSize: number;
+  maxSize: number;
+  hitRate: number;
+}
+
+/** Eviction strategy interface */
+export interface CacheEvictionStrategy<T = unknown> {
+  /** Get item from cache */
+  get(key: string): T | undefined;
+  /** Set item in cache */
+  set(key: string, value: T, ttlMs?: number): void;
+  /** Check if key exists */
+  has(key: string): boolean;
+  /** Delete item from cache */
+  delete(key: string): boolean;
+  /** Clear all items */
+  clear(): void;
+  /** Get current size */
+  size(): number;
+  /** Get all keys */
+  keys(): string[];
+  /** Get statistics */
+  stats(): StrategyStats;
+  /** Peek at value without updating access */
+  peek(key: string): T | undefined;
+  /** Peek at full entry with metadata without updating access */
+  peekEntry?(key: string): CacheEntry<T> | undefined;
+}
+
+// -----------------------------------------------------------------------------
+// LRU Strategy Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Create an LRU (Least Recently Used) eviction strategy.
+ * Evicts the least recently accessed items when capacity is reached.
+ *
+ * @example
+ * ```typescript
+ * const cache = createLRUStrategy<string>({ maxSize: 100 });
+ * cache.set('user:1', 'Alice');
+ * cache.get('user:1'); // Returns 'Alice', updates access time
+ * ```
+ */
+export function createLRUStrategy<T = unknown>(config: StrategyConfig): CacheEvictionStrategy<T> {
+  const { maxSize, defaultTtlMs, onEvict } = config;
+
+  const cache = new Map<string, CacheEntry<T>>();
+  let hits = 0;
+  let misses = 0;
+  let evictions = 0;
+
+  function evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of cache) {
+      if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+        cache.delete(key);
+        onEvict?.(key, entry.value);
+        evictions++;
+      }
+    }
+  }
+
+  function evictLRU(): void {
+    if (cache.size === 0) return;
+
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of cache) {
+      if (entry.meta.lastAccessedAt < oldestTime) {
+        oldestTime = entry.meta.lastAccessedAt;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      const entry = cache.get(oldestKey);
+      cache.delete(oldestKey);
+      if (entry) onEvict?.(oldestKey, entry.value);
+      evictions++;
+    }
+  }
+
+  function get(key: string): T | undefined {
+    evictExpired();
+
+    const entry = cache.get(key);
+    if (!entry) {
+      misses++;
+      return undefined;
+    }
+
+    // Check expiration
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      evictions++;
+      misses++;
+      return undefined;
+    }
+
+    // Update access metadata
+    entry.meta.lastAccessedAt = Date.now();
+    entry.meta.accessCount++;
+    hits++;
+
+    // Move to end (most recently used) by re-inserting
+    cache.delete(key);
+    cache.set(key, entry);
+
+    return entry.value;
+  }
+
+  function set(key: string, value: T, ttlMs?: number): void {
+    evictExpired();
+
+    // Evict if at capacity and key is new
+    if (!cache.has(key) && cache.size >= maxSize) {
+      evictLRU();
+    }
+
+    const now = Date.now();
+    const effectiveTtl = ttlMs ?? defaultTtlMs;
+
+    const entry: CacheEntry<T> = {
+      key,
+      value,
+      meta: {
+        createdAt: now,
+        lastAccessedAt: now,
+        accessCount: 1,
+        expiresAt: effectiveTtl ? now + effectiveTtl : undefined,
+      },
+    };
+
+    // Delete first to ensure it goes to end
+    cache.delete(key);
+    cache.set(key, entry);
+  }
+
+  function has(key: string): boolean {
+    const entry = cache.get(key);
+    if (!entry) return false;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      return false;
+    }
+    return true;
+  }
+
+  function del(key: string): boolean {
+    const entry = cache.get(key);
+    if (entry) {
+      cache.delete(key);
+      return true;
+    }
+    return false;
+  }
+
+  function clear(): void {
+    cache.clear();
+  }
+
+  function size(): number {
+    evictExpired();
+    return cache.size;
+  }
+
+  function keys(): string[] {
+    evictExpired();
+    return Array.from(cache.keys());
+  }
+
+  function stats(): StrategyStats {
+    const total = hits + misses;
+    return {
+      hits,
+      misses,
+      evictions,
+      currentSize: cache.size,
+      maxSize,
+      hitRate: total > 0 ? hits / total : 0,
+    };
+  }
+
+  function peek(key: string): T | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  function peekEntry(key: string): CacheEntry<T> | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry;
+  }
+
+  return { get, set, has, delete: del, clear, size, keys, stats, peek, peekEntry };
+}
+
+// -----------------------------------------------------------------------------
+// LFU Strategy Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Create an LFU (Least Frequently Used) eviction strategy.
+ * Evicts the least frequently accessed items when capacity is reached.
+ *
+ * @example
+ * ```typescript
+ * const cache = createLFUStrategy<string>({ maxSize: 100 });
+ * cache.set('popular', 'data');
+ * cache.get('popular'); // Increases frequency
+ * cache.get('popular'); // Now won't be evicted easily
+ * ```
+ */
+export function createLFUStrategy<T = unknown>(config: StrategyConfig): CacheEvictionStrategy<T> {
+  const { maxSize, defaultTtlMs, onEvict } = config;
+
+  const cache = new Map<string, CacheEntry<T>>();
+  let hits = 0;
+  let misses = 0;
+  let evictions = 0;
+
+  function evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of cache) {
+      if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+        cache.delete(key);
+        onEvict?.(key, entry.value);
+        evictions++;
+      }
+    }
+  }
+
+  function evictLFU(): void {
+    if (cache.size === 0) return;
+
+    let lfuKey: string | null = null;
+    let minFreq = Infinity;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of cache) {
+      // Find lowest frequency, break ties by oldest access time
+      if (
+        entry.meta.accessCount < minFreq ||
+        (entry.meta.accessCount === minFreq && entry.meta.lastAccessedAt < oldestTime)
+      ) {
+        minFreq = entry.meta.accessCount;
+        oldestTime = entry.meta.lastAccessedAt;
+        lfuKey = key;
+      }
+    }
+
+    if (lfuKey) {
+      const entry = cache.get(lfuKey);
+      cache.delete(lfuKey);
+      if (entry) onEvict?.(lfuKey, entry.value);
+      evictions++;
+    }
+  }
+
+  function get(key: string): T | undefined {
+    evictExpired();
+
+    const entry = cache.get(key);
+    if (!entry) {
+      misses++;
+      return undefined;
+    }
+
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      evictions++;
+      misses++;
+      return undefined;
+    }
+
+    entry.meta.lastAccessedAt = Date.now();
+    entry.meta.accessCount++;
+    hits++;
+
+    return entry.value;
+  }
+
+  function set(key: string, value: T, ttlMs?: number): void {
+    evictExpired();
+
+    if (!cache.has(key) && cache.size >= maxSize) {
+      evictLFU();
+    }
+
+    const now = Date.now();
+    const effectiveTtl = ttlMs ?? defaultTtlMs;
+
+    const existing = cache.get(key);
+    const entry: CacheEntry<T> = {
+      key,
+      value,
+      meta: {
+        createdAt: existing?.meta.createdAt ?? now,
+        lastAccessedAt: now,
+        accessCount: existing ? existing.meta.accessCount + 1 : 1,
+        expiresAt: effectiveTtl ? now + effectiveTtl : undefined,
+      },
+    };
+
+    cache.set(key, entry);
+  }
+
+  function has(key: string): boolean {
+    const entry = cache.get(key);
+    if (!entry) return false;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      return false;
+    }
+    return true;
+  }
+
+  function del(key: string): boolean {
+    return cache.delete(key);
+  }
+
+  function clear(): void {
+    cache.clear();
+  }
+
+  function size(): number {
+    evictExpired();
+    return cache.size;
+  }
+
+  function keys(): string[] {
+    evictExpired();
+    return Array.from(cache.keys());
+  }
+
+  function stats(): StrategyStats {
+    const total = hits + misses;
+    return {
+      hits,
+      misses,
+      evictions,
+      currentSize: cache.size,
+      maxSize,
+      hitRate: total > 0 ? hits / total : 0,
+    };
+  }
+
+  function peek(key: string): T | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  function peekEntry(key: string): CacheEntry<T> | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry;
+  }
+
+  return { get, set, has, delete: del, clear, size, keys, stats, peek, peekEntry };
+}
+
+// -----------------------------------------------------------------------------
+// FIFO Strategy Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a FIFO (First In First Out) eviction strategy.
+ * Evicts the oldest items first when capacity is reached.
+ *
+ * @example
+ * ```typescript
+ * const cache = createFIFOStrategy<string>({ maxSize: 100 });
+ * cache.set('first', 'data'); // Will be evicted first
+ * cache.set('second', 'data');
+ * ```
+ */
+export function createFIFOStrategy<T = unknown>(config: StrategyConfig): CacheEvictionStrategy<T> {
+  const { maxSize, defaultTtlMs, onEvict } = config;
+
+  const cache = new Map<string, CacheEntry<T>>();
+  let hits = 0;
+  let misses = 0;
+  let evictions = 0;
+
+  function evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of cache) {
+      if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+        cache.delete(key);
+        onEvict?.(key, entry.value);
+        evictions++;
+      }
+    }
+  }
+
+  function evictFIFO(): void {
+    if (cache.size === 0) return;
+
+    // Map maintains insertion order, first key is oldest
+    const firstKey = cache.keys().next().value;
+    if (firstKey) {
+      const entry = cache.get(firstKey);
+      cache.delete(firstKey);
+      if (entry) onEvict?.(firstKey, entry.value);
+      evictions++;
+    }
+  }
+
+  function get(key: string): T | undefined {
+    evictExpired();
+
+    const entry = cache.get(key);
+    if (!entry) {
+      misses++;
+      return undefined;
+    }
+
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      evictions++;
+      misses++;
+      return undefined;
+    }
+
+    entry.meta.lastAccessedAt = Date.now();
+    entry.meta.accessCount++;
+    hits++;
+
+    // FIFO doesn't reorder on access
+    return entry.value;
+  }
+
+  function set(key: string, value: T, ttlMs?: number): void {
+    evictExpired();
+
+    if (!cache.has(key) && cache.size >= maxSize) {
+      evictFIFO();
+    }
+
+    const now = Date.now();
+    const effectiveTtl = ttlMs ?? defaultTtlMs;
+
+    // For FIFO, we don't want to update position of existing keys
+    const existing = cache.get(key);
+    const entry: CacheEntry<T> = {
+      key,
+      value,
+      meta: {
+        createdAt: existing?.meta.createdAt ?? now,
+        lastAccessedAt: now,
+        accessCount: existing ? existing.meta.accessCount + 1 : 1,
+        expiresAt: effectiveTtl ? now + effectiveTtl : undefined,
+      },
+    };
+
+    if (existing) {
+      // Update in place
+      cache.set(key, entry);
+    } else {
+      // New entry goes to end
+      cache.set(key, entry);
+    }
+  }
+
+  function has(key: string): boolean {
+    const entry = cache.get(key);
+    if (!entry) return false;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      return false;
+    }
+    return true;
+  }
+
+  function del(key: string): boolean {
+    return cache.delete(key);
+  }
+
+  function clear(): void {
+    cache.clear();
+  }
+
+  function size(): number {
+    evictExpired();
+    return cache.size;
+  }
+
+  function keys(): string[] {
+    evictExpired();
+    return Array.from(cache.keys());
+  }
+
+  function stats(): StrategyStats {
+    const total = hits + misses;
+    return {
+      hits,
+      misses,
+      evictions,
+      currentSize: cache.size,
+      maxSize,
+      hitRate: total > 0 ? hits / total : 0,
+    };
+  }
+
+  function peek(key: string): T | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  function peekEntry(key: string): CacheEntry<T> | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry;
+  }
+
+  return { get, set, has, delete: del, clear, size, keys, stats, peek, peekEntry };
+}
+
+// -----------------------------------------------------------------------------
+// TTL Strategy Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a TTL (Time To Live) eviction strategy.
+ * Items automatically expire after their TTL.
+ *
+ * @example
+ * ```typescript
+ * const cache = createTTLStrategy<string>({
+ *   maxSize: 1000,
+ *   defaultTtlMs: 60000 // 1 minute default
+ * });
+ * cache.set('temp', 'data', 5000); // Expires in 5 seconds
+ * ```
+ */
+export function createTTLStrategy<T = unknown>(config: StrategyConfig): CacheEvictionStrategy<T> {
+  const { maxSize, defaultTtlMs = 60000, onEvict } = config;
+
+  const cache = new Map<string, CacheEntry<T>>();
+  let hits = 0;
+  let misses = 0;
+  let evictions = 0;
+
+  function evictExpired(): number {
+    const now = Date.now();
+    let count = 0;
+    for (const [key, entry] of cache) {
+      if (entry.meta.expiresAt && now > entry.meta.expiresAt) {
+        cache.delete(key);
+        onEvict?.(key, entry.value);
+        evictions++;
+        count++;
+      }
+    }
+    return count;
+  }
+
+  function evictOldest(): void {
+    if (cache.size === 0) return;
+
+    let oldestKey: string | null = null;
+    let oldestExpiry = Infinity;
+
+    for (const [key, entry] of cache) {
+      const expiry = entry.meta.expiresAt ?? entry.meta.createdAt;
+      if (expiry < oldestExpiry) {
+        oldestExpiry = expiry;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      const entry = cache.get(oldestKey);
+      cache.delete(oldestKey);
+      if (entry) onEvict?.(oldestKey, entry.value);
+      evictions++;
+    }
+  }
+
+  function get(key: string): T | undefined {
+    evictExpired();
+
+    const entry = cache.get(key);
+    if (!entry) {
+      misses++;
+      return undefined;
+    }
+
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      evictions++;
+      misses++;
+      return undefined;
+    }
+
+    entry.meta.lastAccessedAt = Date.now();
+    entry.meta.accessCount++;
+    hits++;
+
+    return entry.value;
+  }
+
+  function set(key: string, value: T, ttlMs?: number): void {
+    evictExpired();
+
+    if (!cache.has(key) && cache.size >= maxSize) {
+      evictOldest();
+    }
+
+    const now = Date.now();
+    const effectiveTtl = ttlMs ?? defaultTtlMs;
+
+    const entry: CacheEntry<T> = {
+      key,
+      value,
+      meta: {
+        createdAt: now,
+        lastAccessedAt: now,
+        accessCount: 1,
+        expiresAt: now + effectiveTtl,
+      },
+    };
+
+    cache.set(key, entry);
+  }
+
+  function has(key: string): boolean {
+    const entry = cache.get(key);
+    if (!entry) return false;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      cache.delete(key);
+      onEvict?.(key, entry.value);
+      return false;
+    }
+    return true;
+  }
+
+  function del(key: string): boolean {
+    return cache.delete(key);
+  }
+
+  function clear(): void {
+    cache.clear();
+  }
+
+  function size(): number {
+    evictExpired();
+    return cache.size;
+  }
+
+  function keys(): string[] {
+    evictExpired();
+    return Array.from(cache.keys());
+  }
+
+  function stats(): StrategyStats {
+    const total = hits + misses;
+    return {
+      hits,
+      misses,
+      evictions,
+      currentSize: cache.size,
+      maxSize,
+      hitRate: total > 0 ? hits / total : 0,
+    };
+  }
+
+  function peek(key: string): T | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  function peekEntry(key: string): CacheEntry<T> | undefined {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    if (entry.meta.expiresAt && Date.now() > entry.meta.expiresAt) {
+      return undefined;
+    }
+    return entry;
+  }
+
+  return { get, set, has, delete: del, clear, size, keys, stats, peek, peekEntry };
+}
+
+// -----------------------------------------------------------------------------
+// Adaptive Strategy Implementation
+// -----------------------------------------------------------------------------
+
+/** Adaptive strategy configuration */
+export interface AdaptiveStrategyConfig extends StrategyConfig {
+  /** Window size for measuring access patterns */
+  analysisWindowMs?: number;
+  /** How often to analyze and potentially switch strategies */
+  analysisIntervalMs?: number;
+}
+
+/**
+ * Create an Adaptive eviction strategy.
+ * Dynamically switches between LRU and LFU based on access patterns.
+ *
+ * @example
+ * ```typescript
+ * const cache = createAdaptiveStrategy<string>({
+ *   maxSize: 1000,
+ *   analysisWindowMs: 60000 // Analyze every minute
+ * });
+ * ```
+ */
+export function createAdaptiveStrategy<T = unknown>(
+  config: AdaptiveStrategyConfig,
+): CacheEvictionStrategy<T> {
+  const {
+    maxSize,
+    defaultTtlMs,
+    onEvict,
+    analysisWindowMs = 60000,
+    analysisIntervalMs = 10000,
+  } = config;
+
+  // Start with LRU
+  let currentStrategy: 'lru' | 'lfu' = 'lru';
+  const lruCache = createLRUStrategy<T>({ maxSize, defaultTtlMs, onEvict });
+  const lfuCache = createLFUStrategy<T>({ maxSize, defaultTtlMs, onEvict });
+  let activeCache = lruCache;
+
+  // Access pattern tracking
+  const accessLog: Array<{ key: string; time: number }> = [];
+  let lastAnalysis = Date.now();
+
+  function analyzePatterns(): void {
+    const now = Date.now();
+    if (now - lastAnalysis < analysisIntervalMs) return;
+    lastAnalysis = now;
+
+    // Filter to window
+    const windowStart = now - analysisWindowMs;
+    const recentAccesses = accessLog.filter(a => a.time >= windowStart);
+
+    if (recentAccesses.length < 10) return; // Not enough data
+
+    // Count frequency of each key
+    const keyCounts = new Map<string, number>();
+    for (const access of recentAccesses) {
+      keyCounts.set(access.key, (keyCounts.get(access.key) ?? 0) + 1);
+    }
+
+    // Calculate skewness - how concentrated are accesses?
+    const counts = Array.from(keyCounts.values());
+    const total = counts.reduce((a, b) => a + b, 0);
+    const mean = total / counts.length;
+    const variance = counts.reduce((sum, c) => sum + Math.pow(c - mean, 2), 0) / counts.length;
+    const stdDev = Math.sqrt(variance);
+    const coefficientOfVariation = mean > 0 ? stdDev / mean : 0;
+
+    // High CV = skewed access (few hot keys) = prefer LFU
+    // Low CV = uniform access = prefer LRU
+    const shouldUseLFU = coefficientOfVariation > 1.5;
+
+    if (shouldUseLFU && currentStrategy !== 'lfu') {
+      // Switch to LFU - migrate data preserving per-entry TTLs
+      const entries = lruCache
+        .keys()
+        .map(k => lruCache.peekEntry?.(k))
+        .filter((e): e is CacheEntry<T> => e !== undefined);
+      lfuCache.clear();
+      for (const entry of entries) {
+        // Calculate remaining TTL to preserve per-entry expiration
+        const remainingTtlMs = entry.meta.expiresAt
+          ? Math.max(0, entry.meta.expiresAt - now)
+          : undefined;
+        // Only migrate non-expired entries
+        if (remainingTtlMs === undefined || remainingTtlMs > 0) {
+          lfuCache.set(entry.key, entry.value, remainingTtlMs);
+        }
+      }
+      // Clear source cache to avoid memory duplication
+      lruCache.clear();
+      activeCache = lfuCache;
+      currentStrategy = 'lfu';
+    } else if (!shouldUseLFU && currentStrategy !== 'lru') {
+      // Switch to LRU - migrate data preserving per-entry TTLs
+      const entries = lfuCache
+        .keys()
+        .map(k => lfuCache.peekEntry?.(k))
+        .filter((e): e is CacheEntry<T> => e !== undefined);
+      lruCache.clear();
+      for (const entry of entries) {
+        // Calculate remaining TTL to preserve per-entry expiration
+        const remainingTtlMs = entry.meta.expiresAt
+          ? Math.max(0, entry.meta.expiresAt - now)
+          : undefined;
+        // Only migrate non-expired entries
+        if (remainingTtlMs === undefined || remainingTtlMs > 0) {
+          lruCache.set(entry.key, entry.value, remainingTtlMs);
+        }
+      }
+      // Clear source cache to avoid memory duplication
+      lfuCache.clear();
+      activeCache = lruCache;
+      currentStrategy = 'lru';
+    }
+
+    // Trim access log - remove old entries and cap max length to prevent memory spikes
+    const maxLogLength = 10000;
+    while (accessLog.length > 0 && (accessLog[0]?.time ?? 0) < windowStart) {
+      accessLog.shift();
+    }
+    // Hard cap to prevent unbounded growth under high QPS
+    if (accessLog.length > maxLogLength) {
+      accessLog.splice(0, accessLog.length - maxLogLength);
+    }
+  }
+
+  function get(key: string): T | undefined {
+    analyzePatterns();
+    // Cap accessLog length on push to prevent memory spikes under high QPS
+    if (accessLog.length >= 10000) {
+      accessLog.shift();
+    }
+    accessLog.push({ key, time: Date.now() });
+    return activeCache.get(key);
+  }
+
+  function set(key: string, value: T, ttlMs?: number): void {
+    analyzePatterns();
+    activeCache.set(key, value, ttlMs);
+  }
+
+  function has(key: string): boolean {
+    return activeCache.has(key);
+  }
+
+  function del(key: string): boolean {
+    // Delete from both to be safe
+    lruCache.delete(key);
+    lfuCache.delete(key);
+    return activeCache.delete(key);
+  }
+
+  function clear(): void {
+    lruCache.clear();
+    lfuCache.clear();
+    accessLog.length = 0;
+  }
+
+  function size(): number {
+    return activeCache.size();
+  }
+
+  function keys(): string[] {
+    return activeCache.keys();
+  }
+
+  function stats(): StrategyStats {
+    const baseStats = activeCache.stats();
+    return {
+      ...baseStats,
+      // Could add strategy-specific stats here
+    };
+  }
+
+  function peek(key: string): T | undefined {
+    return activeCache.peek(key);
+  }
+
+  function peekEntry(key: string): CacheEntry<T> | undefined {
+    return activeCache.peekEntry?.(key);
+  }
+
+  return { get, set, has, delete: del, clear, size, keys, stats, peek, peekEntry };
+}
+
+// -----------------------------------------------------------------------------
+// Factory Function
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a cache strategy by type.
+ *
+ * @example
+ * ```typescript
+ * const cache = createCacheStrategy('lru', { maxSize: 1000 });
+ * const adaptiveCache = createCacheStrategy('adaptive', { maxSize: 1000 });
+ * ```
+ */
+export function createCacheStrategy<T = unknown>(
+  strategy: EvictionStrategy,
+  config: StrategyConfig | AdaptiveStrategyConfig,
+): CacheEvictionStrategy<T> {
+  switch (strategy) {
+    case 'lru':
+      return createLRUStrategy<T>(config);
+    case 'lfu':
+      return createLFUStrategy<T>(config);
+    case 'fifo':
+      return createFIFOStrategy<T>(config);
+    case 'ttl':
+      return createTTLStrategy<T>(config);
+    case 'adaptive':
+      return createAdaptiveStrategy<T>(config as AdaptiveStrategyConfig);
+    default:
+      throw new Error(`Unknown cache strategy: ${strategy}`);
+  }
+}