bst-typed 1.53.6 → 1.53.8

package/README.md

@@ -345,6 +345,67 @@ bfsNodes[2].id;                                                // 16
 
 [//]: # (No deletion!!! Start of Example Replace Section)
 
+### Merge 3 sorted datasets
+```typescript
+    const dataset1 = new BST<number, string>([
+      [1, 'A'],
+      [7, 'G']
+    ]);
+    const dataset2 = [
+      [2, 'B'],
+      [6, 'F']
+    ];
+    const dataset3 = new BST<number, string>([
+      [3, 'C'],
+      [5, 'E'],
+      [4, 'D']
+    ]);
+
+    // Merge datasets into a single BinarySearchTree
+    const merged = new BST<number, string>(dataset1);
+    merged.addMany(dataset2);
+    merged.merge(dataset3);
+
+    // Verify merged dataset is in sorted order
+    console.log([...merged.values()]); // ['A', 'B', 'C', 'D', 'E', 'F', 'G']
+```
+
+### Find elements in a range
+```typescript
+    const bst = new BST<number>([10, 5, 15, 3, 7, 12, 18]);
+    console.log(bst.search(new Range(5, 10))); // [10, 5, 7]
+    console.log(bst.rangeSearch([4, 12], node => node.key.toString())); // ['10', '12', '5', '7']
+    console.log(bst.search(new Range(4, 12, true, false))); // [10, 5, 7]
+    console.log(bst.rangeSearch([15, 20])); // [15, 18]
+    console.log(bst.search(new Range(15, 20, false))); // [18]
+```
+
+### Find lowest common ancestor
+```typescript
+    const bst = new BST<number>([20, 10, 30, 5, 15, 25, 35, 3, 7, 12, 18]);
+
+    // LCA helper function
+    const findLCA = (num1: number, num2: number): number | undefined => {
+      const path1 = bst.getPathToRoot(num1);
+      const path2 = bst.getPathToRoot(num2);
+      // Find the first common ancestor
+      return findFirstCommon(path1, path2);
+    };
+
+    function findFirstCommon(arr1: number[], arr2: number[]): number | undefined {
+      for (const num of arr1) {
+        if (arr2.indexOf(num) !== -1) {
+          return num;
+        }
+      }
+      return undefined;
+    }
+
+    // Assertions
+    console.log(findLCA(3, 10)); // 7
+    console.log(findLCA(5, 35)); // 15
+    console.log(findLCA(20, 30)); // 25
+```
 
 [//]: # (No deletion!!! End of Example Replace Section)
 

package/dist/common/index.d.ts

@@ -0,0 +1,12 @@
+export declare enum DFSOperation {
+    VISIT = 0,
+    PROCESS = 1
+}
+export declare class Range<K> {
+    low: K;
+    high: K;
+    includeLow: boolean;
+    includeHigh: boolean;
+    constructor(low: K, high: K, includeLow?: boolean, includeHigh?: boolean);
+    isInRange(key: K, comparator: (a: K, b: K) => number): boolean;
+}

package/dist/common/index.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Range = exports.DFSOperation = void 0;
+const utils_1 = require("../utils");
+var DFSOperation;
+(function (DFSOperation) {
+    DFSOperation[DFSOperation["VISIT"] = 0] = "VISIT";
+    DFSOperation[DFSOperation["PROCESS"] = 1] = "PROCESS";
+})(DFSOperation = exports.DFSOperation || (exports.DFSOperation = {}));
+class Range {
+    constructor(low, high, includeLow = true, includeHigh = true) {
+        this.low = low;
+        this.high = high;
+        this.includeLow = includeLow;
+        this.includeHigh = includeHigh;
+        if (!((0, utils_1.isComparable)(low) && (0, utils_1.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, comparator) {
+        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;
+    }
+}
+exports.Range = Range;

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

@@ -102,7 +102,7 @@ export declare class AVLTreeMultiMap<K = any, V = any, R = object, NODE extends
      * 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.
      */
-    keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V, count?: number): [NODE | undefined, V | undefined];
+    protected _keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V, count?: number): [NODE | undefined, V | undefined];
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)

package/dist/data-structures/binary-tree/avl-tree-multi-map.js

@@ -96,7 +96,7 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
      * object.
      */
     createTree(options) {
-        return new AVLTreeMultiMap([], Object.assign({ iterationType: this.iterationType, isMapMode: this._isMapMode, comparator: this._comparator, toEntryFn: this._toEntryFn }, options));
+        return new AVLTreeMultiMap([], Object.assign({ iterationType: this.iterationType, isMapMode: this._isMapMode, extractComparable: this._extractComparable, toEntryFn: this._toEntryFn, isReverse: this._isReverse }, options));
     }
     /**
      * The function checks if the input is an instance of AVLTreeMultiMapNode.
@@ -120,7 +120,7 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
      * 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.
      */
-    keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count = 1) {
+    _keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count = 1) {
         if (keyNodeEntryOrRaw === undefined || keyNodeEntryOrRaw === null)
             return [undefined, undefined];
         if (this.isNode(keyNodeEntryOrRaw))
@@ -132,17 +132,14 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
             const finalValue = value !== null && value !== void 0 ? value : entryValue;
             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);
-                const finalValue = value !== null && value !== void 0 ? 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 !== null && value !== void 0 ? 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];
     }
     /**
@@ -163,7 +160,7 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
      * @returns a boolean value.
      */
     add(keyNodeEntryOrRaw, value, count = 1) {
-        const [newNode, newValue] = this.keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count);
+        const [newNode, newValue] = this._keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw, value, count);
         if (newNode === undefined)
             return false;
         const orgNodeCount = (newNode === null || newNode === void 0 ? void 0 : newNode.count) || 0;

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

@@ -85,7 +85,7 @@ class AVLTree extends bst_1.BST {
      * @returns a new AVLTree object.
      */
     createTree(options) {
-        return new AVLTree([], Object.assign({ iterationType: this.iterationType, isMapMode: this._isMapMode, comparator: this._comparator, toEntryFn: this._toEntryFn }, options));
+        return new AVLTree([], Object.assign({ iterationType: this.iterationType, isMapMode: this._isMapMode, extractComparable: this._extractComparable, toEntryFn: this._toEntryFn, isReverse: this._isReverse }, options));
     }
     /**
      * The function checks if the input is an instance of AVLTreeNode.
@@ -409,7 +409,7 @@ class AVLTree extends bst_1.BST {
      */
     _balancePath(node) {
         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/dist/data-structures/binary-tree/binary-tree.d.ts

@@ -8,6 +8,7 @@
 import { BinaryTreeDeleteResult, BinaryTreeNested, BinaryTreeNodeNested, BinaryTreeOptions, BinaryTreePrintOptions, BTNEntry, BTNRep, DFSOrderPattern, EntryCallback, FamilyPosition, IterationType, NodeCallback, NodeDisplayLayout, NodePredicate, OptNodeOrNull, ToEntryFn } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 import { IterableEntryBase } from '../base';
+import { Range } from '../../common';
 /**
  * Represents a node in a binary tree.
  * @template V - The type of data stored in the node.
@@ -91,7 +92,7 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * input parameter (`keyNodeEntryOrRaw`) and processes it accordingly to return a node or null
      * value.
      */
-    keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V): [OptNodeOrNull<NODE>, V | undefined];
+    protected _keyValueNodeEntryRawToNodeAndValue(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R, value?: V): [OptNodeOrNull<NODE>, V | undefined];
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -120,6 +121,13 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * is not a node.
      */
     isNode(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): keyNodeEntryOrRaw is NODE;
+    /**
+     * 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;
     /**
      * The function `isRealNode` checks if a given input is a valid node in a binary tree.
@@ -150,6 +158,7 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * property of the current object and returning a boolean value based on that comparison.
      */
     isNIL(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): boolean;
+    isRange(keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE> | Range<K>): keyNodeEntryRawOrPredicate is Range<K>;
     /**
      * The function determines whether a given key, node, entry, or raw data is a leaf node in a binary
      * tree.
@@ -221,6 +230,15 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * corresponds to the success of adding the corresponding key or value in the input iterable.
      */
     addMany(keysNodesEntriesOrRaws: Iterable<BTNRep<K, V, NODE> | R>, values?: Iterable<V | undefined>): boolean[];
+    /**
+     * 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>): void;
     /**
      * Time Complexity: O(k * n)
      * Space Complexity: O(1)
@@ -250,6 +268,31 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * need to be balanced (`needBalanced`).
      */
     delete(keyNodeEntryOrRaw: BTNRep<K, V, NODE> | R): BinaryTreeDeleteResult<NODE>[];
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(k + log n)
+     *
+     * 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.
+     */
+    search<C extends NodeCallback<NODE>>(keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE>, onlyOne?: boolean, callback?: C, startNode?: BTNRep<K, V, NODE> | R, iterationType?: IterationType): ReturnType<C>[];
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(k + log n)
@@ -293,20 +336,6 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * or `null` if no matching node is found.
      */
     getNode(keyNodeEntryRawOrPredicate: BTNRep<K, V, NODE> | R | NodePredicate<NODE>, startNode?: BTNRep<K, V, NODE> | R, iterationType?: IterationType): OptNodeOrNull<NODE>;
-    /**
-     * 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): OptNodeOrNull<NODE>;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(log n)
@@ -478,7 +507,7 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * array is either in reverse order or in the original order based on the value of the `isReverse`
      * parameter.
      */
-    getPathToRoot<C extends NodeCallback<OptNodeOrNull<NODE>>>(callback: C | undefined, beginNode: BTNRep<K, V, NODE> | R, isReverse?: boolean): ReturnType<C>[];
+    getPathToRoot<C extends NodeCallback<OptNodeOrNull<NODE>>>(beginNode: BTNRep<K, V, NODE> | R, callback?: C, isReverse?: boolean): ReturnType<C>[];
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(1)
@@ -825,16 +854,16 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      * 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;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -851,10 +880,16 @@ export declare class BinaryTree<K = any, V = any, R = object, NODE extends Binar
      */
     protected _setValue(key: K | null | undefined, value: V | undefined): false | Map<K, V | undefined>;
     /**
+     * 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(): void;
     /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
      * The _clearValues function clears all values stored in the _store object.
      */
     protected _clearValues(): void;