red-black-tree-typed 2.2.1 → 2.2.3

package/README.md

@@ -224,49 +224,104 @@ lastBFSNodes[0].id                          // 12
 
 [//]: # (No deletion!!! Start of Example Replace Section)
 
-### using Red-Black Tree as a price-based index for stock data
+### basic Red-Black Tree with simple number keys
 ```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
+ // Create a simple Red-Black Tree with numeric keys
+    const tree = new RedBlackTree([5, 2, 8, 1, 9]);
+
+    tree.print();
+    //   _2___
+    //  /     \
+    //  1    _8_
+    //      /   \
+    //      5   9
+
+    // Verify the tree maintains sorted order
+    console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
+
+    // Check size
+    console.log(tree.size); // 5;
+```
+
+### Red-Black Tree with key-value pairs for lookups
+```typescript
+ interface Employee {
+      id: number;
+      name: string;
+    }
+
+    // Create tree with employee data
+    const employees = new RedBlackTree<number, Employee>([
+      [1, { id: 1, name: 'Alice' }],
+      [3, { id: 3, name: 'Charlie' }],
+      [2, { id: 2, name: 'Bob' }]
+    ]);
+
+    // Retrieve employee by ID
+    const alice = employees.get(1);
+    console.log(alice?.name); // 'Alice';
+
+    // Verify sorted order by ID
+    console.log([...employees.keys()]); // [1, 2, 3];
+```
+
+### Red-Black Tree range search for filtering
+```typescript
+ interface Product {
+      name: string;
+      price: number;
     }
 
-    // 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
-        }
-      ]
+    const products = new RedBlackTree<number, Product>([
+      [10, { name: 'Item A', price: 10 }],
+      [25, { name: 'Item B', price: 25 }],
+      [40, { name: 'Item C', price: 40 }],
+      [50, { name: 'Item D', price: 50 }]
+    ]);
+
+    // Find products in price range [20, 45]
+    const pricesInRange = products.rangeSearch([20, 45], node => {
+      return products.get(node)?.name;
     });
 
-    // Query the stock with the highest price
-    const highestPricedStock = priceIndex.getRightMost();
-    console.log(priceIndex.get(highestPricedStock)?.symbol); // 'AMZN' // Amazon has the highest price
+    console.log(pricesInRange); // ['Item B', 'Item C'];
+```
+
+### Red-Black Tree as database index for stock market data
+```typescript
+ interface StockPrice {
+      symbol: string;
+      volume: number;
+      timestamp: Date;
+    }
+
+    // Simulate real-time stock price index
+    const priceIndex = new RedBlackTree<number, StockPrice>([
+      [142.5, { symbol: 'AAPL', volume: 1000000, timestamp: new Date() }],
+      [335.2, { symbol: 'MSFT', volume: 800000, timestamp: new Date() }],
+      [3285.04, { symbol: 'AMZN', volume: 500000, timestamp: new Date() }],
+      [267.98, { symbol: 'META', volume: 750000, timestamp: new Date() }],
+      [234.57, { symbol: 'GOOGL', volume: 900000, timestamp: new Date() }]
+    ]);
+
+    // Find highest-priced stock
+    const maxPrice = priceIndex.getRightMost();
+    console.log(priceIndex.get(maxPrice)?.symbol); // 'AMZN';
+
+    // Find stocks in price range [200, 400] for portfolio balancing
+    const stocksInRange = priceIndex.rangeSearch([200, 400], node => {
+      const stock = priceIndex.get(node);
+      return {
+        symbol: stock?.symbol,
+        price: node,
+        volume: stock?.volume
+      };
+    });
 
-    // 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', 'META', 'MSFT']
+    console.log(stocksInRange.length); // 3;
+    console.log(stocksInRange.some((s: any) => s.symbol === 'GOOGL')); // true;
+    console.log(stocksInRange.some((s: any) => s.symbol === 'META')); // true;
+    console.log(stocksInRange.some((s: any) => s.symbol === 'MSFT')); // true;
 ```
 
 [//]: # (No deletion!!! End of Example Replace Section)

package/dist/cjs/index.cjs

@@ -1463,6 +1463,17 @@ var BinaryTree = class extends IterableEntryBase {
     }
     return false;
   }
+  /**
+   * Adds or updates a new node to the tree.
+   * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). This implementation adds the node at the first available position in a level-order (BFS) traversal. This is NOT a Binary Search Tree insertion. Time O(N), where N is the number of nodes. It must traverse level-by-level to find an empty slot. Space O(N) in the worst case for the BFS queue (e.g., a full last level).
+   *
+   * @param keyNodeOrEntry - The key, node, or entry to add or update.
+   * @param [value] - The value, if providing just a key.
+   * @returns True if the addition was successful, false otherwise.
+   */
+  set(keyNodeOrEntry, value) {
+    return this.add(keyNodeOrEntry, value);
+  }
   /**
    * Adds multiple items to the tree.
    * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
@@ -1490,6 +1501,17 @@ var BinaryTree = class extends IterableEntryBase {
     }
     return inserted;
   }
+  /**
+   * Adds or updates multiple items to the tree.
+   * @remarks Time O(N * M), where N is the number of items to add and M is the size of the tree at insertion (due to O(M) `add` operation). Space O(M) (from `add`) + O(N) (for the `inserted` array).
+   *
+   * @param keysNodesEntriesOrRaws - An iterable of items to add or update.
+   * @param [values] - An optional parallel iterable of values.
+   * @returns An array of booleans indicating the success of each individual `add` operation.
+   */
+  setMany(keysNodesEntriesOrRaws, values) {
+    return this.addMany(keysNodesEntriesOrRaws, values);
+  }
   /**
    * Merges another tree into this one by adding all its nodes.
    * @remarks Time O(N * M), same as `addMany`, where N is the size of `anotherTree` and M is the size of this tree. Space O(M) (from `add`).
@@ -3188,6 +3210,32 @@ var BST = class extends BinaryTree {
     else _iterate();
     return inserted;
   }
+  /**
+   * Returns the first node with a key greater than or equal to the given key.
+   * This is equivalent to C++ std::lower_bound on a BST.
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * Time Complexity: O(log n) on average, O(h) where h is tree height.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+   * @returns The first node with key >= given key, or undefined if no such node exists.
+   */
+  lowerBound(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    return this._bound(keyNodeEntryOrPredicate, true, iterationType);
+  }
+  /**
+   * Returns the first node with a key strictly greater than the given key.
+   * This is equivalent to C++ std::upper_bound on a BST.
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * Time Complexity: O(log n) on average, O(h) where h is tree height.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+   * @returns The first node with key > given key, or undefined if no such node exists.
+   */
+  upperBound(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+    return this._bound(keyNodeEntryOrPredicate, false, iterationType);
+  }
   /**
    * Traverses the tree and returns nodes that are lesser or greater than a target node.
    * @remarks Time O(N), as it performs a full traversal. Space O(log N) or O(N).
@@ -3348,6 +3396,121 @@ var BST = class extends BinaryTree {
     }
     return false;
   }
+  /**
+   * (Protected) Core bound search implementation supporting all parameter types.
+   * Unified logic for both lowerBound and upperBound.
+   * Resolves various input types (Key, Node, Entry, Predicate) using parent class utilities.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param isLower - True for lowerBound (>=), false for upperBound (>).
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first matching node, or undefined if no such node exists.
+   */
+  _bound(keyNodeEntryOrPredicate, isLower, iterationType) {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      return void 0;
+    }
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      return this._boundByPredicate(keyNodeEntryOrPredicate, iterationType);
+    }
+    let targetKey;
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === void 0) {
+        return void 0;
+      }
+      targetKey = key;
+    } else {
+      targetKey = keyNodeEntryOrPredicate;
+    }
+    if (targetKey !== void 0) {
+      return this._boundByKey(targetKey, isLower, iterationType);
+    }
+    return void 0;
+  }
+  /**
+   * (Protected) Binary search for bound by key with pruning optimization.
+   * Performs standard BST binary search, choosing left or right subtree based on comparator result.
+   * For lowerBound: finds first node where key >= target.
+   * For upperBound: finds first node where key > target.
+   * @param key - The target key to search for.
+   * @param isLower - True for lowerBound (>=), false for upperBound (>).
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node matching the bound condition, or undefined if none exists.
+   */
+  _boundByKey(key, isLower, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (!this.isRealNode(cur)) return void 0;
+        const cmp = this.comparator(cur.key, key);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+        if (condition) {
+          const leftResult = dfs(cur.left);
+          return leftResult ?? cur;
+        } else {
+          return dfs(cur.right);
+        }
+      }, "dfs");
+      return dfs(this.root);
+    } else {
+      let current = this.root;
+      let result = void 0;
+      while (this.isRealNode(current)) {
+        const cmp = this.comparator(current.key, key);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+        if (condition) {
+          result = current;
+          current = current.left ?? void 0;
+        } else {
+          current = current.right ?? void 0;
+        }
+      }
+      return result;
+    }
+  }
+  /**
+   * (Protected) In-order traversal search by predicate.
+   * Falls back to linear in-order traversal when predicate-based search is required.
+   * Returns the first node that satisfies the predicate function.
+   * Note: Predicate-based search cannot leverage BST's binary search optimization.
+   * Time Complexity: O(n) since it may visit every node.
+   * @param predicate - The predicate function to test nodes.
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node satisfying predicate, or undefined if none found.
+   */
+  _boundByPredicate(predicate, iterationType) {
+    if (iterationType === "RECURSIVE") {
+      let result = void 0;
+      const dfs = /* @__PURE__ */ __name((cur) => {
+        if (result || !this.isRealNode(cur)) return;
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+        if (!result && predicate(cur)) {
+          result = cur;
+        }
+        if (!result && this.isRealNode(cur.right)) dfs(cur.right);
+      }, "dfs");
+      dfs(this.root);
+      return result;
+    } else {
+      const stack = [];
+      let current = this.root;
+      while (stack.length > 0 || this.isRealNode(current)) {
+        if (this.isRealNode(current)) {
+          stack.push(current);
+          current = current.left;
+        } else {
+          const node = stack.pop();
+          if (!this.isRealNode(node)) break;
+          if (predicate(node)) {
+            return node;
+          }
+          current = node.right;
+        }
+      }
+      return void 0;
+    }
+  }
   /**
    * (Protected) Creates a new, empty instance of the same BST constructor.
    * @remarks Time O(1)