data-structure-typed 1.47.9 → 1.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.47.9",
+  "version": "1.48.0",
   "description": "Data Structures of Javascript & TypeScript. Heap, Binary Tree, RedBlack 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.",
   "main": "dist/cjs/index.js",
   "module": "dist/mjs/index.js",

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

@@ -82,6 +82,15 @@ export class AVLTree<V = any, N extends AVLTreeNode<V, N> = AVLTreeNode<V, AVLTr
     }) as TREE;
   }
 
+  /**
+   * The function checks if an exemplar is an instance of AVLTreeNode.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`.
+   * @returns a boolean value indicating whether the exemplar is an instance of the AVLTreeNode class.
+   */
+  override isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N {
+    return exemplar instanceof AVLTreeNode;
+  }
+
   /**
    * Time Complexity: O(log n) - logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (BST) has logarithmic time complexity.
    * Space Complexity: O(1) - constant space, as it doesn't use additional data structures that scale with input size.

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

@@ -163,6 +163,47 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
     return new BinaryTree<V, N, TREE>([], { iterationType: this.iterationType, ...options }) as TREE;
   }
 
+  /**
+   * The function "isNode" checks if an exemplar is an instance of the BinaryTreeNode class.
+   * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<V, N>`.
+   * @returns a boolean value indicating whether the exemplar is an instance of the class N.
+   */
+  isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N {
+    return exemplar instanceof BinaryTreeNode;
+  }
+
+  /**
+   * The function `exemplarToNode` converts an exemplar of a binary tree node into an actual node
+   * object.
+   * @param exemplar - BTNodeExemplar<V, N> - A generic type representing the exemplar parameter of the
+   * function. It can be any type.
+   * @returns a value of type `N` (which represents a node), or `null`, or `undefined`.
+   */
+  exemplarToNode(exemplar: BTNodeExemplar<V, N>): N | null | undefined {
+    if (exemplar === undefined) return;
+
+    let node: N | null | undefined;
+    if (exemplar === null) {
+      node = null;
+    } else if (this.isEntry(exemplar)) {
+      const [key, value] = exemplar;
+      if (key === undefined) {
+        return;
+      } else if (key === null) {
+        node = null;
+      } else {
+        node = this.createNode(key, value);
+      }
+    } else if (this.isNode(exemplar)) {
+      node = exemplar;
+    } else if (this.isNodeKey(exemplar)) {
+      node = this.createNode(exemplar);
+    } else {
+      return;
+    }
+    return node;
+  }
+
   /**
    * The function checks if a given value is an entry in a binary tree node.
    * @param kne - BTNodeExemplar<V, N> - A generic type representing a node in a binary tree. It has
@@ -188,7 +229,9 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
    */
   add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | null | undefined {
 
-    let inserted: N | null | undefined, needInsert: N | null | undefined;
+    let inserted: N | null | undefined;
+    const newNode = this.exemplarToNode(keyOrNodeOrEntry);
+    if (newNode === undefined) return;
 
     const _bfs = (root: N, newNode: N | null): N | undefined | null => {
       const queue = new Queue<N>([root]);
@@ -205,30 +248,11 @@ export class BinaryTree<V = any, N extends BinaryTreeNode<V, N> = BinaryTreeNode
       }
     };
 
-    if (keyOrNodeOrEntry === null) {
-      needInsert = null;
-    } else if (this.isNodeKey(keyOrNodeOrEntry)) {
-      needInsert = this.createNode(keyOrNodeOrEntry);
-    } else if (keyOrNodeOrEntry instanceof BinaryTreeNode) {
-      needInsert = keyOrNodeOrEntry;
-    } else if (this.isEntry(keyOrNodeOrEntry)) {
-      const [key, value] = keyOrNodeOrEntry;
-      if (key === undefined) {
-        return;
-      } else if (key === null) {
-        needInsert = null;
-      } else {
-        needInsert = this.createNode(key, value);
-      }
-    } else {
-      return;
-    }
-
     if (this.root) {
-      inserted = _bfs(this.root, needInsert);
+      inserted = _bfs(this.root, newNode);
     } else {
-      this._setRoot(needInsert);
-      if (needInsert) {
+      this._setRoot(newNode);
+      if (newNode) {
         this._size = 1;
       } else {
         this._size = 0;

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

@@ -143,6 +143,42 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
     }) as TREE;
   }
 
+  /**
+   * The function checks if an exemplar is an instance of BSTNode.
+   * @param exemplar - The `exemplar` parameter is a variable of type `BTNodeExemplar<V, N>`.
+   * @returns a boolean value indicating whether the exemplar is an instance of the BSTNode class.
+   */
+  override isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N {
+    return exemplar instanceof BSTNode;
+  }
+
+  /**
+   * The function `exemplarToNode` takes an exemplar and returns a corresponding node if the exemplar
+   * is valid, otherwise it returns undefined.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`.
+   * @returns a variable `node` which is of type `N` or `undefined`.
+   */
+  override exemplarToNode(exemplar: BTNodeExemplar<V, N>): N | undefined {
+    let node: N | undefined;
+    if (exemplar === null || exemplar === undefined) {
+      return;
+    } else if (this.isNode(exemplar)) {
+      node = exemplar;
+    } else if (this.isEntry(exemplar)) {
+      const [key, value] = exemplar;
+      if (key === undefined || key === null) {
+        return;
+      } else {
+        node = this.createNode(key, value);
+      }
+    } else if (this.isNodeKey(exemplar)) {
+      node = this.createNode(exemplar);
+    } else {
+      return;
+    }
+    return node;
+  }
+
   /**
    * Time Complexity: O(log n) - Average case for a balanced tree. In the worst case (unbalanced tree), it can be O(n).
    * Space Complexity: O(1) - Constant space is used.
@@ -159,25 +195,8 @@ export class BST<V = any, N extends BSTNode<V, N> = BSTNode<V, BSTNodeNested<V>>
    * (`keyOrNodeOrEntry`) is null, undefined, or does not match any of the expected types.
    */
   override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined {
-    if (keyOrNodeOrEntry === null || keyOrNodeOrEntry === undefined) {
-      return undefined;
-    }
-
-    let newNode: N | undefined;
-    if (keyOrNodeOrEntry instanceof BSTNode) {
-      newNode = keyOrNodeOrEntry;
-    } else if (this.isNodeKey(keyOrNodeOrEntry)) {
-      newNode = this.createNode(keyOrNodeOrEntry);
-    } else if (this.isEntry(keyOrNodeOrEntry)) {
-      const [key, value] = keyOrNodeOrEntry;
-      if (key === undefined || key === null) {
-        return;
-      } else {
-        newNode = this.createNode(key, value);
-      }
-    } else {
-      return;
-    }
+    const newNode = this.exemplarToNode(keyOrNodeOrEntry);
+    if (newNode === undefined) return;
 
     if (this.root === undefined) {
       this._setRoot(newNode);

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

@@ -107,38 +107,62 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
   }
 
   /**
-   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
-   * Space Complexity: O(1)
+   * The function checks if an exemplar is an instance of the RedBlackTreeNode class.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`.
+   * @returns a boolean value indicating whether the exemplar is an instance of the RedBlackTreeNode
+   * class.
    */
-
+  override isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N {
+    return exemplar instanceof RedBlackTreeNode;
+  }
 
   /**
-   * The function adds a node to a Red-Black Tree data structure.
-   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
-   * @returns The method `add` returns either an instance of `N` (the node that was added) or
-   * `undefined`.
+   * The function `exemplarToNode` takes an exemplar and returns a node if the exemplar is valid,
+   * otherwise it returns undefined.
+   * @param exemplar - BTNodeExemplar<V, N> - A generic type representing an exemplar of a binary tree
+   * node. It can be either a node itself, an entry (key-value pair), a node key, or any other value
+   * that is not a valid exemplar.
+   * @returns a variable `node` which is of type `N | undefined`.
    */
-  override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined {
-    let node: N;
-    if (this.isNodeKey(keyOrNodeOrEntry)) {
-      node = this.createNode(keyOrNodeOrEntry, undefined, RBTNColor.RED);
-    } else if (keyOrNodeOrEntry instanceof RedBlackTreeNode) {
-      node = keyOrNodeOrEntry;
-    } else if (keyOrNodeOrEntry === null || keyOrNodeOrEntry === undefined) {
+  override exemplarToNode(exemplar: BTNodeExemplar<V, N>): N | undefined {
+    let node: N | undefined;
+
+    if (exemplar === null || exemplar === undefined) {
       return;
-    } else if (this.isEntry(keyOrNodeOrEntry)) {
-      const [key, value] = keyOrNodeOrEntry;
+    } else if (this.isNode(exemplar)) {
+      node = exemplar;
+    } else if (this.isEntry(exemplar)) {
+      const [key, value] = exemplar;
       if (key === undefined || key === null) {
         return;
       } else {
         node = this.createNode(key, value, RBTNColor.RED);
       }
+    } else if (this.isNodeKey(exemplar)) {
+      node = this.createNode(exemplar, undefined, RBTNColor.RED);
     } else {
       return;
     }
+    return node;
+  }
+
+  /**
+   * Time Complexity: O(log n) on average (where n is the number of nodes in the tree)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * The function adds a node to a Red-Black Tree data structure.
+   * @param keyOrNodeOrEntry - The `keyOrNodeOrEntry` parameter can be one of the following:
+   * @returns The method `add` returns either an instance of `N` (the node that was added) or
+   * `undefined`.
+   */
+  override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>): N | undefined {
+    const newNode = this.exemplarToNode(keyOrNodeOrEntry);
+    if (newNode === undefined) return;
 
-    node.left = this.Sentinel;
-    node.right = this.Sentinel;
+    newNode.left = this.Sentinel;
+    newNode.right = this.Sentinel;
 
     let y: N | undefined = undefined;
     let x: N | undefined = this.root;
@@ -146,13 +170,13 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
     while (x !== this.Sentinel) {
       y = x;
       if (x) {
-        if (node.key < x.key) {
+        if (newNode.key < x.key) {
           x = x.left;
-        } else if (node.key > x.key) {
+        } else if (newNode.key > x.key) {
           x = x?.right;
         } else {
-          if (node !== x) {
-            this._replaceNode(x, node)
+          if (newNode !== x) {
+            this._replaceNode(x, newNode)
           }
           return;
         }
@@ -160,27 +184,27 @@ export class RedBlackTree<V = any, N extends RedBlackTreeNode<V, N> = RedBlackTr
 
     }
 
-    node.parent = y;
+    newNode.parent = y;
     if (y === undefined) {
-      this._setRoot(node);
-    } else if (node.key < y.key) {
-      y.left = node;
+      this._setRoot(newNode);
+    } else if (newNode.key < y.key) {
+      y.left = newNode;
     } else {
-      y.right = node;
+      y.right = newNode;
     }
 
-    if (node.parent === undefined) {
-      node.color = RBTNColor.BLACK;
+    if (newNode.parent === undefined) {
+      newNode.color = RBTNColor.BLACK;
       this._size++;
       return;
     }
 
-    if (node.parent.parent === undefined) {
+    if (newNode.parent.parent === undefined) {
       this._size++;
       return;
     }
 
-    this._fixInsert(node);
+    this._fixInsert(newNode);
     this._size++;
   }
 

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

@@ -80,6 +80,45 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
     }) as TREE;
   }
 
+  /**
+   * The function checks if an exemplar is an instance of the TreeMultimapNode class.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`.
+   * @returns a boolean value indicating whether the exemplar is an instance of the TreeMultimapNode
+   * class.
+   */
+  override isNode(exemplar: BTNodeExemplar<V, N>): exemplar is N {
+    return exemplar instanceof TreeMultimapNode;
+  }
+
+  /**
+   * The function `exemplarToNode` converts an exemplar object into a node object.
+   * @param exemplar - The `exemplar` parameter is of type `BTNodeExemplar<V, N>`, where `V` represents
+   * the value type and `N` represents the node type.
+   * @param [count=1] - The `count` parameter is an optional parameter that specifies the number of
+   * times the node should be created. If not provided, it defaults to 1.
+   * @returns a value of type `N` (the generic type parameter) or `undefined`.
+   */
+  override exemplarToNode(exemplar: BTNodeExemplar<V, N>, count = 1): N | undefined {
+    let node: N | undefined;
+    if (exemplar === undefined || exemplar === null) {
+      return;
+    } else if (this.isNode(exemplar)) {
+      node = exemplar;
+    } else if (this.isEntry(exemplar)) {
+      const [key, value] = exemplar;
+      if (key === undefined || key === null) {
+        return;
+      } else {
+        node = this.createNode(key, value, count);
+      }
+    } else if (this.isNodeKey(exemplar)) {
+      node = this.createNode(exemplar, undefined, count);
+    } else {
+      return;
+    }
+    return node;
+  }
+
   /**
    * Time Complexity: O(log n) - logarithmic time, where "n" is the number of nodes in the tree. The add method of the superclass (AVLTree) has logarithmic time complexity.
    * Space Complexity: O(1) - constant space, as it doesn't use additional data structures that scale with input size.
@@ -98,23 +137,9 @@ export class TreeMultimap<V = any, N extends TreeMultimapNode<V, N> = TreeMultim
    * @returns either a node (`N`) or `undefined`.
    */
   override add(keyOrNodeOrEntry: BTNodeExemplar<V, N>, count = 1): N | undefined {
-    let newNode: N | undefined;
-    if (keyOrNodeOrEntry === undefined || keyOrNodeOrEntry === null) {
-      return;
-    } else if (keyOrNodeOrEntry instanceof TreeMultimapNode) {
-      newNode = keyOrNodeOrEntry;
-    } else if (this.isNodeKey(keyOrNodeOrEntry)) {
-      newNode = this.createNode(keyOrNodeOrEntry, undefined, count);
-    } else if (this.isEntry(keyOrNodeOrEntry)) {
-      const [key, value] = keyOrNodeOrEntry;
-      if (key === undefined || key === null) {
-        return;
-      } else {
-        newNode = this.createNode(key, value, count);
-      }
-    } else {
-      return;
-    }
+    const newNode = this.exemplarToNode(keyOrNodeOrEntry, count);
+    if (newNode === undefined) return;
+
     const orgNodeCount = newNode?.count || 0;
     const inserted = super.add(newNode);
     if (inserted) {