tree-multimap-typed 2.2.4 → 2.2.7

package/dist/cjs/index.cjs

@@ -1000,6 +1000,14 @@ var IterableEntryBase = class {
     }
     return accumulator;
   }
+  /**
+   * Converts data structure to `[key, value]` pairs.
+   * @returns Array of entries.
+   * @remarks Time O(n), Space O(n)
+   */
+  toArray() {
+    return [...this];
+  }
   /**
    * Visualize the iterable as an array of `[key, value]` pairs (or a custom string).
    * @returns Array of entries (default) or a string.
@@ -1029,8 +1037,6 @@ var Range = class {
     this.high = high;
     this.includeLow = includeLow;
     this.includeHigh = includeHigh;
-    if (!(isComparable(low) && isComparable(high))) throw new RangeError("low or high is not comparable");
-    if (low > high) throw new RangeError("low must be less than or equal to high");
   }
   static {
     __name(this, "Range");
@@ -2855,27 +2861,6 @@ var BST = class extends BinaryTree {
   get root() {
     return this._root;
   }
-  /**
-   * (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.
-   */
-  _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 comparator function used to determine the order of keys in the tree.
   
@@ -3197,31 +3182,141 @@ 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);
+  ceiling(keyNodeEntryOrPredicate, callback = this._DEFAULT_NODE_CALLBACK, iterationType) {
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
+    const node = this._bound(keyNodeEntryOrPredicate, true, actualIterationType);
+    if (!actualCallback) {
+      return node?.key;
+    }
+    return node ? actualCallback(node) : void 0;
+  }
+  higher(keyNodeEntryOrPredicate, callback = this._DEFAULT_NODE_CALLBACK, iterationType) {
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
+    const node = this._bound(keyNodeEntryOrPredicate, false, actualIterationType);
+    if (!actualCallback) {
+      return node?.key;
+    }
+    return node ? actualCallback(node) : void 0;
   }
-  /**
-   * 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);
+  floor(keyNodeEntryOrPredicate, callback = this._DEFAULT_NODE_CALLBACK, iterationType) {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      if (typeof callback === "string" || !callback) {
+        return void 0;
+      }
+      return void 0;
+    }
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      const node = this._floorByPredicate(keyNodeEntryOrPredicate, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
+    }
+    let targetKey;
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === void 0) {
+        if (typeof callback === "string" || !callback) {
+          return void 0;
+        }
+        return void 0;
+      }
+      targetKey = key;
+    } else {
+      targetKey = keyNodeEntryOrPredicate;
+    }
+    if (targetKey !== void 0) {
+      const node = this._floorByKey(targetKey, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
+    }
+    if (typeof callback === "string" || !callback) {
+      return void 0;
+    }
+    return void 0;
+  }
+  lower(keyNodeEntryOrPredicate, callback, iterationType) {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      if (typeof callback === "string" || !callback) {
+        return void 0;
+      }
+      return void 0;
+    }
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      const node = this._lowerByPredicate(keyNodeEntryOrPredicate, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
+    }
+    let targetKey;
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === void 0) {
+        if (typeof callback === "string" || !callback) {
+          return void 0;
+        }
+        return void 0;
+      }
+      targetKey = key;
+    } else {
+      targetKey = keyNodeEntryOrPredicate;
+    }
+    if (targetKey !== void 0) {
+      const node = this._lowerByKey(targetKey, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
+    }
+    if (typeof callback === "string" || !callback) {
+      return void 0;
+    }
+    return void 0;
   }
   /**
    * Traverses the tree and returns nodes that are lesser or greater than a target node.
@@ -3393,13 +3488,7 @@ var BST = class extends BinaryTree {
    *   - 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
-    );
+    const toDelete = this.search(keyNodeEntryOrPredicate, onlyOne, (node) => node, startNode, iterationType);
     let results = [];
     for (const node of toDelete) {
       const deleteInfo = this.delete(node);
@@ -3407,6 +3496,191 @@ var BST = class extends BinaryTree {
     }
     return results;
   }
+  /**
+   * (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.
+   */
+  _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;
+    };
+  }
+  /**
+   * (Protected) Binary search for floor by key with pruning optimization.
+   * Performs standard BST binary search, choosing left or right subtree based on comparator result.
+   * Finds first node where key <= target.
+   * @remarks Time O(h) where h is tree height.
+   *
+   * @param key - The target key to search for.
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node with key <= target, or undefined if none exists.
+   */
+  _floorByKey(key, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (!this.isRealNode(cur)) return void 0;
+        const cmp = this.comparator(cur.key, key);
+        if (cmp <= 0) {
+          const rightResult = dfs(cur.right);
+          return rightResult ?? cur;
+        } else {
+          return dfs(cur.left);
+        }
+      }, "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);
+        if (cmp <= 0) {
+          result = current;
+          current = current.right ?? void 0;
+        } else {
+          current = current.left ?? void 0;
+        }
+      }
+      return result;
+    }
+  }
+  /**
+   * (Protected) In-order traversal search for floor by predicate.
+   * Falls back to linear in-order traversal when predicate-based search is required.
+   * Returns the last node that satisfies the predicate function.
+   * @remarks Time Complexity: O(n) since it may visit every node.
+   * Space Complexity: O(h) for recursion, O(h) for iterative stack.
+   *
+   * @param predicate - The predicate function to test nodes.
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The last node satisfying predicate (highest key), or undefined if none found.
+   */
+  _floorByPredicate(predicate, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      let result = void 0;
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (!this.isRealNode(cur)) return;
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+        if (predicate(cur)) {
+          result = cur;
+        }
+        if (this.isRealNode(cur.right)) dfs(cur.right);
+      }, "dfs");
+      dfs(this.root);
+      return result;
+    } else {
+      const stack = [];
+      let current = this.root;
+      let result = void 0;
+      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)) {
+            result = node;
+          }
+          current = node.right;
+        }
+      }
+      return result;
+    }
+  }
+  /**
+   * (Protected) Binary search for lower by key with pruning optimization.
+   * Performs standard BST binary search, choosing left or right subtree based on comparator result.
+   * Finds first node where key < target.
+   * @remarks Time O(h) where h is tree height.
+   *
+   * @param key - The target key to search for.
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node with key < target, or undefined if none exists.
+   */
+  _lowerByKey(key, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (!this.isRealNode(cur)) return void 0;
+        const cmp = this.comparator(cur.key, key);
+        if (cmp < 0) {
+          const rightResult = dfs(cur.right);
+          return rightResult ?? cur;
+        } else {
+          return dfs(cur.left);
+        }
+      }, "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);
+        if (cmp < 0) {
+          result = current;
+          current = current.right ?? void 0;
+        } else {
+          current = current.left ?? void 0;
+        }
+      }
+      return result;
+    }
+  }
+  /**
+   * (Protected) In-order traversal search for lower by predicate.
+   * Falls back to linear in-order traversal when predicate-based search is required.
+   * Returns the node that satisfies the predicate and appears last in in-order traversal.
+   * @remarks Time Complexity: O(n) since it may visit every node.
+   * Space Complexity: O(h) for recursion, O(h) for iterative stack.
+   *
+   * @param predicate - The predicate function to test nodes.
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The last node satisfying predicate (highest key < target), or undefined if none found.
+   */
+  _lowerByPredicate(predicate, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      let result = void 0;
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (!this.isRealNode(cur)) return;
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+        if (predicate(cur)) {
+          result = cur;
+        }
+        if (this.isRealNode(cur.right)) dfs(cur.right);
+      }, "dfs");
+      dfs(this.root);
+      return result;
+    } else {
+      const stack = [];
+      let current = this.root;
+      let result = void 0;
+      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)) {
+            result = node;
+          }
+          current = node.right;
+        }
+      }
+      return result;
+    }
+  }
   /**
    * (Protected) Core bound search implementation supporting all parameter types.
    * Unified logic for both lowerBound and upperBound.