data-structure-typed 1.50.2 → 1.50.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.50.2",
+  "version": "1.50.3",
   "description": "Javascript Data Structure. Heap, Binary Tree, Red Black Tree, Linked List, Deque, Trie, HashMap, Directed Graph, Undirected Graph, Binary Search Tree(BST), AVL Tree, Priority Queue, Graph, Queue, Tree Multiset, Singly Linked List, Doubly Linked List, Max Heap, Max Priority Queue, Min Heap, Min Priority Queue, Stack. Benchmark compared with C++ STL. API aligned with ES6 and Java.util. Usability is comparable to Python",
   "main": "dist/cjs/index.js",
   "module": "dist/mjs/index.js",
@@ -94,17 +94,52 @@
   "keywords": [
     "data structure",
     "data structures",
-    "javascript data structure",
-    "javascript data structures",
-    "typescript data structure",
-    "typescript data structures",
-    "js data structure",
-    "js data structures",
-    "data-structure",
     "datastructure",
+    "datastructures",
     "data",
     "structure",
     "structures",
+    "min",
+    "max",
+    "heap",
+    "priority",
+    "queue",
+    "min heap",
+    "min-heap",
+    "max heap",
+    "max-heap",
+    "priority queue",
+    "priority-queue",
+    "max priority queue",
+    "max-priority-queue",
+    "min priority queue",
+    "min-priority-queue",
+    "binary search tree",
+    "binary-search-tree",
+    "BST",
+    "binary tree",
+    "binary-tree",
+    "red black tree",
+    "red black tree",
+    "red-black-tree",
+    "rb tree",
+    "trie",
+    "prefix tree",
+    "prefix-tree",
+    "avl tree",
+    "avl-tree",
+    "tree set",
+    "tree-set",
+    "tree multiset",
+    "tree-multiset",
+    "tree map",
+    "tree-map",
+    "tree multimap",
+    "tree-multimap",
+    "binary indexed tree",
+    "binary-indexed-tree",
+    "segment tree",
+    "segment-tree",
     "binary",
     "depth",
     "breadth",
@@ -124,18 +159,26 @@
     "set",
     "multiset",
     "multimap",
-    "directed",
-    "undirected",
-    "graph",
-    "min",
-    "max",
-    "heap",
-    "priority",
-    "queue",
     "singly",
     "doubly",
     "linked",
     "list",
+    "linked list",
+    "linked-list",
+    "singly linked list",
+    "singly-linked-list",
+    "doubly linked list",
+    "doubly-linked-list",
+    "javascript data structure",
+    "javascript data structures",
+    "typescript data structures",
+    "js data structure",
+    "js data structures",
+    "data-structure",
+    "data-structures",
+    "directed",
+    "undirected",
+    "graph",
     "js",
     "ts",
     "javascript",
@@ -159,32 +202,6 @@
     "java.util",
     "Java",
     "util",
-    "binary search tree",
-    "binary-search-tree",
-    "BST",
-    "binary tree",
-    "binary-tree",
-    "red black tree",
-    "red black tree",
-    "red-black-tree",
-    "rb tree",
-    "trie",
-    "prefix tree",
-    "prefix-tree",
-    "avl tree",
-    "avl-tree",
-    "tree set",
-    "tree-set",
-    "tree multiset",
-    "tree-multiset",
-    "tree map",
-    "tree-map",
-    "tree multimap",
-    "tree-multimap",
-    "binary indexed tree",
-    "binary-indexed-tree",
-    "segment tree",
-    "segment-tree",
     "sort",
     "sorted",
     "order",
@@ -212,28 +229,12 @@
     "directed-graph",
     "undirected graph",
     "undirected-graph",
-    "min heap",
-    "min-heap",
-    "max heap",
-    "max-heap",
-    "priority queue",
-    "priority-queue",
-    "max priority queue",
-    "max-priority-queue",
-    "min priority queue",
-    "min-priority-queue",
     "hash",
     "map",
     "hashmap",
     "hash map",
     "hash-map",
     "deque",
-    "linked list",
-    "linked-list",
-    "singly linked list",
-    "singly-linked-list",
-    "doubly linked list",
-    "doubly-linked-list",
     "stack",
     "CommonJS",
     "ES6",

package/src/data-structures/base/iterable-base.ts

@@ -289,8 +289,14 @@ export abstract class IterableEntryBase<K = any, V = any> {
 
   abstract isEmpty(): boolean;
 
+  abstract clear(): void;
+
   abstract clone(): any;
 
+  abstract map(...args: any[]): any;
+
+  abstract filter(...args: any[]): any;
+
   protected abstract _getIterator(...args: any[]): IterableIterator<[K, V]>;
 }
 
@@ -497,7 +503,13 @@ export abstract class IterableElementBase<E = any, C = any> {
 
   abstract isEmpty(): boolean;
 
+  abstract clear(): void;
+
   abstract clone(): C;
 
+  abstract map(...args: any[]): any;
+
+  abstract filter(...args: any[]): any;
+
   protected abstract _getIterator(...args: any[]): IterableIterator<E>;
 }

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

@@ -22,11 +22,36 @@ export class AVLTreeNode<
   V = any,
   NODE extends AVLTreeNode<K, V, NODE> = AVLTreeNodeNested<K, V>
 > extends BSTNode<K, V, NODE> {
-  height: number;
-
+  /**
+   * The constructor function initializes a new instance of a class with a key and an optional value,
+   * and sets the height property to 0.
+   * @param {K} key - The "key" parameter is of type K, which represents the type of the key for the
+   * constructor. It is used to initialize the key property of the object 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 constructor.
+   */
   constructor(key: K, value?: V) {
     super(key, value);
-    this.height = 0;
+    this._height = 0;
+  }
+
+  protected _height: number;
+
+  /**
+   * The function returns the value of the height property.
+   * @returns The height of the object.
+   */
+  get height(): number {
+    return this._height;
+  }
+
+  /**
+   * The above function sets the value of the height property.
+   * @param {number} value - The value parameter is a number that represents the new height value to be
+   * set.
+   */
+  set height(value: number) {
+    this._height = value;
   }
 }
 
@@ -488,6 +513,15 @@ export class AVLTree<
     }
   }
 
+  /**
+   * The function replaces an old node with a new node while preserving the height of the old node.
+   * @param {NODE} oldNode - The `oldNode` parameter is the node that you want to replace with the
+   * `newNode`.
+   * @param {NODE} newNode - The `newNode` parameter is the new node that will replace the `oldNode` in
+   * the data structure.
+   * @returns the result of calling the `_replaceNode` method on the superclass, passing in the
+   * `oldNode` and `newNode` as arguments.
+   */
   protected _replaceNode(oldNode: NODE, newNode: NODE): NODE {
     newNode.height = oldNode.height;
 

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

@@ -27,26 +27,48 @@ export class BinaryIndexedTree {
 
   protected _freqMap: Record<number, number>;
 
+  /**
+   * The function returns the frequency map of numbers.
+   * @returns The `_freqMap` property, which is a record with number keys and number values, is being
+   * returned.
+   */
   get freqMap(): Record<number, number> {
     return this._freqMap;
   }
 
   protected _msb: number;
 
+  /**
+   * The function returns the value of the _msb property.
+   * @returns The `_msb` property of the object.
+   */
   get msb(): number {
     return this._msb;
   }
 
   protected _negativeCount: number;
 
+  /**
+   * The function returns the value of the _negativeCount property.
+   * @returns The method is returning the value of the variable `_negativeCount`, which is of type
+   * `number`.
+   */
   get negativeCount(): number {
     return this._negativeCount;
   }
 
+  /**
+   * The above function returns the value of the protected variable `_freq`.
+   * @returns The frequency value stored in the protected variable `_freq`.
+   */
   get freq(): number {
     return this._freq;
   }
 
+  /**
+   * The above function returns the maximum value.
+   * @returns The maximum value stored in the variable `_max`.
+   */
   get max(): number {
     return this._max;
   }

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

@@ -44,7 +44,7 @@ export class BinaryTreeNode<
   /**
    * The constructor function initializes an object with a key and an optional value.
    * @param {K} key - The "key" parameter is of type K, which represents the type of the key for the
-   * constructor. It is used to set the value of the "key" property of the object being created.
+   * constructor. It is used to set the key property of the object 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 constructor.
    */

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

@@ -34,10 +34,19 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
 
   protected override _left?: NODE;
 
+  /**
+   * The function returns the value of the `_left` property.
+   * @returns The `_left` property of the current object is being returned.
+   */
   override get left(): NODE | undefined {
     return this._left;
   }
 
+  /**
+   * 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`.
+   */
   override set left(v: NODE | undefined) {
     if (v) {
       v.parent = this as unknown as NODE;
@@ -47,10 +56,20 @@ export class BSTNode<K = any, V = any, NODE extends BSTNode<K, V, NODE> = BSTNod
 
   protected override _right?: 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`.
+   */
   override get right(): NODE | undefined {
     return this._right;
   }
 
+  /**
+   * 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`.
+   */
   override set right(v: NODE | undefined) {
     if (v) {
       v.parent = this as unknown as NODE;
@@ -77,10 +96,10 @@ export class BST<
   extends BinaryTree<K, V, NODE, TREE>
   implements IBinaryTree<K, V, NODE, TREE> {
   /**
-   * 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:
    */
@@ -99,23 +118,31 @@ export class BST<
 
   protected override _root?: NODE;
 
+  /**
+   * The function returns the root node of a tree structure.
+   * @returns The `_root` property of the object, which is of type `NODE` or `undefined`.
+   */
   override get root(): NODE | undefined {
     return this._root;
   }
 
   protected _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.
    */
   override createNode(key: K, value?: V): NODE {
     return new BSTNode<K, V, NODE>(key, value) as NODE;
@@ -124,9 +151,10 @@ export class BST<
   /**
    * 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.
    */
   override createTree(options?: Partial<BSTOptions<K>>): TREE {
     return new BST<K, V, NODE, TREE>([], {
@@ -824,6 +852,11 @@ export class BST<
     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`.
+   */
   protected _setRoot(v: NODE | undefined) {
     if (v) {
       v.parent = undefined;

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

@@ -24,11 +24,38 @@ export class RedBlackTreeNode<
   V = any,
   NODE extends RedBlackTreeNode<K, V, NODE> = RedBlackTreeNodeNested<K, V>
 > extends BSTNode<K, V, NODE> {
-  color: RBTNColor;
-
+  /**
+   * The constructor function initializes a Red-Black Tree Node with a key, an optional value, and a
+   * color.
+   * @param {K} key - The key parameter is of type K and represents the key of the node in the
+   * Red-Black Tree.
+   * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
+   * associated with the key in the Red-Black Tree Node. It is not required and can be omitted when
+   * creating a new instance of the Red-Black Tree Node.
+   * @param {RBTNColor} color - The `color` parameter is used to specify the color of the Red-Black
+   * Tree Node. It is an optional parameter with a default value of `RBTNColor.BLACK`.
+   */
   constructor(key: K, value?: V, color: RBTNColor = RBTNColor.BLACK) {
     super(key, value);
-    this.color = color;
+    this._color = color;
+  }
+
+  protected _color: RBTNColor;
+
+  /**
+   * The function returns the color value of a variable.
+   * @returns The color value stored in the protected variable `_color`.
+   */
+  get color(): RBTNColor {
+    return this._color;
+  }
+
+  /**
+   * The function sets the color property to the specified value.
+   * @param {RBTNColor} value - The value parameter is of type RBTNColor.
+   */
+  set color(value: RBTNColor) {
+    this._color = value;
   }
 }
 
@@ -47,8 +74,6 @@ export class RedBlackTree<
 >
   extends BST<K, V, NODE, TREE>
   implements IBinaryTree<K, V, NODE, TREE> {
-  Sentinel: NODE = new RedBlackTreeNode<K, V>(NaN as K) as unknown as NODE;
-
   /**
    * This is the constructor function for a Red-Black Tree data structure in TypeScript, which
    * initializes the tree with optional nodes and options.
@@ -63,18 +88,36 @@ export class RedBlackTree<
   constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: RBTreeOptions<K>) {
     super([], options);
 
-    this._root = this.Sentinel;
+    this._root = this._Sentinel;
     if (keysOrNodesOrEntries) super.addMany(keysOrNodesOrEntries);
   }
 
+  protected _Sentinel: NODE = new RedBlackTreeNode<K, V>(NaN as K) as unknown as NODE;
+
+  /**
+   * The function returns the value of the `_Sentinel` property.
+   * @returns The method is returning the value of the `_Sentinel` property.
+   */
+  get Sentinel(): NODE {
+    return this._Sentinel;
+  }
+
   protected _root: NODE;
 
+  /**
+   * The function returns the root node.
+   * @returns The root node of the data structure.
+   */
   get root(): NODE {
     return this._root;
   }
 
   protected _size: number = 0;
 
+  /**
+   * The function returns the size of an object.
+   * @returns The size of the object, which is a number.
+   */
   get size(): number {
     return this._size;
   }
@@ -149,8 +192,14 @@ export class RedBlackTree<
     return keyOrNodeOrEntry instanceof RedBlackTreeNode;
   }
 
+  /**
+   * The function checks if a given node is a real node in a Red-Black Tree.
+   * @param {NODE | undefined} node - The `node` parameter is of type `NODE | undefined`, which means
+   * it can either be of type `NODE` or `undefined`.
+   * @returns a boolean value.
+   */
   override isRealNode(node: NODE | undefined): node is NODE {
-    if (node === this.Sentinel || node === undefined) return false;
+    if (node === this._Sentinel || node === undefined) return false;
     return node instanceof RedBlackTreeNode;
   }
 
@@ -176,13 +225,13 @@ export class RedBlackTree<
     const newNode = this.keyValueOrEntryToNode(keyOrNodeOrEntry, value);
     if (newNode === undefined) return false;
 
-    newNode.left = this.Sentinel;
-    newNode.right = this.Sentinel;
+    newNode.left = this._Sentinel;
+    newNode.right = this._Sentinel;
 
     let y: NODE | undefined = undefined;
     let x: NODE | undefined = this.root;
 
-    while (x !== this.Sentinel) {
+    while (x !== this._Sentinel) {
       y = x;
       if (x) {
         if (newNode.key < x.key) {
@@ -250,9 +299,9 @@ export class RedBlackTree<
     const ans: BinaryTreeDeleteResult<NODE>[] = [];
     if (identifier === null) return ans;
     const helper = (node: NODE | undefined): void => {
-      let z: NODE = this.Sentinel;
+      let z: NODE = this._Sentinel;
       let x: NODE | undefined, y: NODE;
-      while (node !== this.Sentinel) {
+      while (node !== this._Sentinel) {
         if (node && callback(node) === identifier) {
           z = node;
         }
@@ -264,17 +313,17 @@ export class RedBlackTree<
         }
       }
 
-      if (z === this.Sentinel) {
+      if (z === this._Sentinel) {
         this._size--;
         return;
       }
 
       y = z;
       let yOriginalColor: number = y.color;
-      if (z.left === this.Sentinel) {
+      if (z.left === this._Sentinel) {
         x = z.right;
         this._rbTransplant(z, z.right!);
-      } else if (z.right === this.Sentinel) {
+      } else if (z.right === this._Sentinel) {
         x = z.left;
         this._rbTransplant(z, z.left!);
       } else {
@@ -346,8 +395,14 @@ export class RedBlackTree<
    * Space Complexity: O(1)
    */
 
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The "clear" function sets the root node to the sentinel node and resets the size to 0.
+   */
   override clear() {
-    this._root = this.Sentinel;
+    this._root = this._Sentinel;
     this._size = 0;
   }
 
@@ -379,6 +434,12 @@ export class RedBlackTree<
     return y!;
   }
 
+  /**
+   * The function sets the root node of a tree structure and updates the parent property of the new
+   * root node.
+   * @param {NODE} v - The parameter "v" is of type "NODE", which represents a node in a data
+   * structure.
+   */
   protected override _setRoot(v: NODE) {
     if (v) {
       v.parent = undefined;
@@ -402,7 +463,7 @@ export class RedBlackTree<
     if (x.right) {
       const y: NODE = x.right;
       x.right = y.left;
-      if (y.left !== this.Sentinel) {
+      if (y.left !== this._Sentinel) {
         if (y.left) y.left.parent = x;
       }
       y.parent = x.parent;
@@ -435,7 +496,7 @@ export class RedBlackTree<
     if (x.left) {
       const y: NODE = x.left;
       x.left = y.right;
-      if (y.right !== this.Sentinel) {
+      if (y.right !== this._Sentinel) {
         if (y.right) y.right.parent = x;
       }
       y.parent = x.parent;