data-structure-typed 0.8.18 → 1.12.9

package/package.json

@@ -1,62 +1,42 @@
 {
   "name": "data-structure-typed",
-  "version": "0.8.18",
-  "description": "Hash (CoordinateSet, CoordinateMap) Heap (MaxHeap, MinHeap) Binary Tree (AVL Tree, Binary Indexed Tree, Binary Search Tree, Segment Tree, Tree Multiset) Graph (Directed Graph, Undirected Graph) Linked List (Singly Linked List, Doubly Linked List) Matrix Priority Queue (Max Priority Queue, Min Priority Queue) Queue (Queue, Dequeue) Stack Trie",
+  "version": "1.12.9",
+  "description": "Explore our comprehensive Javascript Data Structure / TypeScript Data Structure Library, meticulously crafted to empower developers with a versatile set of essential data structures. Our library includes a wide range of data structures, such as Binary Tree, AVL Tree, Binary Search Tree (BST), Tree Multiset, Segment Tree, Binary Indexed Tree, Graph, Directed Graph, Undirected Graph, Singly Linked List, Hash, CoordinateSet, CoordinateMap, Heap, Doubly Linked List, Priority Queue, Max Priority Queue, Min Priority Queue, Queue, ObjectDeque, ArrayDeque, Stack, and Trie. Each data structure is thoughtfully designed and implemented using TypeScript to provide efficient, reliable, and easy-to-use solutions for your programming needs. Whether you're optimizing algorithms, managing data, or enhancing performance, our TypeScript Data Structure Library is your go-to resource. Elevate your coding experience with these fundamental building blocks for software development.",
   "main": "dist/index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "rm -rf dist && npx tsc",
+    "test": "jest",
+    "build:docs": "typedoc --out docs ./src",
+    "deps:check": "dependency-cruiser src"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zrwusa/data-structure-typed.git"
   },
   "keywords": [
-    "Hash",
-    "CoordinateSet",
-    "CoordinateMap",
-    "Heap",
-    "MaxHeap",
-    "MinHeap",
-    "Binary",
-    "Tree",
-    "AVL",
-    "Tree",
-    "Binary",
-    "Indexed",
-    "Tree",
-    "Binary",
-    "Search",
-    "Tree",
-    "Segment",
-    "Tree",
-    "Tree",
-    "Multiset",
-    "Graph",
-    "Directed",
+    "Binary Tree",
+    "Binary Search Tree (BST)",
+    "AVL Tree",
+    "Tree Multiset",
+    "Segment Tree",
+    "Binary Indexed Tree",
     "Graph",
-    "Undirected",
-    "Graph",
-    "Linked",
-    "List",
-    "Singly",
-    "Linked",
-    "List",
-    "Doubly",
-    "Linked",
-    "List",
-    "Matrix",
-    "Priority",
-    "Queue",
-    "Max",
-    "Priority",
+    "Directed Graph",
+    "Undirected Graph",
+    "Linked List",
+    "Singly Linked List",
+    "Doubly Linked List",
     "Queue",
-    "Min",
-    "Priority",
-    "Queue",
-    "Queue",
-    "Queue",
-    "Dequeue",
+    "Object Deque",
+    "Array Deque",
     "Stack",
+    "Hash",
+    "Coordinate Set",
+    "Coordinate Map",
+    "Heap",
+    "Priority Queue",
+    "Max Priority Queue",
+    "Min Priority Queue",
     "Trie"
   ],
   "author": "Tyler Zeng",
@@ -67,7 +47,13 @@
   "homepage": "https://github.com/zrwusa/data-structure-typed#readme",
   "types": "dist/index.d.ts",
   "devDependencies": {
-    "@types/lodash": "^4.14.178",
+    "@types/jest": "^29.5.3",
+    "@types/lodash": "^4.14.197",
+    "@types/node": "^20.4.9",
+    "dependency-cruiser": "^13.1.2",
+    "jest": "^29.6.2",
+    "ts-jest": "^29.1.1",
+    "typedoc": "^0.24.8",
     "typescript": "^4.6.2"
   },
   "dependencies": {

package/rename_clear_files.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+# iterate the directory to rename and clear content of files
+rename_and_clear_files() {
+  local directory="$1"
+  local extension="$2"
+  local new_prefix="$3"
+
+  for file in "$directory"/*; do
+    if [ -d "$file" ]; then
+      rename_and_clear_files "$file" "$extension" "$new_prefix"
+    elif [ -f "$file" ] && [[ "$file" == *"$extension" ]]; then
+      filename=$(basename "$file" "$extension")
+      new_name="$directory/${filename}${new_prefix}${extension}"
+      mv "$file" "$new_name"
+      echo "Renamed $file to $new_name"
+      > "$new_name"  # clear content of file
+    fi
+  done
+}
+
+# check if directory, extension and prefix were provided
+if [ -z "$1" ] || [ -z "$2" ] || [ -z "$3" ]; then
+  echo "Usage: $0 <directory> <extension> <new_prefix>"
+  exit 1
+fi
+
+# evoke the recursive function to rename and clear files
+rename_and_clear_files "$1" "$2" "$3"

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

@@ -1,10 +1,9 @@
+/**
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT
+ */
 import {BST, BSTNode} from './bst';
-import {BinaryTreeNodeId} from './binary-tree';
-
-export interface AVLTreeDeleted<T> {
-    deleted: AVLTreeNode<T> | null;
-    needBalanced: AVLTreeNode<T> | null;
-}
+import type {AVLTreeDeleted, BinaryTreeNodeId} from '../types';
 
 export class AVLTreeNode<T> extends BSTNode<T> {
     override clone(): AVLTreeNode<T> {
@@ -18,12 +17,34 @@ export class AVLTree<T> extends BST<T> {
         return new AVLTreeNode<T>(id, val, count);
     }
 
+    /**
+     * The function overrides the put method of a Binary Search Tree to insert a node with a given id and value, and then
+     * balances the tree.
+     * @param {BinaryTreeNodeId} id - The `id` parameter is the identifier of the binary tree node that we want to put or
+     * update in the AVL tree.
+     * @param {T | null} val - The `val` parameter represents the value that you want to assign to the node with the given
+     * `id`. It can be of type `T` (the generic type) or `null`.
+     * @param {number} [count] - The `count` parameter is an optional parameter of type `number`. It represents the number
+     * of times the value `val` should be inserted into the AVL tree. If the `count` parameter is not provided, it defaults
+     * to `1`, indicating that the value should be inserted once.
+     * @returns The method is returning either an AVLTreeNode<T> object or null.
+     */
     override put(id: BinaryTreeNodeId, val: T | null, count?: number): AVLTreeNode<T> | null {
         const inserted = super.put(id, val, count);
         if (inserted) this.balancePath(inserted);
         return inserted;
     }
 
+    /**
+     * The function overrides the remove method of the Binary Search Tree class, performs the removal operation, and
+     * then balances the tree if necessary.
+     * @param {BinaryTreeNodeId} id - The `id` parameter represents the identifier of the binary tree node that needs to be
+     * removed from the AVL tree.
+     * @param {boolean} [isUpdateAllLeftSum] - The `isUpdateAllLeftSum` parameter is an optional boolean parameter that
+     * determines whether the left sum of all nodes in the AVL tree should be updated after removing a node. If
+     * `isUpdateAllLeftSum` is set to `true`, the left sum of all nodes will be recalculated.
+     * @returns The method is returning an array of `AVLTreeDeleted<T>` objects.
+     */
     override remove(id: BinaryTreeNodeId, isUpdateAllLeftSum?: boolean): AVLTreeDeleted<T>[] {
         const deletedResults = super.remove(id, isUpdateAllLeftSum);
         for (const {needBalanced} of deletedResults) {
@@ -34,6 +55,12 @@ export class AVLTree<T> extends BST<T> {
         return deletedResults;
     }
 
+    /**
+     * 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 AVLTreeNode<T>, which represents a node in an AVL tree.
+     * @returns The balance factor of the given AVL tree node.
+     */
     balanceFactor(node: AVLTreeNode<T>): number {
         if (!node.right) // node has no right subtree
             return -node.height;
@@ -43,6 +70,10 @@ export class AVLTree<T> extends BST<T> {
             return node.right.height - node.left.height;
     }
 
+    /**
+     * 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.
+     */
     updateHeight(node: AVLTreeNode<T>): void {
         if (!node.left && !node.right) // node is a leaf
             node.height = 0;
@@ -56,6 +87,11 @@ export class AVLTree<T> extends BST<T> {
             node.height = 1 + Math.max(node.right.height, node.left.height);
     }
 
+    /**
+     * 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.
+     */
     balancePath(node: AVLTreeNode<T>): void {
         const path = this.getPathToRoot(node);
         for (let i = path.length - 1; i >= 0; i--) {
@@ -83,6 +119,10 @@ export class AVLTree<T> extends BST<T> {
         }
     }
 
+    /**
+     * The `balanceLL` function performs a left-left rotation on an AVL tree to balance it.
+     * @param A - The parameter A is an AVLTreeNode object.
+     */
     balanceLL(A: AVLTreeNode<T>): void {
         const parentOfA = A.parent;
         const B = A.left; // A is left-heavy and B is left-heavy
@@ -109,6 +149,10 @@ export class AVLTree<T> extends BST<T> {
         if (B) this.updateHeight(B);
     }
 
+    /**
+     * The `balanceLR` function performs a left-right rotation to balance an AVL tree.
+     * @param A - A is an AVLTreeNode object.
+     */
     balanceLR(A: AVLTreeNode<T>): void {
         const parentOfA = A.parent;
         const B = A.left; // A is left-heavy
@@ -153,6 +197,10 @@ export class AVLTree<T> extends BST<T> {
         C && this.updateHeight(C);
     }
 
+    /**
+     * The `balanceRR` function performs a right-right rotation on an AVL tree to balance it.
+     * @param A - The parameter A is an AVLTreeNode object.
+     */
     balanceRR(A: AVLTreeNode<T>): void {
         const parentOfA = A.parent;
         const B = A.right; // A is right-heavy and B is right-heavy
@@ -184,6 +232,10 @@ export class AVLTree<T> extends BST<T> {
         B && this.updateHeight(B);
     }
 
+    /**
+     * The `balanceRL` function performs a right-left rotation to balance an AVL tree.
+     * @param A - A is an AVLTreeNode object.
+     */
     balanceRL(A: AVLTreeNode<T>): void {
         const parentOfA = A.parent;
         const B = A.right; // A is right-heavy

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

@@ -1,3 +1,7 @@
+/**
+ * @copyright 2030 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT
+ */
 export class BinaryIndexedTree {
     private readonly _sumTree: number[];
 
@@ -5,6 +9,18 @@ export class BinaryIndexedTree {
         this._sumTree = new Array<number>(n + 1).fill(0);
     }
 
+    static lowBit(x: number) {
+        return x & (-x);
+    }
+
+    /**
+     * The update function updates the values in a binary indexed tree by adding a delta value to the specified index and
+     * its ancestors.
+     * @param {number} i - The parameter `i` represents the index of the element in the `_sumTree` array that needs to be
+     * updated.
+     * @param {number} delta - The "delta" parameter represents the change in value that needs to be added to the element
+     * at index "i" in the "_sumTree" array.
+     */
     update(i: number, delta: number) {
         while (i < this._sumTree.length) {
             this._sumTree[i] += delta;
@@ -12,6 +28,13 @@ export class BinaryIndexedTree {
         }
     }
 
+    /**
+     * The function calculates the prefix sum of an array using a binary indexed tree.
+     * @param {number} i - The parameter "i" in the function "getPrefixSum" represents the index of the element in the
+     * array for which we want to calculate the prefix sum.
+     * @returns The function `getPrefixSum` returns the prefix sum of the elements in the binary indexed tree up to index
+     * `i`.
+     */
     getPrefixSum(i: number) {
         let sum = 0;
         while (i > 0) {
@@ -21,13 +44,17 @@ export class BinaryIndexedTree {
         return sum;
     }
 
+    /**
+     * The function `getRangeSum` calculates the sum of a range of numbers in an array.
+     * @param {number} start - The start parameter is the starting index of the range for which we want to calculate the
+     * sum.
+     * @param {number} end - The "end" parameter represents the ending index of the range for which we want to calculate
+     * the sum.
+     * @returns the sum of the elements in the range specified by the start and end indices.
+     */
     public getRangeSum(start: number, end: number): number {
         if (!(0 <= start && start <= end && end <= this._sumTree.length))
             throw 'Index out of bounds';
         return this.getPrefixSum(end) - this.getPrefixSum(start);
     }
-
-    static lowBit(x: number) {
-        return x & (-x);
-    }
 }