data-structure-typed 1.50.1 → 1.50.3

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

@@ -11,14 +11,16 @@ export class BSTNode extends BinaryTreeNode {
     }
     _left;
     /**
-     * Get the left child node.
+     * The function returns the value of the `_left` property.
+     * @returns The `_left` property of the current object is being returned.
      */
     get left() {
         return this._left;
     }
     /**
-     * Set the left child node.
-     * @param {N | undefined} v - The left child node.
+     * The function sets the left child of a node and updates the parent reference of the child.
+     * @param {NODE | undefined} v - The parameter `v` is of type `NODE | undefined`. It can either be an
+     * instance of the `NODE` class or `undefined`.
      */
     set left(v) {
         if (v) {
@@ -28,14 +30,17 @@ export class BSTNode extends BinaryTreeNode {
     }
     _right;
     /**
-     * Get the right child node.
+     * The function returns the right node of a binary tree or undefined if there is no right node.
+     * @returns The method is returning the value of the `_right` property, which is of type `NODE` or
+     * `undefined`.
      */
     get right() {
         return this._right;
     }
     /**
-     * Set the right child node.
-     * @param {N | undefined} v - The right child node.
+     * The function sets the right child of a node and updates the parent reference of the child.
+     * @param {NODE | undefined} v - The parameter `v` is of type `NODE | undefined`. It can either be a
+     * `NODE` object or `undefined`.
      */
     set right(v) {
         if (v) {
@@ -55,10 +60,10 @@ export class BSTNode extends BinaryTreeNode {
  */
 export class BST extends BinaryTree {
     /**
-     * This is the constructor function for a binary search tree class in TypeScript, which initializes
-     * the tree with optional keysOrNodesOrEntries and options.
-     * @param [keysOrNodesOrEntries] - An optional iterable of KeyOrNodeOrEntry objects that will be added to the
-     * binary search 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.
      * @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:
      */
@@ -74,20 +79,28 @@ export class BST extends BinaryTree {
             this.addMany(keysOrNodesOrEntries);
     }
     _root;
+    /**
+     * The function returns the root node of a tree structure.
+     * @returns The `_root` property of the object, which is of type `NODE` or `undefined`.
+     */
     get root() {
         return this._root;
     }
     _variant = BSTVariant.STANDARD;
+    /**
+     * The function returns the value of the _variant property.
+     * @returns The value of the `_variant` property.
+     */
     get variant() {
         return this._variant;
     }
     /**
-     * The function creates a new binary search tree node with the given key and value.
-     * @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.
+     * 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
+     * being created.
+     * @param {V} [value] - The "value" parameter is an optional parameter of type V. It represents the
+     * value associated with the key in the node being created.
+     * @returns The method is returning a new instance of the BSTNode class, casted as the NODE type.
      */
     createNode(key, value) {
         return new BSTNode(key, value);
@@ -95,9 +108,10 @@ export class BST extends BinaryTree {
     /**
      * 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
-     * behavior of the `createTree` method. It accepts a partial `BSTOptions` object, which is a type
-     * that defines various options for creating a binary search tree.
-     * @returns a new instance of the BST class with the specified options.
+     * behavior of the `createTree` method. It is of type `Partial<BSTOptions<K>>`, which means it is a
+     * partial object of type `BSTOptions<K>`.
+     * @returns a new instance of the BST class, with the provided options merged with the default
+     * options. The returned value is casted as TREE.
      */
     createTree(options) {
         return new BST([], {
@@ -107,14 +121,14 @@ export class BST extends BinaryTree {
         });
     }
     /**
-     * The function `exemplarToNode` takes an keyOrNodeOrEntry and returns a node if the keyOrNodeOrEntry is valid,
+     * The function `keyValueOrEntryToNode` takes an keyOrNodeOrEntry and returns a node if the keyOrNodeOrEntry is valid,
      * otherwise it returns undefined.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, N>`, where:
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`, where:
      * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
-     * `exemplarToNode` function. It represents the value associated with the keyOrNodeOrEntry node.
-     * @returns a node of type N or undefined.
+     * `keyValueOrEntryToNode` function. It represents the value associated with the keyOrNodeOrEntry node.
+     * @returns a node of type NODE or undefined.
      */
-    exemplarToNode(keyOrNodeOrEntry, value) {
+    keyValueOrEntryToNode(keyOrNodeOrEntry, value) {
         let node;
         if (keyOrNodeOrEntry === null || keyOrNodeOrEntry === undefined) {
             return;
@@ -142,7 +156,6 @@ export class BST extends BinaryTree {
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
-     * Average case for a balanced tree. Space for the recursive call stack in the worst case.
      */
     /**
      * Time Complexity: O(log n)
@@ -150,11 +163,11 @@ export class BST extends BinaryTree {
      *
      * The function `ensureNode` returns the node corresponding to the given key if it is a node key,
      * otherwise it returns the key itself.
-     * @param {K | N | undefined} keyOrNodeOrEntry - The `key` parameter can be of type `K`, `N`, or
+     * @param {K | NODE | undefined} keyOrNodeOrEntry - The `key` parameter can be of type `K`, `NODE`, 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.
+     * @returns either a node object (NODE) or undefined.
      */
     ensureNode(keyOrNodeOrEntry, iterationType = IterationType.ITERATIVE) {
         let res;
@@ -173,7 +186,7 @@ export class BST extends BinaryTree {
     }
     /**
      * The function checks if an keyOrNodeOrEntry is an instance of BSTNode.
-     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is a variable of type `KeyOrNodeOrEntry<K, V, N>`.
+     * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is a variable of type `KeyOrNodeOrEntry<K, V, NODE>`.
      * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the BSTNode class.
      */
     isNode(keyOrNodeOrEntry) {
@@ -182,7 +195,6 @@ export class BST extends BinaryTree {
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
-     *  - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
      */
     /**
      * Time Complexity: O(log n)
@@ -197,7 +209,7 @@ export class BST extends BinaryTree {
      * node was not added.
      */
     add(keyOrNodeOrEntry, value) {
-        const newNode = this.exemplarToNode(keyOrNodeOrEntry, value);
+        const newNode = this.keyValueOrEntryToNode(keyOrNodeOrEntry, value);
         if (newNode === undefined)
             return false;
         if (this.root === undefined) {
@@ -221,7 +233,6 @@ export class BST extends BinaryTree {
             else if (this._compare(current.key, newNode.key) === CP.gt) {
                 if (current.left === undefined) {
                     current.left = newNode;
-                    newNode.parent = current;
                     this._size++;
                     return true;
                 }
@@ -230,7 +241,6 @@ export class BST extends BinaryTree {
             else {
                 if (current.right === undefined) {
                     current.right = newNode;
-                    newNode.parent = current;
                     this._size++;
                     return true;
                 }
@@ -241,12 +251,11 @@ export class BST extends BinaryTree {
     }
     /**
      * Time Complexity: O(k log n)
-     * Space Complexity: O(k)
-     * Adding each element individually in a balanced tree. Additional space is required for the sorted array.
+     * Space Complexity: O(k + log n)
      */
     /**
      * Time Complexity: O(k log n)
-     * Space Complexity: O(k)
+     * 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.
@@ -262,7 +271,7 @@ export class BST extends BinaryTree {
      * @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 (`N`) or `undefined` values.
+     * @returns The function `addMany` returns an array of nodes (`NODE`) or `undefined` values.
      */
     addMany(keysOrNodesOrEntries, values, isBalanceAdd = true, iterationType = this.iterationType) {
         const inserted = [];
@@ -353,7 +362,7 @@ export class BST extends BinaryTree {
      * @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 (`N`) if a node with the specified key is
+     * @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, iterationType = IterationType.ITERATIVE) {
@@ -389,32 +398,31 @@ export class BST extends BinaryTree {
     }
     /**
      * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
-     * Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key. Space for the recursive call stack in the worst case.
+     * Space Complexity: O(k + log n)
      * /
   
      /**
      * Time Complexity: O(log n)
-     * Space Complexity: O(log n)
+     * Space Complexity: O(k + log n)
      *
      * The function `getNodes` returns an array of nodes that match a given identifier, using either a
      * recursive or iterative approach.
      * @param {ReturnType<C> | undefined} identifier - The `identifier` parameter is the value that you
      * want to search for in the nodes of the binary tree. It can be of any type that is returned by the
      * callback function `C`.
-     * @param {C} callback - The `callback` parameter is a function that takes a node of type `N` as its
+     * @param {C} callback - The `callback` parameter is a function that takes a node of type `NODE` as its
      * argument and returns a value of type `ReturnType<C>`. The `C` type parameter represents a callback
-     * function type that extends the `BTNCallback<N>` type. The `BTNCallback<N>` type is
+     * function type that extends the `BTNCallback<NODE>` type. The `BTNCallback<NODE>` type is
      * @param [onlyOne=false] - A boolean flag indicating whether to stop searching after finding the
      * 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 {K | N | undefined} beginRoot - The `beginRoot` parameter represents the starting node
+     * @param {K | NODE | 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[]`).
+     * @returns The method returns an array of nodes (`NODE[]`).
      */
     getNodes(identifier, callback = this._defaultOneParamCallback, onlyOne = false, beginRoot = this.root, iterationType = this.iterationType) {
         beginRoot = this.ensureNode(beginRoot);
@@ -472,25 +480,6 @@ export class BST extends BinaryTree {
         }
         return ans;
     }
-    // /**
-    //  * The function overrides the subTreeTraverse method and returns the result of calling the super
-    //  * method with the provided arguments.
-    //  * @param {C} callback - The `callback` parameter is a function that will be called for each node in
-    //  * the subtree traversal. It should accept a single parameter of type `N`, which represents a node in
-    //  * the tree. The return type of the callback function can be any type.
-    //  * @param beginRoot - The `beginRoot` parameter is the starting point for traversing the subtree. It
-    //  * can be either a key, a node, or an entry.
-    //  * @param iterationType - The `iterationType` parameter is used to specify the type of iteration to
-    //  * be performed during the traversal of the subtree. It can have one of the following values:
-    //  * @returns The method is returning an array of the return type of the callback function.
-    //  */
-    // override subTreeTraverse<C extends BTNCallback<N>>(
-    //   callback: C = this._defaultOneParamCallback as C,
-    //   beginRoot: KeyOrNodeOrEntry<K, V, N> = this.root,
-    //   iterationType = this.iterationType
-    // ): ReturnType<C>[] {
-    //   return super.subTreeTraverse(callback, beginRoot, iterationType, false);
-    // }
     /**
      * Time complexity: O(n)
      * Space complexity: O(n)
@@ -552,7 +541,7 @@ export class BST extends BinaryTree {
      * The function overrides the listLevels method and returns an array of arrays containing the return
      * type of the callback function for each level of the tree.
      * @param {C} callback - The `callback` parameter is a generic type `C` that extends
-     * `BTNCallback<N>`. It represents a callback function that will be called for each node in the tree
+     * `BTNCallback<NODE>`. It represents a callback function that will be called for each node in the tree
      * during the level listing process.
      * @param beginRoot - The `beginRoot` parameter is used to specify the starting point for listing the
      * levels of a binary tree. It can be either a key, a node, or an entry in the binary tree. If not
@@ -567,18 +556,17 @@ export class BST extends BinaryTree {
         return super.listLevels(callback, beginRoot, iterationType, false);
     }
     /**
-     * Time Complexity: O(n log n)
-     * Space Complexity: O(n)
-     * Adding each element individually in a balanced tree. Additional space is required for the sorted array.
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(n log n)
-     * Space Complexity: O(n)
+     * 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 | N | undefined} beginRoot - The `beginRoot` parameter is optional and can be of
-     * type `K`, `N`, or `undefined`. It represents the starting point for finding the last key in
+     * @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
@@ -605,7 +593,6 @@ export class BST extends BinaryTree {
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
-     * Average case for a balanced tree. O(n) - Visiting each node once when identifier is not node's key. Space for the recursive call stack in the worst case.
      */
     /**
      * Time Complexity: O(log n)
@@ -615,12 +602,12 @@ export class BST extends BinaryTree {
      * are either lesser or greater than a target node, depending on the specified comparison type.
      * @param {C} callback - The `callback` parameter is a function that will be called for each node
      * that satisfies the condition specified by the `lesserOrGreater` parameter. It takes a single
-     * parameter of type `N` (the node type) and returns a value of any type.
+     * parameter of type `NODE` (the node type) and returns a value of any type.
      * @param {CP} lesserOrGreater - The `lesserOrGreater` parameter is used to determine whether to
      * 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 {K | N | undefined} targetNode - The `targetNode` parameter represents the node in the
+     * @param {K | NODE | 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
@@ -729,8 +716,8 @@ export class BST extends BinaryTree {
      * AVL Tree: AVL trees are well-suited for scenarios involving frequent searching, insertion, and deletion operations. Through rotation adjustments, AVL trees maintain their balance, ensuring average and worst-case time complexity of O(log n).
      */
     /**
-     * Time Complexity: O(n) - Building a balanced tree from a sorted array.
-     * Space Complexity: O(n) - Additional space is required for the sorted array.
+     * Time Complexity: O(n)
+     * Space Complexity: O(log n)
      */
     /**
      * Time Complexity: O(n)
@@ -786,6 +773,11 @@ export class BST extends BinaryTree {
         }
         return balanced;
     }
+    /**
+     * The function sets the root property of an object and updates the parent property of the new root.
+     * @param {NODE | undefined} v - The parameter `v` is of type `NODE | undefined`. This means that it
+     * can either be an object of type `NODE` or it can be `undefined`.
+     */
     _setRoot(v) {
         if (v) {
             v.parent = undefined;