/**
 * Interface for cache provider implementations
 */
export interface CacheProvider {
  /**
   * Get a value from the cache
   * @param key Cache key
   * @returns Promise resolving to the cached value or undefined if not found
   */
  get<T>(key: string): Promise<T | undefined>;

  /**
   * Set a value in the cache
   * @param key Cache key
   * @param value Value to cache
   * @param ttl Time-to-live in milliseconds (optional)
   * @returns Promise resolving to true if successful
   */
  set<T>(key: string, value: T, ttl?: number): Promise<boolean>;

  /**
   * Delete a value from the cache
   * @param key Cache key
   * @returns Promise resolving to true if successful
   */
  delete(key: string): Promise<boolean>;

  /**
   * Check if a key exists in the cache
   * @param key Cache key
   * @returns Promise resolving to true if the key exists
   */
  has(key: string): Promise<boolean>;

  /**
   * Clear all values from the cache
   * @returns Promise resolving to true if successful
   */
  clear(): Promise<boolean>;

  /**
   * Get multiple values from the cache
   * @param keys Array of cache keys
   * @returns Promise resolving to a map of key-value pairs for found items
   */
  getMany<T>(keys: string[]): Promise<Map<string, T>>;

  /**
   * Set multiple values in the cache
   * @param entries Map of key-value pairs to cache
   * @param ttl Time-to-live in milliseconds (optional)
   * @returns Promise resolving to true if successful
   */
  setMany<T>(entries: Map<string, T>, ttl?: number): Promise<boolean>;

  /**
   * Delete multiple values from the cache
   * @param keys Array of cache keys to delete
   * @returns Promise resolving to true if successful
   */
  deleteMany(keys: string[]): Promise<boolean>;

  /**
   * Get the Time-To-Live (TTL) for a cache key
   * @param key Cache key
   * @returns Promise resolving to TTL in milliseconds, or undefined if not found
   */
  getTtl(key: string): Promise<number | undefined>;

  /**
   * Update the Time-To-Live (TTL) for a cache key
   * @param key Cache key
   * @param ttl New TTL in milliseconds
   * @returns Promise resolving to true if successful
   */
  updateTtl(key: string, ttl: number): Promise<boolean>;

  /**
   * Increment a numeric value in the cache
   * @param key Cache key
   * @param increment Amount to increment (default: 1)
   * @returns Promise resolving to the new value
   */
  increment(key: string, increment?: number): Promise<number>;

  /**
   * Decrement a numeric value in the cache
   * @param key Cache key
   * @param decrement Amount to decrement (default: 1)
   * @returns Promise resolving to the new value
   */
  decrement(key: string, decrement?: number): Promise<number>;

  /**
   * Connect to the cache backend
   * @returns Promise resolving when connected
   */
  connect(): Promise<void>;

  /**
   * Disconnect from the cache backend
   * @returns Promise resolving when disconnected
   */
  disconnect(): Promise<void>;

  /**
   * Get cache stats
   * @returns Promise resolving to cache statistics
   */
  getStats(): Promise<CacheStats>;
}

/**
 * Cache statistics
 */
export interface CacheStats {
  /**
   * Number of items in the cache
   */
  size: number;

  /**
   * Number of cache hits
   */
  hits: number;

  /**
   * Number of cache misses
   */
  misses: number;

  /**
   * Hit ratio (hits / (hits + misses))
   */
  hitRatio: number;

  /**
   * Additional provider-specific stats
   */
  [key: string]: any;
}