data-structure-typed 2.2.5 → 2.2.7

package/CHANGELOG.md

@@ -8,7 +8,7 @@ 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.5](https://github.com/zrwusa/data-structure-typed/compare/v2.2.3...main) (upcoming)
+## [v2.2.7](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)
 

package/CONTRIBUTING.md

@@ -83,9 +83,55 @@
 - click the `New pull request` on Github https://github.com/zrwusa/data-structure-typed/branches
 
 **performance inspection**
-- `node --inspect-brk benchmark/all.js`  
+- `node --inspect-brk perf/hello-world.js`  
 - chrome://inspect/#devices -> Open dedicated DevTools for Node
 
+
+**node:perf_hooks**
+```javascript
+const { performance } = require('node:perf_hooks');
+
+// Force garbage collection (run with --expose-gc flag)
+const forceGC = () => {
+  if (global.gc) {
+    global.gc();
+  }
+};
+
+// Test Queue
+function testQueue(QUANTITY) {
+  forceGC();
+  const initialMemory = process.memoryUsage().heapUsed;
+
+  const queue = new Queue();
+  const start = performance.now();
+
+  for (let i = 0; i < QUANTITY; i++) {
+    queue.push(i);
+  }
+
+  const end = performance.now();
+  const finalMemory = process.memoryUsage().heapUsed;
+  const memoryDelta = formatMemory(finalMemory - initialMemory);
+
+  console.log(`Queue push ${QUANTITY} elements: ${(end - start).toFixed(2)}ms`);
+  console.log(`Memory usage: ${memoryDelta}${CURRENT_UNIT} (growth)`);
+
+  return queue;
+}
+
+testDeque(1000000);
+
+```
+
+```shell
+ node --expose-gc benchmark/deque.js
+```
+
+**performance info output**
+-`node --prof perf/hello-world.js`
+-`node --prof-process isolate-*.log > prof.txt`
+
 **Contributing New Data Structures**
 
 - Make your pull requests to be **specific** and **focused**. Instead of

package/README.md

@@ -2,7 +2,7 @@
 
 A comprehensive TypeScript data structures library with production-ready implementations.
 
-**📚 [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)**
+**📚 [Installation](#-installation) • [Quick Start](#-quick-start-30-seconds) • [Full Docs](./docs/CONCEPTS.md) • [API Reference](./docs/REFERENCE.md) • [Playground](#playground) • [Examples](./docs/GUIDES.md)**
 
 ---
 
@@ -484,14 +484,14 @@ const tree = new RedBlackTree([5, 2, 8]);
 console.log([...tree]);  // [2, 5, 8] - Automatically sorted!
 ```
 
-## 🏃🏻‍♀️ Playground
+## Playground
 
-Try it instantly:
+🏃🏻‍♀️ 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)
+- [Node.js JavaScript](https://stackblitz.com/edit/stackblitz-starters-oczhrfzn?file=src%2Findex.js)
+- [React TypeScript](https://stackblitz.com/edit/vitejs-vite-7bva1zhd?file=src%2FApp.tsx)
+- [NestJS](https://stackblitz.com/edit/nestjs-typescript-starter-q9n7okgc?file=src%2Fproduct%2Fservices%2Fproduct-price-index.service.ts)
 
 
 ### Step 4: Learn More

package/dist/cjs/index.cjs

@@ -160,6 +160,14 @@ var IterableEntryBase = class {
     }
     return accumulator;
   }
+  /**
+   * Converts data structure to `[key, value]` pairs.
+   * @returns Array of entries.
+   * @remarks Time O(n), Space O(n)
+   */
+  toArray() {
+    return [...this];
+  }
   /**
    * Visualize the iterable as an array of `[key, value]` pairs (or a custom string).
    * @returns Array of entries (default) or a string.
@@ -6830,8 +6838,6 @@ var Range = class {
     this.high = high;
     this.includeLow = includeLow;
     this.includeHigh = includeHigh;
-    if (!(isComparable(low) && 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");
   }
   static {
     __name(this, "Range");
@@ -8977,77 +8983,63 @@ 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);
-  }
-  /**
-   * Returns the first node with a key greater than or equal to the given key.
-   * This is equivalent to Java TreeMap.ceilingEntry().
-   * Supports RECURSIVE and ITERATIVE implementations.
-   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
-   * @returns The first node with key >= given key, or undefined if no such node exists.
-   */
-  ceilingEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
-    return this.lowerBound(keyNodeEntryOrPredicate, iterationType);
+  ceiling(keyNodeEntryOrPredicate, callback = this._DEFAULT_NODE_CALLBACK, iterationType) {
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
+    const node = this._bound(keyNodeEntryOrPredicate, true, actualIterationType);
+    if (!actualCallback) {
+      return node?.key;
+    }
+    return node ? actualCallback(node) : void 0;
   }
-  /**
-   * Returns the first node with a key strictly greater than the given key.
-   * This is equivalent to Java TreeMap.higherEntry().
-   * Supports RECURSIVE and ITERATIVE implementations.
-   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
-   * @returns The first node with key > given key, or undefined if no such node exists.
-   */
-  higherEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
-    return this.upperBound(keyNodeEntryOrPredicate, iterationType);
+  higher(keyNodeEntryOrPredicate, callback = this._DEFAULT_NODE_CALLBACK, iterationType) {
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
+    const node = this._bound(keyNodeEntryOrPredicate, false, actualIterationType);
+    if (!actualCallback) {
+      return node?.key;
+    }
+    return node ? actualCallback(node) : void 0;
   }
-  /**
-   * Returns the first node with a key less than or equal to the given key.
-   * This is equivalent to Java TreeMap.floorEntry().
-   * Supports RECURSIVE and ITERATIVE implementations.
-   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
-   * @returns The first node with key <= given key, or undefined if no such node exists.
-   */
-  floorEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+  floor(keyNodeEntryOrPredicate, callback = this._DEFAULT_NODE_CALLBACK, iterationType) {
     if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      if (typeof callback === "string" || !callback) {
+        return void 0;
+      }
       return void 0;
     }
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
     if (this._isPredicate(keyNodeEntryOrPredicate)) {
-      return this._floorByPredicate(keyNodeEntryOrPredicate, iterationType);
+      const node = this._floorByPredicate(keyNodeEntryOrPredicate, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
     }
     let targetKey;
     if (this.isNode(keyNodeEntryOrPredicate)) {
@@ -9055,6 +9047,9 @@ var BST = class extends BinaryTree {
     } else if (this.isEntry(keyNodeEntryOrPredicate)) {
       const key = keyNodeEntryOrPredicate[0];
       if (key === null || key === void 0) {
+        if (typeof callback === "string" || !callback) {
+          return void 0;
+        }
         return void 0;
       }
       targetKey = key;
@@ -9062,27 +9057,40 @@ var BST = class extends BinaryTree {
       targetKey = keyNodeEntryOrPredicate;
     }
     if (targetKey !== void 0) {
-      return this._floorByKey(targetKey, iterationType);
+      const node = this._floorByKey(targetKey, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
+    }
+    if (typeof callback === "string" || !callback) {
+      return void 0;
     }
     return void 0;
   }
-  /**
-   * Returns the first node with a key strictly less than the given key.
-   * This is equivalent to Java TreeMap.lowerEntry().
-   * Supports RECURSIVE and ITERATIVE implementations.
-   * @remarks 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=this.iterationType] - The iteration type (RECURSIVE or ITERATIVE).
-   * @returns The first node with key < given key, or undefined if no such node exists.
-   */
-  lowerEntry(keyNodeEntryOrPredicate, iterationType = this.iterationType) {
+  lower(keyNodeEntryOrPredicate, callback, iterationType) {
     if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === void 0) {
+      if (typeof callback === "string" || !callback) {
+        return void 0;
+      }
       return void 0;
     }
+    let actualCallback = void 0;
+    let actualIterationType = this.iterationType;
+    if (typeof callback === "string") {
+      actualIterationType = callback;
+    } else if (callback) {
+      actualCallback = callback;
+      if (iterationType) {
+        actualIterationType = iterationType;
+      }
+    }
     if (this._isPredicate(keyNodeEntryOrPredicate)) {
-      return this._lowerByPredicate(keyNodeEntryOrPredicate, iterationType);
+      const node = this._lowerByPredicate(keyNodeEntryOrPredicate, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
     }
     let targetKey;
     if (this.isNode(keyNodeEntryOrPredicate)) {
@@ -9090,6 +9098,9 @@ var BST = class extends BinaryTree {
     } else if (this.isEntry(keyNodeEntryOrPredicate)) {
       const key = keyNodeEntryOrPredicate[0];
       if (key === null || key === void 0) {
+        if (typeof callback === "string" || !callback) {
+          return void 0;
+        }
         return void 0;
       }
       targetKey = key;
@@ -9097,7 +9108,14 @@ var BST = class extends BinaryTree {
       targetKey = keyNodeEntryOrPredicate;
     }
     if (targetKey !== void 0) {
-      return this._lowerByKey(targetKey, iterationType);
+      const node = this._lowerByKey(targetKey, actualIterationType);
+      if (!actualCallback) {
+        return node?.key;
+      }
+      return node ? actualCallback(node) : void 0;
+    }
+    if (typeof callback === "string" || !callback) {
+      return void 0;
     }
     return void 0;
   }
@@ -9286,7 +9304,6 @@ var BST = class extends BinaryTree {
    */
   _createDefaultComparator() {
     return (a, b) => {
-      debugger;
       if (isComparable(a) && isComparable(b)) {
         if (a > b) return 1;
         if (a < b) return -1;