data-structure-typed 1.37.3 → 1.37.4

package/lib/data-structures/binary-tree/tree-multiset.js

@@ -46,11 +46,11 @@ export class TreeMultiset extends AVLTree {
         return new TreeMultisetNode(key, val, count);
     }
     /**
-     * The function swaps the location of two nodes in a tree data structure.
-     * @param {N} srcNode - The source node that we want to _swap with the destination node.
-     * @param {N} destNode - The `destNode` parameter represents the destination node where the values from `srcNode` will
-     * be swapped with.
-     * @returns the `destNode` after swapping its values with the `srcNode`.
+     * The function swaps the values of two nodes in a binary tree.
+     * @param {N} srcNode - The source node that needs to be swapped with the destination node.
+     * @param {N} destNode - The `destNode` parameter represents the destination node where the values
+     * from `srcNode` will be swapped into.
+     * @returns The method is returning the `destNode` after swapping its properties with the `srcNode`.
      */
     _swap(srcNode, destNode) {
         const { key, val, count, height } = destNode;
@@ -69,14 +69,17 @@ export class TreeMultiset extends AVLTree {
         return destNode;
     }
     /**
-     * The `add` function adds a new node to a binary search tree, maintaining the tree's properties and balancing if
-     * necessary.
-     * @param {BinaryTreeNodeKey | N} keyOrNode - The `keyOrNode` parameter can be either a `BinaryTreeNodeKey` or a `N` (which
-     * represents a `BinaryTreeNode`).
-     * @param [val] - The `val` parameter represents the value to be added to the binary tree node.
-     * @param {number} [count] - The `count` parameter is an optional parameter that specifies the number of times the
-     * value should be added to the binary tree. If the `count` parameter is not provided, it defaults to 1.
-     * @returns The method `add` returns either the inserted node (`N`), `null`, or `undefined`.
+     * The `add` function adds a new node to a binary search tree, updating the count if the key already
+     * exists, and balancing the tree if necessary.
+     * @param {BinaryTreeNodeKey | N | null} keyOrNode - The `keyOrNode` parameter can be either a
+     * `BinaryTreeNodeKey` (which represents the key of the node to be added), a `N` (which represents a
+     * node to be added), or `null` (which represents a null node).
+     * @param [val] - The `val` parameter represents the value associated with the key that is being
+     * added to the binary tree.
+     * @param [count=1] - The `count` parameter represents the number of occurrences of the key/value
+     * pair that will be added to the binary tree. It has a default value of 1, which means that if no
+     * count is specified, the default count will be 1.
+     * @returns The function `add` returns a value of type `N | null | undefined`.
      */
     add(keyOrNode, val, count = 1) {
         let inserted = undefined, newNode;
@@ -155,13 +158,12 @@ export class TreeMultiset extends AVLTree {
         return inserted;
     }
     /**
-     * The function adds a new node to a binary tree if there is an available slot on the left or right side of the parent
-     * node.
-     * @param {N | null} newNode - The `newNode` parameter represents the node that needs to be added to the tree. It can
-     * be either a node object (`N`) or `null`.
-     * @param {N} parent - The `parent` parameter represents the parent node to which the new node will be added as a
-     * child.
-     * @returns The method returns either the `parent.left`, `parent.right`, or `undefined`.
+     * The function adds a new node to a binary tree if there is an available slot in the parent node.
+     * @param {N | null} newNode - The `newNode` parameter represents the node that needs to be added to
+     * the tree. It can be either a node object (`N`) or `null`.
+     * @param {N} parent - The `parent` parameter represents the parent node to which the new node will
+     * be added as a child.
+     * @returns The method `_addTo` returns either the `parent.left`, `parent.right`, or `undefined`.
      */
     _addTo(newNode, parent) {
         if (parent) {
@@ -190,13 +192,13 @@ export class TreeMultiset extends AVLTree {
         }
     }
     /**
-     * The `addMany` function takes an array of node IDs or nodes and adds them to the tree multiset, returning an array of
-     * the inserted nodes.
-     * @param {(BinaryTreeNodeKey | null)[] | (N | null)[]} keysOrNodes - An array of BinaryTreeNodeKey or BinaryTreeNode
-     * objects, or null values.
-     * @param {N['val'][]} [data] - The `data` parameter is an optional array of values (`N['val'][]`) that corresponds to
-     * the nodes being added. It is used when adding nodes using the `keyOrNode` and `data` arguments in the `this.add()`
-     * method. If provided, the `data` array should
+     * The `addMany` function adds multiple keys or nodes to a TreeMultiset and returns an array of the
+     * inserted nodes.
+     * @param {(BinaryTreeNodeKey | null)[] | (N | null)[]} keysOrNodes - An array of keys or nodes to be
+     * added to the multiset. Each element can be either a BinaryTreeNodeKey or a TreeMultisetNode.
+     * @param {N['val'][]} [data] - The `data` parameter is an optional array of values that correspond
+     * to the keys or nodes being added to the multiset. It is used to associate additional data with
+     * each key or node.
      * @returns The function `addMany` returns an array of `N`, `null`, or `undefined` values.
      */
     addMany(keysOrNodes, data) {
@@ -216,9 +218,12 @@ export class TreeMultiset extends AVLTree {
         return inserted;
     }
     /**
-     * The `perfectlyBalance` function takes a binary tree, performs a depth-first search to sort the nodes, and then
-     * constructs a balanced binary search tree using either a recursive or iterative approach.
-     * @returns The function `perfectlyBalance()` returns a boolean value.
+     * The `perfectlyBalance` function in TypeScript takes a sorted array of nodes and builds a balanced
+     * binary search tree using either a recursive or iterative approach.
+     * @param iterationType - The `iterationType` parameter is an optional parameter that specifies the
+     * type of iteration to use when building a balanced binary search tree. It can have two possible
+     * values:
+     * @returns a boolean value.
      */
     perfectlyBalance(iterationType = this.iterationType) {
         const sorted = this.dfs(node => node, 'in'), n = sorted.length;
@@ -257,13 +262,16 @@ export class TreeMultiset extends AVLTree {
         }
     }
     /**
-     * The `delete` function removes a node from a binary search tree and returns the deleted node along with the parent
-     * node that needs to be balanced.
-     * @param {N | BinaryTreeNodeKey | null} nodeOrKey - The `nodeOrKey` parameter can be one of the following:
-     * @param {boolean} [ignoreCount] - The `ignoreCount` parameter is an optional boolean parameter that determines
-     * whether to ignore the count of the node being removed. If `ignoreCount` is set to `true`, the count of the node will
-     * not be taken into account when removing it. If `ignoreCount` is set to `false
-     * @returns The function `delete` returns an array of `BinaryTreeDeletedResult<N>` objects.
+     * The `delete` function in a binary search tree deletes a node from the tree and returns the deleted
+     * node along with the parent node that needs to be balanced.
+     * @param {N | BinaryTreeNodeKey} nodeOrKey - The `nodeOrKey` parameter can be either a node object
+     * (`N`) or a key value (`BinaryTreeNodeKey`). It represents the node or key that needs to be deleted
+     * from the binary tree.
+     * @param [ignoreCount=false] - A boolean flag indicating whether to ignore the count of the node
+     * being deleted. If set to true, the count of the node will not be considered and the node will be
+     * deleted regardless of its count. If set to false (default), the count of the node will be
+     * decremented by 1 and
+     * @returns The method `delete` returns an array of `BinaryTreeDeletedResult<N>` objects.
      */
     delete(nodeOrKey, ignoreCount = false) {
         const bstDeletedResult = [];
@@ -322,14 +330,14 @@ export class TreeMultiset extends AVLTree {
         return bstDeletedResult;
     }
     /**
-     * The clear() function clears the data and sets the count to 0.
+     * The clear() function clears the contents of a data structure and sets the count to zero.
      */
     clear() {
         super.clear();
         this._setCount(0);
     }
     /**
-     * The function "_setCount" is used to set the value of the "_count" property.
+     * The function sets the value of the "_count" property.
      * @param {number} v - number
      */
     _setCount(v) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.37.3",
+  "version": "1.37.4",
   "description": "Data Structures of Javascript & TypeScript. Binary Tree, BST, Graph, Heap, Priority Queue, Linked List, Queue, Deque, Stack, AVL Tree, Tree Multiset, Trie, Directed Graph, Undirected Graph, Singly Linked List, Doubly Linked List, Max Heap, Max Priority Queue, Min Heap, Min Priority Queue.",
   "main": "dist/index.js",
   "module": "lib/index.js",
@@ -58,17 +58,17 @@
     "@typescript-eslint/eslint-plugin": "^6.7.4",
     "@typescript-eslint/parser": "^6.7.4",
     "auto-changelog": "^2.4.0",
-    "avl-tree-typed": "^1.37.2",
+    "avl-tree-typed": "^1.37.3",
     "benchmark": "^2.1.4",
-    "binary-tree-typed": "^1.37.2",
-    "bst-typed": "^1.37.2",
+    "binary-tree-typed": "^1.37.3",
+    "bst-typed": "^1.37.3",
     "dependency-cruiser": "^14.1.0",
     "eslint": "^8.50.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-import-resolver-alias": "^1.1.2",
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.28.1",
-    "heap-typed": "^1.37.2",
+    "heap-typed": "^1.37.3",
     "istanbul-badges-readme": "^1.8.5",
     "jest": "^29.7.0",
     "prettier": "^3.0.3",

package/src/data-structures/binary-tree/avl-tree.ts

@@ -33,11 +33,12 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_swap` function swaps the location of two nodes in a binary tree.
-   * @param {N} srcNode - The source node that you want to _swap with the destination node.
-   * @param {N} destNode - The `destNode` parameter represents the destination node where the values from `srcNode` will
-   * be swapped to.
-   * @returns The `destNode` is being returned.
+   * 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 override _swap(srcNode: N, destNode: N): N {
     const {key, val, height} = destNode;
@@ -59,11 +60,12 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function creates a new AVL tree node with the given key and value.
-   * @param {BinaryTreeNodeKey} key - The `key` parameter is the identifier for the binary tree node. It is used to uniquely
-   * identify each node in the tree.
-   * @param [val] - The `val` parameter is an optional value that can be assigned to the node. It represents the value
-   * that will be stored in the node.
+   * 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.
    */
   override createNode(key: BinaryTreeNodeKey, val?: N['val']): N {
@@ -71,11 +73,13 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function overrides the add method of a binary tree node and balances the tree after inserting a new node.
-   * @param keyOrNode - The `keyOrNode` parameter is either a key or a node that needs to be added to the binary tree.
-   * @param [val] - The `val` parameter is an optional value that can be assigned to the node being added. It is of type
-   * `N['val']`, which means it should be of the same type as the `val` property of the nodes in the binary tree.
-   * @returns The method is returning the inserted node, or null or undefined if the insertion was not successful.
+   * 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`.
    */
   override add(keyOrNode: BinaryTreeNodeKey | N | null, val?: N['val']): N | null | undefined {
     // TODO support node as a param
@@ -85,9 +89,11 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function overrides the delete method of a binary tree and performs additional operations to balance the tree after deletion.
+   * 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.
-   * @param nodeOrKey - The `nodeOrKey` parameter is either a node or a key that needs to be deleted from the binary tree.
    */
   override delete(nodeOrKey: N | BinaryTreeNodeKey): BinaryTreeDeletedResult<N>[] {
     const deletedResults = super.delete(nodeOrKey);
@@ -100,10 +106,10 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The balance factor of a given AVL tree node is calculated by subtracting the height of its left subtree from the
-   * height of its right subtree.
-   * @param node - The parameter "node" is of type N, which represents a node in an AVL tree.
-   * @returns The balance factor of the given AVL tree node.
+   * 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 {
     if (!node.right)
@@ -116,8 +122,9 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The function updates the height of a node in an AVL tree based on the heights of its left and right subtrees.
-   * @param node - The parameter `node` is an AVLTreeNode object, which represents a node in an AVL tree.
+   * 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 {
     if (!node.left && !node.right) node.height = 0;
@@ -129,9 +136,10 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balancePath` function balances the AVL tree by performing appropriate rotations based on the balance factor of
-   * each node in the path from the given node to the root.
-   * @param node - The `node` parameter is an AVLTreeNode object, which represents a node in an AVL tree.
+   * 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 {
     const path = this.getPathToRoot(node, false); // first O(log n) + O(log n)
@@ -173,8 +181,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceLL` function performs a left-left rotation on an AVL tree to balance it.
-   * @param A - The parameter A is an AVLTreeNode object.
+   * 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 {
     const parentOfA = A.parent;
@@ -203,8 +211,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceLR` function performs a left-right rotation to balance an AVL tree.
-   * @param A - A is an AVLTreeNode object.
+   * 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 {
     const parentOfA = A.parent;
@@ -251,8 +259,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceRR` function performs a right-right rotation on an AVL tree to balance it.
-   * @param A - The parameter A is an AVLTreeNode object.
+   * 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 {
     const parentOfA = A.parent;
@@ -286,8 +294,8 @@ export class AVLTree<N extends AVLTreeNode<N['val'], N> = AVLTreeNode> extends B
   }
 
   /**
-   * The `_balanceRL` function performs a right-left rotation to balance an AVL tree.
-   * @param A - A is an AVLTreeNode object.
+   * 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 {
     const parentOfA = A.parent;