@procedures/collections 0.0.0-stage → 0.2.0

package/dist/impl/priority-queue.js

@@ -0,0 +1,343 @@
+/**
+ * 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 { defaultEq, defaultCompare } from "../utils/defaults.js";
+/**
+ * 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 {
+    _heap;
+    _compare;
+    _eq;
+    constructor(options = {}) {
+        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() {
+        return this._heap.length;
+    }
+    get isEmpty() {
+        return this._heap.length === 0;
+    }
+    get eq() {
+        return this._eq;
+    }
+    get compare() {
+        return this._compare;
+    }
+    get comparator() {
+        return this._compare;
+    }
+    // ========================================================================
+    // Priority queue operations
+    // ========================================================================
+    offer(element) {
+        this._heap.push(element);
+        this.bubbleUp(this._heap.length - 1);
+        return true;
+    }
+    poll() {
+        if (this.isEmpty) {
+            throw new Error("Priority queue is empty");
+        }
+        return this.pollOrUndefined();
+    }
+    pollOrUndefined() {
+        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() {
+        if (this.isEmpty) {
+            throw new Error("Priority queue is empty");
+        }
+        return this._heap[0];
+    }
+    peekOrUndefined() {
+        return this.isEmpty ? undefined : this._heap[0];
+    }
+    // ========================================================================
+    // Queue interface compatibility
+    // ========================================================================
+    enqueue(element) {
+        return this.offer(element);
+    }
+    dequeue() {
+        return this.poll();
+    }
+    // ========================================================================
+    // Collection operations
+    // ========================================================================
+    add(element) {
+        return this.offer(element);
+    }
+    addAll(other) {
+        let modified = false;
+        for (const element of other) {
+            this.offer(element);
+            modified = true;
+        }
+        return modified;
+    }
+    contains(element) {
+        for (const item of this._heap) {
+            if (this._eq(item, element)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    containsAll(other) {
+        for (const element of other) {
+            if (!this.contains(element)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    remove(element) {
+        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) {
+        let modified = false;
+        for (const element of other) {
+            while (this.remove(element)) {
+                modified = true;
+            }
+        }
+        return modified;
+    }
+    retainAll(other) {
+        const toRetain = new Set(other);
+        const newHeap = [];
+        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() {
+        this._heap = [];
+    }
+    // ========================================================================
+    // Iteration
+    // ========================================================================
+    /**
+     * Iterator returns elements in arbitrary order (not priority order).
+     * To get elements in priority order, repeatedly call poll().
+     */
+    *[Symbol.iterator]() {
+        yield* this._heap;
+    }
+    forEach(action) {
+        this._heap.forEach((element, index) => action(element, index));
+    }
+    /**
+     * Returns elements in arbitrary heap order (not sorted).
+     */
+    toArray() {
+        return this._heap.slice();
+    }
+    /**
+     * Returns elements in priority order (sorted).
+     * This is a destructive operation that drains the queue.
+     */
+    toSortedArray() {
+        const result = [];
+        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.
+     */
+    bubbleUp(index) {
+        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.)
+     */
+    bubbleDown(index) {
+        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).
+     */
+    heapify() {
+        // 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() {
+        const clone = new PriorityQueue({
+            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() {
+        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() {
+        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(optionsOrElementsOrComparator) {
+    // If it's a function, treat it as a comparator
+    if (typeof optionsOrElementsOrComparator === "function") {
+        return new PriorityQueue({
+            compare: optionsOrElementsOrComparator,
+        });
+    }
+    // Check if it's an iterable (not options)
+    if (optionsOrElementsOrComparator && Symbol.iterator in optionsOrElementsOrComparator) {
+        const pq = new PriorityQueue();
+        pq.addAll(optionsOrElementsOrComparator);
+        return pq;
+    }
+    return new PriorityQueue(optionsOrElementsOrComparator);
+}
+//# sourceMappingURL=priority-queue.js.map

package/dist/impl/priority-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-queue.js","sourceRoot":"","sources":["../../src/impl/priority-queue.ts"],"names":[],"mappings":"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"}

package/dist/impl/tree-map.d.ts

@@ -0,0 +1,153 @@
+/**
+ * TreeMap - Red-black tree based sorted map implementation.
+ *
+ * Implements a self-balancing binary search tree that maintains keys in sorted
+ * order. Mirrors java.util.TreeMap.
+ *
+ * Key features:
+ * - O(log n) access, insert, delete
+ * - Keys maintained in sorted order (natural or custom comparator)
+ * - Navigation methods (floor, ceiling, lower, higher)
+ * - Range view operations (subMap, headMap, tailMap)
+ *
+ * @example
+ * const map = treeMap<string, number>()
+ * map.set('c', 3)
+ * map.set('a', 1)
+ * map.set('b', 2)
+ * // Iteration order: a, b, c (sorted)
+ *
+ * @example
+ * // Custom comparator for descending order
+ * const map = treeMap<number, string>({
+ *   compare: (a, b) => b - a
+ * })
+ */
+import type { NavigableMap, SortedMap, Entry } from "../interfaces/map.js";
+import type { Eq, Compare } from "../core/traits.js";
+/**
+ * Options for creating a TreeMap.
+ */
+export interface TreeMapOptions<K, V> {
+    /**
+     * Comparison function for keys.
+     * @default defaultCompare
+     */
+    compare?: Compare<K>;
+    /**
+     * Equality function for keys.
+     * @default defaultEq
+     */
+    eq?: Eq<K>;
+    /**
+     * Equality function for values.
+     * @default defaultEq
+     */
+    valueEq?: Eq<V>;
+}
+/**
+ * TreeMap<K, V> - Red-black tree based sorted map.
+ *
+ * Maintains keys in sorted order using a self-balancing binary search tree.
+ * Provides O(log n) operations and navigation methods.
+ */
+export declare class TreeMap<K, V> implements NavigableMap<K, V> {
+    private _root;
+    private _size;
+    private readonly _compare;
+    private readonly _eq;
+    private readonly _valueEq;
+    constructor(options?: TreeMapOptions<K, V>);
+    get size(): number;
+    get isEmpty(): boolean;
+    get comparator(): Compare<K>;
+    get keyEq(): Eq<K>;
+    get valueEq(): Eq<V>;
+    has(key: K): boolean;
+    containsKey(key: K): boolean;
+    containsValue(value: V): boolean;
+    get(key: K): V;
+    getOrUndefined(key: K): V | undefined;
+    getOrDefault(key: K, defaultValue: V): V;
+    set(key: K, value: V): V | undefined;
+    setIfAbsent(key: K, value: V): V;
+    replace(key: K, value: V): V | undefined;
+    replaceEntry(key: K, oldValue: V, newValue: V): boolean;
+    delete(key: K): V | undefined;
+    deleteEntry(key: K, value: V): boolean;
+    clear(): void;
+    putAll(other: NavigableMap<K, V> | Iterable<Entry<K, V>>): void;
+    computeIfAbsent(key: K, mappingFunction: (key: K) => V): V;
+    computeIfPresent(key: K, remappingFunction: (key: K, value: V) => V | undefined): V | undefined;
+    compute(key: K, remappingFunction: (key: K, value: V | undefined) => V | undefined): V | undefined;
+    merge(key: K, value: V, remappingFunction: (oldValue: V, newValue: V) => V | undefined): V | undefined;
+    firstKey(): K;
+    lastKey(): K;
+    headMap(toKey: K): SortedMap<K, V>;
+    tailMap(fromKey: K): SortedMap<K, V>;
+    subMap(fromKey: K, toKey: K): SortedMap<K, V>;
+    floorKey(key: K): K | undefined;
+    ceilingKey(key: K): K | undefined;
+    lowerKey(key: K): K | undefined;
+    higherKey(key: K): K | undefined;
+    floorEntry(key: K): Entry<K, V> | undefined;
+    ceilingEntry(key: K): Entry<K, V> | undefined;
+    lowerEntry(key: K): Entry<K, V> | undefined;
+    higherEntry(key: K): Entry<K, V> | undefined;
+    firstEntry(): Entry<K, V> | undefined;
+    lastEntry(): Entry<K, V> | undefined;
+    pollFirstEntry(): Entry<K, V> | undefined;
+    pollLastEntry(): Entry<K, V> | undefined;
+    descendingMap(): NavigableMap<K, V>;
+    descendingKeys(): IterableIterator<K>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+    entries(): IterableIterator<Entry<K, V>>;
+    [Symbol.iterator](): Iterator<Entry<K, V>>;
+    forEach(action: (value: V, key: K, map: this) => void): void;
+    toArray(): Entry<K, V>[];
+    private createNode;
+    private getNode;
+    private getFirstNode;
+    private getLastNode;
+    private findValue;
+    private inOrderTraversal;
+    private reverseInOrderTraversal;
+    private rotateLeft;
+    private rotateRight;
+    private fixAfterInsertion;
+    /**
+     * Deletes a node (the CLRS algorithm, as in java.util.TreeMap). A null leaf counts as black.
+     *
+     * Before (BUGS-2026-07 L10): the deletion of a black leaf skipped the fix-up, so the black
+     * heights drifted and the tree became unbalanced, and the fix-up treated a null leaf as
+     * "not black", so it chose the wrong case and rotated at null (a TypeError).
+     */
+    private deleteNode;
+    private fixAfterDeletion;
+    toString(): string;
+}
+/**
+ * Factory function to create a TreeMap.
+ *
+ * @example
+ * const map = treeMap<string, number>()
+ * map.set('c', 3)
+ * map.set('a', 1)
+ * map.set('b', 2)
+ * // Iteration order: a, b, c
+ *
+ * @example
+ * // With initial entries
+ * const map = treeMap<string, number>([
+ *   ['c', 3],
+ *   ['a', 1],
+ *   ['b', 2]
+ * ])
+ *
+ * @example
+ * // Custom comparator for descending order
+ * const map = treeMap<number, string>({ compare: (a, b) => b - a })
+ */
+export declare function treeMap<K, V>(optionsOrEntries?: TreeMapOptions<K, V> | Iterable<[K, V]>): TreeMap<K, V>;
+//# sourceMappingURL=tree-map.d.ts.map

package/dist/impl/tree-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-map.d.ts","sourceRoot":"","sources":["../../src/impl/tree-map.ts"],"names":[],"mappings":"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"}