data-structure-typed 2.2.4 → 2.2.5

package/dist/types/data-structures/binary-tree/bst.d.ts

@@ -288,12 +288,6 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @returns The root node.
      */
     get root(): OptNode<BSTNode<K, V>>;
-    /**
-     * (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.
-     */
-    protected _createDefaultComparator(): Comparator<K>;
     /**
      * The comparator function used to determine the order of keys in the tree.
   
@@ -457,6 +451,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @returns The first node with key > given key, or undefined if no such node exists.
      */
     upperBound(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, iterationType?: IterationType): BSTNode<K, V> | undefined;
+    /**
+     * 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: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, iterationType?: IterationType): BSTNode<K, V> | undefined;
+    /**
+     * 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: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, iterationType?: IterationType): BSTNode<K, V> | undefined;
+    /**
+     * 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: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, iterationType?: IterationType): BSTNode<K, V> | undefined;
+    /**
+     * 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: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, iterationType?: IterationType): BSTNode<K, V> | undefined;
     /**
      * 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).
@@ -536,6 +578,58 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      *   - If no nodes match the search criteria, the returned map is empty.
      */
     deleteWhere(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>> | Range<K>, onlyOne?: boolean, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): BinaryTreeDeleteResult<BSTNode<K, V>>[];
+    /**
+     * (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.
+     */
+    protected _createDefaultComparator(): Comparator<K>;
+    /**
+     * (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.
+     */
+    protected _floorByKey(key: K, iterationType: IterationType): BSTNode<K, V> | undefined;
+    /**
+     * (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.
+     */
+    protected _floorByPredicate(predicate: NodePredicate<BSTNode<K, V>>, iterationType: IterationType): BSTNode<K, V> | undefined;
+    /**
+     * (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.
+     */
+    protected _lowerByKey(key: K, iterationType: IterationType): BSTNode<K, V> | undefined;
+    /**
+     * (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.
+     */
+    protected _lowerByPredicate(predicate: NodePredicate<BSTNode<K, V>>, iterationType: IterationType): BSTNode<K, V> | undefined;
     /**
      * (Protected) Core bound search implementation supporting all parameter types.
      * Unified logic for both lowerBound and upperBound.

package/dist/umd/data-structure-typed.js

@@ -8654,27 +8654,6 @@ var dataStructureTyped = (() => {
     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;
-      };
-    }
     /**
      * Gets the comparator function used by the tree.
      * @remarks Time O(1)
@@ -9018,6 +8997,104 @@ var dataStructureTyped = (() => {
     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).
@@ -9188,13 +9265,7 @@ var dataStructureTyped = (() => {
      *   - 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);
@@ -9202,6 +9273,193 @@ var dataStructureTyped = (() => {
       }
       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) {
+      var _a, _b;
+      if (iterationType === "RECURSIVE") {
+        const dfs = (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 != null ? rightResult : cur;
+          } else {
+            return dfs(cur.left);
+          }
+        };
+        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 = (_a = current.right) != null ? _a : void 0;
+          } else {
+            current = (_b = current.left) != null ? _b : 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 = (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(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) {
+      var _a, _b;
+      if (iterationType === "RECURSIVE") {
+        const dfs = (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 != null ? rightResult : cur;
+          } else {
+            return dfs(cur.left);
+          }
+        };
+        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 = (_a = current.right) != null ? _a : void 0;
+          } else {
+            current = (_b = current.left) != null ? _b : 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 = (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(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.