@praxisjs/concurrent 1.2.13 → 1.3.0

package/src/__tests__/pool.test.ts

@@ -2,7 +2,20 @@ import { describe, it, expect, vi } from "vitest";
 
 import { pool } from "../pool";
 
-describe("pool", () => {
+/** Abortable delay — rejects with AbortError when signal fires. */
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+    }, { once: true });
+  });
+}
+
+// ── Without AbortSignal (existing behaviour) ───────────────────────────────────
+
+describe("pool — without signal", () => {
   it("executes a task and resolves with its result", async () => {
     const p = pool(2, async (x: unknown) => (x as number) * 3);
     expect(await p(4)).toBe(12);
@@ -11,25 +24,19 @@ describe("pool", () => {
   it("respects concurrency limit", async () => {
     let active = 0;
     let maxActive = 0;
-
     const p = pool(2, async () => {
       active++;
       maxActive = Math.max(maxActive, active);
       await new Promise((r) => setTimeout(r, 10));
       active--;
     });
-
     await Promise.all([p(), p(), p(), p()]);
     expect(maxActive).toBeLessThanOrEqual(2);
   });
 
   it("active() reflects currently running tasks", async () => {
     const resolvers: Array<() => void> = [];
-    const p = pool(
-      3,
-      () => new Promise<void>((r) => resolvers.push(r)),
-    );
-
+    const p = pool(3, () => new Promise<void>((r) => resolvers.push(r)));
     const tasks = [p(), p()];
     expect(p.active()).toBe(2);
     resolvers.forEach((r) => { r(); });
@@ -39,38 +46,42 @@ describe("pool", () => {
 
   it("loading is true when active > 0", async () => {
     let resolve!: () => void;
-    const p = pool(
-      1,
-      () => new Promise<void>((r) => { resolve = r; }),
-    );
-    const task = p();
+    const p = pool(1, () => new Promise<void>((r) => { resolve = r; }));
+    const t = p();
     expect(p.loading()).toBe(true);
     resolve();
-    await task;
+    await t;
     expect(p.loading()).toBe(false);
   });
 
   it("captures errors in the error signal and resolves undefined", async () => {
-    const p = pool(1, async () => {
-      throw new Error("pool error");
-    });
+    const p = pool(1, async () => { throw new Error("pool error"); });
+    expect(await p()).toBeUndefined();
+    expect(p.error()?.message).toBe("pool error");
+  });
+
+  it("wraps non-Error throws in an Error object", async () => {
+    // eslint-disable-next-line @typescript-eslint/only-throw-error
+    const p = pool(1, async () => { throw "plain string error"; });
+    expect(await p()).toBeUndefined();
+    expect(p.error()).toBeInstanceOf(Error);
+    expect(p.error()?.message).toBe("plain string error");
+  });
+
+  it("AbortError thrown by fn itself (no cancelAll) is not stored in error()", async () => {
+    const p = pool(1, async () => { throw new DOMException("Aborted", "AbortError"); });
     const result = await p();
     expect(result).toBeUndefined();
-    expect(p.error()?.message).toBe("pool error");
+    expect(p.error()).toBeNull();
   });
 
   it("pending count decrements as tasks start", async () => {
     let resolveFirst!: () => void;
-    const started: number[] = [];
     const p = pool(1, async (idx: unknown) => {
-      started.push(idx as number);
       if (idx === 0) await new Promise<void>((r) => { resolveFirst = r; });
     });
-
     const t1 = p(0);
     const t2 = p(1);
-
-    // second task is pending while first runs
     expect(p.pending()).toBe(1);
     resolveFirst();
     await t1;
@@ -78,127 +89,124 @@ describe("pool", () => {
     expect(p.pending()).toBe(0);
   });
 
-  it("wraps non-Error throws in an Error object", async () => {
-    const p = pool(1, async () => {
-      // eslint-disable-next-line @typescript-eslint/only-throw-error
-      throw "plain string error";
-    });
-    const result = await p();
-    expect(result).toBeUndefined();
-    expect(p.error()).toBeInstanceOf(Error);
-    expect(p.error()?.message).toBe("plain string error");
-  });
-
   it("concurrency=1 guarantees serial execution", async () => {
     const order: number[] = [];
     let resolveFirst!: () => void;
-
     const p = pool(1, async (n: unknown) => {
       if (n === 0) await new Promise<void>((r) => { resolveFirst = r; });
       order.push(n as number);
     });
-
     const t1 = p(0);
     const t2 = p(1);
-
-    // t2 cannot start until t1 finishes
     expect(p.active()).toBe(1);
     expect(p.pending()).toBe(1);
-
     resolveFirst();
     await t1;
     await t2;
-
-    expect(order).toEqual([0, 1]); // serial order preserved
+    expect(order).toEqual([0, 1]);
   });
 
   it("error in one task does not block subsequent tasks", async () => {
-    const results: Array<number | undefined> = [];
     const p = pool(1, async (n: unknown) => {
       if (n === 0) throw new Error("task 0 failed");
       return n as number;
     });
-
-    const r0 = p(0);
-    const r1 = p(1);
-
-    results.push(await r0);
-    results.push(await r1);
-
-    expect(results[0]).toBeUndefined(); // error → undefined
-    expect(results[1]).toBe(1);         // subsequent task ran
+    expect(await p(0)).toBeUndefined();
+    expect(await p(1)).toBe(1);
   });
 
-  it("concurrency=0 — clamps to 1, tasks execute serially", async () => {
+  it("concurrency=0 — clamps to 1", async () => {
     const fn = vi.fn(async () => "result");
     const p = pool(0, fn);
-
-    // concurrency=0 is clamped to 1, so the task runs immediately
-    const result = await p();
+    expect(await p()).toBe("result");
     expect(fn).toHaveBeenCalledOnce();
-    expect(result).toBe("result");
+  });
+
+  it("cancelAll() when idle — no-op, no crash", () => {
+    const p = pool(2, async () => "ok");
+    expect(() => p.cancelAll()).not.toThrow();
     expect(p.pending()).toBe(0);
-    expect(p.loading()).toBe(false);
+    expect(p.active()).toBe(0);
   });
+});
+
+// ── With AbortSignal (opt-in via first param named "signal") ──────────────────
 
-  it("active() never exceeds concurrency", async () => {
-    const concurrency = 2;
-    let maxObservedActive = 0;
+describe("pool — with signal", () => {
+  it("passes a live AbortSignal to fn", async () => {
+    let capturedSignal!: AbortSignal;
+    const p = pool(1, async (signal) => { capturedSignal = signal as AbortSignal; });
+    await p();
+    expect(capturedSignal).toBeInstanceOf(AbortSignal);
+    expect(capturedSignal.aborted).toBe(false);
+  });
 
-    const p = pool(concurrency, async () => {
-      maxObservedActive = Math.max(maxObservedActive, p.active());
-      await new Promise((r) => setTimeout(r, 5));
+  it("executes tasks and passes correct args alongside signal", async () => {
+    const p = pool(2, async (signal, x: unknown) => { void (signal as AbortSignal); return (x as number) * 3; });
+    expect(await p(4)).toBe(12);
+  });
+
+  it("cancelAll() aborts all active signals", async () => {
+    const signals: AbortSignal[] = [];
+    const resolvers: Array<() => void> = [];
+    const p = pool(3, async (signal) => {
+      signals.push(signal as AbortSignal);
+      await new Promise<void>((r) => resolvers.push(r));
     });
+    const t1 = p();
+    const t2 = p();
+    const t3 = p();
+    await Promise.resolve();
+    p.cancelAll();
+    resolvers.forEach((r) => r());
+    await Promise.all([t1, t2, t3]);
+    expect(signals.every((s) => s.aborted)).toBe(true);
+  });
 
-    await Promise.all([p(), p(), p(), p()]);
-    expect(maxObservedActive).toBeLessThanOrEqual(concurrency);
+  it("cancelAll() resolves active tasks as undefined without setting error()", async () => {
+    const p = pool(1, async (signal) => { await delay(10000, signal as AbortSignal); });
+    const t = p();
+    await Promise.resolve();
+    p.cancelAll();
+    expect(await t).toBeUndefined();
+    expect(p.error()).toBeNull();
+    expect(p.active()).toBe(0);
   });
 
-  it("pool(-5, fn) — clamps to 1, runs tasks serially", async () => {
-    const order: number[] = [];
+  it("cancelAll() resolves pending tasks as undefined", async () => {
     let resolveFirst!: () => void;
-
-    const p = pool(-5, async (n: unknown) => {
-      if (n === 0) await new Promise<void>((r) => { resolveFirst = r; });
-      order.push(n as number);
+    const p = pool(1, async (signal, idx: unknown) => {
+      void (signal as AbortSignal);
+      if (idx === 0) await new Promise<void>((r) => { resolveFirst = r; });
     });
-
     const t1 = p(0);
     const t2 = p(1);
-
-    expect(p.active()).toBe(1);
-    expect(p.pending()).toBe(1);
-
+    const t3 = p(2);
+    await Promise.resolve();
+    p.cancelAll();
     resolveFirst();
-    await t1;
-    await t2;
-
-    expect(order).toEqual([0, 1]);
-  });
-
-  it("multiple tasks error — error signal reflects last error", async () => {
-    let callCount = 0;
-    const p = pool(1, async () => {
-      callCount++;
-      throw new Error(`error ${callCount}`);
-    });
-
-    await p();
-    await p();
-    await p();
-
-    expect(p.error()?.message).toBe("error 3");
+    const [r1, r2, r3] = await Promise.all([t1, t2, t3]);
+    expect(r1).toBeUndefined();
+    expect(r2).toBeUndefined();
+    expect(r3).toBeUndefined();
+    expect(p.pending()).toBe(0);
+    expect(p.error()).toBeNull();
   });
 
-  it("active() never goes negative even if task throws synchronously", async () => {
-    const p = pool(2, async () => {
-      throw new Error("sync-ish throw");
+  it("cancelAll() then new runs work normally", async () => {
+    let resolve!: () => void;
+    const p = pool(1, async (signal, which: unknown) => {
+      void (signal as AbortSignal);
+      if (which === "stale") await new Promise<void>((r) => { resolve = r; });
+      return which as string;
     });
-
-    await p();
-    await p();
-
-    expect(p.active()).toBeGreaterThanOrEqual(0);
+    const stale = p("stale");
+    await Promise.resolve();
+    p.cancelAll();
+    resolve();
+    await stale;
+    expect(await p("fresh")).toBe("fresh");
     expect(p.active()).toBe(0);
+    expect(p.error()).toBeNull();
   });
 });

package/src/__tests__/queue.test.ts

@@ -2,28 +2,35 @@ import { describe, it, expect } from "vitest";
 
 import { queue, QueueClearedError } from "../queue";
 
-describe("queue", () => {
+/** Abortable delay — rejects with AbortError when signal fires. */
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+    }, { once: true });
+  });
+}
+
+// ── Without AbortSignal (existing behaviour) ───────────────────────────────────
+
+describe("queue — without signal", () => {
   it("executes the task and resolves the promise", async () => {
     const q = queue(async (x: unknown) => (x as number) * 2);
-    const result = await q(5);
-    expect(result).toBe(10);
+    expect(await q(5)).toBe(10);
   });
 
   it("runs tasks sequentially (FIFO)", async () => {
     const order: number[] = [];
-    const q = queue(async (n: unknown) => {
-      order.push(n as number);
-      return n as number;
-    });
+    const q = queue(async (n: unknown) => { order.push(n as number); return n as number; });
     await Promise.all([q(1), q(2), q(3)]);
     expect(order).toEqual([1, 2, 3]);
   });
 
   it("loading is true while running, false when done", async () => {
     let resolve!: () => void;
-    const q = queue(
-      () => new Promise<void>((r) => { resolve = r; }),
-    );
+    const q = queue(() => new Promise<void>((r) => { resolve = r; }));
     const p = q();
     expect(q.loading()).toBe(true);
     resolve();
@@ -33,39 +40,29 @@ describe("queue", () => {
 
   it("pending decrements as tasks complete", async () => {
     let resolveFirst!: () => void;
-    const q = queue(
-      (_: unknown, idx: unknown) =>
-        idx === 0
-          ? new Promise<void>((r) => { resolveFirst = r; })
-          : Promise.resolve(),
+    const q = queue((_: unknown, idx: unknown) =>
+      idx === 0
+        ? new Promise<void>((r) => { resolveFirst = r; })
+        : Promise.resolve(),
     );
-
     const p1 = q(null, 0);
     const p2 = q(null, 1);
-
-    // Both enqueued — first is running, second is pending
     expect(q.pending()).toBeGreaterThanOrEqual(0);
-
     resolveFirst();
     await p1;
     await p2;
-
     expect(q.pending()).toBe(0);
   });
 
   it("captures errors in the error signal", async () => {
-    const q = queue(async () => {
-      throw new Error("boom");
-    });
+    const q = queue(async () => { throw new Error("boom"); });
     await expect(q()).rejects.toThrow("boom");
     expect(q.error()?.message).toBe("boom");
   });
 
   it("wraps non-Error throws in an Error", async () => {
-    const q = queue(async () => {
-      // eslint-disable-next-line @typescript-eslint/no-throw-literal
-      throw "string error";
-    });
+    // eslint-disable-next-line @typescript-eslint/no-throw-literal
+    const q = queue(async () => { throw "string error"; });
     await expect(q()).rejects.toThrow("string error");
     expect(q.error()?.message).toBe("string error");
   });
@@ -75,81 +72,43 @@ describe("queue", () => {
       if (n === 0) throw new Error("task 0 failed");
       return n as number;
     });
-
-    const p0 = q(0); // will reject
-    const p1 = q(1); // should still run despite p0 failing
+    const p0 = q(0);
+    const p1 = q(1);
     const p2 = q(2);
-
     await expect(p0).rejects.toThrow("task 0 failed");
     expect(await p1).toBe(1);
     expect(await p2).toBe(2);
-    expect(q.error()?.message).toBe("task 0 failed");
   });
 
-  it("clear() empties the pending queue", async () => {
+  it("clear() with pending tasks rejects their promises with QueueClearedError", async () => {
     let resolveFirst!: () => void;
-    const q = queue(
-      (_: unknown, idx: unknown) =>
-        idx === 0
-          ? new Promise<void>((r) => { resolveFirst = r; })
-          : Promise.resolve(),
+    const q = queue((_: unknown, idx: unknown) =>
+      idx === 0
+        ? new Promise<void>((r) => { resolveFirst = r; })
+        : Promise.resolve(),
     );
-
     q(null, 0);
     const p1 = q(null, 1);
     const p2 = q(null, 2);
-
-    // Suppress expected rejections from clear()
-    p1.catch(() => undefined);
-    p2.catch(() => undefined);
-
     q.clear();
-    resolveFirst();
-
-    // After clearing, pending count should be 0
-    expect(q.pending()).toBe(0);
-  });
-
-  it("clear() with pending tasks rejects their promises with QueueClearedError", async () => {
-    let resolveFirst!: () => void;
-    const q = queue(
-      (_: unknown, idx: unknown) =>
-        idx === 0
-          ? new Promise<void>((r) => { resolveFirst = r; })
-          : Promise.resolve(),
-    );
-
-    q(null, 0); // running — not in _queue
-    const p1 = q(null, 1); // pending — in _queue
-    const p2 = q(null, 2); // pending — in _queue
-
-    q.clear();
-
     await expect(p1).rejects.toBeInstanceOf(QueueClearedError);
     await expect(p2).rejects.toBeInstanceOf(QueueClearedError);
-
     resolveFirst();
   });
 
   it("clear() then new enqueue() — queue works normally after being cleared", async () => {
     let resolveFirst!: () => void;
-    const q = queue(
-      (n: unknown, stall: unknown) =>
-        stall
-          ? new Promise<number>((r) => { resolveFirst = () => r(n as number); })
-          : Promise.resolve(n as number),
+    const q = queue((n: unknown, stall: unknown) =>
+      stall
+        ? new Promise<number>((r) => { resolveFirst = () => r(n as number); })
+        : Promise.resolve(n as number),
     );
-
-    q(0, true); // running — stalls
-    const p1 = q(1, false); // pending
+    q(0, true);
+    const p1 = q(1, false);
     q.clear();
-
     await expect(p1).rejects.toBeInstanceOf(QueueClearedError);
     resolveFirst();
-
-    // Queue should work normally after clearing
-    const result = await q(42, false);
-    expect(result).toBe(42);
+    expect(await q(42, false)).toBe(42);
     expect(q.pending()).toBe(0);
   });
 
@@ -159,50 +118,80 @@ describe("queue", () => {
     expect(q.pending()).toBe(0);
   });
 
-  it("error in task does not corrupt pending counter", async () => {
-    const q = queue(async (n: unknown) => {
-      if (n === 0) throw new Error("bad");
-      return n as number;
-    });
-
-    const p0 = q(0);
-    const p1 = q(1);
-    const p2 = q(2);
-
-    await expect(p0).rejects.toThrow("bad");
-    expect(await p1).toBe(1);
-    expect(await p2).toBe(2);
+  it("very large queue (100 tasks) — all execute in order", async () => {
+    const order: number[] = [];
+    const q = queue(async (n: unknown) => { order.push(n as number); return n as number; });
+    await Promise.all(Array.from({ length: 100 }, (_, i) => q(i)));
+    expect(order).toEqual(Array.from({ length: 100 }, (_, i) => i));
     expect(q.pending()).toBe(0);
   });
+});
 
-  it("multiple tasks error — only last error stored", async () => {
-    const q = queue(async (n: unknown) => {
-      throw new Error(`error ${n as number}`);
-    });
-
-    const p0 = q(0);
-    const p1 = q(1);
-    const p2 = q(2);
+// ── With AbortSignal (opt-in via first param named "signal") ──────────────────
 
-    await expect(p0).rejects.toThrow("error 0");
-    await expect(p1).rejects.toThrow("error 1");
-    await expect(p2).rejects.toThrow("error 2");
+describe("queue — with signal", () => {
+  it("passes a live AbortSignal to fn", async () => {
+    let capturedSignal!: AbortSignal;
+    const q = queue(async (signal) => { capturedSignal = signal as AbortSignal; });
+    await q();
+    expect(capturedSignal).toBeInstanceOf(AbortSignal);
+    expect(capturedSignal.aborted).toBe(false);
+  });
 
-    // Only the last error is stored
-    expect(q.error()?.message).toBe("error 2");
+  it("executes tasks and passes correct args alongside signal", async () => {
+    const q = queue(async (signal, x: unknown) => { void (signal as AbortSignal); return (x as number) * 2; });
+    expect(await q(5)).toBe(10);
   });
 
-  it("very large queue (100 tasks, concurrency=1) — all execute in order", async () => {
-    const order: number[] = [];
-    const q = queue(async (n: unknown) => {
-      order.push(n as number);
-      return n as number;
+  it("clear() aborts the running item's signal", async () => {
+    let capturedSignal!: AbortSignal;
+    let resolve!: () => void;
+    const q = queue(async (signal) => {
+      capturedSignal = signal as AbortSignal;
+      await new Promise<void>((r) => { resolve = r; });
     });
+    const p = q();
+    p.catch(() => undefined);
+    await Promise.resolve(); // let drain start
+    q.clear();
+    resolve();
+    await p.catch(() => undefined);
+    expect(capturedSignal.aborted).toBe(true);
+  });
 
-    const tasks = Array.from({ length: 100 }, (_, i) => q(i));
-    await Promise.all(tasks);
+  it("clear() rejects the running item with QueueClearedError", async () => {
+    const q = queue(async (signal) => { await delay(10000, signal as AbortSignal); });
+    const p = q();
+    await Promise.resolve();
+    q.clear();
+    await expect(p).rejects.toBeInstanceOf(QueueClearedError);
+  });
 
-    expect(order).toEqual(Array.from({ length: 100 }, (_, i) => i));
-    expect(q.pending()).toBe(0);
+  it("AbortError from clear() is not stored in error()", async () => {
+    const q = queue(async (signal) => { await delay(10000, signal as AbortSignal); });
+    const p = q();
+    await Promise.resolve();
+    q.clear();
+    await p.catch(() => undefined);
+    expect(q.error()).toBeNull();
+  });
+
+  it("each pending item gets its own AbortSignal, all aborted on clear()", async () => {
+    const signals: AbortSignal[] = [];
+    let resolveFirst!: () => void;
+    const q = queue(async (signal, idx: unknown) => {
+      signals.push(signal as AbortSignal);
+      if (idx === 0) await new Promise<void>((r) => { resolveFirst = r; });
+    });
+    const p0 = q(0);
+    const p1 = q(1);
+    const p2 = q(2);
+    p1.catch(() => undefined);
+    p2.catch(() => undefined);
+    await Promise.resolve();
+    q.clear();
+    resolveFirst();
+    await Promise.all([p0.catch(() => undefined), p1.catch(() => undefined), p2.catch(() => undefined)]);
+    expect(signals[0]?.aborted).toBe(true);
   });
 });