max-priority-queue-typed 2.3.0 → 2.4.1

package/dist/types/data-structures/binary-tree/tree-multi-map.d.ts

@@ -2,118 +2,28 @@
  * data-structure-typed
  *
  * @author Pablo Zeng
- * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @copyright Copyright (c) 2022 Pablo Zeng
  * @license MIT License
  */
-import type { ElemOf, EntryCallback, FamilyPosition, RBTNColor, TreeMultiMapOptions } from '../../types';
-import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
-import { IBinaryTree } from '../../interfaces';
+import type { Comparator, TreeMultiMapOptions } from '../../types';
+import { Range } from '../../common';
+import { RedBlackTreeNode } from './red-black-tree';
 /**
- * Node used by TreeMultiMap; stores the key with a bucket of values (array).
- * @remarks Time O(1), Space O(1)
- * @template K
- * @template V
+ * Node type used by TreeMultiMap (alias to RedBlackTreeNode for backward compatibility).
+ *
+ * @deprecated Direct node manipulation is discouraged. Use TreeMultiMap methods instead.
  */
-export declare class TreeMultiMapNode<K = any, V = any> {
-    key: K;
-    value?: V[];
-    parent?: TreeMultiMapNode<K, V>;
-    /**
-     * Create a TreeMultiMap node with an optional value bucket.
-     * @remarks Time O(1), Space O(1)
-     * @param key - Key of the node.
-     * @param [value] - Initial array of values.
-     * @returns New TreeMultiMapNode instance.
-     */
-    constructor(key: K, value?: V[], color?: RBTNColor);
-    _left?: TreeMultiMapNode<K, V> | null | undefined;
-    /**
-     * Get the left child pointer.
-     * @remarks Time O(1), Space O(1)
-     * @returns Left child node, or null/undefined.
-     */
-    get left(): TreeMultiMapNode<K, V> | null | undefined;
-    /**
-     * Set the left child and update its parent pointer.
-     * @remarks Time O(1), Space O(1)
-     * @param v - New left child node, or null/undefined.
-     * @returns void
-     */
-    set left(v: TreeMultiMapNode<K, V> | null | undefined);
-    _right?: TreeMultiMapNode<K, V> | null | undefined;
-    /**
-     * Get the right child pointer.
-     * @remarks Time O(1), Space O(1)
-     * @returns Right child node, or null/undefined.
-     */
-    get right(): TreeMultiMapNode<K, V> | null | undefined;
-    /**
-     * Set the right child and update its parent pointer.
-     * @remarks Time O(1), Space O(1)
-     * @param v - New right child node, or null/undefined.
-     * @returns void
-     */
-    set right(v: TreeMultiMapNode<K, V> | null | undefined);
-    _height: number;
-    /**
-     * Gets the height of the node (used in self-balancing trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The height.
-     */
-    get height(): number;
-    /**
-     * Sets the height of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new height.
-     */
-    set height(value: number);
-    _color: RBTNColor;
-    /**
-     * Gets the color of the node (used in Red-Black trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The node's color.
-     */
-    get color(): RBTNColor;
-    /**
-     * Sets the color of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new color.
-     */
-    set color(value: RBTNColor);
-    _count: number;
-    /**
-     * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The subtree node count.
-     */
-    get count(): number;
-    /**
-     * Sets the count of nodes in the subtree.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new count.
-     */
-    set count(value: number);
-    /**
-     * Gets the position of the node relative to its parent.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
-     */
-    get familyPosition(): FamilyPosition;
+export declare class TreeMultiMapNode<K = any, V = any> extends RedBlackTreeNode<K, V[]> {
+    constructor(key: K, value?: V[]);
 }
 /**
- * Red-Black Tree–based multimap (key → array of values). Preserves O(log N) updates and supports map-like mode.
- * @remarks Time O(1), Space O(1)
- * @template K
- * @template V
- * @template R
+ * TreeMultiMap (ordered MultiMap) — key → bucket (Array of values).
  *
+ * Semantics (RFC):
+ * - Bucketed design: each key appears once; duplicates live in the bucket.
+ * - `get(key)` returns a **live** bucket reference.
+ * - Default iteration yields bucket entries: `[K, V[]]`.
+ * - Navigable operations (`first/last/ceiling/...`) return entry tuples like TreeMap.
  * @example
  * // players ranked by score with their equipment
  *  type Equipment = {
@@ -241,7 +151,7 @@ export declare class TreeMultiMapNode<K = any, V = any> {
  *       isMapMode: false
  *     });
  *
- *     const topPlayersEquipments = playerRankings.rangeSearch([8900, 10000], node => playerRankings.get(node));
+ *     const topPlayersEquipments = playerRankings.rangeSearch([8900, 10000], node => playerRankings.get(node.key));
  *     console.log(topPlayersEquipments); // [
  *  //      [
  *  //        {
@@ -279,55 +189,236 @@ export declare class TreeMultiMapNode<K = any, V = any> {
  *  //      ]
  *  //    ];
  */
-export declare class TreeMultiMap<K = any, V = any, R = any> extends RedBlackTree<K, V[], R> implements IBinaryTree<K, V[], R> {
+export declare class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]]> {
+    #private;
     /**
-     * Create a TreeMultiMap and optionally bulk-insert items.
-     * @remarks Time O(N log N), Space O(N)
-     * @param [keysNodesEntriesOrRaws] - Iterable of keys/nodes/entries/raw items to insert.
-     * @param [options] - Options for TreeMultiMap (comparator, reverse, map mode).
-     * @returns New TreeMultiMap instance.
+     * Creates a new TreeMultiMap.
+     * @param keysNodesEntriesOrRaws - Initial entries, or raw elements if `toEntryFn` is provided.
+     * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
+     * @remarks Time O(m log m), Space O(m) where m is the number of initial entries
+     * @example
+     * // Standard usage with entries
+     * const mmap = new TreeMultiMap([['a', ['x', 'y']], ['b', ['z']]]);
+     *
+     * // Using toEntryFn to transform raw objects
+     * const players = [{ score: 100, items: ['sword'] }, { score: 200, items: ['shield', 'bow'] }];
+     * const mmap = new TreeMultiMap(players, { toEntryFn: p => [p.score, p.items] });
      */
-    constructor(keysNodesEntriesOrRaws?: Iterable<K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | R>, options?: TreeMultiMapOptions<K, V[], R>);
-    createNode(key: K, value?: V[]): TreeMultiMapNode<K, V>;
+    constructor(keysNodesEntriesOrRaws?: Iterable<K | [K | null | undefined, V[] | undefined] | null | undefined | R>, options?: TreeMultiMapOptions<K, V[], R>);
     /**
-     * Checks if the given item is a `TreeMultiMapNode` instance.
+     * Validates the key against the default comparator rules.
      * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeOrEntry - The item to check.
-     * @returns True if it's a TreeMultiMapNode, false otherwise.
      */
-    isNode(keyNodeOrEntry: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): keyNodeOrEntry is TreeMultiMapNode<K, V>;
-    set(keyNodeOrEntry: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
+    private _validateKey;
+    /**
+     * Number of distinct keys.
+     * @remarks Time O(1), Space O(1)
+     */
+    get size(): number;
+    /**
+     * Whether the map is empty.
+     * @remarks Time O(1), Space O(1)
+     */
+    isEmpty(): boolean;
+    /**
+     * Removes all entries from the map.
+     * @remarks Time O(1), Space O(1)
+     */
+    clear(): void;
+    /**
+     * Bucket length for a key (missing => 0).
+     * @remarks Time O(log n), Space O(1)
+     */
+    count(key: K): number;
+    /**
+     * Total number of values across all buckets (Σ bucket.length).
+     * @remarks Time O(n), Space O(1)
+     */
+    get totalSize(): number;
+    /**
+     * Whether the map contains the given key.
+     * @remarks Time O(log n), Space O(1)
+     */
+    has(key: K): boolean;
+    /**
+     * Live bucket reference (do not auto-delete key if bucket becomes empty via mutation).
+     * @remarks Time O(log n), Space O(1)
+     */
+    get(key: K): V[] | undefined;
+    /**
+     * Append a single value.
+     * @remarks Time O(log n), Space O(1)
+     */
+    add(key: K, value: V): boolean;
+    /**
+     * Alias for compatibility with existing TreeMultiMap semantics.
+     * @remarks Time O(log n), Space O(1) for single value; O(log n + m) for bucket append
+     */
+    set(entry: [K | null | undefined, V[] | undefined] | K | null | undefined, value?: V): boolean;
     set(key: K, value: V): boolean;
     /**
-     * Delete a single value from the bucket at a given key. Removes the key if the bucket becomes empty.
-     * @remarks Time O(log N), Space O(1)
-     * @param keyNodeOrEntry - Key, node, or [key, values] entry to locate the bucket.
-     * @param value - Value to remove from the bucket.
-     * @returns True if the value was removed; false if not found.
+     * Deletes a key and its entire bucket.
+     * @remarks Time O(log n), Space O(1)
+     */
+    delete(key: K): boolean;
+    /**
+     * Check if a specific value exists in a key's bucket.
+     * @remarks Time O(log n + m), Space O(1) where m is bucket size
+     */
+    hasEntry(key: K, value: V, eq?: (a: V, b: V) => boolean): boolean;
+    /**
+     * Delete a single occurrence of a value from a key's bucket.
+     * @remarks Time O(log n + m), Space O(1) where m is bucket size
+     */
+    deleteValue(key: K, value: V, eq?: (a: V, b: V) => boolean): boolean;
+    /**
+     * Delete all occurrences of a value from a key's bucket.
+     * @remarks Time O(log n + m), Space O(1) where m is bucket size
+     */
+    deleteValues(key: K, value: V, eq?: (a: V, b: V) => boolean): number;
+    /**
+     * Iterates over all entries as [key, bucket] pairs.
+     * @remarks Time O(n), Space O(1)
+     */
+    [Symbol.iterator](): Iterator<[K, V[]]>;
+    /**
+     * Iterates over all keys.
+     * @remarks Time O(n), Space O(1)
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Iterates over all buckets.
+     * @remarks Time O(n), Space O(1)
+     */
+    values(): IterableIterator<V[]>;
+    /**
+     * Iterates over all entries for a specific key.
+     * @remarks Time O(log n + m), Space O(1) where m is bucket size
+     */
+    entriesOf(key: K): IterableIterator<[K, V]>;
+    /**
+     * Iterates over all values for a specific key.
+     * @remarks Time O(log n + m), Space O(1) where m is bucket size
+     */
+    valuesOf(key: K): IterableIterator<V>;
+    /**
+     * Iterates over all [key, value] pairs (flattened from buckets).
+     * @remarks Time O(T), Space O(1) where T is totalSize
+     */
+    flatEntries(): IterableIterator<[K, V]>;
+    /**
+     * Returns the entry with the smallest key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[1, ['a']], [2, ['b']]]);
+     * map.first();  // [1, ['a']]
+     */
+    first(): [K, V[]] | undefined;
+    /**
+     * Returns the entry with the largest key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[1, ['a']], [2, ['b']]]);
+     * map.last();  // [2, ['b']]
      */
-    deleteValue(keyNodeOrEntry: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined, value: V): boolean;
-    map<MK = K, MVArr extends unknown[] = V[], MR = any>(callback: EntryCallback<K, V[] | undefined, [MK, MVArr]>, options?: Partial<TreeMultiMapOptions<MK, MVArr, MR>>, thisArg?: unknown): TreeMultiMap<MK, ElemOf<MVArr>, MR>;
-    map<MK = K, MV = V[], MR = any>(callback: EntryCallback<K, V[] | undefined, [MK, MV]>, options?: Partial<TreeMultiMapOptions<MK, MV, MR>>, thisArg?: unknown): RedBlackTree<MK, MV, MR>;
+    last(): [K, V[]] | undefined;
     /**
-     * (Protected) Create an empty instance of the same concrete class.
+     * Removes and returns the entry with the smallest key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[1, ['a']], [2, ['b']]]);
+     * map.pollFirst();  // [1, ['a']]
+     * map.has(1);       // false
+     */
+    pollFirst(): [K, V[]] | undefined;
+    /**
+     * Removes and returns the entry with the largest key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[1, ['a']], [2, ['b']]]);
+     * map.pollLast();  // [2, ['b']]
+     * map.has(2);      // false
+     */
+    pollLast(): [K, V[]] | undefined;
+    /**
+     * Returns the entry with the smallest key >= given key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[10, ['a']], [20, ['b']], [30, ['c']]]);
+     * map.ceiling(15);  // [20, ['b']]
+     * map.ceiling(20);  // [20, ['b']]
+     */
+    ceiling(key: K): [K, V[]] | undefined;
+    /**
+     * Returns the entry with the largest key <= given key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[10, ['a']], [20, ['b']], [30, ['c']]]);
+     * map.floor(25);  // [20, ['b']]
+     * map.floor(20);  // [20, ['b']]
+     */
+    floor(key: K): [K, V[]] | undefined;
+    /**
+     * Returns the entry with the smallest key > given key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[10, ['a']], [20, ['b']], [30, ['c']]]);
+     * map.higher(10);  // [20, ['b']]
+     * map.higher(15);  // [20, ['b']]
+     */
+    higher(key: K): [K, V[]] | undefined;
+    /**
+     * Returns the entry with the largest key < given key.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const map = new TreeMultiMap([[10, ['a']], [20, ['b']], [30, ['c']]]);
+     * map.lower(20);  // [10, ['a']]
+     * map.lower(15);  // [10, ['a']]
+     */
+    lower(key: K): [K, V[]] | undefined;
+    /**
+     * Prints the internal tree structure (for debugging).
+     * @remarks Time O(n), Space O(n)
+     */
+    print(): void;
+    /**
+     * Executes a callback for each entry.
+     * @remarks Time O(n), Space O(1)
+     */
+    forEach(callback: (value: V[], key: K, map: this) => void): void;
+    /**
+     * Creates a new map with entries that pass the predicate.
+     * @remarks Time O(n), Space O(n)
+     */
+    filter(predicate: (value: V[], key: K, map: this) => boolean): TreeMultiMap<K, V, R>;
+    /**
+     * Creates a new map by transforming each entry.
+     * @remarks Time O(n log n), Space O(n)
+     */
+    map<V2>(mapper: (value: V[], key: K, map: this) => [K, V2[]]): TreeMultiMap<K, V2, R>;
+    /**
+     * Reduces all entries to a single value.
+     * @remarks Time O(n), Space O(1)
+     */
+    reduce<U>(callback: (accumulator: U, value: V[], key: K, map: this) => U, initialValue: U): U;
+    /**
+     * Sets multiple entries at once.
+     * @remarks Time O(m log n), Space O(m) where m is input size
+     */
+    setMany(keysNodesEntriesOrRaws: Iterable<K | [K | null | undefined, V[] | undefined]>): boolean[];
+    /**
+     * Searches for entries within a key range.
+     * @remarks Time O(log n + k), Space O(k) where k is result size
+     */
+    rangeSearch<C extends (node: RedBlackTreeNode<K, V[]>) => unknown>(range: Range<K> | [K, K], callback?: C): ReturnType<C>[];
+    /**
+     * Creates a shallow clone of this map.
+     * @remarks Time O(n log n), Space O(n)
+     */
+    clone(): TreeMultiMap<K, V, R>;
+    /**
+     * Expose comparator for advanced usage/testing (read-only).
      * @remarks Time O(1), Space O(1)
-     * @template TK
-     * @template TV
-     * @template TR
-     * @param [options] - Optional constructor options for the like-kind instance.
-     * @returns An empty like-kind instance.
-     */
-    protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<TreeMultiMapOptions<TK, TV, TR>>): this;
-    /**
-     * (Protected) Create a like-kind instance and seed it from an iterable.
-     * @remarks Time O(N log N), Space O(N)
-     * @template TK
-     * @template TV
-     * @template TR
-     * @param iter - Iterable used to seed the new tree.
-     * @param [options] - Options merged with the current snapshot.
-     * @returns A like-kind RedBlackTree built from the iterable.
-     */
-    protected _createLike<TK = K, TV = V, TR = R>(iter?: Iterable<TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<TreeMultiMapOptions<TK, TV, TR>>): RedBlackTree<TK, TV, TR>;
+     */
+    get comparator(): Comparator<K>;
 }

package/dist/types/data-structures/binary-tree/tree-multi-set.d.ts

@@ -0,0 +1,270 @@
+/**
+ * TreeMultiSet (ordered multiset) — a restricted, native-like API backed by RedBlackTree.
+ *
+ * Design goals:
+ * - No node exposure
+ * - Strict default comparator (number/string/Date), otherwise require comparator
+ * - Default iteration is expanded (each element yielded `count(x)` times)
+ * - `delete(x)` removes one occurrence by default
+ */
+import type { Comparator, TreeMultiSetOptions } from '../../types';
+export declare class TreeMultiSet<K = any, R = K> implements Iterable<K> {
+    #private;
+    private _size;
+    /**
+     * Creates a new TreeMultiSet.
+     * @param elements - Initial elements to add, or raw elements if `toElementFn` is provided.
+     * @param options - Configuration options including optional `toElementFn` to transform raw elements.
+     * @remarks Time O(m log m), Space O(m) where m is the number of initial elements
+     * @example
+     * // Standard usage with elements
+     * const mset = new TreeMultiSet([1, 2, 2, 3]);
+     *
+     * // Using toElementFn to transform raw objects
+     * const items = [{ score: 100 }, { score: 200 }, { score: 100 }];
+     * const mset = new TreeMultiSet<number, Item>(items, { toElementFn: item => item.score });
+     */
+    constructor(elements?: Iterable<R> | Iterable<K>, options?: TreeMultiSetOptions<K, R>);
+    /**
+     * Validates the key against the default comparator rules.
+     * @remarks Time O(1), Space O(1)
+     */
+    private _validateKey;
+    /**
+     * Validates that count is a non-negative safe integer.
+     * @remarks Time O(1), Space O(1)
+     */
+    private _validateCount;
+    /**
+     * Total occurrences (sumCounts).
+     * @remarks Time O(1), Space O(1)
+     */
+    get size(): number;
+    /**
+     * Number of distinct keys.
+     * @remarks Time O(1), Space O(1)
+     */
+    get distinctSize(): number;
+    /**
+     * Whether the multiset is empty.
+     * @remarks Time O(1), Space O(1)
+     */
+    isEmpty(): boolean;
+    /**
+     * Whether the multiset contains the given key.
+     * @remarks Time O(log n), Space O(1)
+     */
+    has(key: K): boolean;
+    /**
+     * Returns the count of occurrences for the given key.
+     * @remarks Time O(log n), Space O(1)
+     */
+    count(key: K): number;
+    /**
+     * Add `n` occurrences of `key`.
+     * @returns True if the multiset changed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    add(key: K, n?: number): boolean;
+    /**
+     * Set count for `key` to exactly `n`.
+     * @returns True if changed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    setCount(key: K, n: number): boolean;
+    /**
+     * Delete `n` occurrences of `key` (default 1).
+     * @returns True if any occurrence was removed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    delete(key: K, n?: number): boolean;
+    /**
+     * Delete all occurrences of the given key.
+     * @returns True if any occurrence was removed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    deleteAll(key: K): boolean;
+    /**
+     * Iterates over distinct keys (each key yielded once).
+     * @remarks Time O(n), Space O(1)
+     */
+    keysDistinct(): IterableIterator<K>;
+    /**
+     * Iterates over entries as [key, count] pairs.
+     * @remarks Time O(n), Space O(1)
+     */
+    entries(): IterableIterator<[K, number]>;
+    /**
+     * Expanded iteration (default). Each key is yielded `count(key)` times.
+     * @remarks Time O(size), Space O(1) where size is total occurrences
+     */
+    [Symbol.iterator](): Iterator<K>;
+    /**
+     * Returns an array with all elements (expanded).
+     * @remarks Time O(size), Space O(size)
+     */
+    toArray(): K[];
+    /**
+     * Returns an array with distinct keys only.
+     * @remarks Time O(n), Space O(n)
+     */
+    toDistinctArray(): K[];
+    /**
+     * Returns an array of [key, count] entries.
+     * @remarks Time O(n), Space O(n)
+     */
+    toEntries(): Array<[K, number]>;
+    /**
+     * Expose comparator for advanced usage/testing (read-only).
+     * @remarks Time O(1), Space O(1)
+     */
+    get comparator(): Comparator<K>;
+    /**
+     * Remove all elements from the multiset.
+     * @remarks Time O(1), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 2, 2, 3]);
+     * ms.clear();
+     * ms.size;  // 0
+     */
+    clear(): void;
+    /**
+     * Returns the smallest key, or undefined if empty.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([3, 1, 4]);
+     * ms.first();  // 1
+     */
+    first(): K | undefined;
+    /**
+     * Returns the largest key, or undefined if empty.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([3, 1, 4]);
+     * ms.last();  // 4
+     */
+    last(): K | undefined;
+    /**
+     * Removes all occurrences of the smallest key and returns it.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3]);
+     * ms.pollFirst();  // 1
+     * ms.has(1);       // false
+     */
+    pollFirst(): K | undefined;
+    /**
+     * Removes all occurrences of the largest key and returns it.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 2, 3, 3]);
+     * ms.pollLast();  // 3
+     * ms.has(3);      // false
+     */
+    pollLast(): K | undefined;
+    /**
+     * Returns the smallest key >= given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.ceiling(15);  // 20
+     * ms.ceiling(20);  // 20
+     */
+    ceiling(key: K): K | undefined;
+    /**
+     * Returns the largest key <= given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.floor(25);  // 20
+     * ms.floor(20);  // 20
+     */
+    floor(key: K): K | undefined;
+    /**
+     * Returns the smallest key > given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.higher(10);  // 20
+     * ms.higher(15);  // 20
+     */
+    higher(key: K): K | undefined;
+    /**
+     * Returns the largest key < given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.lower(20);  // 10
+     * ms.lower(15);  // 10
+     */
+    lower(key: K): K | undefined;
+    /**
+     * Iterates over distinct keys with their counts.
+     * @remarks Time O(n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * ms.forEach((key, count) => console.log(`${key}: ${count}`));
+     * // 1: 2, 2: 1, 3: 3
+     */
+    forEach(callback: (key: K, count: number) => void): void;
+    /**
+     * Creates a new TreeMultiSet with entries that match the predicate.
+     * @remarks Time O(n log n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * const filtered = ms.filter((key, count) => count >= 2);
+     * // TreeMultiSet { 1: 2, 3: 3 }
+     */
+    filter(predicate: (key: K, count: number) => boolean): TreeMultiSet<K>;
+    /**
+     * Reduces the multiset to a single value.
+     * @remarks Time O(n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * const total = ms.reduce((acc, key, count) => acc + count, 0);  // 6
+     */
+    reduce<U>(callback: (accumulator: U, key: K, count: number) => U, initialValue: U): U;
+    /**
+     * Maps keys and counts to a new TreeMultiSet.
+     * When multiple keys map to the same new key, counts are merged (added).
+     * @remarks Time O(n log n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * const mapped = ms.map((key, count) => [key * 10, count]);
+     * // TreeMultiSet { 10: 2, 20: 1, 30: 3 }
+     * @example
+     * // Collision: counts merge
+     * const ms = new TreeMultiSet([1, 2, 3]);
+     * const merged = ms.map((key, count) => [key % 2, count]);
+     * // { 0: 1, 1: 2 }  (1 and 3 both map to 1, counts add)
+     */
+    map<K2>(mapper: (key: K, count: number) => [K2, number], options?: {
+        comparator?: Comparator<K2>;
+    }): TreeMultiSet<K2>;
+    /**
+     * Creates an independent copy of this multiset.
+     * @remarks Time O(n log n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2]);
+     * const copy = ms.clone();
+     * copy.add(3);
+     * ms.has(3);  // false (original unchanged)
+     */
+    clone(): TreeMultiSet<K>;
+    /**
+     * Returns keys within the given range.
+     * @remarks Time O(log n + k), Space O(k) where k is result size
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30, 40, 50]);
+     * ms.rangeSearch([15, 45]);  // [20, 30, 40]
+     */
+    rangeSearch<C extends (key: K) => any>(range: [K, K], callback?: C): (C extends undefined ? K : ReturnType<C>)[];
+    /**
+     * Prints the internal tree structure (for debugging).
+     * @remarks Time O(n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 2, 3]);
+     * ms.print();
+     */
+    print(): void;
+}