@praxisjs/concurrent 1.3.8 → 1.3.9

package/src/__tests__/decorators.test.ts

@@ -1,267 +0,0 @@
-import { describe, it, expect } from "vitest";
-
-import { Task, Queue, Pool } from "../decorators";
-import { QueueClearedError } from "../queue";
-
-function fieldCtx(name: string) {
-  const initializers: Array<(this: unknown) => void> = [];
-  return {
-    ctx: {
-      name,
-      kind: "field" as const,
-      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
-    } as ClassFieldDecoratorContext,
-    run(instance: unknown) { initializers.forEach((fn) => { fn.call(instance); }); },
-  };
-}
-
-// ── Task ──────────────────────────────────────────────────────────────────────
-
-describe("Task decorator", () => {
-  it("wraps the named method and exposes signals as sub-properties", async () => {
-    const { ctx, run } = fieldCtx("taskLoad");
-    Task("load")(undefined, ctx);
-
-    const instance: Record<string, unknown> = {
-      load: async (x: unknown) => (x as number) * 2,
-    };
-    run(instance);
-
-    const taskLoad = instance.taskLoad as {
-      (...args: unknown[]): Promise<number>;
-      loading: () => boolean;
-      error: () => Error | null;
-      lastResult: () => number | null;
-      cancelAll: () => void;
-    };
-
-    expect(typeof taskLoad).toBe("function");
-    expect(taskLoad.loading).toBeDefined();
-    expect(taskLoad.error).toBeDefined();
-    expect(taskLoad.lastResult).toBeDefined();
-    expect(taskLoad.cancelAll).toBeDefined();
-
-    const result = await taskLoad(5);
-    expect(result).toBe(10);
-    expect(taskLoad.lastResult()).toBe(10);
-  });
-
-  it("sets loading while running", async () => {
-    const { ctx, run } = fieldCtx("taskFetch");
-    Task("fetch")(undefined, ctx);
-
-    let resolve!: (v: string) => void;
-    const instance: Record<string, unknown> = {
-      fetch: async () => new Promise<string>((r) => { resolve = r; }),
-    };
-    run(instance);
-
-    const taskFetch = instance.taskFetch as { (): Promise<string>; loading: () => boolean };
-    const p = taskFetch();
-    expect(taskFetch.loading()).toBe(true);
-    resolve("done");
-    await p;
-    expect(taskFetch.loading()).toBe(false);
-  });
-
-  it("cancelAll() aborts the in-flight signal", async () => {
-    const { ctx, run } = fieldCtx("taskFetch");
-    Task("fetch")(undefined, ctx);
-
-    let capturedSignal!: AbortSignal;
-    let resolve!: () => void;
-    const instance: Record<string, unknown> = {
-      fetch: async (signal: AbortSignal) => {
-        capturedSignal = signal;
-        await new Promise<void>((r) => { resolve = r; });
-      },
-    };
-    run(instance);
-
-    const taskFetch = instance.taskFetch as { (): Promise<void>; cancelAll: () => void };
-    const p = taskFetch();
-    taskFetch.cancelAll();
-    resolve();
-    await p;
-
-    expect(capturedSignal.aborted).toBe(true);
-  });
-});
-
-// ── Queue ─────────────────────────────────────────────────────────────────────
-
-describe("Queue decorator", () => {
-  it("wraps the named method and exposes signals", async () => {
-    const { ctx, run } = fieldCtx("taskSave");
-    Queue("save")(undefined, ctx);
-
-    const instance: Record<string, unknown> = {
-      save: async (x: unknown) => String(x),
-    };
-    run(instance);
-
-    const taskSave = instance.taskSave as {
-      (...args: unknown[]): Promise<string>;
-      loading: () => boolean;
-      pending: () => number;
-      error: () => Error | null;
-      clear: () => void;
-    };
-
-    expect(typeof taskSave).toBe("function");
-    expect(taskSave.loading).toBeDefined();
-    expect(taskSave.pending).toBeDefined();
-    expect(taskSave.error).toBeDefined();
-    expect(taskSave.clear).toBeDefined();
-
-    const result = await taskSave("hello");
-    expect(result).toBe("hello");
-  });
-
-  it("clear() rejects queued calls with QueueClearedError", async () => {
-    const { ctx, run } = fieldCtx("taskSave");
-    Queue("save")(undefined, ctx);
-
-    let resolveFirst!: () => void;
-    const instance: Record<string, unknown> = {
-      save: async (signal: AbortSignal, _: unknown, idx: unknown) => {
-        void signal;
-        return idx === 0
-          ? new Promise<void>((r) => { resolveFirst = r; })
-          : Promise.resolve();
-      },
-    };
-    run(instance);
-
-    const taskSave = instance.taskSave as { (...args: unknown[]): Promise<unknown>; clear: () => void };
-    taskSave(null, 0);
-    const p1 = taskSave(null, 1);
-    taskSave.clear();
-
-    await expect(p1).rejects.toThrow("Queue cleared");
-    resolveFirst();
-  });
-});
-
-// ── Pool ──────────────────────────────────────────────────────────────────────
-
-describe("Pool decorator", () => {
-  it("wraps the named method and exposes signals", async () => {
-    const { ctx, run } = fieldCtx("taskProcess");
-    Pool("process", 2)(undefined, ctx);
-
-    const instance: Record<string, unknown> = {
-      process: async (x: unknown) => (x as number) + 1,
-    };
-    run(instance);
-
-    const taskProcess = instance.taskProcess as {
-      (...args: unknown[]): Promise<number>;
-      loading: () => boolean;
-      active: () => number;
-      pending: () => number;
-      error: () => Error | null;
-      cancelAll: () => void;
-    };
-
-    expect(typeof taskProcess).toBe("function");
-    expect(taskProcess.loading).toBeDefined();
-    expect(taskProcess.active).toBeDefined();
-    expect(taskProcess.pending).toBeDefined();
-    expect(taskProcess.error).toBeDefined();
-    expect(taskProcess.cancelAll).toBeDefined();
-
-    const result = await taskProcess(9);
-    expect(result).toBe(10);
-  });
-
-  it("respects concurrency limit", async () => {
-    const { ctx, run } = fieldCtx("taskWork");
-    Pool("work", 2)(undefined, ctx);
-
-    const resolvers: Array<() => void> = [];
-    const instance: Record<string, unknown> = {
-      work: async () => new Promise<void>((r) => resolvers.push(r)),
-    };
-    run(instance);
-
-    const taskWork = instance.taskWork as { (): Promise<void>; active: () => number; pending: () => number };
-    const t1 = taskWork();
-    const t2 = taskWork();
-    taskWork();
-
-    expect(taskWork.active()).toBe(2);
-    expect(taskWork.pending()).toBe(1);
-
-    resolvers.forEach((r) => { r(); });
-    await Promise.all([t1, t2]);
-  });
-
-  it("defaults concurrency to 1", async () => {
-    const { ctx, run } = fieldCtx("taskWork");
-    Pool("work")(undefined, ctx);
-
-    const resolvers: Array<() => void> = [];
-    const instance: Record<string, unknown> = {
-      work: async () => new Promise<void>((r) => resolvers.push(r)),
-    };
-    run(instance);
-
-    const taskWork = instance.taskWork as { (): Promise<void>; active: () => number; pending: () => number };
-    const t1 = taskWork();
-    const t2 = taskWork();
-
-    expect(taskWork.active()).toBe(1);
-    expect(taskWork.pending()).toBe(1);
-
-    resolvers[0]();
-    await t1;
-    resolvers[1]();
-    await t2;
-  });
-
-  it("cancelAll() cancels pending and active tasks", async () => {
-    const { ctx, run } = fieldCtx("taskWork");
-    Pool("work", 1)(undefined, ctx);
-
-    let resolveFirst!: () => void;
-    const instance: Record<string, unknown> = {
-      work: async (signal: AbortSignal, idx: unknown) => {
-        void signal;
-        if (idx === 0) await new Promise<void>((r) => { resolveFirst = r; });
-      },
-    };
-    run(instance);
-
-    const taskWork = instance.taskWork as {
-      (...args: unknown[]): Promise<void>;
-      active: () => number;
-      pending: () => number;
-      cancelAll: () => void;
-    };
-
-    const t1 = taskWork(0);
-    const t2 = taskWork(1);
-
-    await Promise.resolve();
-    taskWork.cancelAll();
-    resolveFirst();
-
-    await Promise.all([t1, t2]);
-
-    expect(taskWork.active()).toBe(0);
-    expect(taskWork.pending()).toBe(0);
-  });
-});
-
-// ── QueueClearedError re-export ────────────────────────────────────────────────
-
-describe("QueueClearedError", () => {
-  it("is exported from the package", () => {
-    expect(QueueClearedError).toBeDefined();
-    const e = new QueueClearedError();
-    expect(e).toBeInstanceOf(Error);
-    expect(e.name).toBe("QueueClearedError");
-    expect(e.message).toBe("Queue cleared");
-  });
-});

package/src/__tests__/pool.test.ts

@@ -1,212 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-
-import { pool } from "../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);
-  });
-
-  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 tasks = [p(), p()];
-    expect(p.active()).toBe(2);
-    resolvers.forEach((r) => { r(); });
-    await Promise.all(tasks);
-    expect(p.active()).toBe(0);
-  });
-
-  it("loading is true when active > 0", async () => {
-    let resolve!: () => void;
-    const p = pool(1, () => new Promise<void>((r) => { resolve = r; }));
-    const t = p();
-    expect(p.loading()).toBe(true);
-    resolve();
-    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"); });
-    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()).toBeNull();
-  });
-
-  it("pending count decrements as tasks start", async () => {
-    let resolveFirst!: () => void;
-    const p = pool(1, async (idx: unknown) => {
-      if (idx === 0) await new Promise<void>((r) => { resolveFirst = r; });
-    });
-    const t1 = p(0);
-    const t2 = p(1);
-    expect(p.pending()).toBe(1);
-    resolveFirst();
-    await t1;
-    await t2;
-    expect(p.pending()).toBe(0);
-  });
-
-  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);
-    expect(p.active()).toBe(1);
-    expect(p.pending()).toBe(1);
-    resolveFirst();
-    await t1;
-    await t2;
-    expect(order).toEqual([0, 1]);
-  });
-
-  it("error in one task does not block subsequent tasks", async () => {
-    const p = pool(1, async (n: unknown) => {
-      if (n === 0) throw new Error("task 0 failed");
-      return n as number;
-    });
-    expect(await p(0)).toBeUndefined();
-    expect(await p(1)).toBe(1);
-  });
-
-  it("concurrency=0 — clamps to 1", async () => {
-    const fn = vi.fn(async () => "result");
-    const p = pool(0, fn);
-    expect(await p()).toBe("result");
-    expect(fn).toHaveBeenCalledOnce();
-  });
-
-  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.active()).toBe(0);
-  });
-});
-
-// ── With AbortSignal (opt-in via first param named "signal") ──────────────────
-
-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);
-  });
-
-  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);
-  });
-
-  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("cancelAll() resolves pending tasks as undefined", async () => {
-    let resolveFirst!: () => void;
-    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);
-    const t3 = p(2);
-    await Promise.resolve();
-    p.cancelAll();
-    resolveFirst();
-    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("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;
-    });
-    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

@@ -1,197 +0,0 @@
-import { describe, it, expect } from "vitest";
-
-import { queue, QueueClearedError } from "../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);
-    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; });
-    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 p = q();
-    expect(q.loading()).toBe(true);
-    resolve();
-    await p;
-    expect(q.loading()).toBe(false);
-  });
-
-  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 p1 = q(null, 0);
-    const p2 = q(null, 1);
-    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"); });
-    await expect(q()).rejects.toThrow("boom");
-    expect(q.error()?.message).toBe("boom");
-  });
-
-  it("wraps non-Error throws in an Error", async () => {
-    // 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");
-  });
-
-  it("error in one task does not prevent subsequent tasks from running", async () => {
-    const q = queue(async (n: unknown) => {
-      if (n === 0) throw new Error("task 0 failed");
-      return n as number;
-    });
-    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);
-  });
-
-  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);
-    const p1 = q(null, 1);
-    const p2 = q(null, 2);
-    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),
-    );
-    q(0, true);
-    const p1 = q(1, false);
-    q.clear();
-    await expect(p1).rejects.toBeInstanceOf(QueueClearedError);
-    resolveFirst();
-    expect(await q(42, false)).toBe(42);
-    expect(q.pending()).toBe(0);
-  });
-
-  it("clear() with no pending tasks — no-op, no crash", () => {
-    const q = queue(async () => "ok");
-    expect(() => q.clear()).not.toThrow();
-    expect(q.pending()).toBe(0);
-  });
-
-  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);
-  });
-});
-
-// ── With AbortSignal (opt-in via first param named "signal") ──────────────────
-
-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);
-  });
-
-  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("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);
-  });
-
-  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);
-  });
-
-  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);
-  });
-});