/**
 * Generic Cache Manager Module
 *
 * Provides a type-safe, generic LRU cache with TTL support.
 * Can be used for any data type (Bitcoin balances, addresses, query results, etc.)
 *
 * Features:
 * - Generic type support
 * - TTL-based expiration
 * - LRU eviction policy
 * - Hit/miss statistics
 * - Memory-efficient
 * - Thread-safe operations
 */
import { Result } from '../../types/result';
import { SDKError } from '../../utils/error-handler';
/**
 * Cache entry with metadata
 */
interface CacheEntry<T> {
    /** Cached value */
    value: T;
    /** Unix timestamp when entry was created (ms) */
    timestamp: number;
    /** Number of times this entry was accessed */
    hits: number;
    /** Unix timestamp of last access (ms) */
    lastAccessed: number;
}
/**
 * Cache statistics
 */
export interface CacheStats {
    /** Current number of entries in cache */
    size: number;
    /** Total cache hits */
    hits: number;
    /** Total cache misses */
    misses: number;
    /** Total evictions performed */
    evictions: number;
    /** Timestamp of oldest entry (ms) */
    oldestEntry: number;
    /** Timestamp of newest entry (ms) */
    newestEntry: number;
    /** Hit rate as percentage (0-100) */
    hitRate: number;
}
/**
 * Cache configuration
 */
export interface CacheConfig {
    /** Maximum number of entries (default: 1000) */
    maxSize?: number;
    /** Time-to-live in milliseconds (default: 60000 = 1 minute) */
    ttlMs?: number;
    /** Enable debug logging (default: false) */
    debug?: boolean;
    /** Cache name for logging (default: 'Cache') */
    name?: string;
}
/**
 * Generic LRU Cache with TTL support
 *
 * @template K - Key type (usually string)
 * @template V - Value type
 *
 * @example
 * ```typescript
 * // Create a cache for Bitcoin balances
 * const balanceCache = new LRUCache<string, BitcoinBalance>({
 *   maxSize: 500,
 *   ttlMs: 60000,
 *   name: 'BitcoinBalance'
 * });
 *
 * // Set value
 * balanceCache.set('bc1q...', { balance: Satoshis(50000000n) });
 *
 * // Get value
 * const balance = balanceCache.get('bc1q...');
 * if (balance) {
 *   console.log('Cached balance:', balance.balance);
 * }
 * ```
 */
export declare class LRUCache<K, V> {
    private cache;
    /**
     * Audit M-J: singleflight registry for `getOrCompute` / `getOrComputeResult`.
     * Concurrent cache-miss callers for the same key share one inflight promise
     * instead of each running `compute()` independently — important when the
     * compute spends a paid LIT capacity credit or hits a rate-limited upstream.
     */
    private inflight;
    private inflightResult;
    private readonly maxSize;
    private readonly ttlMs;
    private readonly debug;
    private readonly name;
    private stats;
    constructor(config?: CacheConfig);
    /**
     * Get value from cache
     *
     * Returns null if:
     * - Key not found
     * - Entry has expired
     *
     * @param key - Cache key
     * @returns Cached value or null
     */
    get(key: K): V | null;
    /**
     * Get value from cache with Result wrapper
     *
     * Useful when you want to distinguish between "not found" and "expired"
     */
    getResult(key: K): Result<V, SDKError>;
    /**
     * Set value in cache
     *
     * If cache is full, evicts the least recently used entry
     *
     * @param key - Cache key
     * @param value - Value to cache
     * @param ttl - Optional custom TTL for this entry (ms)
     */
    set(key: K, value: V, ttl?: number): void;
    /**
     * Set value in cache with Result wrapper
     */
    setResult(key: K, value: V, ttl?: number): Result<void, SDKError>;
    /**
     * Check if key exists in cache (without affecting stats)
     */
    has(key: K): boolean;
    /**
     * Delete specific key from cache
     */
    delete(key: K): boolean;
    /**
     * Clear entire cache
     */
    clear(): void;
    /**
     * Get current cache size
     */
    size(): number;
    /**
     * Get cache statistics
     */
    getStats(): CacheStats;
    /**
     * Get hit rate percentage
     */
    getHitRate(): number;
    /**
     * Get all cached keys (for debugging)
     */
    getKeys(): K[];
    /**
     * Get all cached values (for debugging)
     */
    getValues(): V[];
    /**
     * Get all cache entries with metadata (for debugging)
     */
    getEntries(): Array<{
        key: K;
        value: V;
        metadata: Omit<CacheEntry<V>, 'value'>;
    }>;
    /**
     * Clean up expired entries
     *
     * Useful for periodic maintenance
     *
     * @returns Number of entries cleaned
     */
    cleanExpired(): number;
    /**
     * Check if cache entry is expired
     */
    private isExpired;
    /**
     * Evict least recently used entry
     */
    private evictLRU;
    /**
     * Get or compute value
     *
     * If key exists in cache, returns cached value.
     * Otherwise, computes value using provided function and caches it.
     *
     * @param key - Cache key
     * @param compute - Function to compute value if not in cache
     * @param ttl - Optional custom TTL for this entry
     * @returns Cached or computed value
     */
    getOrCompute(key: K, compute: () => Promise<V>, ttl?: number): Promise<V>;
    /**
     * Get or compute value with Result wrapper
     */
    getOrComputeResult(key: K, compute: () => Promise<Result<V, SDKError>>, ttl?: number): Promise<Result<V, SDKError>>;
}
/**
 * Generic cache interface for type safety
 */
export interface Cache<T> {
    get(key: string): T | null | undefined;
    set(key: string, value: T): void;
    delete(key: string): boolean;
    clear(): void;
    has(key: string): boolean;
    size(): number;
    getStats(): CacheStats;
}
/**
 * Cache Manager - Factory for creating specialized caches
 */
export declare class CacheManager {
    private caches;
    private readonly globalConfig;
    constructor(globalConfig?: CacheConfig);
    /**
     * Create or get a named cache
     *
     * @param name - Unique cache name
     * @param config - Optional cache-specific configuration
     * @returns LRU cache instance
     */
    getCache<K, V>(name: string, config?: CacheConfig): LRUCache<K, V>;
    /**
     * Clear all caches
     */
    clearAll(): void;
    /**
     * Clean expired entries from all caches
     */
    cleanAllExpired(): number;
    /**
     * Get statistics for all caches
     */
    getAllStats(): Record<string, CacheStats>;
    /**
     * Get list of all cache names
     */
    getCacheNames(): string[];
    /**
     * Delete a named cache
     */
    deleteCache(name: string): boolean;
}
/**
 * Factory function to create a CacheManager instance
 */
export declare function createCacheManager(config?: CacheConfig): CacheManager;
export {};
