red-black-tree-typed 1.53.7 → 1.54.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -224,6 +224,58 @@ lastBFSNodes[0].id                          // 12
 
 [//]: # (No deletion!!! Start of Example Replace Section)
 
+### Find elements in a range
+```typescript
+    const bst = new RedBlackTree<number>([10, 5, 15, 3, 7, 12, 18]);
+    console.log(bst.search(new Range(5, 10))); // [5, 10, 7]
+    console.log(bst.search(new Range(4, 12))); // [5, 10, 12, 7]
+    console.log(bst.search(new Range(15, 20))); // [15, 18]
+```
+
+### using Red-Black Tree as a price-based index for stock data
+```typescript
+    // Define the structure of individual stock records
+    interface StockRecord {
+      price: number; // Stock price (key for indexing)
+      symbol: string; // Stock ticker symbol
+      volume: number; // Trade volume
+    }
+
+    // Simulate stock market data as it might come from an external feed
+    const marketStockData: StockRecord[] = [
+      { price: 142.5, symbol: 'AAPL', volume: 1000000 },
+      { price: 335.2, symbol: 'MSFT', volume: 800000 },
+      { price: 3285.04, symbol: 'AMZN', volume: 500000 },
+      { price: 267.98, symbol: 'META', volume: 750000 },
+      { price: 234.57, symbol: 'GOOGL', volume: 900000 }
+    ];
+
+    // Extend the stock record type to include metadata for database usage
+    type StockTableRecord = StockRecord & { lastUpdated: Date };
+
+    // Create a Red-Black Tree to index stock records by price
+    // Simulates a database index with stock price as the key for quick lookups
+    const priceIndex = new RedBlackTree<number, StockTableRecord, StockRecord>(marketStockData, {
+      toEntryFn: stockRecord => [
+        stockRecord.price, // Use stock price as the key
+        {
+          ...stockRecord,
+          lastUpdated: new Date() // Add a timestamp for when the record was indexed
+        }
+      ]
+    });
+
+    // Query the stock with the highest price
+    const highestPricedStock = priceIndex.getRightMost();
+    console.log(priceIndex.get(highestPricedStock)?.symbol); // 'AMZN' // Amazon has the highest price
+
+    // Query stocks within a specific price range (200 to 400)
+    const stocksInRange = priceIndex.rangeSearch(
+      [200, 400], // Price range
+      node => priceIndex.get(node)?.symbol // Extract stock symbols for the result
+    );
+    console.log(stocksInRange); // ['GOOGL', 'MSFT', 'META']
+```
 
 [//]: # (No deletion!!! End of Example Replace Section)
 

package/dist/common/index.js

@@ -1,6 +1,7 @@
 "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";
@@ -12,6 +13,10 @@ class Range {
         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) {

package/dist/data-structures/base/iterable-entry-base.js

@@ -65,7 +65,7 @@ class IterableEntryBase {
     every(predicate, thisArg) {
         let index = 0;
         for (const item of this) {
-            if (!predicate.call(thisArg, item[1], item[0], index++, this)) {
+            if (!predicate.call(thisArg, item[0], item[1], index++, this)) {
                 return false;
             }
         }
@@ -89,7 +89,7 @@ class IterableEntryBase {
     some(predicate, thisArg) {
         let index = 0;
         for (const item of this) {
-            if (predicate.call(thisArg, item[1], item[0], index++, this)) {
+            if (predicate.call(thisArg, item[0], item[1], index++, this)) {
                 return true;
             }
         }
@@ -112,7 +112,7 @@ class IterableEntryBase {
         let index = 0;
         for (const item of this) {
             const [key, value] = item;
-            callbackfn.call(thisArg, value, key, index++, this);
+            callbackfn.call(thisArg, key, value, index++, this);
         }
     }
     /**
@@ -136,7 +136,7 @@ class IterableEntryBase {
         let index = 0;
         for (const item of this) {
             const [key, value] = item;
-            if (callbackfn.call(thisArg, value, key, index++, this))
+            if (callbackfn.call(thisArg, key, value, index++, this))
                 return item;
         }
         return;

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

@@ -0,0 +1,213 @@
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { AVLTreeCounterOptions, BinaryTreeDeleteResult, BSTNOptKeyOrNode, BTNRep, EntryCallback, IterationType, OptNodeOrNull } from '../../types';
+import { IBinaryTree } from '../../interfaces';
+import { AVLTree, AVLTreeNode } from './avl-tree';
+export declare class AVLTreeCounterNode<K = any, V = any> extends AVLTreeNode<K, V> {
+    /**
+     * The constructor function initializes a BinaryTreeNode object with a key, value, and count.
+     * @param {K} key - The `key` parameter is of type `K` and represents the unique identifier
+     * of the binary tree node.
+     * @param {V} [value] - The `value` parameter is an optional parameter of type `V`. It represents the value of the binary
+     * tree node. If no value is provided, it will be `undefined`.
+     * @param {number} [count=1] - The `count` parameter is a number that represents the number of times a particular value
+     * occurs in a binary tree node. It has a default value of 1, which means that if no value is provided for the `count`
+     * parameter when creating a new instance of the `BinaryTreeNode` class.
+     */
+    constructor(key: K, value?: V, count?: number);
+    parent?: AVLTreeCounterNode<K, V>;
+    _left?: OptNodeOrNull<AVLTreeCounterNode<K, V>>;
+    get left(): OptNodeOrNull<AVLTreeCounterNode<K, V>>;
+    set left(v: OptNodeOrNull<AVLTreeCounterNode<K, V>>);
+    _right?: OptNodeOrNull<AVLTreeCounterNode<K, V>>;
+    get right(): OptNodeOrNull<AVLTreeCounterNode<K, V>>;
+    set right(v: OptNodeOrNull<AVLTreeCounterNode<K, V>>);
+}
+/**
+ * The only distinction between a AVLTreeCounter and a AVLTree lies in the ability of the former to store duplicate nodes through the utilization of counters.
+ */
+export declare class AVLTreeCounter<K = any, V = any, R = object, MK = any, MV = any, MR = object> extends AVLTree<K, V, R, MK, MV, MR> implements IBinaryTree<K, V, R, MK, MV, MR> {
+    /**
+     * The constructor initializes a new AVLTreeCounter object with optional initial elements.
+     * @param keysNodesEntriesOrRaws - The `keysNodesEntriesOrRaws` parameter is an
+     * iterable object that can contain either keys, nodes, entries, or raw elements.
+     * @param [options] - The `options` parameter is an optional object that can be used to customize the
+     * behavior of the AVLTreeCounter. It can include properties such as `compareKeys` and
+     * `compareValues` functions to define custom comparison logic for keys and values, respectively.
+     */
+    constructor(keysNodesEntriesOrRaws?: Iterable<BTNRep<K, V, AVLTreeCounterNode<K, V>> | R>, options?: AVLTreeCounterOptions<K, V, R>);
+    protected _count: number;
+    /**
+     * The function calculates the sum of the count property of all nodes in a tree using depth-first
+     * search.
+     * @returns the sum of the count property of all nodes in the tree.
+     */
+    get count(): number;
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function calculates the sum of the count property of all nodes in a tree using depth-first
+     * search.
+     * @returns the sum of the count property of all nodes in the tree.
+     */
+    getComputedCount(): number;
+    /**
+     * The function creates a new AVLTreeCounterNode with the specified key, value, and count.
+     * @param {K} key - The key parameter represents the key of the node being created. It is of type K,
+     * which is a generic type that can be replaced with any specific type when using the function.
+     * @param {V} [value] - The `value` parameter is an optional parameter that represents the value
+     * associated with the key in the node. It is of type `V`, which can be any data type.
+     * @param {number} [count] - The `count` parameter represents the number of occurrences of a
+     * key-value pair in the AVLTreeCounterNode. It is an optional parameter, so it can be omitted when
+     * calling the `createNode` method. If provided, it specifies the initial count for the node.
+     * @returns a new instance of the AVLTreeCounterNode class, casted as AVLTreeCounterNode<K, V>.
+     */
+    createNode(key: K, value?: V, count?: number): AVLTreeCounterNode<K, V>;
+    /**
+     * The function creates a new AVLTreeCounter object with the specified options and returns it.
+     * @param [options] - The `options` parameter is an optional object that contains additional
+     * configuration options for creating the AVLTreeCounter. It can have the following properties:
+     * @returns a new instance of the AVLTreeCounter class, with the specified options, as a TREE
+     * object.
+     */
+    createTree(options?: AVLTreeCounterOptions<K, V, R>): AVLTreeCounter<K, V, R, MK, MV, MR>;
+    /**
+     * 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>>`.
+     * @returns a boolean value indicating whether the input parameter `keyNodeOrEntry` is
+     * an instance of the `AVLTreeCounterNode` class.
+     */
+    isNode(keyNodeOrEntry: BTNRep<K, V, AVLTreeCounterNode<K, V>>): keyNodeOrEntry is AVLTreeCounterNode<K, V>;
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     *
+     * 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
+     * `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,
+     * 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.
+     * @param [count=1] - The `count` parameter represents the number of times the key-value pair should
+     * be added to the data structure. By default, it is set to 1, meaning that the key-value pair will
+     * be added once. However, you can specify a different value for `count` if you want to add
+     * @returns a boolean value.
+     */
+    add(keyNodeOrEntry: BTNRep<K, V, AVLTreeCounterNode<K, V>>, value?: V, count?: number): boolean;
+    /**
+     * Time Complexity: O(log n)
+     * Space Complexity: O(1)
+     *
+     * 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`
+     * 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.
+     * @param [ignoreCount=false] - The `ignoreCount` parameter in the `override delete` method is a
+     * boolean flag that determines whether to ignore the count of the node being deleted. If
+     * `ignoreCount` is set to `true`, the method will delete the node regardless of its count. If
+     * `ignoreCount` is set to
+     * @returns The `delete` method overrides the default delete behavior in a binary tree data
+     * structure. It takes a predicate or node to be deleted and an optional flag to ignore count. The
+     * method returns an array of `BinaryTreeDeleteResult` objects, each containing information about the
+     * deleted node and whether balancing is needed in the tree.
+     */
+    delete(keyNodeOrEntry: BTNRep<K, V, AVLTreeCounterNode<K, V>>, ignoreCount?: boolean): BinaryTreeDeleteResult<AVLTreeCounterNode<K, V>>[];
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The "clear" function overrides the parent class's "clear" function and also resets the count to
+     * zero.
+     */
+    clear(): void;
+    /**
+     * 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
+     * specifies the type of iteration to use when building the balanced binary search tree. It has a
+     * default value of `this.iterationType`, which means it will use the iteration type currently set in
+     * the object.
+     * @returns The function `perfectlyBalance` returns a boolean value. It returns `true` if the
+     * balancing operation is successful, and `false` if there are no nodes to balance.
+     */
+    perfectlyBalance(iterationType?: IterationType): boolean;
+    /**
+     * Time complexity: O(n)
+     * Space complexity: O(n)
+     *
+     * The function overrides the clone method to create a deep copy of a tree object.
+     * @returns The `clone()` method is returning a cloned instance of the `TREE` object.
+     */
+    clone(): AVLTreeCounter<K, V, R, MK, MV, MR>;
+    /**
+     * The `map` function in TypeScript overrides the default behavior to create a new AVLTreeCounter
+     * with modified entries based on a provided callback.
+     * @param callback - The `callback` parameter is a function that will be called for each entry in the
+     * AVLTreeCounter. It takes four arguments:
+     * @param [options] - The `options` parameter in the `override map` function is of type
+     * `AVLTreeCounterOptions<MK, MV, MR>`. This parameter allows you to provide additional
+     * configuration options when creating a new `AVLTreeCounter` instance within the `map` function.
+     * These options
+     * @param {any} [thisArg] - The `thisArg` parameter in the `override map` function is used to specify
+     * the value of `this` when executing the `callback` function. It allows you to set the context
+     * (value of `this`) for the callback function. This can be useful when you want to access properties
+     * or
+     * @returns The `map` method is returning a new `AVLTreeCounter` instance with the entries
+     * transformed by the provided `callback` function. Each entry in the original tree is passed to the
+     * `callback` function along with the index and the original tree itself. The transformed entries are
+     * then added to the new `AVLTreeCounter` instance, which is returned at the end.
+     */
+    map<MK, MV, MR>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: AVLTreeCounterOptions<MK, MV, MR>, thisArg?: any): AVLTreeCounter<MK, MV, MR>;
+    /**
+     * 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 {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`.
+     * @param [count=1] - The `count` parameter is an optional parameter that specifies the number of
+     * times the key-value pair should be added to the data structure. If not provided, it defaults to 1.
+     * @returns either a AVLTreeCounterNode<K, V> object or undefined.
+     */
+    protected _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry: BTNRep<K, V, AVLTreeCounterNode<K, V>>, value?: V, count?: number): [AVLTreeCounterNode<K, V> | undefined, V | undefined];
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The `_swapProperties` function swaps the properties (key, value, count, height) between two nodes
+     * in a binary search tree.
+     * @param {BSTNOptKeyOrNode<K, AVLTreeCounterNode<K, V>>} srcNode - The `srcNode` parameter represents the source node
+     * that will be swapped with the `destNode`.
+     * @param {BSTNOptKeyOrNode<K, AVLTreeCounterNode<K, V>>} destNode - The `destNode` parameter represents the destination
+     * node where the properties will be swapped with the source node.
+     * @returns The method is returning the `destNode` after swapping its properties with the `srcNode`.
+     * If either `srcNode` or `destNode` is undefined, it returns `undefined`.
+     */
+    protected _swapProperties(srcNode: BSTNOptKeyOrNode<K, AVLTreeCounterNode<K, V>>, destNode: BSTNOptKeyOrNode<K, AVLTreeCounterNode<K, V>>): AVLTreeCounterNode<K, V> | undefined;
+    /**
+     * Time Complexity: O(1)
+     * Space Complexity: O(1)
+     *
+     * The function replaces an old node with a new node and updates the count property of the new node.
+     * @param {AVLTreeCounterNode<K, V>} oldNode - The oldNode parameter represents the node that needs to be replaced in the
+     * data structure. It is of type AVLTreeCounterNode<K, V>.
+     * @param {AVLTreeCounterNode<K, V>} newNode - The `newNode` parameter is an instance of the `AVLTreeCounterNode<K, V>` class.
+     * @returns The method is returning the result of calling the `_replaceNode` method from the
+     * superclass, which is of type `AVLTreeCounterNode<K, V>`.
+     */
+    protected _replaceNode(oldNode: AVLTreeCounterNode<K, V>, newNode: AVLTreeCounterNode<K, V>): AVLTreeCounterNode<K, V>;
+}