data-structure-typed 1.51.0 → 1.51.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.51.0",
+  "version": "1.51.2",
   "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",
@@ -66,11 +66,11 @@
     "@typescript-eslint/eslint-plugin": "^6.7.4",
     "@typescript-eslint/parser": "^6.7.4",
     "auto-changelog": "^2.4.0",
-    "avl-tree-typed": "^1.50.9",
+    "avl-tree-typed": "^1.51.1",
     "benchmark": "^2.1.4",
-    "binary-tree-typed": "^1.50.9",
-    "bst-typed": "^1.50.9",
-    "data-structure-typed": "^1.50.9",
+    "binary-tree-typed": "^1.51.1",
+    "bst-typed": "^1.51.1",
+    "data-structure-typed": "^1.51.1",
     "dependency-cruiser": "^14.1.0",
     "doctoc": "^2.2.1",
     "eslint": "^8.50.0",
@@ -79,7 +79,7 @@
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.28.1",
     "fast-glob": "^3.3.1",
-    "heap-typed": "^1.50.9",
+    "heap-typed": "^1.51.1",
     "istanbul-badges-readme": "^1.8.5",
     "jest": "^29.7.0",
     "js-sdsl": "^4.4.2",

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

@@ -240,7 +240,7 @@ export class AVLTreeMultiMap<
    */
   override delete<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C>,
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     ignoreCount = false
   ): BinaryTreeDeleteResult<NODE>[] {
     const deletedResult: BinaryTreeDeleteResult<NODE>[] = [];

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

@@ -164,13 +164,13 @@ export class AVLTree<
    * `callback` function.
    * @param {C} callback - The `callback` parameter is a function that will be called for each node
    * that is deleted from the binary tree. It is an optional parameter and if not provided, it will
-   * default to the `_defaultOneParamCallback` function. The `callback` function should have a single
+   * default to the `_DEFAULT_CALLBACK` function. The `callback` function should have a single
    * parameter of type `NODE
    * @returns The method is returning an array of `BinaryTreeDeleteResult<NODE>`.
    */
   override delete<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C>,
-    callback: C = this._defaultOneParamCallback as C
+    callback: C = this._DEFAULT_CALLBACK as C
   ): BinaryTreeDeleteResult<NODE>[] {
     if ((identifier as any) instanceof AVLTreeNode) callback = (node => node) as C;
     const deletedResults = super.delete(identifier, callback);

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

@@ -191,6 +191,16 @@ export class BinaryTree<
     return this._size;
   }
 
+  protected _NIL: NODE = new BinaryTreeNode<K, V>(NaN as K) as unknown as NODE;
+
+  /**
+   * The function returns the value of the _NIL property.
+   * @returns The method is returning the value of the `_NIL` property.
+   */
+  get NIL(): NODE {
+    return this._NIL;
+  }
+
   /**
    * Creates a new instance of BinaryTreeNode with the given key and value.
    * @param {K} key - The key for the new node.
@@ -268,17 +278,26 @@ export class BinaryTree<
     keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>,
     iterationType: IterationType = 'ITERATIVE'
   ): NODE | null | undefined {
-    let res: NODE | null | undefined;
     if (this.isRealNode(keyOrNodeOrEntry)) {
-      res = keyOrNodeOrEntry;
+      return keyOrNodeOrEntry;
     } else if (this.isEntry(keyOrNodeOrEntry)) {
-      if (keyOrNodeOrEntry[0] === null) res = null;
-      else if (keyOrNodeOrEntry[0] !== undefined) res = this.getNodeByKey(keyOrNodeOrEntry[0], iterationType);
+      if (keyOrNodeOrEntry[0] === null) return null;
+      if (keyOrNodeOrEntry[0] === undefined) return;
+      return this.getNodeByKey(keyOrNodeOrEntry[0], iterationType);
     } else {
-      if (keyOrNodeOrEntry === null) res = null;
-      else if (keyOrNodeOrEntry !== undefined) res = this.getNodeByKey(keyOrNodeOrEntry, iterationType);
+      if (keyOrNodeOrEntry === null) return null;
+      if (keyOrNodeOrEntry === undefined) return;
+      return this.getNodeByKey(keyOrNodeOrEntry, iterationType);
     }
-    return res;
+  }
+
+  /**
+   * The function checks if a given node is a real node or null.
+   * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
+   * @returns a boolean value.
+   */
+  isNodeOrNull(node: KeyOrNodeOrEntry<K, V, NODE>): node is NODE | null {
+    return this.isRealNode(node) || node === null;
   }
 
   /**
@@ -290,16 +309,6 @@ export class BinaryTree<
     return keyOrNodeOrEntry instanceof BinaryTreeNode;
   }
 
-  /**
-   * The function checks if a given value is an entry in a binary tree node.
-   * @param keyOrNodeOrEntry - KeyOrNodeOrEntry<K, V,NODE> - A generic type representing a node in a binary tree. It has
-   * two type parameters V and NODE, representing the value and node type respectively.
-   * @returns a boolean value.
-   */
-  isEntry(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is BTNEntry<K, V> {
-    return Array.isArray(keyOrNodeOrEntry) && keyOrNodeOrEntry.length === 2;
-  }
-
   /**
    * The function checks if a given node is a real node by verifying if it is an instance of
    * BinaryTreeNode and its key is not NaN.
@@ -307,7 +316,8 @@ export class BinaryTree<
    * @returns a boolean value.
    */
   isRealNode(node: KeyOrNodeOrEntry<K, V, NODE>): node is NODE {
-    return node instanceof BinaryTreeNode && String(node.key) !== 'NaN';
+    if (!this.isNode(node)) return false;
+    return node !== this.NIL;
   }
 
   /**
@@ -316,16 +326,17 @@ export class BinaryTree<
    * @returns a boolean value.
    */
   isNIL(node: KeyOrNodeOrEntry<K, V, NODE>) {
-    return node instanceof BinaryTreeNode && String(node.key) === 'NaN';
+    return node === this.NIL;
   }
 
   /**
-   * The function checks if a given node is a real node or null.
-   * @param {any} node - The parameter `node` is of type `any`, which means it can be any data type.
+   * The function checks if a given value is an entry in a binary tree node.
+   * @param keyOrNodeOrEntry - KeyOrNodeOrEntry<K, V,NODE> - A generic type representing a node in a binary tree. It has
+   * two type parameters V and NODE, representing the value and node type respectively.
    * @returns a boolean value.
    */
-  isNodeOrNull(node: KeyOrNodeOrEntry<K, V, NODE>): node is NODE | null {
-    return this.isRealNode(node) || node === null;
+  isEntry(keyOrNodeOrEntry: KeyOrNodeOrEntry<K, V, NODE>): keyOrNodeOrEntry is BTNEntry<K, V> {
+    return Array.isArray(keyOrNodeOrEntry) && keyOrNodeOrEntry.length === 2;
   }
 
   /**
@@ -486,16 +497,16 @@ export class BinaryTree<
    * specific node based on its value or object.
    * @param {C} callback - The `callback` parameter is a function that is used to determine the
    * identifier of the node to be deleted. It is optional and has a default value of
-   * `this._defaultOneParamCallback`. The `callback` function should return the identifier of the node.
+   * `this._DEFAULT_CALLBACK`. The `callback` function should return the identifier of the node.
    * @returns an array of `BinaryTreeDeleteResult<NODE>`.
    */
   delete<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C> | null | undefined,
-    callback: C = this._defaultOneParamCallback as C
+    callback: C = this._DEFAULT_CALLBACK as C
   ): BinaryTreeDeleteResult<NODE>[] {
     const deletedResult: BinaryTreeDeleteResult<NODE>[] = [];
     if (!this.root) return deletedResult;
-    if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
+    if ((!callback || callback === this._DEFAULT_CALLBACK) && (identifier as any) instanceof BinaryTreeNode)
       callback = (node => node) as C;
 
     const curr = this.getNode(identifier, callback);
@@ -579,7 +590,7 @@ export class BinaryTree<
    * specific value.
    * @param {C} callback - The `callback` parameter is a function that takes a node of type `NODE` as
    * input and returns a value of type `C`. It is used to determine if a node matches the given
-   * identifier. If no callback is provided, the `_defaultOneParamCallback` function is used as the
+   * identifier. If no callback is provided, the `_DEFAULT_CALLBACK` function is used as the
    * default
    * @param [onlyOne=false] - A boolean value indicating whether to only return the first node that
    * matches the identifier. If set to true, the function will stop iterating once it finds a matching
@@ -594,12 +605,12 @@ export class BinaryTree<
    */
   getNodes<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C> | null | undefined,
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     onlyOne = false,
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType
   ): NODE[] {
-    if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
+    if ((!callback || callback === this._DEFAULT_CALLBACK) && (identifier as any) instanceof BinaryTreeNode)
       callback = (node => node) as C;
     beginRoot = this.ensureNode(beginRoot);
     if (!beginRoot) return [];
@@ -607,28 +618,28 @@ export class BinaryTree<
     const ans: NODE[] = [];
 
     if (iterationType === 'RECURSIVE') {
-      const _traverse = (cur: NODE) => {
+      const dfs = (cur: NODE) => {
         if (callback(cur) === identifier) {
           ans.push(cur);
           if (onlyOne) return;
         }
-        if (!cur.left && !cur.right) return;
-        cur.left && _traverse(cur.left);
-        cur.right && _traverse(cur.right);
+        if (!this.isRealNode(cur.left) && !this.isRealNode(cur.right)) return;
+        this.isRealNode(cur.left) && dfs(cur.left);
+        this.isRealNode(cur.right) && dfs(cur.right);
       };
 
-      _traverse(beginRoot);
+      dfs(beginRoot);
     } else {
-      const queue = new Queue<NODE>([beginRoot]);
-      while (queue.size > 0) {
-        const cur = queue.shift();
-        if (cur) {
+      const stack = [beginRoot];
+      while (stack.length > 0) {
+        const cur = stack.pop();
+        if (this.isRealNode(cur)) {
           if (callback(cur) === identifier) {
             ans.push(cur);
             if (onlyOne) return ans;
           }
-          cur.left && queue.push(cur.left);
-          cur.right && queue.push(cur.right);
+          this.isRealNode(cur.left) && stack.push(cur.left);
+          this.isRealNode(cur.right) && stack.push(cur.right);
         }
       }
     }
@@ -685,13 +696,10 @@ export class BinaryTree<
    */
   getNode<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C> | null | undefined,
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType
   ): NODE | null | undefined {
-    if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
-      callback = (node => node) as C;
-
     return this.getNodes(identifier, callback, true, beginRoot, iterationType)[0] ?? null;
   }
 
@@ -717,23 +725,23 @@ export class BinaryTree<
   getNodeByKey(key: K, iterationType: IterationType = 'ITERATIVE'): NODE | undefined {
     if (!this.root) return undefined;
     if (iterationType === 'RECURSIVE') {
-      const _dfs = (cur: NODE): NODE | undefined => {
+      const dfs = (cur: NODE): NODE | undefined => {
         if (cur.key === key) return cur;
 
         if (!cur.left && !cur.right) return;
-        if (cur.left) return _dfs(cur.left);
-        if (cur.right) return _dfs(cur.right);
+        if (cur.left) return dfs(cur.left);
+        if (cur.right) return dfs(cur.right);
       };
 
-      return _dfs(this.root);
+      return dfs(this.root);
     } else {
-      const queue = new Queue<NODE>([this.root]);
-      while (queue.size > 0) {
-        const cur = queue.shift();
+      const stack = [this.root];
+      while (stack.length > 0) {
+        const cur = stack.pop();
         if (cur) {
           if (cur.key === key) return cur;
-          cur.left && queue.push(cur.left);
-          cur.right && queue.push(cur.right);
+          cur.left && stack.push(cur.left);
+          cur.right && stack.push(cur.right);
         }
       }
     }
@@ -789,13 +797,10 @@ export class BinaryTree<
    */
   override get<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C> | null | undefined,
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType
   ): V | undefined {
-    if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
-      callback = (node => node) as C;
-
     return this.getNode(identifier, callback, beginRoot, iterationType)?.value ?? undefined;
   }
 
@@ -848,11 +853,11 @@ export class BinaryTree<
    */
   override has<C extends BTNCallback<NODE>>(
     identifier: ReturnType<C> | null | undefined,
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType
   ): boolean {
-    if ((!callback || callback === this._defaultOneParamCallback) && (identifier as any) instanceof BinaryTreeNode)
+    if ((!callback || callback === this._DEFAULT_CALLBACK) && (identifier as any) instanceof BinaryTreeNode)
       callback = (node => node) as C;
 
     return this.getNodes(identifier, callback, true, beginRoot, iterationType).length > 0;
@@ -1184,20 +1189,20 @@ export class BinaryTree<
     if (!this.isRealNode(beginRoot)) return beginRoot;
 
     if (iterationType === 'RECURSIVE') {
-      const _traverse = (cur: NODE): NODE => {
+      const dfs = (cur: NODE): NODE => {
         if (!this.isRealNode(cur.left)) return cur;
-        return _traverse(cur.left);
+        return dfs(cur.left);
       };
 
-      return _traverse(beginRoot);
+      return dfs(beginRoot);
     } else {
       // Indirect implementation of iteration using tail recursion optimization
-      const _traverse = trampoline((cur: NODE) => {
+      const dfs = trampoline((cur: NODE) => {
         if (!this.isRealNode(cur.left)) return cur;
-        return _traverse.cont(cur.left);
+        return dfs.cont(cur.left);
       });
 
-      return _traverse(beginRoot);
+      return dfs(beginRoot);
     }
   }
 
@@ -1231,20 +1236,20 @@ export class BinaryTree<
     if (!beginRoot) return beginRoot;
 
     if (iterationType === 'RECURSIVE') {
-      const _traverse = (cur: NODE): NODE => {
+      const dfs = (cur: NODE): NODE => {
         if (!this.isRealNode(cur.right)) return cur;
-        return _traverse(cur.right);
+        return dfs(cur.right);
       };
 
-      return _traverse(beginRoot);
+      return dfs(beginRoot);
     } else {
       // Indirect implementation of iteration using tail recursion optimization
-      const _traverse = trampoline((cur: NODE) => {
+      const dfs = trampoline((cur: NODE) => {
         if (!this.isRealNode(cur.right)) return cur;
-        return _traverse.cont(cur.right);
+        return dfs.cont(cur.right);
       });
 
-      return _traverse(beginRoot);
+      return dfs(beginRoot);
     }
   }
 
@@ -1351,7 +1356,7 @@ export class BinaryTree<
    * @returns an array of values that are the return values of the callback function.
    */
   dfs<C extends BTNCallback<NODE | null | undefined>>(
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     pattern: DFSOrderPattern = 'IN',
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = 'ITERATIVE',
@@ -1361,38 +1366,38 @@ export class BinaryTree<
     if (!beginRoot) return [];
     const ans: ReturnType<C>[] = [];
     if (iterationType === 'RECURSIVE') {
-      const _traverse = (node: NODE | null | undefined) => {
+      const dfs = (node: NODE | null | undefined) => {
         switch (pattern) {
           case 'IN':
             if (includeNull) {
-              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) _traverse(node.left);
+              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) dfs(node.left);
               this.isNodeOrNull(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) _traverse(node.right);
+              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) dfs(node.right);
             } else {
-              if (this.isRealNode(node) && this.isRealNode(node.left)) _traverse(node.left);
+              if (this.isRealNode(node) && this.isRealNode(node.left)) dfs(node.left);
               this.isRealNode(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isRealNode(node.right)) _traverse(node.right);
+              if (this.isRealNode(node) && this.isRealNode(node.right)) dfs(node.right);
             }
             break;
           case 'PRE':
             if (includeNull) {
               this.isNodeOrNull(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) _traverse(node.left);
-              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) _traverse(node.right);
+              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) dfs(node.left);
+              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) dfs(node.right);
             } else {
               this.isRealNode(node) && ans.push(callback(node));
-              if (this.isRealNode(node) && this.isRealNode(node.left)) _traverse(node.left);
-              if (this.isRealNode(node) && this.isRealNode(node.right)) _traverse(node.right);
+              if (this.isRealNode(node) && this.isRealNode(node.left)) dfs(node.left);
+              if (this.isRealNode(node) && this.isRealNode(node.right)) dfs(node.right);
             }
             break;
           case 'POST':
             if (includeNull) {
-              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) _traverse(node.left);
-              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) _traverse(node.right);
+              if (this.isRealNode(node) && this.isNodeOrNull(node.left)) dfs(node.left);
+              if (this.isRealNode(node) && this.isNodeOrNull(node.right)) dfs(node.right);
               this.isNodeOrNull(node) && ans.push(callback(node));
             } else {
-              if (this.isRealNode(node) && this.isRealNode(node.left)) _traverse(node.left);
-              if (this.isRealNode(node) && this.isRealNode(node.right)) _traverse(node.right);
+              if (this.isRealNode(node) && this.isRealNode(node.left)) dfs(node.left);
+              if (this.isRealNode(node) && this.isRealNode(node.right)) dfs(node.right);
               this.isRealNode(node) && ans.push(callback(node));
             }
 
@@ -1400,7 +1405,7 @@ export class BinaryTree<
         }
       };
 
-      _traverse(beginRoot);
+      dfs(beginRoot);
     } else {
       // 0: visit, 1: print
       const stack: { opt: 0 | 1; node: NODE | null | undefined }[] = [{ opt: 0, node: beginRoot }];
@@ -1486,7 +1491,7 @@ export class BinaryTree<
    * the breadth-first traversal of a binary tree.
    */
   bfs<C extends BTNCallback<NODE | null>>(
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType,
     includeNull = false
@@ -1499,7 +1504,7 @@ export class BinaryTree<
     if (iterationType === 'RECURSIVE') {
       const queue: Queue<NODE | null | undefined> = new Queue<NODE | null | undefined>([beginRoot]);
 
-      const traverse = (level: number) => {
+      const dfs = (level: number) => {
         if (queue.size === 0) return;
 
         const current = queue.shift()!;
@@ -1513,10 +1518,10 @@ export class BinaryTree<
           if (this.isRealNode(current.right)) queue.push(current.right);
         }
 
-        traverse(level + 1);
+        dfs(level + 1);
       };
 
-      traverse(0);
+      dfs(0);
     } else {
       const queue = new Queue<NODE | null | undefined>([beginRoot]);
       while (queue.size > 0) {
@@ -1580,7 +1585,7 @@ export class BinaryTree<
    * @returns The function `listLevels` returns a two-dimensional array of type `ReturnType<C>[][]`.
    */
   listLevels<C extends BTNCallback<NODE | null>>(
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root,
     iterationType: IterationType = this.iterationType,
     includeNull = false
@@ -1651,7 +1656,7 @@ export class BinaryTree<
    * by the return type of the `callback` function.
    */
   morris<C extends BTNCallback<NODE>>(
-    callback: C = this._defaultOneParamCallback as C,
+    callback: C = this._DEFAULT_CALLBACK as C,
     pattern: DFSOrderPattern = 'IN',
     beginRoot: KeyOrNodeOrEntry<K, V, NODE> = this.root
   ): ReturnType<C>[] {
@@ -1995,7 +2000,7 @@ export class BinaryTree<
     }
   }
 
-  protected _defaultOneParamCallback = (node: NODE | null | undefined) => (node ? node.key : undefined);
+  protected _DEFAULT_CALLBACK = (node: NODE | null | undefined) => (node ? node.key : undefined);
 
   /**
    * Swap the data of two nodes in the binary tree.