binary-tree-typed 2.5.0 → 2.5.2

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

@@ -254,6 +254,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<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>;
+    protected _enableOrderStatistic: boolean;
     /**
      * Gets the root node of the tree.
      * @remarks Time O(1)
@@ -307,7 +308,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param key - The key to validate.
      * @returns True if the key is valid, false otherwise.
      */
-    isValidKey(key: any): key is K;
+    isValidKey(key: unknown): key is K;
     /**
    * Depth-first search traversal
   
@@ -330,6 +331,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
     * @example
@@ -356,6 +405,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
     * @example
  * // Breadth-first traversal
  *  const bst = new BST<number>([5, 3, 7]);
@@ -383,6 +480,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
     * @example
  * // Level-order grouping
  *  const bst = new BST<number>([5, 3, 7, 1, 4]);
@@ -421,6 +566,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Get node object by key
    *  const bst = new BST<number, string>([[5, 'root'], [3, 'left'], [7, 'right']]);
@@ -443,6 +636,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
     * @example
  * // Search nodes by predicate
  *  const bst = new BST<number, string>([[1, 'a'], [2, 'b'], [3, 'c'], [4, 'd']]);
@@ -464,6 +705,30 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
     * @example
  * // Find all keys in a range
  *  const bst = new BST<number>([10, 20, 30, 40, 50]);
@@ -471,6 +736,69 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
    */
     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>[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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>[];
     /**
      * 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).
@@ -498,6 +826,78 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
      
      
      
@@ -533,6 +933,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Set multiple key-value pairs
    *  const bst = new BST<number, string>();
@@ -557,6 +1005,30 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Find the least key ≥ target
    *  const bst = new BST<number>([10, 20, 30, 40, 50]);
@@ -587,6 +1059,30 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Find the least key strictly > target
    *  const bst = new BST<number>([10, 20, 30, 40]);
@@ -616,6 +1112,30 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Find the greatest key ≤ target
    *  const bst = new BST<number>([10, 20, 30, 40, 50]);
@@ -646,6 +1166,30 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Find the greatest key strictly < target
    *  const bst = new BST<number>([10, 20, 30, 40]);
@@ -676,6 +1220,30 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Rebalance the tree
    *  const bst = new BST<number>();
@@ -701,6 +1269,30 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Check if tree is height-balanced
    *  const bst = new BST<number>([3, 1, 5, 2, 4]);
@@ -738,6 +1330,54 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      
      
      
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
       * @example
    * // Transform to new tree
    *  const bst = new BST<number, number>([[1, 10], [2, 20], [3, 30]]);
@@ -908,6 +1548,41 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      *
      * @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;
+    /**
+     * (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;
+    /**
+     * (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;
+    /**
+     * (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;
+    /**
+     * (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;
+    /**
+     * (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;
+    /**
+     * (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;
     protected _setRoot(v: OptNode<BSTNode<K, V>>): void;
     /**
      * (Protected) Compares two keys using the tree's comparator and reverse setting.