max-priority-queue-typed 2.5.1 → 2.5.2

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'));
     };
   }
 
@@ -231,6 +231,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -259,19 +274,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'));
   }
 
   /**
@@ -407,6 +422,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -583,6 +613,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -753,6 +798,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -912,6 +972,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1067,6 +1142,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1223,6 +1313,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1379,6 +1484,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1539,6 +1659,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1698,6 +1833,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1866,6 +2016,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2030,6 +2195,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2187,6 +2367,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2347,6 +2542,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2507,6 +2717,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2670,6 +2895,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2825,6 +3065,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -2883,6 +3138,9 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
    
    
    
@@ -2949,6 +3207,9 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
    
    
    
@@ -2993,6 +3254,9 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
    
    
    
@@ -3042,6 +3306,9 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
    
    
    
@@ -3171,6 +3438,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3317,6 +3596,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3455,6 +3746,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3591,6 +3894,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3730,6 +4045,18 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -3782,6 +4109,66 @@ 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 with rangeByRank
+ *  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)
@@ -3913,6 +4300,21 @@ export class TreeSet<K = any, R = K> implements Iterable<K> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
    
    
    

package/src/data-structures/graph/abstract-graph.ts

@@ -8,7 +8,7 @@
 
 import type { DijkstraResult, EntryCallback, GraphOptions, VertexKey } from '../../types';
 import { uuidV4 } from '../../utils';
-import { ERR } from '../../common';
+import { ERR, raise } from '../../common';
 import { IterableEntryBase } from '../base';
 import { IGraph } from '../../interfaces';
 import { Heap } from '../heap';
@@ -275,7 +275,7 @@ export abstract class AbstractGraph<
         const newEdge = this.createEdge(srcOrEdge, dest, weight, value);
         return this._addEdge(newEdge);
       } else {
-        throw new TypeError(ERR.invalidArgument('dest must be a Vertex or vertex key when srcOrEdge is an Edge.', 'Graph'));
+        raise(TypeError, ERR.invalidArgument('dest must be a Vertex or vertex key when srcOrEdge is an Edge.', 'Graph'));
       }
     }
   }