binary-tree-typed 2.5.0 → 2.5.1

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

@@ -86,6 +86,27 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    * @remarks Time O(1), Space O(1)
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
     * @example
  * // Unique key count
  *  const ms = new TreeMultiSet<number>();
@@ -138,17 +159,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Check empty
- *  console.log(new TreeMultiSet().isEmpty()); // true;
-   */
-  isEmpty(): boolean {
-    return this.size === 0;
-  }
-
-  /**
-   * Whether the multiset contains the given key.
-   * @remarks Time O(log n), Space O(1)
    
    
    
@@ -190,38 +200,8 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Check existence
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1);
- *       console.log(ms.has(1)); // true;
- *       console.log(ms.has(2)); // false;
-   */
-  has(key: K): boolean {
-    this._validateKey(key);
-    return this.count(key) > 0;
-  }
-
-  /**
-   * Returns the count of occurrences for the given key.
-   * @remarks Time O(log n), Space O(1)
    
    
-    * @example
- * // Get occurrence count
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 5);
- *       console.log(ms.count(1)); // 5;
-   */
-  count(key: K): number {
-    this._validateKey(key);
-    return this.#core.get(key) ?? 0;
-  }
-
-  /**
-   * Add `n` occurrences of `key`.
-   * @returns True if the multiset changed.
-   * @remarks Time O(log n), Space O(1)
    
    
    
@@ -254,59 +234,46 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Add elements
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1);
- *       ms.add(1);
- *       ms.add(2);
- *       console.log(ms.count(1)); // 2;
- *       console.log(ms.size); // 3;
-   */
-  add(key: K, n = 1): boolean {
-    this._validateKey(key);
-    this._validateCount(n);
-    if (n === 0) return false;
-
-    const old = this.#core.get(key) ?? 0;
-    const next = old + n;
-    this.#core.set(key, next);
-    this._size += n;
-    return true;
-  }
-
-  /**
-   * Set count for `key` to exactly `n`.
-   * @returns True if changed.
-   * @remarks Time O(log n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
     * @example
- * // Set occurrence count
- *  const ms = new TreeMultiSet<number>();
- *       ms.setCount(1, 3);
- *       console.log(ms.count(1)); // 3;
+ * // Check empty
+ *  console.log(new TreeMultiSet().isEmpty()); // true;
    */
-  setCount(key: K, n: number): boolean {
-    this._validateKey(key);
-    this._validateCount(n);
-
-    const old = this.#core.get(key) ?? 0;
-    if (old === n) return false;
-
-    if (n === 0) {
-      if (old !== 0) this.#core.delete(key);
-    } else {
-      this.#core.set(key, n);
-    }
-
-    this._size += n - old;
-    return true;
+  isEmpty(): boolean {
+    return this.size === 0;
   }
 
   /**
-   * Delete `n` occurrences of `key` (default 1).
-   * @returns True if any occurrence was removed.
+   * Whether the multiset contains the given key.
    * @remarks Time O(log n), Space O(1)
    
    
@@ -349,72 +316,10 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Remove one occurrence
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 3);
- *       ms.delete(1);
- *       console.log(ms.count(1)); // 2;
-   */
-  delete(key: K, n = 1): boolean {
-    this._validateKey(key);
-    this._validateCount(n);
-    if (n === 0) return false;
-
-    const old = this.#core.get(key) ?? 0;
-    if (old === 0) return false;
-
-    const removed = Math.min(old, n);
-    const next = old - removed;
-
-    if (next === 0) this.#core.delete(key);
-    else this.#core.set(key, next);
-
-    this._size -= removed;
-    return true;
-  }
-
-  /**
-   * Delete all occurrences of the given key.
-   * @returns True if any occurrence was removed.
-   * @remarks Time O(log n), Space O(1)
    
    
-    * @example
- * // Remove all occurrences
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 3);
- *       ms.deleteAll(1);
- *       console.log(ms.has(1)); // false;
-   */
-  deleteAll(key: K): boolean {
-    this._validateKey(key);
-    const old = this.#core.get(key) ?? 0;
-    if (old === 0) return false;
-    this.#core.delete(key);
-    this._size -= old;
-    return true;
-  }
-
-  /**
-   * Iterates over distinct keys (each key yielded once).
-   * @remarks Time O(n), Space O(1)
    
    
-    * @example
- * // Iterate unique keys
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 2);
- *       ms.add(2);
- *       console.log([...ms.keysDistinct()]); // [1, 2];
-   */
-  *keysDistinct(): IterableIterator<K> {
-    yield* this.#core.keys();
-  }
-
-  /**
-   * Iterates over entries as [key, count] pairs.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -453,31 +358,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Iterate entries
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 2);
- *       console.log([...ms.entries()].length); // > 0;
-   */
-  *entries(): IterableIterator<[K, number]> {
-    for (const [k, v] of this.#core) {
-      yield [k, v ?? 0];
-    }
-  }
-
-  /**
-   * 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> {
-    for (const [k, c] of this.entries()) {
-      for (let i = 0; i < c; i++) yield k;
-    }
-  }
-
-  /**
-   * Returns an array with all elements (expanded).
-   * @remarks Time O(size), Space O(size)
    
    
    
@@ -516,63 +396,183 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // All elements (with duplicates)
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 2);
- *       ms.add(2);
- *       console.log(ms.toArray()); // [1, 1, 2];
-   */
-  toArray(): K[] {
-    return [...this];
-  }
-
-  /**
-   * Returns an array with distinct keys only.
-   * @remarks Time O(n), Space O(n)
    
    
-    * @example
- * // Unique keys only
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 3);
- *       ms.add(2);
- *       console.log(ms.toDistinctArray()); // [1, 2];
-   */
-  toDistinctArray(): K[] {
-    return [...this.keysDistinct()];
-  }
-
-  /**
-   * Returns an array of [key, count] entries.
-   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
     * @example
- * // Key-count pairs
+ * // Check existence
  *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 2);
- *       ms.add(3);
- *       console.log(ms.toEntries()); // [[1, 2], [3, 1]];
+ *       ms.add(1);
+ *       console.log(ms.has(1)); // true;
+ *       console.log(ms.has(2)); // false;
    */
-  toEntries(): Array<[K, number]> {
-    return [...this.entries()];
+  has(key: K): boolean {
+    this._validateKey(key);
+    return this.count(key) > 0;
   }
 
   /**
-   * Expose comparator for advanced usage/testing (read-only).
-   * @remarks Time O(1), Space O(1)
+   * Returns the count of occurrences for the given key.
+   * @remarks Time O(log n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get occurrence count
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 5);
+ *       console.log(ms.count(1)); // 5;
    */
-  get comparator(): Comparator<K> {
-    return this.#core.comparator;
+  count(key: K): number {
+    this._validateKey(key);
+    return this.#core.get(key) ?? 0;
   }
 
-  // ━━━ clear ━━━
-
   /**
-   * Remove all elements from the multiset.
-   * @remarks Time O(1), Space O(1)
-  
+   * Add `n` occurrences of `key`.
+   * @returns True if the multiset changed.
+   * @remarks Time O(log n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -612,97 +612,2248 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
     * @example
- * // Remove all
+ * // Add elements
  *  const ms = new TreeMultiSet<number>();
  *       ms.add(1);
- *       ms.clear();
- *       console.log(ms.isEmpty()); // true;
+ *       ms.add(1);
+ *       ms.add(2);
+ *       console.log(ms.count(1)); // 2;
+ *       console.log(ms.size); // 3;
    */
-  clear(): void {
-    this.#core.clear();
-    this._size = 0;
-  }
+  add(key: K, n = 1): boolean {
+    this._validateKey(key);
+    this._validateCount(n);
+    if (n === 0) return false;
 
-  // ━━━ Navigable methods ━━━
+    const old = this.#core.get(key) ?? 0;
+    const next = old + n;
+    this.#core.set(key, next);
+    this._size += n;
+    return true;
+  }
 
   /**
-   * Returns the smallest key, or undefined if empty.
+   * Set count for `key` to exactly `n`.
+   * @returns True if changed.
    * @remarks Time O(log n), Space O(1)
-  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
     * @example
- * // Smallest element
+ * // Set occurrence count
  *  const ms = new TreeMultiSet<number>();
- *       ms.add(3);
- *       ms.add(1);
- *       console.log(ms.first()); // 1;
+ *       ms.setCount(1, 3);
+ *       console.log(ms.count(1)); // 3;
    */
-  first(): K | undefined {
-    return this.#core.getLeftMost();
+  setCount(key: K, n: number): boolean {
+    this._validateKey(key);
+    this._validateCount(n);
+
+    const old = this.#core.get(key) ?? 0;
+    if (old === n) return false;
+
+    if (n === 0) {
+      if (old !== 0) this.#core.delete(key);
+    } else {
+      this.#core.set(key, n);
+    }
+
+    this._size += n - old;
+    return true;
   }
 
   /**
-   * Returns the largest key, or undefined if empty.
+   * Delete `n` occurrences of `key` (default 1).
+   * @returns True if any occurrence was removed.
    * @remarks Time O(log n), Space O(1)
-  
    
    
-    * @example
- * // Largest element
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove one occurrence
  *  const ms = new TreeMultiSet<number>();
- *       ms.add(1);
- *       ms.add(3);
- *       console.log(ms.last()); // 3;
+ *       ms.add(1, 3);
+ *       ms.delete(1);
+ *       console.log(ms.count(1)); // 2;
    */
-  last(): K | undefined {
-    return this.#core.getRightMost();
+  delete(key: K, n = 1): boolean {
+    this._validateKey(key);
+    this._validateCount(n);
+    if (n === 0) return false;
+
+    const old = this.#core.get(key) ?? 0;
+    if (old === 0) return false;
+
+    const removed = Math.min(old, n);
+    const next = old - removed;
+
+    if (next === 0) this.#core.delete(key);
+    else this.#core.set(key, next);
+
+    this._size -= removed;
+    return true;
   }
 
   /**
-   * Removes all occurrences of the smallest key and returns it.
+   * Delete all occurrences of the given key.
+   * @returns True if any occurrence was removed.
    * @remarks Time O(log n), Space O(1)
-  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
     * @example
- * // Remove and return smallest
+ * // Remove all occurrences
  *  const ms = new TreeMultiSet<number>();
- *       ms.add(2);
- *       ms.add(1);
- *       console.log(ms.pollFirst()); // 1;
+ *       ms.add(1, 3);
+ *       ms.deleteAll(1);
  *       console.log(ms.has(1)); // false;
    */
-  pollFirst(): K | undefined {
-    const key = this.first();
-    if (key === undefined) return undefined;
-    this.deleteAll(key);
-    return key;
+  deleteAll(key: K): boolean {
+    this._validateKey(key);
+    const old = this.#core.get(key) ?? 0;
+    if (old === 0) return false;
+    this.#core.delete(key);
+    this._size -= old;
+    return true;
   }
 
   /**
-   * Removes all occurrences of the largest key and returns it.
-   * @remarks Time O(log n), Space O(1)
-  
+   * Iterates over distinct keys (each key yielded once).
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
     * @example
- * // Remove and return largest
+ * // Iterate unique keys
  *  const ms = new TreeMultiSet<number>();
- *       ms.add(1);
- *       ms.add(3);
- *       console.log(ms.pollLast()); // 3;
+ *       ms.add(1, 2);
+ *       ms.add(2);
+ *       console.log([...ms.keysDistinct()]); // [1, 2];
    */
-  pollLast(): K | undefined {
-    const key = this.last();
-    if (key === undefined) return undefined;
-    this.deleteAll(key);
-    return key;
+  *keysDistinct(): IterableIterator<K> {
+    yield* this.#core.keys();
+  }
+
+  /**
+   * Iterates over entries as [key, count] pairs.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Iterate entries
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       console.log([...ms.entries()].length); // > 0;
+   */
+  *entries(): IterableIterator<[K, number]> {
+    for (const [k, v] of this.#core) {
+      yield [k, v ?? 0];
+    }
+  }
+
+  /**
+   * 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> {
+    for (const [k, c] of this.entries()) {
+      for (let i = 0; i < c; i++) yield k;
+    }
+  }
+
+  /**
+   * Returns an array with all elements (expanded).
+   * @remarks Time O(size), Space O(size)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // All elements (with duplicates)
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2);
+ *       console.log(ms.toArray()); // [1, 1, 2];
+   */
+  toArray(): K[] {
+    return [...this];
+  }
+
+  /**
+   * Returns an array with distinct keys only.
+   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Unique keys only
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       ms.add(2);
+ *       console.log(ms.toDistinctArray()); // [1, 2];
+   */
+  toDistinctArray(): K[] {
+    return [...this.keysDistinct()];
+  }
+
+  /**
+   * Returns an array of [key, count] entries.
+   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Key-count pairs
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(3);
+ *       console.log(ms.toEntries()); // [[1, 2], [3, 1]];
+   */
+  toEntries(): Array<[K, number]> {
+    return [...this.entries()];
+  }
+
+  /**
+   * Expose comparator for advanced usage/testing (read-only).
+   * @remarks Time O(1), Space O(1)
+   */
+  get comparator(): Comparator<K> {
+    return this.#core.comparator;
+  }
+
+  // ━━━ clear ━━━
+
+  /**
+   * Remove all elements from the multiset.
+   * @remarks Time O(1), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       ms.clear();
+ *       console.log(ms.isEmpty()); // true;
+   */
+  clear(): void {
+    this.#core.clear();
+    this._size = 0;
+  }
+
+  // ━━━ Navigable methods ━━━
+
+  /**
+   * Returns the smallest key, or undefined if empty.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Smallest element
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(3);
+ *       ms.add(1);
+ *       console.log(ms.first()); // 1;
+   */
+  first(): K | undefined {
+    return this.#core.getLeftMost();
+  }
+
+  /**
+   * Returns the largest key, or undefined if empty.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Largest element
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       ms.add(3);
+ *       console.log(ms.last()); // 3;
+   */
+  last(): K | undefined {
+    return this.#core.getRightMost();
+  }
+
+  /**
+   * Removes all occurrences of the smallest key and returns it.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove and return smallest
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(2);
+ *       ms.add(1);
+ *       console.log(ms.pollFirst()); // 1;
+ *       console.log(ms.has(1)); // false;
+   */
+  pollFirst(): K | undefined {
+    const key = this.first();
+    if (key === undefined) return undefined;
+    this.deleteAll(key);
+    return key;
+  }
+
+  /**
+   * Removes all occurrences of the largest key and returns it.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove and return largest
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1);
+ *       ms.add(3);
+ *       console.log(ms.pollLast()); // 3;
+   */
+  pollLast(): K | undefined {
+    const key = this.last();
+    if (key === undefined) return undefined;
+    this.deleteAll(key);
+    return key;
+  }
+
+  /**
+   * Returns the smallest key >= given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Least key ≥ target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       ms.add(30);
+ *       console.log(ms.ceiling(15)); // 20;
+   */
+  ceiling(key: K): K | undefined {
+    this._validateKey(key);
+    return this.#core.ceiling(key);
+  }
+
+  /**
+   * Returns the largest key <= given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Greatest key ≤ target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       ms.add(30);
+ *       console.log(ms.floor(25)); // 20;
+   */
+  floor(key: K): K | undefined {
+    this._validateKey(key);
+    return this.#core.floor(key);
+  }
+
+  /**
+   * Returns the smallest key > given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Least key > target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       console.log(ms.higher(10)); // 20;
+   */
+  higher(key: K): K | undefined {
+    this._validateKey(key);
+    return this.#core.higher(key);
+  }
+
+  /**
+   * Returns the largest key < given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Greatest key < target
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(10);
+ *       ms.add(20);
+ *       console.log(ms.lower(20)); // 10;
+   */
+  lower(key: K): K | undefined {
+    this._validateKey(key);
+    return this.#core.lower(key);
+  }
+
+  // ━━━ Functional methods ━━━
+
+  /**
+   * Iterates over distinct keys with their counts.
+   * @remarks Time O(n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Iterate
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2);
+ *       const pairs: [number, number][] = [];
+ *       ms.forEach((k, c) => pairs.push([k, c]));
+ *       console.log(pairs); // [[1, 2], [2, 1]];
+   */
+  forEach(callback: (key: K, count: number) => void): void {
+    for (const [k, c] of this.entries()) {
+      callback(k, c);
+    }
+  }
+
+  /**
+   * Creates a new TreeMultiSet with entries that match the predicate.
+   * @remarks Time O(n log n), Space O(n)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 3);
+ *       ms.add(2, 1);
+ *       ms.add(3, 2);
+ *       const filtered = ms.filter((k, c) => c > 1);
+ *       console.log([...filtered.keysDistinct()]); // [1, 3];
+   */
+  filter(predicate: (key: K, count: number) => boolean): TreeMultiSet<K> {
+    const result = new TreeMultiSet<K>([], {
+      comparator: this.#isDefaultComparator ? undefined : this.comparator,
+      isMapMode: this.#core.isMapMode
+    });
+    for (const [k, c] of this.entries()) {
+      if (predicate(k, c)) {
+        result.add(k, c);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Reduces the multiset to a single value.
+   * @remarks Time O(n), Space O(1)
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Aggregate
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2, 3);
+ *       const sum = ms.reduce((acc, k, c) => acc + k * c, 0);
+ *       console.log(sum); // 8;
+   */
+  reduce<U>(callback: (accumulator: U, key: K, count: number) => U, initialValue: U): U {
+    let acc = initialValue;
+    for (const [k, c] of this.entries()) {
+      acc = callback(acc, k, c);
+    }
+    return acc;
+  }
+
+  /**
+   * 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
+ * // Transform
+ *  const ms = new TreeMultiSet<number>();
+ *       ms.add(1, 2);
+ *       ms.add(2, 3);
+ *       const doubled = ms.map((k, c) => [k * 10, c] as [number, number]);
+ *       console.log([...doubled.keysDistinct()]); // [10, 20];
+   */
+  map<K2>(
+    mapper: (key: K, count: number) => [K2, number],
+    options?: { comparator?: Comparator<K2> }
+  ): TreeMultiSet<K2> {
+    const result = new TreeMultiSet<K2>([], {
+      comparator: options?.comparator,
+      isMapMode: this.#core.isMapMode
+    });
+    for (const [k, c] of this.entries()) {
+      const [newKey, newCount] = mapper(k, c);
+      result.add(newKey, newCount);
+    }
+    return result;
   }
 
   /**
-   * Returns the smallest key >= given key, or undefined.
-   * @remarks Time O(log n), Space O(1)
+   * Creates an independent copy of this multiset.
+   * @remarks Time O(n log n), Space O(n)
   
    
    
@@ -733,23 +2884,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Least key ≥ target
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(10);
- *       ms.add(20);
- *       ms.add(30);
- *       console.log(ms.ceiling(15)); // 20;
-   */
-  ceiling(key: K): K | undefined {
-    this._validateKey(key);
-    return this.#core.ceiling(key);
-  }
-
-  /**
-   * Returns the largest key <= given key, or undefined.
-   * @remarks Time O(log n), Space O(1)
-  
    
    
    
@@ -779,23 +2913,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Greatest key ≤ target
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(10);
- *       ms.add(20);
- *       ms.add(30);
- *       console.log(ms.floor(25)); // 20;
-   */
-  floor(key: K): K | undefined {
-    this._validateKey(key);
-    return this.#core.floor(key);
-  }
-
-  /**
-   * Returns the smallest key > given key, or undefined.
-   * @remarks Time O(log n), Space O(1)
-  
    
    
    
@@ -825,22 +2942,33 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Least key > target
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(10);
- *       ms.add(20);
- *       console.log(ms.higher(10)); // 20;
-   */
-  higher(key: K): K | undefined {
-    this._validateKey(key);
-    return this.#core.higher(key);
-  }
-
-  /**
-   * Returns the largest key < given key, or undefined.
-   * @remarks Time O(log n), Space O(1)
-  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -871,22 +2999,29 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
     * @example
- * // Greatest key < target
+ * // Deep clone
  *  const ms = new TreeMultiSet<number>();
- *       ms.add(10);
- *       ms.add(20);
- *       console.log(ms.lower(20)); // 10;
+ *       ms.add(1, 3);
+ *       const copy = ms.clone();
+ *       copy.deleteAll(1);
+ *       console.log(ms.has(1)); // true;
    */
-  lower(key: K): K | undefined {
-    this._validateKey(key);
-    return this.#core.lower(key);
+  clone(): TreeMultiSet<K> {
+    const result = new TreeMultiSet<K>([], {
+      comparator: this.#isDefaultComparator ? undefined : this.comparator,
+      isMapMode: this.#core.isMapMode
+    });
+    for (const [k, c] of this.entries()) {
+      result.add(k, c);
+    }
+    return result;
   }
 
-  // ━━━ Functional methods ━━━
+  // ━━━ Tree utilities ━━━
 
   /**
-   * Iterates over distinct keys with their counts.
-   * @remarks Time O(n), Space O(1)
+   * Returns keys within the given range.
+   * @remarks Time O(log n + k), Space O(k) where k is result size
   
    
    
@@ -926,26 +3061,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Iterate
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 2);
- *       ms.add(2);
- *       const pairs: [number, number][] = [];
- *       ms.forEach((k, c) => pairs.push([k, c]));
- *       console.log(pairs); // [[1, 2], [2, 1]];
-   */
-  forEach(callback: (key: K, count: number) => void): void {
-    for (const [k, c] of this.entries()) {
-      callback(k, c);
-    }
-  }
-
-  /**
-   * Creates a new TreeMultiSet with entries that match the predicate.
-   * @remarks Time O(n log n), Space O(n)
-  
-   
    
    
    
@@ -983,32 +3098,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Filter
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 3);
- *       ms.add(2, 1);
- *       ms.add(3, 2);
- *       const filtered = ms.filter((k, c) => c > 1);
- *       console.log([...filtered.keysDistinct()]); // [1, 3];
-   */
-  filter(predicate: (key: K, count: number) => boolean): TreeMultiSet<K> {
-    const result = new TreeMultiSet<K>([], {
-      comparator: this.#isDefaultComparator ? undefined : this.comparator,
-      isMapMode: this.#core.isMapMode
-    });
-    for (const [k, c] of this.entries()) {
-      if (predicate(k, c)) {
-        result.add(k, c);
-      }
-    }
-    return result;
-  }
-
-  /**
-   * Reduces the multiset to a single value.
-   * @remarks Time O(n), Space O(1)
-  
    
    
    
@@ -1048,25 +3137,25 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
     * @example
- * // Aggregate
+ * // Find in range
  *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 2);
- *       ms.add(2, 3);
- *       const sum = ms.reduce((acc, k, c) => acc + k * c, 0);
- *       console.log(sum); // 8;
+ *       ms.add(10);
+ *       ms.add(20);
+ *       ms.add(30);
+ *       const result = ms.rangeSearch([15, 25]);
+ *       console.log(result.length); // 1;
    */
-  reduce<U>(callback: (accumulator: U, key: K, count: number) => U, initialValue: U): U {
-    let acc = initialValue;
-    for (const [k, c] of this.entries()) {
-      acc = callback(acc, k, c);
-    }
-    return acc;
+  rangeSearch<C extends (key: K) => any>(
+    range: [K, K],
+    callback?: C
+  ): (C extends undefined ? K : ReturnType<C>)[] {
+    const cb = callback ?? ((k: K) => k);
+    return this.#core.rangeSearch(range, node => cb(node.key));
   }
 
   /**
-   * 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)
+   * Prints the internal tree structure (for debugging).
+   * @remarks Time O(n), Space O(n)
   
    
    
@@ -1106,33 +3195,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Transform
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 2);
- *       ms.add(2, 3);
- *       const doubled = ms.map((k, c) => [k * 10, c] as [number, number]);
- *       console.log([...doubled.keysDistinct()]); // [10, 20];
-   */
-  map<K2>(
-    mapper: (key: K, count: number) => [K2, number],
-    options?: { comparator?: Comparator<K2> }
-  ): TreeMultiSet<K2> {
-    const result = new TreeMultiSet<K2>([], {
-      comparator: options?.comparator,
-      isMapMode: this.#core.isMapMode
-    });
-    for (const [k, c] of this.entries()) {
-      const [newKey, newCount] = mapper(k, c);
-      result.add(newKey, newCount);
-    }
-    return result;
-  }
-
-  /**
-   * Creates an independent copy of this multiset.
-   * @remarks Time O(n log n), Space O(n)
-  
    
    
    
@@ -1171,31 +3233,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Deep clone
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(1, 3);
- *       const copy = ms.clone();
- *       copy.deleteAll(1);
- *       console.log(ms.has(1)); // true;
-   */
-  clone(): TreeMultiSet<K> {
-    const result = new TreeMultiSet<K>([], {
-      comparator: this.#isDefaultComparator ? undefined : this.comparator,
-      isMapMode: this.#core.isMapMode
-    });
-    for (const [k, c] of this.entries()) {
-      result.add(k, c);
-    }
-    return result;
-  }
-
-  // ━━━ Tree utilities ━━━
-
-  /**
-   * Returns keys within the given range.
-   * @remarks Time O(log n + k), Space O(k) where k is result size
-  
    
    
    
@@ -1225,27 +3262,6 @@ export class TreeMultiSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Find in range
- *  const ms = new TreeMultiSet<number>();
- *       ms.add(10);
- *       ms.add(20);
- *       ms.add(30);
- *       const result = ms.rangeSearch([15, 25]);
- *       console.log(result.length); // 1;
-   */
-  rangeSearch<C extends (key: K) => any>(
-    range: [K, K],
-    callback?: C
-  ): (C extends undefined ? K : ReturnType<C>)[] {
-    const cb = callback ?? ((k: K) => k);
-    return this.#core.rangeSearch(range, node => cb(node.key));
-  }
-
-  /**
-   * Prints the internal tree structure (for debugging).
-   * @remarks Time O(n), Space O(n)
-