data-structure-typed 2.4.4 → 2.5.0

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]);
  *
@@ -336,10 +308,90 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * @returns True if the key is valid, false otherwise.
      */
     isValidKey(key: any): 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 +402,73 @@ 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 +478,37 @@ 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 +522,23 @@ 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 +546,23 @@ 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 +576,22 @@ 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 +605,23 @@ 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 +635,22 @@ 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 +667,23 @@ 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 +692,19 @@ 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 +719,30 @@ 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>;
     /**

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeDeleteResult, BTNRep, CRUD, EntryCallback, FamilyPosition, NodePredicate, RBTNColor, RedBlackTreeOptions } from '../../types';
+import type { BinaryTreeDeleteResult, BTNRep, CRUD, EntryCallback, FamilyPosition, NodePredicate, RBTNColor, IterationType, RedBlackTreeOptions } from '../../types';
 import { BST } from './bst';
 import { IBinaryTree } from '../../interfaces';
 export declare class RedBlackTreeNode<K = any, V = any> {
@@ -56,12 +56,6 @@ export declare class RedBlackTreeNode<K = any, V = any> {
      * @returns The height.
      */
     get height(): number;
-    /**
-     * Sets the height of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new height.
-     */
     set height(value: number);
     _color: RBTNColor;
     /**
@@ -86,13 +80,6 @@ export declare class RedBlackTreeNode<K = any, V = any> {
      * @returns The subtree node count.
      */
     get count(): number;
-    /**
-     * Sets the count of nodes in the subtree.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new count.
-     */
-    set count(value: number);
     /**
      * Gets the position of the node relative to its parent.
      * @remarks Time O(1), Space O(1)
@@ -111,23 +98,6 @@ export declare class RedBlackTreeNode<K = any, V = any> {
  * 2. It is BST itself. Compared with Heap which is not completely ordered, RedBlackTree is completely ordered.
  *
  * @example
- * // basic Red-Black Tree with simple number keys
- *  // Create a simple Red-Black Tree with numeric keys
- *     const tree = new RedBlackTree([5, 2, 8, 1, 9]);
- *
- *     tree.print();
- *     //   _2___
- *     //  /     \
- *     //  1    _8_
- *     //      /   \
- *     //      5   9
- *
- *     // Verify the tree maintains sorted order
- *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
- *
- *     // Check size
- *     console.log(tree.size); // 5;
- * @example
  * // Red-Black Tree with key-value pairs for lookups
  *  interface Employee {
  *       id: number;
@@ -254,6 +224,46 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
     /**
      * Remove all nodes and clear internal caches.
      * @remarks Time O(n) average, Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove all entries
+   *  const rbt = new RedBlackTree<number>([1, 2, 3]);
+   *     rbt.clear();
+   *     console.log(rbt.isEmpty()); // true;
      */
     clear(): void;
     /**
@@ -355,6 +365,59 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      * - updates via a single-pass search (no double walk)
      *
      * @remarks Time O(log n) average, Space O(1)
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // basic Red-Black Tree with simple number keys
+   *  // Create a simple Red-Black Tree with numeric keys
+   *     const tree = new RedBlackTree([5, 2, 8, 1, 9]);
+   *
+   *     tree.print();
+   *     //   _2___
+   *     //  /     \
+   *     //  1    _8_
+   *     //      /   \
+   *     //      5   9
+   *
+   *     // Verify the tree maintains sorted order
+   *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
+   *
+   *     // Check size
+   *     console.log(tree.size); // 5;
      */
     set(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
@@ -362,6 +425,50 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      * @remarks Time O(log n) average, Space O(1)
      * @param keyNodeEntryRawOrPredicate - Key, node, or [key, value] entry identifying the node to delete.
      * @returns Array with deletion metadata (removed node, rebalancing hint if any).
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove and rebalance
+   *  const rbt = new RedBlackTree<number>([10, 5, 15, 3, 7]);
+   *     rbt.delete(5);
+   *     console.log(rbt.has(5)); // false;
+   *     console.log(rbt.size); // 4;
      */
     delete(keyNodeEntryRawOrPredicate: BTNRep<K, V, RedBlackTreeNode<K, V>> | NodePredicate<RedBlackTreeNode<K, V> | null>): BinaryTreeDeleteResult<RedBlackTreeNode<K, V>>[];
     /**
@@ -375,6 +482,85 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      * @param [thisArg] - See parameter type for details.
      * @returns A new RedBlackTree with mapped entries.
      */
+    /**
+     * Red-Black trees are self-balancing — `perfectlyBalance` rebuilds via
+     * sorted bulk insert, which naturally produces a balanced RBT.
+     * @remarks Time O(N), Space O(N)
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Rebalance tree
+   *  const rbt = new RedBlackTree<number>([1, 2, 3, 4, 5]);
+   *     rbt.perfectlyBalance();
+   *     console.log(rbt.isAVLBalanced()); // true;
+     */
+    perfectlyBalance(_iterationType?: IterationType): boolean;
+    /**
+   * Transform to new tree
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform to new tree
+ *  const rbt = new RedBlackTree<number, number>([[1, 10], [2, 20]]);
+ *     const doubled = rbt.map((v, k) => [k, (v ?? 0) * 2] as [number, number]);
+ *     console.log([...doubled.values()]); // [20, 40];
+   */
     map<MK = K, MV = V, MR = any>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<RedBlackTreeOptions<MK, MV, MR>>, thisArg?: unknown): RedBlackTree<MK, MV, MR>;
     /**
      * (Internal) Create an empty instance of the same concrete tree type.