/**
 * Cache Interface
 * Abstraction for caching operations following DIP
 */

export interface CacheStats {
  hits: number;
  misses: number;
  size: number;
  hitRate: number;
}

export interface ICache {
  /**
   * Get a value from cache
   */
  get<T>(key: string): T | null;

  /**
   * Set a value in cache with optional TTL
   */
  set<T>(key: string, data: T, ttlSeconds?: number): void;

  /**
   * Get or set a value in cache using a fetcher function
   */
  getOrSet<T>(key: string, fetcher: () => Promise<T>, ttlSeconds?: number): Promise<T>;

  /**
   * Delete a value from cache
   */
  delete(key: string): boolean;

  /**
   * Delete all values matching a pattern
   */
  deletePattern(pattern: string): number;

  /**
   * Clear the entire cache
   */
  clear(): void;

  /**
   * Check if a key exists and is not expired
   */
  has(key: string): boolean;

  /**
   * Get cache statistics
   */
  getStats(): CacheStats;

  /**
   * Get all keys in cache
   */
  keys(): string[];

  /**
   * Get cache size
   */
  size(): number;

  /**
   * Refresh TTL for a key
   */
  touch(key: string, ttlSeconds?: number): boolean;

  /**
   * Get time to live for a key in seconds
   */
  ttl(key: string): number | null;

  /**
   * Cleanup resources (for graceful shutdown)
   */
  destroy(): void;
}
