/**
 * QA360 LRU Cache Module
 *
 * Intelligent caching system for HTTP responses to avoid redundant requests.
 * Features:
 * - LRU (Least Recently Used) eviction policy
 * - TTL (Time To Live) expiration
 * - Size-based limits
 * - Cache key generation based on request parameters
 * - Thread-safe operations (async-friendly)
 * - Metrics and statistics
 *
 * @example
 * ```typescript
 * const cache = new ResponseCache({
 *   maxSize: 100,
 *   ttl: 60000, // 1 minute
 *   maxSizeBytes: 10 * 1024 * 1024 // 10MB
 * });
 *
 * const response = await cache.getOrFetch('GET:/api/users', async () => {
 *   return await fetch('/api/users');
 * });
 * ```
 */
/**
 * Cache entry containing response data and metadata
 */
export interface CacheEntry<T> {
    /** Cached response data */
    data: T;
    /** Timestamp when entry was created (ms) */
    createdAt: number;
    /** Timestamp when entry was last accessed (ms) */
    lastAccessed: number;
    /** Number of times this entry was accessed */
    hitCount: number;
    /** Size of the cached data in bytes (approximate) */
    size: number;
    /** Optional cache key for this entry */
    key?: string;
}
/**
 * Cache configuration options
 */
export interface CacheOptions {
    /** Maximum number of entries in the cache (default: 100) */
    maxSize?: number;
    /** Time to live for entries in milliseconds (default: 300000 = 5 minutes) */
    ttl?: number;
    /** Maximum total size of cache in bytes (default: 10MB) */
    maxSizeBytes?: number;
    /** Whether to enable cache statistics (default: true) */
    enableStats?: boolean;
    /** Whether to log cache operations (default: false) */
    verbose?: boolean;
}
/**
 * Cache statistics
 */
export interface CacheStats {
    /** Total number of cache hits */
    hits: number;
    /** Total number of cache misses */
    misses: number;
    /** Total number of entries added to cache */
    additions: number;
    /** Total number of entries evicted from cache */
    evictions: number;
    /** Current number of entries in cache */
    size: number;
    /** Current approximate size in bytes */
    sizeBytes: number;
    /** Cache hit rate (0-1) */
    hitRate: number;
    /** Average entry size in bytes */
    avgEntrySize: number;
}
/**
 * Cache key generation options
 */
export interface CacheKeyOptions {
    /** HTTP method (GET, POST, etc.) */
    method: string;
    /** Request URL/endpoint */
    url: string;
    /** Request headers (for cache key variation) */
    headers?: Record<string, string>;
    /** Request body (for POST/PUT/PATCH) */
    body?: string | Record<string, unknown>;
    /** Query parameters */
    params?: Record<string, string>;
    /** Vary headers (headers that affect cacheability) */
    varyHeaders?: string[];
}
/**
 * LRU Response Cache
 *
 * Thread-safe LRU cache with TTL and size-based eviction.
 */
export declare class ResponseCache<T = unknown> {
    private cache;
    private maxSize;
    private ttl;
    private maxSizeBytes;
    private currentSizeBytes;
    private enableStats;
    private verbose;
    private stats;
    constructor(options?: CacheOptions);
    /**
     * Get a value from cache by key
     * Returns undefined if not found or expired
     */
    get(key: string): T | undefined;
    /**
     * Set a value in cache by key
     * If key exists, updates the entry
     * If cache is full, evicts LRU entry
     */
    set(key: string, data: T, size?: number): void;
    /**
     * Get a value from cache, or compute and cache it if not present
     * This is the main method to use for caching operations
     */
    getOrFetch(key: string, fetchFn: () => Promise<T>, size?: number): Promise<T>;
    /**
     * Check if a key exists in cache and is not expired
     */
    has(key: string): boolean;
    /**
     * Delete a specific entry from cache
     */
    delete(key: string): boolean;
    /**
     * Clear all entries from cache
     */
    clear(): void;
    /**
     * Remove expired entries from cache
     * Returns the number of entries removed
     */
    purgeExpired(): number;
    /**
     * Get cache statistics
     */
    getStats(): CacheStats;
    /**
     * Reset cache statistics
     */
    resetStats(): void;
    /**
     * Get all cache keys (useful for debugging)
     */
    keys(): string[];
    /**
     * Get cache size
     */
    get size(): number;
    /**
     * Check if cache is empty
     */
    isEmpty(): boolean;
    /**
     * Evict least recently used entry (private method)
     * Since we move accessed entries to the end, the first entry is the LRU
     */
    private _evictLRU;
    /**
     * Remove entry and update size tracking (private method)
     */
    private _remove;
    /**
     * Estimate size of data in bytes (private method)
     */
    private _estimateSize;
    private _recordHit;
    private _recordMiss;
    private _recordAddition;
}
/**
 * Generate a cache key from request parameters
 *
 * The key is generated based on:
 * - HTTP method
 * - URL
 * - Vary headers (Authorization, Content-Type, etc.)
 * - Request body (for POST/PUT/PATCH)
 * - Query parameters
 */
export declare function generateCacheKey(options: CacheKeyOptions): string;
/**
 * Create a response cache with default options for HTTP caching
 */
export declare function createResponseCache<T = unknown>(options?: CacheOptions): ResponseCache<T>;
/**
 * Get or create the default cache instance
 */
export declare function getDefaultCache<T = unknown>(): ResponseCache<T>;
/**
 * Reset the default cache instance
 */
export declare function resetDefaultCache(): void;