@evolplus/evo-utils/dist/cache.d.ts

Simple utilities solution.

/**
 * Interface defining the standard operations for a cache.
 *
 * @interface
 * @template T The type of items that the cache will store.
 */
export interface Cache<T> {
    put(key: string, value: T, expiry?: number): void;
    get(key: string): T | undefined;
    delete(key: string): void;
    capacity(): number;
    count(): number;
}
/**
 * Type definition for an individual cache item.
 *
 * @typedef {Object} CacheItem
 * @template T The type of the cache item's value.
 *
 * @property {string} [key] - The key associated with the cache item.
 * @property {T} [value] - The value of the cache item.
 * @property {number} [expiry] - The expiry time of the cache item.
 * @property {number} [score] - The score associated with the cache item (used in certain cache types).
 * @property {number} lastUpdate - The timestamp of the last update to the cache item.
 * @property {CacheItem} [prev] - Pointer to the previous cache item.
 * @property {CacheItem} [next] - Pointer to the next cache item.
 */
type CacheItem<T> = {
    key?: string;
    value?: T;
    expiry?: number;
    score?: number;
    lastUpdate: number;
    prev?: CacheItem<T>;
    next?: CacheItem<T>;
};
/**
 * Abstract class representing the basic structure and functionality of a cache.
 * Provides foundational methods and properties for specific cache implementations.
 *
 * @abstract
 * @template T The type of items that the cache will store.
 */
declare abstract class BasicCache<T> implements Cache<T> {
    private map;
    private _capacity;
    private _count;
    protected head: CacheItem<T>;
    protected tail: CacheItem<T>;
    /**
     * Creates an instance of the BasicCache class.
     * Initializes the cache with a specified capacity and sets up head and tail pointers for cache item order.
     *
     * @param {number} capacity - The maximum number of items the cache can hold.
     */
    constructor(capacity: number);
    /**
     * Adds an item to the cache or updates an existing item's value.
     * If the cache reaches its capacity, it evicts an item based on the specific cache's eviction policy.
     *
     * @param {string} key - The key associated with the item.
     * @param {T} value - The value to be stored in the cache.
     * @param {number} [expiry] - Optional expiry time for the item.
     */
    put(key: string, value: T, expiry?: number): void;
    /**
     * Retrieves an item from the cache based on its key.
     *
     * @param {string} key - The key associated with the item to be retrieved.
     * @returns {T | undefined} The value of the item if it exists, or undefined if it doesn't.
     */
    get(key: string): T | undefined;
    /**
     * Check a key is in the cache or not.
     *
     * @param {string} key - The key associated with the item to be checked.
     * @returns {boolean} True if the key is in the cache, otherwise false.
     */
    contains(key: string): boolean;
    /**
     * Removes an item from the cache based on its key.
     *
     * @param {string} key - The key associated with the item to be removed.
     */
    delete(key: string): void;
    /**
     * Protected method that remove a cache item from the linked list.
     * @param item Item being to be removed.
     */
    protected remove(item: CacheItem<T>): void;
    /**
     * Protected method that insert a cache item just after another item in the linked list.
     * @param item The item which already is in the list. The new item will be inserted at the position right after this item.
     * @param newItem The item that will be inserted into the list.
     */
    protected insertAfter(item: CacheItem<T>, newItem: CacheItem<T>): void;
    /**
     * Protected function that allow caller to query a cache item by its key.
     * @param key The key for querying.
     * @returns The cache item if it is found, otherwise returns undefined.
     */
    protected getItem(key: string): CacheItem<T> | undefined;
    /**
     * Returns the maximum capacity of the cache.
     *
     * @returns {number} The maximum number of items the cache can hold.
     */
    capacity(): number;
    /**
     * Returns the current number of items in the cache.
     *
     * @returns {number} The number of items currently stored in the cache.
     */
    count(): number;
    /**
     * Abstract method that implements the attaching of a new cache item.
     * @param item The cache item that will be attached to the linked list.
     */
    protected abstract attachItem(item: CacheItem<T>): void;
    /**
     * Abstract method that implements the logics of a cache item when it is hit by read.
     * @param item The cache item that will be calculated and/or processed.
     */
    protected abstract hitItem(item: CacheItem<T>): void;
}
/**
 * LRUCache class that extends BasicCache to implement the Least Recently Used (LRU) cache eviction policy.
 * Items that are accessed recently are moved to the front,
 * and the least recently used items are removed when the cache reaches its capacity.
 *
 * @extends {BasicCache<T>}
 * @template T The type of items that the cache will store.
 */
export declare class LRUCache<T> extends BasicCache<T> implements Cache<T> {
    /**
     * Creates an instance of the LRUCache class with a specified capacity.
     *
     * @param {number} capacity - The maximum number of items the cache can hold.
     */
    constructor(capacity: number);
    protected attachItem(item: CacheItem<T>): void;
    protected hitItem(item: CacheItem<T>): void;
}
/**
 * DecayCache class that extends BasicCache to implement a decay-based cache eviction policy.
 * Cache items have a score which decays over time. The score increases with each access,
 * and the item's position in the cache is adjusted based on its score relative to other items.
 *
 * @extends {BasicCache<T>}
 * @template T The type of items that the cache will store.
 */
export declare class DecayCache<T> extends BasicCache<T> implements Cache<T> {
    private halfLife;
    /**
     * Creates an instance of the DecayCache class with a specified capacity and half-life.
     *
     * @param {number} capacity - The maximum number of items the cache can hold.
     * @param {number} [halfLife=300000] - The time (in milliseconds) after which the score of a cache item is halved.
     */
    constructor(capacity: number, halfLife?: number);
    /**
     *
     * @param item Calculate decay of an item.
     * @param ts Timestamp of the time when this item is calculated.
     */
    private calculate;
    protected attachItem(item: CacheItem<T>): void;
    protected hitItem(item: CacheItem<T>): void;
    /**
     * A special method for DecayCache class.
     * @param key The key to be hit
     * @returns The decay score of the key.
     */
    hit(key: string): number;
}
export {};