stack-typed 1.48.2 → 1.48.3

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

@@ -83,17 +83,24 @@ class BinaryTree extends base_1.IterablePairBase {
     constructor(elements, options) {
         super();
         this.iterationType = types_1.IterationType.ITERATIVE;
+        this._extractor = (key) => Number(key);
         this._defaultOneParamCallback = (node) => node.key;
         if (options) {
-            const { iterationType } = options;
+            const { iterationType, extractor } = options;
             if (iterationType) {
                 this.iterationType = iterationType;
             }
+            if (extractor) {
+                this._extractor = extractor;
+            }
         }
         this._size = 0;
         if (elements)
             this.addMany(elements);
     }
+    get extractor() {
+        return this._extractor;
+    }
     get root() {
         return this._root;
     }
@@ -102,7 +109,7 @@ class BinaryTree extends base_1.IterablePairBase {
     }
     /**
      * Creates a new instance of BinaryTreeNode with the given key and value.
-     * @param {BTNKey} key - The key for the new node.
+     * @param {K} key - The key for the new node.
      * @param {V} value - The value for the new node.
      * @returns {N} - The newly created BinaryTreeNode.
      */
@@ -121,7 +128,7 @@ class BinaryTree extends base_1.IterablePairBase {
     }
     /**
      * The function "isNode" checks if an exemplar is an instance of the BinaryTreeNode class.
-     * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<V, N>`.
+     * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<K, V,N>`.
      * @returns a boolean value indicating whether the exemplar is an instance of the class N.
      */
     isNode(exemplar) {
@@ -130,7 +137,7 @@ class BinaryTree extends base_1.IterablePairBase {
     /**
      * The function `exemplarToNode` converts an exemplar of a binary tree node into an actual node
      * object.
-     * @param exemplar - BTNodeExemplar<V, N> - A generic type representing the exemplar parameter of the
+     * @param exemplar - BTNodeExemplar<K, V,N> - A generic type representing the exemplar parameter of the
      * function. It can be any type.
      * @returns a value of type `N` (which represents a node), or `null`, or `undefined`.
      */
@@ -156,7 +163,7 @@ class BinaryTree extends base_1.IterablePairBase {
         else if (this.isNode(exemplar)) {
             node = exemplar;
         }
-        else if (this.isNodeKey(exemplar)) {
+        else if (this.isNotNodeInstance(exemplar)) {
             node = this.createNode(exemplar);
         }
         else {
@@ -166,7 +173,7 @@ class BinaryTree extends base_1.IterablePairBase {
     }
     /**
      * The function checks if a given value is an entry in a binary tree node.
-     * @param kne - BTNodeExemplar<V, N> - A generic type representing a node in a binary tree. It has
+     * @param kne - BTNodeExemplar<K, V,N> - A generic type representing a node in a binary tree. It has
      * two type parameters V and N, representing the value and node type respectively.
      * @returns a boolean value.
      */
@@ -234,7 +241,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * The function `addMany` takes in an iterable of `BTNodeExemplar` objects, adds each object to the
      * current instance, and returns an array of the inserted nodes.
      * @param nodes - The `nodes` parameter is an iterable (such as an array or a set) of
-     * `BTNodeExemplar<V, N>` objects.
+     * `BTNodeExemplar<K, V,N>` objects.
      * @returns The function `addMany` returns an array of values, where each value is either of type
      * `N`, `null`, or `undefined`.
      */
@@ -334,11 +341,11 @@ class BinaryTree extends base_1.IterablePairBase {
      * Space Complexity: O(1)
      *
      * The function calculates the depth of a given node in a binary tree.
-     * @param {BTNKey | N | null | undefined} distNode - The `distNode` parameter represents the node in
-     * the binary tree whose depth we want to find. It can be of type `BTNKey`, `N`, `null`, or
+     * @param {K | N | null | undefined} distNode - The `distNode` parameter represents the node in
+     * the binary tree whose depth we want to find. It can be of type `K`, `N`, `null`, or
      * `undefined`.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
-     * from which we want to calculate the depth. It can be either a `BTNKey` (binary tree node key) or
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * from which we want to calculate the depth. It can be either a `K` (binary tree node key) or
      * `N` (binary tree node) or `null` or `undefined`. If no value is provided for `beginRoot
      * @returns the depth of the `distNode` relative to the `beginRoot`.
      */
@@ -365,9 +372,9 @@ class BinaryTree extends base_1.IterablePairBase {
      *
      * The function `getHeight` calculates the maximum height of a binary tree using either recursive or
      * iterative traversal.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node of the binary tree from which we want to calculate the height. It can be of type
-     * `BTNKey`, `N`, `null`, or `undefined`. If not provided, it defaults to `this.root`.
+     * `K`, `N`, `null`, or `undefined`. If not provided, it defaults to `this.root`.
      * @param iterationType - The `iterationType` parameter is used to determine whether to calculate the
      * height of the tree using a recursive approach or an iterative approach. It can have two possible
      * values:
@@ -412,9 +419,9 @@ class BinaryTree extends base_1.IterablePairBase {
      *
      * The `getMinHeight` function calculates the minimum height of a binary tree using either a
      * recursive or iterative approach.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node of the binary tree from which we want to calculate the minimum height. It can be of
-     * type `BTNKey`, `N`, `null`, or `undefined`. If no value is provided, it defaults to `this.root`.
+     * type `K`, `N`, `null`, or `undefined`. If no value is provided, it defaults to `this.root`.
      * @param iterationType - The `iterationType` parameter is used to determine the method of iteration
      * to calculate the minimum height of a binary tree. It can have two possible values:
      * @returns The function `getMinHeight` returns the minimum height of a binary tree.
@@ -475,8 +482,8 @@ class BinaryTree extends base_1.IterablePairBase {
      *
      * The function checks if a binary tree is perfectly balanced by comparing the minimum height and the
      * height of the tree.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for calculating the height and minimum height of a binary tree. It can be either a `BTNKey` (a key
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for calculating the height and minimum height of a binary tree. It can be either a `K` (a key
      * value of a binary tree node), `N` (a node of a binary tree), `null`, or `undefined`. If
      * @returns a boolean value.
      */
@@ -501,7 +508,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * matches the identifier. If set to true, the function will stop iterating once it finds a matching
      * node and return that node. If set to false (default), the function will continue iterating and
      * return all nodes that match the identifier.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node for the traversal. It can be either a key, a node object, or `null`/`undefined`. If
      * it is `null` or `undefined`, an empty array will be returned.
      * @param iterationType - The `iterationType` parameter determines the type of iteration used to
@@ -558,8 +565,8 @@ class BinaryTree extends base_1.IterablePairBase {
      * the binary tree. It is used to filter the nodes based on certain conditions. The `callback`
      * function should return a boolean value indicating whether the node should be included in the
      * result or not.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for the search in the binary tree. It can be specified as a `BTNKey` (a unique identifier for a
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for the search in the binary tree. It can be specified as a `K` (a unique identifier for a
      * node in the binary tree), a node object (`N`), or `null`/`undefined` to start the search from
      * @param iterationType - The `iterationType` parameter is a variable that determines the type of
      * iteration to be performed on the binary tree. It is used to specify whether the iteration should
@@ -584,7 +591,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the binary tree. It is used to determine if a node matches the given identifier. The `callback`
      * function should take a single parameter of type `N` (the type of the nodes in the binary tree) and
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
      * for searching the binary tree. It can be either a key value, a node object, or `null`/`undefined`.
      * If `null` or `undefined` is passed, the search will start from the root of the binary tree.
      * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
@@ -608,7 +615,7 @@ class BinaryTree extends base_1.IterablePairBase {
      *
      * The function `getNodeByKey` searches for a node in a binary tree by its key, using either
      * recursive or iterative iteration.
-     * @param {BTNKey} key - The `key` parameter is the key value that we are searching for in the tree.
+     * @param {K} key - The `key` parameter is the key value that we are searching for in the tree.
      * It is used to find the node with the matching key value.
      * @param iterationType - The `iterationType` parameter is used to determine whether the search for
      * the node with the given key should be performed iteratively or recursively. It has two possible
@@ -652,7 +659,7 @@ class BinaryTree extends base_1.IterablePairBase {
     /**
      * The function `ensureNode` returns the node corresponding to the given key if it is a valid node
      * key, otherwise it returns the key itself.
-     * @param {BTNKey | N | null | undefined} key - The `key` parameter can be of type `BTNKey`, `N`,
+     * @param {K | N | null | undefined} key - The `key` parameter can be of type `K`, `N`,
      * `null`, or `undefined`. It represents a key used to identify a node in a binary tree.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to be used when searching for a node by key. It has a default value of
@@ -661,7 +668,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * itself if it is not a valid node key.
      */
     ensureNode(key, iterationType = types_1.IterationType.ITERATIVE) {
-        return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
+        return this.isNotNodeInstance(key) ? this.getNodeByKey(key, iterationType) : key;
     }
     /**
      * Time Complexity: O(n)
@@ -676,8 +683,8 @@ class BinaryTree extends base_1.IterablePairBase {
      * the binary tree. It is used to determine whether a node matches the given identifier. The callback
      * function should return a value that can be compared to the identifier to determine if it is a
      * match.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for the search in the binary tree. It can be specified as a `BTNKey` (a unique identifier for a
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for the search in the binary tree. It can be specified as a `K` (a unique identifier for a
      * node), a node object of type `N`, or `null`/`undefined` to start the search from the root of
      * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
      * be performed when searching for a node in the binary tree. It is an optional parameter with a
@@ -715,8 +722,8 @@ class BinaryTree extends base_1.IterablePairBase {
      *
      * The function `getPathToRoot` returns an array of nodes from a given node to the root of a tree
      * structure, with the option to reverse the order of the nodes.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node from which you want to find the path to the root. It can be of type `BTNKey`, `N`,
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node from which you want to find the path to the root. It can be of type `K`, `N`,
      * `null`, or `undefined`.
      * @param [isReverse=true] - The `isReverse` parameter is a boolean flag that determines whether the
      * resulting path should be reversed or not. If `isReverse` is set to `true`, the path will be
@@ -748,8 +755,8 @@ class BinaryTree extends base_1.IterablePairBase {
      *
      * The function `getLeftMost` returns the leftmost node in a binary tree, either recursively or
      * iteratively.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
-     * for finding the leftmost node in a binary tree. It can be either a `BTNKey` (a key value), `N` (a
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting point
+     * for finding the leftmost node in a binary tree. It can be either a `K` (a key value), `N` (a
      * node), `null`, or `undefined`. If not provided, it defaults to `this.root`,
      * @param iterationType - The `iterationType` parameter is used to determine the type of iteration to
      * be performed when finding the leftmost node in a binary tree. It can have two possible values:
@@ -788,8 +795,8 @@ class BinaryTree extends base_1.IterablePairBase {
      *
      * The function `getRightMost` returns the rightmost node in a binary tree, either recursively or
      * iteratively.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node from which we want to find the rightmost node. It can be of type `BTNKey`, `N`,
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node from which we want to find the rightmost node. It can be of type `K`, `N`,
      * `null`, or `undefined`. If not provided, it defaults to `this.root`, which is a property of the
      * current object.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
@@ -829,7 +836,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * Space Complexity: O(1)
      *
      * The function `isSubtreeBST` checks if a given binary tree is a valid binary search tree.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the root
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the root
      * node of the binary search tree (BST) that you want to check if it is a subtree of another BST.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to use when checking if a subtree is a binary search tree (BST). It can have two
@@ -845,9 +852,10 @@ class BinaryTree extends base_1.IterablePairBase {
             const dfs = (cur, min, max) => {
                 if (!cur)
                     return true;
-                if (cur.key <= min || cur.key >= max)
+                const numKey = this.extractor(cur.key);
+                if (numKey <= min || numKey >= max)
                     return false;
-                return dfs(cur.left, min, cur.key) && dfs(cur.right, cur.key, max);
+                return dfs(cur.left, min, numKey) && dfs(cur.right, numKey, max);
             };
             return dfs(beginRoot, Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
         }
@@ -860,9 +868,10 @@ class BinaryTree extends base_1.IterablePairBase {
                     curr = curr.left;
                 }
                 curr = stack.pop();
-                if (!curr || prev >= curr.key)
+                const numKey = this.extractor(curr.key);
+                if (!curr || prev >= numKey)
                     return false;
-                prev = curr.key;
+                prev = numKey;
                 curr = curr.right;
             }
             return true;
@@ -897,8 +906,8 @@ class BinaryTree extends base_1.IterablePairBase {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the subtree traversal. It takes a single parameter, which is the current node being traversed, and
      * returns a value of any type.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
-     * starting node or key from which the subtree traversal should begin. It can be of type `BTNKey`,
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * starting node or key from which the subtree traversal should begin. It can be of type `K`,
      * `N`, `null`, or `undefined`. If not provided, the `root` property of the current object is used as
      * the default value.
      * @param iterationType - The `iterationType` parameter determines the type of traversal to be
@@ -980,13 +989,13 @@ class BinaryTree extends base_1.IterablePairBase {
         return this.isRealNode(node) || node === null;
     }
     /**
-     * The function "isNodeKey" checks if a potential key is a number.
+     * The function "isNotNodeInstance" checks if a potential key is a number.
      * @param {any} potentialKey - The potentialKey parameter is of type any, which means it can be any
      * data type.
      * @returns a boolean value indicating whether the potentialKey is of type number or not.
      */
-    isNodeKey(potentialKey) {
-        return typeof potentialKey === 'number';
+    isNotNodeInstance(potentialKey) {
+        return !(potentialKey instanceof BinaryTreeNode);
     }
     /**
      * Time complexity: O(n)
@@ -1000,7 +1009,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * `null`, or `undefined`, and returns a value of any type. The default value for this parameter is
      * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter determines the order in which the
      * nodes are traversed during the depth-first search. It can have one of the following values:
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
      * for the depth-first search traversal. It can be specified as a key, a node object, or
      * `null`/`undefined`. If not provided, the `beginRoot` will default to the root node of the tree.
      * @param {IterationType} iterationType - The `iterationType` parameter determines the type of
@@ -1126,7 +1135,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the breadth-first search traversal. It takes a single parameter, which is the current node being
      * visited, and returns a value of any type.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node for the breadth-first search traversal. It can be specified as a key, a node object,
      * or `null`/`undefined` to indicate the root of the tree. If not provided, the `root` property of
      * the class is used as
@@ -1200,9 +1209,9 @@ class BinaryTree extends base_1.IterablePairBase {
      * @param {C} callback - The `callback` parameter is a function that will be called for each node in
      * the tree. It takes a single parameter, which can be of type `N`, `null`, or `undefined`, and
      * returns a value of any type.
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter represents the
      * starting node for traversing the tree. It can be either a node object (`N`), a key value
-     * (`BTNKey`), `null`, or `undefined`. If not provided, it defaults to the root node of the tree.
+     * (`K`), `null`, or `undefined`. If not provided, it defaults to the root node of the tree.
      * @param iterationType - The `iterationType` parameter determines the type of iteration to be
      * performed on the tree. It can have two possible values:
      * @param [includeNull=false] - The `includeNull` parameter is a boolean value that determines
@@ -1262,7 +1271,7 @@ class BinaryTree extends base_1.IterablePairBase {
     }
     /**
      * The function `getPredecessor` returns the predecessor node of a given node in a binary tree.
-     * @param {BTNKey | N | null | undefined} node - The `node` parameter can be of type `BTNKey`, `N`,
+     * @param {K | N | null | undefined} node - The `node` parameter can be of type `K`, `N`,
      * `null`, or `undefined`.
      * @returns The function `getPredecessor` returns a value of type `N | undefined`.
      */
@@ -1285,7 +1294,7 @@ class BinaryTree extends base_1.IterablePairBase {
     }
     /**
      * The function `getSuccessor` returns the next node in a binary tree given a current node.
-     * @param {BTNKey | N | null} [x] - The parameter `x` can be of type `BTNKey`, `N`, or `null`.
+     * @param {K | N | null} [x] - The parameter `x` can be of type `K`, `N`, or `null`.
      * @returns the successor of the given node or key. The successor is the node that comes immediately
      * after the given node in the inorder traversal of the binary tree.
      */
@@ -1314,7 +1323,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * @param {DFSOrderPattern} [pattern=in] - The `pattern` parameter in the `morris` function
      * determines the order in which the nodes of a binary tree are traversed. It can have one of the
      * following values:
-     * @param {BTNKey | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
+     * @param {K | N | null | undefined} beginRoot - The `beginRoot` parameter is the starting node
      * for the traversal. It can be specified as a key, a node object, or `null`/`undefined` to indicate
      * the root of the tree. If no value is provided, the default value is the root of the tree.
      * @returns The function `morris` returns an array of values that are the result of invoking the
@@ -1480,7 +1489,7 @@ class BinaryTree extends base_1.IterablePairBase {
         return newTree;
     }
     // // TODO Type error, need to return a TREE<NV> that is a value type only for callback function.
-    // // map<NV>(callback: (entry: [BTNKey, V | undefined], tree: this) => NV) {
+    // // map<NV>(callback: (entry: [K, V | undefined], tree: this) => NV) {
     // //   const newTree = this.createTree();
     // //   for (const [key, value] of this) {
     // //     newTree.add(key, callback([key, value], this));
@@ -1490,7 +1499,7 @@ class BinaryTree extends base_1.IterablePairBase {
     //
     /**
      * The `print` function is used to display a binary tree structure in a visually appealing way.
-     * @param {BTNKey | N | null | undefined} [beginRoot=this.root] - The `root` parameter is of type `BTNKey | N | null |
+     * @param {K | N | null | undefined} [beginRoot=this.root] - The `root` parameter is of type `K | N | null |
      * undefined`. It represents the root node of a binary tree. The root node can have one of the
      * following types:
      * @param {BinaryTreePrintOptions} [options={ isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false}] - Options object that controls printing behavior. You can specify whether to display undefined, null, or sentinel nodes.
@@ -1524,23 +1533,23 @@ class BinaryTree extends base_1.IterablePairBase {
             const stack = [];
             let current = node;
             while (current || stack.length > 0) {
-                while (current && !isNaN(current.key)) {
+                while (current && !isNaN(this.extractor(current.key))) {
                     stack.push(current);
                     current = current.left;
                 }
                 current = stack.pop();
-                if (current && !isNaN(current.key)) {
+                if (current && !isNaN(this.extractor(current.key))) {
                     yield [current.key, current.value];
                     current = current.right;
                 }
             }
         }
         else {
-            if (node.left && !isNaN(node.key)) {
+            if (node.left && !isNaN(this.extractor(node.key))) {
                 yield* this[Symbol.iterator](node.left);
             }
             yield [node.key, node.value];
-            if (node.right && !isNaN(node.key)) {
+            if (node.right && !isNaN(this.extractor(node.key))) {
                 yield* this[Symbol.iterator](node.right);
             }
         }
@@ -1555,12 +1564,12 @@ class BinaryTree extends base_1.IterablePairBase {
         else if (node === undefined && !isShowUndefined) {
             return emptyDisplayLayout;
         }
-        else if (node !== null && node !== undefined && isNaN(node.key) && !isShowRedBlackNIL) {
+        else if (node !== null && node !== undefined && isNaN(this.extractor(node.key)) && !isShowRedBlackNIL) {
             return emptyDisplayLayout;
         }
         else if (node !== null && node !== undefined) {
             // Display logic of normal nodes
-            const key = node.key, line = isNaN(key) ? 'S' : key.toString(), width = line.length;
+            const key = node.key, line = isNaN(this.extractor(key)) ? 'S' : this.extractor(key).toString(), width = line.length;
             return _buildNodeDisplay(line, width, this._displayAux(node.left, options), this._displayAux(node.right, options));
         }
         else {
@@ -1647,7 +1656,7 @@ class BinaryTree extends base_1.IterablePairBase {
      * If the parent node is null, the function also returns undefined.
      */
     _addTo(newNode, parent) {
-        if (this.isNodeKey(parent))
+        if (this.isNotNodeInstance(parent))
             parent = this.getNode(parent);
         if (parent) {
             // When all leaf nodes are null, it will no longer be possible to add new entity nodes to this binary tree.

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

@@ -5,13 +5,13 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { BSTNested, BSTNodeKeyOrNode, BSTNodeNested, BSTOptions, BTNCallback, BTNKey, BTNodeExemplar, Comparator } from '../../types';
-import { CP, IterationType } from '../../types';
+import type { BSTNested, BSTNodeKeyOrNode, BSTNodeNested, BSTOptions, BTNCallback, BTNodeExemplar } from '../../types';
+import { BSTVariant, CP, IterationType } from '../../types';
 import { BinaryTree, BinaryTreeNode } from './binary-tree';
 import { IBinaryTree } from '../../interfaces';
-export declare class BSTNode<V = any, N extends BSTNode<V, N> = BSTNodeNested<V>> extends BinaryTreeNode<V, N> {
+export declare class BSTNode<K = any, V = any, N extends BSTNode<K, V, N> = BSTNodeNested<K, V>> extends BinaryTreeNode<K, V, N> {
     parent?: N;
-    constructor(key: BTNKey, value?: V);
+    constructor(key: K, value?: V);
     protected _left?: N;
     /**
      * Get the left child node.
@@ -42,7 +42,7 @@ export declare class BSTNode<V = any, N extends BSTNode<V, N> = BSTNodeNested<V>
  * 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<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>, TREE extends BST<V, N, TREE> = BST<V, N, BSTNested<V, N>>> extends BinaryTree<V, N, TREE> implements IBinaryTree<V, N, TREE> {
+export declare class BST<K = any, V = any, N extends BSTNode<K, V, N> = BSTNode<K, V, BSTNodeNested<K, V>>, TREE extends BST<K, V, N, TREE> = BST<K, V, N, BSTNested<K, V, N>>> extends BinaryTree<K, V, N, TREE> implements IBinaryTree<K, V, N, TREE> {
     /**
      * This is the constructor function for a binary search tree class in TypeScript, which initializes
      * the tree with optional elements and options.
@@ -51,19 +51,20 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * @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:
      */
-    constructor(elements?: Iterable<BTNodeExemplar<V, N>>, options?: Partial<BSTOptions>);
+    constructor(elements?: Iterable<BTNodeExemplar<K, V, N>>, options?: Partial<BSTOptions<K>>);
     protected _root?: N;
     get root(): N | undefined;
-    comparator: Comparator<BTNKey>;
+    protected _variant: BSTVariant;
+    get variant(): BSTVariant;
     /**
      * The function creates a new binary search tree node with the given key and value.
-     * @param {BTNKey} key - The key parameter is the key value that will be associated with
+     * @param {K} 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 [value] - The parameter `value` is an optional value that can be assigned to the node. It
      * represents the value associated with the node in a binary search tree.
      * @returns a new instance of the BSTNode class with the specified key and value.
      */
-    createNode(key: BTNKey, value?: V): N;
+    createNode(key: K, value?: V): N;
     /**
      * The function creates a new binary search tree with the specified options.
      * @param [options] - The `options` parameter is an optional object that allows you to customize the
@@ -71,20 +72,20 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * that defines various options for creating a binary search tree.
      * @returns a new instance of the BST class with the specified options.
      */
-    createTree(options?: Partial<BSTOptions>): TREE;
+    createTree(options?: Partial<BSTOptions<K>>): TREE;
     /**
      * The function checks if an exemplar is an instance of BSTNode.
-     * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<V, N>`.
+     * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<K, V, N>`.
      * @returns a boolean value indicating whether the exemplar is an instance of the BSTNode class.
      */
-    isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N;
+    isNode(exemplar: BTNodeExemplar<K, V, N>): exemplar is N;
     /**
      * The function `exemplarToNode` takes an exemplar and returns a corresponding node if the exemplar
      * is valid, otherwise it returns undefined.
-     * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`.
+     * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<K, V, N>`.
      * @returns a variable `node` which is of type `N` or `undefined`.
      */
-    exemplarToNode(exemplar: BTNodeExemplar<V, N>): N | undefined;
+    exemplarToNode(exemplar: BTNodeExemplar<K, V, N>): N | undefined;
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
      * Space Complexity: O(1) - Constant space is used.
@@ -99,7 +100,7 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * @returns The method returns either the newly added node (`newNode`) or `undefined` if the input
      * (`keyOrNodeOrEntry`) is null, undefined, or does not match any of the expected types.
      */
-    add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined;
+    add(keyOrNodeOrEntry: BTNodeExemplar<K, V, N>): N | undefined;
     /**
      * Time Complexity: O(k log n) - Adding each element individually in a balanced tree.
      * Space Complexity: O(k) - Additional space is required for the sorted array.
@@ -120,27 +121,7 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * tree instance.
      * @returns The `addMany` function returns an array of `N` or `undefined` values.
      */
-    addMany(keysOrNodesOrEntries: Iterable<BTNodeExemplar<V, N>>, isBalanceAdd?: boolean, iterationType?: IterationType): (N | undefined)[];
-    /**
-     * Time Complexity: O(n log n) - Adding each element individually in a balanced tree.
-     * Space Complexity: O(n) - Additional space is required for the sorted array.
-     */
-    /**
-     * Time Complexity: O(log n) - Average case for a balanced tree.
-     * Space Complexity: O(1) - Constant space is used.
-     *
-     * 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 {BTNKey | N | undefined} beginRoot - The `beginRoot` parameter is optional and can be of
-     * type `BTNKey`, `N`, 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`).
-     * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
-     * be performed. It can have one of the following values:
-     * @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?: BSTNodeKeyOrNode<N>, iterationType?: IterationType): BTNKey;
+    addMany(keysOrNodesOrEntries: Iterable<BTNodeExemplar<K, V, N>>, isBalanceAdd?: boolean, iterationType?: IterationType): (N | undefined)[];
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree.
      * Space Complexity: O(1) - Constant space is used.
@@ -151,7 +132,7 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      *
      * The function `getNodeByKey` searches for a node in a binary tree based on a given key, using
      * either recursive or iterative methods.
-     * @param {BTNKey} key - The `key` parameter is the key value that we are searching for in the tree.
+     * @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
@@ -159,7 +140,7 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * @returns The function `getNodeByKey` returns a node (`N`) if a node with the specified key is
      * found in the binary tree. If no node is found, it returns `undefined`.
      */
-    getNodeByKey(key: BTNKey, iterationType?: IterationType): N | undefined;
+    getNodeByKey(key: K, iterationType?: IterationType): N | undefined;
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree.
      * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
@@ -167,13 +148,13 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
     /**
      * The function `ensureNode` returns the node corresponding to the given key if it is a node key,
      * otherwise it returns the key itself.
-     * @param {BTNKey | N | undefined} key - The `key` parameter can be of type `BTNKey`, `N`, or
+     * @param {K | N | undefined} key - The `key` parameter can be of type `K`, `N`, or
      * `undefined`.
      * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
      * type of iteration to be performed. It has a default value of `IterationType.ITERATIVE`.
      * @returns either a node object (N) or undefined.
      */
-    ensureNode(key: BSTNodeKeyOrNode<N>, iterationType?: IterationType): N | undefined;
+    ensureNode(key: BSTNodeKeyOrNode<K, N>, iterationType?: IterationType): N | undefined;
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key.
      * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
@@ -190,14 +171,14 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * first node that matches the identifier. If set to true, the function will return an array
      * containing only the first matching node. If set to false (default), the function will continue
      * searching for all nodes that match the identifier and return an array containing
-     * @param {BTNKey | N | undefined} beginRoot - The `beginRoot` parameter represents the starting node
+     * @param {K | N | undefined} beginRoot - The `beginRoot` parameter represents the starting node
      * for the traversal. It can be either a key value or a node object. If it is undefined, the
      * traversal will start from the root of the tree.
      * @param iterationType - The `iterationType` parameter determines the type of iteration to be
      * performed on the binary tree. It can have two possible values:
      * @returns The method returns an array of nodes (`N[]`).
      */
-    getNodes<C extends BTNCallback<N>>(identifier: ReturnType<C> | undefined, callback?: C, onlyOne?: boolean, beginRoot?: BSTNodeKeyOrNode<N>, iterationType?: IterationType): N[];
+    getNodes<C extends BTNCallback<N>>(identifier: ReturnType<C> | undefined, callback?: C, onlyOne?: boolean, beginRoot?: BSTNodeKeyOrNode<K, N>, iterationType?: IterationType): N[];
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key.
      * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
@@ -215,7 +196,7 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * traverse nodes that are lesser than, greater than, or equal to the `targetNode`. It is of type
      * `CP`, which is a custom type representing the comparison operator. The possible values for
      * `lesserOrGreater` are
-     * @param {BTNKey | N | undefined} targetNode - The `targetNode` parameter represents the node in the
+     * @param {K | N | undefined} targetNode - The `targetNode` parameter represents the node in the
      * binary tree that you want to traverse from. It can be specified either by its key, by the node
      * object itself, or it can be left undefined to start the traversal from the root of the tree.
      * @param iterationType - The `iterationType` parameter determines the type of traversal to be
@@ -223,7 +204,7 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
      * @returns The function `lesserOrGreaterTraverse` returns an array of values of type
      * `ReturnType<C>`, which is the return type of the callback function passed as an argument.
      */
-    lesserOrGreaterTraverse<C extends BTNCallback<N>>(callback?: C, lesserOrGreater?: CP, targetNode?: BSTNodeKeyOrNode<N>, iterationType?: IterationType): ReturnType<C>[];
+    lesserOrGreaterTraverse<C extends BTNCallback<N>>(callback?: C, lesserOrGreater?: CP, targetNode?: BSTNodeKeyOrNode<K, N>, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time Complexity: O(log n) - Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key.
      * Space Complexity: O(log n) - Space for the recursive call stack in the worst case.
@@ -267,10 +248,10 @@ export declare class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNe
     /**
      * 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 {BTNKey} a - The parameter "a" is of type BTNKey.
-     * @param {BTNKey} b - The parameter "b" in the above code represents a BTNKey.
+     * @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 CP.gt (greater
      * than), CP.lt (less than), or CP.eq (equal).
      */
-    protected _compare(a: BTNKey, b: BTNKey): CP;
+    protected _compare(a: K, b: K): CP;
 }