data-structure-typed 2.2.3 → 2.2.4

package/CHANGELOG.md

@@ -8,7 +8,9 @@ All notable changes to this project will be documented in this file.
 - [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - [`auto-changelog`](https://github.com/CookPete/auto-changelog)
 
-## [v2.2.3](https://github.com/zrwusa/data-structure-typed/compare/v2.2.2...main) (upcoming)
+## [v2.2.4](https://github.com/zrwusa/data-structure-typed/compare/v2.2.3...main) (upcoming)
+
+## [v2.2.3](https://github.com/zrwusa/data-structure-typed/compare/v2.2.2...v2.2.3) (6 January 2026)
 
 ## [v2.2.2](https://github.com/zrwusa/data-structure-typed/compare/v2.0.4...v2.2.2) (5 January 2026)
 

package/README.md

@@ -2,7 +2,7 @@
 
 A comprehensive TypeScript data structures library with production-ready implementations.
 
-**📚 [Quick Start](#-quick-start-30-seconds) • [Full Docs](./docs/CONCEPTS.md) • [API Reference](./docs/REFERENCE.md) • [Examples](./docs/GUIDES.md)**
+**📚 [Quick Start](#-quick-start-30-seconds) • [Installation](#-installation) • [Full Docs](./docs/CONCEPTS.md) • [API Reference](./docs/REFERENCE.md) • [Playground](#-playground) • [Installation](#-installation) • [Examples](./docs/GUIDES.md)**
 
 ---
 
@@ -56,10 +56,11 @@ for (let i = 0; i < 100000; i++) {
   queue.shift();  // O(n) - Reindexes EVERY element!
 }
 // Time: 2829ms ❌
+```
 
+```javascript
 // ✅ WITH data-structure-typed (Deque)
-const deque = new Deque([1, 2, 3, ..., 100000
-])
+const deque = new Deque([1, 2, 3, ..., 100000])
 ;
 for (let i = 0; i < 100000; i++) {
   deque.shift();  // O(1) - Just moves a pointer
@@ -95,7 +96,8 @@ Don't learn new APIs. Just use `push`, `pop`, `map`, `filter`, and `reduce` ever
 // All linear structures use THE SAME 4 methods
 const deque = new Deque([1, 2, 3]);
 const queue = new Queue([1, 2, 3]);
-const stack = new Stack([1, 2, 3]);
+const doublyLinkeList = new DoublyLinkedList([1, 2, 3]);
+const singlyLinkedList = new SinglyLinkedList([1, 2, 3]);
 
 // They ALL support:
 structure.push(item);          // Add to end
@@ -211,7 +213,7 @@ const topPlayers = [...leaderboard.values()].reverse().slice(0, 3);
 ```typescript
 import { MaxPriorityQueue } from 'data-structure-typed';
 
-const taskQueue = new MaxPriorityQueue([], {
+const taskQueue = new MaxPriorityQueue<{priority: number; task: string}>([], {
   comparator: (a, b) => b.priority - a.priority
 });
 
@@ -329,20 +331,67 @@ class LRUCache<K, V> {
 ### Leaderboard
 
 ```typescript
-class Leaderboard {
-  private scores = new RedBlackTree<number, Player>(
-    (a, b) => b - a  // Descending
-  );
 
-  getTopN(n: number): Player[] {
-    return [...this.scores.values()].slice(0, n);
+type Player = {
+  id: string;
+  name: string;
+  score: number;
+};
+
+const seedPlayers: Player[] = [
+  { id: 'player_01HZX4E8Q2K8Y3J9M7T1A6B3C4', name: 'Pablo', score: 65 },
+  { id: 'player_01HZX4E9R6V2D8K1P0N5S4T7U8', name: 'Bunny', score: 10 },
+  { id: 'player_01HZX4EA3M9Q7W1E2R8T6Y5U0I', name: 'Jeff', score: 99 },
+];
+
+class ScoreLeaderboard {
+  private readonly byScore: RedBlackTree<number, Player, Player>;
+
+  constructor(initialPlayers: Player[]) {
+    this.byScore = new RedBlackTree<number, Player, Player>(initialPlayers, {
+      isMapMode: false,// Use "node value" storage rather than Map-style.
+      toEntryFn: (player) => [player.score, player], // Convert a player object into the tree entry: key = score, value = player.
+    });
+  }
+
+  /**
+   * Returns players whose scores fall within the given range.
+   * Supports either a tuple [min, max] or a Range object for inclusive/exclusive bounds.
+   */
+  public findPlayersByScoreRange(range: [number, number] | Range<number>): (Player | undefined)[] {
+    return this.byScore.rangeSearch(range, (node) => node.value);
+  }
+  
+  public upsertPlayer(player: Player) {
+    return this.byScore.set(player.score, player);
   }
 }
+
+const leaderboard = new ScoreLeaderboard(seedPlayers);
+
+console.log(leaderboard.findPlayersByScoreRange([65, 100]));
+
+leaderboard.upsertPlayer({
+  id: 'player_01HZX4EB7C4N2M9Q8R1T3Y6U5I',
+  name: 'Alex',
+  score: 80,
+});
+
+console.log(leaderboard.findPlayersByScoreRange(new Range(65, 100, true, true)));
 ```
 
 ### Message Queue
 
 ```typescript
+type Message = {
+  id: string;
+  type: string;
+  payload: unknown;
+  priority: 'urgent' | 'normal';
+  createdAt: number;
+  retryCount?: number;
+};
+
 class MessageQueue {
   private urgent = new Deque<Message>();
   private normal = new Deque<Message>();
@@ -435,6 +484,16 @@ const tree = new RedBlackTree([5, 2, 8]);
 console.log([...tree]);  // [2, 5, 8] - Automatically sorted!
 ```
 
+## 🏃🏻‍♀️ Playground
+
+Try it instantly:
+
+- [Node.js TypeScript](https://stackblitz.com/edit/stackblitz-starters-e1vdy3zw?file=src%2Findex.ts)
+- [Node.js JavaScript](https://stackblitz.com/edit/stackblitz-starters-dgvchziu?file=src%2Findex.js)
+- [React TypeScript](https://stackblitz.com/edit/vitejs-vite-6xvhtdua?file=src%2FApp.tsx)
+- [NestJS](https://stackblitz.com/edit/nestjs-typescript-starter-3cyp7pel?file=src%2Franking%2Franking.service.ts)
+
+
 ### Step 4: Learn More
 
 👉 Check [CONCEPTS.md](./docs/CONCEPTS.md) for core concepts  

package/dist/cjs/index.cjs

@@ -8636,9 +8636,13 @@ var BST = class extends BinaryTree {
   constructor(keysNodesEntriesOrRaws = [], options) {
     super([], options);
     if (options) {
-      const { specifyComparable, isReverse } = options;
-      if (typeof specifyComparable === "function") this._specifyComparable = specifyComparable;
-      if (isReverse !== void 0) this._isReverse = isReverse;
+      if ("comparator" in options && options.comparator !== void 0) {
+        this._comparator = options.comparator;
+      } else {
+        this._comparator = this._createDefaultComparator();
+      }
+    } else {
+      this._comparator = this._createDefaultComparator();
     }
     if (keysNodesEntriesOrRaws) this.addMany(keysNodesEntriesOrRaws);
   }
@@ -8652,40 +8656,33 @@ var BST = class extends BinaryTree {
   get root() {
     return this._root;
   }
-  _isReverse = false;
   /**
-   * Gets whether the tree's comparison logic is reversed.
-   * @remarks Time O(1)
-   *
-   * @returns True if the tree is reversed (e.g., a max-heap logic).
+   * (Protected) Creates the default comparator function for keys that don't have a custom comparator.
+   * @remarks Time O(1) Space O(1)
+   * @returns The default comparator function.
    */
-  get isReverse() {
-    return this._isReverse;
+  _createDefaultComparator() {
+    return (a, b) => {
+      debugger;
+      if (isComparable(a) && isComparable(b)) {
+        if (a > b) return 1;
+        if (a < b) return -1;
+        return 0;
+      }
+      if (typeof a === "object" || typeof b === "object") {
+        throw TypeError(
+          `When comparing object type keys, a custom comparator must be provided in the constructor's options!`
+        );
+      }
+      return 0;
+    };
   }
   /**
-   * The default comparator function.
-   * @remarks Time O(1) (or O(C) if `specifyComparable` is used, C is complexity of that function).
-   */
-  _comparator = /* @__PURE__ */ __name((a, b) => {
-    if (isComparable(a) && isComparable(b)) {
-      if (a > b) return 1;
-      if (a < b) return -1;
-      return 0;
-    }
-    if (this._specifyComparable) {
-      const va = this._specifyComparable(a);
-      const vb = this._specifyComparable(b);
-      if (va > vb) return 1;
-      if (va < vb) return -1;
-      return 0;
-    }
-    if (typeof a === "object" || typeof b === "object") {
-      throw TypeError(
-        `When comparing object types, a custom specifyComparable must be defined in the constructor's options.`
-      );
-    }
-    return 0;
-  }, "_comparator");
+     * The comparator function used to determine the order of keys in the tree.
+  
+     * @remarks Time O(1) Space O(1)
+     */
+  _comparator;
   /**
    * Gets the comparator function used by the tree.
    * @remarks Time O(1)
@@ -8695,16 +8692,6 @@ var BST = class extends BinaryTree {
   get comparator() {
     return this._comparator;
   }
-  _specifyComparable;
-  /**
-   * Gets the function used to extract a comparable value from a complex key.
-   * @remarks Time O(1)
-   *
-   * @returns The key-to-comparable conversion function.
-   */
-  get specifyComparable() {
-    return this._specifyComparable;
-  }
   /**
    * (Protected) Creates a new BST node.
    * @remarks Time O(1), Space O(1)
@@ -8745,7 +8732,7 @@ var BST = class extends BinaryTree {
    * @returns True if the key is valid, false otherwise.
    */
   isValidKey(key) {
-    return isComparable(key, this._specifyComparable !== void 0);
+    return isComparable(key);
   }
   /**
    * Performs a Depth-First Search (DFS) traversal.
@@ -8834,8 +8821,8 @@ var BST = class extends BinaryTree {
       if (!this.isRealNode(cur.left)) return false;
       if (isRange) {
         const range = keyNodeEntryOrPredicate;
-        const leftS = this.isReverse ? range.high : range.low;
-        const leftI = this.isReverse ? range.includeHigh : range.includeLow;
+        const leftS = range.low;
+        const leftI = range.includeLow;
         return leftI && this._compare(cur.key, leftS) >= 0 || !leftI && this._compare(cur.key, leftS) > 0;
       }
       if (!isRange && !this._isPredicate(keyNodeEntryOrPredicate)) {
@@ -8849,8 +8836,8 @@ var BST = class extends BinaryTree {
       if (!this.isRealNode(cur.right)) return false;
       if (isRange) {
         const range = keyNodeEntryOrPredicate;
-        const rightS = this.isReverse ? range.low : range.high;
-        const rightI = this.isReverse ? range.includeLow : range.includeHigh;
+        const rightS = range.high;
+        const rightI = range.includeHigh;
         return rightI && this._compare(cur.key, rightS) <= 0 || !rightI && this._compare(cur.key, rightS) < 0;
       }
       if (!isRange && !this._isPredicate(keyNodeEntryOrPredicate)) {
@@ -9171,31 +9158,55 @@ var BST = class extends BinaryTree {
     return out;
   }
   /**
-   * Deletes the first node found that satisfies the predicate.
-   * @remarks Performs an in-order traversal. Time O(N) worst-case (O(log N) to find + O(log N) to delete). Space O(log N) for stack.
+   * Deletes nodes that match a key, node, entry, predicate, or range.
    *
-   * @param predicate - A function to test each [key, value] pair.
-   * @returns True if a node was deleted, false otherwise.
-   */
-  deleteWhere(predicate) {
-    const stack = [];
-    let cur = this._root;
-    let index = 0;
-    while (stack.length > 0 || cur !== void 0) {
-      while (cur !== void 0 && cur !== null) {
-        stack.push(cur);
-        cur = cur.left;
-      }
-      const node = stack.pop();
-      if (!node) break;
-      const key = node.key;
-      const val = node.value;
-      if (predicate(key, val, index++, this)) {
-        return this._deleteByKey(key);
-      }
-      cur = node.right;
+   * @remarks
+   * Time Complexity: O(N) for search + O(M log N) for M deletions, where N is tree size.
+   * Space Complexity: O(M) for storing matched nodes and result map.
+   *
+   * @template K - The key type.
+   * @template V - The value type.
+   *
+   * @param keyNodeEntryOrPredicate - The search criteria. Can be one of:
+   *   - A key (type K): searches for exact key match using the comparator.
+   *   - A BSTNode: searches for the matching node in the tree.
+   *   - An entry tuple: searches for the key-value pair.
+   *   - A NodePredicate function: tests each node and returns true for matches.
+   *   - A Range object: searches for nodes whose keys fall within the specified range (inclusive/exclusive based on range settings).
+   *   - null or undefined: treated as no match, returns empty results.
+   *
+   * @param onlyOne - If true, stops the search after finding the first match and only deletes that one node.
+   *   If false (default), searches for and deletes all matching nodes.
+   *
+   * @param startNode - The node to start the search from. Can be:
+   *   - A key, node, or entry: the method resolves it to a node and searches from that subtree.
+   *   - null or undefined: defaults to the root, searching the entire tree.
+   *   - Default value: this._root (the tree's root).
+   *
+   * @param iterationType - Controls the internal traversal implementation:
+   *   - 'RECURSIVE': uses recursive function calls for traversal.
+   *   - 'ITERATIVE': uses explicit stack-based iteration.
+   *   - Default: this.iterationType (the tree's default iteration mode).
+   *
+   * @returns A Map<K, boolean> containing the deletion results:
+   *   - Key: the matched node's key.
+   *   - Value: true if the deletion succeeded, false if it failed (e.g., key not found during deletion phase).
+   *   - If no nodes match the search criteria, the returned map is empty.
+   */
+  deleteWhere(keyNodeEntryOrPredicate, onlyOne = false, startNode = this._root, iterationType = this.iterationType) {
+    const toDelete = this.search(
+      keyNodeEntryOrPredicate,
+      onlyOne,
+      (node) => node,
+      startNode,
+      iterationType
+    );
+    let results = [];
+    for (const node of toDelete) {
+      const deleteInfo = this.delete(node);
+      results = results.concat(deleteInfo);
     }
-    return false;
+    return results;
   }
   /**
    * (Protected) Core bound search implementation supporting all parameter types.
@@ -9347,8 +9358,7 @@ var BST = class extends BinaryTree {
   _snapshotOptions() {
     return {
       ...super._snapshotOptions(),
-      specifyComparable: this.specifyComparable,
-      isReverse: this.isReverse
+      comparator: this._comparator
     };
   }
   /**
@@ -9376,14 +9386,14 @@ var BST = class extends BinaryTree {
   }
   /**
    * (Protected) Compares two keys using the tree's comparator and reverse setting.
-   * @remarks Time O(1) (or O(C) if `specifyComparable` is used).
+   * @remarks Time O(1) Space O(1)
    *
    * @param a - The first key.
    * @param b - The second key.
    * @returns A number (1, -1, or 0) representing the comparison.
    */
   _compare(a, b) {
-    return this._isReverse ? -this._comparator(a, b) : this._comparator(a, b);
+    return this._comparator(a, b);
   }
   /**
    * (Private) Deletes a node by its key.