data-structure-typed 2.2.7 → 2.3.0

package/dist/types/data-structures/base/linear-base.d.ts

@@ -52,7 +52,7 @@ export declare abstract class LinearBase<E, R = any, NODE extends LinkedListNode
      * @param options - `{ maxLen?, ... }` bounds/behavior options.
      * @remarks Time O(1), Space O(1)
      */
-    protected constructor(options?: LinearBaseOptions<E, R>);
+    constructor(options?: LinearBaseOptions<E, R>);
     /**
      * Element count.
      * @returns Number of elements.
@@ -91,12 +91,12 @@ export declare abstract class LinearBase<E, R = any, NODE extends LinkedListNode
      */
     findIndex(predicate: ElementCallback<E, R, boolean>, thisArg?: any): number;
     /**
-     * Concatenate multiple containers of the same species.
-     * @param items - Other lists to append.
+     * Concatenate elements and/or containers.
+     * @param items - Elements or other containers.
      * @returns New container with combined elements (`this` type).
      * @remarks Time O(sum(length)), Space O(sum(length))
      */
-    concat(...items: this[]): this;
+    concat(...items: (E | this)[]): this;
     /**
      * In-place stable order via array sort semantics.
      * @param compareFn - Comparator `(a, b) => number`.
@@ -238,7 +238,7 @@ export declare abstract class LinearBase<E, R = any, NODE extends LinkedListNode
  * @remarks Time O(1), Space O(1)
  */
 export declare abstract class LinearLinkedBase<E, R = any, NODE extends LinkedListNode<E> = LinkedListNode<E>> extends LinearBase<E, R, NODE> {
-    protected constructor(options?: LinearBaseOptions<E, R>);
+    constructor(options?: LinearBaseOptions<E, R>);
     /**
      * Linked-list optimized `indexOf` (forwards scan).
      * @param searchElement - Value to match.
@@ -261,7 +261,7 @@ export declare abstract class LinearLinkedBase<E, R = any, NODE extends LinkedLi
      * @returns New list with combined elements (`this` type).
      * @remarks Time O(sum(length)), Space O(sum(length))
      */
-    concat(...items: LinearBase<E, R>[]): this;
+    concat(...items: (E | LinearBase<E, R>)[]): this;
     /**
      * Slice via forward iteration (no random access required).
      * @param start - Inclusive start (supports negative index).

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

@@ -147,7 +147,7 @@ export declare class AVLTreeCounter<K = any, V = any, R = any> extends AVLTree<K
      * @param [count] - How much to increase the node's count (default 1).
      * @returns True if inserted/updated; false if ignored.
      */
-    add(keyNodeOrEntry: K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V, count?: number): boolean;
+    set(keyNodeOrEntry: K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V, count?: number): boolean;
     /**
      * Delete a node (or decrement its count) and rebalance if needed.
      * @remarks Time O(log N), Space O(1)

package/dist/types/data-structures/binary-tree/avl-tree-multi-map.d.ts

@@ -132,8 +132,8 @@ export declare class AVLTreeMultiMap<K = any, V = any, R = any> extends AVLTree<
      * @returns True if it's a AVLTreeMultiMapNode, false otherwise.
      */
     isNode(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): keyNodeOrEntry is AVLTreeMultiMapNode<K, V>;
-    add(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
-    add(key: K, value: V): boolean;
+    set(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
+    set(key: K, value: V): boolean;
     /**
      * Delete a single value from the bucket at a given key. Removes the key if the bucket becomes empty.
      * @remarks Time O(log N), Space O(1)

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

@@ -112,7 +112,7 @@ export declare class AVLTreeNode<K = any, V = any> {
 }
 /**
  * Represents a self-balancing AVL (Adelson-Velsky and Landis) Tree.
- * This tree extends BST and performs rotations on add/delete to maintain balance.
+ * This tree extends BST and performs rotations on set/delete to maintain balance.
  *
  * @template K - The type of the key.
  * @template V - The type of the value.
@@ -145,7 +145,7 @@ export declare class AVLTreeNode<K = any, V = any> {
  *     console.log(tree.size); // 5;
  *
  *     // Add a new element
- *     tree.add(3);
+ *     tree.set(3);
  *     console.log(tree.size); // 6;
  *     console.log([...tree.keys()]); // [1, 2, 3, 5, 8, 9];
  * @example
@@ -208,7 +208,7 @@ export declare class AVLTreeNode<K = any, V = any> {
  *     console.log(universityTree.isAVLBalanced()); // true;
  *
  *     // Add more universities
- *     universityTree.add(6, { name: 'Oxford', rank: 6, students: 2000 });
+ *     universityTree.set(6, { name: 'Oxford', rank: 6, students: 2000 });
  *     console.log(universityTree.isAVLBalanced()); // true;
  *
  *     // Delete and verify balance is maintained
@@ -288,9 +288,9 @@ export declare class AVLTreeNode<K = any, V = any> {
 export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements IBinaryTree<K, V, R> {
     /**
      * Creates an instance of AVLTree.
-     * @remarks Time O(N log N) (from `addMany` with balanced add). Space O(N).
+     * @remarks Time O(N log N) (from `setMany` with balanced set). Space O(N).
      *
-     * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to add.
+     * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to set.
      * @param [options] - Configuration options for the AVL tree.
      */
     constructor(keysNodesEntriesOrRaws?: Iterable<K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: AVLTreeOptions<K, V, R>);
@@ -312,14 +312,14 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
      */
     isNode(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is AVLTreeNode<K, V>;
     /**
-     * Adds a new node to the AVL tree and balances the tree path.
-     * @remarks Time O(log N) (O(H) for BST add + O(H) for `_balancePath`). Space O(H) for path/recursion.
+     * Sets a new node to the AVL tree and balances the tree path.
+     * @remarks Time O(log N) (O(H) for BST set + O(H) for `_balancePath`). Space O(H) for path/recursion.
      *
-     * @param keyNodeOrEntry - The key, node, or entry to add.
+     * @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.
      */
-    add(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
+    set(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
      * Deletes a node from the AVL tree and re-balances the tree.
      * @remarks Time O(log N) (O(H) for BST delete + O(H) for `_balancePath`). Space O(H) for path/recursion.
@@ -339,7 +339,7 @@ export declare class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> imp
     perfectlyBalance(iterationType?: IterationType): boolean;
     /**
      * Creates a new AVLTree by mapping each [key, value] pair.
-     * @remarks Time O(N log N) (O(N) iteration + O(log M) `add` for each item into the new tree). Space O(N) for the new tree.
+     * @remarks Time O(N log N) (O(N) iteration + O(log M) `set` for each item into the new tree). Space O(N) for the new tree.
      *
      * @template MK - New key type.
      * @template MV - New value type.

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeDeleteResult, BinaryTreeOptions, BinaryTreePrintOptions, BTNEntry, DFSOrderPattern, EntryCallback, FamilyPosition, IterationType, NodeCallback, NodeDisplayLayout, NodePredicate, RBTNColor, ToEntryFn } from '../../types';
+import type { BinaryTreeDeleteResult, BinaryTreeOptions, BinaryTreePrintOptions, BTNEntry, BTNRep, DFSOrderPattern, EntryCallback, FamilyPosition, IterationType, NodeCallback, NodeDisplayLayout, NodePredicate, RBTNColor, ToEntryFn } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { IterableEntryBase } from '../base';
 import { Range } from '../../common';
@@ -113,7 +113,7 @@ export declare class BinaryTreeNode<K = any, V = any> {
  *
  * @remarks
  * This class implements a basic Binary Tree, not a Binary Search Tree.
- * The `add` operation inserts nodes level-by-level (BFS) into the first available slot.
+ * The `set` operation inserts nodes level-by-level (BFS) into the first available slot.
  *
  * @template K - The type of the key.
  * @template V - The type of the value.
@@ -145,7 +145,7 @@ export declare class BinaryTreeNode<K = any, V = any> {
  *     console.log(tree.size); // 9;
  *
  *     // Add new element
- *     tree.add(10, 'ten');
+ *     tree.set(10, 'ten');
  *     console.log(tree.size); // 10;
  * @example
  * // BinaryTree get and has operations
@@ -269,9 +269,9 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
     iterationType: IterationType;
     /**
      * Creates an instance of BinaryTree.
-     * @remarks Time O(N * M), where N is the number of items in `keysNodesEntriesOrRaws` and M is the tree size at insertion time (due to O(M) `add` operation). Space O(N) for storing the nodes.
+     * @remarks Time O(N * M), where N is the number of items in `keysNodesEntriesOrRaws` and M is the tree size at insertion time (due to O(M) `set` operation). Space O(N) for storing the nodes.
      *
-     * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to add.
+     * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to set.
      * @param [options] - Configuration options for the tree.
      */
     constructor(keysNodesEntriesOrRaws?: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: BinaryTreeOptions<K, V, R>);
@@ -434,49 +434,47 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
      * @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).
      *
      * @param keyNodeOrEntry - The key, node, or entry to add.
-     * @param [value] - The value, if providing just a key.
      * @returns True if the addition was successful, false otherwise.
      */
-    add(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
+    add(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): boolean;
     /**
      * 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 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(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).
      *
-     * @param keyNodeOrEntry - The key, node, or entry to add or update.
+     * @param keyNodeOrEntry - The key, node, or entry to set or update.
      * @param [value] - The value, if providing just a key.
      * @returns True if the addition was successful, false otherwise.
      */
     set(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
      * Adds multiple items to the tree.
-     * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
+     * @remarks Time O(N * M), where N is the number of items to set and M is the size of the tree at insertion (due to O(M) `set` operation). Space O(M) (from `set`) + O(N) (for the `inserted` array).
      *
-     * @param keysNodesEntriesOrRaws - An iterable of items to add.
-     * @param [values] - An optional parallel iterable of values.
-     * @returns An array of booleans indicating the success of each individual `add` operation.
+     * @param keysNodesEntriesOrRaws - An iterable of items to set.
+     * @returns An array of booleans indicating the success of each individual `set` operation.
      */
-    addMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): boolean[];
+    addMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>): boolean[];
     /**
      * Adds or updates multiple items to the tree.
-     * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
+     * @remarks Time O(N * M), where N is the number of items to set and M is the size of the tree at insertion (due to O(M) `set` operation). Space O(M) (from `set`) + O(N) (for the `inserted` array).
      *
-     * @param keysNodesEntriesOrRaws - An iterable of items to add or update.
+     * @param keysNodesEntriesOrRaws - An iterable of items to set or update.
      * @param [values] - An optional parallel iterable of values.
-     * @returns An array of booleans indicating the success of each individual `add` operation.
+     * @returns An array of booleans indicating the success of each individual `set` operation.
      */
     setMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): boolean[];
     /**
-     * Merges another tree into this one by adding all its nodes.
-     * @remarks Time O(N * M), same as `addMany`, where N is the size of `anotherTree` and M is the size of this tree. Space O(M) (from `add`).
+     * Merges another tree into this one by seting all its nodes.
+     * @remarks Time O(N * M), same as `setMany`, where N is the size of `anotherTree` and M is the size of this tree. Space O(M) (from `set`).
      *
      * @param anotherTree - The tree to merge.
      */
     merge(anotherTree: BinaryTree<K, V, R>): void;
     /**
      * Clears the tree and refills it with new items.
-     * @remarks Time O(N) (for `clear`) + O(N * M) (for `addMany`) = O(N * M). Space O(M) (from `addMany`).
+     * @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 add.
+     * @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;
@@ -484,10 +482,10 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
      * 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).
      *
-     * @param keyNodeOrEntry - The node to delete.
+     * @param keyNodeEntryRawOrPredicate - The node to delete.
      * @returns An array containing deletion results (for compatibility with self-balancing trees).
      */
-    delete(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
+    delete(keyNodeEntryRawOrPredicate: BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
     search(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V> | null>, onlyOne?: boolean): (K | undefined)[];
     search<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V> | null>, onlyOne: boolean, callback: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
     /**
@@ -624,14 +622,14 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
     morris<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback?: C, pattern?: DFSOrderPattern, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): ReturnType<C>[];
     /**
      * Clones the tree.
-     * @remarks Time O(N * M), where N is the number of nodes and M is the tree size during insertion (due to `bfs` + `add`, and `add` is O(M)). Space O(N) for the new tree and the BFS queue.
+     * @remarks Time O(N * M), where N is the number of nodes and M is the tree size during insertion (due to `bfs` + `set`, and `set` is O(M)). Space O(N) for the new tree and the BFS queue.
      *
      * @returns A new, cloned instance of the tree.
      */
     clone(): this;
     /**
      * Creates a new tree containing only the entries that satisfy the predicate.
-     * @remarks Time O(N * M), where N is nodes in this tree, and M is size of the new tree during insertion (O(N) iteration + O(M) `add` for each item). Space O(N) for the new tree.
+     * @remarks Time O(N * M), where N is nodes in this tree, and M is size of the new tree during insertion (O(N) iteration + O(M) `set` for each item). Space O(N) for the new tree.
      *
      * @param predicate - A function to test each [key, value] pair.
      * @param [thisArg] - `this` context for the predicate.
@@ -722,8 +720,8 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
      */
     protected _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): [BinaryTreeNode<K, V> | null | undefined, V | undefined];
     /**
-     * (Protected) Helper for cloning. Performs a BFS and adds all nodes to the new tree.
-     * @remarks Time O(N * M) (O(N) BFS + O(M) `add` for each node).
+     * (Protected) Helper for cloning. Performs a BFS and sets all nodes to the new tree.
+     * @remarks Time O(N * M) (O(N) BFS + O(M) `set` for each node).
      *
      * @param cloned - The new, empty tree instance to populate.
      */

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

@@ -130,7 +130,8 @@ export declare class BSTNode<K = any, V = any> {
  *  // 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]);
  *
- *     bst.print();
+ *     // Keep the example output in source comments but avoid noisy test logs.
+ *     await withMutedConsole(() => bst.print());
  *     //         _______8__________
  *     //        /                  \
  *     //     ___4___          ____12_____
@@ -145,8 +146,8 @@ export declare class BSTNode<K = any, V = any> {
  *     console.log(bst.size); // 16;
  *
  *     // Add new elements
- *     bst.add(17);
- *     bst.add(0);
+ *     bst.set(17);
+ *     bst.set(0);
  *     console.log(bst.size); // 18;
  *
  *     // Verify keys are searchable
@@ -192,7 +193,7 @@ export declare class BSTNode<K = any, V = any> {
  *
  *     // Merge datasets into a single BinarySearchTree
  *     const merged = new BST<number, string>(dataset1);
- *     merged.addMany(dataset2);
+ *     merged.setMany(dataset2);
  *     merged.merge(dataset3);
  *
  *     // Verify merged dataset is in sorted order
@@ -276,7 +277,7 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * Creates an instance of BST.
      * @remarks Time O(N log N) or O(N^2) depending on `isBalanceAdd` in `addMany` and input order. Space O(N).
      *
-     * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to add.
+     * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to set.
      * @param [options] - Configuration options for the BST, including comparator.
      */
     constructor(keysNodesEntriesOrRaws?: Iterable<K | BSTNode | [K | null | undefined, V | undefined] | null | undefined | R>, options?: BSTOptions<K, V, R>);
@@ -359,24 +360,24 @@ export declare class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R>
      * Adds a new node to the BST based on key comparison.
      * @remarks Time O(log N), where H is tree height. O(N) worst-case (unbalanced tree), O(log N) average. Space O(1).
      *
-     * @param keyNodeOrEntry - The key, node, or entry to add.
+     * @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.
      */
-    add(keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
+    set(keyNodeOrEntry: K | BSTNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
      * Adds multiple items to the tree.
-     * @remarks If `isBalanceAdd` is true, sorts the input and builds a balanced tree. Time O(N log N) (due to sort and balanced add).
+     * @remarks If `isBalanceAdd` is true, sorts the input and builds a balanced tree. Time O(N log N) (due to sort and balanced set).
      * If false, adds items one by one. Time O(N * H), which is O(N^2) worst-case.
      * Space O(N) for sorting and recursion/iteration stack.
      *
-     * @param keysNodesEntriesOrRaws - An iterable of items to add.
+     * @param keysNodesEntriesOrRaws - An iterable of items to set.
      * @param [values] - An optional parallel iterable of values.
      * @param [isBalanceAdd=true] - If true, builds a balanced tree from the items.
-     * @param [iterationType=this.iterationType] - The traversal method for balanced add (recursive or iterative).
-     * @returns An array of booleans indicating the success of each individual `add` operation.
+     * @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.
      */
-    addMany(keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, BSTNode<K, V>>>, values?: Iterable<V | undefined>, isBalanceAdd?: boolean, iterationType?: IterationType): boolean[];
+    setMany(keysNodesEntriesOrRaws: Iterable<R | BTNRep<K, V, BSTNode<K, V>>>, values?: Iterable<V | undefined>, isBalanceAdd?: boolean, iterationType?: IterationType): boolean[];
     /**
      * Returns the first key with a value >= target.
      * Equivalent to Java TreeMap.ceiling.

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, CRUD, EntryCallback, FamilyPosition, RBTNColor, RedBlackTreeOptions } from '../../types';
+import type { BinaryTreeDeleteResult, BTNRep, CRUD, EntryCallback, FamilyPosition, NodePredicate, RBTNColor, RedBlackTreeOptions } from '../../types';
 import { BST } from './bst';
 import { IBinaryTree } from '../../interfaces';
 export declare class RedBlackTreeNode<K = any, V = any> {
@@ -13,12 +13,11 @@ export declare class RedBlackTreeNode<K = any, V = any> {
     value?: V;
     parent?: RedBlackTreeNode<K, V>;
     /**
-     * Create a Red-Black Tree and optionally bulk-insert items.
-     * @remarks Time O(n log n), Space O(n)
-     * @param key - See parameter type for details.
-     * @param [value]- See parameter type for details.
-     * @param color - See parameter type for details.
-     * @returns New RedBlackTree instance.
+     * Create a Red-Black Tree node.
+     * @remarks Time O(1), Space O(1)
+     * @param key - Node key.
+     * @param [value] - Node value (unused in map mode trees).
+     * @param color - Node color.
      */
     constructor(key: K, value?: V, color?: RBTNColor);
     _left?: RedBlackTreeNode<K, V> | null | undefined;
@@ -104,7 +103,7 @@ export declare class RedBlackTreeNode<K = any, V = any> {
 }
 /**
  * Represents a Red-Black Tree (self-balancing BST) supporting map-like mode and stable O(log n) updates.
- * @remarks Time O(1), Space O(1)
+ * @remarks Operation complexity depends on the method; see each method's docs.
  * @template K
  * @template V
  * @template R
@@ -207,6 +206,24 @@ export declare class RedBlackTreeNode<K = any, V = any> {
 export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implements IBinaryTree<K, V, R> {
     constructor(keysNodesEntriesOrRaws?: Iterable<K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: RedBlackTreeOptions<K, V, R>);
     protected _root: RedBlackTreeNode<K, V> | undefined;
+    /**
+     * (Internal) Header sentinel:
+     * - header.parent -> root
+     * - header._left  -> min (or NIL)
+     * - header._right -> max (or NIL)
+     *
+     * IMPORTANT:
+     * - This header is NOT part of the actual tree.
+     * - Do NOT use `header.left` / `header.right` accessors for wiring: those setters update `NIL.parent`
+     *   and can corrupt sentinel invariants / cause hangs. Only touch `header._left/_right`.
+     */
+    protected _header: RedBlackTreeNode<K, V>;
+    /**
+     * (Internal) Cache of the current minimum and maximum nodes.
+     * Used for fast-path insert/update when keys are monotonic or near-boundary.
+     */
+    protected _minNode: RedBlackTreeNode<K, V> | undefined;
+    protected _maxNode: RedBlackTreeNode<K, V> | undefined;
     /**
      * Get the current root node.
      * @remarks Time O(1), Space O(1)
@@ -234,25 +251,122 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      * @remarks Time O(n), Space O(1)
      * @returns void
      */
+    /**
+     * Remove all nodes and clear internal caches.
+     * @remarks Time O(n) average, Space O(1)
+     */
     clear(): void;
     /**
-     * Insert or replace an entry using BST order and red-black fix-up.
-     * @remarks Time O(log n), Space O(1)
-     * @param keyNodeOrEntry - Key, node, or [key, value] entry to insert.
-     * @param [value]- See parameter type for details.
-     * @returns True if inserted or updated; false if ignored.
+     * (Internal) Find a node by key using a tight BST walk (no allocations).
+     *
+     * NOTE: This uses `header.parent` as the canonical root pointer.
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    protected _findNodeByKey(key: K): RedBlackTreeNode<K, V> | undefined;
+    /**
+     * (Internal) In-order predecessor of a node in a BST.
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    protected _predecessorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined;
+    /**
+     * (Internal) In-order successor of a node in a BST.
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    protected _successorOf(node: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined;
+    /**
+     * (Internal) Attach a new node directly under a known parent/side (no search).
+     *
+     * This is a performance-oriented helper used by boundary fast paths and hinted insertion.
+     * It will:
+     * - wire parent/child pointers (using accessors, so parent pointers are updated)
+     * - initialize children to NIL
+     * - mark the new node RED, then run insert fix-up
+     *
+     * Precondition: the chosen slot (parent.left/parent.right) is empty (NIL/null/undefined).
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    protected _attachNewNode(parent: RedBlackTreeNode<K, V>, side: 'left' | 'right', node: RedBlackTreeNode<K, V>): void;
+    /**
+     * (Internal) a single source of truth for min/max is header._left/_right.
+     * Keep legacy _minNode/_maxNode mirrored for compatibility.
+     * @remarks Time O(1), Space O(1)
+     */
+    /**
+     * (Internal) Update min cache pointers (header._left is the canonical min pointer).
+     * @remarks Time O(1), Space O(1)
+     */
+    protected _setMinCache(node: RedBlackTreeNode<K, V> | undefined): void;
+    /**
+     * (Internal) Update max cache pointers (header._right is the canonical max pointer).
+     * @remarks Time O(1), Space O(1)
      */
-    add(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
+    protected _setMaxCache(node: RedBlackTreeNode<K, V> | undefined): void;
+    /**
+     * (Internal) Core set implementation returning the affected node.
+     *
+     * Hot path goals:
+     * - Avoid double walks (search+insert): do a single traversal that either updates or inserts.
+     * - Use header min/max caches to fast-path boundary inserts.
+     * - Keep header._left/_right as canonical min/max pointers.
+     *
+     * Return value:
+     * - `{ node, created:false }` when an existing key is updated
+     * - `{ node, created:true }` when a new node is inserted
+     * - `undefined` only on unexpected internal failure.
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    protected _setKVNode(key: K, nextValue?: V): {
+        node: RedBlackTreeNode<K, V>;
+        created: boolean;
+    } | undefined;
+    /**
+     * (Internal) Boolean wrapper around `_setKVNode`.
+     *
+     * Includes a map-mode update fast-path:
+     * - If `isMapMode=true` and the key already exists in `_store`, then updating the value does not
+     *   require any tree search/rotation (tree shape depends only on key).
+     * - This path is intentionally limited to `nextValue !== undefined` to preserve existing
+     *   semantics for `undefined` values.
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    protected _setKV(key: K, nextValue?: V): boolean;
+    /**
+     * Insert/update using a hint node to speed up nearby insertions.
+     *
+     * close to the expected insertion position (often the previously returned node in a loop).
+     *
+     * When the hint is a good fit (sorted / nearly-sorted insertion), this can avoid most of the
+     * normal root-to-leaf search and reduce constant factors.
+     *
+     * When the hint does not match (random workloads), this will fall back to the normal set path.
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    setWithHintNode(key: K, value: V, hint?: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V> | undefined;
+    /**
+     * Boolean wrapper for setWithHintNode.
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    setWithHint(key: K, value: V, hint?: RedBlackTreeNode<K, V>): boolean;
+    /**
+     * Insert or update a key/value (map mode) or key-only (set mode).
+     *
+     * This method is optimized for:
+     * - monotonic inserts via min/max boundary fast paths
+     * - updates via a single-pass search (no double walk)
+     *
+     * @remarks Time O(log n) average, Space O(1)
+     */
+    set(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
      * Delete a node by key/node/entry and rebalance as needed.
-     * @remarks Time O(log n), Space O(1)
-     * @param keyNodeOrEntry - Key, node, or [key, value] entry identifying the node to delete.
+     * @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).
      */
-    delete(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): BinaryTreeDeleteResult<RedBlackTreeNode<K, V>>[];
+    delete(keyNodeEntryRawOrPredicate: BTNRep<K, V, RedBlackTreeNode<K, V>> | NodePredicate<RedBlackTreeNode<K, V> | null>): BinaryTreeDeleteResult<RedBlackTreeNode<K, V>>[];
     /**
      * Transform entries into a like-kind red-black tree with possibly different key/value types.
-     * @remarks Time O(n), Space O(n)
+     * @remarks Time O(n) average, Space O(n)
      * @template MK
      * @template MV
      * @template MR
@@ -262,13 +376,29 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
      * @returns A new RedBlackTree with mapped entries.
      */
     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.
+     * @remarks Time O(1) average, Space O(1)
+     */
     protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): this;
+    /**
+     * (Internal) Create a like-kind tree (same concrete class) populated from an iterable.
+     * @remarks Time O(m log m) average (m = iterable length), Space O(m)
+     */
     protected _createLike<TK = K, TV = V, TR = R>(iter?: Iterable<TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): RedBlackTree<TK, TV, TR>;
+    /**
+     * (Internal) Set the root pointer and keep header.parent in sync.
+     * @remarks Time O(1), Space O(1)
+     */
     protected _setRoot(v: RedBlackTreeNode<K, V> | undefined): void;
+    /**
+     * (Internal) Replace a node in place while preserving its color.
+     * @remarks Time O(1) average, Space O(1)
+     */
     protected _replaceNode(oldNode: RedBlackTreeNode<K, V>, newNode: RedBlackTreeNode<K, V>): RedBlackTreeNode<K, V>;
     /**
      * (Protected) Standard BST insert followed by red-black fix-up.
-     * @remarks Time O(log n), Space O(1)
+     * @remarks Time O(log n) average, Space O(1)
      * @param node - Node to insert.
      * @returns Status string: 'CREATED' or 'UPDATED'.
      */
@@ -283,14 +413,14 @@ export declare class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R
     protected _transplant(u: RedBlackTreeNode<K, V>, v: RedBlackTreeNode<K, V> | undefined): void;
     /**
      * (Protected) Restore red-black properties after insertion (recolor/rotate).
-     * @remarks Time O(log n), Space O(1)
+     * @remarks Time O(log n) average, Space O(1)
      * @param z - Recently inserted node.
      * @returns void
      */
     protected _insertFixup(z: RedBlackTreeNode<K, V> | undefined): void;
     /**
      * (Protected) Restore red-black properties after deletion (recolor/rotate).
-     * @remarks Time O(log n), Space O(1)
+     * @remarks Time O(log n) average, Space O(1)
      * @param node - Child that replaced the deleted node (may be undefined).
      * @returns void
      */

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BinaryTreeDeleteResult, BSTNOptKeyOrNode, EntryCallback, FamilyPosition, IterationType, RBTNColor, TreeCounterOptions } from '../../types';
+import type { BinaryTreeDeleteResult, BSTNOptKeyOrNode, BTNRep, EntryCallback, FamilyPosition, IterationType, NodePredicate, RBTNColor, TreeCounterOptions } from '../../types';
 import { BSTNode } from './bst';
 import { IBinaryTree } from '../../interfaces';
 import { RedBlackTree } from './red-black-tree';
@@ -154,15 +154,15 @@ export declare class TreeCounter<K = any, V = any, R = any> extends RedBlackTree
      * @param [count] - How much to increase the node's count (default 1).
      * @returns True if inserted/updated; false if ignored.
      */
-    add(keyNodeOrEntry: K | TreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V, count?: number): boolean;
+    set(keyNodeOrEntry: K | TreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V, count?: number): boolean;
     /**
      * Delete a node (or decrement its count) and rebalance if needed.
      * @remarks Time O(log N), Space O(1)
-     * @param keyNodeOrEntry - Key, node, or [key, value] entry identifying the node.
+     * @param keyNodeEntryRawOrPredicate - Key, node, or [key, value] entry identifying the node.
      * @param [ignoreCount] - If true, remove the node regardless of its count.
      * @returns Array of deletion results including deleted node and a rebalance hint when present.
      */
-    delete(keyNodeOrEntry: K | TreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, ignoreCount?: boolean): BinaryTreeDeleteResult<TreeCounterNode<K, V>>[];
+    delete(keyNodeEntryRawOrPredicate: BTNRep<K, V, TreeCounterNode<K, V>> | NodePredicate<TreeCounterNode<K, V> | null>, ignoreCount?: boolean): BinaryTreeDeleteResult<TreeCounterNode<K, V>>[];
     /**
      * Remove all nodes and reset aggregate counters.
      * @remarks Time O(N), Space O(1)

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

@@ -297,8 +297,8 @@ export declare class TreeMultiMap<K = any, V = any, R = any> extends RedBlackTre
      * @returns True if it's a TreeMultiMapNode, false otherwise.
      */
     isNode(keyNodeOrEntry: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): keyNodeOrEntry is TreeMultiMapNode<K, V>;
-    add(keyNodeOrEntry: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
-    add(key: K, value: V): boolean;
+    set(keyNodeOrEntry: K | TreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
+    set(key: K, value: V): boolean;
     /**
      * Delete a single value from the bucket at a given key. Removes the key if the bucket becomes empty.
      * @remarks Time O(log N), Space O(1)