xpeditis2.0/apps/backend/src/domain/ports/out/cache.port.ts

/**
 * Cache Port
 *
 * Defines the interface for caching operations.
 * This is a secondary port (output port) in hexagonal architecture.
 */

export const CACHE_PORT = 'CachePort';

export interface CachePort {
  /**
   * Get a value from cache
   * Returns null if key doesn't exist
   */
  get<T>(key: string): Promise<T | null>;

  /**
   * Set a value in cache
   * @param key - Cache key
   * @param value - Value to store
   * @param ttlSeconds - Time to live in seconds (optional)
   */
  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;

  /**
   * Delete a key from cache
   */
  delete(key: string): Promise<void>;

  /**
   * Delete multiple keys from cache
   */
  deleteMany(keys: string[]): Promise<void>;

  /**
   * Check if a key exists in cache
   */
  exists(key: string): Promise<boolean>;

  /**
   * Get time to live for a key (in seconds)
   * Returns -2 if key doesn't exist, -1 if key has no expiration
   */
  ttl(key: string): Promise<number>;

  /**
   * Clear all cache entries
   */
  clear(): Promise<void>;

  /**
   * Get cache statistics
   */
  getStats(): Promise<{
    hits: number;
    misses: number;
    hitRate: number;
    keyCount: number;
  }>;
}