cache-entanglement/dist/types/utils/InvertedWeakMap.d.ts

Manage caches that are dependent on each other efficiently.

/**
 * A Map that holds weak references to its values.
 * Unlike a standard WeakMap where the keys are weak, this implementation makes the values weak.
 * It uses `WeakRef` to store values and `FinalizationRegistry` to clean up the map when values are garbage collected.
 * @template K Type of the key (primitive or symbol).
 * @template V Type of the value (must be an object/WeakKey).
 */
export declare class InvertedWeakMap<K extends string | number | symbol, V extends WeakKey> {
    private readonly map;
    private readonly registry;
    /**
     * Creates an instance of InvertedWeakMap.
     */
    constructor();
    /**
     * Clears all entries from the map.
     */
    clear(): void;
    /**
     * Removes an entry from the map by key.
     * Also unregisters the value from the finalization registry if it still exists.
     * @param key The key to remove.
     * @returns True if the entry was removed, false otherwise.
     */
    delete(key: K): boolean;
    /**
     * Retrieves a value by key.
     * @param key The key to look for.
     * @returns The value if it exists and hasn't been garbage collected, otherwise undefined.
     */
    get(key: K): V | undefined;
    /**
     * Checks if a key exists in the map and its value hasn't been garbage collected.
     * @param key The key to check.
     * @returns True if the key exists and the value is still alive.
     */
    has(key: K): boolean;
    /**
     * Sets a value for the given key using a weak reference.
     * Registers the value in the finalization registry to automatically remove the key when the value is GC'd.
     * @param key The key to associate with the value.
     * @param value The value to store weakly.
     * @returns This InvertedWeakMap instance.
     */
    set(key: K, value: V): this;
    /**
     * Returns the number of entries currently in the map.
     * Note: This may include entries whose values have been GC'd but not yet cleaned up by the registry.
     */
    get size(): number;
    /**
     * Returns an iterator of keys in the map.
     * @returns An iterable iterator of keys.
     */
    keys(): IterableIterator<K>;
}