feat(async/unstable): add support for AbortSignal in pooledMap

async/deno.json

@@ -10,6 +10,7 @@
     "./mux-async-iterator": "./mux_async_iterator.ts",
     "./unstable-mux-async-iterator": "./unstable_mux_async_iterator.ts",
     "./pool": "./pool.ts",
+    "./unstable-pool": "./unstable_pool.ts",
     "./retry": "./retry.ts",
     "./unstable-retry": "./unstable_retry.ts",
     "./tee": "./tee.ts",

async/unstable_pool.ts

@@ -0,0 +1,182 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+
+/** Error message emitted from the thrown error while mapping. */
+const ERROR_WHILE_MAPPING_MESSAGE =
+  "Cannot complete the mapping as an error was thrown from an item";
+
+/** Options for {@linkcode pooledMap}. */
+export interface PooledMapOptions {
+  /**
+   * The maximum count of items being processed concurrently.
+   */
+  poolLimit: number;
+  /**
+   * An AbortSignal to cancel the pooled mapping operation.
+   *
+   * If the signal is aborted, no new items will begin processing. All currently
+   * executing items are allowed to finish. The iterator then rejects with the
+   * signal's reason.
+   *
+   * @default {undefined}
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Transforms values from an (async) iterable into another async iterable.
+ * The transforms are done concurrently, with a max concurrency defined by
+ * {@linkcode PooledMapOptions.poolLimit}.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * If an error is thrown from `iteratorFn`, no new transformations will begin.
+ * All currently executing transformations are allowed to finish and still
+ * yielded on success. After that, the rejections among them are gathered and
+ * thrown by the iterator in an `AggregateError`.
+ *
+ * @example Usage
+ * ```ts
+ * import { pooledMap } from "@std/async/unstable-pool";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const results = pooledMap(
+ *   [1, 2, 3],
+ *   (i) => new Promise((r) => setTimeout(() => r(i), 1000)),
+ *   { poolLimit: 2 },
+ * );
+ *
+ * assertEquals(await Array.fromAsync(results), [1, 2, 3]);
+ * ```
+ *
+ * @example Cancellation with AbortSignal
+ * ```ts
+ * import { pooledMap } from "@std/async/unstable-pool";
+ * import { assertRejects } from "@std/assert";
+ *
+ * const controller = new AbortController();
+ * const results = pooledMap(
+ *   [1, 2, 3, 4, 5],
+ *   (i) => new Promise((r) => setTimeout(() => r(i), 1000)),
+ *   { poolLimit: 2, signal: controller.signal },
+ * );
+ *
+ * controller.abort(new Error("cancelled"));
+ *
+ * await assertRejects(
+ *   () => Array.fromAsync(results),
+ *   Error,
+ *   "cancelled",
+ * );
+ * ```
+ *
+ * @typeParam T the input type.
+ * @typeParam R the output type.
+ * @param array The input array for mapping.
+ * @param iteratorFn The function to call for every item of the array.
+ * @param options Options including pool limit and abort signal.
+ * @returns The async iterator with the transformed values.
+ */
+export function pooledMap<T, R>(
+  array: Iterable<T> | AsyncIterable<T>,
+  iteratorFn: (data: T) => Promise<R>,
+  options: PooledMapOptions,
+): AsyncIterableIterator<R> {
+  const { poolLimit, signal } = options;
+
+  if (!Number.isInteger(poolLimit) || poolLimit < 1) {
+    throw new RangeError("'poolLimit' must be a positive integer");
+  }
+
+  const res = new TransformStream<Promise<R>, R>({
+    async transform(
+      p: Promise<R>,
+      controller: TransformStreamDefaultController<R>,
+    ) {
+      try {
+        const s = await p;
+        controller.enqueue(s);
+      } catch (e) {
+        if (signal?.aborted) {
+          controller.error(signal.reason);
+        } else if (
+          e instanceof AggregateError &&
+          e.message === ERROR_WHILE_MAPPING_MESSAGE
+        ) {
+          controller.error(e as unknown);
+        }
+      }
+    },
+  });
+
+  (async () => {
+    const writer = res.writable.getWriter();
+    const executing: Array<Promise<unknown>> = [];
+
+    function raceWithSignal(
+      promises: Array<Promise<unknown>>,
+    ): Promise<unknown> {
+      if (!signal) return Promise.race(promises);
+      const { promise, resolve, reject } = Promise.withResolvers<never>();
+      const onAbort = () => reject(signal.reason);
+      signal.addEventListener("abort", onAbort, { once: true });
+      return Promise.race([...promises, promise]).finally(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(undefined as never);
+      });
+    }
+
+    try {
+      signal?.throwIfAborted();
+
+      for await (const item of array) {
+        signal?.throwIfAborted();
+
+        const p = Promise.resolve().then(() => iteratorFn(item));
+        // Only write on success. If we `writer.write()` a rejected promise,
+        // that will end the iteration. We don't want that yet. Instead let it
+        // fail the race, taking us to the catch block where all currently
+        // executing jobs are allowed to finish and all rejections among them
+        // can be reported together.
+        writer.write(p);
+        const e: Promise<unknown> = p.then(() =>
+          executing.splice(executing.indexOf(e), 1)
+        );
+        executing.push(e);
+        if (executing.length >= poolLimit) {
+          await raceWithSignal(executing);
+        }
+      }
+      await Promise.all(executing);
+      writer.close();
+    } catch {
+      const errors = [];
+      for (const result of await Promise.allSettled(executing)) {
+        if (result.status === "rejected") {
+          errors.push(result.reason);
+        }
+      }
+      if (signal?.aborted) {
+        writer.write(Promise.reject(signal.reason)).catch(() => {});
+      } else {
+        writer.write(Promise.reject(
+          new AggregateError(errors, ERROR_WHILE_MAPPING_MESSAGE),
+        )).catch(() => {});
+      }
+    }
+  })();
+
+  // Feature test until browser coverage is adequate
+  return Symbol.asyncIterator in res.readable &&
+      typeof res.readable[Symbol.asyncIterator] === "function"
+    ? (res.readable[Symbol.asyncIterator] as () => AsyncIterableIterator<R>)()
+    : (async function* () {
+      const reader = res.readable.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield value;
+      }
+      reader.releaseLock();
+    })();
+}

async/unstable_pool_test.ts

@@ -0,0 +1,202 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+import { pooledMap } from "./unstable_pool.ts";
+import {
+  assertEquals,
+  assertGreaterOrEqual,
+  assertLess,
+  assertRejects,
+  assertStringIncludes,
+  assertThrows,
+} from "@std/assert";
+import { delay } from "./delay.ts";
+import { FakeTime } from "@std/testing/time";
+
+Deno.test("pooledMap() throws for non-positive poolLimit", () => {
+  const noop = (i: number) => Promise.resolve(i);
+  assertThrows(
+    () => pooledMap([1], noop, { poolLimit: 0 }),
+    RangeError,
+    "'poolLimit' must be a positive integer",
+  );
+  assertThrows(
+    () => pooledMap([1], noop, { poolLimit: -1 }),
+    RangeError,
+    "'poolLimit' must be a positive integer",
+  );
+});
+
+Deno.test("pooledMap() throws for non-integer poolLimit", () => {
+  const noop = (i: number) => Promise.resolve(i);
+  assertThrows(
+    () => pooledMap([1], noop, { poolLimit: 1.5 }),
+    RangeError,
+    "'poolLimit' must be a positive integer",
+  );
+  assertThrows(
+    () => pooledMap([1], noop, { poolLimit: NaN }),
+    RangeError,
+    "'poolLimit' must be a positive integer",
+  );
+  assertThrows(
+    () => pooledMap([1], noop, { poolLimit: Infinity }),
+    RangeError,
+    "'poolLimit' must be a positive integer",
+  );
+});
+
+Deno.test("pooledMap()", async () => {
+  using time = new FakeTime();
+
+  const start = Date.now();
+  const results = pooledMap(
+    [1, 2, 3],
+    (i) => new Promise<number>((r) => setTimeout(() => r(i), 300)),
+    { poolLimit: 2 },
+  );
+  for (const _ of Array(7)) {
+    time.tick(100);
+    await time.runMicrotasks();
+  }
+  const array = await Array.fromAsync(results);
+  assertEquals(array, [1, 2, 3]);
+  const diff = Date.now() - start;
+
+  assertGreaterOrEqual(diff, 600);
+  assertLess(diff, 900);
+});
+
+Deno.test("pooledMap() handles errors", async () => {
+  async function mapNumber(n: number): Promise<number> {
+    if (n <= 2) {
+      throw new Error(`Bad number: ${n}`);
+    }
+    await delay(100);
+    return n;
+  }
+  const mappedNumbers: number[] = [];
+  const error = await assertRejects(
+    async () => {
+      for await (
+        const m of pooledMap([1, 2, 3, 4], mapNumber, { poolLimit: 3 })
+      ) {
+        mappedNumbers.push(m);
+      }
+    },
+    AggregateError,
+    "Cannot complete the mapping as an error was thrown from an item",
+  );
+  assertEquals(error.errors.length, 2);
+  assertStringIncludes(error.errors[0].stack, "Error: Bad number: 1");
+  assertStringIncludes(error.errors[1].stack, "Error: Bad number: 2");
+  assertEquals(mappedNumbers, [3]);
+});
+
+Deno.test("pooledMap() returns ordered items", async () => {
+  const results = pooledMap(
+    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    (i) => new Promise<number>((r) => setTimeout(() => r(i), 100 / i)),
+    { poolLimit: 2 },
+  );
+
+  const returned = await Array.fromAsync(results);
+  assertEquals(returned, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+});
+
+Deno.test("pooledMap() checks browser compat", async () => {
+  const asyncIterFunc = ReadableStream.prototype[Symbol.asyncIterator];
+  // deno-lint-ignore no-explicit-any
+  delete (ReadableStream.prototype as any)[Symbol.asyncIterator];
+  try {
+    const results = pooledMap(
+      [1, 2, 3],
+      (i) => new Promise<number>((r) => setTimeout(() => r(i), 100)),
+      { poolLimit: 2 },
+    );
+    const array = await Array.fromAsync(results);
+    assertEquals(array, [1, 2, 3]);
+  } finally {
+    ReadableStream.prototype[Symbol.asyncIterator] = asyncIterFunc;
+  }
+});
+
+Deno.test("pooledMap() rejects immediately with already-aborted signal", async () => {
+  const controller = new AbortController();
+  controller.abort(new Error("already aborted"));
+
+  const results = pooledMap(
+    [1, 2, 3],
+    (i) => Promise.resolve(i),
+    { poolLimit: 2, signal: controller.signal },
+  );
+
+  await assertRejects(
+    () => Array.fromAsync(results),
+    Error,
+    "already aborted",
+  );
+});
+
+Deno.test("pooledMap() stops processing when signal is aborted", async () => {
+  const controller = new AbortController();
+  const started: number[] = [];
+
+  const results = pooledMap(
+    [1, 2, 3, 4, 5],
+    async (i) => {
+      started.push(i);
+      await delay(50);
+      if (i === 2) controller.abort(new Error("stop at 2"));
+      return i;
+    },
+    { poolLimit: 1, signal: controller.signal },
+  );
+
+  const collected: number[] = [];
+  await assertRejects(
+    async () => {
+      for await (const value of results) {
+        collected.push(value);
+      }
+    },
+    Error,
+    "stop at 2",
+  );
+
+  assertGreaterOrEqual(started.length, 2);
+  assertLess(started.length, 5);
+});
+
+Deno.test("pooledMap() aborts during pool wait", async () => {
+  const controller = new AbortController();
+
+  const results = pooledMap(
+    [1, 2, 3, 4, 5, 6, 7, 8],
+    async (i) => {
+      await delay(200);
+      return i;
+    },
+    { poolLimit: 2, signal: controller.signal },
+  );
+
+  setTimeout(() => controller.abort(new Error("timed out")), 50);
+
+  await assertRejects(
+    () => Array.fromAsync(results),
+    Error,
+    "timed out",
+  );
+});
+
+Deno.test("pooledMap() works normally without signal", async () => {
+  const results = pooledMap(
+    [10, 20, 30],
+    async (i) => {
+      await delay(10);
+      return i * 2;
+    },
+    { poolLimit: 2 },
+  );
+
+  const array = await Array.fromAsync(results);
+  assertEquals(array, [20, 40, 60]);
+});