data-structure-typed 2.4.4 → 2.5.0

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

@@ -7,21 +7,10 @@
  */
 
 import type { Comparator, TreeMultiMapOptions } from '../../types';
-import { Range } from '../../common';
+import { ERR, Range } from '../../common';
 import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
 import { TreeSet } from './tree-set';
 
-/**
- * Node type used by TreeMultiMap (alias to RedBlackTreeNode for backward compatibility).
- *
- * @deprecated Direct node manipulation is discouraged. Use TreeMultiMap methods instead.
- */
-export class TreeMultiMapNode<K = any, V = any> extends RedBlackTreeNode<K, V[]> {
-  constructor(key: K, value: V[] = []) {
-    super(key, value);
-  }
-}
-
 /**
  * TreeMultiMap (ordered MultiMap) — key → bucket (Array of values).
  *
@@ -31,169 +20,10 @@ export class TreeMultiMapNode<K = any, V = any> extends RedBlackTreeNode<K, V[]>
  * - 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 = {
- *       name: string; // Equipment name
- *       quality: 'legendary' | 'epic' | 'rare' | 'common';
- *       level: number;
- *     };
- *
- *     type Player = {
- *       name: string;
- *       score: number;
- *       equipments: Equipment[];
- *     };
- *
- *     // Mock player data with their scores and equipment
- *     const players: Player[] = [
- *       {
- *         name: 'DragonSlayer',
- *         score: 8750,
- *         equipments: [
- *           { name: 'AWM', quality: 'legendary', level: 85 },
- *           { name: 'Level 3 Helmet', quality: 'epic', level: 80 },
- *           { name: 'Extended Quickdraw Mag', quality: 'rare', level: 75 },
- *           { name: 'Compensator', quality: 'epic', level: 78 },
- *           { name: 'Vertical Grip', quality: 'rare', level: 72 }
- *         ]
- *       },
- *       {
- *         name: 'ShadowNinja',
- *         score: 7200,
- *         equipments: [
- *           { name: 'M416', quality: 'epic', level: 75 },
- *           { name: 'Ghillie Suit', quality: 'rare', level: 70 },
- *           { name: 'Red Dot Sight', quality: 'common', level: 65 },
- *           { name: 'Extended QuickDraw Mag', quality: 'rare', level: 68 }
- *         ]
- *       },
- *       {
- *         name: 'RuneMaster',
- *         score: 9100,
- *         equipments: [
- *           { name: 'KAR98K', quality: 'legendary', level: 90 },
- *           { name: 'Level 3 Vest', quality: 'legendary', level: 85 },
- *           { name: 'Holographic Sight', quality: 'epic', level: 82 },
- *           { name: 'Suppressor', quality: 'legendary', level: 88 },
- *           { name: 'Level 3 Backpack', quality: 'epic', level: 80 }
- *         ]
- *       },
- *       {
- *         name: 'BattleKing',
- *         score: 8500,
- *         equipments: [
- *           { name: 'AUG', quality: 'epic', level: 82 },
- *           { name: 'Red Dot Sight', quality: 'rare', level: 75 },
- *           { name: 'Extended Mag', quality: 'common', level: 70 },
- *           { name: 'Tactical Stock', quality: 'rare', level: 76 }
- *         ]
- *       },
- *       {
- *         name: 'SniperElite',
- *         score: 7800,
- *         equipments: [
- *           { name: 'M24', quality: 'legendary', level: 88 },
- *           { name: 'Compensator', quality: 'epic', level: 80 },
- *           { name: 'Scope 8x', quality: 'legendary', level: 85 },
- *           { name: 'Level 2 Helmet', quality: 'rare', level: 75 }
- *         ]
- *       },
- *       {
- *         name: 'RushMaster',
- *         score: 7500,
- *         equipments: [
- *           { name: 'Vector', quality: 'rare', level: 72 },
- *           { name: 'Level 2 Helmet', quality: 'common', level: 65 },
- *           { name: 'Quickdraw Mag', quality: 'common', level: 60 },
- *           { name: 'Laser Sight', quality: 'rare', level: 68 }
- *         ]
- *       },
- *       {
- *         name: 'GhostWarrior',
- *         score: 8200,
- *         equipments: [
- *           { name: 'SCAR-L', quality: 'epic', level: 78 },
- *           { name: 'Extended Quickdraw Mag', quality: 'rare', level: 70 },
- *           { name: 'Holographic Sight', quality: 'epic', level: 75 },
- *           { name: 'Suppressor', quality: 'rare', level: 72 },
- *           { name: 'Vertical Grip', quality: 'common', level: 65 }
- *         ]
- *       },
- *       {
- *         name: 'DeathDealer',
- *         score: 7300,
- *         equipments: [
- *           { name: 'SKS', quality: 'epic', level: 76 },
- *           { name: 'Holographic Sight', quality: 'rare', level: 68 },
- *           { name: 'Extended Mag', quality: 'common', level: 65 }
- *         ]
- *       },
- *       {
- *         name: 'StormRider',
- *         score: 8900,
- *         equipments: [
- *           { name: 'MK14', quality: 'legendary', level: 92 },
- *           { name: 'Level 3 Backpack', quality: 'legendary', level: 85 },
- *           { name: 'Scope 8x', quality: 'epic', level: 80 },
- *           { name: 'Suppressor', quality: 'legendary', level: 88 },
- *           { name: 'Tactical Stock', quality: 'rare', level: 75 }
- *         ]
- *       },
- *       {
- *         name: 'CombatLegend',
- *         score: 7600,
- *         equipments: [
- *           { name: 'UMP45', quality: 'rare', level: 74 },
- *           { name: 'Level 2 Vest', quality: 'common', level: 67 },
- *           { name: 'Red Dot Sight', quality: 'common', level: 62 },
- *           { name: 'Extended Mag', quality: 'rare', level: 70 }
- *         ]
- *       }
- *     ];
- *
- *     // Create a TreeMultiMap for player rankings
- *     const playerRankings = new TreeMultiMap<number, Equipment, Player>(players, {
- *       toEntryFn: ({ score, equipments }) => [score, equipments],
- *       isMapMode: false
- *     });
- *
- *     const topPlayersEquipments = playerRankings.rangeSearch([8900, 10000], node => playerRankings.get(node.key));
- *     console.log(topPlayersEquipments); // [
- *  //      [
- *  //        {
- *  //          name: 'MK14',
- *  //          quality: 'legendary',
- *  //          level: 92
- *  //        },
- *  //        { name: 'Level 3 Backpack', quality: 'legendary', level: 85 },
- *  //        {
- *  //          name: 'Scope 8x',
- *  //          quality: 'epic',
- *  //          level: 80
- *  //        },
- *  //        { name: 'Suppressor', quality: 'legendary', level: 88 },
- *  //        {
- *  //          name: 'Tactical Stock',
- *  //          quality: 'rare',
- *  //          level: 75
- *  //        }
- *  //      ],
- *  //      [
- *  //        { name: 'KAR98K', quality: 'legendary', level: 90 },
- *  //        {
- *  //          name: 'Level 3 Vest',
- *  //          quality: 'legendary',
- *  //          level: 85
- *  //        },
- *  //        { name: 'Holographic Sight', quality: 'epic', level: 82 },
- *  //        {
- *  //          name: 'Suppressor',
- *  //          quality: 'legendary',
- *  //          level: 88
- *  //        },
- *  //        { name: 'Level 3 Backpack', quality: 'epic', level: 80 }
- *  //      ]
- *  //    ];
+ * // Morris traversal (O(1) space)
+ *  const tmm = new TreeMultiMap<number>([5, 3, 7]);
+ *     const result = tmm.morris(n => n.key, 'IN');
+ *     console.log(result.length); // > 0;
  */
 export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]]> {
   readonly #core: RedBlackTree<K, V[], R>;
@@ -261,15 +91,15 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
     // reuse TreeSet strict validation (same policy)
     // NOTE: TreeSet._validateKey is private, so we replicate the checks.
     if (typeof key === 'number') {
-      if (Number.isNaN(key)) throw new TypeError('TreeMultiMap: NaN is not a valid key');
+      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN('TreeMultiMap'));
       return;
     }
     if (typeof key === 'string') return;
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError('TreeMultiMap: invalid Date key');
+      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate('TreeMultiMap'));
       return;
     }
-    throw new TypeError('TreeMultiMap: comparator is required for non-number/non-string/non-Date keys');
+    throw new TypeError(ERR.comparatorRequired('TreeMultiMap'));
   }
 
   /**
@@ -283,6 +113,52 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * Whether the map is empty.
    * @remarks Time O(1), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check if empty
+ *  console.log(new TreeMultiMap().isEmpty()); // true;
    */
   isEmpty(): boolean {
     return this.size === 0;
@@ -291,6 +167,55 @@ 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;
    */
   clear(): void {
     this.#core.clear();
@@ -299,6 +224,15 @@ 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;
    */
   count(key: K): number {
     const b = this.get(key);
@@ -308,6 +242,16 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * 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;
@@ -318,6 +262,70 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * 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;
    */
   has(key: K): boolean {
     this._validateKey(key);
@@ -327,6 +335,70 @@ 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'];
    */
   get(key: K): V[] | undefined {
     this._validateKey(key);
@@ -336,6 +408,50 @@ 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'];
    */
   add(key: K, value: V): boolean {
     this._validateKey(key);
@@ -350,6 +466,68 @@ 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'];
    */
   set(entry: [K | null | undefined, V[] | undefined] | K | null | undefined, value?: V): boolean;
   set(key: K, value: V): boolean;
@@ -379,6 +557,71 @@ 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;
    */
   delete(key: K): boolean {
     this._validateKey(key);
@@ -388,6 +631,15 @@ 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;
    */
   hasEntry(key: K, value: V, eq: (a: V, b: V) => boolean = Object.is): boolean {
     const bucket = this.get(key);
@@ -398,6 +650,16 @@ 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'];
    */
   deleteValue(key: K, value: V, eq: (a: V, b: V) => boolean = Object.is): boolean {
     const bucket = this.get(key);
@@ -412,6 +674,17 @@ 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;
    */
   deleteValues(key: K, value: V, eq: (a: V, b: V) => boolean = Object.is): number {
     const bucket = this.get(key);
@@ -436,13 +709,62 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   *[Symbol.iterator](): Iterator<[K, V[]]> {
     for (const [k, v] of this.#core) {
       // core always stores buckets, but guard anyway
-      yield [k, v ?? ([] as V[])];
+      yield [k, v ?? /* istanbul ignore next */ ([] as 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];
    */
   *keys(): IterableIterator<K> {
     yield* this.#core.keys();
@@ -451,6 +773,55 @@ 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']];
    */
   *values(): IterableIterator<V[]> {
     for (const [, bucket] of this) yield bucket;
@@ -461,6 +832,15 @@ export class TreeMultiMap<K = any, V = any, R = any> implements Iterable<[K, V[]
   /**
    * 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']];
    */
   *entriesOf(key: K): IterableIterator<[K, V]> {
     const bucket = this.get(key);
@@ -471,6 +851,15 @@ 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'];
    */
   *valuesOf(key: K): IterableIterator<V> {
     const bucket = this.get(key);
@@ -481,6 +870,16 @@ 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']];
    */
   *flatEntries(): IterableIterator<[K, V]> {
     for (const [k, bucket] of this) {
@@ -493,38 +892,84 @@ 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
-   * const map = new TreeMultiMap([[1, ['a']], [2, ['b']]]);
-   * map.first();  // [1, ['a']]
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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();
     if (k === undefined) return undefined;
     const b = this.get(k);
-    return b === undefined ? undefined : [k, b];
+    return b === undefined ? /* istanbul ignore next -- defensive: key in core always has bucket */ undefined : [k, b];
   }
 
   /**
    * 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']]
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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();
     if (k === undefined) return undefined;
     const b = this.get(k);
-    return b === undefined ? undefined : [k, b];
+    return b === undefined ? /* istanbul ignore next -- defensive: key in core always has bucket */ undefined : [k, b];
   }
 
   /**
    * 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
+  
+   
+   
+   
+    * @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();
@@ -536,10 +981,17 @@ 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
-   * const map = new TreeMultiMap([[1, ['a']], [2, ['b']]]);
-   * map.pollLast();  // [2, ['b']]
-   * map.has(2);      // false
+  
+   
+   
+   
+    * @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();
@@ -551,65 +1003,235 @@ 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
-   * const map = new TreeMultiMap([[10, ['a']], [20, ['b']], [30, ['c']]]);
-   * map.ceiling(15);  // [20, ['b']]
-   * map.ceiling(20);  // [20, ['b']]
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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);
     const k = this.#core.ceiling(key);
     if (k === undefined) return undefined;
     const b = this.get(k);
-    return b === undefined ? undefined : [k, b];
+    return b === undefined ? /* istanbul ignore next -- defensive: key in core always has bucket */ undefined : [k, b];
   }
 
   /**
    * 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']]
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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);
     const k = this.#core.floor(key);
     if (k === undefined) return undefined;
     const b = this.get(k);
-    return b === undefined ? undefined : [k, b];
+    return b === undefined ? /* istanbul ignore next -- defensive: key in core always has bucket */ undefined : [k, b];
   }
 
   /**
    * 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']]
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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);
     const k = this.#core.higher(key);
     if (k === undefined) return undefined;
     const b = this.get(k);
-    return b === undefined ? undefined : [k, b];
+    return b === undefined ? /* istanbul ignore next -- defensive: key in core always has bucket */ undefined : [k, b];
   }
 
   /**
    * 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']]
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @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);
     const k = this.#core.lower(key);
     if (k === undefined) return undefined;
     const b = this.get(k);
-    return b === undefined ? undefined : [k, b];
+    return b === undefined ? /* istanbul ignore next -- defensive: key in core always has bucket */ undefined : [k, b];
   }
 
   // ━━━ Tree utilities ━━━
@@ -617,6 +1239,54 @@ 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();
    */
   print(): void {
     this.#core.print();
@@ -625,6 +1295,57 @@ 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];
    */
   forEach(callback: (value: V[], key: K, map: this) => void): void {
     for (const [k, v] of this) {
@@ -635,6 +1356,57 @@ 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];
    */
   filter(predicate: (value: V[], key: K, map: this) => boolean): TreeMultiMap<K, V, R> {
     const filtered: [K, V[]][] = [];
@@ -647,6 +1419,55 @@ 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'];
    */
   map<V2>(
     mapper: (value: V[], key: K, map: this) => [K, V2[]]
@@ -661,6 +1482,56 @@ 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;
    */
   reduce<U>(callback: (accumulator: U, value: V[], key: K, map: this) => U, initialValue: U): U {
     let acc = initialValue;
@@ -673,6 +1544,46 @@ 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;
    */
   setMany(keysNodesEntriesOrRaws: Iterable<K | [K | null | undefined, V[] | undefined]>): boolean[] {
     const results: boolean[] = [];
@@ -686,6 +1597,48 @@ 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;
    */
   rangeSearch<C extends (node: RedBlackTreeNode<K, V[]>) => unknown>(
     range: Range<K> | [K, K],
@@ -697,6 +1650,56 @@ 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
+ * // 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 });