@fimbul-works/observable/dist/map.d.ts

A lightweight, strongly-typed TypeScript library for reactive programming patterns, providing observable collections, values, and event handling.

import type { CollectionEvent, Observable } from "./types";
/**
 * A Map implementation that notifies observers when its contents change.
 * Emits CollectionEvents for add, update, delete, and clear operations.
 *
 * @template K The type of keys in the map
 * @template V The type of values in the map
 * @implements {Observable<CollectionEvent<K, V>>}
 */
export declare class ObservableMap<K, V> implements Observable<CollectionEvent<K, V>> {
    #private;
    /**
     * Creates a new ObservableMap instance.
     * @param entries - Optional initial entries for the map
     */
    constructor(entries?: Iterable<readonly [K, V]>);
    /** Iterator implementation */
    [Symbol.iterator](): IterableIterator<[K, V]>;
    /**
     * Returns the number of entries in the map.
     * @returns The number of key-value pairs in the map
     */
    get size(): number;
    /**
     * Sets a value for the specified key in the map.
     * Emits an 'add' event for new entries or an 'update' event for existing ones.
     * @param key - The key to set
     * @param value - The value to associate with the key
     * @returns {this} The map instance for method chaining
     */
    set(key: K, value: V): this;
    /**
     * Sets a value for the specified key and waits for all change handlers to complete.
     * @param key - The key to set
     * @param value - The value to associate with the key
     * @returns {Promise<this>} Promise resolving to the map instance for method chaining
     */
    setAsync(key: K, value: V): Promise<this>;
    /**
     * Retrieves the value associated with a key.
     * @param key - The key to look up
     * @returns {V | undefined} The value associated with the key, or undefined if the key doesn't exist
     */
    get(key: K): V | undefined;
    /**
     * Checks if a key exists in the map.
     * @param key - The key to check
     * @returns {boolean} True if the key exists, false otherwise
     */
    has(key: K): boolean;
    /**
     * Removes a key and its associated value from the map.
     * Emits a 'delete' event if the key existed.
     * @param key - The key to remove
     * @returns {boolean} True if the key was removed, false if it didn't exist
     */
    delete(key: K): boolean;
    /**
     * Deletes a key-value pair and waits for all change handlers to complete.
     * @param key - The key to delete
     * @returns {Promise<boolean>} Promise resolving to true if the key was deleted, false otherwise
     */
    deleteAsync(key: K): Promise<boolean>;
    /**
     * Removes all entries from the map.
     * Emits a 'clear' event.
     */
    clear(): void;
    /**
     * Clears the map and waits for all change handlers to complete.
     * @returns {Promise<void>}
     */
    clearAsync(): Promise<void>;
    /**
     * Returns an iterator over the map's values.
     * @returns {IterableIterator<V>} An iterator over the map's values
     */
    values(): IterableIterator<V>;
    /**
     * Returns an iterator over the map's keys.
     * @returns {IterableIterator<K>} An iterator over the map's keys
     */
    keys(): IterableIterator<K>;
    /**
     * Returns an iterator over the map's entries.
     * @returns {IterableIterator<[K, V]>} An iterator over the map's key-value pairs
     */
    entries(): IterableIterator<[K, V]>;
    /**
     * Registers a function to be called when the map changes.
     * @param fn - Function to be called with collection events
     * @returns {() => void} A cleanup function that removes the listener
     */
    onChange(fn: (event: CollectionEvent<K, V>) => void): () => void;
    /**
     * Executes a provided function once per each key/value pair in the Map, in insertion order.
     * @param fn - Function to be called
     */
    forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: unknown): void;
    /**
     * Creates a new ObservableMap with the results of calling a provided function on every element.
     * @template U The type of values in the new map
     * @param callbackfn - Function that produces a value for the new map
     * @returns A new ObservableMap with each value transformed by the function
     */
    map<U>(callbackfn: (value: V, key: K, map: this) => U): ObservableMap<K, U>;
    /**
     * Creates a new ObservableMap with all elements that pass the test.
     * @param predicate - Function to test each entry of the map
     * @returns A new ObservableMap with the entries that passed the test
     */
    filter(predicate: (value: V, key: K, map: this) => boolean): ObservableMap<K, V>;
    /**
     * Converts the map to a plain object.
     * Note: Keys must be strings or symbols.
     * @returns A plain object with the same entries as the map
     * @throws {TypeError} If any key is not a string or symbol
     */
    toObject(): Record<string | symbol, V>;
    /**
     * Converts the map to a JSON-serializable format.
     * Note: Values must be JSON-serializable.
     * @returns An array of entries suitable for JSON serialization
     */
    toJSON(): Array<[string, unknown]>;
}