tree-multimap-typed 2.2.2 → 2.2.4

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

@@ -7,11 +7,10 @@
  */
 
 import type {
-  BinaryTreeOptions,
+  BinaryTreeDeleteResult,
   BSTNOptKeyOrNode,
   BSTOptions,
   BTNRep,
-  Comparable,
   Comparator,
   CP,
   DFSOrderPattern,
@@ -201,8 +200,57 @@ export class BSTNode<K = any, V = any> {
  * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
  *
  * @example
+ * // basic BST creation and add operation
+ *  // Create a simple BST with numeric keys
+ *     const bst = new BST<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     bst.print();
+ *     //         _______8__________
+ *     //        /                  \
+ *     //     ___4___          ____12_____
+ *     //    /       \        /           \
+ *     //   _2_     _6_     _10__       _14__
+ *     //  /   \   /   \   /     \     /     \
+ *     //  1   3   5   7   9    11    13    15__
+ *     //                                       \
+ *     //                                      16
+ *
+ *     // Verify size
+ *     console.log(bst.size); // 16;
+ *
+ *     // Add new elements
+ *     bst.add(17);
+ *     bst.add(0);
+ *     console.log(bst.size); // 18;
+ *
+ *     // Verify keys are searchable
+ *     console.log(bst.has(11)); // true;
+ *     console.log(bst.has(100)); // false;
+ * @example
+ * // BST delete and search after deletion
+ *  const bst = new BST<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     // Delete a leaf node
+ *     bst.delete(1);
+ *     console.log(bst.has(1)); // false;
+ *
+ *     // Delete a node with one child
+ *     bst.delete(2);
+ *     console.log(bst.has(2)); // false;
+ *
+ *     // Delete a node with two children
+ *     bst.delete(3);
+ *     console.log(bst.has(3)); // false;
+ *
+ *     // Size decreases with each deletion
+ *     console.log(bst.size); // 13;
+ *
+ *     // Other nodes remain searchable
+ *     console.log(bst.has(11)); // true;
+ *     console.log(bst.has(15)); // true;
+ * @example
  * // Merge 3 sorted datasets
- *     const dataset1 = new BST<number, string>([
+ *  const dataset1 = new BST<number, string>([
  *       [1, 'A'],
  *       [7, 'G']
  *     ]);
@@ -222,18 +270,58 @@ export class BSTNode<K = any, V = any> {
  *     merged.merge(dataset3);
  *
  *     // Verify merged dataset is in sorted order
- *     console.log([...merged.values()]); // ['A', 'B', 'C', 'D', 'E', 'F', 'G']
+ *     console.log([...merged.values()]); // ['A', 'B', 'C', 'D', 'E', 'F', 'G'];
  * @example
- * // Find elements in a range
- *     const bst = new BST<number>([10, 5, 15, 3, 7, 12, 18]);
- *     console.log(bst.search(new Range(5, 10))); // [5, 7, 10]
- *     console.log(bst.rangeSearch([4, 12], node => node.key.toString())); // ['5', '7', '10', '12']
- *     console.log(bst.search(new Range(4, 12, true, false))); // [5, 7, 10]
- *     console.log(bst.rangeSearch([15, 20])); // [15, 18]
- *     console.log(bst.search(new Range(15, 20, false))); // [18]
+ * // BST with custom objects for expression evaluation
+ *  interface Expression {
+ *       id: number;
+ *       operator: string;
+ *       precedence: number;
+ *     }
+ *
+ *     // BST efficiently stores and retrieves operators by precedence
+ *     const operatorTree = new BST<number, Expression>(
+ *       [
+ *         [1, { id: 1, operator: '+', precedence: 1 }],
+ *         [2, { id: 2, operator: '*', precedence: 2 }],
+ *         [3, { id: 3, operator: '/', precedence: 2 }],
+ *         [4, { id: 4, operator: '-', precedence: 1 }],
+ *         [5, { id: 5, operator: '^', precedence: 3 }]
+ *       ],
+ *       { isMapMode: false }
+ *     );
+ *
+ *     console.log(operatorTree.size); // 5;
+ *
+ *     // Quick lookup of operators
+ *     const mult = operatorTree.get(2);
+ *     console.log(mult?.operator); // '*';
+ *     console.log(mult?.precedence); // 2;
+ *
+ *     // Check if operator exists
+ *     console.log(operatorTree.has(5)); // true;
+ *     console.log(operatorTree.has(99)); // false;
+ *
+ *     // Retrieve operator by precedence level
+ *     const expNode = operatorTree.getNode(3);
+ *     console.log(expNode?.key); // 3;
+ *     console.log(expNode?.value?.precedence); // 2;
+ *
+ *     // Delete operator and verify
+ *     operatorTree.delete(1);
+ *     console.log(operatorTree.has(1)); // false;
+ *     console.log(operatorTree.size); // 4;
+ *
+ *     // Get tree height for optimization analysis
+ *     const treeHeight = operatorTree.getHeight();
+ *     console.log(treeHeight); // > 0;
+ *
+ *     // Remaining operators are still accessible
+ *     const remaining = operatorTree.get(2);
+ *     console.log(remaining); // defined;
  * @example
  * // Find lowest common ancestor
- *     const bst = new BST<number>([20, 10, 30, 5, 15, 25, 35, 3, 7, 12, 18]);
+ *  const bst = new BST<number>([20, 10, 30, 5, 15, 25, 35, 3, 7, 12, 18]);
  *
  *     // LCA helper function
  *     const findLCA = (num1: number, num2: number): number | undefined => {
@@ -253,9 +341,9 @@ export class BSTNode<K = any, V = any> {
  *     }
  *
  *     // Assertions
- *     console.log(findLCA(3, 10)); // 7
- *     console.log(findLCA(5, 35)); // 15
- *     console.log(findLCA(20, 30)); // 25
+ *     console.log(findLCA(3, 10)); // 7;
+ *     console.log(findLCA(5, 35)); // 15;
+ *     console.log(findLCA(20, 30)); // 25;
  */
 export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implements IBinaryTree<K, V, R> {
   /**
@@ -267,20 +355,28 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    */
   constructor(
     keysNodesEntriesOrRaws: Iterable<
-      K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R
+      K | BSTNode | [K | null | undefined, V | undefined] | null | undefined | R
     > = [],
     options?: BSTOptions<K, V, R>
   ) {
     super([], options);
 
     if (options) {
-      const { specifyComparable, isReverse } = options;
-      if (typeof specifyComparable === 'function') this._specifyComparable = specifyComparable;
-      if (isReverse !== undefined) this._isReverse = isReverse;
+
+      // Use the 'in' operator to check if the field is present
+      if ('comparator' in options && options.comparator !== undefined) {
+        this._comparator = options.comparator;
+      } else {
+        this._comparator = this._createDefaultComparator();
+      }
+    } else {
+      this._comparator = this._createDefaultComparator();
     }
+
     if (keysNodesEntriesOrRaws) this.addMany(keysNodesEntriesOrRaws);
   }
 
+
   protected override _root?: BSTNode<K, V> = undefined;
 
   /**
@@ -293,42 +389,40 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return this._root;
   }
 
-  protected _isReverse: boolean = false;
-
   /**
-   * Gets whether the tree's comparison logic is reversed.
-   * @remarks Time O(1)
-   *
-   * @returns True if the tree is reversed (e.g., a max-heap logic).
+   * (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.
    */
-  get isReverse(): boolean {
-    return this._isReverse;
+  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 default comparator function.
-   * @remarks Time O(1) (or O(C) if `specifyComparable` is used, C is complexity of that function).
+   * The comparator function used to determine the order of keys in the tree.
+
+   * @remarks Time O(1) Space O(1)
    */
-  protected _comparator: Comparator<K> = (a: K, b: K): number => {
-    if (isComparable(a) && isComparable(b)) {
-      if (a > b) return 1;
-      if (a < b) return -1;
-      return 0;
-    }
-    if (this._specifyComparable) {
-      const va = this._specifyComparable(a);
-      const vb = this._specifyComparable(b);
-      if (va > vb) return 1;
-      if (va < vb) return -1;
-      return 0;
-    }
-    if (typeof a === 'object' || typeof b === 'object') {
-      throw TypeError(
-        `When comparing object types, a custom specifyComparable must be defined in the constructor's options.`
-      );
-    }
-    return 0;
-  };
+  protected _comparator: Comparator<K>;
+
 
   /**
    * Gets the comparator function used by the tree.
@@ -340,18 +434,6 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return this._comparator;
   }
 
-  protected _specifyComparable?: (key: K) => Comparable;
-
-  /**
-   * Gets the function used to extract a comparable value from a complex key.
-   * @remarks Time O(1)
-   *
-   * @returns The key-to-comparable conversion function.
-   */
-  get specifyComparable(): ((key: K) => Comparable) | undefined {
-    return this._specifyComparable;
-  }
-
   /**
    * (Protected) Creates a new BST node.
    * @remarks Time O(1), Space O(1)
@@ -400,7 +482,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @returns True if the key is valid, false otherwise.
    */
   override isValidKey(key: any): key is K {
-    return isComparable(key, this._specifyComparable !== undefined);
+    return isComparable(key);
   }
 
   /**
@@ -536,8 +618,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 = this.isReverse ? range.high : range.low;
-        const leftI = this.isReverse ? range.includeHigh : 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)) {
@@ -554,8 +636,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 = this.isReverse ? range.low : range.high;
-        const rightI = this.isReverse ? range.includeLow : 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)) {
@@ -756,6 +838,52 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     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:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType = this.iterationType
+  ): BSTNode<K, V> | undefined {
+    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:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType = this.iterationType
+  ): BSTNode<K, V> | undefined {
+    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).
@@ -902,7 +1030,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    */
   override map<MK = K, MV = V, MR = any>(
     callback: EntryCallback<K, V | undefined, [MK, MV]>,
-    options?: Partial<BinaryTreeOptions<MK, MV, MR>>,
+    options?: Partial<BSTOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): BST<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);
@@ -915,34 +1043,245 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
   }
 
   /**
-   * Deletes the first node found that satisfies the predicate.
-   * @remarks Performs an in-order traversal. Time O(N) worst-case (O(log N) to find + O(log N) to delete). Space O(log N) for stack.
+   * Deletes nodes that match a key, node, entry, predicate, or range.
+   *
+   * @remarks
+   * Time Complexity: O(N) for search + O(M log N) for M deletions, where N is tree size.
+   * Space Complexity: O(M) for storing matched nodes and result map.
+   *
+   * @template K - The key type.
+   * @template V - The value type.
+   *
+   * @param keyNodeEntryOrPredicate - The search criteria. Can be one of:
+   *   - A key (type K): searches for exact key match using the comparator.
+   *   - A BSTNode: searches for the matching node in the tree.
+   *   - An entry tuple: searches for the key-value pair.
+   *   - A NodePredicate function: tests each node and returns true for matches.
+   *   - A Range object: searches for nodes whose keys fall within the specified range (inclusive/exclusive based on range settings).
+   *   - null or undefined: treated as no match, returns empty results.
    *
-   * @param predicate - A function to test each [key, value] pair.
-   * @returns True if a node was deleted, false otherwise.
+   * @param onlyOne - If true, stops the search after finding the first match and only deletes that one node.
+   *   If false (default), searches for and deletes all matching nodes.
+   *
+   * @param startNode - The node to start the search from. Can be:
+   *   - A key, node, or entry: the method resolves it to a node and searches from that subtree.
+   *   - null or undefined: defaults to the root, searching the entire tree.
+   *   - Default value: this._root (the tree's root).
+   *
+   * @param iterationType - Controls the internal traversal implementation:
+   *   - 'RECURSIVE': uses recursive function calls for traversal.
+   *   - 'ITERATIVE': uses explicit stack-based iteration.
+   *   - Default: this.iterationType (the tree's default iteration mode).
+   *
+   * @returns A Map<K, boolean> containing the deletion results:
+   *   - Key: the matched node's key.
+   *   - Value: true if the deletion succeeded, false if it failed (e.g., key not found during deletion phase).
+   *   - If no nodes match the search criteria, the returned map is empty.
    */
-  deleteWhere(predicate: (key: K, value: V | undefined, index: number, tree: this) => boolean): boolean {
-    const stack: Array<BSTNode<K, V> | null | undefined> = [];
-    let cur = this._root as BSTNode<K, V> | null | undefined;
-    let index = 0;
+  deleteWhere(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+      | Range<K>,
+    onlyOne = false,
+    startNode: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined = this._root,
+    iterationType: IterationType = this.iterationType
+  ):  BinaryTreeDeleteResult<BSTNode<K, V>>[] {
 
-    // In-order traversal to find the node
-    while (stack.length > 0 || cur !== undefined) {
-      while (cur !== undefined && cur !== null) {
-        stack.push(cur);
-        cur = cur.left as BSTNode<K, V> | null | undefined;
+    const toDelete = this.search (
+      keyNodeEntryOrPredicate,
+      onlyOne,
+      (node) => node,
+      startNode,
+      iterationType
+    );
+
+    let results : BinaryTreeDeleteResult<BSTNode<K, V>>[] = [];
+    for (const node of toDelete) {
+      const deleteInfo = this.delete(node);
+      results = results.concat(deleteInfo);
+    }
+
+    return results;
+  }
+
+
+  /**
+   * (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.
+   */
+  protected _bound(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    isLower: boolean,
+    iterationType: IterationType
+  ): BSTNode<K, V> | undefined {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === undefined) {
+      return undefined;
+    }
+
+    // Check if input is a predicate function first
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      return this._boundByPredicate(keyNodeEntryOrPredicate, iterationType);
+    }
+
+    // Resolve input to a comparable key
+    let targetKey: K | undefined;
+
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      // Input is a BSTNode - extract its key
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      // Input is a [key, value] entry - extract the key
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === undefined) {
+        return undefined;
       }
-      const node = stack.pop() as BSTNode<K, V> | undefined;
-      if (!node) break;
+      targetKey = key;
+    } else {
+      // Input is a raw key
+      targetKey = keyNodeEntryOrPredicate;
+    }
+
+    // Execute key-based search with binary search optimization
+    if (targetKey !== undefined) {
+      return this._boundByKey(targetKey, isLower, iterationType);
+    }
+
+    return undefined;
+  }
 
-      const key = node.key as K;
-      const val = node.value as V | undefined;
-      if (predicate(key, val, index++, this)) {
-        return this._deleteByKey(key); // Found, now delete
+  /**
+   * (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.
+   */
+  protected _boundByKey(key: K, isLower: boolean, 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);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+
+        if (condition) {
+          // Current node satisfies the bound condition.
+          // Try to find a closer (smaller key) candidate in the left subtree.
+          const leftResult = dfs(cur.left);
+          return leftResult ?? cur;
+        } else {
+          // Current node does not satisfy the condition.
+          // Move right to find larger keys.
+          return dfs(cur.right);
+        }
+      };
+
+      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);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+
+        if (condition) {
+          // Current node is a candidate. Save it and try left subtree for a closer match.
+          result = current;
+          current = current.left ?? undefined;
+        } else {
+          // Move right to find larger keys.
+          current = current.right ?? undefined;
+        }
       }
-      cur = node.right as BSTNode<K, V> | null | undefined;
+
+      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.
+   */
+  protected _boundByPredicate(
+    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 (result || !this.isRealNode(cur)) return;
+
+        // In-order: process left subtree first
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+
+        // Check current node
+        if (!result && predicate(cur)) {
+          result = cur;
+        }
+
+        // Process right subtree
+        if (!result && 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;
+
+      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)) {
+            return node;
+          }
+
+          // Visit right subtree
+          current = node.right;
+        }
+      }
+
+      return undefined;
     }
-    return false;
   }
 
   /**
@@ -991,8 +1330,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>(),
-      specifyComparable: this.specifyComparable as BSTOptions<TK, TV, TR>['specifyComparable'],
-      isReverse: this.isReverse as BSTOptions<TK, TV, TR>['isReverse']
+      comparator: this._comparator as unknown as BSTOptions<TK, TV, TR>['comparator'],
     };
   }
 
@@ -1026,14 +1364,14 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
 
   /**
    * (Protected) Compares two keys using the tree's comparator and reverse setting.
-   * @remarks Time O(1) (or O(C) if `specifyComparable` is used).
+   * @remarks Time O(1) Space O(1)
    *
    * @param a - The first key.
    * @param b - The second key.
    * @returns A number (1, -1, or 0) representing the comparison.
    */
   protected _compare(a: K, b: K) {
-    return this._isReverse ? -this._comparator(a, b) : this._comparator(a, b);
+    return this._comparator(a, b);
   }
 
   /**
@@ -1043,7 +1381,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @param key - The key of the node to delete.
    * @returns True if the node was found and deleted, false otherwise.
    */
-  private _deleteByKey(key: K): boolean {
+  protected _deleteByKey(key: K): boolean {
     let node = this._root as BSTNode<K, V> | undefined;
 
     // 1. Find the node