@tanstack/db/dist/esm/SortedMap.d.ts

A reactive client store for building super fast apps on sync

/**
 * A Map implementation that keeps its entries sorted based on a comparator function
 * @template TKey - The type of keys in the map (must be string | number)
 * @template TValue - The type of values in the map
 */
export declare class SortedMap<TKey extends string | number, TValue> {
    private map;
    private sortedKeys;
    private comparator;
    private dirtyKeys;
    /**
     * Creates a new SortedMap instance
     *
     * @param comparator - Optional function to compare values for sorting.
     *                     If not provided, entries are sorted by key only.
     */
    constructor(comparator?: (a: TValue, b: TValue) => number);
    /**
     * Finds the index where a key-value pair should be inserted to maintain sort order.
     * Uses binary search to find the correct position based on the value (if comparator provided),
     * with key-based tie-breaking for deterministic ordering when values compare as equal.
     * If no comparator is provided, sorts by key only.
     * Runs in O(log n) time.
     *
     * @param key - The key to find position for (used as tie-breaker or primary sort when no comparator)
     * @param value - The value to compare against (only used if comparator is provided)
     * @param keys - The ordered keys to search
     * @returns The index where the key should be inserted
     */
    private indexOf;
    /**
     * Restore the ordered view after a synchronous batch of deferred writes.
     * Dirty keys leave their old slots by Set membership, so a deleted value or
     * one a sync source mutated in place cannot strand a slot. The dirty keys
     * still present are sorted and merged into the rest in one pass:
     * O(n + k log n) for k dirty keys. The merge rewrites sortedKeys in place,
     * so an open key iterator reads the restored order.
     */
    restoreOrder(): void;
    /** Removes a key's slot while its placed value is still mapped. */
    private unplace;
    /**
     * Sets a key-value pair in the map and maintains sort order
     *
     * @param key - The key to set
     * @param value - The value to associate with the key
     * @param deferOrder - Defer ordering until restoreOrder or the next ordered read
     * @returns This SortedMap instance for chaining
     */
    set(key: TKey, value: TValue, deferOrder?: boolean): this;
    /**
     * Gets a value by its key
     *
     * @param key - The key to look up
     * @returns The value associated with the key, or undefined if not found
     */
    get(key: TKey): TValue | undefined;
    /**
     * Removes a key-value pair from the map
     *
     * @param key - The key to remove
     * @param deferOrder - Defer ordering until restoreOrder or the next ordered read
     * @returns True if the key was found and removed, false otherwise
     */
    delete(key: TKey, deferOrder?: boolean): boolean;
    /**
     * Checks if a key exists in the map
     *
     * @param key - The key to check
     * @returns True if the key exists, false otherwise
     */
    has(key: TKey): boolean;
    /**
     * Removes all key-value pairs from the map
     */
    clear(): void;
    /**
     * Gets the number of key-value pairs in the map
     */
    get size(): number;
    /**
     * Default iterator that returns entries in sorted order
     *
     * @returns An iterator for the map's entries
     */
    [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
    /**
     * Returns an iterator for the map's entries in sorted order
     *
     * @returns An iterator for the map's entries
     */
    entries(): IterableIterator<[TKey, TValue]>;
    /**
     * Returns an iterator for the map's keys in sorted order
     *
     * @returns An iterator for the map's keys
     */
    keys(): IterableIterator<TKey>;
    /**
     * Returns an iterator for the map's values in sorted order
     *
     * @returns An iterator for the map's values
     */
    values(): IterableIterator<TValue>;
}