max-priority-queue-typed 2.2.2 → 2.2.4

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

@@ -7,7 +7,6 @@
  */
 import { BST } from './bst';
 import type { AVLTreeOptions, BinaryTreeDeleteResult, BinaryTreeOptions, BSTNOptKeyOrNode, EntryCallback, FamilyPosition, IterationType, RBTNColor } from '../../types';
-import { BSTOptions } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 /**
  * Represents a Node in an AVL (Adelson-Velsky and Landis) Tree.
@@ -128,8 +127,102 @@ export declare class AVLTreeNode<K = any, V = any> {
  * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
  *
  * @example
+ * // basic AVLTree creation and add operation
+ *  // Create a simple AVLTree with initial values
+ *     const tree = new AVLTree([5, 2, 8, 1, 9]);
+ *
+ *     tree.print();
+ *     //   _2___
+ *     //  /     \
+ *     //  1    _8_
+ *     //      /   \
+ *     //      5   9
+ *
+ *     // Verify the tree maintains sorted order
+ *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
+ *
+ *     // Check size
+ *     console.log(tree.size); // 5;
+ *
+ *     // Add a new element
+ *     tree.add(3);
+ *     console.log(tree.size); // 6;
+ *     console.log([...tree.keys()]); // [1, 2, 3, 5, 8, 9];
+ * @example
+ * // AVLTree has and get operations
+ *  const tree = new AVLTree<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     // Check if element exists
+ *     console.log(tree.has(6)); // true;
+ *     console.log(tree.has(99)); // false;
+ *
+ *     // Get node by key
+ *     const node = tree.getNode(6);
+ *     console.log(node?.key); // 6;
+ *
+ *     // Verify tree is balanced
+ *     console.log(tree.isAVLBalanced()); // true;
+ * @example
+ * // AVLTree delete and balance verification
+ *  const tree = new AVLTree([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     // Delete an element
+ *     tree.delete(10);
+ *     console.log(tree.has(10)); // false;
+ *
+ *     // Tree should remain balanced after deletion
+ *     console.log(tree.isAVLBalanced()); // true;
+ *
+ *     // Size decreased
+ *     console.log(tree.size); // 15;
+ *
+ *     // Remaining elements are still sorted
+ *     const keys = [...tree.keys()];
+ *     console.log(keys); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16];
+ * @example
+ * // AVLTree for university ranking system with strict balance
+ *  interface University {
+ *       name: string;
+ *       rank: number;
+ *       students: number;
+ *     }
+ *
+ *     // AVLTree provides highest search efficiency with strict balance
+ *     // (every node's left/right subtrees differ by at most 1 in height)
+ *     const universityTree = new AVLTree<number, University>([
+ *       [1, { name: 'MIT', rank: 1, students: 1200 }],
+ *       [5, { name: 'Stanford', rank: 5, students: 1800 }],
+ *       [3, { name: 'Harvard', rank: 3, students: 2300 }],
+ *       [2, { name: 'Caltech', rank: 2, students: 400 }],
+ *       [4, { name: 'CMU', rank: 4, students: 1500 }]
+ *     ]);
+ *
+ *     // Quick lookup by rank
+ *     const mit = universityTree.get(1);
+ *     console.log(mit?.name); // 'MIT';
+ *
+ *     const cmulevel = universityTree.getHeight(4);
+ *     console.log(typeof cmulevel); // 'number';
+ *
+ *     // Tree maintains strict balance during insertions and deletions
+ *     console.log(universityTree.isAVLBalanced()); // true;
+ *
+ *     // Add more universities
+ *     universityTree.add(6, { name: 'Oxford', rank: 6, students: 2000 });
+ *     console.log(universityTree.isAVLBalanced()); // true;
+ *
+ *     // Delete and verify balance is maintained
+ *     universityTree.delete(2);
+ *     console.log(universityTree.has(2)); // false;
+ *     console.log(universityTree.isAVLBalanced()); // true;
+ *
+ *     // Get all remaining universities in rank order
+ *     const remainingRanks = [...universityTree.keys()];
+ *     console.log(remainingRanks); // [1, 3, 4, 5, 6];
+ *     console.log(universityTree.size); // 5;
+ * @example
  * // Find elements in a range
- *     // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
+ *  // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
  *     type Datum = { timestamp: Date; temperature: number };
  *     // Fixed dataset of CPU temperature readings
  *     const cpuData: Datum[] = [
@@ -190,7 +283,7 @@ export declare class AVLTreeNode<K = any, V = any> {
  *  //      { minute: 13, temperature: 60.2 },
  *  //      { minute: 14, temperature: 59.8 },
  *  //      { minute: 15, temperature: 58.6 }
- *  //    ]
+ *  //    ];
  */
 export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements IBinaryTree<K, V, R> {
     /**
@@ -265,7 +358,7 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
      * @param [options] - Options for the new tree.
      * @returns A new, empty tree.
      */
-    protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<BSTOptions<TK, TV, TR>>): this;
+    protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<AVLTreeOptions<TK, TV, TR>>): this;
     /**
      * (Protected) Creates a new instance of the same AVLTree constructor, potentially with different generic types.
      * @remarks Time O(N log N) (from constructor) due to processing the iterable.
@@ -275,7 +368,7 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
      * @param [options] - Options for the new tree.
      * @returns A new AVLTree.
      */
-    protected _createLike<TK = K, TV = V, TR = R>(iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<BSTOptions<TK, TV, TR>>): AVLTree<TK, TV, TR>;
+    protected _createLike<TK = K, TV = V, TR = R>(iter?: Iterable<TK | AVLTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<AVLTreeOptions<TK, TV, TR>>): AVLTree<TK, TV, TR>;
     /**
      * (Protected) Swaps properties of two nodes, including height.
      * @remarks Time O(H) (due to `ensureNode`), but O(1) if nodes are passed directly.

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

@@ -125,8 +125,86 @@ export declare class BinaryTreeNode<K = any, V = any> {
  * 5. Leaf Nodes: Nodes without children are leaves.
  *
  * @example
+ * // basic BinaryTree creation and insertion
+ *  // Create a BinaryTree with entries
+ *     const entries: [number, string][] = [
+ *       [6, 'six'],
+ *       [1, 'one'],
+ *       [2, 'two'],
+ *       [7, 'seven'],
+ *       [5, 'five'],
+ *       [3, 'three'],
+ *       [4, 'four'],
+ *       [9, 'nine'],
+ *       [8, 'eight']
+ *     ];
+ *
+ *     const tree = new BinaryTree(entries);
+ *
+ *     // Verify size
+ *     console.log(tree.size); // 9;
+ *
+ *     // Add new element
+ *     tree.add(10, 'ten');
+ *     console.log(tree.size); // 10;
+ * @example
+ * // BinaryTree get and has operations
+ *  const tree = new BinaryTree(
+ *       [
+ *         [5, 'five'],
+ *         [3, 'three'],
+ *         [7, 'seven'],
+ *         [1, 'one'],
+ *         [4, 'four'],
+ *         [6, 'six'],
+ *         [8, 'eight']
+ *       ],
+ *       { isMapMode: false }
+ *     );
+ *
+ *     // Check if key exists
+ *     console.log(tree.has(5)); // true;
+ *     console.log(tree.has(10)); // false;
+ *
+ *     // Get value by key
+ *     console.log(tree.get(3)); // 'three';
+ *     console.log(tree.get(7)); // 'seven';
+ *     console.log(tree.get(100)); // undefined;
+ *
+ *     // Get node structure
+ *     const node = tree.getNode(5);
+ *     console.log(node?.key); // 5;
+ *     console.log(node?.value); // 'five';
+ * @example
+ * // BinaryTree level-order traversal
+ *  const tree = new BinaryTree([
+ *       [1, 'one'],
+ *       [2, 'two'],
+ *       [3, 'three'],
+ *       [4, 'four'],
+ *       [5, 'five'],
+ *       [6, 'six'],
+ *       [7, 'seven']
+ *     ]);
+ *
+ *     // Binary tree maintains level-order insertion
+ *     // Complete binary tree structure
+ *     console.log(tree.size); // 7;
+ *
+ *     // Verify all keys are present
+ *     console.log(tree.has(1)); // true;
+ *     console.log(tree.has(4)); // true;
+ *     console.log(tree.has(7)); // true;
+ *
+ *     // Iterate through tree
+ *     const keys: number[] = [];
+ *     for (const [key] of tree) {
+ *       keys.push(key);
+ *     }
+ *     console.log(keys.length); // 7;
+ * @example
  * // determine loan approval using a decision tree
- *     // Decision tree structure
+ *  // Decision tree structure
  *     const loanDecisionTree = new BinaryTree<string>(
  *       ['stableIncome', 'goodCredit', 'Rejected', 'Approved', 'Rejected'],
  *       { isDuplicate: true }
@@ -148,19 +226,19 @@ export declare class BinaryTreeNode<K = any, V = any> {
  *     }
  *
  *     // Test case 1: Stable income and good credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: true })); // 'Approved'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: true })); // 'Approved';
  *
  *     // Test case 2: Stable income but poor credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: false })); // 'Rejected'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: false })); // 'Rejected';
  *
  *     // Test case 3: No stable income
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: true })); // 'Rejected'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: true })); // 'Rejected';
  *
  *     // Test case 4: No stable income and poor credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: false })); // 'Rejected'
+ *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: false })); // 'Rejected';
  * @example
  * // evaluate the arithmetic expression represented by the binary tree
- *     const expressionTree = new BinaryTree<number | string>(['+', 3, '*', null, null, 5, '-', null, null, 2, 8]);
+ *  const expressionTree = new BinaryTree<number | string>(['+', 3, '*', null, null, 5, '-', null, null, 2, 8]);
  *
  *     function evaluate(node?: BinaryTreeNode<number | string> | null): number {
  *       if (!node) return 0;
@@ -185,7 +263,7 @@ export declare class BinaryTreeNode<K = any, V = any> {
  *       }
  *     }
  *
- *     console.log(evaluate(expressionTree.root)); // -27
+ *     console.log(evaluate(expressionTree.root)); // -27;
  */
 export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntryBase<K, V | undefined> implements IBinaryTree<K, V, R> {
     iterationType: IterationType;
@@ -360,6 +438,15 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
      * @returns True if the addition was successful, false otherwise.
      */
     add(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
+    /**
+     * Adds or updates a new node to the tree.
+     * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). This implementation adds the node at the first available position in a level-order (BFS) traversal. This is NOT a Binary Search Tree insertion. Time O(N), where N is the number of nodes. It must traverse level-by-level to find an empty slot. Space O(N) in the worst case for the BFS queue (e.g., a full last level).
+     *
+     * @param keyNodeOrEntry - The key, node, or entry to add or update.
+     * @param [value] - The value, if providing just a key.
+     * @returns True if the addition was successful, false otherwise.
+     */
+    set(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
      * Adds multiple items to the tree.
      * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
@@ -369,6 +456,15 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
      * @returns An array of booleans indicating the success of each individual `add` operation.
      */
     addMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): boolean[];
+    /**
+     * Adds or updates multiple items to the tree.
+     * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
+     *
+     * @param keysNodesEntriesOrRaws - An iterable of items to add or update.
+     * @param [values] - An optional parallel iterable of values.
+     * @returns An array of booleans indicating the success of each individual `add` operation.
+     */
+    setMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): boolean[];
     /**
      * Merges another tree into this one by adding all its nodes.
      * @remarks Time O(N * M), same as `addMany`, where N is the size of `anotherTree` and M is the size of this tree. Space O(M) (from `add`).

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeOptions, BSTNOptKeyOrNode, BSTOptions, BTNRep, Comparable, Comparator, CP, DFSOrderPattern, EntryCallback, FamilyPosition, IterationType, NodeCallback, NodePredicate, OptNode, RBTNColor } from '../../types';
+import type { BinaryTreeDeleteResult, BSTNOptKeyOrNode, BSTOptions, BTNRep, Comparator, CP, DFSOrderPattern, EntryCallback, FamilyPosition, IterationType, NodeCallback, NodePredicate, OptNode, RBTNColor } from '../../types';
 import { BinaryTree } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Range } from '../../common';
@@ -126,8 +126,57 @@ export declare 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']
  *     ]);
@@ -147,18 +196,58 @@ export declare 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 => {
@@ -178,9 +267,9 @@ export declare 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 declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implements IBinaryTree<K, V, R> {
     /**
@@ -190,7 +279,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to add.
      * @param [options] - Configuration options for the BST, including comparator.
      */
-    constructor(keysNodesEntriesOrRaws?: Iterable<K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: BSTOptions<K, V, R>);
+    constructor(keysNodesEntriesOrRaws?: Iterable<K | BSTNode | [K | null | undefined, V | undefined] | null | undefined | R>, options?: BSTOptions<K, V, R>);
     protected _root?: BSTNode<K, V>;
     /**
      * Gets the root node of the tree.
@@ -199,17 +288,16 @@ 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 _isReverse: boolean;
     /**
-     * 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;
+    protected _createDefaultComparator(): Comparator<K>;
     /**
-     * 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>;
     /**
@@ -219,14 +307,6 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @returns The comparator function.
      */
     get comparator(): Comparator<K>;
-    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;
     /**
      * (Protected) Creates a new BST node.
      * @remarks Time O(1), Space O(1)
@@ -355,6 +435,28 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @returns An array of booleans indicating the success of each individual `add` operation.
      */
     addMany(keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, BSTNode<K, V>>>, values?: Iterable<V | undefined>, isBalanceAdd?: boolean, iterationType?: IterationType): boolean[];
+    /**
+     * 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): BSTNode<K, V> | 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.
+     * 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): 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).
@@ -396,15 +498,76 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param [thisArg] - `this` context for the callback.
      * @returns A new, mapped BST.
      */
-    map<MK = K, MV = V, MR = any>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BinaryTreeOptions<MK, MV, MR>>, thisArg?: unknown): BST<MK, MV, MR>;
+    map<MK = K, MV = V, MR = any>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BSTOptions<MK, MV, MR>>, thisArg?: unknown): BST<MK, MV, MR>;
     /**
-     * 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;
+    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) 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;
+    /**
+     * (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;
+    /**
+     * (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;
     /**
      * (Protected) Creates a new, empty instance of the same BST constructor.
      * @remarks Time O(1)
@@ -450,7 +613,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
     protected _setRoot(v: OptNode<BSTNode<K, V>>): void;
     /**
      * (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.
@@ -464,5 +627,5 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param key - The key of the node to delete.
      * @returns True if the node was found and deleted, false otherwise.
      */
-    private _deleteByKey;
+    protected _deleteByKey(key: K): boolean;
 }