data-structure-typed 1.47.6 → 1.47.8

package/dist/mjs/data-structures/binary-tree/binary-tree.js

@@ -14,38 +14,17 @@ import { Queue } from '../queue';
  * @template N - The type of the family relationship in the binary tree.
  */
 export class BinaryTreeNode {
-    /**
-     * The key associated with the node.
-     */
     key;
-    /**
-     * The value stored in the node.
-     */
     value;
-    /**
-     * The parent node of the current node.
-     */
     parent;
-    /**
-     * Creates a new instance of BinaryTreeNode.
-     * @param {BTNKey} key - The key associated with the node.
-     * @param {V} value - The value stored in the node.
-     */
     constructor(key, value) {
         this.key = key;
         this.value = value;
     }
     _left;
-    /**
-     * Get the left child node.
-     */
     get left() {
         return this._left;
     }
-    /**
-     * Set the left child node.
-     * @param {N | null | undefined} v - The left child node.
-     */
     set left(v) {
         if (v) {
             v.parent = this;
@@ -53,16 +32,9 @@ export class BinaryTreeNode {
         this._left = v;
     }
     _right;
-    /**
-     * Get the right child node.
-     */
     get right() {
         return this._right;
     }
-    /**
-     * Set the right child node.
-     * @param {N | null | undefined} v - The right child node.
-     */
     set right(v) {
         if (v) {
             v.parent = this;
@@ -88,14 +60,26 @@ export class BinaryTreeNode {
     }
 }
 /**
- * Represents a binary tree data structure.
- * @template N - The type of the binary tree's nodes.
+ * 1. Two Children Maximum: Each node has at most two children.
+ * 2. Left and Right Children: Nodes have distinct left and right children.
+ * 3. Depth and Height: Depth is the number of edges from the root to a node; height is the maximum depth in the tree.
+ * 4. Subtrees: Each child of a node forms the root of a subtree.
+ * 5. Leaf Nodes: Nodes without children are leaves.
+ * 6. Internal Nodes: Nodes with at least one child are internal.
+ * 7. Balanced Trees: The heights of the left and right subtrees of any node differ by no more than one.
+ * 8. Full Trees: Every node has either 0 or 2 children.
+ * 9. Complete Trees: All levels are fully filled except possibly the last, filled from left to right.
  */
 export class BinaryTree {
     iterationType = IterationType.ITERATIVE;
     /**
-     * Creates a new instance of BinaryTree.
-     * @param {BinaryTreeOptions} [options] - The options for the binary tree.
+     * The constructor function initializes a binary tree object with optional elements and options.
+     * @param [elements] - An optional iterable of BTNodeExemplar objects. These objects represent the
+     * elements to be added to the binary tree.
+     * @param [options] - The `options` parameter is an optional object that can contain additional
+     * configuration options for the binary tree. In this case, it is of type
+     * `Partial<BinaryTreeOptions>`, which means that not all properties of `BinaryTreeOptions` are
+     * required.
      */
     constructor(elements, options) {
         if (options) {
@@ -106,19 +90,13 @@ export class BinaryTree {
         }
         this._size = 0;
         if (elements)
-            this.init(elements);
+            this.addMany(elements);
     }
     _root;
-    /**
-     * Get the root node of the binary tree.
-     */
     get root() {
         return this._root;
     }
     _size;
-    /**
-     * Get the number of nodes in the binary tree.
-     */
     get size() {
         return this._size;
     }
@@ -131,30 +109,46 @@ export class BinaryTree {
     createNode(key, value) {
         return new BinaryTreeNode(key, value);
     }
+    /**
+     * The function creates a binary tree with the given options.
+     * @param [options] - The `options` parameter is an optional object that allows you to customize the
+     * behavior of the `BinaryTree` class. It is of type `Partial<BinaryTreeOptions>`, which means that
+     * you can provide only a subset of the properties defined in the `BinaryTreeOptions` interface.
+     * @returns a new instance of a binary tree.
+     */
     createTree(options) {
         return new BinaryTree([], { iterationType: this.iterationType, ...options });
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
+     * 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
+     * two type parameters V and N, representing the value and node type respectively.
+     * @returns a boolean value.
+     */
+    isEntry(kne) {
+        return Array.isArray(kne) && kne.length === 2;
+    }
+    /**
+     * Time Complexity O(log n) - O(n)
+     * Space Complexity O(1)
+     */
+    /**
+     * Time Complexity O(log n) - O(n)
+     * Space Complexity O(1)
      *
-     * The `add` function adds a new node with a key and value to a binary tree, or updates the value of
-     * an existing node with the same key.
-     * @param {BTNKey | N | null | undefined} keyOrNode - The `keyOrNode` parameter can be one of the
-     * following types:
-     * @param {V} [value] - The value to be associated with the key or node being added to the binary
-     * tree.
-     * @returns The function `add` returns a node (`N`) if it was successfully inserted into the binary
-     * tree, or `null` or `undefined` if the insertion was not successful.
+     * The `add` function adds a new node to a binary tree, either by key or by providing a node object.
+     * @param keyOrNodeOrEntry - The parameter `keyOrNodeOrEntry` can be one of the following:
+     * @returns The function `add` returns the inserted node (`N`), `null`, or `undefined`.
      */
-    add(keyOrNode, value) {
+    add(keyOrNodeOrEntry) {
+        let inserted, needInsert;
         const _bfs = (root, newNode) => {
             const queue = new Queue([root]);
             while (queue.size > 0) {
                 const cur = queue.shift();
                 if (newNode && cur.key === newNode.key) {
-                    cur.value = newNode.value;
-                    return;
+                    this._replaceNode(cur, newNode);
+                    return newNode;
                 }
                 const inserted = this._addTo(newNode, cur);
                 if (inserted !== undefined)
@@ -165,15 +159,26 @@ export class BinaryTree {
                     queue.push(cur.right);
             }
         };
-        let inserted, needInsert;
-        if (keyOrNode === null) {
+        if (keyOrNodeOrEntry === null) {
             needInsert = null;
         }
-        else if (this.isNodeKey(keyOrNode)) {
-            needInsert = this.createNode(keyOrNode, value);
+        else if (this.isNodeKey(keyOrNodeOrEntry)) {
+            needInsert = this.createNode(keyOrNodeOrEntry);
+        }
+        else if (keyOrNodeOrEntry instanceof BinaryTreeNode) {
+            needInsert = keyOrNodeOrEntry;
         }
-        else if (keyOrNode instanceof BinaryTreeNode) {
-            needInsert = keyOrNode;
+        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;
@@ -194,36 +199,28 @@ export class BinaryTree {
         return inserted;
     }
     /**
-     * Time Complexity: O(n)
+     * Time Complexity: O(k log n) - O(k * n)
      * Space Complexity: O(1)
      * Comments: The time complexity for adding a node depends on the depth of the tree. In the best case (when the tree is empty), it's O(1). In the worst case (when the tree is a degenerate tree), it's O(n). The space complexity is constant.
      */
     /**
-     * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
+     * Time Complexity: O(k log n) - O(k * n)
      * Space Complexity: O(1)
      *
-     * The `addMany` function takes an array of keys or nodes and an optional array of values, and adds
-     * each key-value pair to a data structure.
-     * @param {(BTNKey | N |null | undefined)[]} keysOrNodes - An array of keys or nodes to be added to
-     * the binary search tree. Each element can be of type `BTNKey` (a key value), `N` (a node), `null`,
-     * or `undefined`.
-     * @param {(V | undefined)[]} [values] - The `values` parameter is an optional array of values that
-     * correspond to the keys or nodes being added. If provided, the values will be associated with the
-     * keys or nodes during the add operation.
-     * @returns The function `addMany` returns an array of `N`, `null`, or `undefined` values.
-     */
-    addMany(keysOrNodes, values) {
+     * The function `addMany` takes in an iterable of `BTNodeExemplar` objects, adds each object to the
+     * current instance, and returns an array of the inserted nodes.
+     * @param nodes - The `nodes` parameter is an iterable (such as an array or a set) of
+     * `BTNodeExemplar<V, N>` objects.
+     * @returns The function `addMany` returns an array of values, where each value is either of type
+     * `N`, `null`, or `undefined`.
+     */
+    addMany(nodes) {
         // TODO not sure addMany not be run multi times
-        return keysOrNodes.map((keyOrNode, i) => {
-            if (keyOrNode instanceof BinaryTreeNode) {
-                return this.add(keyOrNode.key, keyOrNode.value);
-            }
-            if (keyOrNode === null) {
-                return this.add(null);
-            }
-            const value = values?.[i];
-            return this.add(keyOrNode, value);
-        });
+        const inserted = [];
+        for (const kne of nodes) {
+            inserted.push(this.add(kne));
+        }
+        return inserted;
     }
     /**
      * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
@@ -233,17 +230,13 @@ export class BinaryTree {
      * Time Complexity: O(k * n)  "n" is the number of nodes in the tree, and "k" is the number of keys to be inserted.
      * Space Complexity: O(1)
      *
-     * The `refill` function clears the binary tree and adds multiple nodes with the given IDs or nodes and optional data.
-     * @param {(BTNKey | N)[]} keysOrNodes - The `keysOrNodes` parameter is an array that can contain either
-     * `BTNKey` or `N` values.
-     * @param {N[] | Array<V>} [values] - The `data` parameter is an optional array of values that will be assigned to
-     * the nodes being added. If provided, the length of the `data` array should be equal to the length of the `keysOrNodes`
-     * array. Each value in the `data` array will be assigned to the
-     * @returns The method is returning a boolean value.
+     * The `refill` function clears the current collection and adds new nodes, keys, or entries to it.
+     * @param nodesOrKeysOrEntries - The parameter `nodesOrKeysOrEntries` is an iterable object that can
+     * contain either `BTNodeExemplar` objects, keys, or entries.
      */
-    refill(keysOrNodes, values) {
+    refill(nodesOrKeysOrEntries) {
         this.clear();
-        return keysOrNodes.length === this.addMany(keysOrNodes, values).length;
+        this.addMany(nodesOrKeysOrEntries);
     }
     /**
      * Time Complexity: O(n)
@@ -293,7 +286,7 @@ export class BinaryTree {
                 const leftSubTreeRightMost = this.getRightMost(curr.left);
                 if (leftSubTreeRightMost) {
                     const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
-                    orgCurrent = this._swap(curr, leftSubTreeRightMost);
+                    orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
                     if (parentOfLeftSubTreeMax) {
                         if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost)
                             parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
@@ -326,8 +319,8 @@ export class BinaryTree {
      * @returns the depth of the `distNode` relative to the `beginRoot`.
      */
     getDepth(distNode, beginRoot = this.root) {
-        distNode = this.ensureNotKey(distNode);
-        beginRoot = this.ensureNotKey(beginRoot);
+        distNode = this.ensureNode(distNode);
+        beginRoot = this.ensureNode(beginRoot);
         let depth = 0;
         while (distNode?.parent) {
             if (distNode === beginRoot) {
@@ -357,7 +350,7 @@ export class BinaryTree {
      * @returns the height of the binary tree.
      */
     getHeight(beginRoot = this.root, iterationType = this.iterationType) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return -1;
         if (iterationType === IterationType.RECURSIVE) {
@@ -403,7 +396,7 @@ export class BinaryTree {
      * @returns The function `getMinHeight` returns the minimum height of a binary tree.
      */
     getMinHeight(beginRoot = this.root, iterationType = this.iterationType) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return -1;
         if (iterationType === IterationType.RECURSIVE) {
@@ -493,7 +486,7 @@ export class BinaryTree {
     getNodes(identifier, callback = this._defaultOneParamCallback, onlyOne = false, beginRoot = this.root, iterationType = this.iterationType) {
         if ((!callback || callback === this._defaultOneParamCallback) && identifier instanceof BinaryTreeNode)
             callback = (node => node);
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
         const ans = [];
@@ -631,7 +624,7 @@ export class BinaryTree {
      * Space Complexity: O(log n)
      */
     /**
-     * The function `ensureNotKey` returns the node corresponding to the given key if it is a valid node
+     * The function `ensureNode` returns the node corresponding to the given key if it is a valid node
      * key, otherwise it returns the key itself.
      * @param {BTNKey | N | null | undefined} key - The `key` parameter can be of type `BTNKey`, `N`,
      * `null`, or `undefined`. It represents a key used to identify a node in a binary tree.
@@ -641,7 +634,7 @@ export class BinaryTree {
      * @returns either the node corresponding to the given key if it is a valid node key, or the key
      * itself if it is not a valid node key.
      */
-    ensureNotKey(key, iterationType = IterationType.ITERATIVE) {
+    ensureNode(key, iterationType = IterationType.ITERATIVE) {
         return this.isNodeKey(key) ? this.getNodeByKey(key, iterationType) : key;
     }
     /**
@@ -706,7 +699,7 @@ export class BinaryTree {
     getPathToRoot(beginRoot, isReverse = true) {
         // TODO to support get path through passing key
         const result = [];
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return result;
         while (beginRoot.parent) {
@@ -737,7 +730,7 @@ export class BinaryTree {
      * is no leftmost node, it returns `null` or `undefined` depending on the input.
      */
     getLeftMost(beginRoot = this.root, iterationType = this.iterationType) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return beginRoot;
         if (iterationType === IterationType.RECURSIVE) {
@@ -779,7 +772,7 @@ export class BinaryTree {
      */
     getRightMost(beginRoot = this.root, iterationType = this.iterationType) {
         // TODO support get right most by passing key in
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return beginRoot;
         if (iterationType === IterationType.RECURSIVE) {
@@ -818,7 +811,7 @@ export class BinaryTree {
      */
     isSubtreeBST(beginRoot, iterationType = this.iterationType) {
         // TODO there is a bug
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return true;
         if (iterationType === IterationType.RECURSIVE) {
@@ -891,7 +884,7 @@ export class BinaryTree {
      * by the return type of the `callback` function.
      */
     subTreeTraverse(callback = this._defaultOneParamCallback, beginRoot = this.root, iterationType = this.iterationType, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         const ans = [];
         if (!beginRoot)
             return ans;
@@ -992,7 +985,7 @@ export class BinaryTree {
      * @returns an array of values that are the return values of the callback function.
      */
     dfs(callback = this._defaultOneParamCallback, pattern = 'in', beginRoot = this.root, iterationType = IterationType.ITERATIVE, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
         const ans = [];
@@ -1119,7 +1112,7 @@ export class BinaryTree {
      * the breadth-first traversal of a binary tree.
      */
     bfs(callback = this._defaultOneParamCallback, beginRoot = this.root, iterationType = this.iterationType, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return [];
         const ans = [];
@@ -1192,7 +1185,7 @@ export class BinaryTree {
      * @returns The function `listLevels` returns a two-dimensional array of type `ReturnType<C>[][]`.
      */
     listLevels(callback = this._defaultOneParamCallback, beginRoot = this.root, iterationType = this.iterationType, includeNull = false) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         const levelsNodes = [];
         if (!beginRoot)
             return levelsNodes;
@@ -1247,7 +1240,7 @@ export class BinaryTree {
      * @returns The function `getPredecessor` returns a value of type `N | undefined`.
      */
     getPredecessor(node) {
-        node = this.ensureNotKey(node);
+        node = this.ensureNode(node);
         if (!this.isRealNode(node))
             return undefined;
         if (node.left) {
@@ -1270,7 +1263,7 @@ export class BinaryTree {
      * after the given node in the inorder traversal of the binary tree.
      */
     getSuccessor(x) {
-        x = this.ensureNotKey(x);
+        x = this.ensureNode(x);
         if (!x)
             return undefined;
         if (x.right) {
@@ -1302,7 +1295,7 @@ export class BinaryTree {
      * by the return type of the `callback` function.
      */
     morris(callback = this._defaultOneParamCallback, pattern = 'in', beginRoot = this.root) {
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (beginRoot === null)
             return [];
         const ans = [];
@@ -1413,7 +1406,7 @@ export class BinaryTree {
         const newTree = this.createTree();
         for (const [key, value] of this) {
             if (predicate([key, value], this)) {
-                newTree.add(key, value);
+                newTree.add([key, value]);
             }
         }
         return newTree;
@@ -1427,7 +1420,7 @@ export class BinaryTree {
     map(callback) {
         const newTree = this.createTree();
         for (const [key, value] of this) {
-            newTree.add(key, callback([key, value], this));
+            newTree.add([key, callback([key, value], this)]);
         }
         return newTree;
     }
@@ -1504,7 +1497,7 @@ export class BinaryTree {
      */
     print(beginRoot = this.root, options) {
         const opts = { isShowUndefined: false, isShowNull: false, isShowRedBlackNIL: false, ...options };
-        beginRoot = this.ensureNotKey(beginRoot);
+        beginRoot = this.ensureNode(beginRoot);
         if (!beginRoot)
             return;
         if (opts.isShowUndefined)
@@ -1524,19 +1517,6 @@ export class BinaryTree {
         };
         display(beginRoot);
     }
-    init(elements) {
-        if (elements) {
-            for (const entryOrKey of elements) {
-                if (Array.isArray(entryOrKey)) {
-                    const [key, value] = entryOrKey;
-                    this.add(key, value);
-                }
-                else {
-                    this.add(entryOrKey);
-                }
-            }
-        }
-    }
     _displayAux(node, options) {
         const { isShowNull, isShowUndefined, isShowRedBlackNIL } = options;
         const emptyDisplayLayout = [['─'], 1, 0, 0];
@@ -1587,9 +1567,9 @@ export class BinaryTree {
      * @param {N} destNode - The destination node to swap.
      * @returns {N} - The destination node after the swap.
      */
-    _swap(srcNode, destNode) {
-        srcNode = this.ensureNotKey(srcNode);
-        destNode = this.ensureNotKey(destNode);
+    _swapProperties(srcNode, destNode) {
+        srcNode = this.ensureNode(srcNode);
+        destNode = this.ensureNode(destNode);
         if (srcNode && destNode) {
             const { key, value } = destNode;
             const tempNode = this.createNode(key, value);
@@ -1603,6 +1583,31 @@ export class BinaryTree {
         }
         return undefined;
     }
+    /**
+     * The function replaces an old node with a new node in a binary tree.
+     * @param {N} oldNode - The oldNode parameter represents the node that needs to be replaced in the
+     * tree.
+     * @param {N} newNode - The `newNode` parameter is the node that will replace the `oldNode` in the
+     * tree.
+     * @returns The method is returning the newNode.
+     */
+    _replaceNode(oldNode, newNode) {
+        if (oldNode.parent) {
+            if (oldNode.parent.left === oldNode) {
+                oldNode.parent.left = newNode;
+            }
+            else if (oldNode.parent.right === oldNode) {
+                oldNode.parent.right = newNode;
+            }
+        }
+        newNode.left = oldNode.left;
+        newNode.right = oldNode.right;
+        newNode.parent = oldNode.parent;
+        if (this.root === oldNode) {
+            this._root = newNode;
+        }
+        return newNode;
+    }
     /**
      * The function `_addTo` adds a new node to a binary tree if there is an available position.
      * @param {N | null | undefined} newNode - The `newNode` parameter represents the node that you want to add to