data-structure-typed 2.2.4 → 2.2.5

package/CHANGELOG.md

@@ -8,7 +8,7 @@ All notable changes to this project will be documented in this file.
 - [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - [`auto-changelog`](https://github.com/CookPete/auto-changelog)
 
-## [v2.2.4](https://github.com/zrwusa/data-structure-typed/compare/v2.2.3...main) (upcoming)
+## [v2.2.5](https://github.com/zrwusa/data-structure-typed/compare/v2.2.3...main) (upcoming)
 
 ## [v2.2.3](https://github.com/zrwusa/data-structure-typed/compare/v2.2.2...v2.2.3) (6 January 2026)
 

package/dist/cjs/index.cjs

@@ -8656,27 +8656,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.
   
@@ -9024,6 +9003,104 @@ var BST = class extends BinaryTree {
   upperBound(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
     return this._bound(keyNodeEntryOrPredicate, false, iterationType);
   }
+  /**
+   * Returns the first node with a key greater than or equal to the given key.
+   * This is equivalent to Java TreeMap.ceilingEntry().
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node with key >= given key, or undefined if no such node exists.
+   */
+  ceilingEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    return this.lowerBound(keyNodeEntryOrPredicate, iterationType);
+  }
+  /**
+   * Returns the first node with a key strictly greater than the given key.
+   * This is equivalent to Java TreeMap.higherEntry().
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node with key > given key, or undefined if no such node exists.
+   */
+  higherEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    return this.upperBound(keyNodeEntryOrPredicate, iterationType);
+  }
+  /**
+   * Returns the first node with a key less than or equal to the given key.
+   * This is equivalent to Java TreeMap.floorEntry().
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node with key <= given key, or undefined if no such node exists.
+   */
+  floorEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      return void 0;
+    }
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      return this._floorByPredicate(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._floorByKey(targetKey, iterationType);
+    }
+    return void 0;
+  }
+  /**
+   * Returns the first node with a key strictly less than the given key.
+   * This is equivalent to Java TreeMap.lowerEntry().
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node with key < given key, or undefined if no such node exists.
+   */
+  lowerEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      return void 0;
+    }
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      return this._lowerByPredicate(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._lowerByKey(targetKey, iterationType);
+    }
+    return void 0;
+  }
   /**
    * 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).
@@ -9194,13 +9271,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);
@@ -9208,6 +9279,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.