@thi.ng/cache/tlru.d.ts

In-memory cache implementations with ES6 Map-like API and different eviction strategies

import type { Fn0, Maybe, Nullable } from "@thi.ng/api";
import type { ConsCell, DCons } from "@thi.ng/dcons";
import type { CacheEntry, CacheOpts, MapLike } from "./api.js";
import { LRUCache } from "./lru.js";
export interface TLRUCacheOpts<K, V> extends CacheOpts<K, V> {
    /**
     * Default time-to-live (cache period in milliseconds) before an entry is
     * considered expired.
     *
     * @defaultValue 3600000 (1 hour)
     */
    ttl: number;
    /**
     * If true, a cache hit (i.e. reading a cached value via
     * {@link TLRUCache.get}) will auto-extend the expiry time for that cache
     * entry.
     *
     * @defaultValue false
     */
    autoExtend: boolean;
}
export interface TLRUCacheEntry<K, V> extends CacheEntry<K, V> {
    /**
     * Expiry timestamp
     */
    t: number;
    /**
     * TTL for this entry (defaults to {@link TLRUCacheOpts.ttl}, but can be
     * customized per key via {@link TLRUCache.set} or
     * {@link TLRUCache.getSet}).
     */
    ttl: number;
}
/**
 * Time-aware LRU cache. Extends LRU strategy with TTL (time-to-live)
 * values associated to each entry.
 *
 * @remarks
 * {@link ICache.has} will only return true and {@link ICache.get} only
 * returns a cached value if its TTL hasn't yet expired. When adding a
 * new value to the cache, first removes expired entries and if still
 * not sufficient space then removes entries in LRU order.
 *
 * {@link ICache.set} takes an optional entry specific `ttl` arg. If not
 * given, uses the cache instance's default (provided via ctor option
 * arg). If no instance TTL is given, TTL defaults to 1 hour.
 */
export declare class TLRUCache<K, V> extends LRUCache<K, V> {
    protected opts: TLRUCacheOpts<K, V>;
    protected map: MapLike<K, ConsCell<TLRUCacheEntry<K, V>>>;
    protected items: DCons<TLRUCacheEntry<K, V>>;
    constructor(pairs?: Nullable<Iterable<[K, V]>>, opts?: Partial<TLRUCacheOpts<K, V>>);
    empty(): TLRUCache<K, V>;
    has(key: K): boolean;
    /**
     * Attempts to retrieve & return cached value for `key`. If found, also
     * resets the cache entry's configured TTL. If cache miss, returns
     * `notFound`.
     *
     * @param key
     * @param notFound
     */
    get(key: K, notFound?: V): V | undefined;
    /**
     * Stores given `value` under `key` in the cache, optionally with custom
     * `ttl` (in milliseconds). Returns `value`.
     *
     * @remarks
     * Also see {@link TLRUCache.getSet} for alternative, and
     * {@link CacheOpts.update} for user callback when updating an existing
     * `key` in the cache.
     *
     * @param key
     * @param value
     * @param ttl
     */
    set(key: K, value: V, ttl?: number): V;
    getSet(key: K, retrieve: Fn0<Promise<V>>, ttl?: number): Promise<V>;
    /**
     * Scans all cached entries and evicts any which are expired by now (based
     * on their TTL). Does **not** modify last-accessed time of remaining
     * entries. Returns number of entries evicted.
     *
     * @remarks
     * For very large caches, it's recommended to call this function in a
     * cron-like manner...
     */
    prune(): number;
    protected ensureSize(): boolean;
    protected doSetEntry(e: Maybe<ConsCell<TLRUCacheEntry<K, V>>>, k: K, v: V, s: number, ttl?: number): void;
    protected resetEntry(e: ConsCell<TLRUCacheEntry<K, V>>): V;
}
//# sourceMappingURL=tlru.d.ts.map