@procedures/collections 0.0.0-stage → 0.2.0

package/src/impl/priority-queue.ts

@@ -0,0 +1,448 @@
+/**
+ * PriorityQueue implementation - A binary heap-based priority queue.
+ *
+ * Elements are ordered according to their natural ordering (via comparator).
+ * The head of the queue is the least element according to the comparator.
+ * Provides O(log n) enqueue and O(log n) dequeue operations.
+ * Mirrors java.util.PriorityQueue.
+ *
+ * @example
+ * const pq = priorityQueue<number>((a, b) => a - b) // Min heap
+ * pq.offer(5)
+ * pq.offer(2)
+ * pq.offer(8)
+ * pq.poll() // 2 (smallest element)
+ */
+
+import type { PriorityQueue as IPriorityQueue } from "../interfaces/queue.js";
+import type { Eq, Compare } from "../core/traits.js";
+import { defaultEq, defaultCompare } from "../utils/defaults.js";
+
+/**
+ * Options for creating a PriorityQueue.
+ */
+export interface PriorityQueueOptions<T> {
+  /**
+   * Initial capacity of the heap.
+   * @default 11
+   */
+  initialCapacity?: number;
+
+  /**
+   * Comparator for ordering elements.
+   * Lower values have higher priority (min heap).
+   * @default defaultCompare
+   */
+  compare?: Compare<T>;
+
+  /**
+   * Equality function for elements.
+   * @default defaultEq
+   */
+  eq?: Eq<T>;
+}
+
+/**
+ * PriorityQueue<T> - Binary heap implementation of priority queue.
+ *
+ * Elements are always retrieved in priority order (according to comparator).
+ * Not a FIFO queue - order depends on priority, not insertion order.
+ *
+ * The heap is a min heap by default (smallest element has highest priority).
+ * For max heap, use reversed comparator: (a, b) => compare(b, a)
+ *
+ * Not thread-safe. Use synchronized() behavior for concurrent access.
+ */
+export class PriorityQueue<T> implements IPriorityQueue<T> {
+  private _heap: T[];
+  private readonly _compare: Compare<T>;
+  private readonly _eq: Eq<T>;
+
+  constructor(options: PriorityQueueOptions<T> = {}) {
+    const {
+      compare = defaultCompare,
+      eq = defaultEq,
+    } = options;
+
+    // The heap starts empty: a JavaScript array grows by itself, so initialCapacity is only a
+    // hint. (Before, `new Array(initialCapacity)` made 11 holes: an empty queue had size 11,
+    // and the heap compared holes. BUGS-2026-07 C9.)
+    this._heap = [];
+    this._compare = compare;
+    this._eq = eq;
+  }
+
+  // ========================================================================
+  // Size
+  // ========================================================================
+
+  get size(): number {
+    return this._heap.length;
+  }
+
+  get isEmpty(): boolean {
+    return this._heap.length === 0;
+  }
+
+  get eq(): Eq<T> {
+    return this._eq;
+  }
+
+  get compare(): Compare<T> {
+    return this._compare;
+  }
+
+  get comparator(): Compare<T> {
+    return this._compare;
+  }
+
+  // ========================================================================
+  // Priority queue operations
+  // ========================================================================
+
+  offer(element: T): boolean {
+    this._heap.push(element);
+    this.bubbleUp(this._heap.length - 1);
+    return true;
+  }
+
+  poll(): T {
+    if (this.isEmpty) {
+      throw new Error("Priority queue is empty");
+    }
+    return this.pollOrUndefined()!;
+  }
+
+  pollOrUndefined(): T | undefined {
+    if (this.isEmpty) {
+      return undefined;
+    }
+
+    const result = this._heap[0];
+
+    if (this._heap.length === 1) {
+      this._heap.pop();
+    } else {
+      this._heap[0] = this._heap.pop()!;
+      this.bubbleDown(0);
+    }
+
+    return result;
+  }
+
+  peek(): T {
+    if (this.isEmpty) {
+      throw new Error("Priority queue is empty");
+    }
+    return this._heap[0]!;
+  }
+
+  peekOrUndefined(): T | undefined {
+    return this.isEmpty ? undefined : this._heap[0];
+  }
+
+  // ========================================================================
+  // Queue interface compatibility
+  // ========================================================================
+
+  enqueue(element: T): boolean {
+    return this.offer(element);
+  }
+
+  dequeue(): T {
+    return this.poll();
+  }
+
+  // ========================================================================
+  // Collection operations
+  // ========================================================================
+
+  add(element: T): boolean {
+    return this.offer(element);
+  }
+
+  addAll(other: Iterable<T>): boolean {
+    let modified = false;
+    for (const element of other) {
+      this.offer(element);
+      modified = true;
+    }
+    return modified;
+  }
+
+  contains(element: T): boolean {
+    for (const item of this._heap) {
+      if (this._eq(item, element)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  containsAll(other: Iterable<T>): boolean {
+    for (const element of other) {
+      if (!this.contains(element)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  remove(element: T): boolean {
+    const index = this._heap.findIndex((item) => this._eq(item, element));
+    if (index === -1) {
+      return false;
+    }
+
+    if (index === this._heap.length - 1) {
+      this._heap.pop();
+    } else {
+      this._heap[index] = this._heap.pop()!;
+      this.bubbleDown(index);
+      this.bubbleUp(index);
+    }
+
+    return true;
+  }
+
+  removeAll(other: Iterable<T>): boolean {
+    let modified = false;
+    for (const element of other) {
+      while (this.remove(element)) {
+        modified = true;
+      }
+    }
+    return modified;
+  }
+
+  retainAll(other: Iterable<T>): boolean {
+    const toRetain = new Set(other);
+    const newHeap: T[] = [];
+
+    for (const element of this._heap) {
+      let shouldRetain = false;
+      for (const retainElement of toRetain) {
+        if (this._eq(element, retainElement)) {
+          shouldRetain = true;
+          break;
+        }
+      }
+      if (shouldRetain) {
+        newHeap.push(element);
+      }
+    }
+
+    const modified = newHeap.length !== this._heap.length;
+    this._heap = newHeap;
+    this.heapify();
+
+    return modified;
+  }
+
+  clear(): void {
+    this._heap = [];
+  }
+
+  // ========================================================================
+  // Iteration
+  // ========================================================================
+
+  /**
+   * Iterator returns elements in arbitrary order (not priority order).
+   * To get elements in priority order, repeatedly call poll().
+   */
+  *[Symbol.iterator](): Iterator<T> {
+    yield* this._heap;
+  }
+
+  forEach(action: (element: T, index: number) => void): void {
+    this._heap.forEach((element, index) => action(element, index));
+  }
+
+  /**
+   * Returns elements in arbitrary heap order (not sorted).
+   */
+  toArray(): T[] {
+    return this._heap.slice();
+  }
+
+  /**
+   * Returns elements in priority order (sorted).
+   * This is a destructive operation that drains the queue.
+   */
+  toSortedArray(): T[] {
+    const result: T[] = [];
+    const clone = this.clone();
+
+    while (!clone.isEmpty) {
+      result.push(clone.poll());
+    }
+
+    return result;
+  }
+
+  // ========================================================================
+  // Heap operations
+  // ========================================================================
+
+  /**
+   * Bubbles an element up the heap to maintain heap property.
+   */
+  private bubbleUp(index: number): void {
+    const element = this._heap[index]!;
+
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      const parent = this._heap[parentIndex]!;
+
+      if (this._compare(element, parent) >= 0) {
+        break;
+      }
+
+      this._heap[index] = parent;
+      index = parentIndex;
+    }
+
+    this._heap[index] = element;
+  }
+
+  /**
+   * Bubbles an element down the heap to maintain heap property.
+   *
+   * The element moves down through a hole: a smaller child moves up into the hole, and the
+   * element goes into the last hole. The children are compared with the element. (Before, they
+   * were compared with `_heap[index]`, which after the first step is a copy of the child that
+   * moved up: a poll could leave a larger element above a smaller one.)
+   */
+  private bubbleDown(index: number): void {
+    const length = this._heap.length;
+    const element = this._heap[index]!;
+
+    while (true) {
+      const leftChildIndex = 2 * index + 1;
+      const rightChildIndex = 2 * index + 2;
+      if (leftChildIndex >= length) {
+        break;
+      }
+
+      let childIndex = leftChildIndex;
+      if (
+        rightChildIndex < length &&
+        this._compare(this._heap[rightChildIndex]!, this._heap[leftChildIndex]!) < 0
+      ) {
+        childIndex = rightChildIndex;
+      }
+
+      if (this._compare(this._heap[childIndex]!, element) >= 0) {
+        break;
+      }
+
+      this._heap[index] = this._heap[childIndex]!;
+      index = childIndex;
+    }
+
+    this._heap[index] = element;
+  }
+
+  /**
+   * Rebuilds the heap from an arbitrary array.
+   * Uses Floyd's algorithm (O(n) time).
+   */
+  private heapify(): void {
+    // Start from last non-leaf node and bubble down
+    for (let i = Math.floor(this._heap.length / 2) - 1; i >= 0; i--) {
+      this.bubbleDown(i);
+    }
+  }
+
+  // ========================================================================
+  // Utility methods
+  // ========================================================================
+
+  /**
+   * Creates a shallow copy of this priority queue.
+   */
+  clone(): PriorityQueue<T> {
+    const clone = new PriorityQueue<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+    clone._heap = this._heap.slice();
+    return clone;
+  }
+
+  /**
+   * Validates the heap property (for debugging).
+   * Returns true if the heap is valid.
+   */
+  validate(): boolean {
+    for (let i = 0; i < this._heap.length; i++) {
+      const leftChildIndex = 2 * i + 1;
+      const rightChildIndex = 2 * i + 2;
+
+      if (
+        leftChildIndex < this._heap.length &&
+        this._compare(this._heap[i]!, this._heap[leftChildIndex]!) > 0
+      ) {
+        return false;
+      }
+
+      if (
+        rightChildIndex < this._heap.length &&
+        this._compare(this._heap[i]!, this._heap[rightChildIndex]!) > 0
+      ) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Returns a string representation for debugging.
+   */
+  toString(): string {
+    return `PriorityQueue[${this._heap.join(", ")}]`;
+  }
+}
+
+/**
+ * Factory function to create a PriorityQueue.
+ *
+ * @example
+ * // Min heap (default)
+ * const minHeap = priorityQueue<number>()
+ *
+ * // Max heap
+ * const maxHeap = priorityQueue<number>((a, b) => b - a)
+ *
+ * // From array
+ * const pq = priorityQueue([5, 2, 8, 1, 9])
+ *
+ * // With custom comparator
+ * const pq = priorityQueue<Task>((a, b) => a.priority - b.priority)
+ */
+export function priorityQueue<T>(
+  optionsOrElementsOrComparator?:
+    | PriorityQueueOptions<T>
+    | Iterable<T>
+    | Compare<T>
+): PriorityQueue<T> {
+  // If it's a function, treat it as a comparator
+  if (typeof optionsOrElementsOrComparator === "function") {
+    return new PriorityQueue<T>({
+      compare: optionsOrElementsOrComparator as Compare<T>,
+    });
+  }
+
+  // Check if it's an iterable (not options)
+  if (optionsOrElementsOrComparator && Symbol.iterator in optionsOrElementsOrComparator) {
+    const pq = new PriorityQueue<T>();
+    pq.addAll(optionsOrElementsOrComparator as Iterable<T>);
+    return pq;
+  }
+
+  return new PriorityQueue<T>(
+    optionsOrElementsOrComparator as PriorityQueueOptions<T>
+  );
+}