@praxisjs/concurrent 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @praxisjs/concurrent
 
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [d11a10a]
+  - @praxisjs/core@0.4.2
+
+## 0.2.2
+
+### Patch Changes
+
+- Updated dependencies [fe39901]
+  - @praxisjs/core@0.4.1
+
 ## 0.2.1
 
 ### Patch Changes

package/dist/__tests__/decorators.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=decorators.test.d.ts.map

package/dist/__tests__/decorators.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/decorators.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/decorators.test.js

@@ -0,0 +1,93 @@
+import { describe, it, expect } from "vitest";
+import { Task, Queue, Pool } from "../decorators";
+function methodCtx(name) {
+    const initializers = [];
+    return {
+        ctx: {
+            name,
+            kind: "method",
+            addInitializer(fn) { initializers.push(fn); },
+        },
+        run(instance) { initializers.forEach((fn) => { fn.call(instance); }); },
+    };
+}
+// ── Task ──────────────────────────────────────────────────────────────────────
+describe("Task decorator", () => {
+    it("replaces method with a task runner and exposes signals", async () => {
+        const { ctx, run } = methodCtx("load");
+        const original = async (x) => x * 2;
+        Task()(original, ctx);
+        const instance = {};
+        run(instance);
+        expect(typeof instance.load).toBe("function");
+        expect(instance.load_loading).toBeDefined();
+        expect(instance.load_error).toBeDefined();
+        expect(instance.load_lastResult).toBeDefined();
+        const result = await instance.load(5);
+        expect(result).toBe(10);
+        expect(instance.load_lastResult()).toBe(10);
+    });
+    it("sets loading signal while running", async () => {
+        const { ctx, run } = methodCtx("fetch");
+        let resolve;
+        const original = async () => new Promise((r) => { resolve = r; });
+        Task()(original, ctx);
+        const instance = {};
+        run(instance);
+        const p = instance.fetch();
+        expect(instance.fetch_loading()).toBe(true);
+        resolve("done");
+        await p;
+        expect(instance.fetch_loading()).toBe(false);
+    });
+});
+// ── Queue ─────────────────────────────────────────────────────────────────────
+describe("Queue decorator", () => {
+    it("replaces method with a queue runner and exposes signals", async () => {
+        const { ctx, run } = methodCtx("save");
+        const original = async (x) => String(x);
+        Queue()(original, ctx);
+        const instance = {};
+        run(instance);
+        expect(typeof instance.save).toBe("function");
+        expect(instance.save_loading).toBeDefined();
+        expect(instance.save_pending).toBeDefined();
+        expect(instance.save_error).toBeDefined();
+        const result = await instance.save("hello");
+        expect(result).toBe("hello");
+    });
+});
+// ── Pool ──────────────────────────────────────────────────────────────────────
+describe("Pool decorator", () => {
+    it("replaces method with a pool runner and exposes signals", async () => {
+        const { ctx, run } = methodCtx("process");
+        const original = async (x) => x + 1;
+        Pool(2)(original, ctx);
+        const instance = {};
+        run(instance);
+        expect(typeof instance.process).toBe("function");
+        expect(instance.process_loading).toBeDefined();
+        expect(instance.process_active).toBeDefined();
+        expect(instance.process_pending).toBeDefined();
+        expect(instance.process_error).toBeDefined();
+        const result = await instance.process(9);
+        expect(result).toBe(10);
+    });
+    it("respects concurrency limit", async () => {
+        const { ctx, run } = methodCtx("work");
+        const resolvers = [];
+        const original = async () => new Promise((r) => resolvers.push(r));
+        Pool(2)(original, ctx);
+        const instance = {};
+        run(instance);
+        const work = instance.work;
+        const t1 = work();
+        const t2 = work();
+        work(); // queued — concurrency limit is 2
+        expect(instance.work_active()).toBe(2);
+        expect(instance.work_pending()).toBe(1);
+        resolvers.forEach((r) => { r(); });
+        await Promise.all([t1, t2]);
+    });
+});
+//# sourceMappingURL=decorators.test.js.map

package/dist/__tests__/decorators.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.test.js","sourceRoot":"","sources":["../../src/__tests__/decorators.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/pool.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pool.test.d.ts.map

package/dist/__tests__/pool.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/pool.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/pool.test.js

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi } from "vitest";
+import { pool } from "../pool";
+describe("pool", () => {
+    it("executes a task and resolves with its result", async () => {
+        const p = pool(2, async (x) => x * 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 = [];
+        const p = pool(3, () => new Promise((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;
+        const p = pool(1, () => new Promise((r) => { resolve = r; }));
+        const task = p();
+        expect(p.loading()).toBe(true);
+        resolve();
+        await task;
+        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 result = await p();
+        expect(result).toBeUndefined();
+        expect(p.error()?.message).toBe("pool error");
+    });
+    it("pending count decrements as tasks start", async () => {
+        let resolveFirst;
+        const started = [];
+        const p = pool(1, async (idx) => {
+            started.push(idx);
+            if (idx === 0)
+                await new Promise((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;
+        await t2;
+        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 = [];
+        let resolveFirst;
+        const p = pool(1, async (n) => {
+            if (n === 0)
+                await new Promise((r) => { resolveFirst = r; });
+            order.push(n);
+        });
+        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
+    });
+    it("error in one task does not block subsequent tasks", async () => {
+        const results = [];
+        const p = pool(1, async (n) => {
+            if (n === 0)
+                throw new Error("task 0 failed");
+            return n;
+        });
+        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
+    });
+    it("concurrency=0 — tasks are enqueued but never executed", async () => {
+        const fn = vi.fn(async () => "result");
+        const p = pool(0, fn);
+        // Queue a task — tryRun() bails immediately because _active(0) >= concurrency(0)
+        void p();
+        await new Promise((r) => setTimeout(r, 0));
+        expect(fn).not.toHaveBeenCalled();
+        expect(p.pending()).toBe(1);
+        expect(p.loading()).toBe(false);
+    });
+    it("active() never exceeds concurrency", async () => {
+        const concurrency = 2;
+        let maxObservedActive = 0;
+        const p = pool(concurrency, async () => {
+            maxObservedActive = Math.max(maxObservedActive, p.active());
+            await new Promise((r) => setTimeout(r, 5));
+        });
+        await Promise.all([p(), p(), p(), p()]);
+        expect(maxObservedActive).toBeLessThanOrEqual(concurrency);
+    });
+});
+//# sourceMappingURL=pool.test.js.map

package/dist/__tests__/pool.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.test.js","sourceRoot":"","sources":["../../src/__tests__/pool.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/queue.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=queue.test.d.ts.map

package/dist/__tests__/queue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/queue.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/queue.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from "vitest";
+import { queue } from "../queue";
+describe("queue", () => {
+    it("executes the task and resolves the promise", async () => {
+        const q = queue(async (x) => x * 2);
+        const result = await q(5);
+        expect(result).toBe(10);
+    });
+    it("runs tasks sequentially (FIFO)", async () => {
+        const order = [];
+        const q = queue(async (n) => {
+            order.push(n);
+            return n;
+        });
+        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;
+        const q = queue(() => new Promise((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;
+        const q = queue((_, idx) => idx === 0
+            ? new Promise((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");
+        });
+        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";
+        });
+        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) => {
+            if (n === 0)
+                throw new Error("task 0 failed");
+            return n;
+        });
+        const p0 = q(0); // will reject
+        const p1 = q(1); // should still run despite p0 failing
+        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 () => {
+        let resolveFirst;
+        const q = queue((_, idx) => idx === 0
+            ? new Promise((r) => { resolveFirst = r; })
+            : Promise.resolve());
+        q(null, 0);
+        q(null, 1);
+        q(null, 2);
+        q.clear();
+        resolveFirst();
+        // After clearing, pending count should be 0
+        expect(q.pending()).toBe(0);
+    });
+});
+//# sourceMappingURL=queue.test.js.map

package/dist/__tests__/queue.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.test.js","sourceRoot":"","sources":["../../src/__tests__/queue.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/task.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=task.test.d.ts.map

package/dist/__tests__/task.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/task.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/task.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import { task } from "../task";
+describe("task", () => {
+    it("resolves with the function result", async () => {
+        const t = task(async (x) => x + 1);
+        expect(await t(9)).toBe(10);
+    });
+    it("sets loading to true while running", async () => {
+        let resolve;
+        const t = task(() => new Promise((r) => { resolve = r; }));
+        const p = t();
+        expect(t.loading()).toBe(true);
+        resolve(42);
+        await p;
+        expect(t.loading()).toBe(false);
+    });
+    it("stores last result", async () => {
+        const t = task(async () => "hello");
+        await t();
+        expect(t.lastResult()).toBe("hello");
+    });
+    it("captures errors in the error signal", async () => {
+        const t = task(async () => {
+            throw new Error("task failed");
+        });
+        const result = await t();
+        expect(result).toBeUndefined();
+        expect(t.error()?.message).toBe("task failed");
+    });
+    it("clears error on a new run", async () => {
+        let shouldFail = true;
+        const t = task(async () => {
+            if (shouldFail)
+                throw new Error("oops");
+            return "ok";
+        });
+        await t();
+        expect(t.error()).not.toBeNull();
+        shouldFail = false;
+        await t();
+        expect(t.error()).toBeNull();
+        expect(t.lastResult()).toBe("ok");
+    });
+    it("cancelAll() discards in-flight results", async () => {
+        let resolve;
+        const t = task(() => new Promise((r) => { resolve = r; }));
+        const p = t();
+        t.cancelAll();
+        resolve("stale");
+        const result = await p;
+        expect(result).toBeUndefined();
+        expect(t.loading()).toBe(false);
+    });
+    it("cancelAll() during a failing task discards the error", async () => {
+        let reject;
+        const t = task(() => new Promise((_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(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();
+        expect(t.error()).toBeInstanceOf(Error);
+        expect(t.error()?.message).toBe("string-error");
+    });
+    it("second run while first is pending discards the first result", async () => {
+        let resolveFirst;
+        let resolveSecond;
+        const t = task((_run) => (_run === 1
+            ? new Promise((r) => { resolveFirst = r; })
+            : new Promise((r) => { resolveSecond = r; })));
+        let run = 1;
+        const p1 = t(run++); // run 1
+        const p2 = t(run++); // run 2 — increments _runId, making run 1 stale
+        resolveSecond("result-2");
+        resolveFirst("result-1"); // stale
+        const [r1, r2] = await Promise.all([p1, p2]);
+        expect(r2).toBe("result-2");
+        expect(r1).toBeUndefined(); // stale run discarded
+        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));
+        const result = await t();
+        expect(result).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;
+        const staleTask = task(() => new Promise((r) => { resolve = r; }));
+        const p = staleTask();
+        staleTask.cancelAll();
+        resolve("stale");
+        await p;
+        // Now run a fresh task after cancelAll
+        const result = await t();
+        expect(result).toBe("fresh");
+        expect(t.loading()).toBe(false);
+    });
+});
+//# sourceMappingURL=task.test.js.map

package/dist/__tests__/task.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.test.js","sourceRoot":"","sources":["../../src/__tests__/task.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisjs/concurrent",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,7 +14,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@praxisjs/core": "0.4.0",
+    "@praxisjs/core": "0.4.2",
     "@praxisjs/shared": "0.2.0"
   },
   "scripts": {

package/src/__tests__/decorators.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+
+import { Task, Queue, Pool } from "../decorators";
+
+function methodCtx(name: string) {
+  const initializers: Array<(this: unknown) => void> = [];
+  return {
+    ctx: {
+      name,
+      kind: "method" as const,
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassMethodDecoratorContext,
+    run(instance: unknown) { initializers.forEach((fn) => { fn.call(instance); }); },
+  };
+}
+
+// ── Task ──────────────────────────────────────────────────────────────────────
+
+describe("Task decorator", () => {
+  it("replaces method with a task runner and exposes signals", async () => {
+    const { ctx, run } = methodCtx("load");
+    const original = async (x: unknown) => (x as number) * 2;
+    Task()(original, ctx);
+
+    const instance: Record<string, unknown> = {};
+    run(instance);
+
+    expect(typeof instance.load).toBe("function");
+    expect(instance.load_loading).toBeDefined();
+    expect(instance.load_error).toBeDefined();
+    expect(instance.load_lastResult).toBeDefined();
+
+    const result = await (instance.load as (x: number) => Promise<number>)(5);
+    expect(result).toBe(10);
+    expect(
+      (instance.load_lastResult as () => number)(),
+    ).toBe(10);
+  });
+
+  it("sets loading signal while running", async () => {
+    const { ctx, run } = methodCtx("fetch");
+    let resolve!: (v: string) => void;
+    const original = async () => new Promise<string>((r) => { resolve = r; });
+    Task()(original, ctx);
+
+    const instance: Record<string, unknown> = {};
+    run(instance);
+
+    const p = (instance.fetch as () => Promise<string>)();
+    expect((instance.fetch_loading as () => boolean)()).toBe(true);
+    resolve("done");
+    await p;
+    expect((instance.fetch_loading as () => boolean)()).toBe(false);
+  });
+});
+
+// ── Queue ─────────────────────────────────────────────────────────────────────
+
+describe("Queue decorator", () => {
+  it("replaces method with a queue runner and exposes signals", async () => {
+    const { ctx, run } = methodCtx("save");
+    const original = async (x: unknown) => String(x);
+    Queue()(original, ctx);
+
+    const instance: Record<string, unknown> = {};
+    run(instance);
+
+    expect(typeof instance.save).toBe("function");
+    expect(instance.save_loading).toBeDefined();
+    expect(instance.save_pending).toBeDefined();
+    expect(instance.save_error).toBeDefined();
+
+    const result = await (instance.save as (x: string) => Promise<string>)("hello");
+    expect(result).toBe("hello");
+  });
+});
+
+// ── Pool ──────────────────────────────────────────────────────────────────────
+
+describe("Pool decorator", () => {
+  it("replaces method with a pool runner and exposes signals", async () => {
+    const { ctx, run } = methodCtx("process");
+    const original = async (x: unknown) => (x as number) + 1;
+    Pool(2)(original, ctx);
+
+    const instance: Record<string, unknown> = {};
+    run(instance);
+
+    expect(typeof instance.process).toBe("function");
+    expect(instance.process_loading).toBeDefined();
+    expect(instance.process_active).toBeDefined();
+    expect(instance.process_pending).toBeDefined();
+    expect(instance.process_error).toBeDefined();
+
+    const result = await (instance.process as (x: number) => Promise<number>)(9);
+    expect(result).toBe(10);
+  });
+
+  it("respects concurrency limit", async () => {
+    const { ctx, run } = methodCtx("work");
+    const resolvers: Array<() => void> = [];
+    const original = async () => new Promise<void>((r) => resolvers.push(r));
+    Pool(2)(original, ctx);
+
+    const instance: Record<string, unknown> = {};
+    run(instance);
+
+    const work = instance.work as () => Promise<void>;
+    const t1 = work();
+    const t2 = work();
+    work(); // queued — concurrency limit is 2
+
+    expect((instance.work_active as () => number)()).toBe(2);
+    expect((instance.work_pending as () => number)()).toBe(1);
+
+    resolvers.forEach((r) => { r(); });
+    await Promise.all([t1, t2]);
+  });
+});

package/src/__tests__/pool.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { pool } from "../pool";
+
+describe("pool", () => {
+  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 task = p();
+    expect(p.loading()).toBe(true);
+    resolve();
+    await task;
+    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 result = await p();
+    expect(result).toBeUndefined();
+    expect(p.error()?.message).toBe("pool error");
+  });
+
+  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;
+    await t2;
+    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
+  });
+
+  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
+  });
+
+  it("concurrency=0 — tasks are enqueued but never executed", async () => {
+    const fn = vi.fn(async () => "result");
+    const p = pool(0, fn);
+
+    // Queue a task — tryRun() bails immediately because _active(0) >= concurrency(0)
+    void p();
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(fn).not.toHaveBeenCalled();
+    expect(p.pending()).toBe(1);
+    expect(p.loading()).toBe(false);
+  });
+
+  it("active() never exceeds concurrency", async () => {
+    const concurrency = 2;
+    let maxObservedActive = 0;
+
+    const p = pool(concurrency, async () => {
+      maxObservedActive = Math.max(maxObservedActive, p.active());
+      await new Promise((r) => setTimeout(r, 5));
+    });
+
+    await Promise.all([p(), p(), p(), p()]);
+    expect(maxObservedActive).toBeLessThanOrEqual(concurrency);
+  });
+});

package/src/__tests__/queue.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+
+import { queue } from "../queue";
+
+describe("queue", () => {
+  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);
+  });
+
+  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);
+
+    // 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");
+    });
+    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";
+    });
+    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); // will reject
+    const p1 = q(1); // should still run despite p0 failing
+    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 () => {
+    let resolveFirst!: () => void;
+    const q = queue(
+      (_: unknown, idx: unknown) =>
+        idx === 0
+          ? new Promise<void>((r) => { resolveFirst = r; })
+          : Promise.resolve(),
+    );
+
+    q(null, 0);
+    q(null, 1);
+    q(null, 2);
+
+    q.clear();
+    resolveFirst();
+
+    // After clearing, pending count should be 0
+    expect(q.pending()).toBe(0);
+  });
+});

package/src/__tests__/task.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect } from "vitest";
+
+import { task } from "../task";
+
+describe("task", () => {
+  it("resolves with the function result", async () => {
+    const t = task(async (x: unknown) => (x as number) + 1);
+    expect(await t(9)).toBe(10);
+  });
+
+  it("sets loading to true while running", async () => {
+    let resolve!: (v: number) => void;
+    const t = task(() => new Promise<number>((r) => { resolve = r; }));
+
+    const p = t();
+    expect(t.loading()).toBe(true);
+    resolve(42);
+    await p;
+    expect(t.loading()).toBe(false);
+  });
+
+  it("stores last result", async () => {
+    const t = task(async () => "hello");
+    await t();
+    expect(t.lastResult()).toBe("hello");
+  });
+
+  it("captures errors in the error signal", async () => {
+    const t = task(async () => {
+      throw new Error("task failed");
+    });
+    const result = await t();
+    expect(result).toBeUndefined();
+    expect(t.error()?.message).toBe("task failed");
+  });
+
+  it("clears error on a new run", async () => {
+    let shouldFail = true;
+    const t = task(async () => {
+      if (shouldFail) throw new Error("oops");
+      return "ok";
+    });
+    await t();
+    expect(t.error()).not.toBeNull();
+
+    shouldFail = false;
+    await t();
+    expect(t.error()).toBeNull();
+    expect(t.lastResult()).toBe("ok");
+  });
+
+  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(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(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();
+    expect(t.error()).toBeInstanceOf(Error);
+    expect(t.error()?.message).toBe("string-error");
+  });
+
+  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
+        ? new Promise<string>((r) => { resolveFirst = 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
+
+    resolveSecond("result-2");
+    resolveFirst("result-1"); // stale
+
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r2).toBe("result-2");
+    expect(r1).toBeUndefined(); // stale run discarded
+    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(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; }));
+
+    const p = staleTask();
+    staleTask.cancelAll();
+    resolve("stale");
+    await p;
+
+    // Now run a fresh task after cancelAll
+    const result = await t();
+    expect(result).toBe("fresh");
+    expect(t.loading()).toBe(false);
+  });
+});