bst-typed 1.53.6 → 1.53.8

package/dist/utils/utils.js

@@ -213,7 +213,8 @@ exports.roundFixed = roundFixed;
 function isPrimitiveComparable(value) {
     const valueType = typeof value;
     if (valueType === 'number')
-        return !Number.isNaN(value);
+        return true;
+    // if (valueType === 'number') return !Number.isNaN(value);
     return valueType === 'bigint' || valueType === 'string' || valueType === 'boolean';
 }
 /**
@@ -265,7 +266,8 @@ function isComparable(value, isForceObjectComparable = false) {
     if (typeof value !== 'object')
         return false;
     if (value instanceof Date)
-        return !Number.isNaN(value.getTime());
+        return true;
+    // if (value instanceof Date) return !Number.isNaN(value.getTime());
     if (isForceObjectComparable)
         return true;
     const comparableValue = tryObjectToPrimitive(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bst-typed",
-  "version": "1.53.6",
+  "version": "1.53.8",
   "description": "BST (Binary Search Tree). Javascript & Typescript Data Structure.",
   "main": "dist/index.js",
   "scripts": {
@@ -144,6 +144,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^1.53.6"
+    "data-structure-typed": "^1.53.8"
   }
 }

package/src/common/index.ts

@@ -0,0 +1,25 @@
+import { isComparable } from '../utils';
+
+export enum DFSOperation {
+  VISIT = 0,
+  PROCESS = 1
+}
+
+export class Range<K> {
+  constructor(
+    public low: K,
+    public high: K,
+    public includeLow: boolean = true,
+    public includeHigh: boolean = true
+  ) {
+    if (!(isComparable(low) && isComparable(high))) throw new RangeError('low or high is not comparable');
+    if (low > high) throw new RangeError('low must be less than or equal to high');
+  }
+
+  // Determine whether a key is within the range
+  isInRange(key: K, comparator: (a: K, b: K) => number): boolean {
+    const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
+    const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
+    return lowCheck && highCheck;
+  }
+}

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

@@ -143,8 +143,9 @@ export class AVLTreeMultiMap<
     return new AVLTreeMultiMap<K, V, R, NODE, TREE>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
-      comparator: this._comparator,
+      extractComparable: this._extractComparable,
       toEntryFn: this._toEntryFn,
+      isReverse: this._isReverse,
       ...options
     }) as TREE;
   }
@@ -172,7 +173,7 @@ export class AVLTreeMultiMap<
    * times the key-value pair should be added to the data structure. If not provided, it defaults to 1.
    * @returns either a NODE object or undefined.
    */
-  override keyValueNodeEntryRawToNodeAndValue(
+  protected override _keyValueNodeEntryRawToNodeAndValue(
     keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R,
     value?: V,
     count = 1
@@ -187,17 +188,14 @@ export class AVLTreeMultiMap<
       return [this.createNode(key, finalValue, count), finalValue];
     }
 
-    if (this.isKey(keyNodeEntryOrRaw)) return [this.createNode(keyNodeEntryOrRaw, value, count), value];
-
     if (this.isRaw(keyNodeEntryOrRaw)) {
-      if (this._toEntryFn) {
-        const [key, entryValue] = this._toEntryFn(keyNodeEntryOrRaw as R);
-        const finalValue = value ?? entryValue;
-        if (this.isKey(key)) return [this.createNode(key, finalValue, count), finalValue];
-      }
-      return [undefined, undefined];
+      const [key, entryValue] = this._toEntryFn!(keyNodeEntryOrRaw);
+      const finalValue = value ?? entryValue;
+      if (this.isKey(key)) return [this.createNode(key, finalValue, count), finalValue];
     }
 
+    if (this.isKey(keyNodeEntryOrRaw)) return [this.createNode(keyNodeEntryOrRaw, value, count), value];
+
     return [undefined, undefined];
   }
 
@@ -219,7 +217,7 @@ export class AVLTreeMultiMap<
    * @returns a boolean value.
    */
   override add(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V, count = 1): boolean {
-    const [newNode, newValue] = this.keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count);
+    const [newNode, newValue] = this._keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count);
     if (newNode === undefined) return false;
 
     const orgNodeCount = newNode?.count || 0;

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

@@ -113,8 +113,9 @@ export class AVLTree<
     return new AVLTree<K, V, R, NODE, TREE>([], {
       iterationType: this.iterationType,
       isMapMode: this._isMapMode,
-      comparator: this._comparator,
+      extractComparable: this._extractComparable,
       toEntryFn: this._toEntryFn,
+      isReverse: this._isReverse,
       ...options
     }) as TREE;
   }
@@ -434,7 +435,7 @@ export class AVLTree<
    */
   protected _balancePath(node: BTNRep<K, V, NODE> | R): void {
     node = this.ensureNode(node);
-    const path = this.getPathToRoot(node => node, node, false); // first O(log n) + O(log n)
+    const path = this.getPathToRoot(node, node => node, false); // first O(log n) + O(log n)
     for (let i = 0; i < path.length; i++) {
       // second O(log n)
       const A = path[i];

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.
@@ -216,7 +216,7 @@ export class BinaryTree<
    * input parameter (`keyNodeEntryOrRaw`) and processes it accordingly to return a node or null
    * value.
    */
-  keyValueNodeEntryRawToNodeAndValue(
+  protected _keyValueNodeEntryRawToNodeAndValue(
     keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R,
     value?: V
   ): [OptNodeOrNull<NODE>, V | undefined] {
@@ -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.
@@ -410,7 +420,7 @@ export class BinaryTree<
    * key was found and the node was replaced instead of inserted.
    */
   add(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V): boolean {
-    const [newNode, newValue] = this.keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value);
+    const [newNode, newValue] = this._keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value);
     if (newNode === undefined) return false;
 
     // If the tree is empty, directly set the new node as the root node
@@ -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() {