binary-tree-typed 2.5.2 → 2.5.3

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

@@ -216,7 +216,7 @@ export class BinaryTreeNode<K = any, V = any> {
  *       node?: BinaryTreeNode<string> | null,
  *       conditions?: { [key: string]: boolean }
  *     ): string {
- *       if (!node) raise(Error, 'Invalid node');
+ *       if (!node) throw new Error('Invalid node');
  *
  *       // If it's a leaf node, return the decision result
  *       if (!node.left && !node.right) return node.key;
@@ -261,7 +261,7 @@ export class BinaryTreeNode<K = any, V = any> {
  *         case '/':
  *           return rightValue !== 0 ? leftValue / rightValue : 0; // Handle division by zero
  *         default:
- *           raise(Error, `Unsupported operator: ${node.key}`);
+ *           throw new Error(`Unsupported operator: ${node.key}`);
  *       }
  *     }
  *
@@ -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.
@@ -591,6 +591,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -613,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.
@@ -648,6 +652,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -767,6 +775,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -814,6 +826,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -887,6 +903,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -904,71 +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>>[] = [];
@@ -982,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;
@@ -1009,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;
@@ -1019,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;
     }
@@ -1032,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
   
@@ -1055,6 +1065,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1093,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.
@@ -1191,6 +1205,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1232,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.
@@ -1266,6 +1284,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1299,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).
@@ -1335,6 +1357,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1361,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.
@@ -1397,6 +1423,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1495,6 +1525,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1544,6 +1578,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1605,6 +1643,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1696,6 +1738,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1761,6 +1807,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2067,6 +2117,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2155,6 +2209,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2302,6 +2360,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2402,6 +2464,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2520,6 +2586,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2682,6 +2752,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2735,6 +2809,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2792,6 +2870,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+   
    
    
    
@@ -2882,6 +2964,10 @@ export class BinaryTree<K = any, V = any, R = any>
    
    
    
+   
+   
+   
+