binary-tree-typed 2.5.1 → 2.5.3

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

@@ -28,7 +28,7 @@ import { IBinaryTree } from '../../interfaces';
 import { isComparable, makeTrampoline, makeTrampolineThunk } from '../../utils';
 import { Queue } from '../queue';
 import { IterableEntryBase } from '../base';
-import { DFSOperation, ERR, Range } from '../../common';
+import { DFSOperation, ERR, raise, Range } from '../../common';
 
 /**
  * @template K - The type of the key.
@@ -293,7 +293,7 @@ export class BinaryTree<K = any, V = any, R = any>
       if (isMapMode !== undefined) this._isMapMode = isMapMode;
       if (isDuplicate !== undefined) this._isDuplicate = isDuplicate;
       if (typeof toEntryFn === 'function') this._toEntryFn = toEntryFn;
-      else if (toEntryFn) throw new TypeError(ERR.notAFunction('toEntryFn', 'BinaryTree'));
+      else if (toEntryFn) raise(TypeError, ERR.notAFunction('toEntryFn', 'BinaryTree'));
     }
 
     if (keysNodesEntriesOrRaws) this.setMany(keysNodesEntriesOrRaws);
@@ -562,7 +562,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
   /**
    * Adds 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).
+   * @remarks Time O(N) — level-order traversal to find an empty slot. Space O(N) for the BFS queue. BST/Red-Black Tree/AVL Tree subclasses override to O(log N).
    *
    * @param keyNodeOrEntry - The key, node, or entry to add.
    * @returns True if the addition was successful, false otherwise.
@@ -585,6 +585,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -610,7 +617,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
   /**
    * 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 sets 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).
+   * @remarks Time O(N) — level-order traversal to find an empty slot. Space O(N) for the BFS queue. BST/Red-Black Tree/AVL Tree subclasses override to O(log N).
    *
    * @param keyNodeOrEntry - The key, node, or entry to set or update.
    * @param [value] - The value, if providing just a key.
@@ -639,6 +646,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -755,6 +769,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -799,6 +820,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -869,6 +897,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -889,68 +924,14 @@ export class BinaryTree<K = any, V = any, R = any>
   }
 
   /**
-   * Clears the tree and refills it with new items.
-   * @remarks Time O(N) (for `clear`) + O(N * M) (for `setMany`) = O(N * M). Space O(M) (from `setMany`).
-   *
-   * @param keysNodesEntriesOrRaws - An iterable of items to set.
-   * @param [values] - An optional parallel iterable of values.
-   */
-  refill(
-    keysNodesEntriesOrRaws: Iterable<
-      K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R
-    >,
-    values?: Iterable<V | undefined>
-  ): void {
-    this.clear();
-    this.setMany(keysNodesEntriesOrRaws, values);
-  }
-
-  /**
-   * Deletes a node from 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 finds the node, and if it has two children, swaps it with the rightmost node of its left subtree (in-order predecessor) before deleting. Time O(N) in the worst case. O(N) to find the node (`getNode`) and O(H) (which is O(N) worst-case) to find the rightmost node. Space O(1) (if `getNode` is iterative, which it is).
+   * Deletes a node from the tree (internal, returns balancing metadata).
+   * @remarks Time O(N) — O(N) to find the node + O(H) for predecessor swap. Space O(1). BST/Red-Black Tree/AVL Tree subclasses override to O(log N).
+   * @internal Used by AVL/BST subclasses that need balancing metadata after deletion.
    *
    * @param keyNodeEntryRawOrPredicate - The node to delete.
-   * @returns An array containing deletion results (for compatibility with self-balancing trees).
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove a node
- *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
- *     tree.delete(3);
- *     console.log(tree.has(3)); // false;
- *     console.log(tree.size); // 4;
+   * @returns An array containing deletion results with balancing metadata.
    */
-  delete(
+  protected _deleteInternal(
     keyNodeEntryRawOrPredicate: BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>
   ): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[] {
     const deletedResult: BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[] = [];
@@ -964,26 +945,19 @@ export class BinaryTree<K = any, V = any, R = any>
     let orgCurrent: BinaryTreeNode<K, V> | undefined = curr;
 
     if (!curr.left && !curr.right && !parent) {
-      // Deleting the root with no children
       this._setRoot(undefined);
     } else if (curr.left) {
-      // Node has a left child (or two children)
-      // Find the rightmost node in the left subtree
       const leftSubTreeRightMost = this.getRightMost(node => node, curr.left);
       if (leftSubTreeRightMost) {
         const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
-        // Swap properties
         orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
 
-        // Map mode store tracks key -> node reference; after swapping keys we must re-index both nodes.
         if (this._isMapMode) {
           this._store.set(curr.key, curr);
           this._store.set(leftSubTreeRightMost.key, leftSubTreeRightMost);
         }
 
-        // `orgCurrent` is now the node to be physically deleted (which was the rightmost)
         if (parentOfLeftSubTreeMax) {
-          // Unlink the rightmost node
           if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost)
             parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
           else parentOfLeftSubTreeMax.left = leftSubTreeRightMost.left;
@@ -991,8 +965,6 @@ export class BinaryTree<K = any, V = any, R = any>
         }
       }
     } else if (parent) {
-      // Node has no left child, but has a parent
-      // Promote the right child (which could be null)
       const { familyPosition: fp } = curr;
       if (fp === 'LEFT' || fp === 'ROOT_LEFT') {
         parent.left = curr.right;
@@ -1001,8 +973,6 @@ export class BinaryTree<K = any, V = any, R = any>
       }
       needBalanced = parent;
     } else {
-      // Deleting the root, which has no left child
-      // Promote the right child as the new root
       this._setRoot(curr.right);
       curr.right = undefined;
     }
@@ -1014,6 +984,64 @@ export class BinaryTree<K = any, V = any, R = any>
     return deletedResult;
   }
 
+  /**
+   * Deletes a node from the tree.
+   * @remarks Time O(N) — O(N) to find the node + O(H) for predecessor swap. Space O(1). BST/Red-Black Tree/AVL Tree subclasses override to O(log N).
+   *
+   * @param keyNodeEntryRawOrPredicate - The node to delete.
+   * @returns True if the node was found and deleted, false otherwise.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove a node
+ *  const tree = new BinaryTree<number>([1, 2, 3, 4, 5]);
+ *     tree.delete(3);
+ *     console.log(tree.has(3)); // false;
+ *     console.log(tree.size); // 4;
+   */
+  delete(
+    keyNodeEntryRawOrPredicate: BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>
+  ): boolean {
+    return this._deleteInternal(keyNodeEntryRawOrPredicate).length > 0;
+  }
+
     /**
    * Search by predicate
   
@@ -1031,6 +1059,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1072,7 +1107,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
   /**
    * Searches the tree for nodes matching a predicate.
-   * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). Performs a full DFS (pre-order) scan of the tree. Time O(N), as it may visit every node. Space O(H) for the call stack (recursive) or explicit stack (iterative), where H is the tree height (O(N) worst-case).
+   * @remarks Time O(N) — full DFS scan; may visit every node. Space O(H) for call/explicit stack (O(N) worst-case). BST subclasses with key search override to O(log N).
    *
    * @template C - The type of the callback function.
    * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
@@ -1164,6 +1199,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1208,7 +1250,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
   /**
    * Gets the first node matching a predicate.
-   * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). Time O(N) in the worst case (via `search`). Space O(H) or O(N) (via `search`).
+   * @remarks Time O(N) via `search`. Space O(H) or O(N). BST/Red-Black Tree/AVL Tree subclasses override to O(log N) for key lookups.
    *
    * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
    * @param [startNode=this._root] - The node to start the search from.
@@ -1236,6 +1278,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1272,7 +1321,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
   /**
    * Gets the value associated with a key.
-   * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). Time O(1) if in Map mode. O(N) if not in Map mode (uses `getNode`). Space O(1) if in Map mode. O(H) or O(N) otherwise.
+   * @remarks Time O(1) in Map mode, O(N) otherwise (via `getNode`). Space O(1) in Map mode, O(H) or O(N) otherwise. BST subclasses override non-Map-mode to O(log N).
    *
    * @param keyNodeEntryOrPredicate - The key, node, or entry to get the value for.
    * @param [startNode=this._root] - The node to start searching from (if not in Map mode).
@@ -1302,6 +1351,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1331,7 +1387,7 @@ export class BinaryTree<K = any, V = any, R = any>
 
   /**
    * Checks if a node matching the predicate exists in the tree.
-   * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). Time O(N) in the worst case (via `search`). Space O(H) or O(N) (via `search`).
+   * @remarks Time O(N) via `search`. Space O(H) or O(N). BST/Red-Black Tree/AVL Tree subclasses override to O(log N) for key lookups.
    *
    * @param [keyNodeEntryOrPredicate] - The key, node, entry, or predicate to check for.
    * @param [startNode] - The node to start the search from.
@@ -1361,6 +1417,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1456,6 +1519,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1502,6 +1572,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1560,6 +1637,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1648,6 +1732,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1710,6 +1801,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2013,6 +2111,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2098,6 +2203,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2242,6 +2354,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2339,6 +2458,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2454,6 +2580,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2613,6 +2746,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2663,6 +2803,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2717,6 +2864,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2804,6 +2958,13 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
+   
+   
+