/**
 * Key-Value Store types for distributed caching with TTL support
 */

/**
 * KV operation result
 */
export interface KVOperationResult<T = unknown> {
  /** Whether operation succeeded */
  success: boolean;

  /** Retrieved value (for get operations) */
  value?: T;

  /** Whether key exists */
  exists: boolean;

  /** Error if operation failed */
  error?: {
    type: string;
    reason: string;
  };

  /** Version info for optimistic concurrency */
  version?: {
    seqNo: number;
    primaryTerm: number;
  };

  /** Expiration timestamp (for TTL keys) */
  expiresAt?: Date;

  /** Cache hit/miss info */
  cacheHit?: boolean;
}

/**
 * KV set options
 */
export interface KVSetOptions {
  /** Time-to-live in seconds */
  ttl?: number;

  /** Only set if key doesn't exist */
  nx?: boolean;

  /** Only set if key exists */
  xx?: boolean;

  /** Optimistic concurrency control */
  ifSeqNo?: number;
  ifPrimaryTerm?: number;

  /** Routing value */
  routing?: string;

  /** Pipeline to execute */
  pipeline?: string;

  /** Skip cache and write directly to Elasticsearch */
  skipCache?: boolean;
}

/**
 * KV get options
 */
export interface KVGetOptions {
  /** Return default value if key doesn't exist */
  default?: unknown;

  /** Skip cache and read directly from Elasticsearch */
  skipCache?: boolean;

  /** Routing value */
  routing?: string;
}

/**
 * KV delete options
 */
export interface KVDeleteOptions {
  /** Optimistic concurrency control */
  ifSeqNo?: number;
  ifPrimaryTerm?: number;

  /** Routing value */
  routing?: string;

  /** Also remove from cache */
  invalidateCache?: boolean;
}

/**
 * KV scan options
 */
export interface KVScanOptions {
  /** Pattern to match keys (supports wildcards) */
  pattern?: string;

  /** Maximum keys to return */
  limit?: number;

  /** Scroll cursor for pagination */
  cursor?: string;

  /** Include values in scan results */
  includeValues?: boolean;

  /** Routing value */
  routing?: string;
}

/**
 * KV scan result
 */
export interface KVScanResult<T = unknown> {
  /** Matched keys */
  keys: string[];

  /** Values (if includeValues was true) */
  values?: T[];

  /** Next cursor for pagination */
  nextCursor?: string;

  /** Total matches found */
  total: number;

  /** Whether there are more results */
  hasMore: boolean;
}

/**
 * Cache eviction policy
 */
export type CacheEvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl';

/**
 * Cache statistics
 */
export interface CacheStats {
  /** Total cache entries */
  size: number;

  /** Maximum cache size */
  maxSize: number;

  /** Cache hits */
  hits: number;

  /** Cache misses */
  misses: number;

  /** Hit ratio */
  hitRatio: number;

  /** Total evictions */
  evictions: number;

  /** Memory usage estimate (bytes) */
  memoryUsage: number;
}

/**
 * KV Store configuration
 */
export interface KVStoreConfig {
  /** Index name for key-value storage */
  index: string;

  /** Default TTL in seconds */
  defaultTTL?: number;

  /** Enable in-memory caching */
  enableCache?: boolean;

  /** Maximum cache entries */
  cacheMaxSize?: number;

  /** Cache eviction policy */
  cacheEvictionPolicy?: CacheEvictionPolicy;

  /** Cache TTL in seconds (separate from KV TTL) */
  cacheTTL?: number;

  /** Enable automatic expiration cleanup */
  enableExpirationCleanup?: boolean;

  /** Expiration cleanup interval in seconds */
  cleanupIntervalSeconds?: number;

  /** Batch size for cleanup operations */
  cleanupBatchSize?: number;

  /** Default routing for all operations */
  defaultRouting?: string;

  /** Enable compression for large values */
  enableCompression?: boolean;

  /** Compression threshold in bytes */
  compressionThreshold?: number;

  /** Refresh policy */
  refresh?: boolean | 'wait_for';

  /** Enable optimistic concurrency by default */
  enableOptimisticConcurrency?: boolean;
}

/**
 * KV Store statistics
 */
export interface KVStoreStats {
  /** Total keys stored */
  totalKeys: number;

  /** Total get operations */
  totalGets: number;

  /** Total set operations */
  totalSets: number;

  /** Total delete operations */
  totalDeletes: number;

  /** Total scan operations */
  totalScans: number;

  /** Total expired keys cleaned */
  totalExpired: number;

  /** Cache statistics */
  cacheStats?: CacheStats;

  /** Average operation duration */
  avgGetDurationMs: number;
  avgSetDurationMs: number;
  avgDeleteDurationMs: number;

  /** Storage size estimate (bytes) */
  storageSize: number;
}

/**
 * Internal KV document structure
 */
export interface KVDocument<T = unknown> {
  /** The key */
  key: string;

  /** The value */
  value: T;

  /** Creation timestamp */
  createdAt: Date;

  /** Last update timestamp */
  updatedAt: Date;

  /** Expiration timestamp (null = no expiration) */
  expiresAt: Date | null;

  /** Metadata */
  metadata?: {
    size?: number;
    compressed?: boolean;
    contentType?: string;
    tags?: string[];
  };
}

/**
 * Cache entry
 */
export interface CacheEntry<T = unknown> {
  /** Cached value */
  value: T;

  /** Cache entry creation time */
  cachedAt: Date;

  /** Cache entry expiration time */
  expiresAt?: Date;

  /** Last access time (for LRU) */
  lastAccessedAt: Date;

  /** Access count (for LFU) */
  accessCount: number;

  /** Entry size estimate */
  size: number;

  /** Version info */
  version?: {
    seqNo: number;
    primaryTerm: number;
  };
}

/**
 * Batch get result
 */
export interface KVBatchGetResult<T = unknown> {
  /** Key-value map of results */
  results: Map<string, KVOperationResult<T>>;

  /** Number of keys found */
  found: number;

  /** Number of keys not found */
  notFound: number;

  /** Cache hit count */
  cacheHits: number;
}

/**
 * Batch set result
 */
export interface KVBatchSetResult {
  /** Number of successful sets */
  successful: number;

  /** Number of failed sets */
  failed: number;

  /** Individual results */
  results: Map<string, KVOperationResult>;
}

/**
 * Batch delete result
 */
export interface KVBatchDeleteResult {
  /** Number of successful deletes */
  successful: number;

  /** Number of failed deletes */
  failed: number;

  /** Individual results */
  results: Map<string, KVOperationResult>;
}