avl-tree-typed 2.2.2 → 2.2.3

package/dist/cjs/index.cjs

@@ -1458,6 +1458,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).
@@ -1485,6 +1496,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`).
@@ -3183,6 +3205,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).
@@ -3343,6 +3391,121 @@ var BST = class extends BinaryTree {
     }
     return false;
   }
+  /**
+   * (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.
+   */
+  _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;
+      }
+      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;
+        }
+      }
+      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;
+    }
+  }
   /**
    * (Protected) Creates a new, empty instance of the same BST constructor.
    * @remarks Time O(1)