@catbee/utils/cache/index.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/*
 * The MIT License
 * 
 * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/**
 * Options for configuring a TTLCache instance.
 */
interface TTLCacheOptions {
    /** Default time-to-live in milliseconds for cache entries */
    ttlMs?: number;
    /** Maximum number of entries to keep in cache (uses LRU eviction policy) */
    maxSize?: number;
    /** Auto-cleanup interval in milliseconds (disabled if 0 or negative) */
    autoCleanupMs?: number;
}
/**
 * An in-memory cache with time-to-live (TTL) support for each entry.
 *
 * @typeParam K - Type of the key.
 * @typeParam V - Type of the value.
 *
 * @example
 * const cache = new TTLCache<string, number>({ ttlMs: 1000 });
 * cache.set("x", 123);
 * const value = cache.get("x"); // 123
 */
declare class TTLCache<K, V> {
    private readonly cache;
    private readonly ttlMs;
    private readonly maxSize?;
    private cleanupInterval?;
    /**
     * @param options - Configuration options for the cache
     */
    constructor(options?: TTLCacheOptions);
    /**
     * Sets a key-value pair in the cache with the default TTL.
     *
     * @param key - The key to set.
     * @param value - The value to associate with the key.
     */
    set(key: K, value: V): void;
    /**
     * Sets a key-value pair in the cache with a custom TTL.
     *
     * @param key - The key to set.
     * @param value - The value to associate with the key.
     * @param ttlMs - Time-to-live in milliseconds.
     */
    setWithTTL(key: K, value: V, ttlMs: number): void;
    /**
     * Retrieves the value for a given key if it hasn't expired.
     *
     * @param key - The key to retrieve.
     * @returns The cached value, or undefined if not found or expired.
     */
    get(key: K): V | undefined;
    /**
     * Retrieves or computes a value if it's not in the cache or has expired.
     *
     * @param key - The key to retrieve
     * @param producer - Function to generate the value if not cached
     * @param ttlMs - Optional custom TTL for the computed value
     * @returns The cached or computed value
     */
    getOrCompute(key: K, producer: () => Promise<V>, ttlMs?: number): Promise<V>;
    /**
     * Checks if the key exists and hasn't expired.
     *
     * @param key - The key to check.
     * @returns `true` if key exists and is valid, otherwise `false`.
     */
    has(key: K): boolean;
    /**
     * Deletes a key from the cache.
     *
     * @param key - The key to delete.
     * @returns `true` if the key existed and was removed, `false` otherwise.
     */
    delete(key: K): boolean;
    /**
     * Clears all entries from the cache.
     */
    clear(): void;
    /**
     * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).
     *
     * @returns Number of items in the cache (may include expired keys).
     */
    size(): number;
    /**
     * Set multiple key-value pairs at once with the default TTL.
     *
     * @param entries - Array of [key, value] tuples to set
     */
    setMany(entries: [K, V][]): void;
    /**
     * Get multiple values at once.
     *
     * @param keys - Array of keys to retrieve
     * @returns Array of values (undefined for keys that don't exist or expired)
     */
    getMany(keys: K[]): (V | undefined)[];
    /**
     * Removes all expired entries from the cache.
     *
     * @returns Number of entries removed.
     */
    cleanup(): number;
    /**
     * Returns an iterator of all current valid [key, value] pairs.
     *
     * @returns IterableIterator<[K, V]>
     */
    entries(): IterableIterator<[K, V]>;
    /**
     * Returns an iterator of all current valid keys.
     *
     * @returns IterableIterator<K>
     */
    keys(): IterableIterator<K>;
    /**
     * Returns an iterator of all current valid values.
     *
     * @returns IterableIterator<V>
     */
    values(): IterableIterator<V>;
    /**
     * Extends the expiration of a key by the specified time or default TTL.
     *
     * @param key - The key to refresh
     * @param ttlMs - Optional new TTL in milliseconds (uses default if not specified)
     * @returns true if the key was found and refreshed, false otherwise
     */
    refresh(key: K, ttlMs?: number): boolean;
    /**
     * Returns a snapshot of cache stats.
     *
     * @returns Object containing cache statistics
     */
    stats(): {
        size: number;
        validEntries: number;
        expiredEntries: number;
        maxSize: number | undefined;
    };
    /**
     * Stop the auto-cleanup interval if it's running.
     */
    destroy(): void;
    /**
     * Evict the least recently used entry from the cache.
     * @private
     */
    private evictLRU;
}

export { TTLCache };
export type { TTLCacheOptions };