max-priority-queue-typed 2.5.1 → 2.5.2

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'));
   }
 
   /**
@@ -264,6 +264,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -427,6 +442,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -611,6 +641,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -785,6 +830,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -959,6 +1019,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1123,6 +1198,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1278,6 +1368,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1440,6 +1545,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1596,6 +1716,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1756,6 +1891,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1915,6 +2065,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2083,6 +2248,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2247,6 +2427,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2403,6 +2598,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2563,6 +2773,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2724,6 +2949,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2886,6 +3126,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3041,6 +3296,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3100,6 +3370,9 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
    
    
    
@@ -3166,6 +3439,9 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
    
    
    
@@ -3216,6 +3492,9 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
    
    
    
@@ -3270,6 +3549,9 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
    
    
    
@@ -3405,6 +3687,18 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3567,6 +3861,18 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3713,6 +4019,18 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3859,6 +4177,18 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -4006,6 +4336,18 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -4070,6 +4412,74 @@ 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 with rangeByRank
+ *  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)
@@ -4201,6 +4611,21 @@ export class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | u
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+