graph-typed 2.5.2 → 2.6.0

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

@@ -12,7 +12,7 @@ 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.
@@ -212,6 +212,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -280,7 +287,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.
    
@@ -310,6 +317,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -369,6 +383,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -434,6 +455,9 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
    
    
    
@@ -465,7 +489,47 @@ 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()!;
@@ -507,6 +571,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -609,6 +680,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -658,6 +736,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -677,17 +762,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.
@@ -712,6 +787,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -761,6 +843,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -786,7 +875,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 {
@@ -797,14 +886,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)) {
@@ -814,7 +909,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 {
@@ -860,6 +955,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -945,6 +1047,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1000,6 +1109,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1054,6 +1170,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1115,6 +1238,13 @@ export class Heap<E = any, R = any> extends IterableElementBase<E, R> {
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1361,17 +1491,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/linked-list/doubly-linked-list.ts

@@ -295,6 +295,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -366,6 +373,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -436,6 +450,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -497,6 +518,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -591,6 +619,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -642,6 +677,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -732,6 +774,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -858,6 +907,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -916,6 +972,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -976,6 +1039,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1022,6 +1092,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1072,6 +1149,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1131,6 +1215,10 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
    
    
    
@@ -1139,13 +1227,36 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
     * @example
  * // Find value scanning from tail
  *  const list = new DoublyLinkedList<number>([1, 2, 3, 4]);
- *     // getBackward scans from tail to head, returns first match
- *     const found = list.getBackward(node => node.value < 4);
+ *     // findLast scans from tail to head, returns first match
+ *     const found = list.findLast(node => node.value < 4);
  *     console.log(found); // 3;
    */
 
+  /**
+   * @deprecated Use `findLast` instead. Will be removed in a future major version.
+   */
   getBackward(
     elementNodeOrPredicate: E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)
+  ): E | undefined {
+    return this.findLast(elementNodeOrPredicate);
+  }
+
+  /**
+   * Find the first value matching a predicate scanning backward (tail → head).
+   * @remarks Time O(N), Space O(1)
+   * @param elementNodeOrPredicate - Element, node, or predicate to match.
+   * @returns Matching value or undefined.
+   
+   
+    * @example
+ * // Find value scanning from tail
+ *  const list = new DoublyLinkedList<number>([1, 2, 3, 4]);
+ *     // findLast scans from tail to head, returns first match
+ *     const found = list.findLast(node => node.value < 4);
+ *     console.log(found); // 3;
+   */
+  findLast(
+    elementNodeOrPredicate: E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)
   ): E | undefined {
     const predicate = this._ensurePredicate(elementNodeOrPredicate);
     let current = this.tail;
@@ -1156,6 +1267,23 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
     return undefined;
   }
 
+  /**
+   * Find the index of the last value matching a predicate (scans tail → head).
+   * @remarks Provided for familiarity when migrating from Array. Time O(n), Space O(1).
+   * @param predicate - Function called with (value, index, list).
+   * @returns Matching index, or -1 if not found.
+   */
+  findLastIndex(predicate: (value: E, index: number, list: this) => boolean): number {
+    let current = this.tail;
+    let index = this.length - 1;
+    while (current) {
+      if (predicate(current.value, index, this)) return index;
+      current = current.prev;
+      index--;
+    }
+    return -1;
+  }
+
   /**
    * Reverse the list in place.
    * @remarks Time O(N), Space O(1)
@@ -1187,6 +1315,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1213,6 +1348,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)
@@ -1254,6 +1409,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1309,6 +1471,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+   
    
    
    
@@ -1385,6 +1554,13 @@ export class DoublyLinkedList<E = any, R = any> extends LinearLinkedBase<E, R, D
    
    
    
+   
+   
+   
+   
+   
+   
+