/**
 * Unified Cache Types
 *
 * This module provides common cache type definitions that can be used
 * throughout the codebase. Instead of each module defining its own
 * CacheEntry/CacheStats, import from here for consistency.
 *
 * Migration guide:
 * - Use BaseCacheEntry<T> for simple key-value caches
 * - Use TimedCacheEntry<T> for TTL-based caches
 * - Use LRUCacheEntry<T> for LRU caches with access tracking
 * - Use BaseCacheStats for basic statistics
 * - Use DetailedCacheStats for comprehensive statistics
 */
/**
 * Minimal cache entry - just value and timestamp
 */
export interface BaseCacheEntry<T = unknown> {
    value: T;
    timestamp: number;
}
/**
 * Cache entry with TTL/expiration
 */
export interface TimedCacheEntry<T = unknown> extends BaseCacheEntry<T> {
    expiresAt: number;
    ttl?: number;
}
/**
 * LRU cache entry with access tracking
 */
export interface LRUCacheEntry<T = unknown> extends BaseCacheEntry<T> {
    createdAt: number;
    accessedAt: number;
    accessCount?: number;
}
/**
 * Full-featured cache entry combining all fields
 */
export interface FullCacheEntry<T = unknown> {
    key?: string;
    value: T;
    timestamp: number;
    createdAt: number;
    accessedAt: number;
    expiresAt?: number;
    ttl?: number;
    accessCount?: number;
    metadata?: Record<string, unknown>;
}
/**
 * Basic cache statistics
 */
export interface BaseCacheStats {
    size: number;
    hits: number;
    misses: number;
    hitRate: number;
}
/**
 * Detailed cache statistics with eviction tracking
 */
export interface DetailedCacheStats extends BaseCacheStats {
    maxSize: number;
    evictions: number;
    totalEntries?: number;
    savedTime?: number;
    savedCalls?: number;
}
/**
 * Cache statistics with breakdown by type/category
 */
export interface CategorizedCacheStats extends DetailedCacheStats {
    byCategory?: Record<string, number>;
    byType?: Record<string, number>;
}
/**
 * Base cache configuration
 */
export interface BaseCacheConfig {
    maxSize: number;
    ttlMs?: number;
    enabled?: boolean;
}
/**
 * LRU cache configuration
 */
export interface LRUCacheConfig<T = unknown> extends BaseCacheConfig {
    onEvict?: (key: string, value: T) => void;
    onExpire?: (key: string, value: T) => void;
}
/**
 * Semantic cache configuration (for similarity-based caching)
 */
export interface SemanticCacheConfig extends BaseCacheConfig {
    similarityThreshold: number;
    embeddingDimension?: number;
}
/**
 * Result of a cache lookup
 */
export interface CacheLookupResult<T = unknown> {
    found: boolean;
    value?: T;
    expired?: boolean;
    age?: number;
}
/**
 * Cache operation event
 */
export interface CacheEvent<T = unknown> {
    type: 'get' | 'set' | 'delete' | 'evict' | 'expire' | 'clear';
    key: string;
    value?: T;
    timestamp: number;
}
/**
 * Check if an object is a valid cache entry
 */
export declare function isCacheEntry<T>(obj: unknown): obj is BaseCacheEntry<T>;
/**
 * Check if a cache entry has expired
 */
export declare function isExpired(entry: TimedCacheEntry | FullCacheEntry): boolean;
/**
 * Calculate cache hit rate
 */
export declare function calculateHitRate(hits: number, misses: number): number;
/**
 * Create a basic cache entry
 */
export declare function createCacheEntry<T>(value: T): BaseCacheEntry<T>;
/**
 * Create a timed cache entry
 */
export declare function createTimedCacheEntry<T>(value: T, ttlMs: number): TimedCacheEntry<T>;
/**
 * Create an LRU cache entry
 */
export declare function createLRUCacheEntry<T>(value: T): LRUCacheEntry<T>;
/**
 * Create initial cache statistics
 */
export declare function createCacheStats(maxSize?: number): DetailedCacheStats;
/**
 * Generic cache interface
 */
export interface ICache<T = unknown> {
    get(key: string): T | undefined;
    set(key: string, value: T, ttl?: number): void;
    has(key: string): boolean;
    delete(key: string): boolean;
    clear(): void;
    size(): number;
    getStats?(): BaseCacheStats | DetailedCacheStats;
}
/**
 * Async cache interface (for persistence-backed caches)
 */
export interface IAsyncCache<T = unknown> {
    get(key: string): Promise<T | undefined>;
    set(key: string, value: T, ttl?: number): Promise<void>;
    has(key: string): Promise<boolean>;
    delete(key: string): Promise<boolean>;
    clear(): Promise<void>;
}
