binary-tree-typed 2.5.1 → 2.5.3

package/src/data-structures/binary-tree/tree-set.ts

@@ -9,7 +9,7 @@
 
 import type { Comparator } from '../../types';
 import type { TreeSetElementCallback, TreeSetOptions, TreeSetRangeOptions, TreeSetReduceCallback } from '../../types';
-import { ERR } from '../../common';
+import { ERR, raise } from '../../common';
 import { RedBlackTree } from './red-black-tree';
 
 /**
@@ -50,7 +50,7 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
     this.#isDefaultComparator = options.comparator === undefined;
 
     // RedBlackTree expects an iterable of keys/entries/nodes/raws; for TreeSet we only accept keys.
-    this.#core = new RedBlackTree<K, undefined>([], { comparator, isMapMode: options.isMapMode });
+    this.#core = new RedBlackTree<K, undefined>([], { comparator, isMapMode: options.isMapMode, enableOrderStatistic: options.enableOrderStatistic });
 
     for (const item of elements) {
       const k = toElementFn ? toElementFn(item as R) : item as K;
@@ -73,7 +73,7 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
       // numbers
       if (typeof a === 'number' && typeof b === 'number') {
         /* istanbul ignore next -- _validateKey prevents NaN from entering the tree */
-        if (Number.isNaN(a) || Number.isNaN(b)) throw new TypeError(ERR.invalidNaN('TreeSet'));
+        if (Number.isNaN(a) || Number.isNaN(b)) raise(TypeError, ERR.invalidNaN('TreeSet'));
         const aa = Object.is(a, -0) ? 0 : a;
         const bb = Object.is(b, -0) ? 0 : b;
         return aa > bb ? 1 : aa < bb ? -1 : 0;
@@ -87,11 +87,11 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
         const ta = a.getTime();
         const tb = b.getTime();
         /* istanbul ignore next -- _validateKey prevents invalid Date from entering the tree */
-        if (Number.isNaN(ta) || Number.isNaN(tb)) throw new TypeError(ERR.invalidDate('TreeSet'));
+        if (Number.isNaN(ta) || Number.isNaN(tb)) raise(TypeError, ERR.invalidDate('TreeSet'));
         return ta > tb ? 1 : ta < tb ? -1 : 0;
       }
 
-      throw new TypeError(ERR.comparatorRequired('TreeSet'));
+      raise(TypeError, ERR.comparatorRequired('TreeSet'));
     };
   }
 
@@ -226,6 +226,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -259,19 +294,19 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
     if (!this.#isDefaultComparator) return;
 
     if (typeof key === 'number') {
-      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN('TreeSet'));
+      if (Number.isNaN(key)) raise(TypeError, ERR.invalidNaN('TreeSet'));
       return;
     }
 
     if (typeof key === 'string') return;
 
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate('TreeSet'));
+      if (Number.isNaN(key.getTime())) raise(TypeError, ERR.invalidDate('TreeSet'));
       return;
     }
 
     // Other key types should have provided a comparator, so reaching here means misuse.
-    throw new TypeError(ERR.comparatorRequired('TreeSet'));
+    raise(TypeError, ERR.comparatorRequired('TreeSet'));
   }
 
   /**
@@ -402,6 +437,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -442,6 +512,42 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
     return this;
   }
 
+  /**
+   * Add multiple keys at once.
+   * @remarks Expected time O(m log n), where m is the number of keys.
+   * @param keys - Iterable of keys to add.
+   * @returns Array of booleans indicating whether each key was newly added.
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Add multiple keys
+ *  const ts = new TreeSet<number>();
+ *     ts.addMany([5, 3, 7, 1, 9]);
+ *     console.log(ts.size); // 5;
+   */
+  addMany(keys: Iterable<K>): boolean[] {
+    const results: boolean[] = [];
+    for (const key of keys) {
+      this._validateKey(key);
+      results.push(this.#core.set(key, undefined));
+    }
+    return results;
+  }
+
   /**
    * Test whether a key exists.
    * @remarks Expected time O(log n)
@@ -578,6 +684,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -769,25 +910,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Removing elements while maintaining order
- *  const nums = new TreeSet<number>([1, 3, 5, 7, 9]);
- *
- *     console.log(nums.delete(5)); // true;
- *     console.log(nums.delete(5)); // false; // already gone
- *     console.log([...nums]); // [1, 3, 7, 9];
-   */
-  delete(key: K): boolean {
-    this._validateKey(key);
-    const res = this.#core.delete(key);
-    return Array.isArray(res) && res.length > 0 && !!res[0]?.deleted;
-  }
-
-  /**
-   * Remove all keys.
-   
-   
-   
    
    
    
@@ -823,6 +945,39 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+    * @example
+ * // Removing elements while maintaining order
+ *  const nums = new TreeSet<number>([1, 3, 5, 7, 9]);
+ *
+ *     console.log(nums.delete(5)); // true;
+ *     console.log(nums.delete(5)); // false; // already gone
+ *     console.log([...nums]); // [1, 3, 7, 9];
+   */
+  delete(key: K): boolean {
+    this._validateKey(key);
+    return this.#core.delete(key);
+  }
+
+  /**
+   * Delete all keys matching a predicate.
+   * @remarks Time O(N), Space O(N)
+   * @param predicate - Function (key, index, set) → boolean; return true to delete.
+   * @returns True if at least one key was deleted.
+   */
+  deleteWhere(predicate: (key: K, index: number, set: this) => boolean): boolean {
+    let deleted = false;
+    let index = 0;
+    for (const key of this) {
+      if (predicate(key, index++, this)) {
+        this.delete(key);
+        deleted = true;
+      }
+    }
+    return deleted;
+  }
+
+  /**
+   * Remove all keys.
    
    
    
@@ -928,18 +1083,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Remove all
- *  const ts = new TreeSet<number>([1, 2]);
- *       ts.clear();
- *       console.log(ts.isEmpty()); // true;
-   */
-  clear(): void {
-    this.#core.clear();
-  }
-
-  /**
-   * Iterate over keys in ascending order.
    
    
    
@@ -1013,6 +1156,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+    * @example
+ * // Remove all
+ *  const ts = new TreeSet<number>([1, 2]);
+ *       ts.clear();
+ *       console.log(ts.isEmpty()); // true;
+   */
+  clear(): void {
+    this.#core.clear();
+  }
+
+  /**
+   * Iterate over keys in ascending order.
    
    
    
@@ -1083,19 +1238,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Get sorted keys
- *  const ts = new TreeSet<number>([30, 10, 20]);
- *       console.log([...ts.keys()]); // [10, 20, 30];
-   */
-  keys(): IterableIterator<K> {
-    return this.#core.keys();
-  }
-
-  /**
-   * Iterate over values in ascending order.
-   *
-   * Note: for Set-like containers, `values()` is the same as `keys()`.
    
    
    
@@ -1204,6 +1346,19 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+    * @example
+ * // Get sorted keys
+ *  const ts = new TreeSet<number>([30, 10, 20]);
+ *       console.log([...ts.keys()]); // [10, 20, 30];
+   */
+  keys(): IterableIterator<K> {
+    return this.#core.keys();
+  }
+
+  /**
+   * Iterate over values in ascending order.
+   *
+   * Note: for Set-like containers, `values()` is the same as `keys()`.
    
    
    
@@ -1239,19 +1394,6 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Get values (same as keys for Set)
- *  const ts = new TreeSet<number>([2, 1, 3]);
- *       console.log([...ts.values()]); // [1, 2, 3];
-   */
-  values(): IterableIterator<K> {
-    return this.keys();
-  }
-
-  /**
-   * Iterate over `[value, value]` pairs (native Set convention).
-   *
-   * Note: TreeSet stores only keys internally; `[k, k]` is created on-the-fly during iteration.
    
    
    
@@ -1396,22 +1538,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
     * @example
- * // Iterate entries
- *  const ts = new TreeSet<number>([3, 1, 2]);
- *       console.log([...ts.entries()].map(([k]) => k)); // [1, 2, 3];
+ * // Get values (same as keys for Set)
+ *  const ts = new TreeSet<number>([2, 1, 3]);
+ *       console.log([...ts.values()]); // [1, 2, 3];
    */
-  *entries(): IterableIterator<[K, K]> {
-    for (const k of this.keys()) yield [k, k];
-  }
-
-  [Symbol.iterator](): IterableIterator<K> {
+  values(): IterableIterator<K> {
     return this.keys();
   }
 
   /**
-   * Visit each value in ascending order.
+   * Iterate over `[value, value]` pairs (native Set convention).
    *
-   * Callback follows native Set convention: `(value, value2, set)`.
+   * Note: TreeSet stores only keys internally; `[k, k]` is created on-the-fly during iteration.
    
    
    
@@ -1555,18 +1693,248 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Execute for each
- *  const ts = new TreeSet<number>([3, 1, 2]);
- *       const keys: number[] = [];
- *       ts.forEach(k => keys.push(k));
- *       console.log(keys); // [1, 2, 3];
-   */
-  forEach(cb: (value: K, value2: K, set: TreeSet<K>) => void, thisArg?: unknown): void {
-    for (const k of this) cb.call(thisArg, k, k, this);
-  }
-
-  /**
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Iterate entries
+ *  const ts = new TreeSet<number>([3, 1, 2]);
+ *       console.log([...ts.entries()].map(([k]) => k)); // [1, 2, 3];
+   */
+  *entries(): IterableIterator<[K, K]> {
+    for (const k of this.keys()) yield [k, k];
+  }
+
+  [Symbol.iterator](): IterableIterator<K> {
+    return this.keys();
+  }
+
+  /**
+   * Visit each value in ascending order.
+   *
+   * Callback follows native Set convention: `(value, value2, set)`.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Execute for each
+ *  const ts = new TreeSet<number>([3, 1, 2]);
+ *       const keys: number[] = [];
+ *       ts.forEach(k => keys.push(k));
+ *       console.log(keys); // [1, 2, 3];
+   */
+  forEach(cb: (value: K, value2: K, set: TreeSet<K>) => void, thisArg?: unknown): void {
+    for (const k of this) cb.call(thisArg, k, k, this);
+  }
+
+  /**
    * Create a new TreeSet by mapping each value to a new key.
    *
    * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
@@ -1693,6 +2061,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1861,6 +2264,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2025,6 +2463,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2182,6 +2655,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2342,6 +2850,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2502,6 +3045,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2686,18 +3264,88 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
-    * @example
- * // Convert to array
- *  const ts = new TreeSet<number>([3, 1, 2]);
- *       console.log(ts.toArray()); // [1, 2, 3];
-   */
-  toArray(): K[] {
-    return [...this];
-  }
-
-  /**
-   * Print a human-friendly representation.
-   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Convert to array
+ *  const ts = new TreeSet<number>([3, 1, 2]);
+ *       console.log(ts.toArray()); // [1, 2, 3];
+   */
+  toArray(): K[] {
+    return [...this];
+  }
+
+  /**
+   * Print a human-friendly representation.
+   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2879,6 +3527,13 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2945,6 +3600,13 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2989,6 +3651,13 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3038,6 +3707,13 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3163,6 +3839,34 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3309,6 +4013,34 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3447,6 +4179,34 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3583,6 +4343,34 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3722,6 +4510,34 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3782,6 +4598,74 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
     return out;
   }
 
+  // ─── Order-Statistic Methods ───────────────────────────
+
+  /**
+   * Returns the element at the k-th position in tree order (0-indexed).
+   * @remarks Time O(log n). Requires `enableOrderStatistic: true`.
+   
+   
+   
+    * @example
+ * // Find k-th element in a TreeSet
+ *  const set = new TreeSet<number>([30, 10, 50, 20, 40], { enableOrderStatistic: true });
+ *       console.log(set.getByRank(0)); // 10;
+ *       console.log(set.getByRank(2)); // 30;
+ *       console.log(set.getRank(30)); // 2;
+   */
+  getByRank(k: number): K | undefined {
+    return this.#core.getByRank(k);
+  }
+
+  /**
+   * Returns the 0-based rank of a key (number of elements that precede it in tree order).
+   * @remarks Time O(log n). Requires `enableOrderStatistic: true`.
+    * @example
+ * // Get the rank of a key in sorted order
+ *  const tree = new TreeSet<number>(
+ *         [10, 20, 30, 40, 50],
+ *         { enableOrderStatistic: true }
+ *       );
+ *       console.log(tree.getRank(10)); // 0;  // smallest → rank 0
+ *       console.log(tree.getRank(30)); // 2;  // 2 elements before 30 in tree order
+ *       console.log(tree.getRank(50)); // 4;  // largest → rank 4
+ *       console.log(tree.getRank(25)); // 2;
+   */
+  getRank(key: K): number {
+    return this.#core.getRank(key);
+  }
+
+  /**
+   * Returns elements by rank range (0-indexed, inclusive on both ends).
+   * @remarks Time O(log n + k). Requires `enableOrderStatistic: true`.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Pagination by position in tree order
+ *  const tree = new TreeSet<number>(
+ *         [10, 20, 30, 40, 50, 60, 70, 80, 90],
+ *         { enableOrderStatistic: true }
+ *       );
+ *       const pageSize = 3;
+ *
+ *       // Page 1
+ *       console.log(tree.rangeByRank(0, pageSize - 1)); // [10, 20, 30];
+ *       // Page 2
+ *       console.log(tree.rangeByRank(pageSize, 2 * pageSize - 1)); // [40, 50, 60];
+ *       // Page 3
+ *       console.log(tree.rangeByRank(2 * pageSize, 3 * pageSize - 1)); // [70, 80, 90];
+   */
+  rangeByRank(start: number, end: number): K[] {
+    return this.#core.rangeByRank(start, end).filter((k): k is K => k !== undefined);
+  }
+
   /**
    * Creates a shallow clone of this set.
    * @remarks Time O(n log n), Space O(n)
@@ -3908,6 +4792,41 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+