@cplieger/actions 1.0.0 → 1.0.1

package/src/cross-action-races.test.ts

@@ -0,0 +1,213 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+vi.mock("./notifier.js", () => ({
+  configure: vi.fn(),
+  notifySuccess: vi.fn(),
+  notifyError: vi.fn(),
+  _resetNotifierForTest: vi.fn(),
+}));
+import { defineAction, _resetForTest as resetDefine, _internalsForTest } from "./define.js";
+import { _resetForTest as resetRegistry } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+import { ActionError } from "./error.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.clearAllMocks();
+});
+
+describe("dedupe + retry interaction", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("deduped caller's onError fires with the real error after retries exhaust", async () => {
+    let attempt = 0;
+    const action = defineAction<string, string>({
+      name: "test.dedupe_retry",
+      dedupe: true,
+      retryable: (err) => err.code !== "cancelled",
+      retry: { count: 2, delay: 50 },
+      error: false,
+      run: () => {
+        attempt++;
+        throw new ActionError("server down", { status: 503 });
+      },
+    });
+    const onError1 = vi.fn();
+    const onError2 = vi.fn();
+    const p1 = action.dispatch("x", { onError: onError1 });
+    const p2 = action.dispatch("x", { onError: onError2 });
+    await vi.advanceTimersByTimeAsync(50);
+    await vi.advanceTimersByTimeAsync(100);
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r1).toBeNull();
+    expect(r2).toBeNull();
+    expect(attempt).toBe(3);
+    expect(onError1).toHaveBeenCalledWith(
+      expect.objectContaining({ message: "server down", status: 503 }),
+      "x",
+    );
+    expect(onError2).toHaveBeenCalledWith(
+      expect.objectContaining({ message: "server down", status: 503 }),
+      "x",
+    );
+  });
+
+  it("dedupe map is cleaned up after retry exhaustion", async () => {
+    const action = defineAction<string, string>({
+      name: "test.dedupe_cleanup",
+      dedupe: true,
+      retryable: (err) => err.code !== "cancelled",
+      retry: { count: 1, delay: 20 },
+      error: false,
+      run: () => {
+        throw new ActionError("fail", { status: 500 });
+      },
+    });
+    const p = action.dispatch("z");
+    await vi.advanceTimersByTimeAsync(20);
+    await p;
+    const { activeDedupes } = _internalsForTest();
+    expect(activeDedupes).toBe(0);
+  });
+});
+
+describe("cancel during scope-queued wait", () => {
+  it("cancelling a queued action that hasn't started lets subsequent actions proceed", async () => {
+    let resolveOccupant: (() => void) | null = null;
+    const order: string[] = [];
+    const occupant = defineAction<void, string>({
+      name: "test.queue_cancel_occ",
+      scope: "q-cancel",
+      run: () =>
+        new Promise<string>((r) => {
+          resolveOccupant = () => {
+            r("occ");
+          };
+        }),
+    });
+    const victim = defineAction<void, string>({
+      name: "test.queue_cancel_victim",
+      scope: "q-cancel",
+      error: false,
+      run: () => {
+        order.push("victim-run");
+        return Promise.resolve("victim");
+      },
+    });
+    const follower = defineAction<void, string>({
+      name: "test.queue_cancel_follower",
+      scope: "q-cancel",
+      run: () => {
+        order.push("follower-run");
+        return Promise.resolve("follower");
+      },
+    });
+    const pOcc = occupant.dispatch();
+    await Promise.resolve();
+    const pVictim = victim.dispatch();
+    const pFollower = follower.dispatch();
+    await Promise.resolve();
+    victim.cancel();
+    resolveOccupant!();
+    await pOcc;
+    const rVictim = await pVictim;
+    expect(rVictim).toBeNull();
+    expect(order).not.toContain("victim-run");
+    const rFollower = await pFollower;
+    expect(rFollower).toBe("follower");
+    expect(order).toContain("follower-run");
+  });
+});
+
+describe("dedupe + cancel interaction", () => {
+  it("cancelling the original dispatch propagates cancellation to deduped caller", async () => {
+    const action = defineAction<string, string>({
+      name: "test.dedupe_cancel",
+      dedupe: true,
+      error: false,
+      run: (_args, signal) =>
+        new Promise<string>((_, reject) => {
+          signal.addEventListener("abort", () => {
+            reject(new DOMException("aborted", "AbortError"));
+          });
+        }),
+    });
+    const onSettled1 = vi.fn();
+    const onSettled2 = vi.fn();
+    const p1 = action.dispatch("a", { onSettled: onSettled1 });
+    const p2 = action.dispatch("a", { onSettled: onSettled2 });
+    action.cancel();
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r1).toBeNull();
+    expect(r2).toBeNull();
+    expect(onSettled1).toHaveBeenCalledTimes(1);
+    expect(onSettled2).toHaveBeenCalledTimes(1);
+  });
+
+  it("dedupe map is cleaned up after cancellation", async () => {
+    const action = defineAction<string, string>({
+      name: "test.dedupe_cancel_cleanup",
+      dedupe: true,
+      error: false,
+      run: (_args, signal) =>
+        new Promise<string>((_, reject) => {
+          signal.addEventListener("abort", () => {
+            reject(new DOMException("aborted", "AbortError"));
+          });
+        }),
+    });
+    const p = action.dispatch("b");
+    action.cancel();
+    await p;
+    const { activeDedupes } = _internalsForTest();
+    expect(activeDedupes).toBe(0);
+  });
+});
+
+describe("interleaved cross-action scope chain ordering", () => {
+  it("A-B-A-B dispatches serialize in dispatch order", async () => {
+    const order: string[] = [];
+    const actionA = defineAction<number, string>({
+      name: "test.interleave_A",
+      scope: "interleave",
+      run: (n) => {
+        order.push(`A-${String(n)}`);
+        return Promise.resolve(`A-${String(n)}`);
+      },
+    });
+    const actionB = defineAction<number, string>({
+      name: "test.interleave_B",
+      scope: "interleave",
+      run: (n) => {
+        order.push(`B-${String(n)}`);
+        return Promise.resolve(`B-${String(n)}`);
+      },
+    });
+    const p1 = actionA.dispatch(1);
+    const p2 = actionB.dispatch(1);
+    const p3 = actionA.dispatch(2);
+    const p4 = actionB.dispatch(2);
+    await Promise.all([p1, p2, p3, p4]);
+    expect(order).toEqual(["A-1", "B-1", "A-2", "B-2"]);
+  });
+
+  it("scope chain drains completely — no leaked promises", async () => {
+    const action = defineAction<number, number>({
+      name: "test.drain",
+      scope: "drain",
+      run: (n) => Promise.resolve(n),
+    });
+    await action.dispatch(1);
+    await action.dispatch(2);
+    await action.dispatch(3);
+    const { scopeChains } = _internalsForTest();
+    expect(scopeChains).toBe(0);
+  });
+});

package/src/cross-action-scope-serial.test.ts

@@ -0,0 +1,121 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+vi.mock("./notifier.js", () => ({
+  configure: vi.fn(),
+  notifySuccess: vi.fn(),
+  notifyError: vi.fn(),
+  _resetNotifierForTest: vi.fn(),
+}));
+import { defineAction, _resetForTest as resetDefine } from "./define.js";
+import { _resetForTest as resetRegistry } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.clearAllMocks();
+});
+
+describe("cross-action scope serialization after cancel", () => {
+  it("C waits for A when B is cancelled (middle entry)", async () => {
+    const order: string[] = [];
+    let resolveA!: (v: string) => void;
+    const actionA = defineAction<void, string>({
+      name: "test.serial_A",
+      scope: "serial",
+      run: () => {
+        order.push("A-start");
+        return new Promise<string>((r) => {
+          resolveA = r;
+        });
+      },
+    });
+    const actionB = defineAction<void, string>({
+      name: "test.serial_B",
+      scope: "serial",
+      error: false,
+      run: (_args, signal) => {
+        order.push("B-start");
+        if (signal.aborted) {
+          throw new DOMException("aborted", "AbortError");
+        }
+        return Promise.resolve("B");
+      },
+    });
+    const actionC = defineAction<void, string>({
+      name: "test.serial_C",
+      scope: "serial",
+      run: () => {
+        order.push("C-start");
+        return Promise.resolve("C");
+      },
+    });
+    const pA = actionA.dispatch();
+    await Promise.resolve();
+    expect(order).toEqual(["A-start"]);
+    const pB = actionB.dispatch();
+    const pC = actionC.dispatch();
+    actionB.cancel();
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual(["A-start"]);
+    resolveA("A-done");
+    const [rA, rB, rC] = await Promise.all([pA, pB, pC]);
+    expect(rA).toBe("A-done");
+    expect(rB).toBeNull();
+    expect(rC).toBe("C");
+    expect(order).toEqual(["A-start", "C-start"]);
+  });
+
+  it("D waits for A when B (last entry) is cancelled then D dispatches", async () => {
+    const order: string[] = [];
+    let resolveA!: (v: string) => void;
+    const actionA = defineAction<void, string>({
+      name: "test.last_A",
+      scope: "last-cancel",
+      run: () => {
+        order.push("A-start");
+        return new Promise<string>((r) => {
+          resolveA = r;
+        });
+      },
+    });
+    const actionB = defineAction<void, string>({
+      name: "test.last_B",
+      scope: "last-cancel",
+      error: false,
+      run: (_args, signal) => {
+        order.push("B-start");
+        if (signal.aborted) {
+          throw new DOMException("aborted", "AbortError");
+        }
+        return Promise.resolve("B");
+      },
+    });
+    const actionD = defineAction<void, string>({
+      name: "test.last_D",
+      scope: "last-cancel",
+      run: () => {
+        order.push("D-start");
+        return Promise.resolve("D");
+      },
+    });
+    const pA = actionA.dispatch();
+    await Promise.resolve();
+    const pB = actionB.dispatch();
+    actionB.cancel();
+    const pD = actionD.dispatch();
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual(["A-start"]);
+    resolveA("A-done");
+    const [rA, rB, rD] = await Promise.all([pA, pB, pD]);
+    expect(rA).toBe("A-done");
+    expect(rB).toBeNull();
+    expect(rD).toBe("D");
+    expect(order).toEqual(["A-start", "D-start"]);
+  });
+});

package/src/debounce.test.ts

@@ -0,0 +1,121 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+vi.mock("./notifier.js", () => ({
+  configure: vi.fn(),
+  notifySuccess: vi.fn(),
+  notifyError: vi.fn(),
+  _resetNotifierForTest: vi.fn(),
+}));
+import { defineAction, _resetForTest as resetDefine } from "./define.js";
+import { _resetForTest as resetRegistry } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+import { debouncedDispatch } from "./debounce.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.useFakeTimers();
+});
+
+function makeAction() {
+  const run = vi.fn(async (args: string) => args);
+  const action = defineAction({ name: "test.debounce", run });
+  return { action, run };
+}
+
+describe("debouncedDispatch — trailing (default)", () => {
+  it("dispatches after the wait period", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100 });
+    debounced("a");
+    expect(run).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(100);
+    expect(run).toHaveBeenCalledWith("a", expect.anything(), expect.anything());
+  });
+
+  it("coalesces rapid calls — only last args dispatched", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 50 });
+    debounced("a");
+    debounced("b");
+    debounced("c");
+    vi.advanceTimersByTime(50);
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(run).toHaveBeenCalledWith("c", expect.anything(), expect.anything());
+  });
+
+  it("cancel() prevents the pending dispatch", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100 });
+    debounced("a");
+    debounced.cancel();
+    vi.advanceTimersByTime(200);
+    expect(run).not.toHaveBeenCalled();
+  });
+
+  it("flush() fires immediately with pending args", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100 });
+    debounced("x");
+    debounced.flush();
+    expect(run).toHaveBeenCalledWith("x", expect.anything(), expect.anything());
+  });
+
+  it("flush(args) overrides pending args", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100 });
+    debounced("old");
+    debounced.flush("override");
+    expect(run).toHaveBeenCalledWith("override", expect.anything(), expect.anything());
+  });
+
+  it("isPending() reflects scheduled state", () => {
+    const { action } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100 });
+    expect(debounced.isPending()).toBe(false);
+    debounced("a");
+    expect(debounced.isPending()).toBe(true);
+    vi.advanceTimersByTime(100);
+    expect(debounced.isPending()).toBe(false);
+  });
+});
+
+describe("debouncedDispatch — leading", () => {
+  it("fires immediately on first call", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100, leading: true });
+    debounced("first");
+    expect(run).toHaveBeenCalledWith("first", expect.anything(), expect.anything());
+  });
+
+  it("suppresses calls within the cooldown window", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100, leading: true });
+    debounced("a");
+    debounced("b");
+    debounced("c");
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(run).toHaveBeenCalledWith("a", expect.anything(), expect.anything());
+  });
+
+  it("fires trailing with last suppressed args after cooldown", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100, leading: true });
+    debounced("a");
+    debounced("b");
+    vi.advanceTimersByTime(100);
+    expect(run).toHaveBeenCalledTimes(2);
+    expect(run).toHaveBeenLastCalledWith("b", expect.anything(), expect.anything());
+  });
+
+  it("cancel after leading fire prevents trailing fire", () => {
+    const { action, run } = makeAction();
+    const debounced = debouncedDispatch(action, { wait: 100, leading: true });
+    debounced("a");
+    debounced("b");
+    debounced.cancel();
+    vi.advanceTimersByTime(200);
+    expect(run).toHaveBeenCalledTimes(1);
+  });
+});

package/src/define.property.test.ts

@@ -0,0 +1,133 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import fc from "fast-check";
+vi.mock("./notifier.js", () => ({
+  configure: vi.fn(),
+  notifySuccess: vi.fn(),
+  notifyError: vi.fn(),
+  _resetNotifierForTest: vi.fn(),
+}));
+import { defineAction, _resetForTest as resetDefine } from "./define.js";
+import { _resetForTest as resetRegistry } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.clearAllMocks();
+});
+
+describe("scope serialization property", () => {
+  it("for any N dispatches with same scope key, runs execute sequentially and all resolve", async () => {
+    await fc.assert(
+      fc.asyncProperty(fc.integer({ min: 2, max: 8 }), async (n) => {
+        resetDefine();
+        resetRegistry();
+        resetCleanup();
+        const timeline: { idx: number; event: "start" | "end" }[] = [];
+        let counter = 0;
+        const action = defineAction<number, number>({
+          name: "prop.scope_serial",
+          scope: "serial",
+          error: false,
+          run: async (args) => {
+            const idx = args;
+            timeline.push({ idx, event: "start" });
+            await new Promise((r) => setTimeout(r, 1));
+            timeline.push({ idx, event: "end" });
+            return counter++;
+          },
+        });
+        const promises = Array.from({ length: n }, (_, i) => action.dispatch(i));
+        const results = await Promise.all(promises);
+        expect(results).toHaveLength(n);
+        for (const r of results) {
+          expect(r).not.toBeNull();
+        }
+        for (let i = 0; i < timeline.length; i += 2) {
+          expect(timeline[i]!.event).toBe("start");
+          expect(timeline[i + 1]?.event).toBe("end");
+        }
+      }),
+      { numRuns: 20 },
+    );
+  });
+});
+
+describe("dedupe property", () => {
+  it("for any N dispatches with dedupe:true and same args, at most one run is in-flight", async () => {
+    await fc.assert(
+      fc.asyncProperty(fc.integer({ min: 2, max: 6 }), async (n) => {
+        resetDefine();
+        resetRegistry();
+        resetCleanup();
+        let inFlight = 0;
+        let maxInFlight = 0;
+        let runCount = 0;
+        const action = defineAction<string, string>({
+          name: "prop.dedupe",
+          dedupe: true,
+          error: false,
+          run: async () => {
+            inFlight++;
+            runCount++;
+            maxInFlight = Math.max(maxInFlight, inFlight);
+            await new Promise((r) => setTimeout(r, 5));
+            inFlight--;
+            return "ok";
+          },
+        });
+        const promises = Array.from({ length: n }, () => action.dispatch("same"));
+        const results = await Promise.all(promises);
+        expect(maxInFlight).toBe(1);
+        for (const r of results) {
+          expect(r).toBe("ok");
+        }
+        expect(runCount).toBe(1);
+      }),
+      { numRuns: 20 },
+    );
+  });
+});
+
+describe("cancellation property", () => {
+  it("cancel during any lifecycle phase transitions to cancelled and returns null", async () => {
+    await fc.assert(
+      fc.asyncProperty(fc.constantFrom("immediate", "during-run"), async (phase) => {
+        resetDefine();
+        resetRegistry();
+        resetCleanup();
+        let runStarted = false;
+        const action = defineAction<string, string>({
+          name: "prop.cancel",
+          error: false,
+          run: async (_args, signal) => {
+            runStarted = true;
+            return new Promise<string>((_resolve, reject) => {
+              signal.addEventListener(
+                "abort",
+                () => {
+                  reject(new DOMException("aborted", "AbortError"));
+                },
+                { once: true },
+              );
+            });
+          },
+        });
+        if (phase === "immediate") {
+          const p = action.dispatch("x");
+          action.cancel();
+          expect(await p).toBeNull();
+        } else {
+          const p = action.dispatch("x");
+          await new Promise((r) => setTimeout(r, 1));
+          expect(runStarted).toBe(true);
+          action.cancel();
+          expect(await p).toBeNull();
+        }
+      }),
+      { numRuns: 15 },
+    );
+  });
+});