@johnhenry/iteration 0.0.0

package/src/abort.ts

@@ -0,0 +1,80 @@
+/**
+ * AbortSignal plumbing shared by the async consumers (consumers.ts),
+ * transduceAsync (transduce.ts), and the concurrency helpers
+ * (concurrency.ts).
+ */
+
+/** Options bag accepted by cancellable async operations. */
+export interface SignalOptions {
+  signal?: AbortSignal;
+}
+
+/**
+ * The error an aborted operation rejects with: the signal's own `reason`
+ * when set (AbortController.abort() defaults it to an "AbortError"
+ * DOMException), otherwise a fresh "AbortError" DOMException.
+ * @ignore
+ */
+const abortError = (signal: AbortSignal): unknown =>
+  signal.reason ?? new DOMException("This operation was aborted", "AbortError");
+
+/** Throw the signal's abort reason if it has already aborted. */
+export const throwIfAborted = (signal?: AbortSignal): void => {
+  if (signal?.aborted) {
+    throw abortError(signal);
+  }
+};
+
+/**
+ * Wrap an (a)sync iterable so that iteration rejects promptly with an
+ * AbortError when `signal` aborts -- even while awaiting a slow source --
+ * and `iterator.return()` is propagated to the source on abort, error, or
+ * early consumer exit. With no signal, delegates straight through.
+ *
+ * Note: on abort the source's `return()` is invoked but deliberately not
+ * awaited -- an async generator queues `return()` behind its in-flight
+ * `next()`, so awaiting it could postpone the rejection indefinitely on a
+ * hung source (the very case aborting is for).
+ * @kind function
+ * @name abortable
+ */
+export const abortable = async function* <T>(
+  iterable: AsyncIterable<T> | Iterable<T>,
+  signal?: AbortSignal,
+): AsyncGenerator<T> {
+  if (!signal) {
+    yield* iterable;
+    return;
+  }
+  throwIfAborted(signal);
+  const it =
+    Symbol.asyncIterator in Object(iterable)
+      ? (iterable as AsyncIterable<T>)[Symbol.asyncIterator]()
+      : (iterable as Iterable<T>)[Symbol.iterator]();
+  let onAbort: () => void = () => {};
+  const aborted = new Promise<never>((_, reject) => {
+    onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  // Pre-handle so an abort that never races (e.g. after completion, before
+  // listener removal) can't surface as an unhandled rejection.
+  aborted.catch(() => {});
+  let done = false;
+  try {
+    while (true) {
+      const result = await Promise.race([Promise.resolve(it.next()), aborted]);
+      if (result.done) {
+        done = true;
+        return;
+      }
+      yield result.value;
+    }
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+    if (!done && it.return) {
+      // Close the source on abort, error, or early consumer exit --
+      // fire-and-forget; see note above.
+      Promise.resolve(it.return()).catch(() => {});
+    }
+  }
+};

package/src/assertions/eventualequal.ts

@@ -0,0 +1,36 @@
+// Historically this module was a pop-quiz assertion and imported
+// pop-quiz/testerror. pop-quiz is no longer a dependency (the test suite
+// moved to node:test), so a structurally-compatible TestError is inlined
+// here to keep the "@johnhenry/iteration/pop-quiz/asserteventualequal" subpath
+// export working for existing consumers: it extends Error, exposes the
+// details on `.val`, and is iterable over the [key, value] entries --
+// exactly the shape pop-quiz@1's TestError had.
+import { eventualequal } from "../eventualequal.ts";
+
+export class TestError extends Error {
+  val: Record<string, unknown>;
+  constructor(message: string, val: Record<string, unknown> = {}) {
+    super(message);
+    this.val = val;
+  }
+  [Symbol.iterator](): IterableIterator<[string, unknown]> {
+    return Object.entries(this.val).values();
+  }
+}
+
+export const DefaultMessage = "should eventually be deep equal";
+export default async (
+  actual: unknown,
+  expected: unknown,
+  message: string = DefaultMessage,
+  operator = "eventualequal",
+): Promise<string | TestError> => {
+  if (await eventualequal(actual, expected)) {
+    return message;
+  }
+  return new TestError(message, {
+    actual: actual,
+    expected: expected,
+    operator,
+  });
+};

package/src/async-channel.ts

@@ -0,0 +1,228 @@
+/**
+ * Asynchronous Channel
+ * @kind namespace
+ * @name AsyncChannel
+ */
+
+/**
+ * Constant signaling channel's end
+ * @kind constant
+ * @name CHANNEL_END
+ */
+export const CHANNEL_END: unique symbol = Symbol("CHANNEL_END");
+
+interface InvertedPromiseParts<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+}
+
+/**
+ * Creates a promise that can be resolved/rejected outside of initial closure
+ * @kind function
+ * @name InvertedPromise
+ * @ignore
+ */
+const InvertedPromise = <T>(): InvertedPromiseParts<T> => {
+  const out = {} as InvertedPromiseParts<T>;
+  out.promise = new Promise<T>((resolve, reject) => {
+    out.resolve = resolve;
+    out.reject = reject;
+  });
+  return out;
+};
+
+export interface AsyncChannelOptions<T> {
+  cache?: Array<T | typeof CHANNEL_END | Error>;
+  limit?: number;
+  transform?: (item: T) => T | Promise<T>;
+  debug?: (...args: unknown[]) => unknown;
+}
+
+/**
+ * Asynchronous Channel class
+ * @kind class
+ * @name AsyncChannel
+ */
+export class AsyncChannel<T = unknown> {
+  limit: number;
+  cache: Array<T | typeof CHANNEL_END | Error>;
+  transform: (item: T) => T | Promise<T>;
+  debug?: (...args: unknown[]) => unknown;
+  private promise?: Promise<T | typeof CHANNEL_END>;
+  private resolve?: (value: T | typeof CHANNEL_END) => void;
+  private reject?: (reason?: unknown) => void;
+  /** Producers awaiting capacity, FIFO (backpressure -- see put()). */
+  private putters: Array<{
+    value: T | typeof CHANNEL_END | Error;
+    release: () => void;
+  }> = [];
+  /**
+   * Serializes delivery of concurrent put() calls into call order. Each
+   * put() grabs the current tail synchronously (before any `await`, so
+   * position is fixed by call order rather than by how long e.g.
+   * `transform()` happens to take) and only commits its value once its
+   * predecessor has committed.
+   */
+  private putOrder: Promise<void> = Promise.resolve();
+
+  /**
+   * Asynchronous Channel constructor
+   * @kind function
+   * @name constructor
+   */
+  constructor({ cache = [], limit = Infinity, transform = ($: T) => $, debug }: AsyncChannelOptions<T> = {}) {
+    this.limit = limit;
+    this.cache = cache.slice(0, limit);
+    this.transform = transform;
+    this.debug = debug;
+  }
+  /**
+   * Move waiting producers' items into the cache while there is capacity,
+   * releasing their pending put() promises (FIFO).
+   * @ignore
+   */
+  private drainPutters(): void {
+    while (this.putters.length > 0 && this.cache.length < this.limit) {
+      const { value, release } = this.putters.shift() as {
+        value: T | typeof CHANNEL_END | Error;
+        release: () => void;
+      };
+      this.cache.push(value);
+      release();
+    }
+  }
+  /**
+   * Put item onto Asynchronous Channel. Returns a Promise<void> that
+   * resolves once the channel has accepted the item: immediately when a
+   * taker is waiting or the cache has capacity, otherwise when a later
+   * take() frees a slot (backpressure -- bounded by `limit`). Replaces the
+   * pre-2.1 behavior of throwing "cache full" at capacity.
+   * @kind function
+   * @name put
+   */
+  async put(item: T, ...debug: unknown[]): Promise<void> {
+    this.debug?.("put", item, ...debug);
+    // Reserve this call's delivery slot synchronously, in call order,
+    // before doing any async work (transform() may resolve at a different
+    // speed for different items -- see class doc on putOrder).
+    const myTurn = this.putOrder;
+    let advance!: () => void;
+    this.putOrder = new Promise<void>((resolve) => {
+      advance = resolve;
+    });
+    try {
+      const value = await this.transform(item);
+      await myTurn;
+      if (this.promise) {
+        this.resolve?.(value);
+        return;
+      }
+      if (this.cache.length < this.limit) {
+        this.cache.push(value);
+        return;
+      }
+      await new Promise<void>((release) => {
+        this.putters.push({ value, release });
+      });
+    } finally {
+      advance();
+    }
+  }
+  /**
+   * Take item off of Asynchronous Channel
+   * @kind function
+   * @name take
+   */
+  async take(...debug: unknown[]): Promise<T | typeof CHANNEL_END> {
+    this.debug?.("take", ...debug);
+    if (this.cache.length) {
+      const value = this.cache.shift() as T | typeof CHANNEL_END;
+      this.drainPutters();
+      return value;
+    }
+    if (this.putters.length) {
+      // limit of 0 (rendezvous) or drained cache with waiting producers:
+      // hand off directly.
+      const { value, release } = this.putters.shift() as {
+        value: T | typeof CHANNEL_END;
+        release: () => void;
+      };
+      release();
+      return value;
+    }
+    const { promise, resolve, reject } = InvertedPromise<T | typeof CHANNEL_END>();
+    this.promise = promise;
+    this.resolve = resolve;
+    this.reject = reject;
+    const value = await this.promise;
+    delete this.promise;
+    delete this.resolve;
+    delete this.reject;
+    return value;
+  }
+  /**
+   * Pause Asynchronous Channel
+   * @kind function
+   * @name break
+   */
+  async break(...debug: unknown[]): Promise<void> {
+    this.debug?.("break", ...debug);
+    if (this.promise) {
+      await this.resolve?.(CHANNEL_END);
+    } else if (this.putters.length > 0) {
+      // Keep FIFO order: the end marker must not overtake producers
+      // already waiting for capacity.
+      this.putters.push({ value: CHANNEL_END, release: () => {} });
+    } else {
+      this.cache.push(CHANNEL_END);
+    }
+  }
+  /**
+   * Stop Asynchronous Channel
+   * @kind function
+   * @name throw
+   */
+  async throw(message?: string, ...debug: unknown[]): Promise<void> {
+    this.debug?.("throw", ...debug);
+    if (this.promise) {
+      await this.reject?.(new Error(message));
+    } else if (this.putters.length > 0) {
+      // Keep FIFO order behind producers already waiting for capacity.
+      this.putters.push({ value: new Error(message), release: () => {} });
+    } else {
+      this.cache.push(new Error(message));
+    }
+  }
+  /**
+   * Return pending status of Asynchronous Channel
+   * @kind function
+   * @name pending
+   * Note: should this be a getter?
+   */
+  pending(): boolean {
+    return !!this.promise;
+  }
+  /**
+   * Return string representation of Asynchronous Channel
+   * @kind function
+   * @name toString
+   */
+  toString(): string {
+    return `AsyncChannel {${this.pending() ? "pending" : ""}} [${this.cache.length}/${this.limit}]`;
+  }
+  /**
+   * Return Asynchronous Channel's iterator
+   * @kind function
+   * @name [Symbol.asyncIterator]
+   */
+  async *[Symbol.asyncIterator](...debug: unknown[]): AsyncGenerator<T> {
+    while (true) {
+      const answer = await this.take(...debug);
+      if (answer === CHANNEL_END) {
+        return;
+      }
+      yield answer;
+    }
+  }
+}

package/src/channel-decorators.ts

@@ -0,0 +1,49 @@
+import type { AsyncChannel } from "./async-channel.ts";
+
+interface EmitterLike {
+  addListener(event: string, listener: (...args: never[]) => unknown): unknown;
+}
+
+interface WebSocketLike {
+  onmessage: ((event: unknown) => unknown) | null;
+  onclose: ((event?: unknown) => unknown) | null;
+  onerror: ((event?: unknown) => unknown) | null;
+}
+
+/**
+ * Decorate Asynchronous Channel with generic emitter
+ * @kind function
+ * @name withEmitter
+ */
+export const withEmitter = <T, C extends AsyncChannel<T>>(
+  channel: C,
+  emitter: EmitterLike,
+  data = "data",
+  end = "end",
+  error = "error",
+): C => {
+  emitter.addListener(data, (...args: never[]) => {
+    void channel.put(...(args as unknown as Parameters<typeof channel.put>)).catch((reason: unknown) => {
+      void channel.throw(reason instanceof Error ? reason.message : String(reason));
+    });
+  });
+  emitter.addListener(end, channel.break.bind(channel));
+  emitter.addListener(error, channel.throw.bind(channel));
+  return channel;
+};
+
+/**
+ * Decorate Asynchronous Channel with websocket
+ * @kind function
+ * @name withWebSocket
+ */
+export const withWebSocket = <T, C extends AsyncChannel<T>>(channel: C, websocket: WebSocketLike): C => {
+  websocket.onmessage = (event: unknown) => {
+    void channel.put(event as T).catch((reason: unknown) => {
+      void channel.throw(reason instanceof Error ? reason.message : String(reason));
+    });
+  };
+  websocket.onclose = channel.break.bind(channel);
+  websocket.onerror = channel.throw.bind(channel) as (event?: unknown) => unknown;
+  return channel;
+};

package/src/concurrency.ts

@@ -0,0 +1,168 @@
+/**
+ * Bounded-concurrency helpers: mapConcurrentAsync (parallel map over an
+ * (a)sync iterable with a concurrency limit) and prefetchAsync (eager
+ * read-ahead into a bounded buffer). Both propagate cancellation/early
+ * consumer exit upstream via iterator.return().
+ */
+
+import { type SignalOptions, throwIfAborted } from "./abort.ts";
+
+export interface MapConcurrentOptions extends SignalOptions {
+  /** Maximum number of `fn` invocations in flight at once (required, >= 1). */
+  concurrency: number;
+  /**
+   * true (default): yield results in input order.
+   * false: yield results in completion order.
+   */
+  ordered?: boolean;
+}
+
+const abortErrorOf = (signal: AbortSignal): unknown =>
+  signal.reason ?? new DOMException("This operation was aborted", "AbortError");
+
+const getIterator = <T>(iterable: AsyncIterable<T> | Iterable<T>): AsyncIterator<T> | Iterator<T> =>
+  Symbol.asyncIterator in Object(iterable)
+    ? (iterable as AsyncIterable<T>)[Symbol.asyncIterator]()
+    : (iterable as Iterable<T>)[Symbol.iterator]();
+
+/**
+ * Map `fn` over `iterable` with up to `concurrency` invocations in flight
+ * at once. With `ordered: true` (the default) results are yielded in input
+ * order; with `ordered: false` they are yielded in completion order.
+ *
+ * - Backpressure: at most `concurrency` results are held; the source is
+ *   only pulled while there is spare in-flight capacity.
+ * - Cancellation: an optional `signal` aborts promptly (rejecting with the
+ *   signal's reason, an "AbortError" DOMException by default) even while
+ *   awaiting a slow `fn` or source; the source iterator is closed via
+ *   `return()`.
+ * - Early exit / error: breaking out of the loop, or an `fn` rejection,
+ *   also closes the source via `return()`.
+ * @kind function
+ * @name mapConcurrentAsync
+ */
+export const mapConcurrentAsync = async function* <In, Out>(
+  fn: (item: In) => Out | Promise<Out>,
+  iterable: AsyncIterable<In> | Iterable<In>,
+  { concurrency, ordered = true, signal }: MapConcurrentOptions,
+): AsyncGenerator<Out> {
+  if (!(typeof concurrency === "number" && concurrency >= 1)) {
+    throw new RangeError("mapConcurrentAsync: concurrency must be >= 1");
+  }
+  throwIfAborted(signal);
+  const it = getIterator(iterable);
+
+  let onAbort: (() => void) | undefined;
+  const aborted = signal
+    ? new Promise<never>((_, reject) => {
+        onAbort = () => reject(abortErrorOf(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+      })
+    : undefined;
+  aborted?.catch(() => {});
+  const race = <T>(promise: Promise<T>): Promise<T> => (aborted ? Promise.race([promise, aborted]) : promise);
+
+  let sourceDone = false;
+  try {
+    if (ordered) {
+      const queue: Array<Promise<Out>> = [];
+      while (true) {
+        while (!sourceDone && queue.length < concurrency) {
+          const r = await race(Promise.resolve(it.next()));
+          if (r.done) {
+            sourceDone = true;
+            break;
+          }
+          const task = (async () => fn(r.value))();
+          task.catch(() => {}); // handled when shifted; avoid unhandledRejection
+          queue.push(task);
+        }
+        if (queue.length === 0) {
+          return;
+        }
+        yield await race(queue.shift() as Promise<Out>);
+      }
+    } else {
+      type Tagged = [Promise<unknown>, Out];
+      const pending = new Set<Promise<Tagged>>();
+      const add = (value: In) => {
+        let self!: Promise<Tagged>;
+        self = (async () => {
+          const out = await fn(value);
+          return [self, out] as Tagged;
+        })();
+        self.catch(() => {}); // handled via the race below
+        pending.add(self);
+      };
+      while (true) {
+        while (!sourceDone && pending.size < concurrency) {
+          const r = await race(Promise.resolve(it.next()));
+          if (r.done) {
+            sourceDone = true;
+            break;
+          }
+          add(r.value);
+        }
+        if (pending.size === 0) {
+          return;
+        }
+        const [task, out] = await race(Promise.race(pending));
+        pending.delete(task as Promise<Tagged>);
+        yield out;
+      }
+    }
+  } finally {
+    if (signal && onAbort) {
+      signal.removeEventListener("abort", onAbort);
+    }
+    if (!sourceDone && it.return) {
+      // Close the source on abort, error, or early consumer exit --
+      // fire-and-forget so a hung source can't block the rejection.
+      Promise.resolve(it.return()).catch(() => {});
+    }
+  }
+};
+
+/**
+ * Eagerly pull up to `n` items ahead of the consumer into a bounded
+ * buffer, so a slow consumer overlaps with a slow producer. `n <= 0`
+ * degenerates to plain iteration. Early consumer exit (or an error)
+ * closes the source via `return()`.
+ * @kind function
+ * @name prefetchAsync
+ */
+export const prefetchAsync = async function* <T>(
+  n: number,
+  iterable: AsyncIterable<T> | Iterable<T>,
+): AsyncGenerator<T> {
+  if (n <= 0) {
+    yield* iterable;
+    return;
+  }
+  const it = getIterator(iterable);
+  const buffer: Array<Promise<IteratorResult<T>> | IteratorResult<T>> = [];
+  let done = false;
+  const pull = () => {
+    const p = Promise.resolve(it.next());
+    p.catch(() => {}); // handled when shifted
+    buffer.push(p);
+  };
+  try {
+    for (let i = 0; i < n; i++) {
+      pull();
+    }
+    while (true) {
+      const r = await (buffer.shift() as Promise<IteratorResult<T>>);
+      if (r.done) {
+        done = true;
+        return;
+      }
+      pull(); // keep n reads in flight while the consumer works
+      yield r.value;
+    }
+  } finally {
+    if (!done && it.return) {
+      Promise.resolve(it.return()).catch(() => {});
+    }
+  }
+};