binary-tree-typed 2.5.1 → 2.5.3

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

@@ -7,7 +7,6 @@
  */
 
 import type {
-  BinaryTreeDeleteResult,
   BSTNOptKeyOrNode,
   BSTOptions,
   BTNRep,
@@ -26,7 +25,7 @@ import { BinaryTree } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Queue } from '../queue';
 import { isComparable } from '../../utils';
-import { ERR, Range } from '../../common';
+import { ERR, Range, raise } from '../../common';
 
 /**
  * Represents a Node in a Binary Search Tree.
@@ -345,6 +344,9 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       } else {
         this._comparator = this._createDefaultComparator();
       }
+      if (options.enableOrderStatistic) {
+        this._enableOrderStatistic = true;
+      }
     } else {
       this._comparator = this._createDefaultComparator();
     }
@@ -354,6 +356,8 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
 
   protected override _root?: BSTNode<K, V> = undefined;
 
+  protected _enableOrderStatistic: boolean = false;
+
   /**
    * Gets the root node of the tree.
    * @remarks Time O(1)
@@ -483,6 +487,20 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -579,6 +597,20 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -671,6 +703,20 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -690,7 +736,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
  * // Level-order grouping
  *  const bst = new BST<number>([5, 3, 7, 1, 4]);
  *     const levels = bst.listLevels(node => node.key);
- *     console.log(levels.length); // > 0;
+ *     console.log(levels); // toBeInstanceOf;
  *     console.log(levels[0].length); // 1; // root level has 1 node
  *     const allKeys = levels.flat().sort((a, b) => a - b);
  *     console.log(allKeys); // [1, 3, 4, 5, 7];
@@ -775,6 +821,20 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -898,6 +958,20 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1097,6 +1171,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1140,6 +1221,232 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return this.search(searchRange, false, callback, startNode, iterationType);
   }
 
+  // ─── Order-Statistic Methods ───────────────────────────
+
+  /**
+   * Returns the element at the k-th position in tree order (0-indexed).
+   * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+   * Tree order is defined by the comparator — ascending by default, but respects custom comparators (e.g. descending).
+   *
+   * @param k - The 0-based position in tree order (0 = first element).
+   * @returns The key at position k, or `undefined` if out of bounds.
+    * @example
+ * // Order-statistic on BST
+ *  const tree = new BST<number>([30, 10, 50, 20, 40], { enableOrderStatistic: true });
+ *       console.log(tree.getByRank(0)); // 10;
+ *       console.log(tree.getByRank(4)); // 50;
+ *       console.log(tree.getRank(30)); // 2;
+   */
+  getByRank(k: number): K | undefined;
+
+  /**
+   * Returns the element at the k-th position in tree order and applies a callback.
+   * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+   *
+   * @param k - The 0-based position in tree order (0 = first element).
+   * @param callback - Callback to apply to the found node.
+   * @param iterationType - Iteration strategy ('ITERATIVE' or 'RECURSIVE').
+   * @returns The callback result, or `undefined` if out of bounds.
+   */
+  getByRank<C extends NodeCallback<BSTNode<K, V>>>(
+    k: number,
+    callback: C,
+    iterationType?: IterationType
+  ): ReturnType<C> | undefined;
+
+  getByRank<C extends NodeCallback<BSTNode<K, V>>>(
+    k: number,
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    iterationType: IterationType = this.iterationType
+  ): K | undefined | ReturnType<C> | undefined {
+    if (!this._enableOrderStatistic) {
+      raise(Error, ERR.orderStatisticNotEnabled('getByRank'));
+    }
+    if (k < 0 || k >= this._size) 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;
+      }
+    }
+
+    const node = actualIterationType === 'RECURSIVE'
+      ? this._getByRankRecursive(this._root, k)
+      : this._getByRankIterative(this._root, k);
+
+    if (!node) return undefined;
+    return actualCallback ? actualCallback(node) : node.key;
+  }
+
+  /**
+   * Returns the 0-based rank of a key (number of elements that precede it in tree order).
+   * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+   * Tree order is defined by the comparator. When the key is not found, returns the insertion position.
+   *
+   * @param keyNodeEntryOrPredicate - The key, node, entry `[K, V]`, or predicate to find.
+   * @returns The rank (0-indexed), or -1 if the tree is empty or input is invalid.
+   */
+  getRank(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>
+  ): number;
+
+  /**
+   * Returns the 0-based rank (number of preceding elements in tree order) with explicit iteration type.
+   * @remarks Time O(log n), Space O(1) iterative / O(log n) recursive. Requires `enableOrderStatistic: true`.
+   *
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate to find.
+   * @param iterationType - Iteration strategy ('ITERATIVE' or 'RECURSIVE').
+   * @returns The rank (0-indexed), or -1 if the tree is empty or input is invalid.
+   */
+  getRank(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType
+  ): number;
+
+  getRank(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType = this.iterationType
+  ): number {
+    if (!this._enableOrderStatistic) {
+      raise(Error, ERR.orderStatisticNotEnabled('getRank'));
+    }
+    if (!this._root || this._size === 0) return -1;
+
+    let actualIterationType: IterationType = this.iterationType;
+    if (iterationType) actualIterationType = iterationType;
+
+    // Resolve key from input
+    let key: K | undefined;
+    if (typeof keyNodeEntryOrPredicate === 'function') {
+      // Predicate: find first matching node
+      const results = this.search(keyNodeEntryOrPredicate as NodePredicate<BSTNode<K, V>>, true);
+      if (results.length === 0 || results[0] === undefined) return -1;
+      key = results[0];
+    } else if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === undefined) {
+      return -1;
+    } else if (this.isNode(keyNodeEntryOrPredicate)) {
+      key = keyNodeEntryOrPredicate.key;
+    } else if (Array.isArray(keyNodeEntryOrPredicate)) {
+      key = keyNodeEntryOrPredicate[0] ?? undefined;
+      if (key === undefined || key === null) return -1;
+    } else {
+      key = keyNodeEntryOrPredicate as K;
+    }
+
+    if (key === undefined) return -1;
+
+    return actualIterationType === 'RECURSIVE'
+      ? this._getRankRecursive(this._root, key)
+      : this._getRankIterative(this._root, key);
+  }
+
+  /**
+   * Returns elements by position range in tree order (0-indexed, inclusive on both ends).
+   * @remarks Time O(log n + k), Space O(k), where k = end - start + 1. Requires `enableOrderStatistic: true`.
+   *
+   * @param start - Start position (inclusive, 0-indexed). Clamped to 0 if negative.
+   * @param end - End position (inclusive, 0-indexed). Clamped to size-1 if too large.
+   * @returns Array of keys in tree order within the specified range.
+   */
+  rangeByRank(start: number, end: number): (K | undefined)[];
+
+  /**
+   * Returns elements by position range in tree order with callback and optional iteration type.
+   * @remarks Time O(log n + k), Space O(k), where k = end - start + 1. Requires `enableOrderStatistic: true`.
+   *
+   * @param start - Start rank (inclusive, 0-indexed).
+   * @param end - End rank (inclusive, 0-indexed).
+   * @param callback - Callback to apply to each node in the range.
+   * @param iterationType - Iteration strategy ('ITERATIVE' or 'RECURSIVE').
+   * @returns Array of callback results for nodes in the rank range.
+   */
+  rangeByRank<C extends NodeCallback<BSTNode<K, V>>>(
+    start: number,
+    end: number,
+    callback: C,
+    iterationType?: IterationType
+  ): ReturnType<C>[];
+
+  rangeByRank<C extends NodeCallback<BSTNode<K, V>>>(
+    start: number,
+    end: number,
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    iterationType: IterationType = this.iterationType
+  ): (K | undefined)[] | ReturnType<C>[] {
+    if (!this._enableOrderStatistic) {
+      raise(Error, ERR.orderStatisticNotEnabled('rangeByRank'));
+    }
+    if (this._size === 0) return [];
+
+    // Clamp
+    const lo = Math.max(0, start);
+    const hi = Math.min(this._size - 1, end);
+    if (lo > hi) return [];
+
+    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 results: (K | undefined | ReturnType<C>)[] = [];
+    const count = hi - lo + 1;
+
+    // Find the lo-th node, then in-order traverse count nodes
+    const startNode = actualIterationType === 'RECURSIVE'
+      ? this._getByRankRecursive(this._root, lo)
+      : this._getByRankIterative(this._root, lo);
+
+    if (!startNode) return [];
+
+    // In-order traversal from startNode collecting count elements
+    let collected = 0;
+    const cb = actualCallback ?? this._DEFAULT_NODE_CALLBACK as C;
+
+    // Use higher() to iterate — it's already O(log n) amortized per step
+    let current: BSTNode<K, V> | undefined = startNode;
+    while (current && collected < count) {
+      results.push(cb(current));
+      collected++;
+      if (collected < count) {
+        // Find next in-order node
+        current = this._next(current);
+      }
+    }
+
+    return results as (K | undefined)[] | ReturnType<C>[];
+  }
+
   /**
    * Adds a new node to the BST based on key comparison.
    * @remarks Time O(log N), where H is tree height. O(N) worst-case (unbalanced tree), O(log N) average. Space O(1).
@@ -1214,6 +1521,27 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1253,6 +1581,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       this._setRoot(newNode);
       if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
       this._size++;
+      this._updateCount(newNode);
       return true;
     }
 
@@ -1269,6 +1598,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
           current.left = newNode;
           if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
           this._size++;
+          this._updateCountAlongPath(newNode);
           return true;
         }
         if (current.left !== null) current = current.left;
@@ -1278,6 +1608,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
           current.right = newNode;
           if (this._isMapMode && this.isRealNode(newNode)) this._store.set(newNode.key, newNode);
           this._size++;
+          this._updateCountAlongPath(newNode);
           return true;
         }
         if (current.right !== null) current = current.right;
@@ -1336,6 +1667,20 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1479,6 +1824,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1582,6 +1934,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1684,6 +2043,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1830,6 +2196,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2032,6 +2405,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2102,6 +2482,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2217,6 +2604,20 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2300,16 +2701,15 @@ 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>>[] {
+  ): boolean {
     const toDelete = this.search(keyNodeEntryOrPredicate, onlyOne, node => node, startNode, iterationType);
 
-    let results: BinaryTreeDeleteResult<BSTNode<K, V>>[] = [];
+    let deleted = false;
     for (const node of toDelete) {
-      const deleteInfo = this.delete(node);
-      results = results.concat(deleteInfo);
+      if (this.delete(node)) deleted = true;
     }
 
-    return results;
+    return deleted;
   }
 
   /**
@@ -2331,15 +2731,13 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       if (a instanceof Date && b instanceof Date) {
         const ta = a.getTime();
         const tb = b.getTime();
-        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError(ERR.invalidDate('BST'));
+        if (Number.isNaN(ta) || Number.isNaN(tb)) raise(TypeError, ERR.invalidDate('BST'));
         return ta > tb ? 1 : ta < tb ? -1 : 0;
       }
 
       // If keys are objects and no comparator is provided, throw an error
       if (typeof a === 'object' || typeof b === 'object') {
-        throw new TypeError(
-          ERR.comparatorRequired('BST')
-        );
+        raise(TypeError, ERR.comparatorRequired('BST'));
       }
 
       // Default: keys are equal (fallback case)
@@ -2804,7 +3202,8 @@ 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'],
+      enableOrderStatistic: this._enableOrderStatistic
     };
   }
 
@@ -2831,6 +3230,129 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    *
    * @param v - The node to set as root.
    */
+  /**
+   * (Protected) Recalculates the subtree count for a single node.
+   * @remarks Time O(1). Only active when enableOrderStatistic is true.
+   */
+  protected _updateCount(node: BSTNode<K, V>): void {
+    if (!this._enableOrderStatistic) return;
+    node._count = 1
+      + (this.isRealNode(node.left) ? node.left._count : 0)
+      + (this.isRealNode(node.right) ? node.right._count : 0);
+  }
+
+  /**
+   * (Protected) Updates subtree counts from a node up to the root.
+   * @remarks Time O(log n). Only active when enableOrderStatistic is true.
+   */
+  protected _updateCountAlongPath(node: OptNode<BSTNode<K, V>>): void {
+    if (!this._enableOrderStatistic) return;
+    let current = node;
+    while (current) {
+      this._updateCount(current);
+      current = current.parent as BSTNode<K, V> | undefined;
+    }
+  }
+
+  /**
+   * (Protected) Finds the node at position k in tree order (iterative).
+   * @remarks Time O(log n), Space O(1)
+   */
+  protected _getByRankIterative(node: OptNode<BSTNode<K, V>>, k: number): BSTNode<K, V> | undefined {
+    let current = node;
+    let remaining = k;
+    while (current) {
+      const leftCount = this.isRealNode(current.left) ? current.left._count : 0;
+      if (remaining < leftCount) {
+        current = current.left as BSTNode<K, V> | undefined;
+      } else if (remaining === leftCount) {
+        return current;
+      } else {
+        remaining = remaining - leftCount - 1;
+        current = current.right as BSTNode<K, V> | undefined;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * (Protected) Finds the node at position k in tree order (recursive).
+   * @remarks Time O(log n), Space O(log n) call stack
+   */
+  protected _getByRankRecursive(node: OptNode<BSTNode<K, V>>, k: number): BSTNode<K, V> | undefined {
+    if (!node) return undefined;
+    const leftCount = this.isRealNode(node.left) ? node.left._count : 0;
+    if (k < leftCount) return this._getByRankRecursive(node.left as BSTNode<K, V> | undefined, k);
+    if (k === leftCount) return node;
+    return this._getByRankRecursive(node.right as BSTNode<K, V> | undefined, k - leftCount - 1);
+  }
+
+  /**
+   * (Protected) Computes the rank of a key iteratively.
+   * @remarks Time O(log n), Space O(1)
+   */
+  protected _getRankIterative(node: OptNode<BSTNode<K, V>>, key: K): number {
+    let rank = 0;
+    let current = node;
+    while (this.isRealNode(current)) {
+      const cmp = this._compare(current.key, key);
+      if (cmp > 0) {
+        // key < current.key, go left
+        current = current.left as BSTNode<K, V> | undefined;
+      } else if (cmp < 0) {
+        // key > current.key
+        rank += (this.isRealNode(current.left) ? current.left._count : 0) + 1;
+        current = current.right as BSTNode<K, V> | undefined;
+      } else {
+        // Found
+        rank += this.isRealNode(current.left) ? current.left._count : 0;
+        return rank;
+      }
+    }
+    // Key not found, rank = insertion position
+    return rank;
+  }
+
+  /**
+   * (Protected) Computes the rank of a key recursively.
+   * @remarks Time O(log n), Space O(log n) call stack
+   */
+  protected _getRankRecursive(node: OptNode<BSTNode<K, V>>, key: K): number {
+    if (!node) return 0;
+    const cmp = this._compare(node.key, key);
+    if (cmp > 0) {
+      return this._getRankRecursive(node.left as BSTNode<K, V> | undefined, key);
+    } else if (cmp < 0) {
+      return (this.isRealNode(node.left) ? node.left._count : 0) + 1
+        + this._getRankRecursive(node.right as BSTNode<K, V> | undefined, key);
+    } else {
+      return this.isRealNode(node.left) ? node.left._count : 0;
+    }
+  }
+
+  /**
+   * (Protected) Finds the in-order successor of a node.
+   * @remarks Time O(log n), Space O(1)
+   */
+  protected _next(node: BSTNode<K, V>): BSTNode<K, V> | undefined {
+    if (this.isRealNode(node.right)) {
+      // Leftmost in right subtree
+      let current = node.right as BSTNode<K, V>;
+      while (this.isRealNode(current.left)) {
+        current = current.left as BSTNode<K, V>;
+      }
+      return current;
+    }
+    // Go up until we come from a left child
+    let current: BSTNode<K, V> | undefined = node;
+    let parent = current.parent as BSTNode<K, V> | undefined;
+    while (parent && current === parent.right) {
+      current = parent;
+      parent = parent.parent as BSTNode<K, V> | undefined;
+    }
+    return parent;
+  }
+
   protected override _setRoot(v: OptNode<BSTNode<K, V>>) {
     if (v) v.parent = undefined;
     this._root = v;
@@ -2887,25 +3409,32 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     };
 
     // 2. Perform deletion
+    let countUpdateStart: BSTNode<K, V> | undefined;
     if (node.left === undefined) {
       // Case 1: No left child
+      countUpdateStart = node.parent as BSTNode<K, V> | undefined;
       transplant(node, node.right as BSTNode<K, V> | undefined);
     } else if (node.right === undefined) {
       // Case 2: No right child
+      countUpdateStart = node.parent as BSTNode<K, V> | undefined;
       transplant(node, node.left as BSTNode<K, V> | undefined);
     } else {
       // Case 3: Two children
       const succ = minNode(node.right as BSTNode<K, V> | undefined)!; // Find successor
       if (succ.parent !== node) {
+        countUpdateStart = succ.parent as BSTNode<K, V> | undefined;
         transplant(succ, succ.right as BSTNode<K, V> | undefined);
         succ.right = node.right as BSTNode<K, V> | undefined;
         if (succ.right) (succ.right as BSTNode<K, V>).parent = succ;
+      } else {
+        countUpdateStart = succ;
       }
       transplant(node, succ);
       succ.left = node.left as BSTNode<K, V> | undefined;
       if (succ.left) (succ.left as BSTNode<K, V>).parent = succ;
     }
 
+    this._updateCountAlongPath(countUpdateStart);
     this._size = Math.max(0, this._size - 1);
     return true;
   }