max-priority-queue-typed 2.5.1 → 2.5.3

package/src/data-structures/heap/heap.ts

@@ -8,11 +8,11 @@
 
 import type { Comparator, DFSOrderPattern, ElementCallback, HeapOptions } from '../../types';
 import { IterableElementBase } from '../base';
-import { ERR } from '../../common';
+import { ERR, raise } from '../../common';
 
 /**
  * Binary heap with pluggable comparator; supports fast insertion and removal of the top element.
- * @remarks Time O(1), Space O(1)
+ * @remarks Typical operations: O(log N) insert/remove, O(1) peek. Space O(N).
  * @template E
  * @template R
  * 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
@@ -209,6 +209,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -277,7 +284,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
 
   /**
    * Insert an element.
-   * @remarks Time O(1) amortized, Space O(1)
+   * @remarks Time O(log N) amortized, Space O(1)
    * @param element - Element to insert.
    * @returns True.
    
@@ -304,6 +311,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -360,6 +374,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -419,6 +440,12 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
    
    
    
@@ -453,7 +480,44 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
  *     console.log(topTask?.name); // 'Alert';
    */
 
+  /**
+   * @deprecated Use `pop` instead. Will be removed in a future major version.
+    * @example
+ * // Heap with custom comparator (MaxHeap behavior)
+ *  interface Task {
+ *       id: number;
+ *       priority: number;
+ *       name: string;
+ *     }
+ *
+ *     // Custom comparator for max heap behavior (higher priority first)
+ *     const tasks: Task[] = [
+ *       { id: 1, priority: 5, name: 'Email' },
+ *       { id: 2, priority: 3, name: 'Chat' },
+ *       { id: 3, priority: 8, name: 'Alert' }
+ *     ];
+ *
+ *     const maxHeap = new Heap(tasks, {
+ *       comparator: (a: Task, b: Task) => b.priority - a.priority
+ *     });
+ *
+ *     console.log(maxHeap.size); // 3;
+ *
+ *     // Peek returns highest priority task
+ *     const topTask = maxHeap.peek();
+ *     console.log(topTask?.priority); // 8;
+ *     console.log(topTask?.name); // 'Alert';
+   */
   poll(): E | undefined {
+    return this.pop();
+  }
+
+  /**
+   * Remove and return the top element (min or max depending on comparator).
+   * @remarks Time O(log N) amortized, Space O(1)
+   * @returns The removed top element, or undefined if empty.
+   */
+  pop(): E | undefined {
     if (this.elements.length === 0) return;
     const value = this.elements[0];
     const last = this.elements.pop()!;
@@ -492,6 +556,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -591,6 +662,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -637,6 +715,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -656,17 +741,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
     this._elements = [];
   }
 
-  /**
-   * Replace the backing array and rebuild the heap.
-   * @remarks Time O(N), Space O(N)
-   * @param elements - Iterable used to refill the heap.
-   * @returns Array of per-node results from fixing steps.
-   */
 
-  refill(elements: Iterable<E>): boolean[] {
-    this._elements = Array.from(elements);
-    return this.fix();
-  }
 
   /**
    * Check if an equal element exists in the heap.
@@ -688,6 +763,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -734,6 +816,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -759,7 +848,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
     }
     if (index < 0) return false;
     if (index === 0) {
-      this.poll();
+      this.pop();
     } else if (index === this.elements.length - 1) {
       this.elements.pop();
     } else {
@@ -770,14 +859,20 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
     return true;
   }
 
+  /**
+   * @deprecated Use `deleteWhere` instead. Will be removed in a future major version.
+   */
+  deleteBy(predicate: (element: E, index: number, heap: this) => boolean): boolean {
+    return this.deleteWhere(predicate);
+  }
+
   /**
    * Delete the first element that matches a predicate.
    * @remarks Time O(N), Space O(1)
    * @param predicate - Function (element, index, heap) → boolean.
    * @returns True if an element was removed.
    */
-
-  deleteBy(predicate: (element: E, index: number, heap: this) => boolean): boolean {
+  deleteWhere(predicate: (element: E, index: number, heap: this) => boolean): boolean {
     let idx = -1;
     for (let i = 0; i < this.elements.length; i++) {
       if (predicate(this.elements[i], i, this)) {
@@ -787,7 +882,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
     }
     if (idx < 0) return false;
     if (idx === 0) {
-      this.poll();
+      this.pop();
     } else if (idx === this.elements.length - 1) {
       this.elements.pop();
     } else {
@@ -830,6 +925,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -912,6 +1014,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -964,6 +1073,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1015,6 +1131,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1073,6 +1196,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1094,7 +1224,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
     thisArg?: unknown
   ): Heap<EM, RM> {
     const { comparator, toElementFn, ...rest } = options ?? {};
-    if (!comparator) throw new TypeError(ERR.comparatorRequired('Heap.map'));
+    if (!comparator) raise(TypeError, ERR.comparatorRequired('Heap.map'));
     const out = this._createLike<EM, RM>([], { ...rest, comparator, toElementFn });
     let i = 0;
     for (const x of this) {
@@ -1124,7 +1254,7 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
 
   protected readonly _DEFAULT_COMPARATOR: Comparator<E> = (a: E, b: E): number => {
     if (typeof a === 'object' || typeof b === 'object') {
-      throw new TypeError(ERR.comparatorRequired('Heap'));
+      raise(TypeError, ERR.comparatorRequired('Heap'));
     }
     if (a > b) return 1;
     if (a < b) return -1;
@@ -1266,7 +1396,7 @@ export class FibonacciHeap<E> {
   constructor(comparator?: Comparator<E>) {
     this.clear();
     this._comparator = comparator || this._defaultComparator;
-    if (typeof this.comparator !== 'function') throw new TypeError(ERR.notAFunction('comparator', 'FibonacciHeap'));
+    if (typeof this.comparator !== 'function') raise(TypeError, ERR.notAFunction('comparator', 'FibonacciHeap'));
   }
 
   protected _root?: FibonacciHeapNode<E>;
@@ -1319,17 +1449,17 @@ export class FibonacciHeap<E> {
    * Push an element into the root list.
    * @remarks Time O(1) amortized, Space O(1)
    * @param element - Element to insert.
-   * @returns This heap.
+   * @returns True when the element is added.
    */
 
-  push(element: E): this {
+  push(element: E): boolean {
     const node = this.createNode(element);
     node.left = node;
     node.right = node;
     this.mergeWithRoot(node);
     if (!this.min || this.comparator(node.element, this.min.element) <= 0) this._min = node;
     this._size++;
-    return this;
+    return true;
   }
 
   peek(): E | undefined {

package/src/data-structures/heap/max-heap.ts

@@ -6,7 +6,7 @@
  */
 import type { HeapOptions } from '../../types';
 import { Heap } from './heap';
-import { ERR } from '../../common';
+import { ERR, raise } from '../../common';
 
 /**
  * @template E
@@ -80,7 +80,7 @@ export class MaxHeap<E = any, R = any> extends Heap<E, R> {
     super(elements, {
       comparator: (a: E, b: E): number => {
         if (typeof a === 'object' || typeof b === 'object') {
-          throw new TypeError(ERR.comparatorRequired('MaxHeap'));
+          raise(TypeError, ERR.comparatorRequired('MaxHeap'));
         }
         if (a < b) return 1;
         if (a > b) return -1;

package/src/data-structures/linked-list/doubly-linked-list.ts

@@ -292,6 +292,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -360,6 +367,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -427,6 +441,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -485,6 +506,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -576,6 +604,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -624,6 +659,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -711,6 +753,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -834,6 +883,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -889,6 +945,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -946,6 +1009,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -989,6 +1059,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1036,6 +1113,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1089,6 +1173,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1145,6 +1236,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1171,6 +1269,26 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
     return this;
   }
 
+  /**
+   * Delete the first element that satisfies a predicate.
+   * @remarks Time O(N), Space O(1)
+   * @param predicate - Function (value, index, list) → boolean to decide deletion.
+   * @returns True if a match was removed.
+   */
+  deleteWhere(predicate: (value: E, index: number, list: this) => boolean): boolean {
+    let current = this.head;
+    let index = 0;
+    while (current) {
+      if (predicate(current.value, index, this)) {
+        this.delete(current);
+        return true;
+      }
+      current = current.next;
+      index++;
+    }
+    return false;
+  }
+
   /**
    * Set the equality comparator used to compare values.
    * @remarks Time O(1), Space O(1)
@@ -1209,6 +1327,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1261,6 +1386,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1334,6 +1466,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+