heap-typed 1.51.5 → 1.51.8

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

@@ -106,27 +106,17 @@ class BinaryTree extends base_1.IterableEntryBase {
     constructor(keysOrNodesOrEntries = [], options) {
         super();
         this.iterationType = 'ITERATIVE';
-        this._extractor = (key) => (typeof key === 'number' ? key : Number(key));
         this._NIL = new BinaryTreeNode(NaN);
         this._DEFAULT_CALLBACK = (node) => (node ? node.key : undefined);
         if (options) {
-            const { iterationType, extractor } = options;
+            const { iterationType } = options;
             if (iterationType)
                 this.iterationType = iterationType;
-            if (extractor)
-                this._extractor = extractor;
         }
         this._size = 0;
         if (keysOrNodesOrEntries)
             this.addMany(keysOrNodesOrEntries);
     }
-    /**
-     * The function returns the value of the `_extractor` property.
-     * @returns The `_extractor` property is being returned.
-     */
-    get extractor() {
-        return this._extractor;
-    }
     /**
      * The function returns the root node, which can be of type NODE, null, or undefined.
      * @returns The method is returning the value of the `_root` property, which can be of type `NODE`,
@@ -225,23 +215,24 @@ class BinaryTree extends base_1.IterableEntryBase {
      * itself if it is not a valid node key.
      */
     ensureNode(keyOrNodeOrEntry, iterationType = 'ITERATIVE') {
+        if (keyOrNodeOrEntry === this.NIL)
+            return;
         if (this.isRealNode(keyOrNodeOrEntry)) {
             return keyOrNodeOrEntry;
         }
-        else if (this.isEntry(keyOrNodeOrEntry)) {
-            if (keyOrNodeOrEntry[0] === null)
-                return null;
-            if (keyOrNodeOrEntry[0] === undefined)
-                return;
-            return this.getNodeByKey(keyOrNodeOrEntry[0], iterationType);
-        }
-        else {
-            if (keyOrNodeOrEntry === null)
+        if (this.isEntry(keyOrNodeOrEntry)) {
+            const key = keyOrNodeOrEntry[0];
+            if (key === null)
                 return null;
-            if (keyOrNodeOrEntry === undefined)
+            if (key === undefined)
                 return;
-            return this.getNodeByKey(keyOrNodeOrEntry, iterationType);
+            return this.getNodeByKey(key, iterationType);
         }
+        if (keyOrNodeOrEntry === null)
+            return null;
+        if (keyOrNodeOrEntry === undefined)
+            return;
+        return this.getNodeByKey(keyOrNodeOrEntry, iterationType);
     }
     /**
      * The function checks if a given node is a real node or null.
@@ -426,8 +417,7 @@ class BinaryTree extends base_1.IterableEntryBase {
         const deletedResult = [];
         if (!this.root)
             return deletedResult;
-        if ((!callback || callback === this._DEFAULT_CALLBACK) && identifier instanceof BinaryTreeNode)
-            callback = (node => node);
+        callback = this._ensureCallback(identifier, callback);
         const curr = this.getNode(identifier, callback);
         if (!curr)
             return deletedResult;
@@ -499,11 +489,10 @@ class BinaryTree extends base_1.IterableEntryBase {
      * @returns an array of nodes of type `NODE`.
      */
     getNodes(identifier, callback = this._DEFAULT_CALLBACK, onlyOne = false, beginRoot = this.root, iterationType = this.iterationType) {
-        if ((!callback || callback === this._DEFAULT_CALLBACK) && identifier instanceof BinaryTreeNode)
-            callback = (node => node);
         beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
+        callback = this._ensureCallback(identifier, callback);
         const ans = [];
         if (iterationType === 'RECURSIVE') {
             const dfs = (cur) => {
@@ -584,33 +573,7 @@ class BinaryTree extends base_1.IterableEntryBase {
      * found in the binary tree. If no node is found, it returns `undefined`.
      */
     getNodeByKey(key, iterationType = 'ITERATIVE') {
-        if (!this.root)
-            return undefined;
-        if (iterationType === 'RECURSIVE') {
-            const dfs = (cur) => {
-                if (cur.key === key)
-                    return cur;
-                if (!cur.left && !cur.right)
-                    return;
-                if (cur.left)
-                    return dfs(cur.left);
-                if (cur.right)
-                    return dfs(cur.right);
-            };
-            return dfs(this.root);
-        }
-        else {
-            const stack = [this.root];
-            while (stack.length > 0) {
-                const cur = stack.pop();
-                if (cur) {
-                    if (cur.key === key)
-                        return cur;
-                    cur.left && stack.push(cur.left);
-                    cur.right && stack.push(cur.right);
-                }
-            }
-        }
+        return this.getNode(key, this._DEFAULT_CALLBACK, this.root, iterationType);
     }
     /**
      * Time Complexity: O(n)
@@ -639,8 +602,8 @@ class BinaryTree extends base_1.IterableEntryBase {
      * found, `undefined` is returned.
      */
     get(identifier, callback = this._DEFAULT_CALLBACK, beginRoot = this.root, iterationType = this.iterationType) {
-        var _a, _b;
-        return (_b = (_a = this.getNode(identifier, callback, beginRoot, iterationType)) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : undefined;
+        var _a;
+        return (_a = this.getNode(identifier, callback, beginRoot, iterationType)) === null || _a === void 0 ? void 0 : _a.value;
     }
     /**
      * Time Complexity: O(n)
@@ -668,8 +631,7 @@ class BinaryTree extends base_1.IterableEntryBase {
      * @returns a boolean value.
      */
     has(identifier, callback = this._DEFAULT_CALLBACK, beginRoot = this.root, iterationType = this.iterationType) {
-        if ((!callback || callback === this._DEFAULT_CALLBACK) && identifier instanceof BinaryTreeNode)
-            callback = (node => node);
+        callback = this._ensureCallback(identifier, callback);
         return this.getNodes(identifier, callback, true, beginRoot, iterationType).length > 0;
     }
     /**
@@ -743,7 +705,7 @@ class BinaryTree extends base_1.IterableEntryBase {
             const dfs = (cur, min, max) => {
                 if (!this.isRealNode(cur))
                     return true;
-                const numKey = this.extractor(cur.key);
+                const numKey = Number(cur.key);
                 if (numKey <= min || numKey >= max)
                     return false;
                 return dfs(cur.left, min, numKey) && dfs(cur.right, numKey, max);
@@ -764,7 +726,7 @@ class BinaryTree extends base_1.IterableEntryBase {
                         curr = curr.left;
                     }
                     curr = stack.pop();
-                    const numKey = this.extractor(curr.key);
+                    const numKey = Number(curr.key);
                     if (!this.isRealNode(curr) || (!checkMax && prev >= numKey) || (checkMax && prev <= numKey))
                         return false;
                     prev = numKey;
@@ -794,15 +756,15 @@ class BinaryTree extends base_1.IterableEntryBase {
      * @returns the depth of the `dist` relative to the `beginRoot`.
      */
     getDepth(dist, beginRoot = this.root) {
-        dist = this.ensureNode(dist);
-        beginRoot = this.ensureNode(beginRoot);
+        let distEnsured = this.ensureNode(dist);
+        const beginRootEnsured = this.ensureNode(beginRoot);
         let depth = 0;
-        while (dist === null || dist === void 0 ? void 0 : dist.parent) {
-            if (dist === beginRoot) {
+        while (distEnsured === null || distEnsured === void 0 ? void 0 : distEnsured.parent) {
+            if (distEnsured === beginRootEnsured) {
                 return depth;
             }
             depth++;
-            dist = dist.parent;
+            distEnsured = distEnsured.parent;
         }
         return depth;
     }
@@ -936,16 +898,16 @@ class BinaryTree extends base_1.IterableEntryBase {
     getPathToRoot(beginNode, isReverse = true) {
         // TODO to support get path through passing key
         const result = [];
-        beginNode = this.ensureNode(beginNode);
-        if (!beginNode)
+        let beginNodeEnsured = this.ensureNode(beginNode);
+        if (!beginNodeEnsured)
             return result;
-        while (beginNode.parent) {
+        while (beginNodeEnsured.parent) {
             // Array.push + Array.reverse is more efficient than Array.unshift
             // TODO may consider using Deque, so far this is not the performance bottleneck
-            result.push(beginNode);
-            beginNode = beginNode.parent;
+            result.push(beginNodeEnsured);
+            beginNodeEnsured = beginNodeEnsured.parent;
         }
-        result.push(beginNode);
+        result.push(beginNodeEnsured);
         return isReverse ? result.reverse() : result;
     }
     /**
@@ -1591,10 +1553,10 @@ class BinaryTree extends base_1.IterableEntryBase {
             console.log(`U for undefined
       `);
         if (opts.isShowNull)
-            console.log(`NODE for null
+            console.log(`N for null
       `);
         if (opts.isShowRedBlackNIL)
-            console.log(`S for Sentinel Node
+            console.log(`S for Sentinel Node(NIL)
       `);
         const display = (root) => {
             const [lines, , ,] = this._displayAux(root, opts);
@@ -1620,23 +1582,23 @@ class BinaryTree extends base_1.IterableEntryBase {
             const stack = [];
             let current = node;
             while (current || stack.length > 0) {
-                while (current && !isNaN(this.extractor(current.key))) {
+                while (this.isRealNode(current)) {
                     stack.push(current);
                     current = current.left;
                 }
                 current = stack.pop();
-                if (current && !isNaN(this.extractor(current.key))) {
+                if (this.isRealNode(current)) {
                     yield [current.key, current.value];
                     current = current.right;
                 }
             }
         }
         else {
-            if (node.left && !isNaN(this.extractor(node.key))) {
+            if (node.left && this.isRealNode(node)) {
                 yield* this[Symbol.iterator](node.left);
             }
             yield [node.key, node.value];
-            if (node.right && !isNaN(this.extractor(node.key))) {
+            if (node.right && this.isRealNode(node)) {
                 yield* this[Symbol.iterator](node.right);
             }
         }
@@ -1665,12 +1627,12 @@ class BinaryTree extends base_1.IterableEntryBase {
         else if (node === undefined && !isShowUndefined) {
             return emptyDisplayLayout;
         }
-        else if (node !== null && node !== undefined && isNaN(this.extractor(node.key)) && !isShowRedBlackNIL) {
+        else if (this.isNIL(node) && !isShowRedBlackNIL) {
             return emptyDisplayLayout;
         }
         else if (node !== null && node !== undefined) {
             // Display logic of normal nodes
-            const key = node.key, line = isNaN(this.extractor(key)) ? 'S' : this.extractor(key).toString(), width = line.length;
+            const key = node.key, line = this.isNIL(node) ? 'S' : key.toString(), width = line.length;
             return _buildNodeDisplay(line, width, this._displayAux(node.left, options), this._displayAux(node.right, options));
         }
         else {
@@ -1766,5 +1728,11 @@ class BinaryTree extends base_1.IterableEntryBase {
         }
         this._root = v;
     }
+    _ensureCallback(identifier, callback = this._DEFAULT_CALLBACK) {
+        if ((!callback || callback === this._DEFAULT_CALLBACK) && this.isNode(identifier)) {
+            callback = (node => node);
+        }
+        return callback;
+    }
 }
 exports.BinaryTree = BinaryTree;

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

@@ -5,11 +5,10 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BSTNested, BSTNodeNested, BSTOptions, BTNCallback, KeyOrNodeOrEntry } from '../../types';
-import { BSTNKeyOrNode, BSTVariant, CP, DFSOrderPattern, IterationType } from '../../types';
+import type { BSTNested, BSTNKeyOrNode, BSTNodeNested, BSTOptions, BTNCallback, Comparable, Comparator, CP, DFSOrderPattern, IterationType, KeyOrNodeOrEntry } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
-export declare class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNodeNested<K, V>> extends BinaryTreeNode<K, V, NODE> {
+export declare class BSTNode<K extends Comparable, V = any, NODE extends BSTNode<K, V, NODE> = BSTNodeNested<K, V>> extends BinaryTreeNode<K, V, NODE> {
     parent?: NODE;
     constructor(key: K, value?: V);
     protected _left?: NODE;
@@ -47,12 +46,13 @@ export declare class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE>
  * 6. Balance Variability: Can become unbalanced; special types maintain balance.
  * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
  */
-export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNode<K, V, BSTNodeNested<K, V>>, TREE extends BST<K, V, NODE, TREE> = BST<K, V, NODE, BSTNested<K, V, NODE>>> extends BinaryTree<K, V, NODE, TREE> implements IBinaryTree<K, V, NODE, TREE> {
+export declare class BST<K extends Comparable, V = any, NODE extends BSTNode<K, V, NODE> = BSTNode<K, V, BSTNodeNested<K, V>>, TREE extends BST<K, V, NODE, TREE> = BST<K, V, NODE, BSTNested<K, V, NODE>>> extends BinaryTree<K, V, NODE, TREE> implements IBinaryTree<K, V, NODE, TREE> {
     /**
-     * This is the constructor function for a TypeScript class that initializes a binary search tree with
-     * optional keys or nodes or entries and options.
-     * @param keysOrNodesOrEntries - An iterable object that contains keys, nodes, or entries. It is used
-     * to initialize the binary search tree with the provided keys, nodes, or entries.
+     * This is the constructor function for a Binary Search Tree class in TypeScript, which initializes
+     * the tree with keys, nodes, or entries and optional options.
+     * @param keysOrNodesOrEntries - The `keysOrNodesOrEntries` parameter is an iterable object that can
+     * contain keys, nodes, or entries. It is used to initialize the binary search tree with the provided
+     * keys, nodes, or entries.
      * @param [options] - The `options` parameter is an optional object that can contain additional
      * configuration options for the binary search tree. It can have the following properties:
      */
@@ -63,12 +63,12 @@ export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BS
      * @returns The `_root` property of the object, which is of type `NODE` or `undefined`.
      */
     get root(): NODE | undefined;
-    protected _variant: BSTVariant;
+    protected _comparator: Comparator<K>;
     /**
-     * The function returns the value of the _variant property.
-     * @returns The value of the `_variant` property.
+     * The function returns the value of the _comparator property.
+     * @returns The `_comparator` property is being returned.
      */
-    get variant(): BSTVariant;
+    get comparator(): Comparator<K>;
     /**
      * The function creates a new BSTNode with the given key and value and returns it.
      * @param {K} key - The key parameter is of type K, which represents the type of the key for the node
@@ -127,13 +127,11 @@ export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BS
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * The `add` function adds a new node to a binary tree, updating the value if the key already exists
-     * or inserting a new node if the key is unique.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can accept three types of values:
-     * @param {V} [value] - The `value` parameter represents the value associated with the key that is
-     * being added to the binary tree.
-     * @returns The method `add` returns either the newly added node (`newNode`) or `undefined` if the
-     * node was not added.
+     * The `add` function in TypeScript adds a new node to a binary search tree based on the key value,
+     * updating the value if the key already exists.
+     * @param keyOrNodeOrEntry - It is a parameter that can accept three types of values:
+     * @param {V} [value] - The value to be added to the binary search tree.
+     * @returns The method returns a boolean value.
      */
     add(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>, value?: V): boolean;
     /**
@@ -144,42 +142,26 @@ export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BS
      * Time Complexity: O(k log n)
      * Space Complexity: O(k + log n)
      *
-     * The `addMany` function in TypeScript adds multiple keys or nodes to a binary tree, optionally
-     * balancing the tree after each addition.
-     * @param keysOrNodesOrEntries - An iterable containing the keys, nodes, or entries to be added to
-     * the binary tree.
+     * The `addMany` function in TypeScript adds multiple keys or nodes to a data structure, balancing
+     * the structure if specified, and returns an array indicating whether each key or node was
+     * successfully inserted.
+     * @param keysOrNodesOrEntries - An iterable containing keys, nodes, or entries to be added to the
+     * data structure.
      * @param [values] - An optional iterable of values to be associated with the keys or nodes being
      * added. If provided, the values will be assigned to the corresponding keys or nodes in the same
      * order. If not provided, undefined will be assigned as the value for each key or node.
-     * @param [isBalanceAdd=true] - A boolean flag indicating whether the add operation should be
-     * balanced or not. If set to true, the add operation will be balanced using a binary search tree
-     * algorithm. If set to false, the add operation will not be balanced and the nodes will be added
-     * in the order they appear in the input.
-     * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
-     * type of iteration to use when adding multiple keys or nodes. It has a default value of
-     * `this.iterationType`, which suggests that it is a property of the current object.
-     * @returns The function `addMany` returns an array of nodes (`NODE`) or `undefined` values.
+     * @param [isBalanceAdd=true] - A boolean flag indicating whether the tree should be balanced after
+     * adding the elements. If set to true, the tree will be balanced using a binary search tree
+     * algorithm. If set to false, the elements will be added without balancing the tree. The default
+     * value is true.
+     * @param {IterationType} iterationType - The `iterationType` parameter is an optional parameter that
+     * specifies the type of iteration to use when adding multiple keys or nodes to the binary tree. It
+     * has a default value of `this.iterationType`, which means it will use the iteration type specified
+     * in the binary tree instance.
+     * @returns The function `addMany` returns an array of booleans indicating whether each key or node
+     * or entry was successfully inserted into the data structure.
      */
     addMany(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>>, values?: Iterable<V | undefined>, isBalanceAdd?: boolean, iterationType?: IterationType): boolean[];
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     *
-     * The function `getNodeByKey` searches for a node in a binary tree based on a given key, using
-     * either recursive or iterative methods.
-     * @param {K} key - The `key` parameter is the key value that we are searching for in the tree.
-     * It is used to identify the node that we want to retrieve.
-     * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
-     * type of iteration to use when searching for a node in the binary tree. It can have two possible
-     * values:
-     * @returns The function `getNodeByKey` returns a node (`NODE`) if a node with the specified key is
-     * found in the binary tree. If no node is found, it returns `undefined`.
-     */
-    getNodeByKey(key: K, iterationType?: IterationType): NODE | undefined;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(k + log n)
@@ -235,6 +217,25 @@ export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BS
      * @returns The method is returning a value of type `NODE | null | undefined`.
      */
     getNode<C extends BTNCallback<NODE>>(identifier: ReturnType<C> | undefined, callback?: C, beginRoot?: BSTNKeyOrNode<K, NODE>, iterationType?: IterationType): NODE | undefined;
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     */
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     *
+     * The function `getNodeByKey` searches for a node in a binary tree based on a given key, using
+     * either recursive or iterative methods.
+     * @param {K} key - The `key` parameter is the key value that we are searching for in the tree.
+     * It is used to identify the node that we want to retrieve.
+     * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
+     * type of iteration to use when searching for a node in the binary tree. It can have two possible
+     * values:
+     * @returns The function `getNodeByKey` returns a node (`NODE`) if a node with the specified key is
+     * found in the binary tree. If no node is found, it returns `undefined`.
+     */
+    getNodeByKey(key: K, iterationType?: IterationType): NODE | undefined;
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -304,24 +305,6 @@ export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BS
      * function.
      */
     listLevels<C extends BTNCallback<NODE>>(callback?: C, beginRoot?: KeyOrNodeOrEntry<K, V, NODE>, iterationType?: IterationType): ReturnType<C>[][];
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     */
-    /**
-     * Time Complexity: O(log n)
-     * Space Complexity: O(1)
-     *
-     * The `lastKey` function returns the key of the rightmost node in a binary tree, or the key of the
-     * leftmost node if the comparison result is greater than.
-     * @param {K | NODE | undefined} beginRoot - The `beginRoot` parameter is optional and can be of
-     * type `K`, `NODE`, or `undefined`. It represents the starting point for finding the last key in
-     * the binary tree. If not provided, it defaults to the root of the binary tree (`this.root`).
-     * @returns the key of the rightmost node in the binary tree if the comparison result is less than,
-     * the key of the leftmost node if the comparison result is greater than, and the key of the
-     * rightmost node otherwise. If no node is found, it returns 0.
-     */
-    lastKey(beginRoot?: KeyOrNodeOrEntry<K, V, NODE>): K | undefined;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
@@ -393,32 +376,4 @@ export declare class BST<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BS
      * can either be an object of type `NODE` or it can be `undefined`.
      */
     protected _setRoot(v: NODE | undefined): void;
-    /**
-     * The function compares two values using a comparator function and returns whether the first value
-     * is greater than, less than, or equal to the second value.
-     * @param {K} a - The parameter "a" is of type K.
-     * @param {K} b - The parameter "b" in the above code represents a K.
-     * @returns a value of type CP (ComparisonResult). The possible return values are 'GT' (greater
-     * than), 'LT' (less than), or 'EQ' (equal).
-     */
-    protected _compare(a: K, b: K): CP;
-    /**
-     * The function `_lt` compares two values `a` and `b` using an extractor function and returns true if
-     * `a` is less than `b` based on the specified variant.
-     * @param {K} a - The parameter "a" is of type "K", which means it can be any type. It represents the
-     * first value to be compared in the function.
-     * @param {K} b - The parameter `b` is of type `K`, which means it can be any type. It is used as one
-     * of the arguments for the comparison in the `_lt` function.
-     * @returns a boolean value.
-     */
-    protected _lt(a: K, b: K): boolean;
-    /**
-     * The function compares two values using a custom extractor function and returns true if the first
-     * value is greater than the second value.
-     * @param {K} a - The parameter "a" is of type K, which means it can be any type.
-     * @param {K} b - The parameter "b" is of type K, which means it can be any type. It is used as one
-     * of the arguments for the comparison in the function.
-     * @returns a boolean value.
-     */
-    protected _gt(a: K, b: K): boolean;
 }