stack-typed 1.54.2 → 2.0.0

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

@@ -105,8 +105,8 @@ class AVLTreeCounter extends avl_tree_1.AVLTree {
     }
     /**
      * The function checks if the input is an instance of AVLTreeCounterNode.
-     * @param {BTNRep<K, V, AVLTreeCounterNode<K, V>>} keyNodeOrEntry - The parameter
-     * `keyNodeOrEntry` can be of type `R` or `BTNRep<K, V, AVLTreeCounterNode<K, V>>`.
+     * @param {K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined} keyNodeOrEntry - The parameter
+     * `keyNodeOrEntry` can be of type `R` or `K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined`.
      * @returns a boolean value indicating whether the input parameter `keyNodeOrEntry` is
      * an instance of the `AVLTreeCounterNode` class.
      */
@@ -119,9 +119,9 @@ class AVLTreeCounter extends avl_tree_1.AVLTree {
      *
      * The function overrides the add method of a TypeScript class to add a new node to a data structure
      * and update the count.
-     * @param {BTNRep<K, V, AVLTreeCounterNode<K, V>>} keyNodeOrEntry - The
+     * @param {K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined} keyNodeOrEntry - The
      * `keyNodeOrEntry` parameter can accept a value of type `R`, which can be any type. It
-     * can also accept a value of type `BTNRep<K, V, AVLTreeCounterNode<K, V>>`, which represents a key, node,
+     * can also accept a value of type `K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined`, which represents a key, node,
      * entry, or raw element
      * @param {V} [value] - The `value` parameter represents the value associated with the key in the
      * data structure. It is an optional parameter, so it can be omitted if not needed.
@@ -147,7 +147,7 @@ class AVLTreeCounter extends avl_tree_1.AVLTree {
      *
      * The function overrides the delete method in a binary tree data structure, handling deletion of
      * nodes and maintaining balance in the tree.
-     * @param {BTNRep<K, V, AVLTreeCounterNode<K, V>>} keyNodeOrEntry - The `predicate`
+     * @param {K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined} keyNodeOrEntry - The `predicate`
      * parameter in the `delete` method is used to specify the condition for deleting a node from the
      * binary tree. It can be a key, node, or entry that determines which
      * node(s) should be deleted.
@@ -232,6 +232,7 @@ class AVLTreeCounter extends avl_tree_1.AVLTree {
     /**
      * Time Complexity: O(n log n)
      * Space Complexity: O(log n)
+     *
      * The `perfectlyBalance` function takes a sorted array of nodes and builds a balanced binary search
      * tree using either a recursive or iterative approach.
      * @param {IterationType} iterationType - The `iterationType` parameter is an optional parameter that
@@ -329,8 +330,8 @@ class AVLTreeCounter extends avl_tree_1.AVLTree {
     /**
      * The function `keyValueNodeEntryRawToNodeAndValue` converts a key, value, entry, or raw element into
      * a node object.
-     * @param {BTNRep<K, V, AVLTreeCounterNode<K, V>>} keyNodeOrEntry - The
-     * `keyNodeOrEntry` parameter can be of type `R` or `BTNRep<K, V, AVLTreeCounterNode<K, V>>`.
+     * @param {K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined} keyNodeOrEntry - The
+     * `keyNodeOrEntry` parameter can be of type `R` or `K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined`.
      * @param {V} [value] - The `value` parameter is an optional value that can be passed to the
      * `override` function. It represents the value associated with the key in the data structure. If no
      * value is provided, it will default to `undefined`.

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

@@ -5,10 +5,11 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import { AVLTreeMultiMapOptions, BTNRep, OptNodeOrNull } from '../../types';
+import { AVLTreeMultiMapOptions } from '../../types';
 import { AVLTree, AVLTreeNode } from './avl-tree';
 import { IBinaryTree } from '../../interfaces';
 export declare class AVLTreeMultiMapNode<K = any, V = any> extends AVLTreeNode<K, V[]> {
+    parent?: AVLTreeMultiMapNode<K, V>;
     /**
      * This TypeScript constructor initializes an object with a key of type K and an array of values of
      * type V.
@@ -19,13 +20,12 @@ export declare class AVLTreeMultiMapNode<K = any, V = any> extends AVLTreeNode<K
      * type `V`.
      */
     constructor(key: K, value: V[]);
-    parent?: AVLTreeMultiMapNode<K, V>;
-    _left?: OptNodeOrNull<AVLTreeMultiMapNode<K, V>>;
-    get left(): OptNodeOrNull<AVLTreeMultiMapNode<K, V>>;
-    set left(v: OptNodeOrNull<AVLTreeMultiMapNode<K, V>>);
-    _right?: OptNodeOrNull<AVLTreeMultiMapNode<K, V>>;
-    get right(): OptNodeOrNull<AVLTreeMultiMapNode<K, V>>;
-    set right(v: OptNodeOrNull<AVLTreeMultiMapNode<K, V>>);
+    _left?: AVLTreeMultiMapNode<K, V> | null | undefined;
+    get left(): AVLTreeMultiMapNode<K, V> | null | undefined;
+    set left(v: AVLTreeMultiMapNode<K, V> | null | undefined);
+    _right?: AVLTreeMultiMapNode<K, V> | null | undefined;
+    get right(): AVLTreeMultiMapNode<K, V> | null | undefined;
+    set right(v: AVLTreeMultiMapNode<K, V> | null | undefined);
 }
 /**
  *
@@ -42,7 +42,7 @@ export declare class AVLTreeMultiMap<K = any, V = any, R = object, MK = any, MV
      * `AVLTreeMultiMapOptions<K, V[], R>`. It is an optional parameter that allows you to specify
      * additional options for configuring the AVLTreeMultiMap instance.
      */
-    constructor(keysNodesEntriesOrRaws?: Iterable<BTNRep<K, V[], AVLTreeMultiMapNode<K, V>> | R>, options?: AVLTreeMultiMapOptions<K, V[], R>);
+    constructor(keysNodesEntriesOrRaws?: Iterable<K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | R>, options?: AVLTreeMultiMapOptions<K, V[], R>);
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -60,15 +60,19 @@ export declare class AVLTreeMultiMap<K = any, V = any, R = object, MK = any, MV
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function `createNode` overrides the method to create a new AVLTreeMultiMapNode with a
-     * specified key and an empty array of values.
-     * @param {K} key - The `key` parameter in the `createNode` method represents the key of the node
-     * that will be created in the AVLTreeMultiMap.
-     * @returns An AVLTreeMultiMapNode object is being returned, initialized with the provided key and an
-     * empty array.
+     * The `createNode` function in TypeScript overrides the default implementation to create a new
+     * AVLTreeMultiMapNode with a specified key and value array.
+     * @param {K} key - The `key` parameter represents the key of the node being created in the
+     * AVLTreeMultiMap.
+     * @param {V[]} value - The `value` parameter in the `createNode` method represents an array of
+     * values associated with a specific key in the AVLTreeMultiMapNode. If no value is provided when
+     * calling the method, an empty array `[]` is used as the default value.
+     * @returns An AVLTreeMultiMapNode object is being returned, with the specified key and value. If the
+     * AVLTreeMultiMap is in map mode, an empty array is used as the value, otherwise the provided value
+     * array is used.
      */
-    createNode(key: K): AVLTreeMultiMapNode<K, V>;
-    add(node: BTNRep<K, V[], AVLTreeMultiMapNode<K, V>>): boolean;
+    createNode(key: K, value?: V[]): AVLTreeMultiMapNode<K, V>;
+    add(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined): boolean;
     add(key: K, value: V): boolean;
     /**
      * Time Complexity: O(log n)
@@ -76,7 +80,7 @@ export declare class AVLTreeMultiMap<K = any, V = any, R = object, MK = any, MV
      *
      * The function `deleteValue` removes a specific value from a key in an AVLTreeMultiMap data
      * structure and deletes the entire node if no values are left for that key.
-     * @param {BTNRep<K, V[], AVLTreeMultiMapNode<K, V>> | K} keyNodeOrEntry - The `keyNodeOrEntry`
+     * @param {K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | K} keyNodeOrEntry - The `keyNodeOrEntry`
      * parameter in the `deleteValue` function can be either a `BTNRep` object representing a key-value
      * pair in the AVLTreeMultiMapNode, or just the key itself.
      * @param {V} value - The `value` parameter in the `deleteValue` function represents the specific
@@ -87,7 +91,7 @@ export declare class AVLTreeMultiMap<K = any, V = any, R = object, MK = any, MV
      * `value` was successfully deleted from the array of values associated with the `keyNodeOrEntry`. If
      * the value was not found in the array, it returns `false`.
      */
-    deleteValue(keyNodeOrEntry: BTNRep<K, V[], AVLTreeMultiMapNode<K, V>> | K, value: V): boolean;
+    deleteValue(keyNodeOrEntry: K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | K, value: V): boolean;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)

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

@@ -72,37 +72,40 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
      * provided options.
      */
     createTree(options) {
-        return new AVLTreeMultiMap([], Object.assign({ iterationType: this.iterationType, specifyComparable: this._specifyComparable, toEntryFn: this._toEntryFn, isReverse: this._isReverse }, options));
+        return new AVLTreeMultiMap([], Object.assign({ iterationType: this.iterationType, specifyComparable: this._specifyComparable, toEntryFn: this._toEntryFn, isReverse: this._isReverse, isMapMode: this._isMapMode }, options));
     }
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function `createNode` overrides the method to create a new AVLTreeMultiMapNode with a
-     * specified key and an empty array of values.
-     * @param {K} key - The `key` parameter in the `createNode` method represents the key of the node
-     * that will be created in the AVLTreeMultiMap.
-     * @returns An AVLTreeMultiMapNode object is being returned, initialized with the provided key and an
-     * empty array.
+     * The `createNode` function in TypeScript overrides the default implementation to create a new
+     * AVLTreeMultiMapNode with a specified key and value array.
+     * @param {K} key - The `key` parameter represents the key of the node being created in the
+     * AVLTreeMultiMap.
+     * @param {V[]} value - The `value` parameter in the `createNode` method represents an array of
+     * values associated with a specific key in the AVLTreeMultiMapNode. If no value is provided when
+     * calling the method, an empty array `[]` is used as the default value.
+     * @returns An AVLTreeMultiMapNode object is being returned, with the specified key and value. If the
+     * AVLTreeMultiMap is in map mode, an empty array is used as the value, otherwise the provided value
+     * array is used.
      */
-    createNode(key) {
-        return new AVLTreeMultiMapNode(key, []);
+    createNode(key, value = []) {
+        return new AVLTreeMultiMapNode(key, this._isMapMode ? [] : value);
     }
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
      *
-     * The function `add` in TypeScript overrides the superclass method to add key-value pairs to an AVL
-     * tree multi-map.
-     * @param {BTNRep<K, V[], AVLTreeMultiMapNode<K, V>> | K} keyNodeOrEntry - The `keyNodeOrEntry`
-     * parameter in the `override add` method can be either a key-value pair entry or just a key. If it
-     * is a key-value pair entry, it will be in the format `[key, values]`, where `key` is the key and
-     * `values`
-     * @param {V} [value] - The `value` parameter in the `override add` method represents the value that
-     * you want to add to the AVLTreeMultiMap. It can be a single value or an array of values associated
-     * with a specific key.
-     * @returns The `override add` method is returning a boolean value, which indicates whether the
-     * addition operation was successful or not.
+     * The function `add` in this TypeScript code overrides the superclass method to add key-value pairs
+     * to an AVLTreeMultiMap, handling different input types and scenarios.
+     * @param [key] - The `key` parameter in the `override add` method represents the key of the entry to
+     * be added to the AVLTreeMultiMap. It can be of type `K`, which is the key type of the map. The key
+     * can be a single key value, a node of the AVLTree
+     * @param {V[]} [values] - The `values` parameter in the `add` method represents an array of values
+     * that you want to add to the AVLTreeMultiMap. It can contain one or more values associated with a
+     * specific key.
+     * @returns The `add` method is returning a boolean value, which indicates whether the operation was
+     * successful or not.
      */
     add(keyNodeOrEntry, value) {
         if (this.isRealNode(keyNodeOrEntry))
@@ -110,30 +113,40 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
         const _commonAdd = (key, values) => {
             if (key === undefined || key === null)
                 return false;
-            const existingValues = this.get(key);
-            if (existingValues !== undefined && values !== undefined) {
-                for (const value of values)
-                    existingValues.push(value);
-                return true;
-            }
-            const existingNode = this.getNode(key);
-            if (this.isRealNode(existingNode)) {
-                if (existingValues === undefined) {
-                    super.add(key, values);
-                    return true;
-                }
-                if (values !== undefined) {
+            const _addToValues = () => {
+                const existingValues = this.get(key);
+                if (existingValues !== undefined && values !== undefined) {
                     for (const value of values)
                         existingValues.push(value);
                     return true;
                 }
+                return false;
+            };
+            const _addByNode = () => {
+                const existingNode = this.getNode(key);
+                if (this.isRealNode(existingNode)) {
+                    const existingValues = this.get(existingNode);
+                    if (existingValues === undefined) {
+                        super.add(key, values);
+                        return true;
+                    }
+                    if (values !== undefined) {
+                        for (const value of values)
+                            existingValues.push(value);
+                        return true;
+                    }
+                    else {
+                        return false;
+                    }
+                }
                 else {
-                    return false;
+                    return super.add(key, values);
                 }
+            };
+            if (this._isMapMode) {
+                return _addByNode() || _addToValues();
             }
-            else {
-                return super.add(key, values);
-            }
+            return _addToValues() || _addByNode();
         };
         if (this.isEntry(keyNodeOrEntry)) {
             const [key, values] = keyNodeOrEntry;
@@ -147,7 +160,7 @@ class AVLTreeMultiMap extends avl_tree_1.AVLTree {
      *
      * The function `deleteValue` removes a specific value from a key in an AVLTreeMultiMap data
      * structure and deletes the entire node if no values are left for that key.
-     * @param {BTNRep<K, V[], AVLTreeMultiMapNode<K, V>> | K} keyNodeOrEntry - The `keyNodeOrEntry`
+     * @param {K | AVLTreeMultiMapNode<K, V> | [K | null | undefined, V[] | undefined] | null | undefined | K} keyNodeOrEntry - The `keyNodeOrEntry`
      * parameter in the `deleteValue` function can be either a `BTNRep` object representing a key-value
      * pair in the AVLTreeMultiMapNode, or just the key itself.
      * @param {V} value - The `value` parameter in the `deleteValue` function represents the specific

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

@@ -6,9 +6,10 @@
  * @license MIT License
  */
 import { BST, BSTNode } from './bst';
-import type { AVLTreeOptions, BinaryTreeDeleteResult, BSTNOptKeyOrNode, BTNRep, EntryCallback, OptNodeOrNull } from '../../types';
+import type { AVLTreeOptions, BinaryTreeDeleteResult, BSTNOptKeyOrNode, EntryCallback } from '../../types';
 import { IBinaryTree } from '../../interfaces';
 export declare class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
+    parent?: AVLTreeNode<K, V>;
     /**
      * This TypeScript constructor function initializes an instance with a key and an optional value.
      * @param {K} key - The `key` parameter is typically used to uniquely identify an object or element
@@ -19,13 +20,12 @@ export declare class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
      * default to `undefined`.
      */
     constructor(key: K, value?: V);
-    parent?: AVLTreeNode<K, V>;
-    _left?: OptNodeOrNull<AVLTreeNode<K, V>>;
-    get left(): OptNodeOrNull<AVLTreeNode<K, V>>;
-    set left(v: OptNodeOrNull<AVLTreeNode<K, V>>);
-    _right?: OptNodeOrNull<AVLTreeNode<K, V>>;
-    get right(): OptNodeOrNull<AVLTreeNode<K, V>>;
-    set right(v: OptNodeOrNull<AVLTreeNode<K, V>>);
+    _left?: AVLTreeNode<K, V> | null | undefined;
+    get left(): AVLTreeNode<K, V> | null | undefined;
+    set left(v: AVLTreeNode<K, V> | null | undefined);
+    _right?: AVLTreeNode<K, V> | null | undefined;
+    get right(): AVLTreeNode<K, V> | null | undefined;
+    set right(v: AVLTreeNode<K, V> | null | undefined);
 }
 /**
  * 1. Height-Balanced: Each node's left and right subtrees differ in height by no more than one.
@@ -35,20 +35,85 @@ export declare class AVLTreeNode<K = any, V = any> extends BSTNode<K, V> {
  * 5. Efficient Lookups: Offers O(log n) search time, where 'n' is the number of nodes, due to its balanced nature.
  * 6. Complex Insertions and Deletions: Due to rebalancing, these operations are more complex than in a regular BST.
  * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
+ * @example
+ * // Find elements in a range
+ *     // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
+ *     type Datum = { timestamp: Date; temperature: number };
+ *     // Fixed dataset of CPU temperature readings
+ *     const cpuData: Datum[] = [
+ *       { timestamp: new Date('2024-12-02T00:00:00'), temperature: 55.1 },
+ *       { timestamp: new Date('2024-12-02T00:01:00'), temperature: 56.3 },
+ *       { timestamp: new Date('2024-12-02T00:02:00'), temperature: 54.8 },
+ *       { timestamp: new Date('2024-12-02T00:03:00'), temperature: 57.2 },
+ *       { timestamp: new Date('2024-12-02T00:04:00'), temperature: 58.0 },
+ *       { timestamp: new Date('2024-12-02T00:05:00'), temperature: 59.4 },
+ *       { timestamp: new Date('2024-12-02T00:06:00'), temperature: 60.1 },
+ *       { timestamp: new Date('2024-12-02T00:07:00'), temperature: 61.3 },
+ *       { timestamp: new Date('2024-12-02T00:08:00'), temperature: 62.0 },
+ *       { timestamp: new Date('2024-12-02T00:09:00'), temperature: 63.5 },
+ *       { timestamp: new Date('2024-12-02T00:10:00'), temperature: 64.0 },
+ *       { timestamp: new Date('2024-12-02T00:11:00'), temperature: 62.8 },
+ *       { timestamp: new Date('2024-12-02T00:12:00'), temperature: 61.5 },
+ *       { timestamp: new Date('2024-12-02T00:13:00'), temperature: 60.2 },
+ *       { timestamp: new Date('2024-12-02T00:14:00'), temperature: 59.8 },
+ *       { timestamp: new Date('2024-12-02T00:15:00'), temperature: 58.6 },
+ *       { timestamp: new Date('2024-12-02T00:16:00'), temperature: 57.4 },
+ *       { timestamp: new Date('2024-12-02T00:17:00'), temperature: 56.2 },
+ *       { timestamp: new Date('2024-12-02T00:18:00'), temperature: 55.7 },
+ *       { timestamp: new Date('2024-12-02T00:19:00'), temperature: 54.5 },
+ *       { timestamp: new Date('2024-12-02T00:20:00'), temperature: 53.2 },
+ *       { timestamp: new Date('2024-12-02T00:21:00'), temperature: 52.8 },
+ *       { timestamp: new Date('2024-12-02T00:22:00'), temperature: 51.9 },
+ *       { timestamp: new Date('2024-12-02T00:23:00'), temperature: 50.5 },
+ *       { timestamp: new Date('2024-12-02T00:24:00'), temperature: 49.8 },
+ *       { timestamp: new Date('2024-12-02T00:25:00'), temperature: 48.7 },
+ *       { timestamp: new Date('2024-12-02T00:26:00'), temperature: 47.5 },
+ *       { timestamp: new Date('2024-12-02T00:27:00'), temperature: 46.3 },
+ *       { timestamp: new Date('2024-12-02T00:28:00'), temperature: 45.9 },
+ *       { timestamp: new Date('2024-12-02T00:29:00'), temperature: 45.0 }
+ *     ];
+ *
+ *     // Create an AVL tree to store CPU temperature data
+ *     const cpuTemperatureTree = new AVLTree<Date, number, Datum>(cpuData, {
+ *       toEntryFn: ({ timestamp, temperature }) => [timestamp, temperature]
+ *     });
+ *
+ *     // Query a specific time range (e.g., from 00:05 to 00:15)
+ *     const rangeStart = new Date('2024-12-02T00:05:00');
+ *     const rangeEnd = new Date('2024-12-02T00:15:00');
+ *     const rangeResults = cpuTemperatureTree.rangeSearch([rangeStart, rangeEnd], node => ({
+ *       minute: node ? node.key.getMinutes() : 0,
+ *       temperature: cpuTemperatureTree.get(node ? node.key : undefined)
+ *     }));
+ *
+ *     console.log(rangeResults); // [
+ *  //      { minute: 5, temperature: 59.4 },
+ *  //      { minute: 6, temperature: 60.1 },
+ *  //      { minute: 7, temperature: 61.3 },
+ *  //      { minute: 8, temperature: 62 },
+ *  //      { minute: 9, temperature: 63.5 },
+ *  //      { minute: 10, temperature: 64 },
+ *  //      { minute: 11, temperature: 62.8 },
+ *  //      { minute: 12, temperature: 61.5 },
+ *  //      { minute: 13, temperature: 60.2 },
+ *  //      { minute: 14, temperature: 59.8 },
+ *  //      { minute: 15, temperature: 58.6 }
+ *  //    ]
  */
 export declare class AVLTree<K = any, V = any, R = object, MK = any, MV = any, MR = object> extends BST<K, V, R, MK, MV, MR> implements IBinaryTree<K, V, R, MK, MV, MR> {
     /**
      * This TypeScript constructor initializes an AVLTree with keys, nodes, entries, or raw data provided
      * in an iterable format.
      * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter in the constructor is an
-     * iterable that can contain either `BTNRep<K, V, AVLTreeNode<K, V>>` objects or `R` objects. It is
+     * iterable that can contain either `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined ` objects or `R` objects. It is
      * used to initialize the AVLTree with key-value pairs or raw data entries. If provided
      * @param [options] - The `options` parameter in the constructor is of type `AVLTreeOptions<K, V,
      * R>`. It is an optional parameter that allows you to specify additional options for configuring the
      * AVL tree. These options could include things like custom comparators, initial capacity, or any
      * other configuration settings specific
      */
-    constructor(keysNodesEntriesOrRaws?: Iterable<BTNRep<K, V, AVLTreeNode<K, V>> | R>, options?: AVLTreeOptions<K, V, R>);
+    constructor(keysNodesEntriesOrRaws?: Iterable<K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: AVLTreeOptions<K, V, R>);
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -78,39 +143,41 @@ export declare class AVLTree<K = any, V = any, R = object, MK = any, MV = any, M
      * Space Complexity: O(1)
      *
      * The function checks if the input is an instance of AVLTreeNode.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The parameter
-     * `keyNodeOrEntry` can be of type `R` or `BTNRep<K, V, AVLTreeNode<K, V>>`.
+     * @param {K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } keyNodeOrEntry - The parameter
+     * `keyNodeOrEntry` can be of type `R` or `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined `.
      * @returns a boolean value indicating whether the input parameter `keyNodeOrEntry` is
      * an instance of the `AVLTreeNode` class.
      */
-    isNode(keyNodeOrEntry: BTNRep<K, V, AVLTreeNode<K, V>>): keyNodeOrEntry is AVLTreeNode<K, V>;
+    isNode(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is AVLTreeNode<K, V>;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
      *
      * The function overrides the add method of a class and inserts a key-value pair into a data
      * structure, then balances the path.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The parameter
-     * `keyNodeOrEntry` can accept values of type `R`, `BTNRep<K, V, AVLTreeNode<K, V>>`
+     * @param { K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } keyNodeOrEntry - The parameter
+     * `keyNodeOrEntry` can accept values of type `R`, `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined `
      * @param {V} [value] - The `value` parameter is an optional value that you want to associate with
      * the key or node being added to the data structure.
      * @returns The method is returning a boolean value.
      */
-    add(keyNodeOrEntry: BTNRep<K, V, AVLTreeNode<K, V>>, value?: V): boolean;
+    add(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V): boolean;
     /**
      * Time Complexity: O(log n)
      * Space Complexity: O(log n)
      *
      * The function overrides the delete method in a TypeScript class, performs deletion, and then
      * balances the tree if necessary.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The `keyNodeOrEntry`
+     * @param { K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } keyNodeOrEntry - The `keyNodeOrEntry`
      * parameter in the `override delete` method can be one of the following types:
      * @returns The `delete` method is being overridden in this code snippet. It first calls the `delete`
      * method from the superclass (presumably a parent class) with the provided `predicate`, which could
      * be a key, node, entry, or a custom predicate. The result of this deletion operation is stored in
      * `deletedResults`, which is an array of `BinaryTreeDeleteResult` objects.
      */
-    delete(keyNodeOrEntry: BTNRep<K, V, AVLTreeNode<K, V>>): BinaryTreeDeleteResult<AVLTreeNode<K, V>>[];
+    delete(keyNodeOrEntry: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): BinaryTreeDeleteResult<AVLTreeNode<K, V>>[];
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -213,10 +280,11 @@ export declare class AVLTree<K = any, V = any, R = object, MK = any, MV = any, M
      *
      * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
      * to restore balance in an AVL tree after inserting a node.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} node - The `node` parameter can be of type `R` or
-     * `BTNRep<K, V, AVLTreeNode<K, V>>`.
+     * @param { K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } node - The `node` parameter can be of type `R` or
+     * `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined `.
      */
-    protected _balancePath(node: BTNRep<K, V, AVLTreeNode<K, V>>): void;
+    protected _balancePath(node: K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): void;
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)

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

@@ -53,13 +53,78 @@ exports.AVLTreeNode = AVLTreeNode;
  * 5. Efficient Lookups: Offers O(log n) search time, where 'n' is the number of nodes, due to its balanced nature.
  * 6. Complex Insertions and Deletions: Due to rebalancing, these operations are more complex than in a regular BST.
  * 7. Path Length: The path length from the root to any leaf is longer compared to an unbalanced BST, but shorter than a linear chain of nodes.
+ * @example
+ * // Find elements in a range
+ *     // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
+ *     type Datum = { timestamp: Date; temperature: number };
+ *     // Fixed dataset of CPU temperature readings
+ *     const cpuData: Datum[] = [
+ *       { timestamp: new Date('2024-12-02T00:00:00'), temperature: 55.1 },
+ *       { timestamp: new Date('2024-12-02T00:01:00'), temperature: 56.3 },
+ *       { timestamp: new Date('2024-12-02T00:02:00'), temperature: 54.8 },
+ *       { timestamp: new Date('2024-12-02T00:03:00'), temperature: 57.2 },
+ *       { timestamp: new Date('2024-12-02T00:04:00'), temperature: 58.0 },
+ *       { timestamp: new Date('2024-12-02T00:05:00'), temperature: 59.4 },
+ *       { timestamp: new Date('2024-12-02T00:06:00'), temperature: 60.1 },
+ *       { timestamp: new Date('2024-12-02T00:07:00'), temperature: 61.3 },
+ *       { timestamp: new Date('2024-12-02T00:08:00'), temperature: 62.0 },
+ *       { timestamp: new Date('2024-12-02T00:09:00'), temperature: 63.5 },
+ *       { timestamp: new Date('2024-12-02T00:10:00'), temperature: 64.0 },
+ *       { timestamp: new Date('2024-12-02T00:11:00'), temperature: 62.8 },
+ *       { timestamp: new Date('2024-12-02T00:12:00'), temperature: 61.5 },
+ *       { timestamp: new Date('2024-12-02T00:13:00'), temperature: 60.2 },
+ *       { timestamp: new Date('2024-12-02T00:14:00'), temperature: 59.8 },
+ *       { timestamp: new Date('2024-12-02T00:15:00'), temperature: 58.6 },
+ *       { timestamp: new Date('2024-12-02T00:16:00'), temperature: 57.4 },
+ *       { timestamp: new Date('2024-12-02T00:17:00'), temperature: 56.2 },
+ *       { timestamp: new Date('2024-12-02T00:18:00'), temperature: 55.7 },
+ *       { timestamp: new Date('2024-12-02T00:19:00'), temperature: 54.5 },
+ *       { timestamp: new Date('2024-12-02T00:20:00'), temperature: 53.2 },
+ *       { timestamp: new Date('2024-12-02T00:21:00'), temperature: 52.8 },
+ *       { timestamp: new Date('2024-12-02T00:22:00'), temperature: 51.9 },
+ *       { timestamp: new Date('2024-12-02T00:23:00'), temperature: 50.5 },
+ *       { timestamp: new Date('2024-12-02T00:24:00'), temperature: 49.8 },
+ *       { timestamp: new Date('2024-12-02T00:25:00'), temperature: 48.7 },
+ *       { timestamp: new Date('2024-12-02T00:26:00'), temperature: 47.5 },
+ *       { timestamp: new Date('2024-12-02T00:27:00'), temperature: 46.3 },
+ *       { timestamp: new Date('2024-12-02T00:28:00'), temperature: 45.9 },
+ *       { timestamp: new Date('2024-12-02T00:29:00'), temperature: 45.0 }
+ *     ];
+ *
+ *     // Create an AVL tree to store CPU temperature data
+ *     const cpuTemperatureTree = new AVLTree<Date, number, Datum>(cpuData, {
+ *       toEntryFn: ({ timestamp, temperature }) => [timestamp, temperature]
+ *     });
+ *
+ *     // Query a specific time range (e.g., from 00:05 to 00:15)
+ *     const rangeStart = new Date('2024-12-02T00:05:00');
+ *     const rangeEnd = new Date('2024-12-02T00:15:00');
+ *     const rangeResults = cpuTemperatureTree.rangeSearch([rangeStart, rangeEnd], node => ({
+ *       minute: node ? node.key.getMinutes() : 0,
+ *       temperature: cpuTemperatureTree.get(node ? node.key : undefined)
+ *     }));
+ *
+ *     console.log(rangeResults); // [
+ *  //      { minute: 5, temperature: 59.4 },
+ *  //      { minute: 6, temperature: 60.1 },
+ *  //      { minute: 7, temperature: 61.3 },
+ *  //      { minute: 8, temperature: 62 },
+ *  //      { minute: 9, temperature: 63.5 },
+ *  //      { minute: 10, temperature: 64 },
+ *  //      { minute: 11, temperature: 62.8 },
+ *  //      { minute: 12, temperature: 61.5 },
+ *  //      { minute: 13, temperature: 60.2 },
+ *  //      { minute: 14, temperature: 59.8 },
+ *  //      { minute: 15, temperature: 58.6 }
+ *  //    ]
  */
 class AVLTree extends bst_1.BST {
     /**
      * This TypeScript constructor initializes an AVLTree with keys, nodes, entries, or raw data provided
      * in an iterable format.
      * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter in the constructor is an
-     * iterable that can contain either `BTNRep<K, V, AVLTreeNode<K, V>>` objects or `R` objects. It is
+     * iterable that can contain either `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined ` objects or `R` objects. It is
      * used to initialize the AVLTree with key-value pairs or raw data entries. If provided
      * @param [options] - The `options` parameter in the constructor is of type `AVLTreeOptions<K, V,
      * R>`. It is an optional parameter that allows you to specify additional options for configuring the
@@ -104,8 +169,9 @@ class AVLTree extends bst_1.BST {
      * Space Complexity: O(1)
      *
      * The function checks if the input is an instance of AVLTreeNode.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The parameter
-     * `keyNodeOrEntry` can be of type `R` or `BTNRep<K, V, AVLTreeNode<K, V>>`.
+     * @param {K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } keyNodeOrEntry - The parameter
+     * `keyNodeOrEntry` can be of type `R` or `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined `.
      * @returns a boolean value indicating whether the input parameter `keyNodeOrEntry` is
      * an instance of the `AVLTreeNode` class.
      */
@@ -118,8 +184,9 @@ class AVLTree extends bst_1.BST {
      *
      * The function overrides the add method of a class and inserts a key-value pair into a data
      * structure, then balances the path.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The parameter
-     * `keyNodeOrEntry` can accept values of type `R`, `BTNRep<K, V, AVLTreeNode<K, V>>`
+     * @param { K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } keyNodeOrEntry - The parameter
+     * `keyNodeOrEntry` can accept values of type `R`, `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined `
      * @param {V} [value] - The `value` parameter is an optional value that you want to associate with
      * the key or node being added to the data structure.
      * @returns The method is returning a boolean value.
@@ -138,7 +205,7 @@ class AVLTree extends bst_1.BST {
      *
      * The function overrides the delete method in a TypeScript class, performs deletion, and then
      * balances the tree if necessary.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} keyNodeOrEntry - The `keyNodeOrEntry`
+     * @param { K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } keyNodeOrEntry - The `keyNodeOrEntry`
      * parameter in the `override delete` method can be one of the following types:
      * @returns The `delete` method is being overridden in this code snippet. It first calls the `delete`
      * method from the superclass (presumably a parent class) with the provided `predicate`, which could
@@ -464,8 +531,9 @@ class AVLTree extends bst_1.BST {
      *
      * The `_balancePath` function is used to update the heights of nodes and perform rotation operations
      * to restore balance in an AVL tree after inserting a node.
-     * @param {BTNRep<K, V, AVLTreeNode<K, V>>} node - The `node` parameter can be of type `R` or
-     * `BTNRep<K, V, AVLTreeNode<K, V>>`.
+     * @param { K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined } node - The `node` parameter can be of type `R` or
+     * `
+     K | AVLTreeNode<K, V> | [K | null | undefined, V | undefined]  | null | undefined `.
      */
     _balancePath(node) {
         node = this.ensureNode(node);