queue-typed 1.53.5 → 1.53.7

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

@@ -29,7 +29,7 @@ import { IBinaryTree } from '../../interfaces';
 import { isComparable, trampoline } from '../../utils';
 import { Queue } from '../queue';
 import { IterableEntryBase } from '../base';
-import { DFSOperation } from '../../constants';
+import { DFSOperation, Range } from '../../common';
 
 /**
  * Represents a node in a binary tree.
@@ -233,17 +233,14 @@ export class BinaryTree<
       return [this.createNode(key, finalValue), finalValue];
     }
 
-    if (this.isKey(keyNodeEntryOrRaw)) return [this.createNode(keyNodeEntryOrRaw, value), value];
-
     if (this.isRaw(keyNodeEntryOrRaw)) {
-      if (this._toEntryFn) {
-        const [key, entryValue] = this._toEntryFn(keyNodeEntryOrRaw);
-        const finalValue = value ?? entryValue;
-        if (this.isKey(key)) return [this.createNode(key, finalValue), finalValue];
-      }
-      return [undefined, undefined];
+      const [key, entryValue] = this._toEntryFn!(keyNodeEntryOrRaw);
+      const finalValue = value ?? entryValue;
+      if (this.isKey(key)) return [this.createNode(key, finalValue), finalValue];
     }
 
+    if (this.isKey(keyNodeEntryOrRaw)) return [this.createNode(keyNodeEntryOrRaw, value), value];
+
     return [undefined, undefined];
   }
 
@@ -275,15 +272,15 @@ export class BinaryTree<
       const key = keyNodeEntryOrRaw[0];
       if (key === null) return null;
       if (key === undefined) return;
-      return this.getNodeByKey(key, iterationType);
+      return this.getNode(key, this._root, iterationType);
     }
 
     if (this._toEntryFn) {
       const [key] = this._toEntryFn(keyNodeEntryOrRaw as R);
-      if (this.isKey(key)) return this.getNodeByKey(key);
+      if (this.isKey(key)) return this.getNode(key);
     }
 
-    if (this.isKey(keyNodeEntryOrRaw)) return this.getNodeByKey(keyNodeEntryOrRaw, iterationType);
+    if (this.isKey(keyNodeEntryOrRaw)) return this.getNode(keyNodeEntryOrRaw, this._root, iterationType);
     return;
   }
 
@@ -302,8 +299,15 @@ export class BinaryTree<
     return keyNodeEntryOrRaw instanceof BinaryTreeNode;
   }
 
+  /**
+   * The function `isRaw` checks if the input parameter is of type `R` by verifying if it is an object.
+   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - BTNRep<K, V, NODE> | R
+   * @returns The function `isRaw` is checking if the `keyNodeEntryOrRaw` parameter is of type `R` by
+   * checking if it is an object. If the parameter is an object, the function will return `true`,
+   * indicating that it is of type `R`.
+   */
   isRaw(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): keyNodeEntryOrRaw is R {
-    return typeof keyNodeEntryOrRaw === 'object';
+    return this._toEntryFn !== undefined && typeof keyNodeEntryOrRaw === 'object';
   }
 
   /**
@@ -345,6 +349,12 @@ export class BinaryTree<
     return keyNodeEntryOrRaw === this._NIL;
   }
 
+  isRange(
+    keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE> | Range<K>
+  ): keyNodeEntryRawOrPredicate is Range<K> {
+    return keyNodeEntryRawOrPredicate instanceof Range;
+  }
+
   /**
    * The function determines whether a given key, node, entry, or raw data is a leaf node in a binary
    * tree.
@@ -508,6 +518,18 @@ export class BinaryTree<
     return inserted;
   }
 
+  /**
+   * Time Complexity: O(k * n)
+   * Space Complexity: O(1)
+   *
+   * The `merge` function in TypeScript merges another binary tree into the current tree by adding all
+   * elements from the other tree.
+   * @param anotherTree - `BinaryTree<K, V, R, NODE, TREE>`
+   */
+  merge(anotherTree: BinaryTree<K, V, R, NODE, TREE>) {
+    this.addMany(anotherTree, []);
+  }
+
   /**
    * Time Complexity: O(k * n)
    * Space Complexity: O(1)
@@ -589,41 +611,45 @@ export class BinaryTree<
    * Time Complexity: O(n)
    * Space Complexity: O(k + log n)
    *
-   * The function `getNodes` retrieves nodes from a binary tree based on a key, node, entry, raw data,
-   * or predicate, with options for recursive or iterative traversal.
-   * @param {BTNRep<K, V, NODE> | R | NodePredicate<NODE>} keyNodeEntryRawOrPredicate
-   * - The `getNodes` function you provided takes several parameters:
-   * @param [onlyOne=false] - The `onlyOne` parameter in the `getNodes` function is a boolean flag that
-   * determines whether to return only the first node that matches the criteria specified by the
-   * `keyNodeEntryRawOrPredicate` parameter. If `onlyOne` is set to `true`, the function will
-   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter in the
-   * `getNodes` function is used to specify the starting point for traversing the binary tree. It
-   * represents the root node of the binary tree or the node from which the traversal should begin. If
-   * not provided, the default value is set to `this._root
-   * @param {IterationType} iterationType - The `iterationType` parameter in the `getNodes` function
-   * determines the type of iteration to be performed when traversing the nodes of a binary tree. It
-   * can have two possible values:
-   * @returns The `getNodes` function returns an array of nodes that satisfy the provided condition
-   * based on the input parameters and the iteration type specified.
+   * The `search` function in TypeScript performs a depth-first or breadth-first search on a tree
+   * structure based on a given predicate or key, with options to return multiple results or just one.
+   * @param {BTNRep<K, V, NODE> | R | NodePredicate<NODE>} keyNodeEntryRawOrPredicate - The
+   * `keyNodeEntryRawOrPredicate` parameter in the `search` function can accept three types of values:
+   * @param [onlyOne=false] - The `onlyOne` parameter in the `search` function is a boolean flag that
+   * determines whether the search should stop after finding the first matching node. If `onlyOne` is
+   * set to `true`, the search will return as soon as a matching node is found. If `onlyOne` is
+   * @param {C} callback - The `callback` parameter in the `search` function is a callback function
+   * that will be called on each node that matches the search criteria. It is of type `C`, which
+   * extends `NodeCallback<NODE>`. The default value for `callback` is `this._DEFAULT_NODE_CALLBACK` if
+   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter in the `search` function is
+   * used to specify the node from which the search operation should begin. It represents the starting
+   * point in the binary tree where the search will be performed. If no specific `startNode` is
+   * provided, the search operation will start from the root
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `search` function
+   * specifies the type of iteration to be used when searching for nodes in a binary tree. It can have
+   * two possible values:
+   * @returns The `search` function returns an array of values that match the provided criteria based
+   * on the search algorithm implemented within the function.
    */
-  getNodes(
+  search<C extends NodeCallback<NODE>>(
     keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE>,
     onlyOne = false,
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
     startNode: BTNRep<K, V, NODE> | R = this._root,
     iterationType: IterationType = this.iterationType
-  ): NODE[] {
+  ): ReturnType<C>[] {
     if (keyNodeEntryRawOrPredicate === undefined) return [];
     if (keyNodeEntryRawOrPredicate === null) return [];
     startNode = this.ensureNode(startNode);
     if (!startNode) return [];
-    const callback = this._ensurePredicate(keyNodeEntryRawOrPredicate);
+    const predicate = this._ensurePredicate(keyNodeEntryRawOrPredicate);
 
-    const ans: NODE[] = [];
+    const ans: ReturnType<C>[] = [];
 
     if (iterationType === 'RECURSIVE') {
       const dfs = (cur: NODE) => {
-        if (callback(cur)) {
-          ans.push(cur);
+        if (predicate(cur)) {
+          ans.push(callback(cur));
           if (onlyOne) return;
         }
         if (!this.isRealNode(cur.left) && !this.isRealNode(cur.right)) return;
@@ -637,8 +663,8 @@ export class BinaryTree<
       while (stack.length > 0) {
         const cur = stack.pop();
         if (this.isRealNode(cur)) {
-          if (callback(cur)) {
-            ans.push(cur);
+          if (predicate(cur)) {
+            ans.push(callback(cur));
             if (onlyOne) return ans;
           }
           if (this.isRealNode(cur.left)) stack.push(cur.left);
@@ -650,6 +676,36 @@ export class BinaryTree<
     return ans;
   }
 
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(k + log n)
+   *
+   * The function `getNodes` retrieves nodes from a binary tree based on a key, node, entry, raw data,
+   * or predicate, with options for recursive or iterative traversal.
+   * @param {BTNRep<K, V, NODE> | R | NodePredicate<NODE>} keyNodeEntryRawOrPredicate
+   * - The `getNodes` function you provided takes several parameters:
+   * @param [onlyOne=false] - The `onlyOne` parameter in the `getNodes` function is a boolean flag that
+   * determines whether to return only the first node that matches the criteria specified by the
+   * `keyNodeEntryRawOrPredicate` parameter. If `onlyOne` is set to `true`, the function will
+   * @param {BTNRep<K, V, NODE> | R} startNode - The `startNode` parameter in the
+   * `getNodes` function is used to specify the starting point for traversing the binary tree. It
+   * represents the root node of the binary tree or the node from which the traversal should begin. If
+   * not provided, the default value is set to `this._root
+   * @param {IterationType} iterationType - The `iterationType` parameter in the `getNodes` function
+   * determines the type of iteration to be performed when traversing the nodes of a binary tree. It
+   * can have two possible values:
+   * @returns The `getNodes` function returns an array of nodes that satisfy the provided condition
+   * based on the input parameters and the iteration type specified.
+   */
+  getNodes(
+    keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE>,
+    onlyOne = false,
+    startNode: BTNRep<K, V, NODE> | R = this._root,
+    iterationType: IterationType = this.iterationType
+  ): NODE[] {
+    return this.search(keyNodeEntryRawOrPredicate, onlyOne, node => node, startNode, iterationType);
+  }
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(log n).
@@ -675,24 +731,7 @@ export class BinaryTree<
     startNode: BTNRep<K, V, NODE> | R = this._root,
     iterationType: IterationType = this.iterationType
   ): OptNodeOrNull<NODE> {
-    return this.getNodes(keyNodeEntryRawOrPredicate, true, startNode, iterationType)[0] ?? null;
-  }
-
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(log n)
-   *
-   * The function `getNodeByKey` retrieves a node by its key from a binary tree structure.
-   * @param {K} key - The `key` parameter is the value used to search for a specific node in a data
-   * structure.
-   * @param {IterationType} iterationType - The `iterationType` parameter is a type of iteration that
-   * specifies how the tree nodes should be traversed when searching for a node with the given key. It
-   * is an optional parameter with a default value of `this.iterationType`.
-   * @returns The `getNodeByKey` function is returning an optional binary tree node
-   * (`OptNodeOrNull<NODE>`).
-   */
-  getNodeByKey(key: K, iterationType: IterationType = this.iterationType): OptNodeOrNull<NODE> {
-    return this.getNode(key, this._root, iterationType);
+    return this.search(keyNodeEntryRawOrPredicate, true, node => node, startNode, iterationType)[0] ?? null;
   }
 
   /**
@@ -723,7 +762,7 @@ export class BinaryTree<
     iterationType: IterationType = this.iterationType
   ): V | undefined {
     if (this._isMapMode) {
-      const key = this._getKey(keyNodeEntryRawOrPredicate);
+      const key = this._extractKey(keyNodeEntryRawOrPredicate);
       if (key === null || key === undefined) return;
       return this._store.get(key);
     }
@@ -756,7 +795,7 @@ export class BinaryTree<
     startNode: BTNRep<K, V, NODE> | R = this._root,
     iterationType: IterationType = this.iterationType
   ): boolean {
-    return this.getNodes(keyNodeEntryRawOrPredicate, true, startNode, iterationType).length > 0;
+    return this.search(keyNodeEntryRawOrPredicate, true, node => node, startNode, iterationType).length > 0;
   }
 
   /**
@@ -1023,9 +1062,9 @@ export class BinaryTree<
    * parameter.
    */
   getPathToRoot<C extends NodeCallback<OptNodeOrNull<NODE>>>(
-    callback: C = this._DEFAULT_NODE_CALLBACK as C,
     beginNode: BTNRep<K, V, NODE> | R,
-    isReverse = true
+    callback: C = this._DEFAULT_NODE_CALLBACK as C,
+    isReverse = false
   ): ReturnType<C>[] {
     const result: ReturnType<C>[] = [];
     let beginNodeEnsured = this.ensureNode(beginNode);
@@ -1118,7 +1157,6 @@ export class BinaryTree<
     iterationType: IterationType = this.iterationType
   ): ReturnType<C> {
     if (this.isNIL(startNode)) return callback(undefined);
-    // TODO support get right most by passing key in
     startNode = this.ensureNode(startNode);
     if (!startNode) return callback(startNode);
 
@@ -2144,16 +2182,16 @@ export class BinaryTree<
    * Time Complexity: O(1)
    * Space Complexity: O(1)
    *
-   * The function `_getKey` in TypeScript returns the key from a given input, which can be a node,
+   * The function `_extractKey` in TypeScript returns the key from a given input, which can be a node,
    * entry, raw data, or null/undefined.
-   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The `_getKey` method you provided is a
+   * @param {BTNRep<K, V, NODE> | R} keyNodeEntryOrRaw - The `_extractKey` method you provided is a
    * TypeScript method that takes in a parameter `keyNodeEntryOrRaw` of type `BTNRep<K, V, NODE> | R`,
    * where `BTNRep` is a generic type with keys `K`, `V`, and `NODE`, and `
-   * @returns The `_getKey` method returns the key value extracted from the `keyNodeEntryOrRaw`
+   * @returns The `_extractKey` method returns the key value extracted from the `keyNodeEntryOrRaw`
    * parameter. The return value can be a key value of type `K`, `null`, or `undefined`, depending on
    * the conditions checked in the method.
    */
-  protected _getKey(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): K | null | undefined {
+  protected _extractKey(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): K | null | undefined {
     if (keyNodeEntryOrRaw === null) return null;
     if (keyNodeEntryOrRaw === undefined) return;
     if (keyNodeEntryOrRaw === this._NIL) return;
@@ -2193,6 +2231,9 @@ export class BinaryTree<
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The _clearNodes function sets the root node to undefined and resets the size to 0.
    */
   protected _clearNodes() {
@@ -2201,6 +2242,9 @@ export class BinaryTree<
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The _clearValues function clears all values stored in the _store object.
    */
   protected _clearValues() {