heap-typed 2.1.1 → 2.1.2

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

@@ -1,754 +0,0 @@
-/**
- * data-structure-typed
- *
- * @author Pablo Zeng
- * @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 { IBinaryTree } from '../../interfaces';
-import { IterableEntryBase } from '../base';
-import { Range } from '../../common';
-/**
- * @template K - The type of the key.
- * @template V - The type of the value.
- */
-export declare class BinaryTreeNode<K = any, V = any> {
-    key: K;
-    value?: V;
-    parent?: BinaryTreeNode<K, V>;
-    /**
-     * Creates an instance of BinaryTreeNode.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param key - The key of the node.
-     * @param [value] - The value associated with the key.
-     */
-    constructor(key: K, value?: V);
-    _left?: BinaryTreeNode<K, V> | null | undefined;
-    /**
-     * Gets the left child of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The left child.
-     */
-    get left(): BinaryTreeNode<K, V> | null | undefined;
-    /**
-     * Sets the left child of the node and updates its parent reference.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param v - The node to set as the left child.
-     */
-    set left(v: BinaryTreeNode<K, V> | null | undefined);
-    _right?: BinaryTreeNode<K, V> | null | undefined;
-    /**
-     * Gets the right child of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The right child.
-     */
-    get right(): BinaryTreeNode<K, V> | null | undefined;
-    /**
-     * Sets the right child of the node and updates its parent reference.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param v - The node to set as the right child.
-     */
-    set right(v: BinaryTreeNode<K, V> | null | undefined);
-    _height: number;
-    /**
-     * Gets the height of the node (used in self-balancing trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @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;
-    /**
-     * Gets the color of the node (used in Red-Black trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The node's color.
-     */
-    get color(): RBTNColor;
-    /**
-     * Sets the color of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new color.
-     */
-    set color(value: RBTNColor);
-    _count: number;
-    /**
-     * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @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)
-     *
-     * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
-     */
-    get familyPosition(): FamilyPosition;
-}
-/**
- * A general Binary Tree implementation.
- *
- * @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.
- *
- * @template K - The type of the key.
- * @template V - The type of the value.
- * @template R - The type of the raw data object (if using `toEntryFn`).
- * 1. Two Children Maximum: Each node has at most two children.
- * 2. Left and Right Children: Nodes have distinct left and right children.
- * 3. Depth and Height: Depth is the number of edges from the root to a node; height is the maximum depth in the tree.
- * 4. Subtrees: Each child of a node forms the root of a subtree.
- * 5. Leaf Nodes: Nodes without children are leaves.
- * @example
- * // determine loan approval using a decision tree
- *     // Decision tree structure
- *     const loanDecisionTree = new BinaryTree<string>(
- *       ['stableIncome', 'goodCredit', 'Rejected', 'Approved', 'Rejected'],
- *       { isDuplicate: true }
- *     );
- *
- *     function determineLoanApproval(
- *       node?: BinaryTreeNode<string> | null,
- *       conditions?: { [key: string]: boolean }
- *     ): string {
- *       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;
- *
- *       // Check if a valid condition exists for the current node's key
- *       return conditions?.[node.key]
- *         ? determineLoanApproval(node.left, conditions)
- *         : determineLoanApproval(node.right, conditions);
- *     }
- *
- *     // Test case 1: Stable income and good credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: true })); // 'Approved'
- *
- *     // Test case 2: Stable income but poor credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: true, goodCredit: false })); // 'Rejected'
- *
- *     // Test case 3: No stable income
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: true })); // 'Rejected'
- *
- *     // Test case 4: No stable income and poor credit score
- *     console.log(determineLoanApproval(loanDecisionTree.root, { stableIncome: false, goodCredit: false })); // 'Rejected'
- * @example
- * // evaluate the arithmetic expression represented by the binary tree
- *     const expressionTree = new BinaryTree<number | string>(['+', 3, '*', null, null, 5, '-', null, null, 2, 8]);
- *
- *     function evaluate(node?: BinaryTreeNode<number | string> | null): number {
- *       if (!node) return 0;
- *
- *       if (typeof node.key === 'number') return node.key;
- *
- *       const leftValue = evaluate(node.left); // Evaluate the left subtree
- *       const rightValue = evaluate(node.right); // Evaluate the right subtree
- *
- *       // Perform the operation based on the current node's operator
- *       switch (node.key) {
- *         case '+':
- *           return leftValue + rightValue;
- *         case '-':
- *           return leftValue - rightValue;
- *         case '*':
- *           return leftValue * rightValue;
- *         case '/':
- *           return rightValue !== 0 ? leftValue / rightValue : 0; // Handle division by zero
- *         default:
- *           throw new Error(`Unsupported operator: ${node.key}`);
- *       }
- *     }
- *
- *     console.log(evaluate(expressionTree.root)); // -27
- */
-export declare class BinaryTree<K = any, V = any, R = any> extends IterableEntryBase<K, V | undefined> implements IBinaryTree<K, V, R> {
-    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.
-     *
-     * @param [keysNodesEntriesOrRaws=[]] - An iterable of items to add.
-     * @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>);
-    protected _isMapMode: boolean;
-    /**
-     * Gets whether the tree is in Map mode.
-     * @remarks In Map mode (default), values are stored in an external Map, and nodes only hold keys. If false, values are stored directly on the nodes. Time O(1)
-     *
-     * @returns True if in Map mode, false otherwise.
-     */
-    get isMapMode(): boolean;
-    protected _isDuplicate: boolean;
-    /**
-     * Gets whether the tree allows duplicate keys.
-     * @remarks Time O(1)
-     *
-     * @returns True if duplicates are allowed, false otherwise.
-     */
-    get isDuplicate(): boolean;
-    protected _store: Map<K, V | undefined>;
-    /**
-     * Gets the external value store (used in Map mode).
-     * @remarks Time O(1)
-     *
-     * @returns The map storing key-value pairs.
-     */
-    get store(): Map<K, V | undefined>;
-    protected _root?: BinaryTreeNode<K, V> | null | undefined;
-    /**
-     * Gets the root node of the tree.
-     * @remarks Time O(1)
-     *
-     * @returns The root node.
-     */
-    get root(): BinaryTreeNode<K, V> | null | undefined;
-    protected _size: number;
-    /**
-     * Gets the number of nodes in the tree.
-     * @remarks Time O(1)
-     *
-     * @returns The size of the tree.
-     */
-    get size(): number;
-    protected _NIL: BinaryTreeNode<K, V>;
-    /**
-     * Gets the sentinel NIL node (used in self-balancing trees like Red-Black Tree).
-     * @remarks Time O(1)
-     *
-     * @returns The NIL node.
-     */
-    get NIL(): BinaryTreeNode<K, V>;
-    protected _toEntryFn?: ToEntryFn<K, V, R>;
-    /**
-     * Gets the function used to convert raw data objects (R) into [key, value] entries.
-     * @remarks Time O(1)
-     *
-     * @returns The conversion function.
-     */
-    get toEntryFn(): ToEntryFn<K, V, R> | undefined;
-    /**
-     * (Protected) Creates a new node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param key - The key for the new node.
-     * @param [value] - The value for the new node (used if not in Map mode).
-     * @returns The newly created node.
-     */
-    _createNode(key: K, value?: V): BinaryTreeNode<K, V>;
-    /**
-     * Creates a new, empty tree of the same type and configuration.
-     * @remarks Time O(1) (excluding options cloning), Space O(1)
-     *
-     * @param [options] - Optional overrides for the new tree's options.
-     * @returns A new, empty tree instance.
-     */
-    createTree(options?: Partial<BinaryTreeOptions<K, V, R>>): this;
-    /**
-     * Ensures the input is a node. If it's a key or entry, it searches for the node.
-     * @remarks Time O(1) if a node is passed. O(N) if a key or entry is passed (due to `getNode` performing a full search). Space O(1) if iterative search, O(H) if recursive (where H is height, O(N) worst-case).
-     *
-     * @param keyNodeOrEntry - The item to resolve to a node.
-     * @param [iterationType=this.iterationType] - The traversal method to use if searching.
-     * @returns The resolved node, or null/undefined if not found or input is null/undefined.
-     */
-    ensureNode(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): BinaryTreeNode<K, V> | null | undefined;
-    /**
-     * Checks if the given item is a `BinaryTreeNode` instance.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeOrEntry - The item to check.
-     * @returns True if it's a node, false otherwise.
-     */
-    isNode(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is BinaryTreeNode<K, V>;
-    /**
-     * Checks if the given item is a raw data object (R) that needs conversion via `toEntryFn`.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeEntryOrRaw - The item to check.
-     * @returns True if it's a raw object, false otherwise.
-     */
-    isRaw(keyNodeEntryOrRaw: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R): keyNodeEntryOrRaw is R;
-    /**
-     * Checks if the given item is a "real" node (i.e., not null, undefined, or NIL).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeOrEntry - The item to check.
-     * @returns True if it's a real node, false otherwise.
-     */
-    isRealNode(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is BinaryTreeNode<K, V>;
-    /**
-     * Checks if the given item is either a "real" node or null.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeOrEntry - The item to check.
-     * @returns True if it's a real node or null, false otherwise.
-     */
-    isRealNodeOrNull(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is BinaryTreeNode<K, V> | null;
-    /**
-     * Checks if the given item is the sentinel NIL node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeOrEntry - The item to check.
-     * @returns True if it's the NIL node, false otherwise.
-     */
-    isNIL(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): boolean;
-    /**
-     * Checks if the given item is a `Range` object.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeEntryOrPredicate - The item to check.
-     * @returns True if it's a Range, false otherwise.
-     */
-    isRange(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V>> | Range<K>): keyNodeEntryOrPredicate is Range<K>;
-    /**
-     * Checks if a node is a leaf (has no real children).
-     * @remarks Time O(N) if a key/entry is passed (due to `ensureNode`). O(1) if a node is passed. Space O(1) or O(H) (from `ensureNode`).
-     *
-     * @param keyNodeOrEntry - The node to check.
-     * @returns True if the node is a leaf, false otherwise.
-     */
-    isLeaf(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): boolean;
-    /**
-     * Checks if the given item is a [key, value] entry pair.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param keyNodeOrEntry - The item to check.
-     * @returns True if it's an entry, false otherwise.
-     */
-    isEntry(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is BTNEntry<K, V>;
-    /**
-     * Checks if the given key is valid (comparable or null).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param key - The key to validate.
-     * @returns True if the key is valid, false otherwise.
-     */
-    isValidKey(key: any): key is K;
-    /**
-     * 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).
-     *
-     * @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;
-    /**
-     * 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).
-     *
-     * @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.
-     */
-    addMany(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`).
-     *
-     * @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`).
-     *
-     * @param keysNodesEntriesOrRaws - An iterable of items to add.
-     * @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;
-    /**
-     * 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.
-     * @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>>[];
-    /**
-     * 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).
-     *
-     * @template C - The type of the callback function.
-     * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
-     * @param [onlyOne=false] - If true, stops after finding the first match.
-     * @param [callback=this._DEFAULT_NODE_CALLBACK] - A function to call on matching nodes.
-     * @param [startNode=this._root] - The node to start the search from.
-     * @param [iterationType=this.iterationType] - Whether to use 'RECURSIVE' or 'ITERATIVE' search.
-     * @returns An array of results from the callback function for each matching node.
-     */
-    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>[];
-    /**
-     * Gets all nodes matching a predicate.
-     * @remarks Time O(N) (via `search`). Space O(H) or O(N) (via `search`).
-     *
-     * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
-     * @param [onlyOne=false] - If true, stops after finding the first match.
-     * @param [startNode=this._root] - The node to start the search from.
-     * @param [iterationType=this.iterationType] - The traversal method.
-     * @returns An array of matching nodes.
-     */
-    getNodes(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V>>, onlyOne?: boolean, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): BinaryTreeNode<K, V>[];
-    /**
-     * 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`).
-     *
-     * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
-     * @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.
-     */
-    getNode(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V> | null>, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): BinaryTreeNode<K, V> | null | undefined;
-    /**
-     * 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.
-     *
-     * @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).
-     * @param [iterationType=this.iterationType] - The traversal method (if not in Map mode).
-     * @returns The associated value, or undefined.
-     */
-    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;
-    /**
-     * 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`).
-     *
-     * @param [keyNodeEntryOrPredicate] - The key, node, entry, or predicate to check for.
-     * @param [startNode] - The node to start the search from.
-     * @param [iterationType] - The traversal method.
-     * @returns True if a matching node exists, false otherwise.
-     */
-    has(keyNodeEntryOrPredicate?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V>>, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): boolean;
-    /**
-     * Clears the tree of all nodes and values.
-     * @remarks Time O(N) if in Map mode (due to `_store.clear()`), O(1) otherwise. Space O(1)
-     */
-    clear(): void;
-    /**
-     * Checks if the tree is empty.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns True if the tree has no nodes, false otherwise.
-     */
-    isEmpty(): boolean;
-    /**
-     * Checks if the tree is perfectly balanced.
-     * @remarks A tree is perfectly balanced if the difference between min and max height is at most 1. Time O(N), as it requires two full traversals (`getMinHeight` and `getHeight`). Space O(H) or O(N) (from height calculation).
-     *
-     * @param [startNode=this._root] - The node to start checking from.
-     * @returns True if perfectly balanced, false otherwise.
-     */
-    isPerfectlyBalanced(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): boolean;
-    /**
-     * Checks if the tree is a valid Binary Search Tree (BST).
-     * @remarks Time O(N), as it must 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).
-     *
-     * @param [startNode=this._root] - The node to start checking from.
-     * @param [iterationType=this.iterationType] - The traversal method.
-     * @returns True if it's a valid BST, false otherwise.
-     */
-    isBST(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): boolean;
-    /**
-     * Gets the depth of a node (distance from `startNode`).
-     * @remarks Time O(H), where H is the depth of the `dist` node relative to `startNode`. O(N) worst-case. Space O(1).
-     *
-     * @param dist - The node to find the depth of.
-     * @param [startNode=this._root] - The node to measure depth from (defaults to root).
-     * @returns The depth (0 if `dist` is `startNode`).
-     */
-    getDepth(dist: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): number;
-    /**
-     * Gets the maximum height of the tree (longest path from startNode to a leaf).
-     * @remarks Time O(N), as it must visit every node. Space O(H) for recursive stack (O(N) worst-case) or O(N) for iterative stack (storing node + depth).
-     *
-     * @param [startNode=this._root] - The node to start measuring from.
-     * @param [iterationType=this.iterationType] - The traversal method.
-     * @returns The height ( -1 for an empty tree, 0 for a single-node tree).
-     */
-    getHeight(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): number;
-    /**
-     * Gets the minimum height of the tree (shortest path from startNode to a leaf).
-     * @remarks Time O(N), as it must visit every node. Space O(H) for recursive stack (O(N) worst-case) or O(N) for iterative (due to `depths` Map).
-     *
-     * @param [startNode=this._root] - The node to start measuring from.
-     * @param [iterationType=this.iterationType] - The traversal method.
-     * @returns The minimum height (-1 for empty, 0 for single node).
-     */
-    getMinHeight(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): number;
-    /**
-     * Gets the path from a given node up to the root.
-     * @remarks Time O(H), where H is the depth of the `beginNode`. O(N) worst-case. Space O(H) for the result array.
-     *
-     * @template C - The type of the callback function.
-     * @param beginNode - The node to start the path from.
-     * @param [callback=this._DEFAULT_NODE_CALLBACK] - A function to call on each node in the path.
-     * @param [isReverse=false] - If true, returns the path from root-to-node.
-     * @returns An array of callback results.
-     */
-    getPathToRoot<C extends NodeCallback<BinaryTreeNode<K, V> | undefined>>(beginNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, callback?: C, isReverse?: boolean): ReturnType<C>[];
-    /**
-     * Finds the leftmost node in a subtree (the node with the smallest key in a BST).
-     * @remarks Time O(H), where H is the height of the left spine. O(N) worst-case. Space O(H) for recursive/trampoline stack.
-     *
-     * @template C - The type of the callback function.
-     * @param [callback=this._DEFAULT_NODE_CALLBACK] - A function to call on the leftmost node.
-     * @param [startNode=this._root] - The subtree root to search from.
-     * @param [iterationType=this.iterationType] - The traversal method.
-     * @returns The callback result for the leftmost node.
-     */
-    getLeftMost<C extends NodeCallback<BinaryTreeNode<K, V> | undefined>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>;
-    /**
-     * Finds the rightmost node in a subtree (the node with the largest key in a BST).
-     * @remarks Time O(H), where H is the height of the right spine. O(N) worst-case. Space O(H) for recursive/trampoline stack.
-     *
-     * @template C - The type of the callback function.
-     * @param [callback=this._DEFAULT_NODE_CALLBACK] - A function to call on the rightmost node.
-     * @param [startNode=this._root] - The subtree root to search from.
-     * @param [iterationType=this.iterationType] - The traversal method.
-     * @returns The callback result for the rightmost node.
-     */
-    getRightMost<C extends NodeCallback<BinaryTreeNode<K, V> | undefined>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>;
-    /**
-     * Gets the Morris traversal predecessor (rightmost node in the left subtree, or node itself).
-     * @remarks This is primarily a helper for Morris traversal. Time O(H), where H is the height of the left subtree. O(N) worst-case. Space O(1).
-     *
-     * @param node - The node to find the predecessor for.
-     * @returns The Morris predecessor.
-     */
-    getPredecessor(node: BinaryTreeNode<K, V>): BinaryTreeNode<K, V>;
-    /**
-     * Gets the in-order successor of a node in a BST.
-     * @remarks Time O(H), where H is the tree height. O(N) worst-case. Space O(H) (due to `getLeftMost` stack).
-     *
-     * @param [x] - The node to find the successor of.
-     * @returns The successor node, or null/undefined if none exists.
-     */
-    getSuccessor(x?: K | BinaryTreeNode<K, V> | null): BinaryTreeNode<K, V> | null | undefined;
-    dfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback?: C, pattern?: DFSOrderPattern, onlyOne?: boolean, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
-    dfs<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, pattern?: DFSOrderPattern, onlyOne?: boolean, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: boolean): ReturnType<C>[];
-    bfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: false): ReturnType<C>[];
-    bfs<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: true): ReturnType<C>[];
-    /**
-     * Finds all leaf nodes in the tree.
-     * @remarks Time O(N), visits every node. Space O(H) for recursive stack or O(N) for iterative queue.
-     *
-     * @template C - The type of the callback function.
-     * @param [callback=this._DEFAULT_NODE_CALLBACK] - Function to call on each leaf node.
-     * @param [startNode=this._root] - The node to start from.
-     * @param [iterationType=this.iterationType] - The traversal method.
-     * @returns An array of callback results.
-     */
-    leaves<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
-    listLevels<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: false): ReturnType<C>[][];
-    listLevels<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: true): ReturnType<C>[][];
-    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.
-     *
-     * @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.
-     *
-     * @param predicate - A function to test each [key, value] pair.
-     * @param [thisArg] - `this` context for the predicate.
-     * @returns A new, filtered tree.
-     */
-    filter(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): this;
-    /**
-     * Creates a new tree by mapping each [key, value] pair to a new entry.
-     * @remarks Time O(N * M), where N is nodes in this tree, and M is size of the new tree during insertion. Space O(N) for the new tree.
-     *
-     * @template MK - New key type.
-     * @template MV - New value type.
-     * @template MR - New raw type.
-     * @param cb - A function to map each [key, value] pair.
-     * @param [options] - Options for the new tree.
-     * @param [thisArg] - `this` context for the callback.
-     * @returns A new, mapped tree.
-     */
-    map<MK = K, MV = V, MR = any>(cb: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BinaryTreeOptions<MK, MV, MR>>, thisArg?: unknown): BinaryTree<MK, MV, MR>;
-    /**
-     * Generates a string representation of the tree for visualization.
-     * @remarks Time O(N), visits every node. Space O(N*H) or O(N^2) in the worst case, as the string width can grow significantly.
-     *
-     * @param [startNode=this._root] - The node to start printing from.
-     * @param [options] - Options to control the output (e.g., show nulls).
-     * @returns The string representation of the tree.
-     */
-    toVisual(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, options?: BinaryTreePrintOptions): string;
-    /**
-     * Prints a visual representation of the tree to the console.
-     * @remarks Time O(N) (via `toVisual`). Space O(N*H) or O(N^2) (via `toVisual`).
-     *
-     * @param [options] - Options to control the output.
-     * @param [startNode=this._root] - The node to start printing from.
-     */
-    print(options?: BinaryTreePrintOptions, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): void;
-    protected _dfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback: C, pattern?: DFSOrderPattern, onlyOne?: boolean, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: boolean, shouldVisitLeft?: (node: BinaryTreeNode<K, V> | null | undefined) => boolean, shouldVisitRight?: (node: BinaryTreeNode<K, V> | null | undefined) => boolean, shouldVisitRoot?: (node: BinaryTreeNode<K, V> | null | undefined) => boolean, shouldProcessRoot?: (node: BinaryTreeNode<K, V> | null | undefined) => boolean): ReturnType<C>[];
-    /**
-     * (Protected) Gets the iterator for the tree (default in-order).
-     * @remarks Time O(N) for full iteration. O(H) to get the first element. Space O(H) for the iterative stack. O(H) for recursive stack.
-     *
-     * @param [node=this._root] - The node to start iteration from.
-     * @returns An iterator for [key, value] pairs.
-     */
-    protected _getIterator(node?: BinaryTreeNode<K, V> | null | undefined): IterableIterator<[K, V | undefined]>;
-    /**
-     * (Protected) Default callback function, returns the node's key.
-     * @remarks Time O(1)
-     *
-     * @param node - The node.
-     * @returns The node's key or undefined.
-     */
-    protected _DEFAULT_NODE_CALLBACK: (node: BinaryTreeNode<K, V> | null | undefined) => K | undefined;
-    /**
-     * (Protected) Snapshots the current tree's configuration options.
-     * @remarks Time O(1)
-     *
-     * @template TK, TV, TR - Generic types for the options.
-     * @returns The options object.
-     */
-    protected _snapshotOptions<TK = K, TV = V, TR = R>(): BinaryTreeOptions<TK, TV, TR>;
-    /**
-     * (Protected) Creates a new, empty instance of the same tree constructor.
-     * @remarks Time O(1)
-     *
-     * @template TK, TV, TR - Generic types for the new instance.
-     * @param [options] - Options for the new tree.
-     * @returns A new, empty tree.
-     */
-    protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<BinaryTreeOptions<TK, TV, TR>>): this;
-    /**
-     * (Protected) Creates a new instance of the same tree constructor, potentially with different generic types.
-     * @remarks Time O(N) (or as per constructor) due to processing the iterable.
-     *
-     * @template TK, TV, TR - Generic types for the new instance.
-     * @param [iter=[]] - An iterable to populate the new tree.
-     * @param [options] - Options for the new tree.
-     * @returns A new tree.
-     */
-    protected _createLike<TK = K, TV = V, TR = R>(iter?: Iterable<TK | BinaryTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<BinaryTreeOptions<TK, TV, TR>>): BinaryTree<TK, TV, TR>;
-    /**
-     * (Protected) Converts a key, node, or entry into a standardized [node, value] tuple.
-     * @remarks Time O(1)
-     *
-     * @param keyNodeOrEntry - The input item.
-     * @param [value] - An optional value (used if input is just a key).
-     * @returns A tuple of [node, value].
-     */
-    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).
-     *
-     * @param cloned - The new, empty tree instance to populate.
-     */
-    protected _clone(cloned: BinaryTree<K, V, R>): void;
-    /**
-     * (Protected) Recursive helper for `toVisual`.
-     * @remarks Time O(N), Space O(N*H) or O(N^2)
-     *
-     * @param node - The current node.
-     * @param options - Print options.
-     * @returns Layout information for this subtree.
-     */
-    protected _displayAux(node: BinaryTreeNode<K, V> | null | undefined, options: BinaryTreePrintOptions): NodeDisplayLayout;
-    /**
-     * (Protected) Swaps the key/value properties of two nodes.
-     * @remarks Time O(1)
-     *
-     * @param srcNode - The source node.
-     * @param destNode - The destination node.
-     * @returns The `destNode` (now holding `srcNode`'s properties).
-     */
-    protected _swapProperties(srcNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, destNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): BinaryTreeNode<K, V> | undefined;
-    /**
-     * (Protected) Replaces a node in the tree with a new node, maintaining children and parent links.
-     * @remarks Time O(1)
-     *
-     * @param oldNode - The node to be replaced.
-     * @param newNode - The node to insert.
-     * @returns The `newNode`.
-     */
-    protected _replaceNode(oldNode: BinaryTreeNode<K, V>, newNode: BinaryTreeNode<K, V>): BinaryTreeNode<K, V>;
-    /**
-     * (Protected) Sets the root node and clears its parent reference.
-     * @remarks Time O(1)
-     *
-     * @param v - The node to set as root.
-     */
-    protected _setRoot(v: BinaryTreeNode<K, V> | null | undefined): void;
-    /**
-     * (Protected) Converts a key, node, entry, or predicate into a standardized predicate function.
-     * @remarks Time O(1)
-     *
-     * @param keyNodeEntryOrPredicate - The item to convert.
-     * @returns A predicate function.
-     */
-    protected _ensurePredicate(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V>>): NodePredicate<BinaryTreeNode<K, V>>;
-    /**
-     * (Protected) Checks if an item is a predicate function.
-     * @remarks Time O(1)
-     *
-     * @param p - The item to check.
-     * @returns True if it's a function.
-     */
-    protected _isPredicate(p: any): p is NodePredicate<BinaryTreeNode<K, V>>;
-    /**
-     * (Protected) Extracts the key from a key, node, or entry.
-     * @remarks Time O(1)
-     *
-     * @param keyNodeOrEntry - The item.
-     * @returns The extracted key.
-     */
-    protected _extractKey(keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): K | null | undefined;
-    /**
-     * (Protected) Sets a value in the external store (Map mode).
-     * @remarks Time O(1) (average for Map.set).
-     *
-     * @param key - The key.
-     * @param value - The value.
-     * @returns True if successful.
-     */
-    protected _setValue(key: K | null | undefined, value: V | undefined): false | Map<K, V | undefined>;
-    /**
-     * (Protected) Clears all nodes from the tree.
-     * @remarks Time O(1)
-     */
-    protected _clearNodes(): void;
-    /**
-     * (Protected) Clears all values from the external store.
-     * @remarks Time O(N)
-     */
-    protected _clearValues(): void;
-}