qa360 2.1.7 → 2.2.0

package/core/src/cache/lru-cache.ts

@@ -0,0 +1,536 @@
+/**
+ * QA360 LRU Cache Module
+ *
+ * Intelligent caching system for HTTP responses to avoid redundant requests.
+ * Features:
+ * - LRU (Least Recently Used) eviction policy
+ * - TTL (Time To Live) expiration
+ * - Size-based limits
+ * - Cache key generation based on request parameters
+ * - Thread-safe operations (async-friendly)
+ * - Metrics and statistics
+ *
+ * @example
+ * ```typescript
+ * const cache = new ResponseCache({
+ *   maxSize: 100,
+ *   ttl: 60000, // 1 minute
+ *   maxSizeBytes: 10 * 1024 * 1024 // 10MB
+ * });
+ *
+ * const response = await cache.getOrFetch('GET:/api/users', async () => {
+ *   return await fetch('/api/users');
+ * });
+ * ```
+ */
+
+/**
+ * Cache entry containing response data and metadata
+ */
+export interface CacheEntry<T> {
+  /** Cached response data */
+  data: T;
+  /** Timestamp when entry was created (ms) */
+  createdAt: number;
+  /** Timestamp when entry was last accessed (ms) */
+  lastAccessed: number;
+  /** Number of times this entry was accessed */
+  hitCount: number;
+  /** Size of the cached data in bytes (approximate) */
+  size: number;
+  /** Optional cache key for this entry */
+  key?: string;
+}
+
+/**
+ * Cache configuration options
+ */
+export interface CacheOptions {
+  /** Maximum number of entries in the cache (default: 100) */
+  maxSize?: number;
+  /** Time to live for entries in milliseconds (default: 300000 = 5 minutes) */
+  ttl?: number;
+  /** Maximum total size of cache in bytes (default: 10MB) */
+  maxSizeBytes?: number;
+  /** Whether to enable cache statistics (default: true) */
+  enableStats?: boolean;
+  /** Whether to log cache operations (default: false) */
+  verbose?: boolean;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  /** Total number of cache hits */
+  hits: number;
+  /** Total number of cache misses */
+  misses: number;
+  /** Total number of entries added to cache */
+  additions: number;
+  /** Total number of entries evicted from cache */
+  evictions: number;
+  /** Current number of entries in cache */
+  size: number;
+  /** Current approximate size in bytes */
+  sizeBytes: number;
+  /** Cache hit rate (0-1) */
+  hitRate: number;
+  /** Average entry size in bytes */
+  avgEntrySize: number;
+}
+
+/**
+ * Cache key generation options
+ */
+export interface CacheKeyOptions {
+  /** HTTP method (GET, POST, etc.) */
+  method: string;
+  /** Request URL/endpoint */
+  url: string;
+  /** Request headers (for cache key variation) */
+  headers?: Record<string, string>;
+  /** Request body (for POST/PUT/PATCH) */
+  body?: string | Record<string, unknown>;
+  /** Query parameters */
+  params?: Record<string, string>;
+  /** Vary headers (headers that affect cacheability) */
+  varyHeaders?: string[];
+}
+
+/**
+ * LRU Response Cache
+ *
+ * Thread-safe LRU cache with TTL and size-based eviction.
+ */
+export class ResponseCache<T = unknown> {
+  private cache: Map<string, CacheEntry<T>>;
+  private maxSize: number;
+  private ttl: number;
+  private maxSizeBytes: number;
+  private currentSizeBytes: number;
+  private enableStats: boolean;
+  private verbose: boolean;
+  private stats: CacheStats;
+
+  constructor(options: CacheOptions = {}) {
+    this.maxSize = options.maxSize ?? 100;
+    this.ttl = options.ttl ?? 300000; // 5 minutes default
+    this.maxSizeBytes = options.maxSizeBytes ?? 10 * 1024 * 1024; // 10MB default
+    this.enableStats = options.enableStats ?? true;
+    this.verbose = options.verbose ?? false;
+    this.currentSizeBytes = 0;
+
+    this.cache = new Map();
+
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      additions: 0,
+      evictions: 0,
+      size: 0,
+      sizeBytes: 0,
+      hitRate: 0,
+      avgEntrySize: 0
+    };
+  }
+
+  /**
+   * Get a value from cache by key
+   * Returns undefined if not found or expired
+   */
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      this._recordMiss();
+      return undefined;
+    }
+
+    // Check if entry has expired
+    const now = Date.now();
+    const age = now - entry.createdAt;
+
+    if (age > this.ttl) {
+      // Entry expired, remove it
+      this._remove(key);
+      this._recordMiss();
+      if (this.verbose) {
+        console.log(`📦 Cache EXPIRED: ${key} (age: ${age}ms, TTL: ${this.ttl}ms)`);
+      }
+      return undefined;
+    }
+
+    // Update last accessed time and hit count
+    entry.lastAccessed = now;
+    entry.hitCount++;
+
+    // Move to end of Map to mark as most recently used
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+
+    this._recordHit();
+
+    if (this.verbose) {
+      console.log(`📦 Cache HIT: ${key} (age: ${age}ms, hits: ${entry.hitCount})`);
+    }
+
+    return entry.data;
+  }
+
+  /**
+   * Set a value in cache by key
+   * If key exists, updates the entry
+   * If cache is full, evicts LRU entry
+   */
+  set(key: string, data: T, size?: number): void {
+    const now = Date.now();
+    const entrySize = size ?? this._estimateSize(data);
+
+    // Check if we need to evict entries
+    // First, if key already exists, we'll replace it (size may be different)
+    const existing = this.cache.get(key);
+    if (existing) {
+      this.currentSizeBytes -= existing.size;
+      this.cache.delete(key);
+    }
+
+    // Evict entries if we're over size limits
+    while (
+      (this.cache.size >= this.maxSize) ||
+      (this.currentSizeBytes + entrySize > this.maxSizeBytes)
+    ) {
+      this._evictLRU();
+    }
+
+    // Add new entry
+    const entry: CacheEntry<T> = {
+      data,
+      createdAt: now,
+      lastAccessed: now,
+      hitCount: 0,
+      size: entrySize,
+      key
+    };
+
+    this.cache.set(key, entry);
+    this.currentSizeBytes += entrySize;
+    this._recordAddition();
+
+    if (this.verbose) {
+      console.log(`📦 Cache SET: ${key} (size: ${entrySize} bytes, total: ${this.cache.size} entries)`);
+    }
+  }
+
+  /**
+   * Get a value from cache, or compute and cache it if not present
+   * This is the main method to use for caching operations
+   */
+  async getOrFetch(
+    key: string,
+    fetchFn: () => Promise<T>,
+    size?: number
+  ): Promise<T> {
+    const cached = this.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    // Cache miss - fetch and cache
+    const data = await fetchFn();
+    this.set(key, data, size);
+    return data;
+  }
+
+  /**
+   * Check if a key exists in cache and is not expired
+   */
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+
+    const age = Date.now() - entry.createdAt;
+    return age <= this.ttl;
+  }
+
+  /**
+   * Delete a specific entry from cache
+   */
+  delete(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+
+    this.currentSizeBytes -= entry.size;
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all entries from cache
+   */
+  clear(): void {
+    this.cache.clear();
+    this.currentSizeBytes = 0;
+    if (this.enableStats) {
+      this.stats.hits = 0;
+      this.stats.misses = 0;
+      this.stats.additions = 0;
+      this.stats.evictions = 0;
+    }
+    if (this.verbose) {
+      console.log('📦 Cache CLEARED');
+    }
+  }
+
+  /**
+   * Remove expired entries from cache
+   * Returns the number of entries removed
+   */
+  purgeExpired(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    const keys = Array.from(this.cache.keys());
+    for (const key of keys) {
+      const entry = this.cache.get(key);
+      if (entry) {
+        const age = now - entry.createdAt;
+        if (age > this.ttl) {
+          this._remove(key);
+          removed++;
+        }
+      }
+    }
+
+    if (this.verbose && removed > 0) {
+      console.log(`📦 Cache PURGED: ${removed} expired entries removed`);
+    }
+
+    return removed;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): CacheStats {
+    const totalRequests = this.stats.hits + this.stats.misses;
+
+    return {
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      additions: this.stats.additions,
+      evictions: this.stats.evictions,
+      size: this.cache.size,
+      sizeBytes: this.currentSizeBytes,
+      hitRate: totalRequests > 0 ? this.stats.hits / totalRequests : 0,
+      avgEntrySize: this.cache.size > 0 ? Math.round(this.currentSizeBytes / this.cache.size) : 0
+    };
+  }
+
+  /**
+   * Reset cache statistics
+   */
+  resetStats(): void {
+    this.stats.hits = 0;
+    this.stats.misses = 0;
+    this.stats.additions = 0;
+    this.stats.evictions = 0;
+  }
+
+  /**
+   * Get all cache keys (useful for debugging)
+   */
+  keys(): string[] {
+    return Array.from(this.cache.keys());
+  }
+
+  /**
+   * Get cache size
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Check if cache is empty
+   */
+  isEmpty(): boolean {
+    return this.cache.size === 0;
+  }
+
+  /**
+   * Evict least recently used entry (private method)
+   * Since we move accessed entries to the end, the first entry is the LRU
+   */
+  private _evictLRU(): void {
+    // Get the first key (least recently used)
+    const lruKey = this.cache.keys().next().value;
+
+    if (lruKey) {
+      const entry = this.cache.get(lruKey);
+      this._remove(lruKey);
+      this.stats.evictions++;
+
+      if (this.verbose) {
+        console.log(`📦 Cache EVICT: ${lruKey} (LRU, last accessed: ${entry ? new Date(entry.lastAccessed).toISOString() : 'unknown'})`);
+      }
+    }
+  }
+
+  /**
+   * Remove entry and update size tracking (private method)
+   */
+  private _remove(key: string): void {
+    const entry = this.cache.get(key);
+    if (entry) {
+      this.currentSizeBytes -= entry.size;
+      this.cache.delete(key);
+    }
+  }
+
+  /**
+   * Estimate size of data in bytes (private method)
+   */
+  private _estimateSize(data: unknown): number {
+    if (data === null || data === undefined) {
+      return 0;
+    }
+
+    if (typeof data === 'string') {
+      return data.length * 2; // UTF-16 uses 2 bytes per char
+    }
+
+    if (typeof data === 'number') {
+      return 8;
+    }
+
+    if (typeof data === 'boolean') {
+      return 4;
+    }
+
+    if (data instanceof ArrayBuffer || data instanceof SharedArrayBuffer) {
+      return data.byteLength;
+    }
+
+    if (Array.isArray(data)) {
+      return data.reduce((sum, item) => sum + this._estimateSize(item), 0);
+    }
+
+    if (typeof data === 'object') {
+      return JSON.stringify(data).length * 2;
+    }
+
+    return 100; // Default estimate
+  }
+
+  private _recordHit(): void {
+    if (this.enableStats) {
+      this.stats.hits++;
+    }
+  }
+
+  private _recordMiss(): void {
+    if (this.enableStats) {
+      this.stats.misses++;
+    }
+  }
+
+  private _recordAddition(): void {
+    if (this.enableStats) {
+      this.stats.additions++;
+    }
+  }
+}
+
+/**
+ * Generate a cache key from request parameters
+ *
+ * The key is generated based on:
+ * - HTTP method
+ * - URL
+ * - Vary headers (Authorization, Content-Type, etc.)
+ * - Request body (for POST/PUT/PATCH)
+ * - Query parameters
+ */
+export function generateCacheKey(options: CacheKeyOptions): string {
+  const parts: string[] = [];
+
+  // Method and URL form the base
+  parts.push(`${options.method}:${options.url}`);
+
+  // Add query parameters if present
+  if (options.params && Object.keys(options.params).length > 0) {
+    const sortedParams = Object.keys(options.params)
+      .sort()
+      .map(k => `${k}=${options.params![k]}`)
+      .join('&');
+    parts.push(sortedParams);
+  }
+
+  // Add vary headers (default: Authorization, Content-Type)
+  const varyHeaders = options.varyHeaders ?? ['authorization', 'content-type'];
+  if (options.headers) {
+    const headerValues: string[] = [];
+    for (const header of varyHeaders) {
+      const value = options.headers[header];
+      if (value) {
+        headerValues.push(`${header}:${value}`);
+      }
+    }
+    if (headerValues.length > 0) {
+      parts.push(headerValues.join(';'));
+    }
+  }
+
+  // Add body hash for POST/PUT/PATCH (simplified)
+  if (options.body && ['POST', 'PUT', 'PATCH'].includes(options.method)) {
+    const bodyStr = typeof options.body === 'string' ? options.body : JSON.stringify(options.body);
+    // Simple hash of body content
+    let hash = 0;
+    for (let i = 0; i < bodyStr.length; i++) {
+      const char = bodyStr.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash; // Convert to 32bit integer
+    }
+    parts.push(`body:${Math.abs(hash)}`);
+  }
+
+  return parts.join('|');
+}
+
+/**
+ * Create a response cache with default options for HTTP caching
+ */
+export function createResponseCache<T = unknown>(options?: CacheOptions): ResponseCache<T> {
+  return new ResponseCache<T>(options);
+}
+
+/**
+ * Global default cache instance (singleton pattern)
+ * Can be used across the application for shared caching
+ */
+let defaultCacheInstance: ResponseCache | null = null;
+
+/**
+ * Get or create the default cache instance
+ */
+export function getDefaultCache<T = unknown>(): ResponseCache<T> {
+  if (!defaultCacheInstance) {
+    defaultCacheInstance = new ResponseCache<T>({
+      maxSize: 200,
+      ttl: 300000, // 5 minutes
+      maxSizeBytes: 20 * 1024 * 1024, // 20MB
+      enableStats: true
+    });
+  }
+  return defaultCacheInstance as ResponseCache<T>;
+}
+
+/**
+ * Reset the default cache instance
+ */
+export function resetDefaultCache(): void {
+  if (defaultCacheInstance) {
+    defaultCacheInstance.clear();
+  }
+  defaultCacheInstance = null;
+}