data-structure-typed 2.2.8 → 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/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';
@@ -451,7 +451,6 @@ export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntry
      * @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 set.
-     * @param [values] - An optional parallel iterable of values.
      * @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>): boolean[];
@@ -483,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>[];
     /**

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_____

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)
+     */
+    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';
@@ -158,11 +158,11 @@ export declare class TreeCounter<K = any, V = any, R = any> extends RedBlackTree
     /**
      * 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/interfaces/binary-tree.d.ts

@@ -19,7 +19,7 @@ export interface IBinaryTree<K = any, V = any, R = any> {
     add(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
     set(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
     addMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): boolean[];
-    delete(keyNodeEntryRawOrPredicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
+    delete(keyNodeEntryRawOrPredicate: BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
     clear(): void;
     isEmpty(): boolean;
     get(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): V | undefined;