data-structure-typed 2.5.3 → 2.6.1

package/src/data-structures/binary-tree/tree-multi-map.ts

@@ -5,7 +5,6 @@
  * @copyright Copyright (c) 2022 Pablo Zeng
  * @license MIT License
  */
-
 import type { Comparator, TreeMultiMapOptions } from '../../types';
 import { ERR, raise, Range } from '../../common';
 import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
@@ -49,23 +48,25 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
     const comparator = options.comparator ?? TreeSet.createDefaultComparator<K>();
     this.#isDefaultComparator = options.comparator === undefined;
     const toEntryFn = options.toEntryFn;
-    this.#core = new RedBlackTree<K, V[], R>([], { ...options, comparator, isMapMode: options.isMapMode, enableOrderStatistic: options.enableOrderStatistic });
-
+    this.#core = new RedBlackTree<K, V[], R>([], {
+      ...options,
+      comparator,
+      isMapMode: options.isMapMode,
+      enableOrderStatistic: options.enableOrderStatistic
+    });
     for (const x of keysNodesEntriesOrRaws) {
       if (x === null || x === undefined) continue;
-
       // If toEntryFn is provided, use it to transform raw element
       if (toEntryFn) {
         const [k, bucket] = toEntryFn(x as R);
         if (k === null || k === undefined) continue;
         if (bucket !== undefined) {
-          this.#core.set(k as K, Array.isArray(bucket) ? [...bucket] : [bucket] as V[]);
+          this.#core.set(k as K, Array.isArray(bucket) ? [...bucket] : ([bucket] as V[]));
         } else {
           this.#core.set(k as K, [] as V[]);
         }
         continue;
       }
-
       if (Array.isArray(x)) {
         const [k, bucket] = x;
         if (k === null || k === undefined) continue;
@@ -83,217 +84,44 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   }
 
   /**
-   * Validates the key against the default comparator rules.
+   * Number of distinct keys.
    * @remarks Time O(1), Space O(1)
    */
-  private _validateKey(key: K): void {
-    if (!this.#isDefaultComparator) return;
-    // reuse TreeSet strict validation (same policy)
-    // NOTE: TreeSet._validateKey is private, so we replicate the checks.
-    if (typeof key === 'number') {
-      if (Number.isNaN(key)) raise(TypeError, ERR.invalidNaN('TreeMultiMap'));
-      return;
-    }
-    if (typeof key === 'string') return;
-    if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) raise(TypeError, ERR.invalidDate('TreeMultiMap'));
-      return;
-    }
-    raise(TypeError, ERR.comparatorRequired('TreeMultiMap'));
+  get size(): number {
+    return this.#core.size;
   }
 
   /**
-   * Number of distinct keys.
+   * Total number of values across all buckets (Σ bucket.length).
+   * @remarks Time O(n), Space O(1)
+   * @example
+   * // Total number of values
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       mm.add(2, 'c');
+   *       console.log(mm.totalSize); // 3;
+   */
+  get totalSize(): number {
+    let sum = 0;
+    for (const [, bucket] of this) sum += bucket.length;
+    return sum;
+  }
+
+  /**
+   * Expose comparator for advanced usage/testing (read-only).
    * @remarks Time O(1), Space O(1)
    */
-  get size(): number {
-    return this.#core.size;
+  get comparator(): Comparator<K> {
+    return this.#core.comparator;
   }
 
   /**
    * Whether the map is empty.
    * @remarks Time O(1), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check if empty
- *  console.log(new TreeMultiMap().isEmpty()); // true;
+   * @example
+   * // Check if empty
+   *  console.log(new TreeMultiMap().isEmpty()); // true;
    */
   isEmpty(): boolean {
     return this.size === 0;
@@ -302,190 +130,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Removes all entries from the map.
    * @remarks Time O(1), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove all entries
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.clear();
- *       console.log(mm.isEmpty()); // true;
+   * @example
+   * // Remove all entries
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.clear();
+   *       console.log(mm.isEmpty()); // true;
    */
   clear(): void {
     this.#core.clear();
@@ -494,324 +144,27 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Bucket length for a key (missing => 0).
    * @remarks Time O(log n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Count values for key
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       console.log(mm.count(1)); // 2;
+   * @example
+   * // Count values for key
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       console.log(mm.count(1)); // 2;
    */
   count(key: K): number {
     const b = this.get(key);
     return Array.isArray(b) ? b.length : 0;
   }
 
-  /**
-   * Total number of values across all buckets (Σ bucket.length).
-   * @remarks Time O(n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Total number of values
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       mm.add(2, 'c');
- *       console.log(mm.totalSize); // 3;
-   */
-  get totalSize(): number {
-    let sum = 0;
-    for (const [, bucket] of this) sum += bucket.length;
-    return sum;
-  }
-
   /**
    * Whether the map contains the given key.
    * @remarks Time O(log n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check key existence
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       console.log(mm.has(1)); // true;
- *       console.log(mm.has(2)); // false;
+   * @example
+   * // Check key existence
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       console.log(mm.has(1)); // true;
+   *       console.log(mm.has(2)); // false;
    */
   has(key: K): boolean {
     this._validateKey(key);
@@ -821,232 +174,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Live bucket reference (do not auto-delete key if bucket becomes empty via mutation).
    * @remarks Time O(log n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get values for key
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       console.log(mm.get(1)); // ['a', 'b'];
+   * @example
+   * // Get values for key
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       console.log(mm.get(1)); // ['a', 'b'];
    */
   get(key: K): V[] | undefined {
     this._validateKey(key);
@@ -1056,185 +189,13 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Append a single value.
    * @remarks Time O(log n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Add key-value pair
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       mm.add(2, 'c');
- *       console.log(mm.get(1)); // ['a', 'b'];
+   * @example
+   * // Add key-value pair
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       mm.add(2, 'c');
+   *       console.log(mm.get(1)); // ['a', 'b'];
    */
   add(key: K, value: V): boolean {
     this._validateKey(key);
@@ -1249,230 +210,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * 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
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Set values for key
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.set(1, 'a');
- *       mm.set(1, 'b');
- *       console.log(mm.get(1)); // ['a', 'b'];
+   * @example
+   * // Set values for key
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.set(1, 'a');
+   *       mm.set(1, 'b');
+   *       console.log(mm.get(1)); // ['a', 'b'];
    */
   set(entry: [K | null | undefined, V[] | undefined] | K | null | undefined, value?: V): boolean;
   set(key: K, value: V): boolean;
@@ -1502,233 +245,13 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Deletes a key and its entire bucket.
    * @remarks Time O(log n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove key
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(2, 'b');
- *       mm.delete(1);
- *       console.log(mm.has(1)); // false;
+   * @example
+   * // Remove key
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(2, 'b');
+   *       mm.delete(1);
+   *       console.log(mm.has(1)); // false;
    */
   delete(key: K): boolean {
     this._validateKey(key);
@@ -1738,42 +261,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * 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
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check specific key-value
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       console.log(mm.hasEntry(1, 'a')); // true;
- *       console.log(mm.hasEntry(1, 'z')); // false;
+   * @example
+   * // Check specific key-value
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       console.log(mm.hasEntry(1, 'a')); // true;
+   *       console.log(mm.hasEntry(1, 'z')); // false;
    */
   hasEntry(key: K, value: V, eq: (a: V, b: V) => boolean = Object.is): boolean {
     const bucket = this.get(key);
@@ -1784,43 +277,13 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * 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
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Delete specific value
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       mm.deleteValue(1, 'a');
- *       console.log(mm.get(1)); // ['b'];
+   * @example
+   * // Delete specific value
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       mm.deleteValue(1, 'a');
+   *       console.log(mm.get(1)); // ['b'];
    */
   deleteValue(key: K, value: V, eq: (a: V, b: V) => boolean = Object.is): boolean {
     const bucket = this.get(key);
@@ -1835,44 +298,14 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * 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
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Delete all matching values
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       const count = mm.deleteValues(1, 'a');
- *       console.log(count); // 2;
+   * @example
+   * // Delete all matching values
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       const count = mm.deleteValues(1, 'a');
+   *       console.log(count); // 2;
    */
   deleteValues(key: K, value: V, eq: (a: V, b: V) => boolean = Object.is): number {
     const bucket = this.get(key);
@@ -1904,190 +337,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Iterates over all keys.
    * @remarks Time O(n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Iterate keys
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(3, 'c');
- *       mm.add(1, 'a');
- *       console.log([...mm.keys()]); // [1, 3];
+   * @example
+   * // Iterate keys
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(3, 'c');
+   *       mm.add(1, 'a');
+   *       console.log([...mm.keys()]); // [1, 3];
    */
   *keys(): IterableIterator<K> {
     yield* this.#core.keys();
@@ -2096,236 +351,49 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Iterates over all buckets.
    * @remarks Time O(n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Iterate value arrays
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       console.log([...mm.values()]); // [['a', 'b']];
+   * @example
+   * // Iterate value arrays
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       console.log([...mm.values()]); // [['a', 'b']];
    */
   *values(): IterableIterator<V[]> {
     for (const [, bucket] of this) yield bucket;
   }
 
+  /**
+   * Iterate over all `[key, values[]]` entries (Map-compatible).
+   * @remarks Time O(n), Space O(1) per step.
+   * @example
+   * // Iterate over entries
+   *  const mm = new TreeMultiMap<number, string>();
+   *     mm.set(1, 'a');
+   *     mm.set(1, 'b');
+   *     mm.set(2, 'c');
+   *     console.log([...mm.entries()]); // [
+   *  //      [1, ['a', 'b']],
+   *  //      [2, ['c']]
+   *  //    ];
+   */
+  *entries(): IterableIterator<[K, V[]]> {
+    yield* this;
+  }
+
   // ---- entry-flat views ----
 
   /**
    * Iterates over all entries for a specific key.
    * @remarks Time O(log n + m), Space O(1) where m is bucket size
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get entries for key
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       console.log([...mm.entriesOf(1)]); // [[1, 'a'], [1, 'b']];
+   * @example
+   * // Get entries for key
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       console.log([...mm.entriesOf(1)]); // [
+   *  //        [1, 'a'],
+   *  //        [1, 'b']
+   *  //      ];
    */
   *entriesOf(key: K): IterableIterator<[K, V]> {
     const bucket = this.get(key);
@@ -2336,42 +404,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Iterates over all values for a specific key.
    * @remarks Time O(log n + m), Space O(1) where m is bucket size
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Get flat values for key
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       console.log([...mm.valuesOf(1)]); // ['a', 'b'];
+   * @example
+   * // Get flat values for key
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       console.log([...mm.valuesOf(1)]); // ['a', 'b'];
    */
   *valuesOf(key: K): IterableIterator<V> {
     const bucket = this.get(key);
@@ -2382,43 +420,17 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Iterates over all [key, value] pairs (flattened from buckets).
    * @remarks Time O(T), Space O(1) where T is totalSize
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // All key-value pairs flattened
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(1, 'b');
- *       mm.add(2, 'c');
- *       console.log([...mm.flatEntries()]); // [[1, 'a'], [1, 'b'], [2, 'c']];
+   * @example
+   * // All key-value pairs flattened
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(1, 'b');
+   *       mm.add(2, 'c');
+   *       console.log([...mm.flatEntries()]); // [
+   *  //        [1, 'a'],
+   *  //        [1, 'b'],
+   *  //        [2, 'c']
+   *  //      ];
    */
   *flatEntries(): IterableIterator<[K, V]> {
     for (const [k, bucket] of this) {
@@ -2431,82 +443,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Returns the entry with the smallest key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // First entry
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(3, 'c');
- *       mm.add(1, 'a');
- *       console.log(mm.first()?.[0]); // 1;
+   * @example
+   * // First entry
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(3, 'c');
+   *       mm.add(1, 'a');
+   *       console.log(mm.first()?.[0]); // 1;
    */
   first(): [K, V[]] | undefined {
     const k = this.#core.getLeftMost();
@@ -2518,82 +460,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Returns the entry with the largest key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Last entry
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(3, 'c');
- *       console.log(mm.last()?.[0]); // 3;
+   * @example
+   * // Last entry
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(3, 'c');
+   *       console.log(mm.last()?.[0]); // 3;
    */
   last(): [K, V[]] | undefined {
     const k = this.#core.getRightMost();
@@ -2605,45 +477,14 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Removes and returns the entry with the smallest key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove and return first
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(2, 'b');
- *       mm.add(1, 'a');
- *       const first = mm.pollFirst();
- *       console.log(first?.[0]); // 1;
- *       console.log(mm.has(1)); // false;
+   * @example
+   * // Remove and return first
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(2, 'b');
+   *       mm.add(1, 'a');
+   *       const first = mm.pollFirst();
+   *       console.log(first?.[0]); // 1;
+   *       console.log(mm.has(1)); // false;
    */
   pollFirst(): [K, V[]] | undefined {
     const e = this.first();
@@ -2655,44 +496,13 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Removes and returns the entry with the largest key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove and return last
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(3, 'c');
- *       const last = mm.pollLast();
- *       console.log(last?.[0]); // 3;
+   * @example
+   * // Remove and return last
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(3, 'c');
+   *       const last = mm.pollLast();
+   *       console.log(last?.[0]); // 3;
    */
   pollLast(): [K, V[]] | undefined {
     const e = this.last();
@@ -2704,194 +514,13 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Returns the entry with the smallest key >= given key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Least key ≥ target
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(10, 'a');
- *       mm.add(20, 'b');
- *       mm.add(30, 'c');
- *       console.log(mm.ceiling(15)?.[0]); // 20;
+   * @example
+   * // Least key ≥ target
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(10, 'a');
+   *       mm.add(20, 'b');
+   *       mm.add(30, 'c');
+   *       console.log(mm.ceiling(15)?.[0]); // 20;
    */
   ceiling(key: K): [K, V[]] | undefined {
     this._validateKey(key);
@@ -2904,194 +533,13 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Returns the entry with the largest key <= given key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Greatest key ≤ target
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(10, 'a');
- *       mm.add(20, 'b');
- *       mm.add(30, 'c');
- *       console.log(mm.floor(25)?.[0]); // 20;
+   * @example
+   * // Greatest key ≤ target
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(10, 'a');
+   *       mm.add(20, 'b');
+   *       mm.add(30, 'c');
+   *       console.log(mm.floor(25)?.[0]); // 20;
    */
   floor(key: K): [K, V[]] | undefined {
     this._validateKey(key);
@@ -3104,154 +552,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Returns the entry with the smallest key > given key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Least key > target
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(10, 'a');
- *       mm.add(20, 'b');
- *       console.log(mm.higher(10)?.[0]); // 20;
+   * @example
+   * // Least key > target
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(10, 'a');
+   *       mm.add(20, 'b');
+   *       console.log(mm.higher(10)?.[0]); // 20;
    */
   higher(key: K): [K, V[]] | undefined {
     this._validateKey(key);
@@ -3264,154 +570,12 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Returns the entry with the largest key < given key.
    * @remarks Time O(log n), Space O(1)
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Greatest key < target
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(10, 'a');
- *       mm.add(20, 'b');
- *       console.log(mm.lower(20)?.[0]); // 10;
+   * @example
+   * // Greatest key < target
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(10, 'a');
+   *       mm.add(20, 'b');
+   *       console.log(mm.lower(20)?.[0]); // 10;
    */
   lower(key: K): [K, V[]] | undefined {
     this._validateKey(key);
@@ -3426,189 +590,11 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Prints the internal tree structure (for debugging).
    * @remarks Time O(n), Space O(n)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Display tree
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       expect(() => mm.print()).not.toThrow();
+   * @example
+   * // Display tree
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       expect(() => mm.print()).not.toThrow();
    */
   print(): void {
     this.#core.print();
@@ -3617,192 +603,14 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Executes a callback for each entry.
    * @remarks Time O(n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Iterate entries
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(2, 'b');
- *       const keys: number[] = [];
- *       mm.forEach((v, k) => keys.push(k));
- *       console.log(keys); // [1, 2];
+   * @example
+   * // Iterate entries
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(2, 'b');
+   *       const keys: number[] = [];
+   *       mm.forEach((v, k) => keys.push(k));
+   *       console.log(keys); // [1, 2];
    */
   forEach(callback: (value: V[], key: K, map: this) => void): void {
     for (const [k, v] of this) {
@@ -3813,192 +621,14 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Creates a new map with entries that pass the predicate.
    * @remarks Time O(n), Space O(n)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Filter entries
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       mm.add(2, 'b');
- *       mm.add(3, 'c');
- *       const filtered = mm.filter((v, k) => k > 1);
- *       console.log([...filtered.keys()]); // [2, 3];
+   * @example
+   * // Filter entries
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       mm.add(2, 'b');
+   *       mm.add(3, 'c');
+   *       const filtered = mm.filter((v, k) => k > 1);
+   *       console.log([...filtered.keys()]); // [2, 3];
    */
   filter(predicate: (value: V[], key: K, map: this) => boolean): TreeMultiMap<K, V, R> {
     const filtered: [K, V[]][] = [];
@@ -4011,194 +641,14 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Creates a new map by transforming each entry.
    * @remarks Time O(n log n), Space O(n)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Transform values
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       const mapped = mm.map((v, k) => [k, v.map(s => s.toUpperCase())] as [number, string[]]);
- *       console.log(mapped.get(1)); // ['A'];
+   * @example
+   * // Transform values
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       const mapped = mm.map((v, k) => [k, v.map(s => s.toUpperCase())] as [number, string[]]);
+   *       console.log(mapped.get(1)); // ['A'];
    */
-  map<V2>(
-    mapper: (value: V[], key: K, map: this) => [K, V2[]]
-  ): TreeMultiMap<K, V2, R> {
+  map<V2>(mapper: (value: V[], key: K, map: this) => [K, V2[]]): TreeMultiMap<K, V2, R> {
     const mapped: [K, V2[]][] = [];
     for (const [k, v] of this) {
       mapped.push(mapper(v, k, this));
@@ -4209,191 +659,13 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Reduces all entries to a single value.
    * @remarks Time O(n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Aggregate
- *  const mm = new TreeMultiMap<number, number>();
- *       mm.add(1, 10);
- *       mm.add(2, 20);
- *       const sum = mm.reduce((acc, v) => acc + v.reduce((a, b) => a + b, 0), 0);
- *       console.log(sum); // 30;
+   * @example
+   * // Aggregate
+   *  const mm = new TreeMultiMap<number, number>();
+   *       mm.add(1, 10);
+   *       mm.add(2, 20);
+   *       const sum = mm.reduce((acc, v) => acc + v.reduce((a, b) => a + b, 0), 0);
+   *       console.log(sum); // 30;
    */
   reduce<U>(callback: (accumulator: U, value: V[], key: K, map: this) => U, initialValue: U): U {
     let acc = initialValue;
@@ -4406,181 +678,14 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Sets multiple entries at once.
    * @remarks Time O(m log n), Space O(m) where m is input size
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Set multiple entries
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.setMany([[1, ['a']], [2, ['b']]]);
- *       console.log(mm.size); // 2;
+   * @example
+   * // Set multiple entries
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.setMany([
+   *         [1, ['a']],
+   *         [2, ['b']]
+   *       ]);
+   *       console.log(mm.size); // 2;
    */
   setMany(keysNodesEntriesOrRaws: Iterable<K | [K | null | undefined, V[] | undefined]>): boolean[] {
     const results: boolean[] = [];
@@ -4594,156 +699,14 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Searches for entries within a key range.
    * @remarks Time O(log n + k), Space O(k) where k is result size
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Find keys in range
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(10, 'a');
- *       mm.add(20, 'b');
- *       mm.add(30, 'c');
- *       const result = mm.rangeSearch([15, 25]);
- *       console.log(result.length); // 1;
+   * @example
+   * // Find keys in range
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(10, 'a');
+   *       mm.add(20, 'b');
+   *       mm.add(30, 'c');
+   *       const result = mm.rangeSearch([15, 25]);
+   *       console.log(result.length); // 1;
    */
   rangeSearch<C extends (node: RedBlackTreeNode<K, V[]>) => unknown>(
     range: Range<K> | [K, K],
@@ -4755,270 +718,87 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Creates a shallow clone of this map.
    * @remarks Time O(n log n), Space O(n)
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Order-statistic on BST
- *  const tree = new TreeMultiMap<number>([30, 10, 50, 20, 40], { enableOrderStatistic: true });
- *       console.log(tree.getByRank(0)); // 10;
- *       console.log(tree.getByRank(4)); // 50;
- *       console.log(tree.getRank(30)); // 2;
+   * @example
+   * // Order-statistic on BST
+   *  const tree = new TreeMultiMap<number>([30, 10, 50, 20, 40], { enableOrderStatistic: true });
+   *       console.log(tree.getByRank(0)); // 10;
+   *       console.log(tree.getByRank(4)); // 50;
+   *       console.log(tree.getRank(30)); // 2;
    */
   // ─── Order-Statistic Methods ───────────────────────────
-
   getByRank(k: number): [K, V[]] | undefined {
     const key = this.#core.getByRank(k);
     if (key === undefined) return undefined;
     return [key, this.#core.get(key) ?? []];
   }
 
-    /**
+  /**
    * Get the rank of a key in sorted order
    * @example
- * // Get the rank of a key in sorted order
- *  const tree = new TreeMultiMap<number>(
- *         [10, 20, 30, 40, 50],
- *         { enableOrderStatistic: true }
- *       );
- *       console.log(tree.getRank(10)); // 0;  // smallest → rank 0
- *       console.log(tree.getRank(30)); // 2;  // 2 elements before 30 in tree order
- *       console.log(tree.getRank(50)); // 4;  // largest → rank 4
- *       console.log(tree.getRank(25)); // 2;
+   * // Get the rank of a key in sorted order
+   *  const tree = new TreeMultiMap<number>(
+   *         [10, 20, 30, 40, 50],
+   *         { enableOrderStatistic: true }
+   *       );
+   *       console.log(tree.getRank(10)); // 0;  // smallest → rank 0
+   *       console.log(tree.getRank(30)); // 2;  // 2 elements before 30 in tree order
+   *       console.log(tree.getRank(50)); // 4;  // largest → rank 4
+   *       console.log(tree.getRank(25)); // 2;
    */
   getRank(key: K): number {
     return this.#core.getRank(key);
   }
 
-    /**
+  /**
    * Get elements by rank range
-  
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Pagination by position in tree order
- *  const tree = new TreeMultiMap<number>(
- *         [10, 20, 30, 40, 50, 60, 70, 80, 90],
- *         { enableOrderStatistic: true }
- *       );
- *       const pageSize = 3;
- *
- *       // Page 1
- *       console.log(tree.rangeByRank(0, pageSize - 1)); // [10, 20, 30];
- *       // Page 2
- *       console.log(tree.rangeByRank(pageSize, 2 * pageSize - 1)); // [40, 50, 60];
- *       // Page 3
- *       console.log(tree.rangeByRank(2 * pageSize, 3 * pageSize - 1)); // [70, 80, 90];
+   * @example
+   * // Pagination by position in tree order
+   *  const tree = new TreeMultiMap<number>([10, 20, 30, 40, 50, 60, 70, 80, 90], { enableOrderStatistic: true });
+   *       const pageSize = 3;
+   *
+   *       // Page 1
+   *       console.log(tree.rangeByRank(0, pageSize - 1)); // [10, 20, 30];
+   *       // Page 2
+   *       console.log(tree.rangeByRank(pageSize, 2 * pageSize - 1)); // [40, 50, 60];
+   *       // Page 3
+   *       console.log(tree.rangeByRank(2 * pageSize, 3 * pageSize - 1)); // [70, 80, 90];
    */
   rangeByRank(start: number, end: number): Array<[K, V[]]> {
     const keys = this.#core.rangeByRank(start, end);
-    return keys
-      .filter((k): k is K => k !== undefined)
-      .map(k => [k, this.#core.get(k) ?? []] as [K, V[]]);
+    return keys.filter((k): k is K => k !== undefined).map(k => [k, this.#core.get(k) ?? []] as [K, V[]]);
   }
 
-    /**
+  /**
    * Deep copy
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Deep clone
- *  const mm = new TreeMultiMap<number, string>();
- *       mm.add(1, 'a');
- *       const copy = mm.clone();
- *       copy.delete(1);
- *       console.log(mm.has(1)); // true;
+   * @example
+   * // Deep clone
+   *  const mm = new TreeMultiMap<number, string>();
+   *       mm.add(1, 'a');
+   *       const copy = mm.clone();
+   *       copy.delete(1);
+   *       console.log(mm.has(1)); // true;
    */
   clone(): TreeMultiMap<K, V, R> {
     return new TreeMultiMap<K, V, R>(this, { comparator: this.comparator, isMapMode: this.#core.isMapMode });
   }
 
   /**
-   * Expose comparator for advanced usage/testing (read-only).
+   * Validates the key against the default comparator rules.
    * @remarks Time O(1), Space O(1)
    */
-  get comparator(): Comparator<K> {
-    return this.#core.comparator;
+  private _validateKey(key: K): void {
+    if (!this.#isDefaultComparator) return;
+    // reuse TreeSet strict validation (same policy)
+    // NOTE: TreeSet._validateKey is private, so we replicate the checks.
+    if (typeof key === 'number') {
+      if (Number.isNaN(key)) raise(TypeError, ERR.invalidNaN('TreeMultiMap'));
+      return;
+    }
+    if (typeof key === 'string') return;
+    if (key instanceof Date) {
+      if (Number.isNaN(key.getTime())) raise(TypeError, ERR.invalidDate('TreeMultiMap'));
+      return;
+    }
+    raise(TypeError, ERR.comparatorRequired('TreeMultiMap'));
   }
 }