min-heap-typed 1.38.0 → 1.38.2

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

@@ -0,0 +1,100 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import { BST, BSTNode } from './bst';
+import type { AVLTreeNodeNested, AVLTreeOptions, BinaryTreeDeletedResult, BinaryTreeNodeKey } from '../../types';
+import { IBinaryTree } from '../../interfaces';
+export declare class AVLTreeNode<V = any, FAMILY extends AVLTreeNode<V, FAMILY> = AVLTreeNodeNested<V>> extends BSTNode<V, FAMILY> {
+    height: number;
+    constructor(key: BinaryTreeNodeKey, val?: V);
+}
+export declare class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends BST<N> implements IBinaryTree<N> {
+    /**
+     * This is a constructor function for an AVL tree data structure in TypeScript.
+     * @param {AVLTreeOptions} [options] - The `options` parameter is an optional object that can be passed to the
+     * constructor of the AVLTree class. It allows you to customize the behavior of the AVL tree by providing different
+     * options.
+     */
+    constructor(options?: AVLTreeOptions);
+    /**
+     * The function creates a new AVL tree node with the specified key and value.
+     * @param {BinaryTreeNodeKey} key - The key parameter is the key value that will be associated with
+     * the new node. It is used to determine the position of the node in the binary search tree.
+     * @param [val] - The parameter `val` is an optional value that can be assigned to the node. It is of
+     * type `N['val']`, which means it can be any value that is assignable to the `val` property of the
+     * node type `N`.
+     * @returns a new AVLTreeNode object with the specified key and value.
+     */
+    createNode(key: BinaryTreeNodeKey, val?: N['val']): N;
+    /**
+     * The function overrides the add method of a binary tree node and balances the tree after inserting
+     * a new node.
+     * @param {BinaryTreeNodeKey | N | null} keyOrNode - The `keyOrNode` parameter can accept either a
+     * `BinaryTreeNodeKey` or a `N` (which represents a node in the binary tree) or `null`.
+     * @param [val] - The `val` parameter is the value that you want to assign to the new node that you
+     * are adding to the binary search tree.
+     * @returns The method is returning the inserted node (`N`), `null`, or `undefined`.
+     */
+    add(keyOrNode: BinaryTreeNodeKey | N | null, val?: N['val']): N | null | undefined;
+    /**
+     * The function overrides the delete method of a binary tree and balances the tree after deleting a
+     * node if necessary.
+     * @param {N | BinaryTreeNodeKey} nodeOrKey - The `nodeOrKey` parameter can be either a node object
+     * (`N`) or a key value (`BinaryTreeNodeKey`).
+     * @returns The method is returning an array of `BinaryTreeDeletedResult<N>` objects.
+     */
+    delete(nodeOrKey: N | BinaryTreeNodeKey): BinaryTreeDeletedResult<N>[];
+    /**
+     * The function swaps the key, value, and height properties between two nodes in a binary tree.
+     * @param {N} srcNode - The `srcNode` parameter represents the source node that needs to be swapped
+     * with the `destNode`.
+     * @param {N} destNode - The `destNode` parameter represents the destination node where the values
+     * from the source node (`srcNode`) will be swapped to.
+     * @returns The method is returning the `destNode` after swapping its properties with the `srcNode`.
+     */
+    protected _swap(srcNode: N, destNode: N): N;
+    /**
+     * The function calculates the balance factor of a node in a binary tree.
+     * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
+     * @returns the balance factor of a given node. The balance factor is calculated by subtracting the
+     * height of the left subtree from the height of the right subtree.
+     */
+    protected _balanceFactor(node: N): number;
+    /**
+     * The function updates the height of a node in a binary tree based on the heights of its left and
+     * right children.
+     * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
+     */
+    protected _updateHeight(node: N): void;
+    /**
+     * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
+     * to restore balance in an AVL tree after inserting a node.
+     * @param {N} node - The `node` parameter in the `_balancePath` function represents the node in the
+     * AVL tree that needs to be balanced.
+     */
+    protected _balancePath(node: N): void;
+    /**
+     * The function `_balanceLL` performs a left-left rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    protected _balanceLL(A: N): void;
+    /**
+     * The `_balanceLR` function performs a left-right rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    protected _balanceLR(A: N): void;
+    /**
+     * The function `_balanceRR` performs a right-right rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    protected _balanceRR(A: N): void;
+    /**
+     * The function `_balanceRL` performs a right-left rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    protected _balanceRL(A: N): void;
+}

package/dist/data-structures/binary-tree/avl-tree.js

@@ -0,0 +1,341 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AVLTree = exports.AVLTreeNode = void 0;
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+const bst_1 = require("./bst");
+class AVLTreeNode extends bst_1.BSTNode {
+    constructor(key, val) {
+        super(key, val);
+        this.height = 0;
+    }
+}
+exports.AVLTreeNode = AVLTreeNode;
+class AVLTree extends bst_1.BST {
+    /**
+     * This is a constructor function for an AVL tree data structure in TypeScript.
+     * @param {AVLTreeOptions} [options] - The `options` parameter is an optional object that can be passed to the
+     * constructor of the AVLTree class. It allows you to customize the behavior of the AVL tree by providing different
+     * options.
+     */
+    constructor(options) {
+        super(options);
+    }
+    /**
+     * The function creates a new AVL tree node with the specified key and value.
+     * @param {BinaryTreeNodeKey} key - The key parameter is the key value that will be associated with
+     * the new node. It is used to determine the position of the node in the binary search tree.
+     * @param [val] - The parameter `val` is an optional value that can be assigned to the node. It is of
+     * type `N['val']`, which means it can be any value that is assignable to the `val` property of the
+     * node type `N`.
+     * @returns a new AVLTreeNode object with the specified key and value.
+     */
+    createNode(key, val) {
+        return new AVLTreeNode(key, val);
+    }
+    /**
+     * The function overrides the add method of a binary tree node and balances the tree after inserting
+     * a new node.
+     * @param {BinaryTreeNodeKey | N | null} keyOrNode - The `keyOrNode` parameter can accept either a
+     * `BinaryTreeNodeKey` or a `N` (which represents a node in the binary tree) or `null`.
+     * @param [val] - The `val` parameter is the value that you want to assign to the new node that you
+     * are adding to the binary search tree.
+     * @returns The method is returning the inserted node (`N`), `null`, or `undefined`.
+     */
+    add(keyOrNode, val) {
+        // TODO support node as a param
+        const inserted = super.add(keyOrNode, val);
+        if (inserted)
+            this._balancePath(inserted);
+        return inserted;
+    }
+    /**
+     * The function overrides the delete method of a binary tree and balances the tree after deleting a
+     * node if necessary.
+     * @param {N | BinaryTreeNodeKey} nodeOrKey - The `nodeOrKey` parameter can be either a node object
+     * (`N`) or a key value (`BinaryTreeNodeKey`).
+     * @returns The method is returning an array of `BinaryTreeDeletedResult<N>` objects.
+     */
+    delete(nodeOrKey) {
+        const deletedResults = super.delete(nodeOrKey);
+        for (const { needBalanced } of deletedResults) {
+            if (needBalanced) {
+                this._balancePath(needBalanced);
+            }
+        }
+        return deletedResults;
+    }
+    /**
+     * The function swaps the key, value, and height properties between two nodes in a binary tree.
+     * @param {N} srcNode - The `srcNode` parameter represents the source node that needs to be swapped
+     * with the `destNode`.
+     * @param {N} destNode - The `destNode` parameter represents the destination node where the values
+     * from the source node (`srcNode`) will be swapped to.
+     * @returns The method is returning the `destNode` after swapping its properties with the `srcNode`.
+     */
+    _swap(srcNode, destNode) {
+        const { key, val, height } = destNode;
+        const tempNode = this.createNode(key, val);
+        if (tempNode) {
+            tempNode.height = height;
+            destNode.key = srcNode.key;
+            destNode.val = srcNode.val;
+            destNode.height = srcNode.height;
+            srcNode.key = tempNode.key;
+            srcNode.val = tempNode.val;
+            srcNode.height = tempNode.height;
+        }
+        return destNode;
+    }
+    /**
+     * The function calculates the balance factor of a node in a binary tree.
+     * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
+     * @returns the balance factor of a given node. The balance factor is calculated by subtracting the
+     * height of the left subtree from the height of the right subtree.
+     */
+    _balanceFactor(node) {
+        if (!node.right)
+            // node has no right subtree
+            return -node.height;
+        else if (!node.left)
+            // node has no left subtree
+            return +node.height;
+        else
+            return node.right.height - node.left.height;
+    }
+    /**
+     * The function updates the height of a node in a binary tree based on the heights of its left and
+     * right children.
+     * @param {N} node - The parameter "node" represents a node in a binary tree data structure.
+     */
+    _updateHeight(node) {
+        if (!node.left && !node.right)
+            node.height = 0;
+        else if (!node.left) {
+            const rightHeight = node.right ? node.right.height : 0;
+            node.height = 1 + rightHeight;
+        }
+        else if (!node.right)
+            node.height = 1 + node.left.height;
+        else
+            node.height = 1 + Math.max(node.right.height, node.left.height);
+    }
+    /**
+     * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
+     * to restore balance in an AVL tree after inserting a node.
+     * @param {N} node - The `node` parameter in the `_balancePath` function represents the node in the
+     * AVL tree that needs to be balanced.
+     */
+    _balancePath(node) {
+        const path = this.getPathToRoot(node, false); // first O(log n) + O(log n)
+        for (let i = 0; i < path.length; i++) {
+            // second O(log n)
+            const A = path[i];
+            // Update Heights: After inserting a node, backtrack from the insertion point to the root node, updating the height of each node along the way.
+            this._updateHeight(A); // first O(1)
+            // Check Balance: Simultaneously with height updates, check if each node violates the balance property of an AVL tree.
+            // Balance Restoration: If a balance issue is discovered after inserting a node, it requires balance restoration operations. Balance restoration includes four basic cases where rotation operations need to be performed to fix the balance:
+            switch (this._balanceFactor(A) // second O(1)
+            ) {
+                case -2:
+                    if (A && A.left) {
+                        if (this._balanceFactor(A.left) <= 0) {
+                            // second O(1)
+                            // Left Rotation (LL Rotation): When the inserted node is in the left subtree of the left subtree, causing an imbalance.
+                            this._balanceLL(A);
+                        }
+                        else {
+                            // Left-Right Rotation (LR Rotation): When the inserted node is in the right subtree of the left subtree, causing an imbalance.
+                            this._balanceLR(A);
+                        }
+                    }
+                    break;
+                case +2:
+                    if (A && A.right) {
+                        if (this._balanceFactor(A.right) >= 0) {
+                            // Right Rotation (RR Rotation): When the inserted node is in the right subtree of the right subtree, causing an imbalance.
+                            this._balanceRR(A);
+                        }
+                        else {
+                            // Right-Left Rotation (RL Rotation): When the inserted node is in the left subtree of the right subtree, causing an imbalance.
+                            this._balanceRL(A);
+                        }
+                    }
+            }
+            // TODO So far, no sure if this is necessary that Recursive Repair: Once rotation operations are executed, it may cause imbalance issues at higher levels of the tree. Therefore, you need to recursively check and repair imbalance problems upwards until you reach the root node.
+        }
+    }
+    /**
+     * The function `_balanceLL` performs a left-left rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    _balanceLL(A) {
+        const parentOfA = A.parent;
+        const B = A.left;
+        A.parent = B;
+        if (B && B.right) {
+            B.right.parent = A;
+        }
+        if (B)
+            B.parent = parentOfA;
+        if (A === this.root) {
+            if (B)
+                this._setRoot(B);
+        }
+        else {
+            if ((parentOfA === null || parentOfA === void 0 ? void 0 : parentOfA.left) === A) {
+                parentOfA.left = B;
+            }
+            else {
+                if (parentOfA)
+                    parentOfA.right = B;
+            }
+        }
+        if (B) {
+            A.left = B.right;
+            B.right = A;
+        }
+        this._updateHeight(A);
+        if (B)
+            this._updateHeight(B);
+    }
+    /**
+     * The `_balanceLR` function performs a left-right rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    _balanceLR(A) {
+        const parentOfA = A.parent;
+        const B = A.left;
+        let C = null;
+        if (B) {
+            C = B.right;
+        }
+        if (A)
+            A.parent = C;
+        if (B)
+            B.parent = C;
+        if (C) {
+            if (C.left) {
+                C.left.parent = B;
+            }
+            if (C.right) {
+                C.right.parent = A;
+            }
+            C.parent = parentOfA;
+        }
+        if (A === this.root) {
+            if (C)
+                this._setRoot(C);
+        }
+        else {
+            if (parentOfA) {
+                if (parentOfA.left === A) {
+                    parentOfA.left = C;
+                }
+                else {
+                    parentOfA.right = C;
+                }
+            }
+        }
+        if (C) {
+            A.left = C.right;
+            if (B)
+                B.right = C.left;
+            C.left = B;
+            C.right = A;
+        }
+        this._updateHeight(A);
+        B && this._updateHeight(B);
+        C && this._updateHeight(C);
+    }
+    /**
+     * The function `_balanceRR` performs a right-right rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    _balanceRR(A) {
+        const parentOfA = A.parent;
+        const B = A.right;
+        A.parent = B;
+        if (B) {
+            if (B.left) {
+                B.left.parent = A;
+            }
+            B.parent = parentOfA;
+        }
+        if (A === this.root) {
+            if (B)
+                this._setRoot(B);
+        }
+        else {
+            if (parentOfA) {
+                if (parentOfA.left === A) {
+                    parentOfA.left = B;
+                }
+                else {
+                    parentOfA.right = B;
+                }
+            }
+        }
+        if (B) {
+            A.right = B.left;
+            B.left = A;
+        }
+        this._updateHeight(A);
+        B && this._updateHeight(B);
+    }
+    /**
+     * The function `_balanceRL` performs a right-left rotation to balance a binary tree.
+     * @param {N} A - A is a node in a binary tree.
+     */
+    _balanceRL(A) {
+        const parentOfA = A.parent;
+        const B = A.right;
+        let C = null;
+        if (B) {
+            C = B.left;
+        }
+        A.parent = C;
+        if (B)
+            B.parent = C;
+        if (C) {
+            if (C.left) {
+                C.left.parent = A;
+            }
+            if (C.right) {
+                C.right.parent = B;
+            }
+            C.parent = parentOfA;
+        }
+        if (A === this.root) {
+            if (C)
+                this._setRoot(C);
+        }
+        else {
+            if (parentOfA) {
+                if (parentOfA.left === A) {
+                    parentOfA.left = C;
+                }
+                else {
+                    parentOfA.right = C;
+                }
+            }
+        }
+        if (C)
+            A.right = C.left;
+        if (B && C)
+            B.left = C.right;
+        if (C)
+            C.left = A;
+        if (C)
+            C.right = B;
+        this._updateHeight(A);
+        B && this._updateHeight(B);
+        C && this._updateHeight(C);
+    }
+}
+exports.AVLTree = AVLTree;

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

@@ -0,0 +1,144 @@
+export declare class BinaryIndexedTree {
+    protected readonly _freq: number;
+    protected readonly _max: number;
+    /**
+     * The constructor initializes the properties of an object, including default frequency, maximum
+     * value, a freqMap data structure, the most significant bit, and the count of negative frequencies.
+     * @param  - - `frequency`: The default frequency value. It is optional and has a default
+     * value of 0.
+     */
+    constructor({ frequency, max }: {
+        frequency?: number;
+        max: number;
+    });
+    protected _freqMap: Record<number, number>;
+    get freqMap(): Record<number, number>;
+    set freqMap(value: Record<number, number>);
+    protected _msb: number;
+    get msb(): number;
+    set msb(value: number);
+    protected _negativeCount: number;
+    get negativeCount(): number;
+    set negativeCount(value: number);
+    get freq(): number;
+    get max(): number;
+    /**
+     * The function "readSingle" reads a single number from a specified index.
+     * @param {number} index - The `index` parameter is a number that represents the index of an element in a
+     * collection or array.
+     * @returns a number.
+     */
+    readSingle(index: number): number;
+    /**
+     * The "update" function updates the value at a given index by adding a delta and triggers a callback
+     * to notify of the change.
+     * @param {number} position - The `index` parameter represents the index of the element that needs to be
+     * updated in the data structure.
+     * @param {number} change - The "delta" parameter represents the change in value that needs to be
+     * applied to the frequency at the specified index.
+     */
+    update(position: number, change: number): void;
+    /**
+     * The function "writeSingle" checks the index and writes a single value with a given frequency.
+     * @param {number} index - The `index` parameter is a number that represents the index of an element. It
+     * is used to identify the specific element that needs to be written.
+     * @param {number} freq - The `freq` parameter represents the frequency value that needs to be
+     * written.
+     */
+    writeSingle(index: number, freq: number): void;
+    /**
+     * The read function takes a count parameter, checks if it is an integer, and returns the result of
+     * calling the _read function with the count parameter clamped between 0 and the maximum value.
+     * @param {number} count - The `count` parameter is a number that represents the number of items to
+     * read.
+     * @returns a number.
+     */
+    read(count: number): number;
+    /**
+     * The function returns the lower bound of a non-descending sequence that sums up to a given number.
+     * @param {number} sum - The `sum` parameter is a number that represents the target sum that we want
+     * to find in the sequence.
+     * @returns The lowerBound function is returning a number.
+     */
+    lowerBound(sum: number): number;
+    /**
+     * The upperBound function returns the index of the first element in a sequence that is greater than
+     * or equal to a given sum.
+     * @param {number} sum - The "sum" parameter is a number that represents the target sum that we want
+     * to find in the sequence.
+     * @returns The upperBound function is returning a number.
+     */
+    upperBound(sum: number): number;
+    /**
+     * The function returns the value of a specific index in a freqMap data structure, or a default value if
+     * the index is not found.
+     * @param {number} index - The `index` parameter is a number that represents the index of a node in a
+     * freqMap data structure.
+     * @returns a number.
+     */
+    protected _getFrequency(index: number): number;
+    /**
+     * The function _updateFrequency adds a delta value to the element at the specified index in the freqMap array.
+     * @param {number} index - The index parameter is a number that represents the index of the freqMap
+     * element that needs to be updated.
+     * @param {number} delta - The `delta` parameter represents the change in value that needs to be
+     * added to the freqMap at the specified `index`.
+     */
+    protected _updateFrequency(index: number, delta: number): void;
+    /**
+     * The function checks if the given index is valid and within the range.
+     * @param {number} index - The parameter "index" is of type number and represents the index value
+     * that needs to be checked.
+     */
+    protected _checkIndex(index: number): void;
+    /**
+     * The function calculates the sum of elements in an array up to a given index using a binary indexed
+     * freqMap.
+     * @param {number} index - The `index` parameter is a number that represents the index of an element in a
+     * data structure.
+     * @returns a number.
+     */
+    protected _readSingle(index: number): number;
+    /**
+     * The function `_updateNegativeCount` updates a counter based on changes in frequency values.
+     * @param {number} freqCur - The current frequency value.
+     * @param {number} freqNew - The freqNew parameter represents the new frequency value.
+     */
+    protected _updateNegativeCount(freqCur: number, freqNew: number): void;
+    /**
+     * The `_update` function updates the values in a binary indexed freqMap starting from a given index and
+     * propagating the changes to its parent nodes.
+     * @param {number} index - The `index` parameter is a number that represents the index of the element in
+     * the data structure that needs to be updated.
+     * @param {number} delta - The `delta` parameter represents the change in value that needs to be
+     * applied to the elements in the data structure.
+     */
+    protected _update(index: number, delta: number): void;
+    /**
+     * The `_writeSingle` function updates the frequency at a specific index and triggers a callback if
+     * the frequency has changed.
+     * @param {number} index - The `index` parameter is a number that represents the index of the element
+     * being modified or accessed.
+     * @param {number} freq - The `freq` parameter represents the new frequency value that needs to be
+     * written to the specified index `index`.
+     */
+    protected _writeSingle(index: number, freq: number): void;
+    /**
+     * The `_read` function calculates the sum of values in a binary freqMap up to a given count.
+     * @param {number} count - The `count` parameter is a number that represents the number of elements
+     * to read from the freqMap.
+     * @returns the sum of the values obtained from calling the `_getFrequency` method for each index in the
+     * range from `count` to 1.
+     */
+    protected _read(count: number): number;
+    /**
+     * The function `_binarySearch` performs a binary search to find the largest number that satisfies a given
+     * condition.
+     * @param {number} sum - The sum parameter is a number that represents the target sum value.
+     * @param before - The `before` parameter is a function that takes two numbers `x` and `y` as
+     * arguments and returns a boolean value. It is used to determine if `x` is less than or equal to
+     * `y`. The purpose of this function is to compare two numbers and determine their order.
+     * @returns the value of the variable "left".
+     */
+    protected _binarySearch(sum: number, before: (x: number, y: number) => boolean): number;
+}