tree-multimap-typed 2.1.1 → 2.2.0

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

@@ -1,3 +1,262 @@
-import type { BSTOptions } from './bst';
-export type RBTNColor = 'RED' | 'BLACK';
-export type RedBlackTreeOptions<K, V, R> = BSTOptions<K, V, R> & {};
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { BinaryTreeDeleteResult, BinaryTreeOptions, CRUD, EntryCallback, FamilyPosition, RBTNColor, RedBlackTreeOptions } from '../../types';
+import { BST } from './bst';
+import { IBinaryTree } from '../../interfaces';
+export declare class RedBlackTreeNode<K = any, V = any> {
+    key: K;
+    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.
+     */
+    constructor(key: K, value?: V, color?: RBTNColor);
+    _left?: RedBlackTreeNode<K, V> | null | undefined;
+    /**
+     * Get the left child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Left child node, or null/undefined.
+     */
+    get left(): RedBlackTreeNode<K, V> | null | undefined;
+    /**
+     * Set the left child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New left node, or null/undefined.
+     * @returns void
+     */
+    set left(v: RedBlackTreeNode<K, V> | null | undefined);
+    _right?: RedBlackTreeNode<K, V> | null | undefined;
+    /**
+     * Get the right child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Right child node, or null/undefined.
+     */
+    get right(): RedBlackTreeNode<K, V> | null | undefined;
+    /**
+     * Set the right child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New right node, or null/undefined.
+     * @returns void
+     */
+    set right(v: RedBlackTreeNode<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;
+}
+/**
+ * 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)
+ * @template K
+ * @template V
+ * @template R
+ * 1. Efficient self-balancing, but not completely balanced. Compared with AVLTree, the addition and deletion efficiency is high, but the query efficiency is slightly lower.
+ * 2. It is BST itself. Compared with Heap which is not completely ordered, RedBlackTree is completely ordered.
+ * @example
+ * // using Red-Black Tree as a price-based index for stock data
+ *     // Define the structure of individual stock records
+ *     interface StockRecord {
+ *       price: number; // Stock price (key for indexing)
+ *       symbol: string; // Stock ticker symbol
+ *       volume: number; // Trade volume
+ *     }
+ *
+ *     // Simulate stock market data as it might come from an external feed
+ *     const marketStockData: StockRecord[] = [
+ *       { price: 142.5, symbol: 'AAPL', volume: 1000000 },
+ *       { price: 335.2, symbol: 'MSFT', volume: 800000 },
+ *       { price: 3285.04, symbol: 'AMZN', volume: 500000 },
+ *       { price: 267.98, symbol: 'META', volume: 750000 },
+ *       { price: 234.57, symbol: 'GOOGL', volume: 900000 }
+ *     ];
+ *
+ *     // Extend the stock record type to include metadata for database usage
+ *     type StockTableRecord = StockRecord & { lastUpdated: Date };
+ *
+ *     // Create a Red-Black Tree to index stock records by price
+ *     // Simulates a database index with stock price as the key for quick lookups
+ *     const priceIndex = new RedBlackTree<number, StockTableRecord, StockRecord>(marketStockData, {
+ *       toEntryFn: stockRecord => [
+ *         stockRecord.price, // Use stock price as the key
+ *         {
+ *           ...stockRecord,
+ *           lastUpdated: new Date() // Add a timestamp for when the record was indexed
+ *         }
+ *       ]
+ *     });
+ *
+ *     // Query the stock with the highest price
+ *     const highestPricedStock = priceIndex.getRightMost();
+ *     console.log(priceIndex.get(highestPricedStock)?.symbol); // 'AMZN' // Amazon has the highest price
+ *
+ *     // Query stocks within a specific price range (200 to 400)
+ *     const stocksInRange = priceIndex.rangeSearch(
+ *       [200, 400], // Price range
+ *       node => priceIndex.get(node)?.symbol // Extract stock symbols for the result
+ *     );
+ *     console.log(stocksInRange); // ['GOOGL', 'META', 'MSFT']
+ */
+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;
+    /**
+     * Get the current root node.
+     * @remarks Time O(1), Space O(1)
+     * @returns Root node, or undefined.
+     */
+    get root(): RedBlackTreeNode<K, V> | undefined;
+    /**
+     * Create a red-black node for the given key/value (value ignored in map mode).
+     * @remarks Time O(1), Space O(1)
+     * @param key - See parameter type for details.
+     * @param [value] - See parameter type for details.
+     * @param color - See parameter type for details.
+     * @returns A new RedBlackTreeNode instance.
+     */
+    createNode(key: K, value?: V, color?: RBTNColor): RedBlackTreeNode<K, V>;
+    /**
+     * Type guard: check whether the input is a RedBlackTreeNode.
+     * @remarks Time O(1), Space O(1)
+     * @param keyNodeOrEntry - See parameter type for details.
+     * @returns True if the value is a RedBlackTreeNode.
+     */
+    isNode(keyNodeOrEntry: K | RedBlackTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is RedBlackTreeNode<K, V>;
+    /**
+     * Remove all nodes and clear the key→value store (if in map mode).
+     * @remarks Time O(n), Space O(1)
+     * @returns void
+     */
+    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.
+     */
+    add(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.
+     * @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>>[];
+    /**
+     * Transform entries into a like-kind red-black tree with possibly different key/value types.
+     * @remarks Time O(n), Space O(n)
+     * @template MK
+     * @template MV
+     * @template MR
+     * @param callback - Mapping function from (key, value, index, tree) to a new [key, value].
+     * @param [options] - See parameter type for details.
+     * @param [thisArg] - See parameter type for details.
+     * @returns A new RedBlackTree with mapped entries.
+     */
+    map<MK = K, MV = V, MR = any>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BinaryTreeOptions<MK, MV, MR>>, thisArg?: unknown): RedBlackTree<MK, MV, MR>;
+    protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): this;
+    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>;
+    protected _setRoot(v: RedBlackTreeNode<K, V> | undefined): void;
+    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)
+     * @param node - Node to insert.
+     * @returns Status string: 'CREATED' or 'UPDATED'.
+     */
+    protected _insert(node: RedBlackTreeNode<K, V>): CRUD;
+    /**
+     * (Protected) Transplant a subtree in place of another during deletion.
+     * @remarks Time O(1), Space O(1)
+     * @param u - Node to replace.
+     * @param v - Replacement subtree root (may be undefined).
+     * @returns void
+     */
+    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)
+     * @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)
+     * @param node - Child that replaced the deleted node (may be undefined).
+     * @returns void
+     */
+    protected _deleteFixup(node: RedBlackTreeNode<K, V> | undefined): void;
+    /**
+     * (Protected) Perform a left rotation around x.
+     * @remarks Time O(1), Space O(1)
+     * @param x - Pivot node to rotate around.
+     * @returns void
+     */
+    protected _leftRotate(x: RedBlackTreeNode<K, V> | undefined): void;
+    /**
+     * (Protected) Perform a right rotation around y.
+     * @remarks Time O(1), Space O(1)
+     * @param y - Pivot node to rotate around.
+     * @returns void
+     */
+    protected _rightRotate(y: RedBlackTreeNode<K, V> | undefined): void;
+}

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

@@ -1 +1,160 @@
-export type SegmentTreeNodeVal = number;
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { SegmentTreeNodeVal } from '../../types';
+export declare class SegmentTreeNode {
+    /**
+     * The constructor initializes the properties of a SegmentTreeNode object.
+     * @param {number} start - The `start` parameter represents the starting index of the segment covered
+     * by this node in a segment tree.
+     * @param {number} end - The `end` parameter represents the end index of the segment covered by this
+     * node in a segment tree.
+     * @param {number} sum - The `sum` parameter represents the sum of the values in the range covered by
+     * the segment tree node.
+     * @param {SegmentTreeNodeVal | undefined} [value] - The `value` parameter is an optional parameter
+     * of type `SegmentTreeNodeVal`. It represents the value associated with the segment tree node.
+     */
+    constructor(start: number, end: number, sum: number, value?: SegmentTreeNodeVal | undefined);
+    protected _start: number;
+    /**
+     * The function returns the value of the protected variable _start.
+     * @returns The start value, which is of type number.
+     */
+    get start(): number;
+    /**
+     * The above function sets the value of the "start" property.
+     * @param {number} value - The value parameter is of type number.
+     */
+    set start(value: number);
+    protected _end: number;
+    /**
+     * The function returns the value of the protected variable `_end`.
+     * @returns The value of the protected property `_end`.
+     */
+    get end(): number;
+    /**
+     * The above function sets the value of the "end" property.
+     * @param {number} value - The value parameter is a number that represents the new value for the end
+     * property.
+     */
+    set end(value: number);
+    protected _value: SegmentTreeNodeVal | undefined;
+    /**
+     * The function returns the value of a segment tree node.
+     * @returns The value being returned is either a `SegmentTreeNodeVal` object or `undefined`.
+     */
+    get value(): SegmentTreeNodeVal | undefined;
+    /**
+     * The function sets the value of a segment tree node.
+     * @param {SegmentTreeNodeVal | undefined} value - The `value` parameter is of type
+     * `SegmentTreeNodeVal` or `undefined`.
+     */
+    set value(value: SegmentTreeNodeVal | undefined);
+    protected _sum: number;
+    /**
+     * The function returns the value of the sum property.
+     * @returns The method is returning the value of the variable `_sum`.
+     */
+    get sum(): number;
+    /**
+     * The above function sets the value of the sum property.
+     * @param {number} value - The parameter "value" is of type "number".
+     */
+    set sum(value: number);
+    protected _left: SegmentTreeNode | undefined;
+    /**
+     * The function returns the left child of a segment tree node.
+     * @returns The `left` property of the `SegmentTreeNode` object is being returned. It is of type
+     * `SegmentTreeNode` or `undefined`.
+     */
+    get left(): SegmentTreeNode | undefined;
+    /**
+     * The function sets the value of the left property of a SegmentTreeNode object.
+     * @param {SegmentTreeNode | undefined} value - The value parameter is of type SegmentTreeNode or
+     * undefined.
+     */
+    set left(value: SegmentTreeNode | undefined);
+    protected _right: SegmentTreeNode | undefined;
+    /**
+     * The function returns the right child of a segment tree node.
+     * @returns The `getRight()` method is returning a value of type `SegmentTreeNode` or `undefined`.
+     */
+    get right(): SegmentTreeNode | undefined;
+    /**
+     * The function sets the right child of a segment tree node.
+     * @param {SegmentTreeNode | undefined} value - The `value` parameter is of type `SegmentTreeNode |
+     * undefined`. This means that it can accept either a `SegmentTreeNode` object or `undefined` as its
+     * value.
+     */
+    set right(value: SegmentTreeNode | undefined);
+}
+export declare class SegmentTree {
+    /**
+     * The constructor initializes the values, start, end, and root properties of an object.
+     * @param {number[]} values - An array of numbers that will be used to build a binary search tree.
+     * @param {number} [start] - The `start` parameter is the index of the first element in the `values` array that should
+     * be included in the range. If no value is provided for `start`, it defaults to 0, which means the range starts from
+     * the beginning of the array.
+     * @param {number} [end] - The "end" parameter is the index of the last element in the "values" array that should be
+     * included in the range. If not provided, it defaults to the index of the last element in the "values" array.
+     */
+    constructor(values: number[], start?: number, end?: number);
+    protected _values: number[];
+    /**
+     * The function returns an array of numbers.
+     * @returns An array of numbers is being returned.
+     */
+    get values(): number[];
+    protected _start: number;
+    /**
+     * The function returns the value of the protected variable _start.
+     * @returns The start value, which is of type number.
+     */
+    get start(): number;
+    protected _end: number;
+    /**
+     * The function returns the value of the protected variable `_end`.
+     * @returns The value of the protected property `_end`.
+     */
+    get end(): number;
+    protected _root: SegmentTreeNode | undefined;
+    /**
+     * The function returns the root node of a segment tree.
+     * @returns The `root` property of the class `SegmentTreeNode` or `undefined` if it is not defined.
+     */
+    get root(): SegmentTreeNode | undefined;
+    /**
+     * The build function creates a segment tree by recursively dividing the given range into smaller segments and assigning
+     * the sum of values to each segment.
+     * @param {number} start - The `start` parameter represents the starting index of the segment or range for which we are
+     * building the segment tree.
+     * @param {number} end - The "end" parameter represents the ending index of the segment or range for which we want to
+     * build a segment tree.
+     * @returns a SegmentTreeNode object.
+     */
+    build(start: number, end: number): SegmentTreeNode;
+    /**
+     * The function updates the value of a node in a segment tree and recalculates the sum of its children if they exist.
+     * @param {number} index - The index parameter represents the index of the node in the segment tree that needs to be
+     * updated.
+     * @param {number} sum - The `sum` parameter represents the new value that should be assigned to the `sum` property of
+     * the `SegmentTreeNode` at the specified `index`.
+     * @param {SegmentTreeNodeVal} [value] - The `value` parameter is an optional value that can be assigned to the `value`
+     * property of the `SegmentTreeNode` object. It is not currently used in the code, but you can uncomment the line `//
+     * cur.value = value;` and pass a value for `value` in the
+     * @returns The function does not return anything.
+     */
+    updateNode(index: number, sum: number, value?: SegmentTreeNodeVal): void;
+    /**
+     * The function `querySumByRange` calculates the sum of values within a given range in a segment tree.
+     * @param {number} indexA - The starting index of the range for which you want to calculate the sum.
+     * @param {number} indexB - The parameter `indexB` represents the ending index of the range for which you want to
+     * calculate the sum.
+     * @returns The function `querySumByRange` returns a number.
+     */
+    querySumByRange(indexA: number, indexB: number): number;
+}

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

@@ -1,2 +1,244 @@
-import type { RedBlackTreeOptions } from './red-black-tree';
-export type TreeCounterOptions<K, V, R> = RedBlackTreeOptions<K, V, R> & {};
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { BinaryTreeDeleteResult, BinaryTreeOptions, BSTNOptKeyOrNode, EntryCallback, FamilyPosition, IterationType, RBTNColor, TreeCounterOptions } from '../../types';
+import { BSTOptions } from '../../types';
+import { BSTNode } from './bst';
+import { IBinaryTree } from '../../interfaces';
+import { RedBlackTree } from './red-black-tree';
+/**
+ * RB-tree node with an extra 'count' field; keeps parent/child links.
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ */
+export declare class TreeCounterNode<K = any, V = any> {
+    key: K;
+    value?: V;
+    parent?: TreeCounterNode<K, V>;
+    /**
+     * Create a tree counter node.
+     * @remarks Time O(1), Space O(1)
+     * @param key - Key of the node.
+     * @param [value] - Value associated with the key (ignored in map mode).
+     * @param [count] - Initial count for this node (default 1).
+     * @param color - Initial color ('RED' or 'BLACK').
+     * @returns New TreeCounterNode instance.
+     */
+    constructor(key: K, value?: V, count?: number, color?: RBTNColor);
+    _left?: TreeCounterNode<K, V> | null | undefined;
+    /**
+     * Get the left child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Left child node, or null/undefined.
+     */
+    get left(): TreeCounterNode<K, V> | null | undefined;
+    /**
+     * Set the left child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New left child node, or null/undefined.
+     * @returns void
+     */
+    set left(v: TreeCounterNode<K, V> | null | undefined);
+    _right?: TreeCounterNode<K, V> | null | undefined;
+    /**
+     * Get the right child pointer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Right child node, or null/undefined.
+     */
+    get right(): TreeCounterNode<K, V> | null | undefined;
+    /**
+     * Set the right child and update its parent pointer.
+     * @remarks Time O(1), Space O(1)
+     * @param v - New right child node, or null/undefined.
+     * @returns void
+     */
+    set right(v: TreeCounterNode<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;
+}
+/**
+ * Red-Black Tree–based counter map (key → value with per-node count). Supports O(log N) updates and map-like mode.
+ * @remarks Time O(1), Space O(1)
+ * @template K
+ * @template V
+ * @template R
+ */
+export declare class TreeCounter<K = any, V = any, R = any> extends RedBlackTree<K, V, R> implements IBinaryTree<K, V, R> {
+    /**
+     * Create a TreeCounter and optionally bulk-insert items.
+     * @remarks Time O(N log N), Space O(N)
+     * @param [keysNodesEntriesOrRaws] - Iterable of keys/nodes/entries/raw items to insert.
+     * @param [options] - Options for TreeCounter (comparator, reverse, map mode).
+     * @returns New TreeCounter instance.
+     */
+    constructor(keysNodesEntriesOrRaws?: Iterable<K | TreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: TreeCounterOptions<K, V, R>);
+    protected _count: number;
+    /**
+     * Get the total aggregate count across all nodes.
+     * @remarks Time O(1), Space O(1)
+     * @returns Total count.
+     */
+    get count(): number;
+    /**
+     * Compute the total count by traversing the tree (sums node.count).
+     * @remarks Time O(N), Space O(H)
+     * @returns Total count recomputed from nodes.
+     */
+    getComputedCount(): number;
+    createNode(key: K, value?: V, color?: RBTNColor, count?: number): TreeCounterNode<K, V>;
+    /**
+     * Type guard: check whether the input is a TreeCounterNode.
+     * @remarks Time O(1), Space O(1)
+     * @returns True if the value is a TreeCounterNode.
+     */
+    isNode(keyNodeOrEntry: K | TreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is TreeCounterNode<K, V>;
+    /**
+     * Insert or increment a node and update aggregate count.
+     * @remarks Time O(log N), Space O(1)
+     * @param keyNodeOrEntry - Key, node, or [key, value] entry to insert.
+     * @param [value] - Value when a bare key is provided (ignored in map mode).
+     * @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;
+    /**
+     * 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 [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>>[];
+    /**
+     * Remove all nodes and reset aggregate counters.
+     * @remarks Time O(N), Space O(1)
+     * @returns void
+     */
+    clear(): void;
+    /**
+     * Rebuild the tree into a perfectly balanced form using in-order nodes.
+     * @remarks Time O(N), Space O(N)
+     * @param [iterationType] - Traversal style to use when constructing the balanced tree.
+     * @returns True if rebalancing succeeded (tree not empty).
+     */
+    perfectlyBalance(iterationType?: IterationType): boolean;
+    /**
+     * Create a new TreeCounter by mapping each [key, value] entry.
+     * @remarks Time O(N log N), Space O(N)
+     * @template MK
+     * @template MV
+     * @template MR
+     * @param callback - Function mapping (key, value, index, tree) → [newKey, newValue].
+     * @param [options] - Options for the output tree.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new TreeCounter with mapped entries.
+     */
+    map<MK = K, MV = V, MR = any>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BinaryTreeOptions<MK, MV, MR>>, thisArg?: unknown): TreeCounter<MK, MV, MR>;
+    /**
+     * Deep copy this tree, preserving map mode and aggregate counts.
+     * @remarks Time O(N), Space O(N)
+     * @returns A deep copy of this tree.
+     */
+    clone(): this;
+    /**
+     * (Protected) Create an empty instance of the same concrete class.
+     * @remarks Time O(1), Space O(1)
+     * @template TK
+     * @template TV
+     * @template TR
+     * @param [options] - Optional constructor options for the like-kind instance.
+     * @returns An empty like-kind instance.
+     */
+    protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<BSTOptions<TK, TV, TR>>): this;
+    /**
+     * (Protected) Create a like-kind instance and seed it from an iterable.
+     * @remarks Time O(N log N), Space O(N)
+     * @template TK
+     * @template TV
+     * @template TR
+     * @param iter - Iterable used to seed the new tree.
+     * @param [options] - Options merged with the current snapshot.
+     * @returns A like-kind TreeCounter built from the iterable.
+     */
+    protected _createLike<TK = K, TV = V, TR = R>(iter?: Iterable<TK | BSTNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<BSTOptions<TK, TV, TR>>): TreeCounter<TK, TV, TR>;
+    /**
+     * (Protected) Normalize input into a node plus its effective value and count.
+     * @remarks Time O(1), Space O(1)
+     * @param keyNodeOrEntry - Key, node, or [key, value] entry.
+     * @param [value] - Value used when a bare key is provided.
+     * @param [count] - Count increment to apply (default 1).
+     * @returns Tuple [node, value] where node may be undefined.
+     */
+    protected _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry: K | TreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V, count?: number): [TreeCounterNode<K, V> | undefined, V | undefined];
+    /**
+     * (Protected) Swap keys/values/counters between the source and destination nodes.
+     * @remarks Time O(1), Space O(1)
+     * @param srcNode - Source node (or key) whose properties will be moved.
+     * @param destNode - Destination node (or key) to receive properties.
+     * @returns Destination node after swap, or undefined.
+     */
+    protected _swapProperties(srcNode: BSTNOptKeyOrNode<K, TreeCounterNode<K, V>>, destNode: BSTNOptKeyOrNode<K, TreeCounterNode<K, V>>): TreeCounterNode<K, V> | undefined;
+    /**
+     * (Protected) Replace one node by another and adjust counters accordingly.
+     * @remarks Time O(1), Space O(1)
+     * @param oldNode - Node being replaced.
+     * @param newNode - Replacement node.
+     * @returns The new node after replacement.
+     */
+    protected _replaceNode(oldNode: TreeCounterNode<K, V>, newNode: TreeCounterNode<K, V>): TreeCounterNode<K, V>;
+}