binary-tree-typed 2.4.4 → 2.5.0

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

@@ -26,7 +26,7 @@ import { BinaryTree } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
 import { Queue } from '../queue';
 import { isComparable } from '../../utils';
-import { Range } from '../../common';
+import { ERR, Range } from '../../common';
 
 /**
  * Represents a Node in a Binary Search Tree.
@@ -105,6 +105,7 @@ export class BSTNode<K = any, V = any> {
    *
    * @returns The height.
    */
+  /* istanbul ignore next -- covered by AVLTree/RedBlackTree tests (subclass uses height) */
   get height(): number {
     return this._height;
   }
@@ -115,6 +116,7 @@ export class BSTNode<K = any, V = any> {
    *
    * @param value - The new height.
    */
+  /* istanbul ignore next -- covered by AVLTree/RedBlackTree tests (subclass uses height) */
   set height(value: number) {
     this._height = value;
   }
@@ -127,6 +129,7 @@ export class BSTNode<K = any, V = any> {
    *
    * @returns The node's color.
    */
+  /* istanbul ignore next -- covered by RedBlackTree tests (subclass uses color) */
   get color(): RBTNColor {
     return this._color;
   }
@@ -137,6 +140,7 @@ export class BSTNode<K = any, V = any> {
    *
    * @param value - The new color.
    */
+  /* istanbul ignore next -- covered by RedBlackTree tests (subclass uses color) */
   set color(value: RBTNColor) {
     this._color = value;
   }
@@ -149,6 +153,7 @@ export class BSTNode<K = any, V = any> {
    *
    * @returns The subtree node count.
    */
+  /* istanbul ignore next -- internal field used by subclasses */
   get count(): number {
     return this._count;
   }
@@ -159,6 +164,7 @@ export class BSTNode<K = any, V = any> {
    *
    * @param value - The new count.
    */
+  /* istanbul ignore next -- internal field used by subclasses */
   set count(value: number) {
     this._count = value;
   }
@@ -200,34 +206,6 @@ 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]);
- *
- *     // 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]);
  *
@@ -454,6 +432,36 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return isComparable(key);
   }
 
+    /**
+   * 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];
+   */
   override dfs(): (K | undefined)[];
 
   override dfs<C extends NodeCallback<BSTNode<K, V>>>(
@@ -486,6 +494,28 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return super.dfs(callback, pattern, onlyOne, startNode, iterationType);
   }
 
+    /**
+   * 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;
+   */
   override bfs(): (K | undefined)[];
   override bfs<C extends NodeCallback<BSTNode<K, V>>>(
     callback: C,
@@ -511,6 +541,34 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return super.bfs(callback, startNode, iterationType, false);
   }
 
+    /**
+   * 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];
+   */
   override listLevels(): (K | undefined)[][];
 
   override listLevels<C extends NodeCallback<BSTNode<K, V>>>(
@@ -545,6 +603,31 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @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';
    */
   override getNode(
     keyNodeEntryOrPredicate:
@@ -606,6 +689,26 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
   }
 
 
+    /**
+   * 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;
+   */
   override search(
     keyNodeEntryOrPredicate:
       | K
@@ -699,6 +802,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     let predicate: NodePredicate<BSTNode<K, V>>;
     if (isRange) {
       predicate = node => {
+        /* istanbul ignore next -- node is always defined in iteration callbacks */
         if (!node) return false;
         return (keyNodeEntryOrPredicate).isInRange(node.key, this._comparator);
       };
@@ -708,7 +812,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
 
     // Optimization: Pruning logic
     const shouldVisitLeft = (cur: BSTNode<K, V> | null | undefined) => {
-      if (!cur) return false;
+      /* istanbul ignore next -- defensive: cur is always defined when called from iteration */ if (!cur) return false;
       if (!this.isRealNode(cur.left)) return false;
       if (isRange) {
         // Range search: Only go left if the current key is >= the lower bound
@@ -726,7 +830,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     };
 
     const shouldVisitRight = (cur: BSTNode<K, V> | null | undefined) => {
-      if (!cur) return false;
+      /* istanbul ignore next -- defensive */ if (!cur) return false;
       if (!this.isRealNode(cur.right)) return false;
       if (isRange) {
         // Range search: Only go right if current key <= upper bound
@@ -757,6 +861,24 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     );
   }
 
+    /**
+   * 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>>>(
@@ -794,6 +916,37 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @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';
    */
   override set(
     keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined,
@@ -836,6 +989,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
         if (current.right !== null) current = current.right;
       }
     }
+    /* istanbul ignore next -- defensive: traversal always finds undefined slot before exhausting tree */
     return false;
   }
 
@@ -850,6 +1004,23 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @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';
    */
   override setMany(
     keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, BSTNode<K, V>>>,
@@ -920,6 +1091,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       const stack: Array<[number, number]> = [[0, n - 1]];
       while (stack.length > 0) {
         const popped = stack.pop();
+        /* istanbul ignore next -- stack.pop() on non-empty stack always returns a value */
         if (!popped) continue;
         const [l, r] = popped;
         if (l > r) continue;
@@ -947,6 +1119,23 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * 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:
@@ -1012,6 +1201,22 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * 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:
@@ -1077,6 +1282,23 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * 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:
@@ -1117,7 +1339,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     iterationType?: IterationType
   ): K | undefined | ReturnType<C> {
     if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === undefined) {
-      if (typeof callback === 'string' || !callback) {
+      /* istanbul ignore next */ if (typeof callback === 'string' || !callback) {
         return undefined;
       }
       return undefined;
@@ -1151,7 +1373,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     } else if (this.isEntry(keyNodeEntryOrPredicate)) {
       const key = keyNodeEntryOrPredicate[0];
       if (key === null || key === undefined) {
-        if (typeof callback === 'string' || !callback) {
+        /* istanbul ignore next */ if (typeof callback === 'string' || !callback) {
           return undefined;
         }
         return undefined;
@@ -1164,6 +1386,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     if (targetKey !== undefined) {
       const node = this._floorByKey(targetKey, actualIterationType);
 
+      /* istanbul ignore next */
       if (!actualCallback) {
         return node?.key;
       }
@@ -1171,9 +1394,11 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       return node ? actualCallback(node) : undefined;
     }
 
+    /* istanbul ignore next -- targetKey is always defined if we reach here (null/undefined caught above) */
     if (typeof callback === 'string' || !callback) {
       return undefined;
     }
+    /* istanbul ignore next */
     return undefined;
   }
 
@@ -1182,6 +1407,22 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * 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:
@@ -1222,9 +1463,10 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     iterationType?: IterationType
   ): K | undefined | ReturnType<C> {
     if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === undefined) {
-      if (typeof callback === 'string' || !callback) {
+      /* istanbul ignore next */ if (typeof callback === 'string' || !callback) {
         return undefined;
       }
+      /* istanbul ignore next */
       return undefined;
     }
 
@@ -1256,9 +1498,10 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     } else if (this.isEntry(keyNodeEntryOrPredicate)) {
       const key = keyNodeEntryOrPredicate[0];
       if (key === null || key === undefined) {
-        if (typeof callback === 'string' || !callback) {
+        /* istanbul ignore next */ if (typeof callback === 'string' || !callback) {
           return undefined;
         }
+      /* istanbul ignore next */
         return undefined;
       }
       targetKey = key;
@@ -1276,9 +1519,11 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       return node ? actualCallback(node) : undefined;
     }
 
+    /* istanbul ignore next -- targetKey is always defined if we reach here (null/undefined caught above) */
     if (typeof callback === 'string' || !callback) {
       return undefined;
     }
+    /* istanbul ignore next */
     return undefined;
   }
 
@@ -1345,6 +1590,23 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    *
    * @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 = this.iterationType): boolean {
     const nodes = this.dfs(node => node, 'IN', false, this._root, iterationType);
@@ -1377,6 +1639,19 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    *
    * @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 = this.iterationType): boolean {
     if (!this._root) return true;
@@ -1434,6 +1709,30 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
    * @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];
    */
   override map<MK = K, MV = V, MR = any>(
     callback: EntryCallback<K, V | undefined, [MK, MV]>,
@@ -1523,10 +1822,19 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
         return 0;
       }
 
+      /* istanbul ignore next -- Date objects satisfy isComparable(), so this branch is unreachable via default comparator */
+      // Date keys: compare by getTime()
+      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'));
+        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 TypeError(
-          `When comparing object type keys, a custom comparator must be provided in the constructor's options!`
+        throw new TypeError(
+          ERR.comparatorRequired('BST')
         );
       }
 
@@ -1823,6 +2131,7 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
       return this._boundByKey(targetKey, isLower, iterationType);
     }
 
+    /* istanbul ignore next -- defensive: targetKey is always defined if predicate path was skipped */
     return undefined;
   }