@praxisjs/concurrent 1.2.12 → 1.3.0

package/src/__tests__/task.test.ts

@@ -2,7 +2,20 @@ import { describe, it, expect } from "vitest";
 
 import { task } from "../task";
 
-describe("task", () => {
+/** 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("task — without signal", () => {
   it("resolves with the function result", async () => {
     const t = task(async (x: unknown) => (x as number) + 1);
     expect(await t(9)).toBe(10);
@@ -26,9 +39,7 @@ describe("task", () => {
   });
 
   it("captures errors in the error signal", async () => {
-    const t = task(async () => {
-      throw new Error("task failed");
-    });
+    const t = task(async () => { throw new Error("task failed"); });
     const result = await t();
     expect(result).toBeUndefined();
     expect(t.error()?.message).toBe("task failed");
@@ -41,8 +52,6 @@ describe("task", () => {
       return "ok";
     });
     await t();
-    expect(t.error()).not.toBeNull();
-
     shouldFail = false;
     await t();
     expect(t.error()).toBeNull();
@@ -52,148 +61,145 @@ describe("task", () => {
   it("cancelAll() discards in-flight results", async () => {
     let resolve!: (v: string) => void;
     const t = task(() => new Promise<string>((r) => { resolve = r; }));
-
     const p = t();
     t.cancelAll();
     resolve("stale");
-    const result = await p;
-
-    expect(result).toBeUndefined();
+    expect(await p).toBeUndefined();
     expect(t.loading()).toBe(false);
   });
 
   it("cancelAll() during a failing task discards the error", async () => {
     let reject!: (err: unknown) => void;
     const t = task(() => new Promise<string>((_res, rej) => { reject = rej; }));
-
     const p = t();
     t.cancelAll();
     reject(new Error("cancelled"));
-    const result = await p;
-
-    // The error was from a stale run — result is undefined, no error stored
-    expect(result).toBeUndefined();
+    expect(await p).toBeUndefined();
     expect(t.error()).toBeNull();
   });
 
   it("wraps non-Error throws in an Error object", async () => {
-    const t = task(async () => {
-      // eslint-disable-next-line @typescript-eslint/only-throw-error
-      throw "string-error";
-    });
-    const result = await t();
-    expect(result).toBeUndefined();
+    // eslint-disable-next-line @typescript-eslint/only-throw-error
+    const t = task(async () => { throw "string-error"; });
+    await t();
     expect(t.error()).toBeInstanceOf(Error);
     expect(t.error()?.message).toBe("string-error");
   });
 
+  it("AbortError thrown by fn itself (no cancelAll) is not stored in error()", async () => {
+    const t = task(async () => { throw new DOMException("Aborted", "AbortError"); });
+    const result = await t();
+    expect(result).toBeUndefined();
+    expect(t.error()).toBeNull();
+    expect(t.loading()).toBe(false);
+  });
+
   it("second run while first is pending discards the first result", async () => {
     let resolveFirst!: (v: string) => void;
     let resolveSecond!: (v: string) => void;
-
-    const t = task((_run: unknown) =>
-      (_run === 1
+    const t = task((run: unknown) =>
+      run === 1
         ? new Promise<string>((r) => { resolveFirst = r; })
-        : new Promise<string>((r) => { resolveSecond = r; })),
+        : new Promise<string>((r) => { resolveSecond = r; }),
     );
-
     let run = 1;
-    const p1 = t(run++);  // run 1
-    const p2 = t(run++);  // run 2 — increments _runId, making run 1 stale
-
+    const p1 = t(run++);
+    const p2 = t(run++);
     resolveSecond("result-2");
-    resolveFirst("result-1"); // stale
-
+    resolveFirst("result-1");
     const [r1, r2] = await Promise.all([p1, p2]);
     expect(r2).toBe("result-2");
-    expect(r1).toBeUndefined(); // stale run discarded
+    expect(r1).toBeUndefined();
     expect(t.lastResult()).toBe("result-2");
   });
 
   it("synchronous function (non-async) resolves correctly via await", async () => {
-    // await on a non-Promise simply resolves the value
     const t = task((() => 42) as unknown as () => Promise<number>);
-    const result = await t();
-    expect(result).toBe(42);
+    expect(await t()).toBe(42);
     expect(t.lastResult()).toBe(42);
-    expect(t.loading()).toBe(false);
   });
+});
 
-  it("cancelAll() followed by a new run works correctly", async () => {
-    const t = task(async () => "fresh");
-    let resolve!: (v: string) => void;
-    const staleTask = task(() => new Promise<string>((r) => { resolve = r; }));
+// ── With AbortSignal (opt-in via first param named "signal") ──────────────────
 
-    const p = staleTask();
-    staleTask.cancelAll();
-    resolve("stale");
-    await p;
+describe("task — with signal", () => {
+  it("resolves with the function result", async () => {
+    const t = task(async (signal, x: unknown) => { void (signal as AbortSignal); return (x as number) + 1; });
+    expect(await t(9)).toBe(10);
+  });
 
-    // Now run a fresh task after cancelAll
-    const result = await t();
-    expect(result).toBe("fresh");
-    expect(t.loading()).toBe(false);
+  it("passes a live AbortSignal to fn", async () => {
+    let capturedSignal!: AbortSignal;
+    const t = task(async (signal) => { capturedSignal = signal as AbortSignal; return "done"; });
+    await t();
+    expect(capturedSignal).toBeInstanceOf(AbortSignal);
+    expect(capturedSignal.aborted).toBe(false);
   });
 
-  it("two concurrent calls — second result wins when first is slower", async () => {
-    let resolveFirst!: (v: string) => void;
-    let resolveSecond!: (v: string) => void;
+  it("new run aborts the previous signal", async () => {
+    const signals: AbortSignal[] = [];
+    let resolveFirst!: () => void;
+    const t = task(async (signal) => {
+      signals.push(signal as AbortSignal);
+      if (signals.length === 1) await new Promise<void>((r) => { resolveFirst = r; });
+      return signals.length;
+    });
+    const p1 = t();
+    const p2 = t();
+    resolveFirst();
+    await Promise.all([p1, p2]);
+    expect(signals[0].aborted).toBe(true);
+    expect(signals[1].aborted).toBe(false);
+  });
 
-    const t = task((which: unknown) =>
-      which === "first"
-        ? new Promise<string>((r) => { resolveFirst = r; })
-        : new Promise<string>((r) => { resolveSecond = r; }),
-    );
+  it("cancelAll() aborts the current signal", async () => {
+    let capturedSignal!: AbortSignal;
+    let resolve!: () => void;
+    const t = task(async (signal) => {
+      capturedSignal = signal as AbortSignal;
+      await new Promise<void>((r) => { resolve = r; });
+    });
+    const p = t();
+    t.cancelAll();
+    resolve();
+    await p;
+    expect(capturedSignal.aborted).toBe(true);
+  });
 
+  it("AbortError from cancelAll() is not stored in error()", async () => {
+    const t = task(async (signal) => { await delay(10000, signal as AbortSignal); });
+    const p = t();
+    t.cancelAll();
+    await p;
+    expect(t.error()).toBeNull();
+    expect(t.loading()).toBe(false);
+  });
+
+  it("AbortError from a superseded run is not stored in error()", async () => {
+    const t = task(async (signal, which: unknown) => {
+      if (which === "first") await delay(10000, signal as AbortSignal);
+      return which as string;
+    });
     const p1 = t("first");
     const p2 = t("second");
-
-    // second resolves before first
-    resolveSecond("second-result");
-    resolveFirst("first-result");
-
     const [r1, r2] = await Promise.all([p1, p2]);
-    expect(r2).toBe("second-result");
-    expect(r1).toBeUndefined(); // stale
-    expect(t.lastResult()).toBe("second-result");
+    expect(r1).toBeUndefined();
+    expect(r2).toBe("second");
+    expect(t.error()).toBeNull();
   });
 
   it("cancelAll() called, then new call — new call works normally", async () => {
     let resolveStale!: (v: string) => void;
-    const t = task((which: unknown) =>
+    const t = task((signal, which: unknown) =>
       which === "stale"
         ? new Promise<string>((r) => { resolveStale = r; })
         : Promise.resolve("fresh"),
     );
-
     const staleP = t("stale");
     t.cancelAll();
     resolveStale("stale-value");
     await staleP;
-
-    const freshResult = await t("fresh");
-    expect(freshResult).toBe("fresh");
-    expect(t.loading()).toBe(false);
+    expect(await t("fresh")).toBe("fresh");
     expect(t.lastResult()).toBe("fresh");
   });
-
-  it("lastResult is null when task throws (not stale from previous run)", async () => {
-    let shouldThrow = false;
-    const t = task(async () => {
-      if (shouldThrow) throw new Error("fail");
-      return "success";
-    });
-
-    await t();
-    expect(t.lastResult()).toBe("success");
-
-    shouldThrow = true;
-    await t();
-
-    // After a throw, lastResult should remain the previous value
-    // (the error path does not update lastResult)
-    expect(t.error()?.message).toBe("fail");
-    // lastResult is not reset to null on error — it keeps the last successful value
-    expect(t.lastResult()).toBe("success");
-  });
 });

package/src/__tests__/utils.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+
+import { acceptsSignal } from "../utils";
+
+describe("acceptsSignal", () => {
+  it("returns true for a function with 'signal' as first param", () => {
+    expect(acceptsSignal((signal: AbortSignal) => signal)).toBe(true);
+  });
+
+  it("returns true for an async function with 'signal' as first param", () => {
+    expect(acceptsSignal(async (signal: AbortSignal, id: number) => ({ signal, id }))).toBe(true);
+  });
+
+  it("returns true for a named function with 'signal' as first param", () => {
+    function loadUser(signal: AbortSignal) { return signal; }
+    expect(acceptsSignal(loadUser)).toBe(true);
+  });
+
+  it("returns false for a function with no params", () => {
+    expect(acceptsSignal(() => "ok")).toBe(false);
+  });
+
+  it("returns false for a function whose first param is not 'signal'", () => {
+    expect(acceptsSignal((id: number) => id)).toBe(false);
+  });
+
+  it("returns false for _signal (underscore-prefixed)", () => {
+    expect(acceptsSignal((_signal: AbortSignal) => _signal)).toBe(false);
+  });
+
+  it("returns false when fn.toString() contains no parentheses (regex yields no match)", () => {
+    const noParenFn = Object.assign(
+      () => undefined,
+      { toString() { return "no parens here"; } },
+    ) as unknown as () => unknown;
+
+    expect(acceptsSignal(noParenFn)).toBe(false);
+  });
+
+  it("returns false when fn.toString() throws", () => {
+    const badFn = Object.assign(
+      () => undefined,
+      { toString() { throw new Error("no source"); } },
+    ) as unknown as () => unknown;
+
+    expect(acceptsSignal(badFn)).toBe(false);
+  });
+});

package/src/decorators.ts

@@ -4,14 +4,26 @@ import type { Computed } from "@praxisjs/shared";
 import { pool } from "./pool";
 import { queue } from "./queue";
 import { task } from "./task";
+import { acceptsSignal } from "./utils";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyAsyncFn = (this: any, ...args: any[]) => Promise<any>;
 
+/**
+ * Strips the leading AbortSignal from a parameter tuple when present,
+ * so decorated fields expose only the user-visible arguments.
+ *
+ * Examples:
+ *   [AbortSignal, number, string] → [number, string]
+ *   [number, string]              → [number, string]  (unchanged)
+ */
+type DropSignalIfPresent<T extends unknown[]> =
+  T extends [AbortSignal, ...infer R] ? R : T;
+
 // ── Decorated types ────────────────────────────────────────────────────────────
 
 export type TaskDecorated<T extends AnyAsyncFn> =
-  ((...args: Parameters<T>) => ReturnType<T>) & {
+  ((...args: DropSignalIfPresent<Parameters<T>>) => ReturnType<T>) & {
     loading: Computed<boolean>;
     error: Computed<Error | null>;
     lastResult: Computed<Awaited<ReturnType<T>> | null>;
@@ -19,7 +31,7 @@ export type TaskDecorated<T extends AnyAsyncFn> =
   };
 
 export type QueueDecorated<T extends AnyAsyncFn> =
-  ((...args: Parameters<T>) => ReturnType<T>) & {
+  ((...args: DropSignalIfPresent<Parameters<T>>) => ReturnType<T>) & {
     loading: Computed<boolean>;
     pending: Computed<number>;
     error: Computed<Error | null>;
@@ -27,11 +39,12 @@ export type QueueDecorated<T extends AnyAsyncFn> =
   };
 
 export type PoolDecorated<T extends AnyAsyncFn> =
-  ((...args: Parameters<T>) => ReturnType<T>) & {
+  ((...args: DropSignalIfPresent<Parameters<T>>) => ReturnType<T>) & {
     loading: Computed<boolean>;
     active: Computed<number>;
     pending: Computed<number>;
     error: Computed<Error | null>;
+    cancelAll(): void;
   };
 
 // ── Type helpers ───────────────────────────────────────────────────────────────
@@ -51,9 +64,11 @@ export function Task(methodName: string) {
   return createFieldDecorator({
     bind(instance: object, _name: string) {
       const inst = instance as Record<string, AnyAsyncFn>;
+      // Detect signal on the unbound method — bound functions lose their source.
+      const wantsSignal = acceptsSignal(inst[methodName]);
       return {
         descriptor: {
-          value: task(inst[methodName].bind(instance)) as unknown,
+          value: task(inst[methodName].bind(instance), { signal: wantsSignal }) as unknown,
           writable: true,
         },
       };
@@ -67,9 +82,10 @@ export function Queue(methodName: string) {
   return createFieldDecorator({
     bind(instance: object, _name: string) {
       const inst = instance as Record<string, AnyAsyncFn>;
+      const wantsSignal = acceptsSignal(inst[methodName]);
       return {
         descriptor: {
-          value: queue(inst[methodName].bind(instance)) as unknown,
+          value: queue(inst[methodName].bind(instance), { signal: wantsSignal }) as unknown,
           writable: true,
         },
       };
@@ -83,9 +99,10 @@ export function Pool(methodName: string, concurrency = 1) {
   return createFieldDecorator({
     bind(instance: object, _name: string) {
       const inst = instance as Record<string, AnyAsyncFn>;
+      const wantsSignal = acceptsSignal(inst[methodName]);
       return {
         descriptor: {
-          value: pool(concurrency, inst[methodName].bind(instance)) as unknown,
+          value: pool(concurrency, inst[methodName].bind(instance), { signal: wantsSignal }) as unknown,
           writable: true,
         },
       };

package/src/index.ts

@@ -1,2 +1,3 @@
 export { Task, Queue, Pool } from "./decorators";
 export type { TaskDecorated, QueueDecorated, PoolDecorated, TaskOf, QueueOf, PoolOf } from "./decorators";
+export { QueueClearedError } from "./queue";

package/src/pool.ts

@@ -1,49 +1,66 @@
 import { signal, computed } from "@praxisjs/core/internal";
 import type { Computed } from "@praxisjs/shared";
 
+import { acceptsSignal } from "./utils";
+
 export interface PoolInstance<T> {
   (...args: unknown[]): Promise<T | undefined>;
   loading: Computed<boolean>;
   active: Computed<number>;
   pending: Computed<number>;
   error: Computed<Error | null>;
+  cancelAll(): void;
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
 }
 
 export function pool<T>(
   concurrency: number,
   fn: (...args: unknown[]) => Promise<T>,
+  options?: { signal?: boolean },
 ): PoolInstance<T> {
   concurrency = Math.max(1, concurrency);
   const _active = signal(0);
   const _pending = signal(0);
   const _error = signal<Error | null>(null);
+  const _wantsSignal = options?.signal ?? acceptsSignal(fn);
   const _queue: Array<{
     args: unknown[];
     resolve: (v: T | undefined) => void;
+    controller: AbortController;
   }> = [];
+  const _activeControllers = new Set<AbortController>();
 
   async function tryRun(): Promise<void> {
     if (_active() >= concurrency || _queue.length === 0) return;
     const item = _queue[0];
     _queue.shift();
 
-    const { args, resolve } = item;
+    const { args, resolve, controller } = item;
     _pending.update((n) => n - 1);
     _active.update((n) => n + 1);
+    _activeControllers.add(controller);
     try {
-      resolve(await fn(...args));
+      const result = await (_wantsSignal ? fn(controller.signal, ...args) : fn(...args));
+      resolve(result);
     } catch (err) {
-      _error.set(err instanceof Error ? err : new Error(String(err)));
+      if (!isAbortError(err)) {
+        _error.set(err instanceof Error ? err : new Error(String(err)));
+      }
       resolve(undefined);
     } finally {
+      _activeControllers.delete(controller);
       _active.update((n) => n - 1);
       void tryRun();
     }
   }
 
   function run(...args: unknown[]): Promise<T | undefined> {
+    const controller = new AbortController();
     return new Promise<T | undefined>((resolve) => {
-      _queue.push({ args, resolve });
+      _queue.push({ args, resolve, controller });
       _pending.update((n) => n + 1);
       void tryRun();
     });
@@ -53,6 +70,18 @@ export function pool<T>(
   run.active = computed(() => _active());
   run.pending = computed(() => _pending());
   run.error = computed(() => _error());
+  run.cancelAll = () => {
+    for (const c of _activeControllers) {
+      c.abort();
+    }
+    _activeControllers.clear();
+    while (_queue.length > 0) {
+      const item = _queue.shift();
+      item?.controller.abort();
+      item?.resolve(undefined);
+    }
+    _pending.set(0);
+  };
 
   return run as PoolInstance<T>;
 }

package/src/queue.ts

@@ -1,6 +1,8 @@
 import { signal, computed } from "@praxisjs/core/internal";
 import type { Computed } from "@praxisjs/shared";
 
+import { acceptsSignal } from "./utils";
+
 export class QueueClearedError extends Error {
   constructor() {
     super("Queue cleared");
@@ -8,6 +10,10 @@ export class QueueClearedError extends Error {
   }
 }
 
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
 export interface QueueInstance<T> {
   (...args: unknown[]): Promise<T>;
   loading: Computed<boolean>;
@@ -18,17 +24,22 @@ export interface QueueInstance<T> {
 
 export function queue<T>(
   fn: (...args: unknown[]) => Promise<T>,
+  options?: { signal?: boolean },
 ): QueueInstance<T> {
   const _loading = signal(false);
   const _pending = signal(0);
   const _error = signal<Error | null>(null);
+  const _wantsSignal = options?.signal ?? acceptsSignal(fn);
   const _queue: Array<{
     args: unknown[];
     resolve: (v: T) => void;
     reject: (e: Error) => void;
+    controller: AbortController;
   }> = [];
   let _running = false;
   let _cleared = false;
+  let _activeController: AbortController | null = null;
+  let _activeAbortedByClear = false;
 
   async function drain(): Promise<void> {
     if (_running || _queue.length === 0) return;
@@ -38,14 +49,25 @@ export function queue<T>(
       const item = _queue[0];
       _queue.shift();
 
-      const { args, resolve, reject } = item;
+      const { args, resolve, reject, controller } = item;
+      _activeController = controller;
+      _activeAbortedByClear = false;
       _pending.update((n) => n - 1);
       try {
-        resolve(await fn(...args));
+        const result = await (_wantsSignal ? fn(controller.signal, ...args) : fn(...args));
+        resolve(result);
       } catch (err) {
-        const e = err instanceof Error ? err : new Error(String(err));
-        _error.set(e);
-        reject(e);
+        // _activeAbortedByClear is set asynchronously by clear() between the await and this catch
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (isAbortError(err) && _activeAbortedByClear) {
+          reject(new QueueClearedError());
+        } else {
+          const e = err instanceof Error ? err : new Error(String(err));
+          _error.set(e);
+          reject(e);
+        }
+      } finally {
+        _activeController = null;
       }
     }
     _cleared = false;
@@ -57,8 +79,9 @@ export function queue<T>(
     if (_cleared) {
       _cleared = false;
     }
+    const controller = new AbortController();
     return new Promise<T>((resolve, reject) => {
-      _queue.push({ args, resolve, reject });
+      _queue.push({ args, resolve, reject, controller });
       _pending.update((n) => n + 1);
       void drain();
     });
@@ -68,9 +91,14 @@ export function queue<T>(
   enqueue.pending = computed(() => _pending());
   enqueue.error = computed(() => _error());
   enqueue.clear = () => {
-    // Reject all currently queued (not-yet-started) items
+    if (_activeController) {
+      _activeAbortedByClear = true;
+      _activeController.abort();
+    }
     while (_queue.length > 0) {
-      _queue.shift()?.reject(new QueueClearedError());
+      const item = _queue.shift();
+      item?.controller.abort();
+      item?.reject(new QueueClearedError());
     }
     _pending.set(0);
     _cleared = true;

package/src/task.ts

@@ -1,6 +1,8 @@
 import { signal, computed } from "@praxisjs/core/internal";
 import type { Computed } from "@praxisjs/shared";
 
+import { acceptsSignal } from "./utils";
+
 export interface TaskInstance<T> {
   (...args: unknown[]): Promise<T | undefined>;
   loading: Computed<boolean>;
@@ -9,27 +11,39 @@ export interface TaskInstance<T> {
   cancelAll(): void;
 }
 
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
 export function task<T>(
   fn: (...args: unknown[]) => Promise<T>,
+  options?: { signal?: boolean },
 ): TaskInstance<T> {
   const _loading = signal(false);
   const _error = signal<Error | null>(null);
   const _lastResult = signal<T | null>(null);
   let _runId = 0;
+  let _controller: AbortController | null = null;
+  const _wantsSignal = options?.signal ?? acceptsSignal(fn);
 
   async function run(...args: unknown[]): Promise<T | undefined> {
+    _controller?.abort();
+    const controller = new AbortController();
+    _controller = controller;
     const id = ++_runId;
     _loading.set(true);
     _error.set(null);
     try {
-      const result = await fn(...args);
+      const result = await (_wantsSignal ? fn(controller.signal, ...args) : fn(...args));
       if (id !== _runId) return undefined;
       _lastResult.set(result);
       _loading.set(false);
       return result;
     } catch (err) {
       if (id !== _runId) return undefined;
-      _error.set(err instanceof Error ? err : new Error(String(err)));
+      if (!isAbortError(err)) {
+        _error.set(err instanceof Error ? err : new Error(String(err)));
+      }
       _loading.set(false);
       return undefined;
     }
@@ -39,6 +53,8 @@ export function task<T>(
   run.error = computed(() => _error());
   run.lastResult = computed(() => _lastResult());
   run.cancelAll = () => {
+    _controller?.abort();
+    _controller = null;
     _runId++;
     _loading.set(false);
   };