@procedures/collections 0.0.0-stage → 0.2.0

package/dist/async/async-queue.js

@@ -0,0 +1,342 @@
+/**
+ * AsyncQueue - An async iterable queue with backpressure support.
+ *
+ * Designed for producer-consumer patterns where producers can wait when
+ * the queue is full and consumers can wait when the queue is empty.
+ * Implements AsyncIterable for use with for-await-of loops.
+ *
+ * @example
+ * const queue = asyncQueue<number>({ capacity: 10 })
+ *
+ * // Producer
+ * await queue.put(42) // Waits if queue is full
+ *
+ * // Consumer
+ * const value = await queue.take() // Waits if queue is empty
+ *
+ * // Async iteration
+ * for await (const value of queue) {
+ *   console.log(value)
+ * }
+ */
+/**
+ * AsyncQueue<T> - Thread-safe async queue with backpressure.
+ *
+ * Features:
+ * - Blocking put() when full (backpressure)
+ * - Blocking take() when empty
+ * - AsyncIterable support
+ * - Graceful closing
+ * - Timeouts
+ *
+ * Perfect for:
+ * - Producer-consumer patterns
+ * - Rate limiting
+ * - Task queues
+ * - Stream processing
+ */
+export class AsyncQueue {
+    buffer = [];
+    putters = [];
+    takers = [];
+    _isClosed = false;
+    capacity;
+    defaultTimeout;
+    constructor(options = {}) {
+        this.capacity = options.capacity ?? Infinity;
+        if (options.timeout !== undefined) {
+            this.defaultTimeout = options.timeout;
+        }
+    }
+    // ========================================================================
+    // Size and state
+    // ========================================================================
+    get size() {
+        return this.buffer.length;
+    }
+    get isEmpty() {
+        return this.buffer.length === 0;
+    }
+    get isFull() {
+        return this.buffer.length >= this.capacity;
+    }
+    get isClosed() {
+        return this._isClosed;
+    }
+    get remainingCapacity() {
+        return this.capacity === Infinity ? Infinity : this.capacity - this.buffer.length;
+    }
+    // ========================================================================
+    // Blocking operations
+    // ========================================================================
+    /**
+     * Adds an element to the queue.
+     * If the queue is full, waits until space is available. With a capacity of 0, it waits until
+     * a taker takes the element (a rendezvous).
+     *
+     * @throws Error if queue is closed
+     * @throws Error if timeout expires
+     */
+    async put(element, timeout) {
+        if (this._isClosed) {
+            throw new Error("Queue is closed");
+        }
+        if (this.tryPutNow(element)) {
+            return;
+        }
+        // Queue is full: wait with the element. (Before, a waiting putter kept only its resolve
+        // function, so its element was dropped when space came: BUGS-2026-07 C11.)
+        return new Promise((resolve, reject) => {
+            const putter = { element, resolve, reject };
+            const timeoutMs = timeout ?? this.defaultTimeout;
+            if (timeoutMs !== undefined) {
+                putter.timeoutId = setTimeout(() => {
+                    const index = this.putters.indexOf(putter);
+                    if (index !== -1) {
+                        this.putters.splice(index, 1);
+                    }
+                    reject(new Error(`Put timeout after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }
+            this.putters.push(putter);
+        });
+    }
+    /**
+     * Removes and returns an element from the queue.
+     * If the queue is empty, waits until an element is available.
+     *
+     * @throws Error if queue is closed and empty
+     * @throws Error if timeout expires
+     */
+    async take(timeout) {
+        const next = this.takeNow();
+        if (next.found) {
+            return next.element;
+        }
+        // If closed and empty, throw
+        if (this._isClosed) {
+            throw new Error("Queue is closed and empty");
+        }
+        // Wait for an element
+        return new Promise((resolve, reject) => {
+            const taker = { resolve, reject };
+            const timeoutMs = timeout ?? this.defaultTimeout;
+            if (timeoutMs !== undefined) {
+                taker.timeoutId = setTimeout(() => {
+                    const index = this.takers.indexOf(taker);
+                    if (index !== -1) {
+                        this.takers.splice(index, 1);
+                    }
+                    reject(new Error(`Take timeout after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }
+            this.takers.push(taker);
+        });
+    }
+    // ========================================================================
+    // Non-blocking operations
+    // ========================================================================
+    /**
+     * Attempts to add an element without waiting.
+     * Returns false if queue is full (with a capacity of 0: if no taker waits).
+     */
+    tryPut(element) {
+        if (this._isClosed) {
+            return false;
+        }
+        return this.tryPutNow(element);
+    }
+    /**
+     * Attempts to remove an element without waiting.
+     * Returns undefined if queue is empty.
+     */
+    tryTake() {
+        const next = this.takeNow();
+        return next.found ? next.element : undefined;
+    }
+    /** Gives the element to a waiting taker, or puts it in the buffer when there is space. */
+    tryPutNow(element) {
+        // A waiting taker gets the element directly (the buffer is empty when a taker waits)
+        const taker = this.takers.shift();
+        if (taker) {
+            this.clearTimeout(taker);
+            taker.resolve(element);
+            return true;
+        }
+        if (this.buffer.length < this.capacity) {
+            this.buffer.push(element);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Takes the next element: from the buffer (then a waiting putter moves its element into the
+     * buffer), or directly from a waiting putter (a capacity of 0). (Before, the direct path
+     * released the putter but never gave its element to the taker, so the taker waited forever:
+     * BUGS-2026-07 C11.)
+     */
+    takeNow() {
+        if (this.buffer.length > 0) {
+            const element = this.buffer.shift();
+            this.admitPutter();
+            return { found: true, element };
+        }
+        const putter = this.putters.shift();
+        if (putter) {
+            this.clearTimeout(putter);
+            putter.resolve();
+            return { found: true, element: putter.element };
+        }
+        return { found: false };
+    }
+    // ========================================================================
+    // Peeking
+    // ========================================================================
+    /**
+     * Returns the next element without removing it.
+     * Waits if queue is empty.
+     */
+    async peek() {
+        if (this.buffer.length > 0) {
+            return this.buffer[0];
+        }
+        if (this.putters.length > 0) {
+            return this.putters[0].element;
+        }
+        if (this._isClosed) {
+            throw new Error("Queue is closed and empty");
+        }
+        // Wait for an element, then put it back at the front
+        const element = await this.take();
+        this.buffer.unshift(element);
+        return element;
+    }
+    /**
+     * Returns the next element without waiting.
+     * Returns undefined if queue is empty.
+     */
+    tryPeek() {
+        return this.buffer.length > 0 ? this.buffer[0] : this.putters[0]?.element;
+    }
+    // ========================================================================
+    // Closing and draining
+    // ========================================================================
+    /**
+     * Closes the queue. No more elements can be added.
+     * Existing elements can still be consumed.
+     */
+    close() {
+        this._isClosed = true;
+        // Reject all waiting putters
+        for (const putter of this.putters) {
+            this.clearTimeout(putter);
+            putter.reject(new Error("Queue closed"));
+        }
+        this.putters = [];
+        // Wake up takers if queue is empty
+        if (this.buffer.length === 0) {
+            for (const taker of this.takers) {
+                this.clearTimeout(taker);
+                taker.reject(new Error("Queue closed and empty"));
+            }
+            this.takers = [];
+        }
+    }
+    /**
+     * Drains all elements into an array.
+     * Returns immediately with current elements.
+     */
+    drain() {
+        // The buffer, then the elements of the waiting putters, in order. (Before, the waiting
+        // putters were released but their elements were dropped.)
+        const elements = this.buffer.slice();
+        this.buffer = [];
+        for (const putter of this.putters.splice(0)) {
+            this.clearTimeout(putter);
+            putter.resolve();
+            elements.push(putter.element);
+        }
+        return elements;
+    }
+    // ========================================================================
+    // Async iteration
+    // ========================================================================
+    /**
+     * Async iterator that yields elements as they become available.
+     * Stops when queue is closed and empty.
+     */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const next = this.takeNow();
+            if (next.found) {
+                yield next.element;
+            }
+            else if (this._isClosed) {
+                break;
+            }
+            else {
+                let element;
+                try {
+                    element = await this.take();
+                }
+                catch (error) {
+                    // The queue was closed while the iterator waited
+                    if (this._isClosed)
+                        break;
+                    throw error;
+                }
+                yield element;
+            }
+        }
+    }
+    // ========================================================================
+    // Private helpers
+    // ========================================================================
+    /** When the buffer has space, the first waiting putter moves its element into it. */
+    admitPutter() {
+        if (this.putters.length > 0 && this.buffer.length < this.capacity) {
+            const putter = this.putters.shift();
+            this.clearTimeout(putter);
+            this.buffer.push(putter.element);
+            putter.resolve();
+        }
+    }
+    clearTimeout(resolver) {
+        if (resolver.timeoutId) {
+            clearTimeout(resolver.timeoutId);
+        }
+    }
+    // ========================================================================
+    // Utility methods
+    // ========================================================================
+    /**
+     * Returns statistics about the queue.
+     */
+    getStats() {
+        return {
+            size: this.size,
+            capacity: this.capacity,
+            isEmpty: this.isEmpty,
+            isFull: this.isFull,
+            isClosed: this._isClosed,
+            waitingPutters: this.putters.length,
+            waitingTakers: this.takers.length,
+            remainingCapacity: this.remainingCapacity,
+        };
+    }
+    toString() {
+        return `AsyncQueue[size=${this.size}, capacity=${this.capacity}, closed=${this._isClosed}]`;
+    }
+}
+/**
+ * Factory function to create an AsyncQueue.
+ *
+ * @example
+ * const queue = asyncQueue<number>({ capacity: 100 })
+ * await queue.put(42)
+ * const value = await queue.take()
+ */
+export function asyncQueue(options) {
+    return new AsyncQueue(options);
+}
+//# sourceMappingURL=async-queue.js.map

package/dist/async/async-queue.js.map

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

package/dist/async/channels.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Go-style channels for CSP (Communicating Sequential Processes).
+ *
+ * Provides typed, bidirectional communication channels inspired by Go.
+ * Perfect for coordinating async operations and implementing concurrent patterns.
+ *
+ * @example
+ * const ch = channel<number>()
+ *
+ * // Sender
+ * await ch.send(42)
+ *
+ * // Receiver
+ * const value = await ch.receive()
+ *
+ * // Select from multiple channels
+ * const result = await select(
+ *   ch1.case((v) => console.log('ch1:', v)),
+ *   ch2.case((v) => console.log('ch2:', v))
+ * )
+ */
+/**
+ * Channel<T> - Bidirectional communication channel.
+ *
+ * Inspired by Go channels. Provides send/receive operations
+ * that can block until the other side is ready.
+ */
+export declare class Channel<T> {
+    private queue;
+    private _isClosed;
+    constructor(bufferSize?: number);
+    /**
+     * Sends a value through the channel.
+     * Blocks if channel buffer is full.
+     *
+     * @throws Error if channel is closed
+     */
+    send(value: T): Promise<void>;
+    /**
+     * Receives a value from the channel.
+     * Blocks if no value is available.
+     *
+     * @throws Error if channel is closed and empty
+     */
+    receive(): Promise<T>;
+    /**
+     * Attempts to send without blocking.
+     * Returns false if channel is full.
+     */
+    trySend(value: T): boolean;
+    /**
+     * Attempts to receive without blocking.
+     * Returns undefined if no value is available.
+     */
+    tryReceive(): T | undefined;
+    /**
+     * Closes the channel. No more values can be sent.
+     * Receivers can still drain remaining values.
+     */
+    close(): void;
+    get isClosed(): boolean;
+    get size(): number;
+    /**
+     * Creates a select case for this channel.
+     * Used with the select() function for multiplexing.
+     */
+    case<R>(handler: (value: T) => R): SelectCase<R>;
+    /**
+     * Async iteration over channel values.
+     * Stops when channel is closed and empty.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+/**
+ * SelectCase represents a case in a select statement.
+ */
+export interface SelectCase<R> {
+    channel: Channel<any>;
+    handler: (value: any) => R;
+    tryReceive: () => any;
+    receive: () => Promise<any>;
+}
+/**
+ * Selects from multiple channels (like Go's select statement).
+ *
+ * Waits for the first channel to have a value available,
+ * then calls its handler and returns the result.
+ *
+ * @example
+ * const result = await select(
+ *   ch1.case((v) => `ch1: ${v}`),
+ *   ch2.case((v) => `ch2: ${v}`),
+ *   timeout(1000).case(() => 'timeout')
+ * )
+ */
+export declare function select<R>(...cases: SelectCase<R>[]): Promise<R>;
+/**
+ * Creates a timeout channel that sends after the specified duration.
+ *
+ * @example
+ * const result = await select(
+ *   dataChannel.case((v) => v),
+ *   timeout(5000).case(() => 'timeout!')
+ * )
+ */
+export declare function timeout(ms: number): Channel<void>;
+/**
+ * Creates a ticker channel that sends at regular intervals.
+ *
+ * @example
+ * const tick = ticker(1000) // Every second
+ * for await (const t of tick) {
+ *   console.log('Tick:', t)
+ * }
+ */
+export declare function ticker(ms: number): Channel<number> & {
+    stop: () => void;
+};
+/**
+ * Pipeline: pipes values from input channel through transform to output channel.
+ *
+ * @example
+ * const input = channel<number>()
+ * const output = pipeline(input, (x) => x * 2)
+ *
+ * await input.send(5)
+ * const result = await output.receive() // 10
+ */
+export declare function pipeline<T, U>(input: Channel<T>, transform: (value: T) => U | Promise<U>, bufferSize?: number): Channel<U>;
+/**
+ * Fan-out: distributes values from one input channel to multiple output channels.
+ *
+ * @example
+ * const input = channel<number>()
+ * const [out1, out2, out3] = fanOut(input, 3)
+ *
+ * // Each output gets a copy of every input value
+ */
+export declare function fanOut<T>(input: Channel<T>, count: number, bufferSize?: number): Channel<T>[];
+/**
+ * Fan-in: merges multiple input channels into one output channel.
+ *
+ * @example
+ * const ch1 = channel<number>()
+ * const ch2 = channel<number>()
+ * const merged = fanIn(ch1, ch2)
+ *
+ * // merged receives values from both ch1 and ch2
+ */
+export declare function fanIn<T>(...inputs: Channel<T>[]): Channel<T>;
+/**
+ * Merge: like fanIn but closes output when first input closes.
+ */
+export declare function merge<T>(...inputs: Channel<T>[]): Channel<T>;
+/**
+ * Buffered channel with specified capacity.
+ */
+export declare function buffered<T>(capacity: number): Channel<T>;
+/**
+ * Unbuffered channel (rendezvous point).
+ * Sends block until receiver is ready.
+ */
+export declare function unbuffered<T>(): Channel<T>;
+/**
+ * Factory function to create a channel.
+ *
+ * @example
+ * const ch = channel<number>()
+ * const bufferedCh = channel<string>(10)
+ */
+export declare function channel<T>(bufferSize?: number): Channel<T>;
+/**
+ * WorkerPool: distributes work across multiple workers.
+ *
+ * @example
+ * const pool = workerPool(
+ *   jobChannel,
+ *   async (job) => await processJob(job),
+ *   { workers: 4 }
+ * )
+ *
+ * // 4 workers concurrently process jobs from jobChannel
+ */
+export declare function workerPool<T, R>(jobs: Channel<T>, worker: (job: T) => Promise<R>, options?: {
+    workers: number;
+    bufferSize?: number;
+}): Channel<R>;
+//# sourceMappingURL=channels.d.ts.map

package/dist/async/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","sourceRoot":"","sources":["../../src/async/channels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;;GAKG;AACH,qBAAa,OAAO,CAAC,CAAC;IACpB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAS;IAE1B,YAAY,UAAU,GAAE,MAAU,EAIjC;IAED;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAKlC;IAED;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,CAE1B;IAED;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAGzB;IAED;;;OAGG;IACH,UAAU,IAAI,CAAC,GAAG,SAAS,CAE1B;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI,CAGZ;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAO/C;IAED;;;OAGG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,CAShD;CACF;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,CAAC;IACtB,OAAO,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAgBrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAczE;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EACjB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACvC,UAAU,GAAE,MAAU,GACrB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAU,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAWhG;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAY5D;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAwB5D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAExD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAE1C;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,UAAU,GAAE,MAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAE7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,OAAO,GAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAmB,GACjE,OAAO,CAAC,CAAC,CAAC,CAkBZ"}