min-priority-queue-typed 2.2.4 → 2.2.7

package/src/data-structures/binary-tree/bst.ts

@@ -331,7 +331,7 @@ export class BSTNode<K = any, V = any> {
  *       return findFirstCommon(path1, path2);
  *     };
  *
- *     function findFirstCommon(arr1: number[], arr2: number[]): number | undefined {
+ *     function findFirstCommon(arr1: (number | undefined)[], arr2: (number | undefined)[]): number | undefined {
  *       for (const num of arr1) {
  *         if (arr2.indexOf(num) !== -1) {
  *           return num;
@@ -354,15 +354,12 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @param [options] - Configuration options for the BST, including comparator.
    */
   constructor(
-    keysNodesEntriesOrRaws: Iterable<
-      K | BSTNode | [K | null | undefined, V | undefined] | null | undefined | R
-    > = [],
+    keysNodesEntriesOrRaws: Iterable<K | BSTNode | [K | null | undefined, V | undefined] | null | undefined | R> = [],
     options?: BSTOptions<K, V, R>
   ) {
     super([], options);
 
     if (options) {
-
       // Use the 'in' operator to check if the field is present
       if ('comparator' in options && options.comparator !== undefined) {
         this._comparator = options.comparator;
@@ -376,7 +373,6 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     if (keysNodesEntriesOrRaws) this.addMany(keysNodesEntriesOrRaws);
   }
 
-
   protected override _root?: BSTNode<K, V> = undefined;
 
   /**
@@ -389,33 +385,6 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     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.
-   */
-  protected _createDefaultComparator(): Comparator<K> {
-    return (a: K, b: K): number => {
-      debugger
-      // If both keys are comparable (primitive types), use direct comparison
-      if (isComparable(a) && isComparable(b)) {
-        if (a > b) return 1;
-        if (a < b) return -1;
-        return 0;
-      }
-
-      // If keys are objects and no comparator is provided, throw an error
-      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!`
-        );
-      }
-
-      // Default: keys are equal (fallback case)
-      return 0;
-    };
-  }
-
   /**
    * The comparator function used to determine the order of keys in the tree.
 
@@ -423,7 +392,6 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    */
   protected _comparator: Comparator<K>;
 
-
   /**
    * Gets the comparator function used by the tree.
    * @remarks Time O(1)
@@ -485,6 +453,16 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return isComparable(key);
   }
 
+  override dfs(): (K | undefined)[];
+
+  override dfs<C extends NodeCallback<BSTNode<K, V>>>(
+    callback: C,
+    pattern?: DFSOrderPattern,
+    onlyOne?: boolean,
+    startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
   /**
    * Performs a Depth-First Search (DFS) traversal.
    * @remarks Time O(N), visits every node. Space O(log N) for the call/explicit stack. O(N) worst-case.
@@ -507,6 +485,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return super.dfs(callback, pattern, onlyOne, startNode, iterationType);
   }
 
+  override bfs(): (K | undefined)[];
+  override bfs<C extends NodeCallback<BSTNode<K, V>>>(
+    callback: C,
+    startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
   /**
    * Performs a Breadth-First Search (BFS) or Level-Order traversal.
    * @remarks Time O(N), visits every node. Space O(N) in the worst case for the queue.
@@ -525,6 +510,14 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return super.bfs(callback, startNode, iterationType, false);
   }
 
+  override listLevels(): (K | undefined)[][];
+
+  override listLevels<C extends NodeCallback<BSTNode<K, V>>>(
+    callback: C,
+    startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[][];
+
   /**
    * Returns a 2D array of nodes, grouped by level.
    * @remarks Time O(N), visits every node. Space O(N) for the result array and the queue/stack.
@@ -566,6 +559,33 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return this.getNodes(keyNodeEntryOrPredicate, true, startNode, iterationType)[0] ?? undefined;
   }
 
+  override search(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+      | Range<K>,
+    onlyOne?: boolean
+  ): (K | undefined)[];
+
+  override search<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+      | Range<K>,
+    onlyOne: boolean,
+    callback: C,
+    startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
   /**
    * Searches the tree for nodes matching a predicate, key, or range.
    * @remarks This is an optimized search for a BST. If searching by key or range, it prunes branches.
@@ -618,8 +638,8 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       if (isRange) {
         // Range search: Only go left if the current key is >= the lower bound
         const range = keyNodeEntryOrPredicate as Range<K>;
-        const leftS =  range.low;
-        const leftI =  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)) {
@@ -636,8 +656,8 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       if (isRange) {
         // Range search: Only go right if current key <= upper bound
         const range = keyNodeEntryOrPredicate as Range<K>;
-        const rightS =  range.high;
-        const rightI =  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)) {
@@ -662,6 +682,15 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     );
   }
 
+  rangeSearch(range: Range<K> | [K, K]): (K | undefined)[];
+
+  rangeSearch<C extends NodeCallback<BSTNode<K, V>>>(
+    range: Range<K> | [K, K],
+    callback: C,
+    startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
   /**
    * Performs an optimized search for nodes within a given key range.
    * @remarks Time O(H + M), where H is tree height and M is the number of matches.
@@ -839,16 +868,27 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
   }
 
   /**
-   * 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.
+   * Returns the first key with a value >= target.
+   * Equivalent to Java TreeMap.ceiling.
+   * Time Complexity: O(log n) average, O(h) worst case.
    * 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(
+  ceiling(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+  ): K | undefined;
+
+  /**
+   * Returns the first node with a key >= target and applies callback.
+   * Time Complexity: O(log n) average, O(h) worst case.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   */
+  ceiling<C extends NodeCallback<BSTNode<K, V>>>(
     keyNodeEntryOrPredicate:
       | K
       | BSTNode<K, V>
@@ -856,22 +896,64 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       | null
       | undefined
       | NodePredicate<BSTNode<K, V>>,
-    iterationType: IterationType = this.iterationType
-  ): BSTNode<K, V> | undefined {
-    return this._bound(keyNodeEntryOrPredicate, true, iterationType);
+    callback: C,
+    iterationType?: IterationType
+  ): ReturnType<C>;
+
+  ceiling<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    iterationType?: IterationType
+  ): K | undefined | ReturnType<C> {
+    let actualCallback: C | undefined = undefined;
+    let actualIterationType: IterationType = 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) : undefined;
   }
 
   /**
-   * 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.
+   * Returns the first key with a value > target.
+   * Equivalent to Java TreeMap.higher.
+   * Time Complexity: O(log n) average, O(h) worst case.
    * 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(
+  higher(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+  ): K | undefined;
+
+  /**
+   * Returns the first node with a key > target and applies callback.
+   * Time Complexity: O(log n) average, O(h) worst case.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   */
+  higher<C extends NodeCallback<BSTNode<K, V>>>(
     keyNodeEntryOrPredicate:
       | K
       | BSTNode<K, V>
@@ -879,11 +961,261 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       | null
       | undefined
       | NodePredicate<BSTNode<K, V>>,
-    iterationType: IterationType = this.iterationType
-  ): BSTNode<K, V> | undefined {
-    return this._bound(keyNodeEntryOrPredicate, false, iterationType);
+    callback: C,
+    iterationType?: IterationType
+  ): ReturnType<C>;
+
+  higher<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    iterationType?: IterationType
+  ): K | undefined | ReturnType<C> {
+    let actualCallback: C | undefined = undefined;
+    let actualIterationType: IterationType = 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) : undefined;
+  }
+
+  /**
+   * Returns the first key with a value <= target.
+   * Equivalent to Java TreeMap.floor.
+   * Time Complexity: O(log n) average, O(h) worst case.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   */
+  floor(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+  ): K | undefined;
+
+  /**
+   * Returns the first node with a key <= target and applies callback.
+   * Time Complexity: O(log n) average, O(h) worst case.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   */
+  floor<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    callback: C,
+    iterationType?: IterationType
+  ): ReturnType<C>;
+
+  floor<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    iterationType?: IterationType
+  ): K | undefined | ReturnType<C> {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === undefined) {
+      if (typeof callback === 'string' || !callback) {
+        return undefined;
+      }
+      return undefined;
+    }
+
+    let actualCallback: C | undefined = undefined;
+    let actualIterationType: IterationType = 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) : undefined;
+    }
+
+    let targetKey: K | undefined;
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === undefined) {
+        if (typeof callback === 'string' || !callback) {
+          return undefined;
+        }
+        return undefined;
+      }
+      targetKey = key;
+    } else {
+      targetKey = keyNodeEntryOrPredicate;
+    }
+
+    if (targetKey !== undefined) {
+      const node = this._floorByKey(targetKey, actualIterationType);
+
+      if (!actualCallback) {
+        return node?.key;
+      }
+
+      return node ? actualCallback(node) : undefined;
+    }
+
+    if (typeof callback === 'string' || !callback) {
+      return undefined;
+    }
+    return undefined;
   }
 
+  /**
+   * Returns the first key with a value < target.
+   * Equivalent to Java TreeMap.lower.
+   * Time Complexity: O(log n) average, O(h) worst case.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   */
+  lower(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+  ): K | undefined;
+
+  /**
+   * Returns the first node with a key < target and applies callback.
+   * Time Complexity: O(log n) average, O(h) worst case.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   */
+  lower<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    callback: C,
+    iterationType?: IterationType
+  ): ReturnType<C>;
+
+  lower<C extends NodeCallback<BSTNode<K, V>>>(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    callback?: C | IterationType,
+    iterationType?: IterationType
+  ): K | undefined | ReturnType<C> {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === undefined) {
+      if (typeof callback === 'string' || !callback) {
+        return undefined;
+      }
+      return undefined;
+    }
+
+    let actualCallback: C | undefined = undefined;
+    let actualIterationType: IterationType = 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) : undefined;
+    }
+
+    let targetKey: K | undefined;
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === undefined) {
+        if (typeof callback === 'string' || !callback) {
+          return undefined;
+        }
+        return undefined;
+      }
+      targetKey = key;
+    } else {
+      targetKey = keyNodeEntryOrPredicate;
+    }
+
+    if (targetKey !== undefined) {
+      const node = this._lowerByKey(targetKey, actualIterationType);
+
+      if (!actualCallback) {
+        return node?.key;
+      }
+
+      return node ? actualCallback(node) : undefined;
+    }
+
+    if (typeof callback === 'string' || !callback) {
+      return undefined;
+    }
+    return undefined;
+  }
+
+  lesserOrGreaterTraverse(): (K | undefined)[];
+
+  lesserOrGreaterTraverse<C extends NodeCallback<BSTNode<K, V>>>(
+    callback: C,
+    lesserOrGreater?: number,
+    targetNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
   /**
    * 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).
@@ -1090,17 +1422,10 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     onlyOne = false,
     startNode: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined = this._root,
     iterationType: IterationType = this.iterationType
-  ):  BinaryTreeDeleteResult<BSTNode<K, V>>[] {
+  ): BinaryTreeDeleteResult<BSTNode<K, V>>[] {
+    const toDelete = this.search(keyNodeEntryOrPredicate, onlyOne, node => node, startNode, iterationType);
 
-    const toDelete = this.search (
-      keyNodeEntryOrPredicate,
-      onlyOne,
-      (node) => node,
-      startNode,
-      iterationType
-    );
-
-    let results : BinaryTreeDeleteResult<BSTNode<K, V>>[] = [];
+    let results: BinaryTreeDeleteResult<BSTNode<K, V>>[] = [];
     for (const node of toDelete) {
       const deleteInfo = this.delete(node);
       results = results.concat(deleteInfo);
@@ -1109,6 +1434,268 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     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.
+   */
+  protected _createDefaultComparator(): Comparator<K> {
+    return (a: K, b: K): number => {
+      debugger;
+      // If both keys are comparable (primitive types), use direct comparison
+      if (isComparable(a) && isComparable(b)) {
+        if (a > b) return 1;
+        if (a < b) return -1;
+        return 0;
+      }
+
+      // If keys are objects and no comparator is provided, throw an error
+      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!`
+        );
+      }
+
+      // Default: keys are equal (fallback case)
+      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.
+   */
+  protected _floorByKey(key: K, iterationType: IterationType): BSTNode<K, V> | undefined {
+    if (iterationType === 'RECURSIVE') {
+      // Recursive binary search implementation
+      const dfs = (cur: BSTNode<K, V> | null | undefined): BSTNode<K, V> | undefined => {
+        if (!this.isRealNode(cur)) return undefined;
+
+        const cmp = this.comparator(cur.key!, key);
+
+        if (cmp <= 0) {
+          // Current node satisfies the floor condition (cur.key <= target).
+          // Try to find a larger candidate in the right subtree.
+          const rightResult = dfs(cur.right);
+          return rightResult ?? cur;
+        } else {
+          // Current node is too large, move left to find smaller keys.
+          return dfs(cur.left);
+        }
+      };
+
+      return dfs(this.root);
+    } else {
+      // Iterative binary search implementation
+      let current: BSTNode<K, V> | undefined = this.root;
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      while (this.isRealNode(current)) {
+        const cmp = this.comparator(current.key!, key);
+
+        if (cmp <= 0) {
+          // Current node is a candidate. Save it and try right subtree for a larger key.
+          result = current;
+          current = current.right ?? undefined;
+        } else {
+          // Current node is too large, move left.
+          current = current.left ?? undefined;
+        }
+      }
+
+      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.
+   */
+  protected _floorByPredicate(
+    predicate: NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType
+  ): BSTNode<K, V> | undefined {
+    if (iterationType === 'RECURSIVE') {
+      // Recursive in-order traversal
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      const dfs = (cur: BSTNode<K, V> | null | undefined): void => {
+        if (!this.isRealNode(cur)) return;
+
+        // In-order: process left subtree first
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+
+        // Check current node
+        if (predicate(cur)) {
+          result = cur;
+        }
+
+        // Process right subtree
+        if (this.isRealNode(cur.right)) dfs(cur.right);
+      };
+
+      dfs(this.root);
+      return result;
+    } else {
+      // Iterative in-order traversal using explicit stack
+      const stack: (BSTNode<K, V> | null | undefined)[] = [];
+      let current: BSTNode<K, V> | null | undefined = this.root;
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      while (stack.length > 0 || this.isRealNode(current)) {
+        if (this.isRealNode(current)) {
+          // Go to the leftmost node
+          stack.push(current);
+          current = current.left;
+        } else {
+          // Pop from stack and process
+          const node = stack.pop();
+          if (!this.isRealNode(node)) break;
+
+          // Check if current node satisfies predicate
+          if (predicate(node)) {
+            result = node;
+          }
+
+          // Visit right subtree
+          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.
+   */
+  protected _lowerByKey(key: K, iterationType: IterationType): BSTNode<K, V> | undefined {
+    if (iterationType === 'RECURSIVE') {
+      // Recursive binary search implementation
+      const dfs = (cur: BSTNode<K, V> | null | undefined): BSTNode<K, V> | undefined => {
+        if (!this.isRealNode(cur)) return undefined;
+
+        const cmp = this.comparator(cur.key!, key);
+
+        if (cmp < 0) {
+          // Current node satisfies the lower condition (cur.key < target).
+          // Try to find a larger candidate in the right subtree.
+          const rightResult = dfs(cur.right);
+          return rightResult ?? cur;
+        } else {
+          // Current node is too large or equal, move left to find smaller keys.
+          return dfs(cur.left);
+        }
+      };
+
+      return dfs(this.root);
+    } else {
+      // Iterative binary search implementation
+      let current: BSTNode<K, V> | undefined = this.root;
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      while (this.isRealNode(current)) {
+        const cmp = this.comparator(current.key!, key);
+
+        if (cmp < 0) {
+          // Current node is a candidate. Save it and try right subtree for a larger key.
+          result = current;
+          current = current.right ?? undefined;
+        } else {
+          // Current node is too large or equal, move left.
+          current = current.left ?? undefined;
+        }
+      }
+
+      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.
+   */
+  protected _lowerByPredicate(
+    predicate: NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType
+  ): BSTNode<K, V> | undefined {
+    if (iterationType === 'RECURSIVE') {
+      // Recursive in-order traversal
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      const dfs = (cur: BSTNode<K, V> | null | undefined): void => {
+        if (!this.isRealNode(cur)) return;
+
+        // In-order: process left subtree first
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+
+        // Check current node
+        if (predicate(cur)) {
+          result = cur;
+        }
+
+        // Process right subtree
+        if (this.isRealNode(cur.right)) dfs(cur.right);
+      };
+
+      dfs(this.root);
+      return result;
+    } else {
+      // Iterative in-order traversal using explicit stack
+      const stack: (BSTNode<K, V> | null | undefined)[] = [];
+      let current: BSTNode<K, V> | null | undefined = this.root;
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      while (stack.length > 0 || this.isRealNode(current)) {
+        if (this.isRealNode(current)) {
+          // Go to the leftmost node
+          stack.push(current);
+          current = current.left;
+        } else {
+          // Pop from stack and process
+          const node = stack.pop();
+          if (!this.isRealNode(node)) break;
+
+          // Check if current node satisfies predicate
+          if (predicate(node)) {
+            result = node;
+          }
+
+          // Visit right subtree
+          current = node.right;
+        }
+      }
+
+      return result;
+    }
+  }
 
   /**
    * (Protected) Core bound search implementation supporting all parameter types.
@@ -1330,7 +1917,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
   protected override _snapshotOptions<TK = K, TV = V, TR = R>(): BSTOptions<TK, TV, TR> {
     return {
       ...super._snapshotOptions<TK, TV, TR>(),
-      comparator: this._comparator as unknown as BSTOptions<TK, TV, TR>['comparator'],
+      comparator: this._comparator as unknown as BSTOptions<TK, TV, TR>['comparator']
     };
   }