/**
 * @fileoverview LRU (Least Recently Used) Map implementation.
 *
 * Extends the built-in Map with automatic eviction when a maximum size is
 * exceeded. Uses Map's insertion-order iteration for O(1) LRU eviction.
 *
 * @module utils/lru-map
 */
/**
 * Configuration options for LRUMap.
 */
interface LRUMapOptions<K, V> {
    /** Maximum number of entries before eviction */
    maxSize: number;
    /** Optional callback when an entry is evicted */
    onEvict?: (key: K, value: V) => void;
}
/**
 * A Map with automatic LRU (Least Recently Used) eviction.
 *
 * When the map exceeds maxSize, the oldest entries are evicted.
 * Access via get() refreshes an entry's position (moves to most recent).
 *
 * Uses JavaScript Map's insertion-order guarantee for efficient LRU behavior.
 * All operations are O(1) amortized.
 *
 * @example
 * ```typescript
 * const cache = new LRUMap<string, number>({
 *   maxSize: 100,
 *   onEvict: (key, value) => console.log(`Evicted ${key}`)
 * });
 *
 * cache.set('a', 1);
 * cache.set('b', 2);
 * cache.get('a');  // Refreshes 'a', making 'b' the oldest
 * // When full, 'b' would be evicted first
 * ```
 */
export declare class LRUMap<K, V> extends Map<K, V> {
    private readonly maxSize;
    private readonly onEvict?;
    /** Tracks the newest key for O(1) newest() access */
    private _newestKey;
    /**
     * Creates a new LRUMap.
     *
     * @param options - Configuration options
     */
    constructor(options: LRUMapOptions<K, V>);
    /**
     * Set a key-value pair.
     * If key exists, updates value and refreshes position.
     * If adding new entry would exceed maxSize, evicts oldest entries.
     *
     * @param key - Key to set
     * @param value - Value to associate
     * @returns this (for chaining)
     */
    set(key: K, value: V): this;
    /**
     * Get a value and refresh its position (mark as most recently used).
     *
     * @param key - Key to look up
     * @returns Value if found, undefined otherwise
     */
    get(key: K): V | undefined;
    /**
     * Check if a key exists WITHOUT refreshing its position.
     * Use this when you want to check existence without affecting LRU order.
     *
     * @param key - Key to check
     * @returns True if key exists
     */
    has(key: K): boolean;
    /**
     * Delete a key-value pair.
     * Updates _newestKey if the deleted key was the newest.
     *
     * @param key - Key to delete
     * @returns True if the key existed and was deleted
     */
    delete(key: K): boolean;
    /**
     * Clear all entries.
     * Resets _newestKey to undefined.
     */
    clear(): void;
    /**
     * Peek at a value WITHOUT refreshing its position.
     * Use this when you want to read without affecting LRU order.
     *
     * @param key - Key to peek
     * @returns Value if found, undefined otherwise
     */
    peek(key: K): V | undefined;
    /**
     * Get the oldest entry (next to be evicted) without removing it.
     *
     * @returns [key, value] of oldest entry, or undefined if empty
     */
    oldest(): [K, V] | undefined;
    /**
     * Get the newest entry (most recently accessed).
     * O(1) operation using tracked newest key.
     *
     * @returns [key, value] of newest entry, or undefined if empty
     */
    newest(): [K, V] | undefined;
    /**
     * Evict entries older than a specific timestamp.
     * Assumes values have a timestamp property or are numbers representing time.
     *
     * @param maxAge - Maximum age in milliseconds
     * @param getTimestamp - Function to extract timestamp from value
     * @returns Number of entries evicted
     */
    expireOlderThan(maxAge: number, getTimestamp: (value: V) => number): number;
    /**
     * Get all keys in order from oldest to newest.
     *
     * @returns Array of keys
     */
    keysInOrder(): K[];
    /**
     * Get all values in order from oldest to newest.
     *
     * @returns Array of values
     */
    valuesInOrder(): V[];
    /**
     * Get the maximum size limit.
     */
    get maxEntries(): number;
    /**
     * Get the number of free slots before eviction would occur.
     */
    get freeSlots(): number;
}
export {};
//# sourceMappingURL=lru-map.d.ts.map