binary-tree-typed 2.4.5 → 2.5.1

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

@@ -126,34 +126,6 @@ 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]);
- *
- *     // Keep the example output in source comments but avoid noisy test logs.
- *     await withMutedConsole(() => 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.set(17);
- *     bst.set(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]);
  *
@@ -335,11 +307,217 @@ 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
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Depth-first traversal
+ *  const bst = new BST<number>([5, 3, 7, 1, 4]);
+ *     const inOrder = bst.dfs(node => node.key, 'IN');
+ *     console.log(inOrder); // [1, 3, 4, 5, 7];
+   */
     dfs(): (K | undefined)[];
     dfs<C extends NodeCallback<BSTNode<K, V>>>(callback: C, pattern?: DFSOrderPattern, onlyOne?: boolean, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
+    /**
+   * BinaryTree level-order traversal
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Breadth-first traversal
+ *  const bst = new BST<number>([5, 3, 7]);
+ *     const result = bst.bfs(node => node.key);
+ *     console.log(result.length); // 3;
+   */
     bfs(): (K | undefined)[];
     bfs<C extends NodeCallback<BSTNode<K, V>>>(callback: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
+    /**
+   * Level-order grouping
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // 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[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];
+   */
     listLevels(): (K | undefined)[][];
     listLevels<C extends NodeCallback<BSTNode<K, V>>>(callback: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[][];
     /**
@@ -350,10 +528,178 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param [startNode=this._root] - The node to start the search from.
      * @param [iterationType=this.iterationType] - The traversal method.
      * @returns The first matching node, or undefined if not found.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Get node object by key
+   *  const bst = new BST<number, string>([[5, 'root'], [3, 'left'], [7, 'right']]);
+   *     const node = bst.getNode(3);
+   *     console.log(node?.key); // 3;
+   *     console.log(node?.value); // 'left';
      */
     getNode(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>, startNode?: BSTNOptKeyOrNode<K, BSTNode<K, V>>, iterationType?: IterationType): OptNode<BSTNode<K, V>>;
+    /**
+   * Search nodes by predicate
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Search nodes by predicate
+ *  const bst = new BST<number, string>([[1, 'a'], [2, 'b'], [3, 'c'], [4, 'd']]);
+ *     const found = bst.search(node => node.key > 2, true);
+ *     console.log(found.length); // >= 1;
+   */
     search(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>> | Range<K>, onlyOne?: boolean): (K | undefined)[];
     search<C extends NodeCallback<BSTNode<K, V>>>(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>> | Range<K>, onlyOne: boolean, callback: C, startNode?: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
+    /**
+   * Find all keys in a range
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Find all keys in a range
+ *  const bst = new BST<number>([10, 20, 30, 40, 50]);
+ *     console.log(bst.rangeSearch([15, 35])); // [20, 30];
+   */
     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>[];
     /**
@@ -363,6 +709,100 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param keyNodeOrEntry - The key, node, or entry to set.
      * @param [value] - The value, if providing just a key.
      * @returns True if the addition was successful, false otherwise.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Set a key-value pair
+   *  const bst = new BST<number, string>();
+   *     bst.set(1, 'one');
+   *     bst.set(2, 'two');
+   *     console.log(bst.get(1)); // 'one';
      */
     set(keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
@@ -376,6 +816,65 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param [isBalanceAdd=true] - If true, builds a balanced tree from the items.
      * @param [iterationType=this.iterationType] - The traversal method for balanced set (recursive or iterative).
      * @returns An array of booleans indicating the success of each individual `set` operation.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Set multiple key-value pairs
+   *  const bst = new BST<number, string>();
+   *     bst.setMany([[1, 'a'], [2, 'b'], [3, 'c']]);
+   *     console.log(bst.size); // 3;
+   *     console.log(bst.get(2)); // 'b';
      */
     setMany(keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, BSTNode<K, V>>>, values?: Iterable<V | undefined>, isBalanceAdd?: boolean, iterationType?: IterationType): boolean[];
     /**
@@ -383,6 +882,44 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * Equivalent to Java TreeMap.ceiling.
      * Time Complexity: O(log n) average, O(h) worst case.
      * Space Complexity: O(h) for recursion, O(1) for iteration.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find the least key ≥ target
+   *  const bst = new BST<number>([10, 20, 30, 40, 50]);
+   *     console.log(bst.ceiling(25)); // 30;
+   *     console.log(bst.ceiling(30)); // 30;
+   *     console.log(bst.ceiling(55)); // undefined;
      */
     ceiling(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>): K | undefined;
     /**
@@ -396,6 +933,43 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * Equivalent to Java TreeMap.higher.
      * Time Complexity: O(log n) average, O(h) worst case.
      * Space Complexity: O(h) for recursion, O(1) for iteration.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find the least key strictly > target
+   *  const bst = new BST<number>([10, 20, 30, 40]);
+   *     console.log(bst.higher(20)); // 30;
+   *     console.log(bst.higher(40)); // undefined;
      */
     higher(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>): K | undefined;
     /**
@@ -409,6 +983,44 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * Equivalent to Java TreeMap.floor.
      * Time Complexity: O(log n) average, O(h) worst case.
      * Space Complexity: O(h) for recursion, O(1) for iteration.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find the greatest key ≤ target
+   *  const bst = new BST<number>([10, 20, 30, 40, 50]);
+   *     console.log(bst.floor(25)); // 20;
+   *     console.log(bst.floor(10)); // 10;
+   *     console.log(bst.floor(5)); // undefined;
      */
     floor(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>): K | undefined;
     /**
@@ -422,6 +1034,43 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * Equivalent to Java TreeMap.lower.
      * Time Complexity: O(log n) average, O(h) worst case.
      * Space Complexity: O(h) for recursion, O(1) for iteration.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Find the greatest key strictly < target
+   *  const bst = new BST<number>([10, 20, 30, 40]);
+   *     console.log(bst.lower(30)); // 20;
+   *     console.log(bst.lower(10)); // undefined;
      */
     lower(keyNodeEntryOrPredicate: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BSTNode<K, V>>): K | undefined;
     /**
@@ -438,6 +1087,44 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      *
      * @param [iterationType=this.iterationType] - The traversal method for the initial node export.
      * @returns True if successful, false if the tree was empty.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Rebalance the tree
+   *  const bst = new BST<number>();
+   *     // Insert in sorted order (worst case for BST)
+   *     for (let i = 1; i <= 7; i++) bst.add(i);
+   *     console.log(bst.isAVLBalanced()); // false;
+   *     bst.perfectlyBalance();
+   *     console.log(bst.isAVLBalanced()); // true;
      */
     perfectlyBalance(iterationType?: IterationType): boolean;
     /**
@@ -446,6 +1133,40 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      *
      * @param [iterationType=this.iterationType] - The traversal method.
      * @returns True if the tree is AVL balanced, false otherwise.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Check if tree is height-balanced
+   *  const bst = new BST<number>([3, 1, 5, 2, 4]);
+   *     console.log(bst.isAVLBalanced()); // true;
      */
     isAVLBalanced(iterationType?: IterationType): boolean;
     /**
@@ -460,6 +1181,72 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @param [options] - Options for the new BST.
      * @param [thisArg] - `this` context for the callback.
      * @returns A new, mapped BST.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Transform to new tree
+   *  const bst = new BST<number, number>([[1, 10], [2, 20], [3, 30]]);
+   *     const doubled = bst.map((value, key) => [key, (value ?? 0) * 2] as [number, number]);
+   *     console.log([...doubled.values()]); // [20, 40, 60];
      */
     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>;
     /**