data-structure-typed 1.50.2 → 1.50.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.50.2",
+  "version": "1.50.4",
   "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/{tree-multimap.ts → avl-tree-multi-map.ts}

@@ -6,25 +6,23 @@
  * @license MIT License
  */
 import type {
+  AVLTreeMultiMapNested,
+  AVLTreeMultiMapNodeNested,
+  AVLTreeMultiMapOptions,
   BinaryTreeDeleteResult,
   BSTNKeyOrNode,
   BTNCallback,
-  KeyOrNodeOrEntry,
-  TreeMultimapNested,
-  TreeMultimapNodeNested,
-  TreeMultimapOptions
+  KeyOrNodeOrEntry
 } from '../../types';
 import { FamilyPosition, IterationType } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 
-export class TreeMultimapNode<
+export class AVLTreeMultiMapNode<
   K = any,
   V = any,
-  NODE extends TreeMultimapNode<K, V, NODE> = TreeMultimapNodeNested<K, V>
+  NODE extends AVLTreeMultiMapNode<K, V, NODE> = AVLTreeMultiMapNodeNested<K, V>
 > extends AVLTreeNode<K, V, NODE> {
-  count: number;
-
   /**
    * The constructor function initializes a BinaryTreeNode object with a key, value, and count.
    * @param {K} key - The `key` parameter is of type `K` and represents the unique identifier
@@ -39,27 +37,51 @@ export class TreeMultimapNode<
     super(key, value);
     this.count = count;
   }
+
+  protected _count: number = 1;
+
+  /**
+   * The function returns the value of the protected variable _count.
+   * @returns The count property of the object, which is of type number.
+   */
+  get count(): number {
+    return this._count;
+  }
+
+  /**
+   * The above function sets the value of the count property.
+   * @param {number} value - The value parameter is of type number, which means it can accept any
+   * numeric value.
+   */
+  set count(value: number) {
+    this._count = value;
+  }
 }
 
 /**
- * The only distinction between a TreeMultimap and a AVLTree lies in the ability of the former to store duplicate nodes through the utilization of counters.
+ * The only distinction between a AVLTreeMultiMap and a AVLTree lies in the ability of the former to store duplicate nodes through the utilization of counters.
  */
-export class TreeMultimap<
+export class AVLTreeMultiMap<
   K = any,
   V = any,
-  NODE extends TreeMultimapNode<K, V, NODE> = TreeMultimapNode<K, V, TreeMultimapNodeNested<K, V>>,
-  TREE extends TreeMultimap<K, V, NODE, TREE> = TreeMultimap<K, V, NODE, TreeMultimapNested<K, V, NODE>>
+  NODE extends AVLTreeMultiMapNode<K, V, NODE> = AVLTreeMultiMapNode<K, V, AVLTreeMultiMapNodeNested<K, V>>,
+  TREE extends AVLTreeMultiMap<K, V, NODE, TREE> = AVLTreeMultiMap<K, V, NODE, AVLTreeMultiMapNested<K, V, NODE>>
 >
   extends AVLTree<K, V, NODE, TREE>
   implements IBinaryTree<K, V, NODE, TREE> {
-  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: TreeMultimapOptions<K>) {
+  constructor(keysOrNodesOrEntries: Iterable<KeyOrNodeOrEntry<K, V, NODE>> = [], options?: AVLTreeMultiMapOptions<K>) {
     super([], options);
     if (keysOrNodesOrEntries) this.addMany(keysOrNodesOrEntries);
   }
 
-  private _count = 0;
+  protected _count = 0;
 
   // TODO the _count is not accurate after nodes count modified
+  /**
+   * The function calculates the sum of the count property of all nodes in a tree using depth-first
+   * search.
+   * @returns the sum of the count property of all nodes in the tree.
+   */
   get count(): number {
     let sum = 0;
     this.dfs(node => (sum += node.count));
@@ -76,11 +98,20 @@ export class TreeMultimap<
    * @returns A new instance of the BSTNode class with the specified key, value, and count (if provided).
    */
   override createNode(key: K, value?: V, count?: number): NODE {
-    return new TreeMultimapNode(key, value, count) as NODE;
+    return new AVLTreeMultiMapNode(key, value, count) as NODE;
   }
 
-  override createTree(options?: TreeMultimapOptions<K>): TREE {
-    return new TreeMultimap<K, V, NODE, TREE>([], {
+  /**
+   * The function creates a new AVLTreeMultiMap object with the specified options and returns it.
+   * @param [options] - The `options` parameter is an optional object that contains additional
+   * configuration options for creating the `AVLTreeMultiMap` object. It can include properties such as
+   * `iterationType` and `variant`, which are used to specify the type of iteration and the variant of
+   * the tree, respectively. These properties can be
+   * @returns a new instance of the `AVLTreeMultiMap` class, with the provided options merged with the
+   * default options. The returned value is casted as `TREE`.
+   */
+  override createTree(options?: AVLTreeMultiMapOptions<K>): TREE {
+    return new AVLTreeMultiMap<K, V, NODE, TREE>([], {
       iterationType: this.iterationType,
       variant: this.variant,
       ...options
@@ -124,13 +155,13 @@ export class TreeMultimap<
   }
 
   /**
-   * The function checks if an keyOrNodeOrEntry is an instance of the TreeMultimapNode class.
+   * The function checks if an keyOrNodeOrEntry is an instance of the AVLTreeMultiMapNode class.
    * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter is of type `KeyOrNodeOrEntry<K, V, NODE>`.
-   * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the TreeMultimapNode
+   * @returns a boolean value indicating whether the keyOrNodeOrEntry is an instance of the AVLTreeMultiMapNode
    * class.
    */
   override isNode(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is NODE {
-    return keyOrNodeOrEntry instanceof TreeMultimapNode;
+    return keyOrNodeOrEntry instanceof AVLTreeMultiMapNode;
   }
 
   /**
@@ -375,6 +406,14 @@ export class TreeMultimap<
     return undefined;
   }
 
+  /**
+   * The function replaces an old node with a new node and updates the count property of the new node.
+   * @param {NODE} oldNode - The `oldNode` parameter is of type `NODE` and represents the node that
+   * needs to be replaced in a data structure.
+   * @param {NODE} newNode - The `newNode` parameter is an object of type `NODE`.
+   * @returns The method is returning the result of calling the `_replaceNode` method from the
+   * superclass, after updating the `count` property of the `newNode` object.
+   */
   protected _replaceNode(oldNode: NODE, newNode: NODE): NODE {
     newNode.count = oldNode.count + newNode.count;
     return super._replaceNode(oldNode, newNode);

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>([], {
@@ -680,9 +708,8 @@ export class BST<
         const compared = this._compare(cur.key, targetKey);
         if (compared === lesserOrGreater) ans.push(callback(cur));
 
-        if (!cur.left && !cur.right) return;
-        if (cur.left && this._compare(cur.left.key, targetKey) === lesserOrGreater) _traverse(cur.left);
-        if (cur.right && this._compare(cur.right.key, targetKey) === lesserOrGreater) _traverse(cur.right);
+        if (this.isRealNode(cur.left)) _traverse(cur.left);
+        if (this.isRealNode(cur.right)) _traverse(cur.right);
       };
 
       _traverse(this.root);
@@ -691,12 +718,12 @@ export class BST<
       const queue = new Queue<NODE>([this.root]);
       while (queue.size > 0) {
         const cur = queue.shift();
-        if (cur) {
+        if (this.isRealNode(cur)) {
           const compared = this._compare(cur.key, targetKey);
           if (compared === lesserOrGreater) ans.push(callback(cur));
 
-          if (cur.left && this._compare(cur.left.key, targetKey) === lesserOrGreater) queue.push(cur.left);
-          if (cur.right && this._compare(cur.right.key, targetKey) === lesserOrGreater) queue.push(cur.right);
+          if (this.isRealNode(cur.left)) queue.push(cur.left);
+          if (this.isRealNode(cur.right)) queue.push(cur.right);
         }
       }
       return ans;
@@ -824,6 +851,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/index.ts

@@ -4,4 +4,5 @@ export * from './binary-indexed-tree';
 export * from './segment-tree';
 export * from './avl-tree';
 export * from './rb-tree';
-export * from './tree-multimap';
+export * from './avl-tree-multi-map';
+export * from './tree-multi-map';