binary-tree-typed 2.5.1 → 2.5.3

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

@@ -10,7 +10,7 @@
 import type { Comparator } from '../../types';
 import type { TreeMapEntryCallback, TreeMapOptions, TreeMapRangeOptions, TreeMapReduceCallback } from '../../types';
 import { RedBlackTree } from './red-black-tree';
-import { ERR } from '../../common';
+import { ERR, raise } from '../../common';
 
 /**
  * An ordered Map backed by a red-black tree.
@@ -52,7 +52,7 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
     const comparator = options.comparator ?? TreeMap.createDefaultComparator<K>();
     this.#isDefaultComparator = options.comparator === undefined;
 
-    this.#core = new RedBlackTree<K, V>([], { comparator, isMapMode: options.isMapMode });
+    this.#core = new RedBlackTree<K, V>([], { comparator, isMapMode: options.isMapMode, enableOrderStatistic: options.enableOrderStatistic });
 
     for (const item of entries) {
       let k: K;
@@ -64,7 +64,7 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
       } else {
         // Validate entries like native Map: each item must be a 2-tuple-like value.
         if (!Array.isArray(item) || item.length < 2) {
-          throw new TypeError(ERR.invalidEntry('TreeMap'));
+          raise(TypeError, ERR.invalidEntry('TreeMap'));
         }
         k = item[0] as K;
         v = item[1] as V | undefined;
@@ -88,7 +88,7 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
     return (a: K, b: K): number => {
       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('TreeMap'));
+        if (Number.isNaN(a) || Number.isNaN(b)) raise(TypeError, ERR.invalidNaN('TreeMap'));
         const aa = Object.is(a, -0) ? 0 : a;
         const bb = Object.is(b, -0) ? 0 : b;
         return aa > bb ? 1 : aa < bb ? -1 : 0;
@@ -102,11 +102,11 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
         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('TreeMap'));
+        if (Number.isNaN(ta) || Number.isNaN(tb)) raise(TypeError, ERR.invalidDate('TreeMap'));
         return ta > tb ? 1 : ta < tb ? -1 : 0;
       }
 
-      throw new TypeError(ERR.comparatorRequired('TreeMap'));
+      raise(TypeError, ERR.comparatorRequired('TreeMap'));
     };
   }
 
@@ -114,18 +114,18 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
     if (!this.#isDefaultComparator) return;
 
     if (typeof key === 'number') {
-      if (Number.isNaN(key)) throw new TypeError(ERR.invalidNaN('TreeMap'));
+      if (Number.isNaN(key)) raise(TypeError, ERR.invalidNaN('TreeMap'));
       return;
     }
 
     if (typeof key === 'string') return;
 
     if (key instanceof Date) {
-      if (Number.isNaN(key.getTime())) throw new TypeError(ERR.invalidDate('TreeMap'));
+      if (Number.isNaN(key.getTime())) raise(TypeError, ERR.invalidDate('TreeMap'));
       return;
     }
 
-    throw new TypeError(ERR.comparatorRequired('TreeMap'));
+    raise(TypeError, ERR.comparatorRequired('TreeMap'));
   }
 
   /**
@@ -259,6 +259,41 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -422,6 +457,41 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -471,8 +541,11 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
   }
 
   /**
-   * Get the value under a key.
-   * @remarks Expected time O(log n)
+   * Set multiple key-value pairs at once.
+   * @remarks Expected time O(m log n), where m is the number of entries.
+   * @param entries - Iterable of `[key, value]` tuples.
+   * @returns Array of booleans indicating whether each entry was successfully set.
+  
    
    
    
@@ -488,6 +561,24 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Set multiple key-value pairs
+ *  const tm = new TreeMap<number, string>();
+ *     tm.setMany([[1, 'a'], [2, 'b'], [3, 'c']]);
+ *     console.log(tm.size); // 3;
+   */
+  setMany(entries: Iterable<[K, V | undefined]>): boolean[] {
+    const results: boolean[] = [];
+    for (const [key, value] of entries) {
+      this._validateKey(key);
+      results.push(this.#core.set(key, value as V));
+    }
+    return results;
+  }
+
+  /**
+   * Get the value under a key.
+   * @remarks Expected time O(log n)
    
    
    
@@ -627,26 +718,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Configuration registry with typed lookups
- *  const config = new TreeMap<string, number>([
- *       ['maxRetries', 3],
- *       ['timeout', 5000],
- *       ['poolSize', 10]
- *     ]);
- *
- *     console.log(config.get('timeout')); // 5000;
- *     console.log(config.get('missing')); // undefined;
- *     console.log(config.size); // 3;
-   */
-  get(key: K): V | undefined {
-    this._validateKey(key);
-    return this.#core.get(key);
-  }
-
-  /**
-   * Test whether a key exists.
-   * @remarks Expected time O(log n)
    
    
    
@@ -697,6 +768,33 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Configuration registry with typed lookups
+ *  const config = new TreeMap<string, number>([
+ *       ['maxRetries', 3],
+ *       ['timeout', 5000],
+ *       ['poolSize', 10]
+ *     ]);
+ *
+ *     console.log(config.get('timeout')); // 5000;
+ *     console.log(config.get('missing')); // undefined;
+ *     console.log(config.size); // 3;
+   */
+  get(key: K): V | undefined {
+    this._validateKey(key);
+    return this.#core.get(key);
+  }
+
+  /**
+   * Test whether a key exists.
+   * @remarks Expected time O(log n)
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -801,26 +899,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Feature flag checking
- *  const flags = new TreeMap<string, boolean>([
- *       ['darkMode', true],
- *       ['betaFeature', false],
- *       ['notifications', true]
- *     ]);
- *
- *     console.log(flags.has('darkMode')); // true;
- *     console.log(flags.has('unknownFlag')); // false;
-   */
-  has(key: K): boolean {
-    this._validateKey(key);
-    return this.#core.has(key);
-  }
-
-  /**
-   * Delete a key.
-   * @returns `true` if the key existed; otherwise `false`.
-   * @remarks Expected time O(log n)
    
    
    
@@ -899,6 +977,27 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Feature flag checking
+ *  const flags = new TreeMap<string, boolean>([
+ *       ['darkMode', true],
+ *       ['betaFeature', false],
+ *       ['notifications', true]
+ *     ]);
+ *
+ *     console.log(flags.has('darkMode')); // true;
+ *     console.log(flags.has('unknownFlag')); // false;
+   */
+  has(key: K): boolean {
+    this._validateKey(key);
+    return this.#core.has(key);
+  }
+
+  /**
+   * Delete a key.
+   * @returns `true` if the key existed; otherwise `false`.
+   * @remarks Expected time O(log n)
+   
    
    
    
@@ -975,27 +1074,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Session management with expiry
- *  const sessions = new TreeMap<string, number>([
- *       ['sess_abc', Date.now()],
- *       ['sess_def', Date.now()],
- *       ['sess_ghi', Date.now()]
- *     ]);
- *
- *     console.log(sessions.size); // 3;
- *     sessions.delete('sess_def');
- *     console.log(sessions.has('sess_def')); // false;
- *     console.log(sessions.size); // 2;
-   */
-  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 entries.
    
    
    
@@ -1108,6 +1186,48 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Session management with expiry
+ *  const sessions = new TreeMap<string, number>([
+ *       ['sess_abc', Date.now()],
+ *       ['sess_def', Date.now()],
+ *       ['sess_ghi', Date.now()]
+ *     ]);
+ *
+ *     console.log(sessions.size); // 3;
+ *     sessions.delete('sess_def');
+ *     console.log(sessions.has('sess_def')); // false;
+ *     console.log(sessions.size); // 2;
+   */
+  delete(key: K): boolean {
+    this._validateKey(key);
+    return this.#core.delete(key);
+  }
+
+  /**
+   * Delete all entries matching a predicate.
+   * @remarks Time O(N), Space O(N)
+   * @param predicate - Function (key, value, index, map) → boolean; return true to delete.
+   * @returns True if at least one entry was deleted.
+   */
+  deleteWhere(predicate: (key: K, value: V | undefined, index: number, map: this) => boolean): boolean {
+    let deleted = false;
+    let index = 0;
+    for (const [key, value] of this) {
+      if (predicate(key, value, index++, this)) {
+        this.delete(key);
+        deleted = true;
+      }
+    }
+    return deleted;
+  }
+
+  /**
+   * Remove all entries.
+   
+   
+   
+   
    
    
    
@@ -1139,18 +1259,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Remove all
- *  const tm = new TreeMap<number, string>([[1, 'a']]);
- *       tm.clear();
- *       console.log(tm.isEmpty()); // true;
-   */
-  clear(): void {
-    this.#core.clear();
-  }
-
-  /**
-   * Iterate over keys in ascending order.
    
    
    
@@ -1295,24 +1403,17 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
     * @example
- * // Get sorted keys
- *  const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a']]);
- *       console.log([...tm.keys()]); // [1, 3];
+ * // Remove all
+ *  const tm = new TreeMap<number, string>([[1, 'a']]);
+ *       tm.clear();
+ *       console.log(tm.isEmpty()); // true;
    */
-  keys(): IterableIterator<K> {
-    return this.#core.keys();
-  }
-
-  private _entryFromKey(k: K): [K, V | undefined] {
-    // Keys come from `keys()` which only yields existing keys.
-    // We allow `undefined` as a stored value (native Map behavior), so entries are typed as `[K, V | undefined]`.
-    return [k, this.#core.get(k)];
+  clear(): void {
+    this.#core.clear();
   }
 
   /**
-   * Iterate over values in ascending key order.
-   *
-   * Note: values may be `undefined` (TreeMap allows storing `undefined`, like native `Map`).
+   * Iterate over keys in ascending order.
    
    
    
@@ -1456,22 +1557,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Get values in key order
- *  const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
- *       console.log([...tm.values()]); // ['a', 'b'];
-   */
-  *values(): IterableIterator<V | undefined> {
-    for (const k of this.keys()) yield this._entryFromKey(k)[1];
-  }
-
-  /**
-   * Iterate over `[key, value]` entries in ascending key order.
-   *
-   * Note: values may be `undefined`.
-   
-   
-   
    
    
    
@@ -1507,6 +1592,25 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Get sorted keys
+ *  const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a']]);
+ *       console.log([...tm.keys()]); // [1, 3];
+   */
+  keys(): IterableIterator<K> {
+    return this.#core.keys();
+  }
+
+  private _entryFromKey(k: K): [K, V | undefined] {
+    // Keys come from `keys()` which only yields existing keys.
+    // We allow `undefined` as a stored value (native Map behavior), so entries are typed as `[K, V | undefined]`.
+    return [k, this.#core.get(k)];
+  }
+
+  /**
+   * Iterate over values in ascending key order.
+   *
+   * Note: values may be `undefined` (TreeMap allows storing `undefined`, like native `Map`).
    
    
    
@@ -1612,23 +1716,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Iterate key-value pairs
- *  const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a'], [2, 'b']]);
- *       console.log([...tm.entries()]); // [[1, 'a'], [2, 'b'], [3, 'c']];
-   */
-  *entries(): IterableIterator<[K, V | undefined]> {
-    for (const k of this.keys()) yield this._entryFromKey(k);
-  }
-
-  [Symbol.iterator](): IterableIterator<[K, V | undefined]> {
-    return this.entries();
-  }
-
-  /**
-   * Visit each entry in ascending key order.
-   *
-   * Note: callback value may be `undefined`.
    
    
    
@@ -1702,6 +1789,19 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Get values in key order
+ *  const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
+ *       console.log([...tm.values()]); // ['a', 'b'];
+   */
+  *values(): IterableIterator<V | undefined> {
+    for (const k of this.keys()) yield this._entryFromKey(k)[1];
+  }
+
+  /**
+   * Iterate over `[key, value]` entries in ascending key order.
+   *
+   * Note: values may be `undefined`.
    
    
    
@@ -1772,22 +1872,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Execute for each entry
- *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
- *       const pairs: string[] = [];
- *       tm.forEach((v, k) => pairs.push(`${k}:${v}`));
- *       console.log(pairs); // ['1:a', '2:b'];
-   */
-  forEach(cb: (value: V | undefined, key: K, map: TreeMap<K, V>) => void, thisArg?: unknown): void {
-    for (const [k, v] of this) cb.call(thisArg, v, k, this);
-  }
-
-  /**
-   * Create a new TreeMap by mapping each entry to a new `[key, value]` entry.
-   *
-   * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
-   * @remarks Time O(n log n) expected, Space O(n)
    
    
    
@@ -1896,6 +1980,23 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Iterate key-value pairs
+ *  const tm = new TreeMap<number, string>([[3, 'c'], [1, 'a'], [2, 'b']]);
+ *       console.log([...tm.entries()]); // [[1, 'a'], [2, 'b'], [3, 'c']];
+   */
+  *entries(): IterableIterator<[K, V | undefined]> {
+    for (const k of this.keys()) yield this._entryFromKey(k);
+  }
+
+  [Symbol.iterator](): IterableIterator<[K, V | undefined]> {
+    return this.entries();
+  }
+
+  /**
+   * Visit each entry in ascending key order.
+   *
+   * Note: callback value may be `undefined`.
    
    
    
@@ -1931,31 +2032,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Transform entries
- *  const tm = new TreeMap<number, number>([[1, 10], [2, 20]]);
- *       const doubled = tm.map((v, k) => [k, (v ?? 0) * 2] as [number, number]);
- *       console.log([...doubled.values()]); // [20, 40];
-   */
-  map<MK, MV>(
-    callbackfn: TreeMapEntryCallback<K, V, [MK, MV], TreeMap<K, V>>,
-    options: Omit<TreeMapOptions<MK, MV>, 'toEntryFn'> & { comparator?: (a: MK, b: MK) => number } = {},
-    thisArg?: unknown
-  ): TreeMap<MK, MV> {
-    const out = new TreeMap<MK, MV>([], options as TreeMapOptions<MK, MV>);
-    let index = 0;
-    for (const [k, v] of this) {
-      const [mk, mv] = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => [MK, MV]).call(thisArg, v, k, index++, this);
-      out.set(mk, mv);
-    }
-    return out;
-  }
-
-  /**
-   * Create a new TreeMap containing only entries that satisfy the predicate.
-   * @remarks Time O(n log n) expected, Space O(n)
    
    
    
@@ -2100,33 +2176,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
     * @example
- * // Filter entries
- *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b'], [3, 'c']]);
- *       const filtered = tm.filter((v, k) => k > 1);
- *       console.log([...filtered.keys()]); // [2, 3];
+ * // Execute for each entry
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       const pairs: string[] = [];
+ *       tm.forEach((v, k) => pairs.push(`${k}:${v}`));
+ *       console.log(pairs); // ['1:a', '2:b'];
    */
-  filter(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): TreeMap<K, V> {
-    const out = new TreeMap<K, V>([], { comparator: this.#userComparator });
-    let index = 0;
-    for (const [k, v] of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
-      if (ok) out.set(k, v);
-    }
-    return out;
+  forEach(cb: (value: V | undefined, key: K, map: TreeMap<K, V>) => void, thisArg?: unknown): void {
+    for (const [k, v] of this) cb.call(thisArg, v, k, this);
   }
 
   /**
-   * Reduce entries into a single accumulator.
-   * @remarks Time O(n), Space O(1)
-   
-   
-   
-   
-   
-   
-   
+   * Create a new TreeMap by mapping each entry to a new `[key, value]` entry.
+   *
+   * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
+   * @remarks Time O(n log n) expected, Space O(n)
    
    
    
@@ -2263,21 +2327,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Aggregate values
- *  const tm = new TreeMap<number, number>([[1, 10], [2, 20]]);
- *       console.log(tm.reduce((acc, v) => acc + (v ?? 0), 0)); // 30;
-   */
-  reduce<A>(callbackfn: TreeMapReduceCallback<K, V, A, TreeMap<K, V>>, initialValue: A): A {
-    let acc = initialValue;
-    let index = 0;
-    for (const [k, v] of this) acc = callbackfn(acc, v, k, index++, this);
-    return acc;
-  }
-
-  /**
-   * Test whether all entries satisfy a predicate.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -2320,6 +2369,31 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Transform entries
+ *  const tm = new TreeMap<number, number>([[1, 10], [2, 20]]);
+ *       const doubled = tm.map((v, k) => [k, (v ?? 0) * 2] as [number, number]);
+ *       console.log([...doubled.values()]); // [20, 40];
+   */
+  map<MK, MV>(
+    callbackfn: TreeMapEntryCallback<K, V, [MK, MV], TreeMap<K, V>>,
+    options: Omit<TreeMapOptions<MK, MV>, 'toEntryFn'> & { comparator?: (a: MK, b: MK) => number } = {},
+    thisArg?: unknown
+  ): TreeMap<MK, MV> {
+    const out = new TreeMap<MK, MV>([], options as TreeMapOptions<MK, MV>);
+    let index = 0;
+    for (const [k, v] of this) {
+      const [mk, mv] = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => [MK, MV]).call(thisArg, v, k, index++, this);
+      out.set(mk, mv);
+    }
+    return out;
+  }
+
+  /**
+   * Create a new TreeMap containing only entries that satisfy the predicate.
+   * @remarks Time O(n log n) expected, Space O(n)
    
    
    
@@ -2419,25 +2493,6 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Test all entries
- *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
- *       console.log(tm.every((v, k) => k > 0)); // true;
-   */
-  every(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean {
-    let index = 0;
-    for (const [k, v] of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
-      if (!ok) return false;
-    }
-    return true;
-  }
-
-  /**
-   * Test whether any entry satisfies a predicate.
-   * @remarks Time O(n), Space O(1)
    
    
    
@@ -2517,6 +2572,27 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+    * @example
+ * // Filter entries
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b'], [3, 'c']]);
+ *       const filtered = tm.filter((v, k) => k > 1);
+ *       console.log([...filtered.keys()]); // [2, 3];
+   */
+  filter(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): TreeMap<K, V> {
+    const out = new TreeMap<K, V>([], { comparator: this.#userComparator });
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
+      if (ok) out.set(k, v);
+    }
+    return out;
+  }
+
+  /**
+   * Reduce entries into a single accumulator.
+   * @remarks Time O(n), Space O(1)
    
    
    
@@ -2579,26 +2655,563 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Test any entry
- *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
- *       console.log(tm.some((v, k) => k === 2)); // true;
-   */
-  some(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean {
-    let index = 0;
-    for (const [k, v] of this) {
-      const ok = thisArg === undefined
-        ? callbackfn(v, k, index++, this)
-        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
-      if (ok) return true;
-    }
-    return false;
-  }
-
-  /**
-   * Find the first entry that satisfies a predicate.
-   * @returns The first matching `[key, value]` tuple, or `undefined`.
-   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Aggregate values
+ *  const tm = new TreeMap<number, number>([[1, 10], [2, 20]]);
+ *       console.log(tm.reduce((acc, v) => acc + (v ?? 0), 0)); // 30;
+   */
+  reduce<A>(callbackfn: TreeMapReduceCallback<K, V, A, TreeMap<K, V>>, initialValue: A): A {
+    let acc = initialValue;
+    let index = 0;
+    for (const [k, v] of this) acc = callbackfn(acc, v, k, index++, this);
+    return acc;
+  }
+
+  /**
+   * Test whether all entries satisfy a predicate.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Test all entries
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       console.log(tm.every((v, k) => k > 0)); // true;
+   */
+  every(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean {
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
+      if (!ok) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Test whether any entry satisfies a predicate.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Test any entry
+ *  const tm = new TreeMap<number, string>([[1, 'a'], [2, 'b']]);
+ *       console.log(tm.some((v, k) => k === 2)); // true;
+   */
+  some(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean {
+    let index = 0;
+    for (const [k, v] of this) {
+      const ok = thisArg === undefined
+        ? callbackfn(v, k, index++, this)
+        : (callbackfn as (this: unknown, v: V | undefined, k: K, i: number, self: TreeMap<K, V>) => boolean).call(thisArg, v, k, index++, this);
+      if (ok) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Find the first entry that satisfies a predicate.
+   * @returns The first matching `[key, value]` tuple, or `undefined`.
+   * @remarks Time O(n), Space O(1)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2902,18 +3515,88 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
-    * @example
- * // Convert to array
- *  const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
- *       console.log(tm.toArray()); // [[1, 'a'], [2, 'b']];
-   */
-  toArray(): Array<[K, V | undefined]> {
-    return [...this];
-  }
-
-  /**
-   * Print a human-friendly representation.
-   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Convert to array
+ *  const tm = new TreeMap<number, string>([[2, 'b'], [1, 'a']]);
+ *       console.log(tm.toArray()); // [[1, 'a'], [2, 'b']];
+   */
+  toArray(): Array<[K, V | undefined]> {
+    return [...this];
+  }
+
+  /**
+   * Print a human-friendly representation.
+   * @remarks Time O(n), Space O(n)
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3096,6 +3779,13 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3162,6 +3852,13 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3212,6 +3909,13 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3266,6 +3970,13 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3397,6 +4108,34 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3559,6 +4298,34 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3705,6 +4472,34 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3851,6 +4646,34 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3998,6 +4821,34 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -4070,6 +4921,82 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
     return out;
   }
 
+  // ─── Order-Statistic Methods ───────────────────────────
+
+  /**
+   * Returns the entry at the k-th position in tree order (0-indexed).
+   * @remarks Time O(log n). Requires `enableOrderStatistic: true`.
+   
+   
+   
+    * @example
+ * // Find k-th entry in a TreeMap
+ *  const map = new TreeMap<string, number>(
+ *         [['alice', 95], ['bob', 87], ['charlie', 92]],
+ *         { enableOrderStatistic: true }
+ *       );
+ *       console.log(map.getByRank(0)); // 'alice';
+ *       console.log(map.getByRank(1)); // 'bob';
+ *       console.log(map.getByRank(2)); // 'charlie';
+   */
+  getByRank(k: number): [K, V | undefined] | undefined {
+    const key = this.#core.getByRank(k);
+    if (key === undefined) return undefined;
+    return [key, this.#core.get(key)];
+  }
+
+  /**
+   * 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 TreeMap<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 keys 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 TreeMap<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): Array<[K, V | undefined]> {
+    const keys = this.#core.rangeByRank(start, end);
+    return keys
+      .filter((k): k is K => k !== undefined)
+      .map(k => [k, this.#core.get(k)] as [K, V | undefined]);
+  }
+
   /**
    * Creates a shallow clone of this map.
    * @remarks Time O(n log n), Space O(n)
@@ -4196,6 +5123,41 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+