/**
 * LRU (Least Recently Used) Cache Implementation
 *
 * Features:
 * - O(1) get, set, delete operations
 * - Configurable max size with automatic eviction
 * - Optional TTL (time-to-live) for entries
 * - Event emission for cache operations
 * - Statistics tracking
 *
 * Used to fix unbounded caches throughout the codebase.
 */
import { EventEmitter } from 'events';
export interface LRUCacheOptions<V> {
    maxSize: number;
    ttlMs?: number;
    /** Minimum TTL in ms - entries won't expire before this time */
    minTtlMs?: number;
    /** Maximum TTL in ms - entries always expire after this time */
    maxTtlMs?: number;
    /** Enable adaptive TTL based on access frequency */
    adaptiveTtl?: boolean;
    /** TTL multiplier for frequently accessed entries (default: 2) */
    frequencyTtlMultiplier?: number;
    /** Threshold for "frequently accessed" entries (default: 3) */
    frequencyThreshold?: number;
    onEvict?: (key: string, value: V) => void;
    /** Enable detailed metrics collection */
    enableMetrics?: boolean;
    /** Name for metrics identification */
    cacheName?: string;
}
export interface CacheEntry<V> {
    value: V;
    createdAt: number;
    accessedAt: number;
    /** Dynamic TTL for this entry (can be extended for hot entries) */
    ttlMs?: number;
    /** Number of times this entry has been accessed */
    accessCount: number;
    /** Size in bytes (if tracked) */
    sizeBytes?: number;
}
export interface CacheStats {
    name?: string;
    size: number;
    maxSize: number;
    hits: number;
    misses: number;
    evictions: number;
    hitRate: number;
    /** Average time entries stay in cache (ms) */
    avgResidenceTimeMs: number;
    /** Average access count per entry */
    avgAccessCount: number;
    /** Hot entries (accessed >= frequencyThreshold times) */
    hotEntries: number;
    /** Cold entries (accessed < frequencyThreshold times) */
    coldEntries: number;
    /** Total bytes stored (if size tracking enabled) */
    totalBytes: number;
    /** Latency metrics */
    latency: {
        avgGetMs: number;
        avgSetMs: number;
        p95GetMs: number;
        p99GetMs: number;
    };
}
/**
 * LRU Cache with TTL support and advanced metrics
 */
export declare class LRUCache<V = unknown> extends EventEmitter {
    private cache;
    private maxSize;
    private ttlMs;
    private minTtlMs;
    private maxTtlMs;
    private adaptiveTtl;
    private frequencyTtlMultiplier;
    private frequencyThreshold;
    private onEvict;
    private enableMetrics;
    private cacheName;
    private hits;
    private misses;
    private evictions;
    private totalBytes;
    private getLatencies;
    private setLatencies;
    private readonly maxLatencySamples;
    constructor(options: LRUCacheOptions<V>);
    /**
     * Get a value from the cache
     */
    get(key: string): V | undefined;
    /**
     * Extend TTL for hot entries
     */
    private extendTtl;
    /**
     * Record get latency for metrics
     */
    private recordGetLatency;
    /**
     * Record set latency for metrics
     */
    private recordSetLatency;
    /**
     * Set a value in the cache
     */
    set(key: string, value: V, options?: {
        ttlMs?: number;
        sizeBytes?: number;
    }): void;
    /**
     * Set with custom TTL (convenience method)
     */
    setWithTtl(key: string, value: V, ttlMs: number): void;
    /**
     * Check if key exists in cache
     */
    has(key: string): boolean;
    /**
     * Delete a key from the cache
     */
    delete(key: string): boolean;
    /**
     * Clear all entries
     */
    clear(): void;
    /**
     * Get cache size
     */
    get size(): number;
    /**
     * Get all keys
     */
    keys(): string[];
    /**
     * Get all values
     */
    values(): V[];
    /**
     * Get all entries
     */
    entries(): Array<[string, V]>;
    /**
     * Iterate over entries (non-expired only)
     */
    forEach(callback: (value: V, key: string) => void): void;
    /**
     * Symbol.iterator for for...of loops and spread operator
     */
    [Symbol.iterator](): Iterator<[string, V]>;
    /**
     * Convert to plain object (for JSON serialization)
     */
    toObject(): Record<string, V>;
    /**
     * Load entries from an object or Map
     */
    fromObject(data: Record<string, V> | Map<string, V>): void;
    /**
     * Get cache statistics
     */
    getStats(): CacheStats;
    /**
     * Calculate latency percentiles
     */
    private calculateLatencyStats;
    /**
     * Format statistics for display
     */
    formatStats(): string;
    /**
     * Reset statistics
     */
    resetStats(): void;
    /**
     * Remove expired entries
     */
    prune(): number;
    /**
     * Update max size (may trigger evictions)
     */
    setMaxSize(maxSize: number): void;
    /**
     * Dispose and clean up
     */
    dispose(): void;
    /**
     * Check if entry is expired (supports adaptive TTL)
     */
    private isExpired;
    /**
     * Get remaining TTL for an entry
     */
    getRemainingTtl(key: string): number | null;
    /**
     * Manually refresh TTL for an entry
     */
    touch(key: string): boolean;
    /**
     * Evict least recently used entry
     */
    private evictLRU;
    /**
     * Get or compute a value (cache-aside pattern)
     */
    getOrCompute(key: string, computeFn: () => Promise<V>, options?: {
        ttlMs?: number;
    }): Promise<V>;
    /**
     * Get or compute (sync version)
     */
    getOrComputeSync(key: string, computeFn: () => V, options?: {
        ttlMs?: number;
    }): V;
    /**
     * Export cache state for persistence
     */
    export(): {
        entries: Array<[string, CacheEntry<V>]>;
        stats: CacheStats;
    };
    /**
     * Import cache state from persistence
     */
    import(data: {
        entries: Array<[string, CacheEntry<V>]>;
    }): number;
}
/**
 * LRU Map - Drop-in replacement for Map with LRU eviction
 */
export declare class LRUMap<K, V> {
    private cache;
    private keyToString;
    constructor(maxSize: number, options?: {
        ttlMs?: number;
        keyToString?: (key: K) => string;
    });
    get(key: K): V | undefined;
    set(key: K, value: V): this;
    has(key: K): boolean;
    delete(key: K): boolean;
    clear(): void;
    get size(): number;
    values(): V[];
    getStats(): CacheStats;
    dispose(): void;
}
/**
 * Default cache sizes for different use cases
 */
export declare const CACHE_SIZES: {
    readonly SMALL: 100;
    readonly MEDIUM: 500;
    readonly LARGE: 1000;
    readonly XLARGE: 5000;
    readonly CHECKPOINT: 50;
    readonly CHUNK_STORE: 2000;
    readonly FILE_INDEX: 1000;
    readonly SYMBOL_INDEX: 5000;
    readonly MEMORY: 500;
    readonly ANALYSIS: 200;
    readonly REPAIR_HISTORY: 100;
    readonly CLIENT_POOL: 10;
};
/**
 * Default TTL values in milliseconds
 */
export declare const CACHE_TTL: {
    readonly SHORT: number;
    readonly MEDIUM: number;
    readonly LONG: number;
    readonly HOUR: number;
    readonly DAY: number;
};
/**
 * Create a checkpoint cache
 */
export declare function createCheckpointCache<V>(): LRUCache<V>;
/**
 * Create a chunk store cache
 */
export declare function createChunkStoreCache<V>(): LRUCache<V>;
/**
 * Create a memory cache
 */
export declare function createMemoryCache<V>(): LRUCache<V>;
/**
 * Create an analysis cache
 */
export declare function createAnalysisCache<V>(): LRUCache<V>;
