data-structure-typed 2.3.0 → 2.4.0

package/dist/esm/index.mjs

@@ -7042,6 +7042,9 @@ var BinaryTree = class extends IterableEntryBase {
   get isDuplicate() {
     return this._isDuplicate;
   }
+  // Map mode acceleration store:
+  // - isMapMode=false: unused
+  // - isMapMode=true: key -> node reference (O(1) has/getNode + fast get)
   _store = /* @__PURE__ */ new Map();
   /**
    * Gets the external value store (used in Map mode).
@@ -7101,7 +7104,7 @@ var BinaryTree = class extends IterableEntryBase {
    * @returns The newly created node.
    */
   createNode(key, value) {
-    return new BinaryTreeNode(key, this._isMapMode ? void 0 : value);
+    return new BinaryTreeNode(key, value);
   }
   /**
    * Creates a new, empty tree of the same type and configuration.
@@ -7248,11 +7251,11 @@ var BinaryTree = class extends IterableEntryBase {
    * @returns True if the addition was successful, false otherwise.
    */
   set(keyNodeOrEntry, value) {
-    const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
+    const [newNode] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
     if (newNode === void 0) return false;
     if (!this._root) {
       this._setRoot(newNode);
-      if (this._isMapMode) this._setValue(newNode?.key, newValue);
+      if (this._isMapMode && newNode !== null && newNode !== void 0) this._store.set(newNode.key, newNode);
       this._size = 1;
       return true;
     }
@@ -7264,7 +7267,7 @@ var BinaryTree = class extends IterableEntryBase {
       if (!this._isDuplicate) {
         if (newNode !== null && cur.key === newNode.key) {
           this._replaceNode(cur, newNode);
-          if (this._isMapMode) this._setValue(cur.key, newValue);
+          if (this._isMapMode && newNode !== null) this._store.set(cur.key, newNode);
           return true;
         }
       }
@@ -7284,7 +7287,7 @@ var BinaryTree = class extends IterableEntryBase {
       } else if (potentialParent.right === void 0) {
         potentialParent.right = newNode;
       }
-      if (this._isMapMode) this._setValue(newNode?.key, newValue);
+      if (this._isMapMode && newNode !== null && newNode !== void 0) this._store.set(newNode.key, newNode);
       this._size++;
       return true;
     }
@@ -7369,6 +7372,10 @@ var BinaryTree = class extends IterableEntryBase {
       if (leftSubTreeRightMost) {
         const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
         orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
+        if (this._isMapMode) {
+          this._store.set(curr.key, curr);
+          this._store.set(leftSubTreeRightMost.key, leftSubTreeRightMost);
+        }
         if (parentOfLeftSubTreeMax) {
           if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost)
             parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
@@ -7452,6 +7459,13 @@ var BinaryTree = class extends IterableEntryBase {
    * @returns The first matching node, or undefined if not found.
    */
   getNode(keyNodeEntryOrPredicate, startNode = this._root, iterationType = this.iterationType) {
+    if (this._isMapMode && keyNodeEntryOrPredicate !== null && keyNodeEntryOrPredicate !== void 0) {
+      if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+        const key = this._extractKey(keyNodeEntryOrPredicate);
+        if (key === null || key === void 0) return;
+        return this._store.get(key);
+      }
+    }
     return this.search(keyNodeEntryOrPredicate, true, (node) => node, startNode, iterationType)[0];
   }
   /**
@@ -7467,11 +7481,18 @@ var BinaryTree = class extends IterableEntryBase {
     if (this._isMapMode) {
       const key = this._extractKey(keyNodeEntryOrPredicate);
       if (key === null || key === void 0) return;
-      return this._store.get(key);
+      return this._store.get(key)?.value;
     }
     return this.getNode(keyNodeEntryOrPredicate, startNode, iterationType)?.value;
   }
   has(keyNodeEntryOrPredicate, startNode = this._root, iterationType = this.iterationType) {
+    if (this._isMapMode && keyNodeEntryOrPredicate !== void 0 && keyNodeEntryOrPredicate !== null) {
+      if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+        const key = this._extractKey(keyNodeEntryOrPredicate);
+        if (key === null || key === void 0) return false;
+        return this._store.has(key);
+      }
+    }
     return this.search(keyNodeEntryOrPredicate, true, (node) => node, startNode, iterationType).length > 0;
   }
   /**
@@ -8214,8 +8235,7 @@ var BinaryTree = class extends IterableEntryBase {
         }
         current = stack.pop();
         if (this.isRealNode(current)) {
-          if (this._isMapMode) yield [current.key, this._store.get(current.key)];
-          else yield [current.key, current.value];
+          yield [current.key, current.value];
           current = current.right;
         }
       }
@@ -8223,8 +8243,7 @@ var BinaryTree = class extends IterableEntryBase {
       if (node.left && this.isRealNode(node)) {
         yield* this[Symbol.iterator](node.left);
       }
-      if (this._isMapMode) yield [node.key, this._store.get(node.key)];
-      else yield [node.key, node.value];
+      yield [node.key, node.value];
       if (node.right && this.isRealNode(node)) {
         yield* this[Symbol.iterator](node.right);
       }
@@ -8310,8 +8329,7 @@ var BinaryTree = class extends IterableEntryBase {
       (node) => {
         if (node === null) cloned.set(null);
         else {
-          if (this._isMapMode) cloned.set([node.key, this._store.get(node.key)]);
-          else cloned.set([node.key, node.value]);
+          cloned.set([node.key, node.value]);
         }
       },
       this._root,
@@ -8319,7 +8337,6 @@ var BinaryTree = class extends IterableEntryBase {
       true
       // Include nulls
     );
-    if (this._isMapMode) cloned._store = this._store;
   }
   /**
    * (Protected) Recursive helper for `toVisual`.
@@ -8482,8 +8499,10 @@ var BinaryTree = class extends IterableEntryBase {
    */
   _setValue(key, value) {
     if (key === null || key === void 0) return false;
-    if (value === void 0) return false;
-    return this._store.set(key, value);
+    const node = this._store.get(key);
+    if (!node) return false;
+    node.value = value;
+    return true;
   }
   /**
    * (Protected) Clears all nodes from the tree.
@@ -8694,7 +8713,7 @@ var BST = class extends BinaryTree {
    * @returns The newly created BSTNode.
    */
   createNode(key, value) {
-    return new BSTNode(key, this._isMapMode ? void 0 : value);
+    return new BSTNode(key, value);
   }
   /**
    * Ensures the input is a node. If it's a key or entry, it searches for the node.
@@ -8933,11 +8952,11 @@ var BST = class extends BinaryTree {
    * @returns True if the addition was successful, false otherwise.
    */
   set(keyNodeOrEntry, value) {
-    const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
+    const [newNode] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
     if (newNode === void 0) return false;
     if (this._root === void 0) {
       this._setRoot(newNode);
-      if (this._isMapMode) this._setValue(newNode?.key, newValue);
+      if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
       this._size++;
       return true;
     }
@@ -8945,12 +8964,12 @@ var BST = class extends BinaryTree {
     while (current !== void 0) {
       if (this._compare(current.key, newNode.key) === 0) {
         this._replaceNode(current, newNode);
-        if (this._isMapMode) this._setValue(current.key, newValue);
+        if (this._isMapMode && this.isRealNode(newNode)) this._store.set(current.key, newNode);
         return true;
       } else if (this._compare(current.key, newNode.key) > 0) {
         if (current.left === void 0) {
           current.left = newNode;
-          if (this._isMapMode) this._setValue(newNode?.key, newValue);
+          if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
           this._size++;
           return true;
         }
@@ -8958,7 +8977,7 @@ var BST = class extends BinaryTree {
       } else {
         if (current.right === void 0) {
           current.right = newNode;
-          if (this._isMapMode) this._setValue(newNode?.key, newValue);
+          if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
           this._size++;
           return true;
         }
@@ -10515,7 +10534,7 @@ var AVLTree = class extends BST {
    * @returns The newly created AVLTreeNode.
    */
   createNode(key, value) {
-    return new AVLTreeNode(key, this._isMapMode ? void 0 : value);
+    return new AVLTreeNode(key, value);
   }
   /**
    * Checks if the given item is an `AVLTreeNode` instance.
@@ -11071,7 +11090,7 @@ var RedBlackTree = class extends BST {
    * @returns A new RedBlackTreeNode instance.
    */
   createNode(key, value, color = "BLACK") {
-    return new RedBlackTreeNode(key, this._isMapMode ? void 0 : value, color);
+    return new RedBlackTreeNode(key, value, color);
   }
   /**
    * Type guard: check whether the input is a RedBlackTreeNode.
@@ -11220,20 +11239,15 @@ var RedBlackTree = class extends BST {
     if (minN !== NIL) {
       const cMin = comparator(key, minN.key);
       if (cMin === 0) {
-        if (this._isMapMode) {
-          if (nextValue !== void 0) this._store.set(key, nextValue);
-          else this._setValue(key, nextValue);
-        } else minN.value = nextValue;
+        minN.value = nextValue;
+        if (this._isMapMode) this._store.set(key, minN);
         return { node: minN, created: false };
       }
       const minL = minN.left;
       if (cMin < 0 && (minL === NIL || minL === null || minL === void 0)) {
         const newNode2 = this.createNode(key, nextValue);
         this._attachNewNode(minN, "left", newNode2);
-        if (this._isMapMode) {
-          if (nextValue !== void 0) this._store.set(newNode2.key, nextValue);
-          else this._setValue(newNode2.key, nextValue);
-        }
+        if (this._isMapMode) this._store.set(newNode2.key, newNode2);
         this._size++;
         this._setMinCache(newNode2);
         if (header._right === NIL) this._setMaxCache(newNode2);
@@ -11243,20 +11257,15 @@ var RedBlackTree = class extends BST {
         const maxN = header._right ?? NIL;
         const cMax = comparator(key, maxN.key);
         if (cMax === 0) {
-          if (this._isMapMode) {
-            if (nextValue !== void 0) this._store.set(key, nextValue);
-            else this._setValue(key, nextValue);
-          } else maxN.value = nextValue;
+          maxN.value = nextValue;
+          if (this._isMapMode) this._store.set(key, maxN);
           return { node: maxN, created: false };
         }
         const maxR = maxN.right;
         if (cMax > 0 && (maxR === NIL || maxR === null || maxR === void 0)) {
           const newNode2 = this.createNode(key, nextValue);
           this._attachNewNode(maxN, "right", newNode2);
-          if (this._isMapMode) {
-            if (nextValue !== void 0) this._store.set(newNode2.key, nextValue);
-            else this._setValue(newNode2.key, nextValue);
-          }
+          if (this._isMapMode) this._store.set(newNode2.key, newNode2);
           this._size++;
           this._setMaxCache(newNode2);
           if (header._left === NIL) this._setMinCache(newNode2);
@@ -11276,12 +11285,8 @@ var RedBlackTree = class extends BST {
       if (lastCompared < 0) current = current.left ?? NIL;
       else if (lastCompared > 0) current = current.right ?? NIL;
       else {
-        if (isMapMode) {
-          if (nextValue !== void 0) store.set(key, nextValue);
-          else this._setValue(key, nextValue);
-        } else {
-          current.value = nextValue;
-        }
+        current.value = nextValue;
+        if (isMapMode) store.set(key, current);
         return { node: current, created: false };
       }
     }
@@ -11300,10 +11305,7 @@ var RedBlackTree = class extends BST {
     this._insertFixup(newNode);
     if (this.isRealNode(this._root)) this._root.color = "BLACK";
     else return void 0;
-    if (isMapMode) {
-      if (nextValue !== void 0) store.set(newNode.key, nextValue);
-      else this._setValue(newNode.key, nextValue);
-    }
+    if (isMapMode) store.set(newNode.key, newNode);
     this._size++;
     const hMin = this._header._left ?? NIL;
     const hMax = this._header._right ?? NIL;
@@ -11331,10 +11333,11 @@ var RedBlackTree = class extends BST {
    * @remarks Time O(log n) average, Space O(1)
    */
   _setKV(key, nextValue) {
-    if (this._isMapMode && nextValue !== void 0) {
+    if (this._isMapMode) {
       const store = this._store;
-      if (store.has(key)) {
-        store.set(key, nextValue);
+      const node = store.get(key);
+      if (node) {
+        node.value = nextValue;
         return true;
       }
     }
@@ -11358,10 +11361,8 @@ var RedBlackTree = class extends BST {
     const cmp = this._compare.bind(this);
     const c0 = cmp(key, hint.key);
     if (c0 === 0) {
-      if (this._isMapMode) {
-        if (value !== void 0) this._store.set(key, value);
-        else this._setValue(key, value);
-      } else hint.value = value;
+      hint.value = value;
+      if (this._isMapMode) this._store.set(key, hint);
       return hint;
     }
     if (c0 < 0) {
@@ -11369,10 +11370,7 @@ var RedBlackTree = class extends BST {
         const newNode = this.createNode(key, value);
         if (!this.isRealNode(newNode)) return void 0;
         this._attachNewNode(hint, "left", newNode);
-        if (this._isMapMode) {
-          if (value !== void 0) this._store.set(key, value);
-          else this._setValue(key, value);
-        }
+        if (this._isMapMode) this._store.set(key, newNode);
         this._size++;
         const NIL = this.NIL;
         const hMin = this._header._left ?? NIL;
@@ -11389,10 +11387,7 @@ var RedBlackTree = class extends BST {
         const newNode = this.createNode(key, value);
         if (!this.isRealNode(newNode)) return void 0;
         this._attachNewNode(pred, "right", newNode);
-        if (this._isMapMode) {
-          if (value !== void 0) this._store.set(key, value);
-          else this._setValue(key, value);
-        }
+        if (this._isMapMode) this._store.set(key, newNode);
         this._size++;
         const NIL = this.NIL;
         const hMin = this._header._left ?? NIL;
@@ -11407,10 +11402,7 @@ var RedBlackTree = class extends BST {
       const newNode = this.createNode(key, value);
       if (!this.isRealNode(newNode)) return void 0;
       this._attachNewNode(hint, "right", newNode);
-      if (this._isMapMode) {
-        if (value !== void 0) this._store.set(key, value);
-        else this._setValue(key, value);
-      }
+      if (this._isMapMode) this._store.set(key, newNode);
       this._size++;
       const NIL = this.NIL;
       const hMin = this._header._left ?? NIL;
@@ -11427,10 +11419,7 @@ var RedBlackTree = class extends BST {
       const newNode = this.createNode(key, value);
       if (!this.isRealNode(newNode)) return void 0;
       this._attachNewNode(succ, "left", newNode);
-      if (this._isMapMode) {
-        if (value !== void 0) this._store.set(key, value);
-        else this._setValue(key, value);
-      }
+      if (this._isMapMode) this._store.set(key, newNode);
       this._size++;
       const NIL = this.NIL;
       const hMin = this._header._left ?? NIL;
@@ -11477,12 +11466,24 @@ var RedBlackTree = class extends BST {
       } else {
         return false;
       }
-      if (this._isMapMode) this._setValue(newNode.key, newValue);
+      if (this._isMapMode) {
+        const n = this.getNode(newNode.key);
+        if (this.isRealNode(n)) {
+          n.value = newValue;
+          this._store.set(n.key, n);
+        }
+      }
       this._size++;
       return true;
     }
     if (insertStatus === "UPDATED") {
-      if (this._isMapMode) this._setValue(newNode.key, newValue);
+      if (this._isMapMode) {
+        const n = this.getNode(newNode.key);
+        if (this.isRealNode(n)) {
+          n.value = newValue;
+          this._store.set(n.key, n);
+        }
+      }
       return true;
     }
     return false;
@@ -11848,1457 +11849,1521 @@ var RedBlackTree = class extends BST {
   }
 };
 
-// src/data-structures/binary-tree/avl-tree-multi-map.ts
-var AVLTreeMultiMapNode = class {
+// src/data-structures/binary-tree/tree-set.ts
+var TreeSet = class _TreeSet {
   static {
-    __name(this, "AVLTreeMultiMapNode");
+    __name(this, "TreeSet");
   }
-  key;
-  value;
-  parent = void 0;
+  #core;
+  #isDefaultComparator;
+  #userComparator;
   /**
-   * Create an AVLTreeMultiMap node with a value bucket.
-   * @remarks Time O(1), Space O(1)
-   * @param key - Key of the node.
-   * @param value - Initial array of values.
-   * @returns New AVLTreeMultiMapNode instance.
+   * Create a TreeSet from an iterable of keys.
+   *
+   * @throws {TypeError} When using the default comparator and encountering unsupported key types,
+   * or invalid keys (e.g. `NaN`, invalid `Date`).
    */
-  constructor(key, value = []) {
-    this.key = key;
-    this.value = value;
+  constructor(elements = [], options = {}) {
+    this.#userComparator = options.comparator;
+    const comparator = options.comparator ?? _TreeSet.createDefaultComparator();
+    this.#isDefaultComparator = options.comparator === void 0;
+    this.#core = new RedBlackTree([], { comparator, isMapMode: options.isMapMode });
+    for (const k of elements) this.add(k);
   }
-  _left = void 0;
   /**
-   * Get the left child pointer.
-   * @remarks Time O(1), Space O(1)
-   * @returns Left child node, or null/undefined.
+   * Create the strict default comparator.
+   *
+   * Supports:
+   * - `number` (rejects `NaN`; treats `-0` and `0` as equal)
+   * - `string`
+   * - `Date` (orders by `getTime()`, rejects invalid dates)
+   *
+   * For other key types, a custom comparator must be provided.
    */
-  get left() {
-    return this._left;
+  static createDefaultComparator() {
+    return (a, b) => {
+      if (typeof a === "number" && typeof b === "number") {
+        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError("TreeSet: NaN is not a valid key");
+        const aa = Object.is(a, -0) ? 0 : a;
+        const bb = Object.is(b, -0) ? 0 : b;
+        return aa > bb ? 1 : aa < bb ? -1 : 0;
+      }
+      if (typeof a === "string" && typeof b === "string") {
+        return a > b ? 1 : a < b ? -1 : 0;
+      }
+      if (a instanceof Date && b instanceof Date) {
+        const ta = a.getTime();
+        const tb = b.getTime();
+        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError("TreeSet: invalid Date key");
+        return ta > tb ? 1 : ta < tb ? -1 : 0;
+      }
+      throw new TypeError("TreeSet: comparator is required for non-number/non-string/non-Date keys");
+    };
   }
   /**
-   * Set the left child and update its parent pointer.
-   * @remarks Time O(1), Space O(1)
-   * @param v - New left child node, or null/undefined.
-   * @returns void
+   * Number of elements in the set.
    */
-  set left(v) {
-    if (v) {
-      v.parent = this;
+  get size() {
+    return this.#core.size;
+  }
+  /**
+   * Whether the set is empty.
+   */
+  isEmpty() {
+    return this.size === 0;
+  }
+  _validateKey(key) {
+    if (!this.#isDefaultComparator) return;
+    if (typeof key === "number") {
+      if (Number.isNaN(key)) throw new TypeError("TreeSet: NaN is not a valid key");
+      return;
     }
-    this._left = v;
+    if (typeof key === "string") return;
+    if (key instanceof Date) {
+      if (Number.isNaN(key.getTime())) throw new TypeError("TreeSet: invalid Date key");
+      return;
+    }
+    throw new TypeError("TreeSet: comparator is required for non-number/non-string/non-Date keys");
   }
-  _right = void 0;
   /**
-   * Get the right child pointer.
-   * @remarks Time O(1), Space O(1)
-   * @returns Right child node, or null/undefined.
+   * Add a key to the set (no-op if already present).
+   * @remarks Expected time O(log n)
    */
-  get right() {
-    return this._right;
+  add(key) {
+    this._validateKey(key);
+    this.#core.set(key, void 0);
+    return this;
   }
   /**
-   * Set the right child and update its parent pointer.
-   * @remarks Time O(1), Space O(1)
-   * @param v - New right child node, or null/undefined.
-   * @returns void
+   * Test whether a key exists.
+   * @remarks Expected time O(log n)
    */
-  set right(v) {
-    if (v) {
-      v.parent = this;
-    }
-    this._right = v;
+  has(key) {
+    this._validateKey(key);
+    return this.#core.has(key);
   }
-  _height = 0;
   /**
-   * Gets the height of the node (used in self-balancing trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The height.
+   * Delete a key.
+   * @returns `true` if the key existed; otherwise `false`.
+   * @remarks Expected time O(log n)
    */
-  get height() {
-    return this._height;
+  delete(key) {
+    this._validateKey(key);
+    const res = this.#core.delete(key);
+    return Array.isArray(res) && res.length > 0 && !!res[0]?.deleted;
   }
   /**
-   * Sets the height of the node.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new height.
+   * Remove all keys.
    */
-  set height(value) {
-    this._height = value;
+  clear() {
+    this.#core.clear();
   }
-  _color = "BLACK";
   /**
-   * Gets the color of the node (used in Red-Black trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The node's color.
+   * Iterate over keys in ascending order.
    */
-  get color() {
-    return this._color;
+  keys() {
+    return this.#core.keys();
   }
   /**
-   * Sets the color of the node.
-   * @remarks Time O(1), Space O(1)
+   * Iterate over values in ascending order.
    *
-   * @param value - The new color.
+   * Note: for Set-like containers, `values()` is the same as `keys()`.
    */
-  set color(value) {
-    this._color = value;
+  values() {
+    return this.keys();
   }
-  _count = 1;
   /**
-   * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
-   * @remarks Time O(1), Space O(1)
+   * Iterate over `[value, value]` pairs (native Set convention).
    *
-   * @returns The subtree node count.
+   * Note: TreeSet stores only keys internally; `[k, k]` is created on-the-fly during iteration.
    */
-  get count() {
-    return this._count;
+  *entries() {
+    for (const k of this.keys()) yield [k, k];
+  }
+  [Symbol.iterator]() {
+    return this.keys();
   }
   /**
-   * Sets the count of nodes in the subtree.
-   * @remarks Time O(1), Space O(1)
+   * Visit each value in ascending order.
    *
-   * @param value - The new count.
+   * Callback follows native Set convention: `(value, value2, set)`.
    */
-  set count(value) {
-    this._count = value;
+  forEach(cb, thisArg) {
+    for (const k of this) cb.call(thisArg, k, k, this);
   }
   /**
-   * Gets the position of the node relative to its parent.
-   * @remarks Time O(1), Space O(1)
+   * Create a new TreeSet by mapping each value to a new key.
    *
-   * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
+   * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
+   * @remarks Time O(n log n) expected, Space O(n)
    */
-  get familyPosition() {
-    if (!this.parent) {
-      return this.left || this.right ? "ROOT" : "ISOLATED";
-    }
-    if (this.parent.left === this) {
-      return this.left || this.right ? "ROOT_LEFT" : "LEFT";
-    } else if (this.parent.right === this) {
-      return this.left || this.right ? "ROOT_RIGHT" : "RIGHT";
+  map(callbackfn, options = {}, thisArg) {
+    const out = new _TreeSet([], options);
+    let index = 0;
+    for (const v of this) {
+      const mk = thisArg === void 0 ? callbackfn(v, index++, this) : callbackfn.call(thisArg, v, index++, this);
+      out.add(mk);
     }
-    return "MAL_NODE";
-  }
-};
-var AVLTreeMultiMap = class extends AVLTree {
-  static {
-    __name(this, "AVLTreeMultiMap");
+    return out;
   }
   /**
-   * Create an AVLTreeMultiMap and optionally bulk-insert items.
-   * @remarks Time O(N log N), Space O(N)
-   * @param [keysNodesEntriesOrRaws] - Iterable of keys/nodes/entries/raw items to insert.
-   * @param [options] - Options for AVLTreeMultiMap (comparator, reverse, map mode).
-   * @returns New AVLTreeMultiMap instance.
+   * Create a new TreeSet containing only values that satisfy the predicate.
+   * @remarks Time O(n log n) expected, Space O(n)
    */
-  constructor(keysNodesEntriesOrRaws = [], options) {
-    super([], { ...options, isMapMode: true });
-    if (keysNodesEntriesOrRaws) {
-      this.setMany(keysNodesEntriesOrRaws);
+  filter(callbackfn, thisArg) {
+    const out = new _TreeSet([], { comparator: this.#userComparator });
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, index++, this) : callbackfn.call(thisArg, v, index++, this);
+      if (ok) out.add(v);
     }
-  }
-  createNode(key, value = []) {
-    return new AVLTreeMultiMapNode(key, this._isMapMode ? [] : value);
+    return out;
   }
   /**
-   * Checks if the given item is a `AVLTreeMultiMapNode` instance.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param keyNodeOrEntry - The item to check.
-   * @returns True if it's a AVLTreeMultiMapNode, false otherwise.
+   * Reduce values into a single accumulator.
+   * @remarks Time O(n), Space O(1)
    */
-  isNode(keyNodeOrEntry) {
-    return keyNodeOrEntry instanceof AVLTreeMultiMapNode;
+  reduce(callbackfn, initialValue) {
+    let acc = initialValue;
+    let index = 0;
+    for (const v of this) acc = callbackfn(acc, v, index++, this);
+    return acc;
   }
   /**
-   * Insert a value or a list of values into the multimap. If the key exists, values are appended.
-   * @remarks Time O(log N + M), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, values] entry.
-   * @param [value] - Single value to set when a bare key is provided.
-   * @returns True if inserted or appended; false if ignored.
+   * Test whether all values satisfy a predicate.
+   * @remarks Time O(n), Space O(1)
    */
-  set(keyNodeOrEntry, value) {
-    if (this.isRealNode(keyNodeOrEntry)) return super.set(keyNodeOrEntry);
-    const _commonAdd = /* @__PURE__ */ __name((key, values) => {
-      if (key === void 0 || key === null) return false;
-      const _setToValues = /* @__PURE__ */ __name(() => {
-        const existingValues = this.get(key);
-        if (existingValues !== void 0 && values !== void 0) {
-          for (const value2 of values) existingValues.push(value2);
-          return true;
-        }
-        return false;
-      }, "_setToValues");
-      const _setByNode = /* @__PURE__ */ __name(() => {
-        const existingNode = this.getNode(key);
-        if (this.isRealNode(existingNode)) {
-          const existingValues = this.get(existingNode);
-          if (existingValues === void 0) {
-            super.set(key, values);
-            return true;
-          }
-          if (values !== void 0) {
-            for (const value2 of values) existingValues.push(value2);
-            return true;
-          } else {
-            return false;
-          }
-        } else {
-          return super.set(key, values);
-        }
-      }, "_setByNode");
-      if (this._isMapMode) {
-        return _setByNode() || _setToValues();
-      }
-      return _setToValues() || _setByNode();
-    }, "_commonAdd");
-    if (this.isEntry(keyNodeOrEntry)) {
-      const [key, values] = keyNodeOrEntry;
-      return _commonAdd(key, value !== void 0 ? [value] : values);
+  every(callbackfn, thisArg) {
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, index++, this) : callbackfn.call(thisArg, v, index++, this);
+      if (!ok) return false;
     }
-    return _commonAdd(keyNodeOrEntry, value !== void 0 ? [value] : void 0);
+    return true;
   }
   /**
-   * Delete a single value from the bucket at a given key. Removes the key if the bucket becomes empty.
-   * @remarks Time O(log N), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, values] entry to locate the bucket.
-   * @param value - Value to remove from the bucket.
-   * @returns True if the value was removed; false if not found.
-   */
-  deleteValue(keyNodeOrEntry, value) {
-    const values = this.get(keyNodeOrEntry);
-    if (Array.isArray(values)) {
-      const index = values.indexOf(value);
-      if (index === -1) return false;
-      values.splice(index, 1);
-      if (values.length === 0) this.delete(keyNodeOrEntry);
-      return true;
+   * Test whether any value satisfies a predicate.
+   * @remarks Time O(n), Space O(1)
+   */
+  some(callbackfn, thisArg) {
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, index++, this) : callbackfn.call(thisArg, v, index++, this);
+      if (ok) return true;
     }
     return false;
   }
   /**
-   * Rebuild the tree into a perfectly balanced form using in-order nodes.
-   * @remarks Time O(N), Space O(N)
-   * @param [iterationType] - Traversal style to use when constructing the balanced tree.
-   * @returns True if rebalancing succeeded (tree not empty).
+   * Find the first value that satisfies a predicate.
+   * @remarks Time O(n), Space O(1)
    */
-  perfectlyBalance(iterationType = this.iterationType) {
-    const nodes = this.dfs((node) => node, "IN", false, this._root, iterationType);
-    const n = nodes.length;
-    if (n === 0) return false;
-    this._clearNodes();
-    const build = /* @__PURE__ */ __name((l, r, parent) => {
-      if (l > r) return void 0;
-      const m = l + (r - l >> 1);
-      const root = nodes[m];
-      root.left = build(l, m - 1, root);
-      root.right = build(m + 1, r, root);
-      root.parent = parent;
-      const lh = root.left ? root.left.height : -1;
-      const rh = root.right ? root.right.height : -1;
-      root.height = Math.max(lh, rh) + 1;
-      return root;
-    }, "build");
-    const newRoot = build(0, n - 1, void 0);
-    this._setRoot(newRoot);
-    this._size = n;
-    return true;
+  find(callbackfn, thisArg) {
+    let index = 0;
+    for (const v of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, index++, this) : callbackfn.call(thisArg, v, index++, this);
+      if (ok) return v;
+    }
+    return void 0;
   }
   /**
-   * Create a new tree by mapping each [key, values] bucket.
-   * @remarks Time O(N log N), Space O(N)
-   * @template MK
-   * @template MV
-   * @template MR
-   * @param callback - Function mapping (key, values, index, tree) → [newKey, newValue].
-   * @param [options] - Options for the output tree.
-   * @param [thisArg] - Value for `this` inside the callback.
-   * @returns The mapped AVLTree or AVLTreeMultiMap depending on MV; see overloads.
+   * Materialize the set into an array of keys.
+   * @remarks Time O(n), Space O(n)
    */
-  map(callback, options, thisArg) {
-    const out = this._createLike([], options);
-    let i = 0;
-    for (const [k, v] of this) out.set(callback.call(thisArg, v, k, i++, this));
-    return out;
+  toArray() {
+    return [...this];
   }
   /**
-   * (Protected) Create an empty instance of the same concrete class.
-   * @remarks Time O(1), Space O(1)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param [options] - Optional constructor options for the like-kind instance.
-   * @returns An empty like-kind instance.
+   * Print a human-friendly representation.
+   * @remarks Time O(n), Space O(n)
    */
-  _createInstance(options) {
-    const Ctor = this.constructor;
-    return new Ctor([], { ...this._snapshotOptions?.() ?? {}, ...options ?? {} });
+  print() {
+    this.#core.print();
   }
+  // Navigable operations
   /**
-   * (Protected) Create a like-kind instance and seed it from an iterable.
-   * @remarks Time O(N log N), Space O(N)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param iter - Iterable used to seed the new tree.
-   * @param [options] - Options merged with the current snapshot.
-   * @returns A like-kind AVLTree built from the iterable.
+   * Smallest key in the set.
    */
-  _createLike(iter = [], options) {
-    const Ctor = this.constructor;
-    return new Ctor(iter, { ...this._snapshotOptions?.() ?? {}, ...options ?? {} });
-  }
-};
-
-// src/data-structures/binary-tree/tree-multi-map.ts
-var TreeMultiMapNode = class {
-  static {
-    __name(this, "TreeMultiMapNode");
+  first() {
+    return this.#core.getLeftMost();
   }
-  key;
-  value;
-  parent = void 0;
   /**
-   * Create a TreeMultiMap node with an optional value bucket.
-   * @remarks Time O(1), Space O(1)
-   * @param key - Key of the node.
-   * @param [value] - Initial array of values.
-   * @returns New TreeMultiMapNode instance.
+   * Largest key in the set.
    */
-  constructor(key, value = [], color = "BLACK") {
-    this.key = key;
-    this.value = value;
-    this.color = color;
+  last() {
+    return this.#core.getRightMost();
   }
-  _left = void 0;
   /**
-   * Get the left child pointer.
-   * @remarks Time O(1), Space O(1)
-   * @returns Left child node, or null/undefined.
+   * Remove and return the smallest key.
    */
-  get left() {
-    return this._left;
+  pollFirst() {
+    const k = this.first();
+    if (k === void 0) return void 0;
+    this.delete(k);
+    return k;
   }
   /**
-   * Set the left child and update its parent pointer.
-   * @remarks Time O(1), Space O(1)
-   * @param v - New left child node, or null/undefined.
-   * @returns void
+   * Remove and return the largest key.
    */
-  set left(v) {
-    if (v) {
-      v.parent = this;
-    }
-    this._left = v;
+  pollLast() {
+    const k = this.last();
+    if (k === void 0) return void 0;
+    this.delete(k);
+    return k;
   }
-  _right = void 0;
   /**
-   * Get the right child pointer.
-   * @remarks Time O(1), Space O(1)
-   * @returns Right child node, or null/undefined.
+   * Smallest key that is >= the given key.
    */
-  get right() {
-    return this._right;
+  ceiling(key) {
+    this._validateKey(key);
+    return this.#core.ceiling(key);
   }
   /**
-   * Set the right child and update its parent pointer.
-   * @remarks Time O(1), Space O(1)
-   * @param v - New right child node, or null/undefined.
-   * @returns void
+   * Largest key that is <= the given key.
    */
-  set right(v) {
-    if (v) {
-      v.parent = this;
-    }
-    this._right = v;
+  floor(key) {
+    this._validateKey(key);
+    return this.#core.floor(key);
   }
-  _height = 0;
   /**
-   * Gets the height of the node (used in self-balancing trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The height.
+   * Smallest key that is > the given key.
    */
-  get height() {
-    return this._height;
+  higher(key) {
+    this._validateKey(key);
+    return this.#core.higher(key);
   }
   /**
-   * Sets the height of the node.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new height.
+   * Largest key that is < the given key.
    */
-  set height(value) {
-    this._height = value;
+  lower(key) {
+    this._validateKey(key);
+    return this.#core.lower(key);
   }
-  _color = "BLACK";
   /**
-   * Gets the color of the node (used in Red-Black trees).
-   * @remarks Time O(1), Space O(1)
+   * Return all keys in a given range.
    *
-   * @returns The node's color.
+   * @param range `[low, high]`
+   * @param options Inclusive/exclusive bounds (defaults to inclusive).
    */
-  get color() {
-    return this._color;
+  rangeSearch(range, options = {}) {
+    const { lowInclusive = true, highInclusive = true } = options;
+    const [low, high] = range;
+    this._validateKey(low);
+    this._validateKey(high);
+    const keys = this.#core.rangeSearch([low, high]);
+    const out = [];
+    const cmp = this.#core.comparator;
+    for (const k of keys) {
+      if (k === void 0) continue;
+      if (!lowInclusive && cmp(k, low) === 0) continue;
+      if (!highInclusive && cmp(k, high) === 0) continue;
+      out.push(k);
+    }
+    return out;
+  }
+};
+
+// src/data-structures/binary-tree/tree-multi-map.ts
+var TreeMultiMapNode = class extends RedBlackTreeNode {
+  static {
+    __name(this, "TreeMultiMapNode");
+  }
+  constructor(key, value = []) {
+    super(key, value);
+  }
+};
+var TreeMultiMap = class _TreeMultiMap {
+  static {
+    __name(this, "TreeMultiMap");
+  }
+  #core;
+  #isDefaultComparator;
+  /**
+   * Creates a new TreeMultiMap.
+   * @param keysNodesEntriesOrRaws - Initial entries
+   * @param options - Configuration options
+   * @remarks Time O(m log m), Space O(m) where m is the number of initial entries
+   */
+  constructor(keysNodesEntriesOrRaws = [], options = {}) {
+    const comparator = options.comparator ?? TreeSet.createDefaultComparator();
+    this.#isDefaultComparator = options.comparator === void 0;
+    this.#core = new RedBlackTree([], { ...options, comparator, isMapMode: options.isMapMode });
+    for (const x of keysNodesEntriesOrRaws) {
+      if (x === null || x === void 0) continue;
+      if (Array.isArray(x)) {
+        const [k, bucket] = x;
+        if (k === null || k === void 0) continue;
+        if (bucket !== void 0) {
+          this.#core.set(k, [...bucket]);
+        } else {
+          this.#core.set(k, []);
+        }
+        continue;
+      }
+      this.#core.set(x, []);
+    }
   }
   /**
-   * Sets the color of the node.
+   * Validates the key against the default comparator rules.
    * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new color.
    */
-  set color(value) {
-    this._color = value;
+  _validateKey(key) {
+    if (!this.#isDefaultComparator) return;
+    if (typeof key === "number") {
+      if (Number.isNaN(key)) throw new TypeError("TreeMultiMap: NaN is not a valid key");
+      return;
+    }
+    if (typeof key === "string") return;
+    if (key instanceof Date) {
+      if (Number.isNaN(key.getTime())) throw new TypeError("TreeMultiMap: invalid Date key");
+      return;
+    }
+    throw new TypeError("TreeMultiMap: comparator is required for non-number/non-string/non-Date keys");
   }
-  _count = 1;
   /**
-   * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
+   * Number of distinct keys.
    * @remarks Time O(1), Space O(1)
-   *
-   * @returns The subtree node count.
    */
-  get count() {
-    return this._count;
+  get size() {
+    return this.#core.size;
   }
   /**
-   * Sets the count of nodes in the subtree.
+   * Whether the map is empty.
    * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new count.
    */
-  set count(value) {
-    this._count = value;
+  isEmpty() {
+    return this.size === 0;
   }
   /**
-   * Gets the position of the node relative to its parent.
+   * Removes all entries from the map.
    * @remarks Time O(1), Space O(1)
-   *
-   * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
    */
-  get familyPosition() {
-    if (!this.parent) {
-      return this.left || this.right ? "ROOT" : "ISOLATED";
-    }
-    if (this.parent.left === this) {
-      return this.left || this.right ? "ROOT_LEFT" : "LEFT";
-    } else if (this.parent.right === this) {
-      return this.left || this.right ? "ROOT_RIGHT" : "RIGHT";
-    }
-    return "MAL_NODE";
+  clear() {
+    this.#core.clear();
   }
-};
-var TreeMultiMap = class extends RedBlackTree {
-  static {
-    __name(this, "TreeMultiMap");
+  /**
+   * Bucket length for a key (missing => 0).
+   * @remarks Time O(log n), Space O(1)
+   */
+  count(key) {
+    const b = this.get(key);
+    return Array.isArray(b) ? b.length : 0;
   }
   /**
-   * Create a TreeMultiMap and optionally bulk-insert items.
-   * @remarks Time O(N log N), Space O(N)
-   * @param [keysNodesEntriesOrRaws] - Iterable of keys/nodes/entries/raw items to insert.
-   * @param [options] - Options for TreeMultiMap (comparator, reverse, map mode).
-   * @returns New TreeMultiMap instance.
+   * Total number of values across all buckets (Σ bucket.length).
+   * @remarks Time O(n), Space O(1)
    */
-  constructor(keysNodesEntriesOrRaws = [], options) {
-    super([], { ...options });
-    if (keysNodesEntriesOrRaws) {
-      this.setMany(keysNodesEntriesOrRaws);
-    }
+  get totalSize() {
+    let sum = 0;
+    for (const [, bucket] of this) sum += bucket.length;
+    return sum;
   }
-  createNode(key, value = []) {
-    return new TreeMultiMapNode(key, this._isMapMode ? [] : value);
+  /**
+   * Whether the map contains the given key.
+   * @remarks Time O(log n), Space O(1)
+   */
+  has(key) {
+    this._validateKey(key);
+    return this.#core.has(key);
   }
   /**
-   * Checks if the given item is a `TreeMultiMapNode` instance.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param keyNodeOrEntry - The item to check.
-   * @returns True if it's a TreeMultiMapNode, false otherwise.
+   * Live bucket reference (do not auto-delete key if bucket becomes empty via mutation).
+   * @remarks Time O(log n), Space O(1)
    */
-  isNode(keyNodeOrEntry) {
-    return keyNodeOrEntry instanceof TreeMultiMapNode;
+  get(key) {
+    this._validateKey(key);
+    return this.#core.get(key);
   }
   /**
-   * Insert a value or a list of values into the multimap. If the key exists, values are appended.
-   * @remarks Time O(log N + M), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, values] entry.
-   * @param [value] - Single value to set when a bare key is provided.
-   * @returns True if inserted or appended; false if ignored.
+   * Append a single value.
+   * @remarks Time O(log n), Space O(1)
    */
-  set(keyNodeOrEntry, value) {
-    if (this.isRealNode(keyNodeOrEntry)) return super.set(keyNodeOrEntry);
-    const _commonAdd = /* @__PURE__ */ __name((key, values) => {
-      if (key === void 0 || key === null) return false;
-      const _setToValues = /* @__PURE__ */ __name(() => {
-        const existingValues = this.get(key);
-        if (existingValues !== void 0 && values !== void 0) {
-          for (const value2 of values) existingValues.push(value2);
-          return true;
-        }
-        return false;
-      }, "_setToValues");
-      const _setByNode = /* @__PURE__ */ __name(() => {
-        const existingNode = this.getNode(key);
-        if (this.isRealNode(existingNode)) {
-          const existingValues = this.get(existingNode);
-          if (existingValues === void 0) {
-            super.set(key, values);
-            return true;
-          }
-          if (values !== void 0) {
-            for (const value2 of values) existingValues.push(value2);
-            return true;
-          } else {
-            return false;
-          }
-        } else {
-          return super.set(key, values);
-        }
-      }, "_setByNode");
-      if (this._isMapMode) {
-        return _setByNode() || _setToValues();
+  add(key, value) {
+    this._validateKey(key);
+    const bucket = this.#core.get(key);
+    if (bucket) {
+      bucket.push(value);
+      return true;
+    }
+    return this.#core.set(key, [value]);
+  }
+  set(entry, value) {
+    if (entry === null || entry === void 0) return false;
+    if (Array.isArray(entry)) {
+      const [k, bucket] = entry;
+      if (k === null || k === void 0) return false;
+      if (value !== void 0) return this.add(k, value);
+      if (bucket === void 0) {
+        return this.#core.set(k, []);
       }
-      return _setToValues() || _setByNode();
-    }, "_commonAdd");
-    if (this.isEntry(keyNodeOrEntry)) {
-      const [key, values] = keyNodeOrEntry;
-      return _commonAdd(key, value !== void 0 ? [value] : values);
+      const existing = this.#core.get(k);
+      if (existing) {
+        existing.push(...bucket);
+        return true;
+      }
+      return this.#core.set(k, [...bucket]);
     }
-    return _commonAdd(keyNodeOrEntry, value !== void 0 ? [value] : void 0);
+    if (value !== void 0) return this.add(entry, value);
+    return this.#core.set(entry, []);
   }
   /**
-   * Delete a single value from the bucket at a given key. Removes the key if the bucket becomes empty.
-   * @remarks Time O(log N), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, values] entry to locate the bucket.
-   * @param value - Value to remove from the bucket.
-   * @returns True if the value was removed; false if not found.
-   */
-  deleteValue(keyNodeOrEntry, value) {
-    const values = this.get(keyNodeOrEntry);
-    if (Array.isArray(values)) {
-      const index = values.indexOf(value);
-      if (index === -1) return false;
-      values.splice(index, 1);
-      if (values.length === 0) this.delete(keyNodeOrEntry);
-      return true;
-    }
-    return false;
+   * Deletes a key and its entire bucket.
+   * @remarks Time O(log n), Space O(1)
+   */
+  delete(key) {
+    this._validateKey(key);
+    return this.#core.delete(key).length > 0;
   }
   /**
-   * Create a new tree by mapping each [key, values] bucket.
-   * @remarks Time O(N log N), Space O(N)
-   * @template MK
-   * @template MV
-   * @template MR
-   * @param callback - Function mapping (key, values, index, tree) → [newKey, newValue].
-   * @param [options] - Options for the output tree.
-   * @param [thisArg] - Value for `this` inside the callback.
-   * @returns A new RedBlackTree (or TreeMultiMap when mapping to array values; see overloads).
+   * 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
    */
-  map(callback, options, thisArg) {
-    const out = this._createLike([], options);
-    let i = 0;
-    for (const [k, v] of this) out.set(callback.call(thisArg, v, k, i++, this));
-    return out;
+  hasEntry(key, value, eq = Object.is) {
+    const bucket = this.get(key);
+    if (!Array.isArray(bucket)) return false;
+    return bucket.some((v) => eq(v, value));
   }
   /**
-   * (Protected) Create an empty instance of the same concrete class.
-   * @remarks Time O(1), Space O(1)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param [options] - Optional constructor options for the like-kind instance.
-   * @returns An empty like-kind instance.
+   * 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
    */
-  _createInstance(options) {
-    const Ctor = this.constructor;
-    return new Ctor([], { ...this._snapshotOptions?.() ?? {}, ...options ?? {} });
+  deleteValue(key, value, eq = Object.is) {
+    const bucket = this.get(key);
+    if (!Array.isArray(bucket)) return false;
+    const idx = bucket.findIndex((v) => eq(v, value));
+    if (idx === -1) return false;
+    bucket.splice(idx, 1);
+    if (bucket.length === 0) this.delete(key);
+    return true;
   }
   /**
-   * (Protected) Create a like-kind instance and seed it from an iterable.
-   * @remarks Time O(N log N), Space O(N)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param iter - Iterable used to seed the new tree.
-   * @param [options] - Options merged with the current snapshot.
-   * @returns A like-kind RedBlackTree built from the iterable.
+   * 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
    */
-  _createLike(iter = [], options) {
-    const Ctor = this.constructor;
-    return new Ctor(iter, { ...this._snapshotOptions?.() ?? {}, ...options ?? {} });
+  deleteValues(key, value, eq = Object.is) {
+    const bucket = this.get(key);
+    if (!Array.isArray(bucket) || bucket.length === 0) return 0;
+    let removed = 0;
+    for (let i = bucket.length - 1; i >= 0; i--) {
+      if (eq(bucket[i], value)) {
+        bucket.splice(i, 1);
+        removed++;
+      }
+    }
+    if (bucket.length === 0 && removed > 0) this.delete(key);
+    return removed;
   }
-};
-
-// src/data-structures/binary-tree/tree-counter.ts
-var TreeCounterNode = class {
-  static {
-    __name(this, "TreeCounterNode");
+  // ---- iteration (bucket view) ----
+  /**
+   * Iterates over all entries as [key, bucket] pairs.
+   * @remarks Time O(n), Space O(1)
+   */
+  *[Symbol.iterator]() {
+    for (const [k, v] of this.#core) {
+      yield [k, v ?? []];
+    }
   }
-  key;
-  value;
-  parent = void 0;
   /**
-   * Create a tree counter node.
-   * @remarks Time O(1), Space O(1)
-   * @param key - Key of the node.
-   * @param [value] - Value associated with the key (ignored in map mode).
-   * @param [count] - Initial count for this node (default 1).
-   * @param color - Initial color ('RED' or 'BLACK').
-   * @returns New TreeCounterNode instance.
+   * Iterates over all keys.
+   * @remarks Time O(n), Space O(1)
    */
-  constructor(key, value, count = 1, color = "BLACK") {
-    this.key = key;
-    this.value = value;
-    this.color = color;
-    this.count = count;
+  *keys() {
+    yield* this.#core.keys();
   }
-  _left = void 0;
   /**
-   * Get the left child pointer.
-   * @remarks Time O(1), Space O(1)
-   * @returns Left child node, or null/undefined.
+   * Iterates over all buckets.
+   * @remarks Time O(n), Space O(1)
    */
-  get left() {
-    return this._left;
+  *values() {
+    for (const [, bucket] of this) yield bucket;
   }
+  // ---- entry-flat views ----
   /**
-   * Set the left child and update its parent pointer.
-   * @remarks Time O(1), Space O(1)
-   * @param v - New left child node, or null/undefined.
-   * @returns void
+   * Iterates over all entries for a specific key.
+   * @remarks Time O(log n + m), Space O(1) where m is bucket size
    */
-  set left(v) {
-    if (v) {
-      v.parent = this;
-    }
-    this._left = v;
+  *entriesOf(key) {
+    const bucket = this.get(key);
+    if (!Array.isArray(bucket)) return;
+    for (const v of bucket) yield [key, v];
   }
-  _right = void 0;
   /**
-   * Get the right child pointer.
-   * @remarks Time O(1), Space O(1)
-   * @returns Right child node, or null/undefined.
+   * Iterates over all values for a specific key.
+   * @remarks Time O(log n + m), Space O(1) where m is bucket size
    */
-  get right() {
-    return this._right;
+  *valuesOf(key) {
+    const bucket = this.get(key);
+    if (!Array.isArray(bucket)) return;
+    yield* bucket;
   }
   /**
-   * Set the right child and update its parent pointer.
-   * @remarks Time O(1), Space O(1)
-   * @param v - New right child node, or null/undefined.
-   * @returns void
+   * Iterates over all [key, value] pairs (flattened from buckets).
+   * @remarks Time O(T), Space O(1) where T is totalSize
    */
-  set right(v) {
-    if (v) {
-      v.parent = this;
+  *flatEntries() {
+    for (const [k, bucket] of this) {
+      for (const v of bucket) yield [k, v];
     }
-    this._right = v;
   }
-  _height = 0;
+  // ━━━ Navigable methods (return [K, V[]] | undefined) ━━━
   /**
-   * Gets the height of the node (used in self-balancing trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The height.
+   * 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']]
    */
-  get height() {
-    return this._height;
+  first() {
+    const k = this.#core.getLeftMost();
+    if (k === void 0) return void 0;
+    const b = this.get(k);
+    return b === void 0 ? void 0 : [k, b];
   }
   /**
-   * Sets the height of the node.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new height.
+   * 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']]
    */
-  set height(value) {
-    this._height = value;
+  last() {
+    const k = this.#core.getRightMost();
+    if (k === void 0) return void 0;
+    const b = this.get(k);
+    return b === void 0 ? void 0 : [k, b];
   }
-  _color = "BLACK";
   /**
-   * Gets the color of the node (used in Red-Black trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The node's color.
+   * 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
    */
-  get color() {
-    return this._color;
+  pollFirst() {
+    const e = this.first();
+    if (!e) return void 0;
+    this.delete(e[0]);
+    return e;
   }
   /**
-   * Sets the color of the node.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new color.
+   * 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
    */
-  set color(value) {
-    this._color = value;
+  pollLast() {
+    const e = this.last();
+    if (!e) return void 0;
+    this.delete(e[0]);
+    return e;
   }
-  _count = 1;
   /**
-   * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The subtree node count.
+   * 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']]
    */
-  get count() {
-    return this._count;
+  ceiling(key) {
+    this._validateKey(key);
+    const k = this.#core.ceiling(key);
+    if (k === void 0) return void 0;
+    const b = this.get(k);
+    return b === void 0 ? void 0 : [k, b];
   }
   /**
-   * Sets the count of nodes in the subtree.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new count.
+   * Returns the entry with the largest key <= given key.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const map = new TreeMultiMap([[10, ['a']], [20, ['b']], [30, ['c']]]);
+   * map.floor(25);  // [20, ['b']]
+   * map.floor(20);  // [20, ['b']]
+   */
+  floor(key) {
+    this._validateKey(key);
+    const k = this.#core.floor(key);
+    if (k === void 0) return void 0;
+    const b = this.get(k);
+    return b === void 0 ? void 0 : [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']]
    */
-  set count(value) {
-    this._count = value;
+  higher(key) {
+    this._validateKey(key);
+    const k = this.#core.higher(key);
+    if (k === void 0) return void 0;
+    const b = this.get(k);
+    return b === void 0 ? void 0 : [k, b];
   }
   /**
-   * Gets the position of the node relative to its parent.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
+   * 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']]
    */
-  get familyPosition() {
-    if (!this.parent) {
-      return this.left || this.right ? "ROOT" : "ISOLATED";
+  lower(key) {
+    this._validateKey(key);
+    const k = this.#core.lower(key);
+    if (k === void 0) return void 0;
+    const b = this.get(k);
+    return b === void 0 ? void 0 : [k, b];
+  }
+  // ━━━ Tree utilities ━━━
+  /**
+   * Prints the internal tree structure (for debugging).
+   * @remarks Time O(n), Space O(n)
+   */
+  print(...args) {
+    return this.#core.print(...args);
+  }
+  /**
+   * Executes a callback for each entry.
+   * @remarks Time O(n), Space O(1)
+   */
+  forEach(callback) {
+    for (const [k, v] of this) {
+      callback(v, k, this);
     }
-    if (this.parent.left === this) {
-      return this.left || this.right ? "ROOT_LEFT" : "LEFT";
-    } else if (this.parent.right === this) {
-      return this.left || this.right ? "ROOT_RIGHT" : "RIGHT";
+  }
+  /**
+   * Creates a new map with entries that pass the predicate.
+   * @remarks Time O(n), Space O(n)
+   */
+  filter(predicate) {
+    const filtered = [];
+    for (const [k, v] of this) {
+      if (predicate(v, k, this)) filtered.push([k, v]);
     }
-    return "MAL_NODE";
+    return new _TreeMultiMap(filtered, { comparator: this.comparator });
   }
-};
-var TreeCounter = class extends RedBlackTree {
-  static {
-    __name(this, "TreeCounter");
+  /**
+   * Creates a new map by transforming each entry.
+   * @remarks Time O(n log n), Space O(n)
+   */
+  map(mapper) {
+    const mapped = [];
+    for (const [k, v] of this) {
+      mapped.push(mapper(v, k, this));
+    }
+    return new _TreeMultiMap(mapped, { comparator: this.comparator });
   }
   /**
-   * Create a TreeCounter and optionally bulk-insert items.
-   * @remarks Time O(N log N), Space O(N)
-   * @param [keysNodesEntriesOrRaws] - Iterable of keys/nodes/entries/raw items to insert.
-   * @param [options] - Options for TreeCounter (comparator, reverse, map mode).
-   * @returns New TreeCounter instance.
+   * Reduces all entries to a single value.
+   * @remarks Time O(n), Space O(1)
    */
-  constructor(keysNodesEntriesOrRaws = [], options) {
-    super([], options);
-    if (keysNodesEntriesOrRaws) this.setMany(keysNodesEntriesOrRaws);
+  reduce(callback, initialValue) {
+    let acc = initialValue;
+    for (const [k, v] of this) {
+      acc = callback(acc, v, k, this);
+    }
+    return acc;
   }
-  _count = 0;
   /**
-   * Get the total aggregate count across all nodes.
-   * @remarks Time O(1), Space O(1)
-   * @returns Total count.
+   * Sets multiple entries at once.
+   * @remarks Time O(m log n), Space O(m) where m is input size
    */
-  get count() {
-    return this._count;
+  setMany(keysNodesEntriesOrRaws) {
+    const results = [];
+    for (const x of keysNodesEntriesOrRaws) {
+      results.push(this.set(x, void 0));
+    }
+    return results;
   }
   /**
-   * Compute the total count by traversing the tree (sums node.count).
-   * @remarks Time O(N), Space O(H)
-   * @returns Total count recomputed from nodes.
+   * Searches for entries within a key range.
+   * @remarks Time O(log n + k), Space O(k) where k is result size
    */
-  getComputedCount() {
-    let sum = 0;
-    this.dfs((node) => sum += node ? node.count : 0);
-    return sum;
+  rangeSearch(range, callback, isBalanced) {
+    return this.#core.rangeSearch(range, callback, isBalanced);
   }
-  createNode(key, value, color = "BLACK", count) {
-    return new TreeCounterNode(key, this._isMapMode ? void 0 : value, count, color);
+  /**
+   * Creates a shallow clone of this map.
+   * @remarks Time O(n log n), Space O(n)
+   */
+  clone() {
+    return new _TreeMultiMap(this, { comparator: this.comparator, isMapMode: this.#core._isMapMode });
   }
   /**
-   * Type guard: check whether the input is a TreeCounterNode.
+   * Expose comparator for advanced usage/testing (read-only).
    * @remarks Time O(1), Space O(1)
-   * @returns True if the value is a TreeCounterNode.
    */
-  isNode(keyNodeOrEntry) {
-    return keyNodeOrEntry instanceof TreeCounterNode;
+  get comparator() {
+    return this.#core._comparator;
+  }
+};
+
+// src/data-structures/binary-tree/tree-map.ts
+var TreeMap = class _TreeMap {
+  static {
+    __name(this, "TreeMap");
   }
+  #core;
+  #isDefaultComparator;
+  #userComparator;
   /**
-   * Insert or increment a node and update aggregate count.
-   * @remarks Time O(log N), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, value] entry to insert.
-   * @param [value] - Value when a bare key is provided (ignored in map mode).
-   * @param [count] - How much to increase the node's count (default 1).
-   * @returns True if inserted/updated; false if ignored.
-   */
-  set(keyNodeOrEntry, value, count = 1) {
-    const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value, count);
-    const orgCount = newNode?.count || 0;
-    const isSuccessAdded = super.set(newNode, newValue);
-    if (isSuccessAdded) {
-      this._count += orgCount;
-      return true;
-    } else {
-      return false;
+   * Create a TreeMap from an iterable of `[key, value]` entries.
+   *
+   * @throws {TypeError} If any entry is not a 2-tuple-like value, or when using the default comparator
+   * and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
+   */
+  constructor(entries = [], options = {}) {
+    this.#userComparator = options.comparator;
+    const comparator = options.comparator ?? _TreeMap.createDefaultComparator();
+    this.#isDefaultComparator = options.comparator === void 0;
+    this.#core = new RedBlackTree([], { comparator, isMapMode: options.isMapMode });
+    for (const item of entries) {
+      if (!Array.isArray(item) || item.length < 2) {
+        throw new TypeError("TreeMap: each entry must be a [key, value] tuple");
+      }
+      const k = item[0];
+      const v = item[1];
+      this.set(k, v);
     }
   }
   /**
-   * Delete a node (or decrement its count) and rebalance if needed.
-   * @remarks Time O(log N), Space O(1)
-   * @param keyNodeEntryRawOrPredicate - Key, node, or [key, value] entry identifying the node.
-   * @param [ignoreCount] - If true, remove the node regardless of its count.
-   * @returns Array of deletion results including deleted node and a rebalance hint when present.
+   * Create the strict default comparator.
+   *
+   * Supports:
+   * - `number` (rejects `NaN`; treats `-0` and `0` as equal)
+   * - `string`
+   * - `Date` (orders by `getTime()`, rejects invalid dates)
+   *
+   * For other key types, a custom comparator must be provided.
    */
-  delete(keyNodeEntryRawOrPredicate, ignoreCount = false) {
-    if (keyNodeEntryRawOrPredicate === null) return [];
-    const results = [];
-    let nodeToDelete;
-    if (this._isPredicate(keyNodeEntryRawOrPredicate)) nodeToDelete = this.getNode(keyNodeEntryRawOrPredicate);
-    else nodeToDelete = this.isRealNode(keyNodeEntryRawOrPredicate) ? keyNodeEntryRawOrPredicate : this.getNode(keyNodeEntryRawOrPredicate);
-    if (!nodeToDelete) {
-      return results;
-    }
-    let originalColor = nodeToDelete.color;
-    let replacementNode;
-    if (!this.isRealNode(nodeToDelete.left)) {
-      if (nodeToDelete.right !== null) replacementNode = nodeToDelete.right;
-      if (ignoreCount || nodeToDelete.count <= 1) {
-        if (nodeToDelete.right !== null) {
-          this._transplant(nodeToDelete, nodeToDelete.right);
-          this._count -= nodeToDelete.count;
-        }
-      } else {
-        nodeToDelete.count--;
-        this._count--;
-        results.push({ deleted: nodeToDelete, needBalanced: void 0 });
-        return results;
-      }
-    } else if (!this.isRealNode(nodeToDelete.right)) {
-      replacementNode = nodeToDelete.left;
-      if (ignoreCount || nodeToDelete.count <= 1) {
-        this._transplant(nodeToDelete, nodeToDelete.left);
-        this._count -= nodeToDelete.count;
-      } else {
-        nodeToDelete.count--;
-        this._count--;
-        results.push({ deleted: nodeToDelete, needBalanced: void 0 });
-        return results;
-      }
-    } else {
-      const successor = this.getLeftMost((node) => node, nodeToDelete.right);
-      if (successor) {
-        originalColor = successor.color;
-        if (successor.right !== null) replacementNode = successor.right;
-        if (successor.parent === nodeToDelete) {
-          if (this.isRealNode(replacementNode)) {
-            replacementNode.parent = successor;
-          }
-        } else {
-          if (ignoreCount || nodeToDelete.count <= 1) {
-            if (successor.right !== null) {
-              this._transplant(successor, successor.right);
-            }
-          } else {
-            nodeToDelete.count--;
-            this._count--;
-            results.push({ deleted: nodeToDelete, needBalanced: void 0 });
-            return results;
-          }
-          successor.right = nodeToDelete.right;
-          if (this.isRealNode(successor.right)) {
-            successor.right.parent = successor;
-          }
-        }
-        if (ignoreCount || nodeToDelete.count <= 1) {
-          this._transplant(nodeToDelete, successor);
-          this._count -= nodeToDelete.count;
-        } else {
-          nodeToDelete.count--;
-          this._count--;
-          results.push({ deleted: nodeToDelete, needBalanced: void 0 });
-          return results;
-        }
-        successor.left = nodeToDelete.left;
-        if (this.isRealNode(successor.left)) {
-          successor.left.parent = successor;
-        }
-        successor.color = nodeToDelete.color;
-      }
+  static createDefaultComparator() {
+    return (a, b) => {
+      if (typeof a === "number" && typeof b === "number") {
+        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError("TreeMap: NaN is not a valid key");
+        const aa = Object.is(a, -0) ? 0 : a;
+        const bb = Object.is(b, -0) ? 0 : b;
+        return aa > bb ? 1 : aa < bb ? -1 : 0;
+      }
+      if (typeof a === "string" && typeof b === "string") {
+        return a > b ? 1 : a < b ? -1 : 0;
+      }
+      if (a instanceof Date && b instanceof Date) {
+        const ta = a.getTime();
+        const tb = b.getTime();
+        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError("TreeMap: invalid Date key");
+        return ta > tb ? 1 : ta < tb ? -1 : 0;
+      }
+      throw new TypeError("TreeMap: comparator is required for non-number/non-string/non-Date keys");
+    };
+  }
+  _validateKey(key) {
+    if (!this.#isDefaultComparator) return;
+    if (typeof key === "number") {
+      if (Number.isNaN(key)) throw new TypeError("TreeMap: NaN is not a valid key");
+      return;
     }
-    this._size--;
-    if (originalColor === "BLACK") {
-      this._deleteFixup(replacementNode);
+    if (typeof key === "string") return;
+    if (key instanceof Date) {
+      if (Number.isNaN(key.getTime())) throw new TypeError("TreeMap: invalid Date key");
+      return;
     }
-    results.push({ deleted: nodeToDelete, needBalanced: void 0 });
-    return results;
+    throw new TypeError("TreeMap: comparator is required for non-number/non-string/non-Date keys");
   }
   /**
-   * Remove all nodes and reset aggregate counters.
-   * @remarks Time O(N), Space O(1)
-   * @returns void
+   * Number of entries in the map.
+   */
+  get size() {
+    return this.#core.size;
+  }
+  /**
+   * Whether the map is empty.
+   */
+  isEmpty() {
+    return this.size === 0;
+  }
+  /**
+   * Set or overwrite a value for a key.
+   * @remarks Expected time O(log n)
+   */
+  set(key, value) {
+    this._validateKey(key);
+    this.#core.set(key, value);
+    return this;
+  }
+  /**
+   * Get the value under a key.
+   * @remarks Expected time O(log n)
+   */
+  get(key) {
+    this._validateKey(key);
+    return this.#core.get(key);
+  }
+  /**
+   * Test whether a key exists.
+   * @remarks Expected time O(log n)
+   */
+  has(key) {
+    this._validateKey(key);
+    return this.#core.has(key);
+  }
+  /**
+   * Delete a key.
+   * @returns `true` if the key existed; otherwise `false`.
+   * @remarks Expected time O(log n)
+   */
+  delete(key) {
+    this._validateKey(key);
+    const res = this.#core.delete(key);
+    return Array.isArray(res) && res.length > 0 && !!res[0]?.deleted;
+  }
+  /**
+   * Remove all entries.
    */
   clear() {
-    super.clear();
-    this._count = 0;
+    this.#core.clear();
   }
   /**
-   * Rebuild the tree into a perfectly balanced form using in-order nodes.
-   * @remarks Time O(N), Space O(N)
-   * @param [iterationType] - Traversal style to use when constructing the balanced tree.
-   * @returns True if rebalancing succeeded (tree not empty).
+   * Iterate over keys in ascending order.
    */
-  perfectlyBalance(iterationType = this.iterationType) {
-    const nodes = this.dfs((node) => node, "IN", false, this._root, iterationType);
-    const n = nodes.length;
-    if (n < 1) return false;
-    let total = 0;
-    for (const nd of nodes) total += nd ? nd.count : 0;
-    this._clearNodes();
-    const build = /* @__PURE__ */ __name((l, r, parent) => {
-      if (l > r) return void 0;
-      const m = l + (r - l >> 1);
-      const root = nodes[m];
-      const leftChild = build(l, m - 1, root);
-      const rightChild = build(m + 1, r, root);
-      root.left = leftChild;
-      root.right = rightChild;
-      root.parent = parent;
-      return root;
-    }, "build");
-    const newRoot = build(0, n - 1, void 0);
-    this._setRoot(newRoot);
-    this._size = n;
-    this._count = total;
-    return true;
+  keys() {
+    return this.#core.keys();
+  }
+  _entryFromKey(k) {
+    return [k, this.#core.get(k)];
   }
   /**
-   * Create a new TreeCounter by mapping each [key, value] entry.
-   * @remarks Time O(N log N), Space O(N)
-   * @template MK
-   * @template MV
-   * @template MR
-   * @param callback - Function mapping (key, value, index, tree) → [newKey, newValue].
-   * @param [options] - Options for the output tree.
-   * @param [thisArg] - Value for `this` inside the callback.
-   * @returns A new TreeCounter with mapped entries.
+   * Iterate over values in ascending key order.
+   *
+   * Note: values may be `undefined` (TreeMap allows storing `undefined`, like native `Map`).
    */
-  map(callback, options, thisArg) {
-    const out = this._createLike([], options);
+  *values() {
+    for (const k of this.keys()) yield this._entryFromKey(k)[1];
+  }
+  /**
+   * Iterate over `[key, value]` entries in ascending key order.
+   *
+   * Note: values may be `undefined`.
+   */
+  *entries() {
+    for (const k of this.keys()) yield this._entryFromKey(k);
+  }
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+  /**
+   * Visit each entry in ascending key order.
+   *
+   * Note: callback value may be `undefined`.
+   */
+  forEach(cb, thisArg) {
+    for (const [k, v] of this) cb.call(thisArg, v, k, this);
+  }
+  /**
+   * Create a new TreeMap by mapping each entry to a new `[key, value]` entry.
+   *
+   * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
+   * @remarks Time O(n log n) expected, Space O(n)
+   */
+  map(callbackfn, options = {}, thisArg) {
+    const out = new _TreeMap([], options);
     let index = 0;
-    for (const [key, value] of this) {
-      out.set(callback.call(thisArg, value, key, index++, this));
+    for (const [k, v] of this) {
+      const [mk, mv] = thisArg === void 0 ? callbackfn(v, k, index++, this) : callbackfn.call(thisArg, v, k, index++, this);
+      out.set(mk, mv);
     }
     return out;
   }
   /**
-   * Deep copy this tree, preserving map mode and aggregate counts.
-   * @remarks Time O(N), Space O(N)
-   * @returns A deep copy of this tree.
+   * Create a new TreeMap containing only entries that satisfy the predicate.
+   * @remarks Time O(n log n) expected, Space O(n)
    */
-  clone() {
-    const out = this._createInstance();
-    this._clone(out);
-    out._count = this._count;
-    for (const node of this.dfs((n) => n, "IN")) {
-      if (!node) continue;
-      const outNode = out.getNode(node.key);
-      if (outNode) outNode.count = node.count;
+  filter(callbackfn, thisArg) {
+    const out = new _TreeMap([], { comparator: this.#userComparator });
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, k, index++, this) : callbackfn.call(thisArg, v, k, index++, this);
+      if (ok) out.set(k, v);
     }
     return out;
   }
   /**
-   * (Protected) Create an empty instance of the same concrete class.
-   * @remarks Time O(1), Space O(1)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param [options] - Optional constructor options for the like-kind instance.
-   * @returns An empty like-kind instance.
+   * Reduce entries into a single accumulator.
+   * @remarks Time O(n), Space O(1)
    */
-  _createInstance(options) {
-    const Ctor = this.constructor;
-    return new Ctor([], { ...this._snapshotOptions(), ...options ?? {} });
+  reduce(callbackfn, initialValue) {
+    let acc = initialValue;
+    let index = 0;
+    for (const [k, v] of this) acc = callbackfn(acc, v, k, index++, this);
+    return acc;
   }
   /**
-   * (Protected) Create a like-kind instance and seed it from an iterable.
-   * @remarks Time O(N log N), Space O(N)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param iter - Iterable used to seed the new tree.
-   * @param [options] - Options merged with the current snapshot.
-   * @returns A like-kind TreeCounter built from the iterable.
+   * Test whether all entries satisfy a predicate.
+   * @remarks Time O(n), Space O(1)
    */
-  _createLike(iter = [], options) {
-    const Ctor = this.constructor;
-    return new Ctor(iter, {
-      ...this._snapshotOptions(),
-      ...options ?? {}
-    });
+  every(callbackfn, thisArg) {
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, k, index++, this) : callbackfn.call(thisArg, v, k, index++, this);
+      if (!ok) return false;
+    }
+    return true;
   }
   /**
-   * (Protected) Normalize input into a node plus its effective value and count.
-   * @remarks Time O(1), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, value] entry.
-   * @param [value] - Value used when a bare key is provided.
-   * @param [count] - Count increment to apply (default 1).
-   * @returns Tuple [node, value] where node may be undefined.
+   * Test whether any entry satisfies a predicate.
+   * @remarks Time O(n), Space O(1)
    */
-  _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value, count = 1) {
-    if (keyNodeOrEntry === void 0 || keyNodeOrEntry === null) return [void 0, void 0];
-    if (this.isNode(keyNodeOrEntry)) return [keyNodeOrEntry, value];
-    if (this.isEntry(keyNodeOrEntry)) {
-      const [key, entryValue] = keyNodeOrEntry;
-      if (key === void 0 || key === null) return [void 0, void 0];
-      const finalValue = value ?? entryValue;
-      return [this.createNode(key, finalValue, "BLACK", count), finalValue];
+  some(callbackfn, thisArg) {
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, k, index++, this) : callbackfn.call(thisArg, v, k, index++, this);
+      if (ok) return true;
     }
-    return [this.createNode(keyNodeOrEntry, value, "BLACK", count), value];
+    return false;
   }
   /**
-   * (Protected) Swap keys/values/counters between the source and destination nodes.
-   * @remarks Time O(1), Space O(1)
-   * @param srcNode - Source node (or key) whose properties will be moved.
-   * @param destNode - Destination node (or key) to receive properties.
-   * @returns Destination node after swap, or undefined.
+   * Find the first entry that satisfies a predicate.
+   * @returns The first matching `[key, value]` tuple, or `undefined`.
+   * @remarks Time O(n), Space O(1)
    */
-  _swapProperties(srcNode, destNode) {
-    srcNode = this.ensureNode(srcNode);
-    destNode = this.ensureNode(destNode);
-    if (srcNode && destNode) {
-      const { key, value, count, color } = destNode;
-      const tempNode = this.createNode(key, value, color, count);
-      if (tempNode) {
-        tempNode.color = color;
-        destNode.key = srcNode.key;
-        if (!this._isMapMode) destNode.value = srcNode.value;
-        destNode.count = srcNode.count;
-        destNode.color = srcNode.color;
-        srcNode.key = tempNode.key;
-        if (!this._isMapMode) srcNode.value = tempNode.value;
-        srcNode.count = tempNode.count;
-        srcNode.color = tempNode.color;
-      }
-      return destNode;
+  find(callbackfn, thisArg) {
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === void 0 ? callbackfn(v, k, index++, this) : callbackfn.call(thisArg, v, k, index++, this);
+      if (ok) return [k, v];
     }
     return void 0;
   }
   /**
-   * (Protected) Replace one node by another and adjust counters accordingly.
-   * @remarks Time O(1), Space O(1)
-   * @param oldNode - Node being replaced.
-   * @param newNode - Replacement node.
-   * @returns The new node after replacement.
+   * Materialize the map into an array of `[key, value]` tuples.
+   * @remarks Time O(n), Space O(n)
    */
-  _replaceNode(oldNode, newNode) {
-    newNode.count = oldNode.count + newNode.count;
-    return super._replaceNode(oldNode, newNode);
+  toArray() {
+    return [...this];
+  }
+  /**
+   * Print a human-friendly representation.
+   * @remarks Time O(n), Space O(n)
+   */
+  print() {
+    this.#core.print();
+  }
+  // Navigable operations (return entry tuples)
+  // Note: returned tuple values may be `undefined`.
+  /**
+   * Smallest entry by key.
+   */
+  first() {
+    const k = this.#core.getLeftMost();
+    return k === void 0 ? void 0 : this._entryFromKey(k);
+  }
+  /**
+   * Largest entry by key.
+   */
+  last() {
+    const k = this.#core.getRightMost();
+    return k === void 0 ? void 0 : this._entryFromKey(k);
+  }
+  /**
+   * Remove and return the smallest entry.
+   */
+  pollFirst() {
+    const entry = this.first();
+    if (!entry) return void 0;
+    this.delete(entry[0]);
+    return entry;
+  }
+  /**
+   * Remove and return the largest entry.
+   */
+  pollLast() {
+    const entry = this.last();
+    if (!entry) return void 0;
+    this.delete(entry[0]);
+    return entry;
+  }
+  /**
+   * Smallest entry whose key is >= the given key.
+   */
+  ceiling(key) {
+    this._validateKey(key);
+    const k = this.#core.ceiling(key);
+    return k === void 0 ? void 0 : this._entryFromKey(k);
+  }
+  /**
+   * Largest entry whose key is <= the given key.
+   */
+  floor(key) {
+    this._validateKey(key);
+    const k = this.#core.floor(key);
+    return k === void 0 ? void 0 : this._entryFromKey(k);
+  }
+  /**
+   * Smallest entry whose key is > the given key.
+   */
+  higher(key) {
+    this._validateKey(key);
+    const k = this.#core.higher(key);
+    return k === void 0 ? void 0 : this._entryFromKey(k);
+  }
+  /**
+   * Largest entry whose key is < the given key.
+   */
+  lower(key) {
+    this._validateKey(key);
+    const k = this.#core.lower(key);
+    return k === void 0 ? void 0 : this._entryFromKey(k);
+  }
+  /**
+   * Return all entries in a given key range.
+   *
+   * @param range `[low, high]`
+   * @param options Inclusive/exclusive bounds (defaults to inclusive).
+   */
+  rangeSearch(range, options = {}) {
+    const { lowInclusive = true, highInclusive = true } = options;
+    const [low, high] = range;
+    this._validateKey(low);
+    this._validateKey(high);
+    const keys = this.#core.rangeSearch([low, high]);
+    const out = [];
+    const cmp = this.#core.comparator;
+    for (const k of keys) {
+      if (k === void 0) continue;
+      if (!lowInclusive && cmp(k, low) === 0) continue;
+      if (!highInclusive && cmp(k, high) === 0) continue;
+      out.push(this._entryFromKey(k));
+    }
+    return out;
   }
 };
 
-// src/data-structures/binary-tree/avl-tree-counter.ts
-var AVLTreeCounterNode = class {
+// src/data-structures/binary-tree/tree-multi-set.ts
+var TreeMultiSet = class _TreeMultiSet {
   static {
-    __name(this, "AVLTreeCounterNode");
+    __name(this, "TreeMultiSet");
   }
-  key;
-  value;
-  parent = void 0;
+  #core;
+  #isDefaultComparator;
+  _size = 0;
+  // total occurrences (sumCounts)
   /**
-   * Create an AVL counter node.
+   * Creates a new TreeMultiSet.
+   * @param elements - Initial elements to add
+   * @param options - Configuration options
+   * @remarks Time O(m log m), Space O(m) where m is the number of initial elements
+   */
+  constructor(elements = [], options = {}) {
+    const comparator = options.comparator ?? TreeSet.createDefaultComparator();
+    this.#isDefaultComparator = options.comparator === void 0;
+    this.#core = new RedBlackTree([], { comparator, isMapMode: options.isMapMode });
+    for (const k of elements) this.add(k);
+  }
+  /**
+   * Validates the key against the default comparator rules.
    * @remarks Time O(1), Space O(1)
-   * @param key - Key of the node.
-   * @param [value] - Associated value (ignored in map mode).
-   * @param [count] - Initial count for this node (default 1).
-   * @returns New AVLTreeCounterNode instance.
    */
-  constructor(key, value, count = 1) {
-    this.key = key;
-    this.value = value;
-    this.count = count;
+  _validateKey(key) {
+    if (!this.#isDefaultComparator) return;
+    if (typeof key === "number") {
+      if (Number.isNaN(key)) throw new TypeError("TreeMultiSet: NaN is not a valid key");
+      return;
+    }
+    if (typeof key === "string") return;
+    if (key instanceof Date) {
+      if (Number.isNaN(key.getTime())) throw new TypeError("TreeMultiSet: invalid Date key");
+      return;
+    }
+    throw new TypeError("TreeMultiSet: comparator is required for non-number/non-string/non-Date keys");
   }
-  _left = void 0;
   /**
-   * Get the left child pointer.
+   * Validates that count is a non-negative safe integer.
    * @remarks Time O(1), Space O(1)
-   * @returns Left child node, or null/undefined.
    */
-  get left() {
-    return this._left;
+  _validateCount(n) {
+    if (!Number.isSafeInteger(n) || n < 0) throw new RangeError("TreeMultiSet: count must be a safe integer >= 0");
   }
   /**
-   * Set the left child and update its parent pointer.
+   * Total occurrences (sumCounts).
    * @remarks Time O(1), Space O(1)
-   * @param v - New left child node, or null/undefined.
-   * @returns void
    */
-  set left(v) {
-    if (v) {
-      v.parent = this;
-    }
-    this._left = v;
+  get size() {
+    return this._size;
   }
-  _right = void 0;
   /**
-   * Get the right child pointer.
+   * Number of distinct keys.
    * @remarks Time O(1), Space O(1)
-   * @returns Right child node, or null/undefined.
    */
-  get right() {
-    return this._right;
+  get distinctSize() {
+    return this.#core.size;
   }
   /**
-   * Set the right child and update its parent pointer.
+   * Whether the multiset is empty.
    * @remarks Time O(1), Space O(1)
-   * @param v - New right child node, or null/undefined.
-   * @returns void
    */
-  set right(v) {
-    if (v) {
-      v.parent = this;
-    }
-    this._right = v;
+  isEmpty() {
+    return this.size === 0;
   }
-  _height = 0;
   /**
-   * Gets the height of the node (used in self-balancing trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The height.
+   * Whether the multiset contains the given key.
+   * @remarks Time O(log n), Space O(1)
    */
-  get height() {
-    return this._height;
+  has(key) {
+    this._validateKey(key);
+    return this.count(key) > 0;
   }
   /**
-   * Sets the height of the node.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new height.
+   * Returns the count of occurrences for the given key.
+   * @remarks Time O(log n), Space O(1)
    */
-  set height(value) {
-    this._height = value;
+  count(key) {
+    this._validateKey(key);
+    return this.#core.get(key) ?? 0;
   }
-  _color = "BLACK";
   /**
-   * Gets the color of the node (used in Red-Black trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The node's color.
+   * Add `n` occurrences of `key`.
+   * @returns True if the multiset changed.
+   * @remarks Time O(log n), Space O(1)
    */
-  get color() {
-    return this._color;
+  add(key, n = 1) {
+    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;
   }
   /**
-   * Sets the color of the node.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new color.
+   * Set count for `key` to exactly `n`.
+   * @returns True if changed.
+   * @remarks Time O(log n), Space O(1)
    */
-  set color(value) {
-    this._color = value;
+  setCount(key, n) {
+    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;
   }
-  _count = 1;
   /**
-   * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The subtree node count.
+   * Delete `n` occurrences of `key` (default 1).
+   * @returns True if any occurrence was removed.
+   * @remarks Time O(log n), Space O(1)
    */
-  get count() {
-    return this._count;
+  delete(key, n = 1) {
+    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;
   }
   /**
-   * Sets the count of nodes in the subtree.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @param value - The new count.
+   * Delete all occurrences of the given key.
+   * @returns True if any occurrence was removed.
+   * @remarks Time O(log n), Space O(1)
    */
-  set count(value) {
-    this._count = value;
+  deleteAll(key) {
+    this._validateKey(key);
+    const old = this.#core.get(key) ?? 0;
+    if (old === 0) return false;
+    this.#core.delete(key);
+    this._size -= old;
+    return true;
   }
   /**
-   * Gets the position of the node relative to its parent.
-   * @remarks Time O(1), Space O(1)
-   *
-   * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
+   * Iterates over distinct keys (each key yielded once).
+   * @remarks Time O(n), Space O(1)
    */
-  get familyPosition() {
-    if (!this.parent) {
-      return this.left || this.right ? "ROOT" : "ISOLATED";
+  *keysDistinct() {
+    yield* this.#core.keys();
+  }
+  /**
+   * Iterates over entries as [key, count] pairs.
+   * @remarks Time O(n), Space O(1)
+   */
+  *entries() {
+    for (const [k, v] of this.#core) {
+      yield [k, v ?? 0];
     }
-    if (this.parent.left === this) {
-      return this.left || this.right ? "ROOT_LEFT" : "LEFT";
-    } else if (this.parent.right === this) {
-      return this.left || this.right ? "ROOT_RIGHT" : "RIGHT";
+  }
+  /**
+   * Expanded iteration (default). Each key is yielded `count(key)` times.
+   * @remarks Time O(size), Space O(1) where size is total occurrences
+   */
+  *[Symbol.iterator]() {
+    for (const [k, c] of this.entries()) {
+      for (let i = 0; i < c; i++) yield k;
     }
-    return "MAL_NODE";
   }
-};
-var AVLTreeCounter = class extends AVLTree {
-  static {
-    __name(this, "AVLTreeCounter");
+  /**
+   * Returns an array with all elements (expanded).
+   * @remarks Time O(size), Space O(size)
+   */
+  toArray() {
+    return [...this];
   }
   /**
-   * Create a AVLTreeCounter instance
+   * Returns an array with distinct keys only.
    * @remarks Time O(n), Space O(n)
-   * @param keysNodesEntriesOrRaws
-   * @param options
-   * @returns New AVLTreeCounterNode instance.
    */
-  constructor(keysNodesEntriesOrRaws = [], options) {
-    super([], options);
-    if (keysNodesEntriesOrRaws) this.setMany(keysNodesEntriesOrRaws);
-  }
-  _count = 0;
-  get count() {
-    return this._count;
+  toDistinctArray() {
+    return [...this.keysDistinct()];
   }
   /**
-   * Compute the total count by traversing the tree (sums node.count).
-   * @remarks Time O(N), Space O(H)
-   * @returns Total count recomputed from nodes.
+   * Returns an array of [key, count] entries.
+   * @remarks Time O(n), Space O(n)
    */
-  getComputedCount() {
-    let sum = 0;
-    this.dfs((node) => sum += node.count);
-    return sum;
+  toEntries() {
+    return [...this.entries()];
   }
-  createNode(key, value, count) {
-    return new AVLTreeCounterNode(key, this._isMapMode ? void 0 : value, count);
+  /**
+   * Expose comparator for advanced usage/testing (read-only).
+   * @remarks Time O(1), Space O(1)
+   */
+  get comparator() {
+    return this.#core._comparator;
   }
+  // ━━━ clear ━━━
   /**
-   * Type guard: check whether the input is an AVLTreeCounterNode.
+   * Remove all elements from the multiset.
    * @remarks Time O(1), Space O(1)
-   * @returns True if the value is an AVLTreeCounterNode.
+   * @example
+   * const ms = new TreeMultiSet([1, 2, 2, 3]);
+   * ms.clear();
+   * ms.size;  // 0
    */
-  isNode(keyNodeOrEntry) {
-    return keyNodeOrEntry instanceof AVLTreeCounterNode;
+  clear() {
+    this.#core.clear();
+    this._size = 0;
   }
+  // ━━━ Navigable methods ━━━
   /**
-   * Insert or increment a node and update aggregate count.
-   * @remarks Time O(log N), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, value] entry to insert.
-   * @param [value] - Value when a bare key is provided (ignored in map mode).
-   * @param [count] - How much to increase the node's count (default 1).
-   * @returns True if inserted/updated; false if ignored.
+   * Returns the smallest key, or undefined if empty.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([3, 1, 4]);
+   * ms.first();  // 1
    */
-  set(keyNodeOrEntry, value, count = 1) {
-    const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value, count);
-    if (newNode === void 0) return false;
-    const orgNodeCount = newNode?.count || 0;
-    const inserted = super.set(newNode, newValue);
-    if (inserted) {
-      this._count += orgNodeCount;
-    }
-    return true;
+  first() {
+    return this.#core.getLeftMost();
   }
   /**
-   * Delete a node (or decrement its count) and rebalance if needed.
-   * @remarks Time O(log N), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, value] entry identifying the node.
-   * @param [ignoreCount] - If true, remove the node regardless of its count.
-   * @returns Array of deletion results including deleted node and a rebalance hint when present.
+   * Returns the largest key, or undefined if empty.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([3, 1, 4]);
+   * ms.last();  // 4
    */
-  delete(keyNodeOrEntry, ignoreCount = false) {
-    const deletedResult = [];
-    if (!this.root) return deletedResult;
-    const curr = this.getNode(keyNodeOrEntry) ?? void 0;
-    if (!curr) return deletedResult;
-    const parent = curr?.parent ? curr.parent : void 0;
-    let needBalanced = void 0, orgCurrent = curr;
-    if (curr.count > 1 && !ignoreCount) {
-      curr.count--;
-      this._count--;
-    } else {
-      if (!curr.left) {
-        if (!parent) {
-          if (curr.right !== void 0 && curr.right !== null) this._setRoot(curr.right);
-        } else {
-          const { familyPosition: fp } = curr;
-          if (fp === "LEFT" || fp === "ROOT_LEFT") {
-            parent.left = curr.right;
-          } else if (fp === "RIGHT" || fp === "ROOT_RIGHT") {
-            parent.right = curr.right;
-          }
-          needBalanced = parent;
-        }
-      } else {
-        const leftSubTreeRightMost = curr.left ? this.getRightMost((node) => node, curr.left) : void 0;
-        if (leftSubTreeRightMost) {
-          const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
-          orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
-          if (parentOfLeftSubTreeMax) {
-            if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost) {
-              parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
-            } else {
-              parentOfLeftSubTreeMax.left = leftSubTreeRightMost.left;
-            }
-            needBalanced = parentOfLeftSubTreeMax;
-          }
-        }
-      }
-      this._size = this._size - 1;
-      if (orgCurrent) this._count -= orgCurrent.count;
-    }
-    deletedResult.push({ deleted: orgCurrent, needBalanced });
-    if (needBalanced) {
-      this._balancePath(needBalanced);
-    }
-    return deletedResult;
+  last() {
+    return this.#core.getRightMost();
   }
   /**
-   * Remove all nodes and reset aggregate counters.
-   * @remarks Time O(N), Space O(1)
-   * @returns void
+   * Removes all occurrences of the smallest key and returns it.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([1, 1, 2, 3]);
+   * ms.pollFirst();  // 1
+   * ms.has(1);       // false
    */
-  clear() {
-    super.clear();
-    this._count = 0;
+  pollFirst() {
+    const key = this.first();
+    if (key === void 0) return void 0;
+    this.deleteAll(key);
+    return key;
   }
   /**
-   * Rebuild the tree into a perfectly balanced form using in-order nodes.
-   * @remarks Time O(N), Space O(N)
-   * @param [iterationType] - Traversal style to use when constructing the balanced tree.
-   * @returns True if rebalancing succeeded (tree not empty).
+   * Removes all occurrences of the largest key and returns it.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([1, 2, 3, 3]);
+   * ms.pollLast();  // 3
+   * ms.has(3);      // false
    */
-  perfectlyBalance(iterationType = this.iterationType) {
-    const nodes = this.dfs((node) => node, "IN", false, this._root, iterationType);
-    const n = nodes.length;
-    if (n === 0) return false;
-    let total = 0;
-    for (const nd of nodes) total += nd ? nd.count : 0;
-    this._clearNodes();
-    const build = /* @__PURE__ */ __name((l, r, parent) => {
-      if (l > r) return void 0;
-      const m = l + (r - l >> 1);
-      const root = nodes[m];
-      root.left = build(l, m - 1, root);
-      root.right = build(m + 1, r, root);
-      root.parent = parent;
-      const lh = root.left ? root.left.height : -1;
-      const rh = root.right ? root.right.height : -1;
-      root.height = Math.max(lh, rh) + 1;
-      return root;
-    }, "build");
-    const newRoot = build(0, n - 1, void 0);
-    this._setRoot(newRoot);
-    this._size = n;
-    this._count = total;
-    return true;
+  pollLast() {
+    const key = this.last();
+    if (key === void 0) return void 0;
+    this.deleteAll(key);
+    return key;
   }
   /**
-   * Deep copy this tree, preserving map mode and aggregate counts.
-   * @remarks Time O(N), Space O(N)
-   * @returns A deep copy of this tree.
+   * Returns the smallest key >= given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([10, 20, 30]);
+   * ms.ceiling(15);  // 20
+   * ms.ceiling(20);  // 20
    */
-  clone() {
-    const out = this._createInstance();
-    if (this._isMapMode) {
-      this.bfs((node) => out.set(node.key, void 0, node.count));
-    } else {
-      this.bfs((node) => out.set(node.key, node.value, node.count));
-    }
-    if (this._isMapMode) out._store = this._store;
-    return out;
+  ceiling(key) {
+    this._validateKey(key);
+    return this.#core.ceiling(key);
   }
   /**
-   * Create a new AVLTreeCounter by mapping each [key, value] entry.
-   * @remarks Time O(N log N), Space O(N)
-   * @template MK
-   * @template MV
-   * @template MR
-   * @param callback - Function mapping (key, value, index, tree) → [newKey, newValue].
-   * @param [options] - Options for the output tree.
-   * @param [thisArg] - Value for `this` inside the callback.
-   * @returns A new AVLTreeCounter with mapped entries.
+   * Returns the largest key <= given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([10, 20, 30]);
+   * ms.floor(25);  // 20
+   * ms.floor(20);  // 20
    */
-  map(callback, options, thisArg) {
-    const out = this._createLike([], options);
-    let index = 0;
-    for (const [key, value] of this) {
-      out.set(callback.call(thisArg, value, key, index++, this));
-    }
-    return out;
+  floor(key) {
+    this._validateKey(key);
+    return this.#core.floor(key);
   }
   /**
-   * (Protected) Create an empty instance of the same concrete class.
-   * @remarks Time O(1), Space O(1)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param [options] - Optional constructor options for the like-kind instance.
-   * @returns An empty like-kind instance.
+   * Returns the smallest key > given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([10, 20, 30]);
+   * ms.higher(10);  // 20
+   * ms.higher(15);  // 20
    */
-  _createInstance(options) {
-    const Ctor = this.constructor;
-    return new Ctor([], { ...this._snapshotOptions(), ...options ?? {} });
+  higher(key) {
+    this._validateKey(key);
+    return this.#core.higher(key);
   }
   /**
-   * (Protected) Create a like-kind instance and seed it from an iterable.
-   * @remarks Time O(N log N), Space O(N)
-   * @template TK
-   * @template TV
-   * @template TR
-   * @param iter - Iterable used to seed the new tree.
-   * @param [options] - Options merged with the current snapshot.
-   * @returns A like-kind AVLTreeCounter built from the iterable.
+   * Returns the largest key < given key, or undefined.
+   * @remarks Time O(log n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([10, 20, 30]);
+   * ms.lower(20);  // 10
+   * ms.lower(15);  // 10
    */
-  _createLike(iter = [], options) {
-    const Ctor = this.constructor;
-    return new Ctor(iter, { ...this._snapshotOptions(), ...options ?? {} });
+  lower(key) {
+    this._validateKey(key);
+    return this.#core.lower(key);
   }
+  // ━━━ Functional methods ━━━
   /**
-   * (Protected) Normalize input into a node plus its effective value and count.
-   * @remarks Time O(1), Space O(1)
-   * @param keyNodeOrEntry - Key, node, or [key, value] entry.
-   * @param [value] - Value used when a bare key is provided.
-   * @param [count] - Count increment to apply (default 1).
-   * @returns Tuple [node, value] where node may be undefined.
+   * Iterates over distinct keys with their counts.
+   * @remarks Time O(n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+   * ms.forEach((key, count) => console.log(`${key}: ${count}`));
+   * // 1: 2, 2: 1, 3: 3
    */
-  _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value, count = 1) {
-    if (keyNodeOrEntry === void 0 || keyNodeOrEntry === null) return [void 0, void 0];
-    if (this.isNode(keyNodeOrEntry)) return [keyNodeOrEntry, value];
-    if (this.isEntry(keyNodeOrEntry)) {
-      const [key, entryValue] = keyNodeOrEntry;
-      if (key === void 0 || key === null) return [void 0, void 0];
-      const finalValue = value ?? entryValue;
-      return [this.createNode(key, finalValue, count), finalValue];
+  forEach(callback) {
+    for (const [k, c] of this.entries()) {
+      callback(k, c);
     }
-    return [this.createNode(keyNodeOrEntry, value, count), value];
   }
   /**
-   * (Protected) Swap keys/values/counters between the source and destination nodes.
-   * @remarks Time O(1), Space O(1)
-   * @param srcNode - Source node (or key) whose properties will be moved.
-   * @param destNode - Destination node (or key) to receive properties.
-   * @returns Destination node after swap, or undefined.
+   * Creates a new TreeMultiSet with entries that match the predicate.
+   * @remarks Time O(n log n), Space O(n)
+   * @example
+   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+   * const filtered = ms.filter((key, count) => count >= 2);
+   * // TreeMultiSet { 1: 2, 3: 3 }
    */
-  _swapProperties(srcNode, destNode) {
-    srcNode = this.ensureNode(srcNode);
-    destNode = this.ensureNode(destNode);
-    if (srcNode && destNode) {
-      const { key, value, count, height } = destNode;
-      const tempNode = this.createNode(key, value, count);
-      if (tempNode) {
-        tempNode.height = height;
-        destNode.key = srcNode.key;
-        if (!this._isMapMode) destNode.value = srcNode.value;
-        destNode.count = srcNode.count;
-        destNode.height = srcNode.height;
-        srcNode.key = tempNode.key;
-        if (!this._isMapMode) srcNode.value = tempNode.value;
-        srcNode.count = tempNode.count;
-        srcNode.height = tempNode.height;
+  filter(predicate) {
+    const result = new _TreeMultiSet([], {
+      comparator: this.#isDefaultComparator ? void 0 : this.comparator,
+      isMapMode: this.#core._isMapMode
+    });
+    for (const [k, c] of this.entries()) {
+      if (predicate(k, c)) {
+        result.add(k, c);
       }
-      return destNode;
     }
-    return void 0;
+    return result;
   }
   /**
-   * (Protected) Replace one node by another and adjust counters accordingly.
-   * @remarks Time O(1), Space O(1)
-   * @param oldNode - Node being replaced.
-   * @param newNode - Replacement node.
-   * @returns The new node after replacement.
+   * Reduces the multiset to a single value.
+   * @remarks Time O(n), Space O(1)
+   * @example
+   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+   * const total = ms.reduce((acc, key, count) => acc + count, 0);  // 6
    */
-  _replaceNode(oldNode, newNode) {
-    newNode.count = oldNode.count + newNode.count;
-    return super._replaceNode(oldNode, newNode);
+  reduce(callback, initialValue) {
+    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
+   * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+   * const mapped = ms.map((key, count) => [key * 10, count]);
+   * // TreeMultiSet { 10: 2, 20: 1, 30: 3 }
+   * @example
+   * // Collision: counts merge
+   * const ms = new TreeMultiSet([1, 2, 3]);
+   * const merged = ms.map((key, count) => [key % 2, count]);
+   * // { 0: 1, 1: 2 }  (1 and 3 both map to 1, counts add)
+   */
+  map(mapper, options) {
+    const result = new _TreeMultiSet([], {
+      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)
+   * @example
+   * const ms = new TreeMultiSet([1, 1, 2]);
+   * const copy = ms.clone();
+   * copy.add(3);
+   * ms.has(3);  // false (original unchanged)
+   */
+  clone() {
+    const result = new _TreeMultiSet([], {
+      comparator: this.#isDefaultComparator ? void 0 : 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
+   * @example
+   * const ms = new TreeMultiSet([10, 20, 30, 40, 50]);
+   * ms.rangeSearch([15, 45]);  // [20, 30, 40]
+   */
+  rangeSearch(range, callback) {
+    const cb = callback ?? ((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)
+   * @example
+   * const ms = new TreeMultiSet([1, 2, 3]);
+   * ms.print();
+   */
+  print() {
+    this.#core.print();
   }
 };
 
@@ -14514,6 +14579,13 @@ var TreeNode = class _TreeNode {
  * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng
+ * @license MIT License
+ */
 /**
  * data-structure-typed
  *
@@ -14522,6 +14594,6 @@ var TreeNode = class _TreeNode {
  * @license MIT License
  */
 
-export { AVLTree, AVLTreeCounter, AVLTreeCounterNode, AVLTreeMultiMap, AVLTreeMultiMapNode, AVLTreeNode, AbstractEdge, AbstractGraph, AbstractVertex, BST, BSTNode, BinaryIndexedTree, BinaryTree, BinaryTreeNode, Character, DFSOperation, Deque, DirectedEdge, DirectedGraph, DirectedVertex, DoublyLinkedList, DoublyLinkedListNode, FibonacciHeap, FibonacciHeapNode, HashMap, Heap, IterableElementBase, IterableEntryBase, LinkedHashMap, LinkedListQueue, MapEdge, MapGraph, MapVertex, Matrix, MaxHeap, MaxPriorityQueue, MinHeap, MinPriorityQueue, Navigator, PriorityQueue, Queue, Range, RedBlackTree, RedBlackTreeNode, SegmentTree, SegmentTreeNode, SinglyLinkedList, SinglyLinkedListNode, SkipList, SkipListNode, Stack, TreeCounter, TreeCounterNode, TreeMultiMap, TreeMultiMapNode, TreeNode, Trie, TrieNode, UndirectedEdge, UndirectedGraph, UndirectedVertex, arrayRemove, asyncTrampoline, calcMinUnitsRequired, getMSB, isComparable, isTrampolineThunk, isWeakKey, makeAsyncTrampoline, makeTrampoline, makeTrampolineThunk, rangeCheck, roundFixed, throwRangeError, toBinaryString, trampoline, uuidV4 };
+export { AVLTree, AVLTreeNode, AbstractEdge, AbstractGraph, AbstractVertex, BST, BSTNode, BinaryIndexedTree, BinaryTree, BinaryTreeNode, Character, DFSOperation, Deque, DirectedEdge, DirectedGraph, DirectedVertex, DoublyLinkedList, DoublyLinkedListNode, FibonacciHeap, FibonacciHeapNode, HashMap, Heap, IterableElementBase, IterableEntryBase, LinkedHashMap, LinkedListQueue, MapEdge, MapGraph, MapVertex, Matrix, MaxHeap, MaxPriorityQueue, MinHeap, MinPriorityQueue, Navigator, PriorityQueue, Queue, Range, RedBlackTree, RedBlackTreeNode, SegmentTree, SegmentTreeNode, SinglyLinkedList, SinglyLinkedListNode, SkipList, SkipListNode, Stack, TreeMap, TreeMultiMap, TreeMultiMapNode, TreeMultiSet, TreeNode, TreeSet, Trie, TrieNode, UndirectedEdge, UndirectedGraph, UndirectedVertex, arrayRemove, asyncTrampoline, calcMinUnitsRequired, getMSB, isComparable, isTrampolineThunk, isWeakKey, makeAsyncTrampoline, makeTrampoline, makeTrampolineThunk, rangeCheck, roundFixed, throwRangeError, toBinaryString, trampoline, uuidV4 };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map