/**
 * Shared cache types and interfaces
 *
 * These types provide consistency across all domain-specific cache services.
 */

/**
 * Cache bucket metrics for hit/miss tracking
 */
export interface CacheBucketMetrics {
  hits: number;
  misses: number;
}

/**
 * Cache dependencies for tracking relationships between cached data
 * Used for granular invalidation (e.g., invalidate all catalog entries that depend on Product X)
 */
export interface CacheDependencies {
  productIds?: string[];
  accountIds?: string[];
  [key: string]: string[] | undefined;
}

/**
 * Options for cache operations
 */
export interface CacheOptions<T> {
  /**
   * Whether to cache null values
   * @default false
   */
  allowNull?: boolean;

  /**
   * TTL in seconds (null = no expiry, CDC-driven invalidation only)
   * @default null
   */
  ttl?: number | null;

  /**
   * Callback to resolve cache dependencies for granular invalidation
   */
  resolveDependencies?: (
    value: T
  ) => CacheDependencies | Promise<CacheDependencies | undefined> | undefined;
}

// ============================================================================
// Cache Coordinator Types
// ============================================================================

/**
 * A single cache invalidation operation
 */
export interface CacheOperation {
  /** Human-readable operation name for logging */
  name: string;
  /** The invalidation function to execute */
  execute: () => Promise<void>;
}

/**
 * Error details from a failed cache operation
 */
export interface CacheInvalidationError {
  /** Name of the failed operation */
  operation: string;
  /** The original error */
  error: unknown;
  /** Extracted error message */
  message: string;
}

/**
 * Result of a coordinated cache invalidation
 */
export interface CacheInvalidationResult {
  /** Whether all operations succeeded */
  success: boolean;
  /** Number of operations attempted */
  attempted: number;
  /** Number of successful operations */
  succeeded: number;
  /** Number of failed operations */
  failed: number;
  /** Details of any failures */
  errors: CacheInvalidationError[];
}

/**
 * Metrics tracked by the CacheCoordinator
 */
export interface CacheCoordinatorMetrics {
  /** Total invalidation calls made */
  totalInvalidations: number;
  /** Total individual operations executed */
  totalOperations: number;
  /** Total operation failures */
  totalErrors: number;
}
