@mark1russell7/collections 0.0.0-stage → 0.2.0

package/src/async/channels.ts

@@ -0,0 +1,450 @@
+/**
+ * Go-style channels for CSP (Communicating Sequential Processes).
+ *
+ * This module gives 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))
+ * )
+ */
+
+import { asyncQueue, type AsyncQueue } from "./async-queue.js";
+
+/**
+ * Channel<T> - Bidirectional communication channel.
+ *
+ * The channels of Go are the model. This class gives send/receive operations
+ * that can block until the other side is ready.
+ */
+export class Channel<T> {
+  private queue: AsyncQueue<T>;
+  private _isClosed = false;
+
+  constructor(bufferSize: number = 0) {
+    // A buffer size of 0 is an unbuffered channel: send waits for a receiver (a rendezvous).
+    // (Before, `bufferSize || 1` gave it a buffer of 1: BUGS-2026-07 L17.)
+    this.queue = asyncQueue<T>({ capacity: bufferSize });
+  }
+
+  /**
+   * This method sends a value through the channel.
+   * Blocks if channel buffer is full.
+   *
+   * @throws Error if channel is closed
+   */
+  async send(value: T): Promise<void> {
+    if (this._isClosed) {
+      throw new Error("Cannot send on closed channel");
+    }
+    await this.queue.put(value);
+  }
+
+  /**
+   * This method receives a value from the channel.
+   * Blocks if no value is available.
+   *
+   * @throws Error if channel is closed and empty
+   */
+  async receive(): Promise<T> {
+    return await this.queue.take();
+  }
+
+  /**
+   * This method waits for one value, as `receive` does, and gives it to `onValue`. When the
+   * channel is closed and empty, it calls `onClosed`. These calls are synchronous: they occur in
+   * the call that sends the value or closes the channel.
+   *
+   * The function that it gives withdraws the wait, so no later value goes to it.
+   *
+   * @returns A function that withdraws the wait. It gives true when the wait had no value yet.
+   */
+  waitReceive(onValue: (value: T) => void, onClosed: (error: Error) => void): () => boolean {
+    return this.queue.waitTake(onValue, onClosed);
+  }
+
+  /**
+   * This method tries to send without blocking.
+   * This method gives false if channel is full.
+   */
+  trySend(value: T): boolean {
+    if (this._isClosed) return false;
+    return this.queue.tryPut(value);
+  }
+
+  /**
+   * This method tries to receive without blocking.
+   * This method gives undefined if no value is available.
+   */
+  tryReceive(): T | undefined {
+    return this.queue.tryTake();
+  }
+
+  /**
+   * This method closes the channel. No more values can be sent.
+   * Receivers can still drain remaining values.
+   */
+  close(): void {
+    this._isClosed = true;
+    this.queue.close();
+  }
+
+  get isClosed(): boolean {
+    return this._isClosed;
+  }
+
+  get size(): number {
+    return this.queue.size;
+  }
+
+  /**
+   * This method makes a select case for this channel.
+   * The select() function uses this value for multiplexing.
+   */
+  case<R>(handler: (value: T) => R): SelectCase<R> {
+    return {
+      channel: this,
+      handler,
+      tryReceive: () => this.tryReceive(),
+      receive: () => this.receive(),
+      wait: (onValue, onClosed) => this.waitReceive(onValue, onClosed),
+    };
+  }
+
+  /**
+   * Async iteration over channel values.
+   * Stops when channel is closed and empty.
+   */
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    while (true) {
+      try {
+        yield await this.receive();
+      } catch (e) {
+        // Channel closed
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * SelectCase represents a case in a select statement.
+ */
+export interface SelectCase<R> {
+  channel: Channel<any>;
+  handler: (value: any) => R;
+  tryReceive: () => any;
+  receive: () => Promise<any>;
+  /**
+   * A wait for one value that `select` can withdraw: `Channel.waitReceive`. A case without it
+   * uses the `waitReceive` method of its channel.
+   */
+  wait?: (onValue: (value: any) => void, onClosed: (error: Error) => void) => () => boolean;
+}
+
+/** A wait for one value that can be withdrawn, as `Channel.waitReceive` gives it. */
+type Wait = (onValue: (value: unknown) => void, onClosed: (error: Error) => void) => () => boolean;
+
+/**
+ * This function gives the first value of the waits, with the index of its wait. It rejects with
+ * the error of the first wait whose channel is closed and empty. It withdraws each other wait in
+ * the same call, so a later value stays in its channel. (Before, the receives of the cases that
+ * lost stayed in their channels and dropped the next value of each: audit O56.)
+ */
+function firstOf(waits: readonly Wait[]): Promise<{ index: number; value: unknown }> {
+  return new Promise((resolve, reject) => {
+    const withdraws: Array<() => boolean> = [];
+    let settled = false;
+    const end = (): void => {
+      settled = true;
+      for (const withdraw of withdraws) withdraw();
+    };
+    // A wait can call back at once, in its own call, when its channel has a value or is closed
+    try {
+      for (let index = 0; index < waits.length && !settled; index++) {
+        withdraws.push(
+          waits[index]!(
+            (value) => {
+              if (settled) return;
+              end();
+              resolve({ index, value });
+            },
+            (error) => {
+              if (settled) return;
+              end();
+              reject(error);
+            },
+          ),
+        );
+      }
+    } catch (error) {
+      // A wait that throws: the waits before it are withdrawn
+      if (!settled) end();
+      reject(error);
+    }
+  });
+}
+
+/**
+ * Selects from multiple channels (like Go's select statement).
+ *
+ * This function waits for the first channel to have a value available,
+ * then calls its handler and gives the result.
+ *
+ * The first case with a value at once wins. The cases that lose keep no receive: a value that
+ * comes later stays in its channel for the next receiver. When the channel of a case is closed
+ * and empty, the given promise rejects.
+ *
+ * @example
+ * const result = await select(
+ *   ch1.case((v) => `ch1: ${v}`),
+ *   ch2.case((v) => `ch2: ${v}`),
+ *   timeout(1000).case(() => 'timeout')
+ * )
+ */
+export async function select<R>(...cases: SelectCase<R>[]): Promise<R> {
+  const { index, value } = await firstOf(
+    cases.map((c): Wait => c.wait ?? ((onValue, onClosed) => c.channel.waitReceive(onValue, onClosed))),
+  );
+  // The handler runs after the race, not in the call of the sender
+  return cases[index]!.handler(value);
+}
+
+/**
+ * This function makes a timeout channel that sends after the specified duration.
+ *
+ * @example
+ * const result = await select(
+ *   dataChannel.case((v) => v),
+ *   timeout(5000).case(() => 'timeout!')
+ * )
+ */
+export function timeout(ms: number): Channel<void> {
+  const ch = new Channel<void>();
+  setTimeout(() => {
+    ch.send(undefined).catch(() => {}); // Ignore if closed
+    ch.close();
+  }, ms);
+  return ch;
+}
+
+/**
+ * This function makes 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 function ticker(ms: number): Channel<number> & { stop: () => void } {
+  const ch = new Channel<number>(1);
+  let count = 0;
+
+  const intervalId = setInterval(() => {
+    ch.trySend(count++);
+  }, ms);
+
+  return Object.assign(ch, {
+    stop: () => {
+      clearInterval(intervalId);
+      ch.close();
+    },
+  });
+}
+
+/**
+ * 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 function pipeline<T, U>(
+  input: Channel<T>,
+  transform: (value: T) => U | Promise<U>,
+  bufferSize: number = 0
+): Channel<U> {
+  const output = new Channel<U>(bufferSize);
+
+  // The output closes also when the transform fails, so its reader does not wait forever. The
+  // error goes to the console, as in workerPool. (Before, it was an unhandled rejection: audit pass 2.)
+  (async () => {
+    try {
+      for await (const value of input) {
+        const transformed = await transform(value);
+        await output.send(transformed);
+      }
+    } finally {
+      output.close();
+    }
+  })().catch((error: unknown) => console.error("pipeline error:", error));
+
+  return output;
+}
+
+/**
+ * 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 function fanOut<T>(input: Channel<T>, count: number, bufferSize: number = 0): Channel<T>[] {
+  const outputs = Array.from({ length: count }, () => new Channel<T>(bufferSize));
+
+  (async () => {
+    try {
+      for await (const value of input) {
+        await Promise.all(outputs.map((ch) => ch.send(value)));
+      }
+    } finally {
+      outputs.forEach((ch) => ch.close());
+    }
+  })().catch((error: unknown) => console.error("fanOut error:", error));
+
+  return outputs;
+}
+
+/**
+ * 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 function fanIn<T>(...inputs: Channel<T>[]): Channel<T> {
+  const output = new Channel<T>();
+
+  const workers = inputs.map(async (input) => {
+    for await (const value of input) {
+      await output.send(value);
+    }
+  });
+
+  // All the workers settle, then the output closes, also after a failed send
+  Promise.allSettled(workers).then((results) => {
+    output.close();
+    for (const result of results) if (result.status === "rejected") console.error("fanIn error:", result.reason);
+  });
+
+  return output;
+}
+
+/**
+ * Merge: like fanIn but closes output when first input closes.
+ *
+ * It takes one value at a time, from the inputs in turn. It keeps no receive on an input while
+ * it waits for the reader of the output. Thus each value of each input reaches the output one
+ * time, in the order of its input, or stays in its input.
+ */
+export function merge<T>(...inputs: Channel<T>[]): Channel<T> {
+  const output = new Channel<T>();
+
+  (async () => {
+    // The input after the input of the last value comes first, so a busy input starves no other
+    let start = 0;
+    while (true) {
+      const order = inputs.map((_, offset) => (start + offset) % inputs.length);
+      let next: { index: number; value: unknown };
+      try {
+        next = await firstOf(order.map((index): Wait => (onValue, onClosed) => inputs[index]!.waitReceive(onValue, onClosed)));
+      } catch {
+        // An input is closed and empty
+        break;
+      }
+      const index = order[next.index]!;
+      start = (index + 1) % inputs.length;
+      try {
+        await output.send(next.value as T);
+      } catch {
+        // The reader closed the output
+        break;
+      }
+    }
+    output.close();
+  })();
+
+  return output;
+}
+
+/**
+ * Buffered channel with specified capacity.
+ */
+export function buffered<T>(capacity: number): Channel<T> {
+  return new Channel<T>(capacity);
+}
+
+/**
+ * Unbuffered channel (rendezvous point).
+ * Sends block until receiver is ready.
+ */
+export function unbuffered<T>(): Channel<T> {
+  return new Channel<T>(0);
+}
+
+/**
+ * Factory function to make a channel.
+ *
+ * @example
+ * const ch = channel<number>()
+ * const bufferedCh = channel<string>(10)
+ */
+export function channel<T>(bufferSize: number = 0): Channel<T> {
+  return new Channel<T>(bufferSize);
+}
+
+/**
+ * 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 function workerPool<T, R>(
+  jobs: Channel<T>,
+  worker: (job: T) => Promise<R>,
+  options: { workers: number; bufferSize?: number } = { workers: 1 }
+): Channel<R> {
+  const results = new Channel<R>(options.bufferSize || 0);
+  const { workers: workerCount } = options;
+
+  const workers = Array.from({ length: workerCount }, async () => {
+    for await (const job of jobs) {
+      try {
+        const result = await worker(job);
+        await results.send(result);
+      } catch (error) {
+        console.error("Worker error:", error);
+      }
+    }
+  });
+
+  Promise.all(workers).then(() => results.close());
+
+  return results;
+}

package/src/async/settled.ts

@@ -0,0 +1,41 @@
+/**
+ * asSettled - The results of running promises, in the order that they settle.
+ *
+ * @example
+ * const pages = urls.map((url) => fetch(url));
+ * for await (const result of asSettled(pages)) {
+ *   if (result.status === "fulfilled") show(result.index, result.value);
+ *   else report(result.index, result.reason);
+ * }
+ */
+
+/** One result of `asSettled`: the index of its promise in the input, and how the promise settled. */
+export type Settled<T> = { readonly index: number } & PromiseSettledResult<T>;
+
+/**
+ * This function gives the result of each promise when it settles, in settle order, not in input
+ * order. The promises run already: this function starts nothing. Each result has the index of its
+ * promise in the input. A rejected promise gives `status: "rejected"` and its reason: the
+ * generator does not throw it. When the consumer stops early, the other promises continue, and
+ * their rejections are not reported as unhandled.
+ */
+export async function* asSettled<T>(promises: Iterable<Promise<T>>): AsyncGenerator<Settled<T>, void, undefined> {
+  const pending = new Map<number, Promise<Settled<T>>>();
+  let next = 0;
+  for (const promise of promises) {
+    const index = next;
+    next += 1;
+    pending.set(
+      index,
+      Promise.resolve(promise).then(
+        (value): Settled<T> => ({ index, status: "fulfilled", value }),
+        (reason: unknown): Settled<T> => ({ index, status: "rejected", reason })
+      )
+    );
+  }
+  while (pending.size > 0) {
+    const settled = await Promise.race(pending.values());
+    pending.delete(settled.index);
+    yield settled;
+  }
+}