refactor: Extract the isNode and exemplarToNode methods to achieve be…

…st practices.
zrwusa · Nov 27, 2023 · e1e672b · e1e672b
1 parent 20550fb
commit e1e672b
Show file tree

Hide file tree

Showing 8 changed files with 226 additions and 124 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,7 +8,7 @@ All notable changes to this project will be documented in this file.
 - [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - [`auto-changelog`](https://github.com/CookPete/auto-changelog)
 
-## [v1.47.8](https://github.com/zrwusa/data-structure-typed/compare/v1.35.0...main) (upcoming)
+## [v1.47.9](https://github.com/zrwusa/data-structure-typed/compare/v1.35.0...main) (upcoming)
 
 ### Changes
 

diff --git a/README.md b/README.md
@@ -12,17 +12,7 @@
 Data Structures of Javascript & TypeScript.
 
 Do you envy C++ with [STL]() (std::), Python with [collections](), and Java with [java.util]() ? Well, no need to envy
-anymore! JavaScript and TypeScript now have [data-structure-typed]().
-
-Now you can use this in Node.js and browser environments
-
-CommonJS:**`require export.modules =`**
-
-ESModule:&nbsp;&nbsp;&nbsp;**`import export`**
-
-Typescript:&nbsp;&nbsp;&nbsp;**`import export`**
-
-UMD:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**`var Deque = dataStructureTyped.Deque`**
+anymore! JavaScript and TypeScript now have [data-structure-typed]().**`Benchmark`** compared with C++ STL. **`API standards`** aligned with ES6 and Java. **`Usability`** is comparable to Python
 
 
 [//]: # (![Branches]&#40;https://img.shields.io/badge/branches-55.47%25-red.svg?style=flat&#41;)
@@ -35,6 +25,17 @@ UMD:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**`var Deq
 
 ## Installation and Usage
 
+Now you can use it in Node.js and browser environments
+
+CommonJS:**`require export.modules =`**
+
+ESModule:&nbsp;&nbsp;&nbsp;**`import export`**
+
+Typescript:&nbsp;&nbsp;&nbsp;**`import export`**
+
+UMD:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;**`var Deque = dataStructureTyped.Deque`**
+
+
 ### npm
 
 ```bash
@@ -474,127 +475,127 @@ avl2.print();
 <td>Binary Tree</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/BinaryTree.html"><span>Binary Tree</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/BinaryTree.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Binary Search Tree (BST)</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/BST.html"><span>BST</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/BST.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>AVL Tree</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/AVLTree.html"><span>AVLTree</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/AVLTree.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Red Black Tree</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/RedBlackTree.html"><span>RedBlackTree</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/RedBlackTree.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Tree Multiset</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/TreeMultimap.html"><span>TreeMultimap</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/TreeMultimap.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Segment Tree</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/SegmentTree.html"><span>SegmentTree</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/SegmentTree.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Binary Indexed Tree</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/BinaryIndexedTree.html"><span>BinaryIndexedTree</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/BinaryIndexedTree.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Heap</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/Heap.html"><span>Heap</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/Heap.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Priority Queue</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/PriorityQueue.html"><span>PriorityQueue</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/PriorityQueue.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Max Priority Queue</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/MaxPriorityQueue.html"><span>MaxPriorityQueue</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/MaxPriorityQueue.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Min Priority Queue</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/MinPriorityQueue.html"><span>MinPriorityQueue</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/MinPriorityQueue.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Trie</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/Trie.html"><span>Trie</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/Trie.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Graph</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/AbstractGraph.html"><span>AbstractGraph</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/AbstractGraph.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Directed Graph</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/DirectedGraph.html"><span>DirectedGraph</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/DirectedGraph.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Undirected Graph</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/UndirectedGraph.html"><span>UndirectedGraph</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/UndirectedGraph.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Queue</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/Queue.html"><span>Queue</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/Queue.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Deque</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/Deque.html"><span>Deque</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/Deque.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Linked List</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/SinglyLinkedList.html"><span>SinglyLinkedList</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/SinglyLinkedList.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Singly Linked List</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/SinglyLinkedList.html"><span>SinglyLinkedList</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/SinglyLinkedList.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Doubly Linked List</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/DoublyLinkedList.html"><span>DoublyLinkedList</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/DoublyLinkedList.html"><span>View</span></a></td>
 </tr>
 <tr>
 <td>Stack</td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
 <td><img src="https://raw.githubusercontent.com/zrwusa/assets/master/images/data-structure-typed/assets/tick.svg" alt=""></td>
-<td><a href="https://data-structure-typed-docs.vercel.app/classes/Stack.html"><span>Stack</span></a></td>
+<td><a href="https://data-structure-typed-docs.vercel.app/classes/Stack.html"><span>View</span></a></td>
 </tr>
 </tbody>
 </table>

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.47.8",
+  "version": "1.47.9",
   "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",

diff --git a/src/data-structures/binary-tree/avl-tree.ts b/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.

diff --git a/src/data-structures/binary-tree/binary-tree.ts b/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;

diff --git a/src/data-structures/binary-tree/bst.ts b/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);