transitory/dist/types/cache/bounded/BoundedCache.d.ts

In-memory cache with high hit rates via LFU eviction. Supports time-based expiration, automatic loading and metrics.

import { AbstractCache } from '../AbstractCache';
import { Cache } from '../Cache';
import { CacheSPI } from '../CacheSPI';
import { KeyType } from '../KeyType';
import { Metrics } from '../metrics/Metrics';
import { RemovalListener } from '../RemovalListener';
import { ON_REMOVE, ON_MAINTENANCE, TRIGGER_REMOVE, MAINTENANCE } from '../symbols';
import { Weigher } from '../Weigher';
declare const DATA: unique symbol;
/**
 * Options usable with a BoundedCache.
 */
export interface BoundedCacheOptions<K extends KeyType, V> {
    /**
     * The maximum size of the cache. For unweighed caches this is the maximum
     * number of entries in the cache, for weighed caches this is the maximum
     * weight of the cache.
     */
    maxSize: number;
    /**
     * Weigher function to use. If this is specified the cache turns into
     * a weighted cache and the function is called when cached data is stored
     * to determine its weight.
     */
    weigher?: Weigher<K, V> | null;
    /**
     * Listener to call whenever something is removed from the cache.
     */
    removalListener?: RemovalListener<K, V> | null;
}
/**
 * Bounded cache implementation using W-TinyLFU to keep track of data.
 *
 * See https://arxiv.org/pdf/1512.00727.pdf for details about TinyLFU and
 * the W-TinyLFU optimization.
 */
export declare class BoundedCache<K extends KeyType, V> extends AbstractCache<K, V> implements Cache<K, V>, CacheSPI<K, V> {
    private [DATA];
    [ON_REMOVE]?: RemovalListener<K, V>;
    [ON_MAINTENANCE]?: () => void;
    constructor(options: BoundedCacheOptions<K, V>);
    /**
     * Get the maximum size this cache can be.
     *
     * @returns
     *   maximum size of the cache
     */
    get maxSize(): number;
    /**
     * Get the current size of the cache.
     *
     * @returns
     *   items currently in the cache
     */
    get size(): number;
    /**
     * Get the weighted size of all items in the cache.
     *
     * @returns
     *   the weighted size of all items in the cache
     */
    get weightedSize(): number;
    /**
     * Store a value tied to the specified key. Returns the previous value or
     * `null` if no value currently exists for the given key.
     *
     * @param key -
     *   key to store value under
     * @param value -
     *   value to store
     * @returns
     *   current value or `null`
     */
    set(key: K, value: V): V | null;
    /**
     * Get the cached value for the specified key if it exists. Will return
     * the value or `null` if no cached value exist. Updates the usage of the
     * key.
     *
     * @param key -
     *   key to get
     * @returns
     *   current value or `null`
     */
    getIfPresent(key: K): V | null;
    /**
     * Peek to see if a key is present without updating the usage of the
     * key. Returns the value associated with the key or `null`  if the key
     * is not present.
     *
     * In many cases `has(key)` is a better option to see if a key is present.
     *
     * @param key -
     *   the key to check
     * @returns
     *   value associated with key or `null`
     */
    peek(key: K): V | null;
    /**
     * Delete a value in the cache. Returns the deleted value or `null` if
     * there was no value associated with the key in the cache.
     *
     * @param key -
     *   the key to delete
     * @returns
     *   deleted value or `null`
     */
    delete(key: K): V | null;
    /**
     * Check if the given key exists in the cache.
     *
     * @param key -
     *   key to check
     * @returns
     *   `true` if value currently exists, `false` otherwise
     */
    has(key: K): boolean;
    /**
     * Clear the cache removing all of the entries cached.
     */
    clear(): void;
    /**
     * Get all of the keys in the cache as an array. Can be used to iterate
     * over all of the values in the cache, but be sure to protect against
     * values being removed during iteration due to time-based expiration if
     * used.
     *
     * @returns
     *   snapshot of keys
     */
    keys(): K[];
    /**
     * Request clean up of the cache by removing expired entries and
     * old data. Clean up is done automatically a short time after sets and
     * deletes, but if your cache uses time-based expiration and has very
     * sporadic updates it might be a good idea to call `cleanUp()` at times.
     *
     * A good starting point would be to call `cleanUp()` in a `setInterval`
     * with a delay of at least a few minutes.
     */
    cleanUp(): void;
    /**
     * Get metrics for this cache. Returns an object with the keys `hits`,
     * `misses` and `hitRate`. For caches that do not have metrics enabled
     * trying to access metrics will throw an error.
     */
    get metrics(): Metrics;
    private [TRIGGER_REMOVE];
    private [MAINTENANCE];
}
export {};