/**
 * @fileoverview Map with automatic TTL-based entry expiration.
 *
 * StaleExpirationMap automatically removes entries that haven't been accessed
 * within a configurable TTL (time-to-live). Useful for caches and tracking
 * ephemeral data that should be cleaned up after a period of inactivity.
 *
 * @module utils/stale-expiration-map
 */
import type { Disposable } from '../types.js';
/**
 * Configuration options for StaleExpirationMap.
 */
interface StaleExpirationMapOptions<K, V> {
    /** Time-to-live in milliseconds before entries expire */
    ttlMs: number;
    /** How often to run cleanup (default: ttlMs / 2) */
    cleanupIntervalMs?: number;
    /** Optional callback when an entry expires */
    onExpire?: (key: K, value: V) => void;
    /** Whether to refresh TTL on get (default: true) */
    refreshOnGet?: boolean;
}
/**
 * A Map that automatically expires entries after a TTL.
 *
 * Entries are removed if not accessed within the TTL period.
 * Periodic cleanup runs to remove expired entries.
 *
 * @example
 * ```typescript
 * const cache = new StaleExpirationMap<string, object>({
 *   ttlMs: 5 * 60 * 1000,  // 5 minutes
 *   onExpire: (key, value) => console.log(`Expired: ${key}`)
 * });
 *
 * cache.set('key1', { data: 'value' });
 * // After 5 minutes of no access, 'key1' will be automatically removed
 * ```
 */
export declare class StaleExpirationMap<K, V> implements Disposable {
    private entries;
    private cleanupTimer;
    private _isDisposed;
    private readonly ttlMs;
    private readonly cleanupIntervalMs;
    private readonly onExpire?;
    private readonly refreshOnGet;
    /**
     * Creates a new StaleExpirationMap.
     *
     * @param options - Configuration options
     */
    constructor(options: StaleExpirationMapOptions<K, V>);
    /**
     * Whether this map has been disposed.
     */
    get isDisposed(): boolean;
    /**
     * Number of entries in the map.
     */
    get size(): number;
    /**
     * Set a value with automatic TTL tracking.
     *
     * @param key - Key to set
     * @param value - Value to associate
     * @returns this (for chaining)
     */
    set(key: K, value: V): this;
    /**
     * Get a value, optionally refreshing its TTL.
     *
     * @param key - Key to look up
     * @returns Value if found and not expired, undefined otherwise
     */
    get(key: K): V | undefined;
    /**
     * Check if a key exists and is not expired.
     *
     * @param key - Key to check
     * @returns True if key exists and is not expired
     */
    has(key: K): boolean;
    /**
     * Peek at a value without refreshing its TTL.
     *
     * @param key - Key to peek
     * @returns Value if found and not expired, undefined otherwise
     */
    peek(key: K): V | undefined;
    /**
     * Delete an entry.
     *
     * @param key - Key to delete
     * @returns True if entry existed and was deleted
     */
    delete(key: K): boolean;
    /**
     * Clear all entries.
     */
    clear(): void;
    /**
     * Touch an entry to refresh its TTL without returning the value.
     *
     * @param key - Key to touch
     * @returns True if entry exists
     */
    touch(key: K): boolean;
    /**
     * Get the age of an entry in milliseconds.
     *
     * @param key - Key to check
     * @returns Age in ms, or undefined if not found
     */
    getAge(key: K): number | undefined;
    /**
     * Get remaining TTL for an entry in milliseconds.
     *
     * @param key - Key to check
     * @returns Remaining TTL in ms, or undefined if not found/expired
     */
    getRemainingTtl(key: K): number | undefined;
    /**
     * Iterate over all non-expired entries.
     */
    [Symbol.iterator](): IterableIterator<[K, V]>;
    /**
     * Get all keys (non-expired).
     */
    keys(): IterableIterator<K>;
    /**
     * Get all values (non-expired).
     */
    values(): IterableIterator<V>;
    /**
     * Run cleanup immediately, removing all expired entries.
     *
     * @returns Number of entries removed
     */
    cleanup(): number;
    /**
     * Dispose the map, stopping cleanup timer and clearing entries.
     */
    dispose(): void;
    /**
     * Check if an entry has expired.
     */
    private isExpired;
    /**
     * Start the periodic cleanup timer.
     */
    private startCleanup;
    /**
     * Stop the periodic cleanup timer.
     */
    private stopCleanup;
}
export {};
//# sourceMappingURL=stale-expiration-map.d.ts.map