tree-set-typed 2.3.0

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

@@ -0,0 +1,312 @@
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { BinaryTreeDeleteResult, 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
+ * // basic Red-Black Tree with simple number keys
+ *  // Create a simple Red-Black Tree with numeric keys
+ *     const tree = new RedBlackTree([5, 2, 8, 1, 9]);
+ *
+ *     tree.print();
+ *     //   _2___
+ *     //  /     \
+ *     //  1    _8_
+ *     //      /   \
+ *     //      5   9
+ *
+ *     // Verify the tree maintains sorted order
+ *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
+ *
+ *     // Check size
+ *     console.log(tree.size); // 5;
+ * @example
+ * // Red-Black Tree with key-value pairs for lookups
+ *  interface Employee {
+ *       id: number;
+ *       name: string;
+ *     }
+ *
+ *     // Create tree with employee data
+ *     const employees = new RedBlackTree<number, Employee>([
+ *       [1, { id: 1, name: 'Alice' }],
+ *       [3, { id: 3, name: 'Charlie' }],
+ *       [2, { id: 2, name: 'Bob' }]
+ *     ]);
+ *
+ *     // Retrieve employee by ID
+ *     const alice = employees.get(1);
+ *     console.log(alice?.name); // 'Alice';
+ *
+ *     // Verify sorted order by ID
+ *     console.log([...employees.keys()]); // [1, 2, 3];
+ * @example
+ * // Red-Black Tree range search for filtering
+ *  interface Product {
+ *       name: string;
+ *       price: number;
+ *     }
+ *
+ *     const products = new RedBlackTree<number, Product>([
+ *       [10, { name: 'Item A', price: 10 }],
+ *       [25, { name: 'Item B', price: 25 }],
+ *       [40, { name: 'Item C', price: 40 }],
+ *       [50, { name: 'Item D', price: 50 }]
+ *     ]);
+ *
+ *     // Find products in price range [20, 45]
+ *     const pricesInRange = products.rangeSearch([20, 45], node => {
+ *       return products.get(node)?.name;
+ *     });
+ *
+ *     console.log(pricesInRange); // ['Item B', 'Item C'];
+ * @example
+ * // Red-Black Tree as database index for stock market data
+ *  interface StockPrice {
+ *       symbol: string;
+ *       volume: number;
+ *       timestamp: Date;
+ *     }
+ *
+ *     // Simulate real-time stock price index
+ *     const priceIndex = new RedBlackTree<number, StockPrice>([
+ *       [142.5, { symbol: 'AAPL', volume: 1000000, timestamp: new Date() }],
+ *       [335.2, { symbol: 'MSFT', volume: 800000, timestamp: new Date() }],
+ *       [3285.04, { symbol: 'AMZN', volume: 500000, timestamp: new Date() }],
+ *       [267.98, { symbol: 'META', volume: 750000, timestamp: new Date() }],
+ *       [234.57, { symbol: 'GOOGL', volume: 900000, timestamp: new Date() }]
+ *     ]);
+ *
+ *     // Find highest-priced stock
+ *     const maxPrice = priceIndex.getRightMost();
+ *     console.log(priceIndex.get(maxPrice)?.symbol); // 'AMZN';
+ *
+ *     // Find stocks in price range [200, 400] for portfolio balancing
+ *     const stocksInRange = priceIndex.rangeSearch([200, 400], node => {
+ *       const stock = priceIndex.get(node);
+ *       return {
+ *         symbol: stock?.symbol,
+ *         price: node,
+ *         volume: stock?.volume
+ *       };
+ *     });
+ *
+ *     console.log(stocksInRange.length); // 3;
+ *     console.log(stocksInRange.some((s: any) => s.symbol === 'GOOGL')); // true;
+ *     console.log(stocksInRange.some((s: any) => s.symbol === 'META')); // true;
+ *     console.log(stocksInRange.some((s: any) => s.symbol === 'MSFT')); // true;
+ */
+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.
+     */
+    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.
+     * @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<RedBlackTreeOptions<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

@@ -0,0 +1,160 @@
+/**
+ * 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;
+}