tree-multimap-typed 2.2.2 → 2.2.4

package/dist/esm/index.mjs

@@ -1461,6 +1461,17 @@ var BinaryTree = class extends IterableEntryBase {
     }
     return false;
   }
+  /**
+   * Adds or updates a new node to the tree.
+   * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). This implementation adds the node at the first available position in a level-order (BFS) traversal. This is NOT a Binary Search Tree insertion. Time O(N), where N is the number of nodes. It must traverse level-by-level to find an empty slot. Space O(N) in the worst case for the BFS queue (e.g., a full last level).
+   *
+   * @param keyNodeOrEntry - The key, node, or entry to add or update.
+   * @param [value] - The value, if providing just a key.
+   * @returns True if the addition was successful, false otherwise.
+   */
+  set(keyNodeOrEntry, value) {
+    return this.add(keyNodeOrEntry, value);
+  }
   /**
    * Adds multiple items to the tree.
    * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
@@ -1488,6 +1499,17 @@ var BinaryTree = class extends IterableEntryBase {
     }
     return inserted;
   }
+  /**
+   * Adds or updates multiple items to the tree.
+   * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
+   *
+   * @param keysNodesEntriesOrRaws - An iterable of items to add or update.
+   * @param [values] - An optional parallel iterable of values.
+   * @returns An array of booleans indicating the success of each individual `add` operation.
+   */
+  setMany(keysNodesEntriesOrRaws, values) {
+    return this.addMany(keysNodesEntriesOrRaws, values);
+  }
   /**
    * Merges another tree into this one by adding all its nodes.
    * @remarks Time O(N * M), same as `addMany`, where N is the size of `anotherTree` and M is the size of this tree. Space O(M) (from `add`).
@@ -2811,9 +2833,13 @@ var BST = class extends BinaryTree {
   constructor(keysNodesEntriesOrRaws = [], options) {
     super([], options);
     if (options) {
-      const { specifyComparable, isReverse } = options;
-      if (typeof specifyComparable === "function") this._specifyComparable = specifyComparable;
-      if (isReverse !== void 0) this._isReverse = isReverse;
+      if ("comparator" in options && options.comparator !== void 0) {
+        this._comparator = options.comparator;
+      } else {
+        this._comparator = this._createDefaultComparator();
+      }
+    } else {
+      this._comparator = this._createDefaultComparator();
     }
     if (keysNodesEntriesOrRaws) this.addMany(keysNodesEntriesOrRaws);
   }
@@ -2827,40 +2853,33 @@ var BST = class extends BinaryTree {
   get root() {
     return this._root;
   }
-  _isReverse = false;
   /**
-   * Gets whether the tree's comparison logic is reversed.
-   * @remarks Time O(1)
-   *
-   * @returns True if the tree is reversed (e.g., a max-heap logic).
+   * (Protected) Creates the default comparator function for keys that don't have a custom comparator.
+   * @remarks Time O(1) Space O(1)
+   * @returns The default comparator function.
    */
-  get isReverse() {
-    return this._isReverse;
+  _createDefaultComparator() {
+    return (a, b) => {
+      debugger;
+      if (isComparable(a) && isComparable(b)) {
+        if (a > b) return 1;
+        if (a < b) return -1;
+        return 0;
+      }
+      if (typeof a === "object" || typeof b === "object") {
+        throw TypeError(
+          `When comparing object type keys, a custom comparator must be provided in the constructor's options!`
+        );
+      }
+      return 0;
+    };
   }
   /**
-   * The default comparator function.
-   * @remarks Time O(1) (or O(C) if `specifyComparable` is used, C is complexity of that function).
-   */
-  _comparator = /* @__PURE__ */ __name((a, b) => {
-    if (isComparable(a) && isComparable(b)) {
-      if (a > b) return 1;
-      if (a < b) return -1;
-      return 0;
-    }
-    if (this._specifyComparable) {
-      const va = this._specifyComparable(a);
-      const vb = this._specifyComparable(b);
-      if (va > vb) return 1;
-      if (va < vb) return -1;
-      return 0;
-    }
-    if (typeof a === "object" || typeof b === "object") {
-      throw TypeError(
-        `When comparing object types, a custom specifyComparable must be defined in the constructor's options.`
-      );
-    }
-    return 0;
-  }, "_comparator");
+     * The comparator function used to determine the order of keys in the tree.
+  
+     * @remarks Time O(1) Space O(1)
+     */
+  _comparator;
   /**
    * Gets the comparator function used by the tree.
    * @remarks Time O(1)
@@ -2870,16 +2889,6 @@ var BST = class extends BinaryTree {
   get comparator() {
     return this._comparator;
   }
-  _specifyComparable;
-  /**
-   * Gets the function used to extract a comparable value from a complex key.
-   * @remarks Time O(1)
-   *
-   * @returns The key-to-comparable conversion function.
-   */
-  get specifyComparable() {
-    return this._specifyComparable;
-  }
   /**
    * (Protected) Creates a new BST node.
    * @remarks Time O(1), Space O(1)
@@ -2920,7 +2929,7 @@ var BST = class extends BinaryTree {
    * @returns True if the key is valid, false otherwise.
    */
   isValidKey(key) {
-    return isComparable(key, this._specifyComparable !== void 0);
+    return isComparable(key);
   }
   /**
    * Performs a Depth-First Search (DFS) traversal.
@@ -3009,8 +3018,8 @@ var BST = class extends BinaryTree {
       if (!this.isRealNode(cur.left)) return false;
       if (isRange) {
         const range = keyNodeEntryOrPredicate;
-        const leftS = this.isReverse ? range.high : range.low;
-        const leftI = this.isReverse ? range.includeHigh : range.includeLow;
+        const leftS = range.low;
+        const leftI = range.includeLow;
         return leftI && this._compare(cur.key, leftS) >= 0 || !leftI && this._compare(cur.key, leftS) > 0;
       }
       if (!isRange && !this._isPredicate(keyNodeEntryOrPredicate)) {
@@ -3024,8 +3033,8 @@ var BST = class extends BinaryTree {
       if (!this.isRealNode(cur.right)) return false;
       if (isRange) {
         const range = keyNodeEntryOrPredicate;
-        const rightS = this.isReverse ? range.low : range.high;
-        const rightI = this.isReverse ? range.includeLow : range.includeHigh;
+        const rightS = range.high;
+        const rightI = range.includeHigh;
         return rightI && this._compare(cur.key, rightS) <= 0 || !rightI && this._compare(cur.key, rightS) < 0;
       }
       if (!isRange && !this._isPredicate(keyNodeEntryOrPredicate)) {
@@ -3186,6 +3195,32 @@ var BST = class extends BinaryTree {
     else _iterate();
     return inserted;
   }
+  /**
+   * Returns the first node with a key greater than or equal to the given key.
+   * This is equivalent to C++ std::lower_bound on a BST.
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * Time Complexity: O(log n) on average, O(h) where h is tree height.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+   * @returns The first node with key >= given key, or undefined if no such node exists.
+   */
+  lowerBound(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    return this._bound(keyNodeEntryOrPredicate, true, iterationType);
+  }
+  /**
+   * Returns the first node with a key strictly greater than the given key.
+   * This is equivalent to C++ std::upper_bound on a BST.
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * Time Complexity: O(log n) on average, O(h) where h is tree height.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+   * @returns The first node with key > given key, or undefined if no such node exists.
+   */
+  upperBound(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    return this._bound(keyNodeEntryOrPredicate, false, iterationType);
+  }
   /**
    * Traverses the tree and returns nodes that are lesser or greater than a target node.
    * @remarks Time O(N), as it performs a full traversal. Space O(log N) or O(N).
@@ -3320,31 +3355,170 @@ var BST = class extends BinaryTree {
     return out;
   }
   /**
-   * Deletes the first node found that satisfies the predicate.
-   * @remarks Performs an in-order traversal. Time O(N) worst-case (O(log N) to find + O(log N) to delete). Space O(log N) for stack.
+   * Deletes nodes that match a key, node, entry, predicate, or range.
    *
-   * @param predicate - A function to test each [key, value] pair.
-   * @returns True if a node was deleted, false otherwise.
+   * @remarks
+   * Time Complexity: O(N) for search + O(M log N) for M deletions, where N is tree size.
+   * Space Complexity: O(M) for storing matched nodes and result map.
+   *
+   * @template K - The key type.
+   * @template V - The value type.
+   *
+   * @param keyNodeEntryOrPredicate - The search criteria. Can be one of:
+   *   - A key (type K): searches for exact key match using the comparator.
+   *   - A BSTNode: searches for the matching node in the tree.
+   *   - An entry tuple: searches for the key-value pair.
+   *   - A NodePredicate function: tests each node and returns true for matches.
+   *   - A Range object: searches for nodes whose keys fall within the specified range (inclusive/exclusive based on range settings).
+   *   - null or undefined: treated as no match, returns empty results.
+   *
+   * @param onlyOne - If true, stops the search after finding the first match and only deletes that one node.
+   *   If false (default), searches for and deletes all matching nodes.
+   *
+   * @param startNode - The node to start the search from. Can be:
+   *   - A key, node, or entry: the method resolves it to a node and searches from that subtree.
+   *   - null or undefined: defaults to the root, searching the entire tree.
+   *   - Default value: this._root (the tree's root).
+   *
+   * @param iterationType - Controls the internal traversal implementation:
+   *   - 'RECURSIVE': uses recursive function calls for traversal.
+   *   - 'ITERATIVE': uses explicit stack-based iteration.
+   *   - Default: this.iterationType (the tree's default iteration mode).
+   *
+   * @returns A Map<K, boolean> containing the deletion results:
+   *   - Key: the matched node's key.
+   *   - Value: true if the deletion succeeded, false if it failed (e.g., key not found during deletion phase).
+   *   - If no nodes match the search criteria, the returned map is empty.
+   */
+  deleteWhere(keyNodeEntryOrPredicate, onlyOne = false, startNode = this._root, iterationType = this.iterationType) {
+    const toDelete = this.search(
+      keyNodeEntryOrPredicate,
+      onlyOne,
+      (node) => node,
+      startNode,
+      iterationType
+    );
+    let results = [];
+    for (const node of toDelete) {
+      const deleteInfo = this.delete(node);
+      results = results.concat(deleteInfo);
+    }
+    return results;
+  }
+  /**
+   * (Protected) Core bound search implementation supporting all parameter types.
+   * Unified logic for both lowerBound and upperBound.
+   * Resolves various input types (Key, Node, Entry, Predicate) using parent class utilities.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param isLower - True for lowerBound (>=), false for upperBound (>).
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first matching node, or undefined if no such node exists.
    */
-  deleteWhere(predicate) {
-    const stack = [];
-    let cur = this._root;
-    let index = 0;
-    while (stack.length > 0 || cur !== void 0) {
-      while (cur !== void 0 && cur !== null) {
-        stack.push(cur);
-        cur = cur.left;
+  _bound(keyNodeEntryOrPredicate, isLower, iterationType) {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      return void 0;
+    }
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      return this._boundByPredicate(keyNodeEntryOrPredicate, iterationType);
+    }
+    let targetKey;
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === void 0) {
+        return void 0;
       }
-      const node = stack.pop();
-      if (!node) break;
-      const key = node.key;
-      const val = node.value;
-      if (predicate(key, val, index++, this)) {
-        return this._deleteByKey(key);
+      targetKey = key;
+    } else {
+      targetKey = keyNodeEntryOrPredicate;
+    }
+    if (targetKey !== void 0) {
+      return this._boundByKey(targetKey, isLower, iterationType);
+    }
+    return void 0;
+  }
+  /**
+   * (Protected) Binary search for bound by key with pruning optimization.
+   * Performs standard BST binary search, choosing left or right subtree based on comparator result.
+   * For lowerBound: finds first node where key >= target.
+   * For upperBound: finds first node where key > target.
+   * @param key - The target key to search for.
+   * @param isLower - True for lowerBound (>=), false for upperBound (>).
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node matching the bound condition, or undefined if none exists.
+   */
+  _boundByKey(key, isLower, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (!this.isRealNode(cur)) return void 0;
+        const cmp = this.comparator(cur.key, key);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+        if (condition) {
+          const leftResult = dfs(cur.left);
+          return leftResult ?? cur;
+        } else {
+          return dfs(cur.right);
+        }
+      }, "dfs");
+      return dfs(this.root);
+    } else {
+      let current = this.root;
+      let result = void 0;
+      while (this.isRealNode(current)) {
+        const cmp = this.comparator(current.key, key);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+        if (condition) {
+          result = current;
+          current = current.left ?? void 0;
+        } else {
+          current = current.right ?? void 0;
+        }
       }
-      cur = node.right;
+      return result;
+    }
+  }
+  /**
+   * (Protected) In-order traversal search by predicate.
+   * Falls back to linear in-order traversal when predicate-based search is required.
+   * Returns the first node that satisfies the predicate function.
+   * Note: Predicate-based search cannot leverage BST's binary search optimization.
+   * Time Complexity: O(n) since it may visit every node.
+   * @param predicate - The predicate function to test nodes.
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node satisfying predicate, or undefined if none found.
+   */
+  _boundByPredicate(predicate, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      let result = void 0;
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (result || !this.isRealNode(cur)) return;
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+        if (!result && predicate(cur)) {
+          result = cur;
+        }
+        if (!result && this.isRealNode(cur.right)) dfs(cur.right);
+      }, "dfs");
+      dfs(this.root);
+      return result;
+    } else {
+      const stack = [];
+      let current = this.root;
+      while (stack.length > 0 || this.isRealNode(current)) {
+        if (this.isRealNode(current)) {
+          stack.push(current);
+          current = current.left;
+        } else {
+          const node = stack.pop();
+          if (!this.isRealNode(node)) break;
+          if (predicate(node)) {
+            return node;
+          }
+          current = node.right;
+        }
+      }
+      return void 0;
     }
-    return false;
   }
   /**
    * (Protected) Creates a new, empty instance of the same BST constructor.
@@ -3381,8 +3555,7 @@ var BST = class extends BinaryTree {
   _snapshotOptions() {
     return {
       ...super._snapshotOptions(),
-      specifyComparable: this.specifyComparable,
-      isReverse: this.isReverse
+      comparator: this._comparator
     };
   }
   /**
@@ -3410,14 +3583,14 @@ var BST = class extends BinaryTree {
   }
   /**
    * (Protected) Compares two keys using the tree's comparator and reverse setting.
-   * @remarks Time O(1) (or O(C) if `specifyComparable` is used).
+   * @remarks Time O(1) Space O(1)
    *
    * @param a - The first key.
    * @param b - The second key.
    * @returns A number (1, -1, or 0) representing the comparison.
    */
   _compare(a, b) {
-    return this._isReverse ? -this._comparator(a, b) : this._comparator(a, b);
+    return this._comparator(a, b);
   }
   /**
    * (Private) Deletes a node by its key.