jsm-core/dist/libraries/jsm-ttl-cache/index.d.ts

Core library for JSM project

/**
 * A simple Time-To-Live (TTL) cache implementation.
 * This cache stores key-value pairs with an expiration time.
 * Once the expiration time is reached, the key-value pair is automatically removed.
 *
 * @example
 * const cache = new TTLCache();
 * cache.set('key1', 'value1', 5000); // Stores 'value1' with a TTL of 5 seconds
 * console.log(cache.get('key1')); // Retrieves 'value1'
 * setTimeout(() => console.log(cache.get('key1')), 6000); // After 6 seconds, returns null
 */
export declare class TTLCache {
    private cache;
    private defaultTtl;
    /**
     * Creates an instance of TTLCache.
     * @param {number} [defaultTtl=60000] - The default Time-To-Live (TTL) for cache entries in milliseconds.
     */
    constructor(defaultTtl?: number);
    /**
     * Stores a key-value pair in the cache with an optional TTL.
     * @template T
     * @param {string} key - The key to store the value under.
     * @param {T} value - The value to store.
     * @param {number} [ttl=this.defaultTtl] - The Time-To-Live (TTL) for the cache entry in milliseconds.
     */
    set<T>(key: string, value: T, ttl?: number): void;
    /**
     * Retrieves a value from the cache by its key.
     * @template T
     * @param {string} key - The key of the value to retrieve.
     * @param {T | null} [defaultValue=null] - The default value to return if the key is not found or expired.
     * @returns {T | null} - The cached value or the default value if the key is not found or expired.
     */
    get<T>(key: string, defaultValue?: T | null): T | null;
    /**
     * Checks if a key exists in the cache and is not expired.
     * @param {string} key - The key to check.
     * @returns {boolean} - True if the key exists and is not expired, false otherwise.
     */
    has(key: string): boolean;
    /**
     * Deletes a key-value pair from the cache.
     * @param {string} key - The key to delete.
     */
    delete(key: string): void;
    /**
     * Clears all key-value pairs from the cache.
     */
    clear(): void;
    /**
     * Retrieves all keys currently stored in the cache.
     * @returns {string[]} - An array of keys that are not expired.
     */
    getKeys(): string[];
    /**
     * Retrieves all values currently stored in the cache.
     * @returns {any[]} - An array of values that are not expired.
     */
    getValues(): any[];
    /**
     * Retrieves the number of active (non-expired) entries in the cache.
     * @returns {number} - The number of active entries.
     */
    getSize(): number;
    /**
     * Retrieves the default TTL for cache entries.
     * @returns {number} - The default TTL in milliseconds.
     */
    getDefaultTtl(): number;
    /**
     * Updates the default TTL for cache entries.
     * @param {number} ttl - The new default TTL in milliseconds.
     * @throws {Error} - Throws an error if the TTL is not a positive number.
     */
    setDefaultTtl(ttl: number): void;
    /**
     * Converts the cache to a JSON object.
     * @returns {Record<string, any>} - A JSON object representation of the cache.
     */
    toJSON(): Record<string, any>;
    /**
     * Populates the cache from a JSON object.
     * @param {Record<string, any>} json - The JSON object to populate the cache from.
     * @param {number} [ttl=this.defaultTtl] - The TTL to apply to all entries.
     */
    fromJSON(json: Record<string, any>, ttl?: number): void;
}
export declare const ttlCache: TTLCache;