lrufy/dist/lru-cache.d.ts

A feature-rich LRU cache implementation with TTL support, custom sizing, and event hooks

/**
 * Options for an individual cache item
 */
export interface ItemOptions {
    /**
     * Time-to-live in milliseconds
     */
    ttl?: number;
    /**
     * Size of the item (defaults to 1 if size calculation is not provided)
     */
    size?: number;
}
/**
 * Function to calculate the size of a cached item
 */
export type SizeCalculator<K, V> = (value: V, key: K) => number;
/**
 * Function called when an item is disposed from the cache
 */
export type DisposeCallback<K, V> = (value: V, key: K, reason: EvictionReason) => void | Promise<void>;
/**
 * Statistics about cache performance
 */
export interface CacheStats {
    /**
     * Total number of items in the cache
     */
    size: number;
    /**
     * Number of successful cache hits
     */
    hits: number;
    /**
     * Number of cache misses
     */
    misses: number;
    /**
     * Total size of all items in the cache (if sizeCalculation is used)
     */
    totalSize: number;
    /**
     * Ratio of hits to total accesses
     */
    hitRate: number;
}
/**
 * Reason an item was evicted from the cache
 */
export declare enum EvictionReason {
    /**
     * Item was manually deleted
     */
    DELETED = "deleted",
    /**
     * Item was evicted due to capacity constraints
     */
    EVICTED = "evicted",
    /**
     * Item expired due to TTL
     */
    EXPIRED = "expired",
    /**
     * Item was overwritten with a new value
     */
    OVERWRITTEN = "overwritten",
    /**
     * Cache was manually cleared
     */
    CACHE_CLEAR = "clear"
}
/**
 * Options for configuring the LRU cache
 */
export interface LRUCacheOptions<K, V> {
    /**
     * Maximum number of items in the cache
     */
    max?: number;
    /**
     * Maximum size of all items in the cache combined
     */
    maxSize?: number;
    /**
     * Default time-to-live for cache items in milliseconds
     */
    ttl?: number;
    /**
     * Function to calculate the size of items
     */
    sizeCalculation?: SizeCalculator<K, V>;
    /**
     * Function called when an item is disposed
     */
    dispose?: DisposeCallback<K, V> | null;
    /**
     * Whether to not call dispose when an item is overwritten
     */
    noDisposeOnSet?: boolean;
    /**
     * Whether to allow returning stale (expired) items before removing them
     */
    allowStale?: boolean;
    /**
     * How often to check for and remove expired items (ms), disabled if 0
     */
    pruneInterval?: number;
    /**
     * Whether to dispose of items asynchronously
     */
    asyncDispose?: boolean;
}
/**
 * A fully-featured Least Recently Used (LRU) cache implementation
 * with optional TTL, custom sizing, and event hooks
 */
export declare class LRUCache<K = string, V = any> {
    private cache;
    private list;
    private readonly options;
    private totalSize;
    private pruneTimer;
    private hits;
    private misses;
    /**
     * Creates a new LRU cache instance
     * @param options - Configuration options for the cache
     */
    constructor(options?: LRUCacheOptions<K, V>);
    /**
     * Gets the current size of the cache
     */
    get size(): number;
    /**
     * Retrieves an item from the cache
     * @param key - The key to retrieve
     * @returns The cached value or undefined if not found
     */
    get(key: K): V | undefined;
    /**
     * Checks if a key exists in the cache without updating its recency
     * @param key - The key to check
     * @returns True if the key exists and is not expired
     */
    has(key: K): boolean;
    /**
     * Gets an item without updating its recency
     * @param key - The key to retrieve
     * @returns The cached value or undefined if not found
     */
    peek(key: K): V | undefined;
    /**
     * Adds or updates an item in the cache
     * @param key - The key to set
     * @param value - The value to cache
     * @param options - Options for this specific item
     * @returns The cache instance for chaining
     */
    set(key: K, value: V, options?: ItemOptions): this;
    /**
     * Removes an item from the cache
     * @param key - The key to remove
     * @param reason - The reason for removal (for dispose callback)
     * @returns True if the item was found and removed
     */
    delete(key: K, reason?: EvictionReason): boolean;
    /**
     * Clears all items from the cache
     */
    clear(): void;
    /**
     * Retrieves cache statistics
     * @returns An object with cache statistics
     */
    getStats(): CacheStats;
    /**
     * Removes all expired items from the cache
     * @returns Number of items pruned
     */
    prune(): number;
    /**
     * Serializes the cache to a JSON-friendly format
     * @returns An array of entries that can be used to reconstruct the cache
     */
    serialize(): Array<[K, V, ItemOptions]>;
    /**
     * Loads serialized data into the cache
     * @param data - Serialized cache data from serialize()
     * @returns The cache instance for chaining
     */
    deserialize(data: Array<[K, V, ItemOptions]>): this;
    /**
     * Starts the automatic pruning timer
     */
    private startPruneTimer;
    /**
     * Handles disposing of an item
     */
    private disposeItem;
}