@cplieger/actions 1.0.0 → 1.0.1

package/src/primitives.test.ts

@@ -0,0 +1,215 @@
+// @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, IDEMPOTENCY_HEADER, _resetForTest as resetDefine } from "./define.js";
+import { apiAction } from "./api.js";
+import { _resetForTest as resetRegistry, pendingCount } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+import { debouncedDispatch } from "./debounce.js";
+import { retryNetwork } from "./error.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.clearAllMocks();
+});
+
+describe("idempotencyKey", () => {
+  it("apiAction sends Idempotency-Key header when configured: true", async () => {
+    const fetchSpy = vi.fn<typeof fetch>(() =>
+      Promise.resolve(new Response("{}", { status: 200 })),
+    );
+    vi.stubGlobal("fetch", fetchSpy);
+    const action = apiAction<{ id: string }>({
+      name: "test.idem.true",
+      idempotencyKey: true,
+      request: ({ id }) => ({ method: "POST", path: `/api/x/${id}`, body: {} }),
+    });
+    await action.dispatch({ id: "abc" });
+    const init = fetchSpy.mock.calls[0]?.[1]!;
+    const headers = init.headers as Record<string, string>;
+    const hk = IDEMPOTENCY_HEADER.toLowerCase();
+    expect(headers[hk]).toBeDefined();
+    expect(headers[hk]!.length).toBeGreaterThan(5);
+    vi.unstubAllGlobals();
+  });
+
+  it("no Idempotency-Key when idempotencyKey is undefined", async () => {
+    const fetchSpy = vi.fn<typeof fetch>(() =>
+      Promise.resolve(new Response("{}", { status: 200 })),
+    );
+    vi.stubGlobal("fetch", fetchSpy);
+    const action = apiAction<void>({
+      name: "test.idem.none",
+      request: () => ({ method: "POST", path: "/api/x", body: {} }),
+    });
+    await action.dispatch();
+    const init = fetchSpy.mock.calls[0]?.[1]!;
+    const headers = (init.headers ?? {}) as Record<string, string>;
+    expect(headers[IDEMPOTENCY_HEADER.toLowerCase()]).toBeUndefined();
+    vi.unstubAllGlobals();
+  });
+
+  it("custom defineAction can read idempotencyKey from ctx", async () => {
+    const seen: string[] = [];
+    const action = defineAction<void, void>({
+      name: "test.idem.ctx",
+      idempotencyKey: true,
+      run: (_args, _signal, ctx) => {
+        if (ctx?.idempotencyKey !== undefined) {
+          seen.push(ctx.idempotencyKey);
+        }
+        return Promise.resolve();
+      },
+    });
+    await action.dispatch();
+    await action.dispatch();
+    expect(seen).toHaveLength(2);
+    expect(seen[0]).not.toBe(seen[1]);
+  });
+
+  it("retries reuse the same idempotency key across attempts", async () => {
+    let attempt = 0;
+    const fetchSpy = vi.fn<typeof fetch>(() => {
+      attempt++;
+      if (attempt < 3) {
+        return Promise.reject(new TypeError("Failed to fetch"));
+      }
+      return Promise.resolve(new Response("{}", { status: 200 }));
+    });
+    vi.stubGlobal("fetch", fetchSpy);
+    vi.useFakeTimers();
+    const action = apiAction<void>({
+      name: "test.idem.retry",
+      idempotencyKey: true,
+      retryable: retryNetwork,
+      retry: { count: 2, delay: 50 },
+      request: () => ({ method: "POST", path: "/api/x", body: {} }),
+    });
+    const p = action.dispatch();
+    await vi.advanceTimersByTimeAsync(50);
+    await vi.advanceTimersByTimeAsync(100);
+    await p;
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+    const k1 = (fetchSpy.mock.calls[0]?.[1])!.headers as Record<string, string>;
+    const k2 = (fetchSpy.mock.calls[1]?.[1])!.headers as Record<string, string>;
+    const k3 = (fetchSpy.mock.calls[2]?.[1])!.headers as Record<string, string>;
+    const hk = IDEMPOTENCY_HEADER.toLowerCase();
+    expect(k1[hk]).toBe(k2[hk]);
+    expect(k2[hk]).toBe(k3[hk]);
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+});
+
+describe("dedupe", () => {
+  it("two concurrent dispatches with matching args share one in-flight promise", async () => {
+    let resolveRun: ((v: string) => void) | undefined;
+    let runCalls = 0;
+    const action = defineAction<{ id: string }, string>({
+      name: "test.dedupe",
+      dedupe: true,
+      run: () => {
+        runCalls++;
+        return new Promise<string>((r) => {
+          resolveRun = r;
+        });
+      },
+    });
+    const p1 = action.dispatch({ id: "a" });
+    const p2 = action.dispatch({ id: "a" });
+    expect(runCalls).toBe(1);
+    resolveRun?.("ok");
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r1).toBe("ok");
+    expect(r2).toBe("ok");
+  });
+
+  it("different args do NOT collapse", async () => {
+    let runCalls = 0;
+    const action = defineAction<{ id: string }, string>({
+      name: "test.dedupe.different",
+      dedupe: true,
+      run: (args) => {
+        runCalls++;
+        return Promise.resolve(args.id);
+      },
+    });
+    await Promise.all([action.dispatch({ id: "a" }), action.dispatch({ id: "b" })]);
+    expect(runCalls).toBe(2);
+  });
+
+  it("dedupe entry clears after resolution; subsequent dispatch starts fresh", async () => {
+    let runCalls = 0;
+    const action = defineAction<{ id: string }, void>({
+      name: "test.dedupe.clear",
+      dedupe: true,
+      run: () => {
+        runCalls++;
+        return Promise.resolve();
+      },
+    });
+    await action.dispatch({ id: "a" });
+    await action.dispatch({ id: "a" });
+    expect(runCalls).toBe(2);
+  });
+});
+
+describe("pendingCount", () => {
+  it("sums across all action names without arguments", async () => {
+    let resolveA: () => void = () => {};
+    let resolveB: () => void = () => {};
+    const a = defineAction<void, void>({
+      name: "test.pc.a",
+      run: () =>
+        new Promise<void>((r) => {
+          resolveA = r;
+        }),
+    });
+    const b = defineAction<void, void>({
+      name: "test.pc.b",
+      run: () =>
+        new Promise<void>((r) => {
+          resolveB = r;
+        }),
+    });
+    expect(pendingCount()).toBe(0);
+    const pa = a.dispatch();
+    const pb = b.dispatch();
+    expect(pendingCount()).toBe(2);
+    resolveA();
+    await pa;
+    expect(pendingCount()).toBe(1);
+    resolveB();
+    await pb;
+    expect(pendingCount()).toBe(0);
+  });
+});
+
+describe("debouncedDispatch", () => {
+  it("coalesces rapid calls into a single dispatch with the latest args", async () => {
+    vi.useFakeTimers();
+    const runArgs: string[] = [];
+    const action = defineAction<string, void>({
+      name: "test.debounce.basic",
+      run: (args) => {
+        runArgs.push(args);
+        return Promise.resolve();
+      },
+    });
+    const dbg = debouncedDispatch(action, { wait: 100 });
+    dbg("a");
+    dbg("b");
+    dbg("c");
+    expect(runArgs).toEqual([]);
+    await vi.advanceTimersByTimeAsync(100);
+    expect(runArgs).toEqual(["c"]);
+    vi.useRealTimers();
+  });
+});

package/src/race-dedupe-cancel.test.ts

@@ -0,0 +1,88 @@
+// @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("dedupe + cancel + immediate re-dispatch race", () => {
+  it("re-dispatch after cancel should start a fresh run, not collapse onto cancelled", async () => {
+    let runCount = 0;
+    const action = defineAction<string, string>({
+      name: "test.dedupe_cancel_redispatch",
+      dedupe: true,
+      error: false,
+      run: (_args, signal) => {
+        runCount++;
+        const myRun = runCount;
+        return new Promise<string>((resolve, reject) => {
+          if (signal.aborted) {
+            reject(new DOMException("aborted", "AbortError"));
+            return;
+          }
+          signal.addEventListener("abort", () => {
+            reject(new DOMException("aborted", "AbortError"));
+          });
+          setTimeout(() => {
+            resolve(`result-${myRun}`);
+          }, 10);
+        });
+      },
+    });
+    const p1 = action.dispatch("x");
+    action.cancel();
+    const p2 = action.dispatch("x");
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r1).toBeNull();
+    expect(r2).toBe("result-2");
+    expect(runCount).toBe(2);
+  });
+
+  it("second cancel after re-dispatch still works correctly", async () => {
+    let runCount = 0;
+    const action = defineAction<string, string>({
+      name: "test.dedupe_double_cancel",
+      dedupe: true,
+      error: false,
+      run: (_args, signal) => {
+        runCount++;
+        return new Promise<string>((resolve, reject) => {
+          if (signal.aborted) {
+            reject(new DOMException("aborted", "AbortError"));
+            return;
+          }
+          signal.addEventListener("abort", () => {
+            reject(new DOMException("aborted", "AbortError"));
+          });
+          setTimeout(() => {
+            resolve(`result-${runCount}`);
+          }, 10);
+        });
+      },
+    });
+    const p1 = action.dispatch("x");
+    action.cancel();
+    await p1;
+    await Promise.resolve();
+    await Promise.resolve();
+    const p2 = action.dispatch("x");
+    action.cancel();
+    await p2;
+    const p3 = action.dispatch("x");
+    const r3 = await p3;
+    expect(r3).toBe(`result-${runCount}`);
+    expect(runCount).toBe(3);
+  });
+});

package/src/redteam.test.ts

@@ -0,0 +1,254 @@
+// @vitest-environment happy-dom
+// RED-TEAM adversarial tests: probing edge cases not covered by existing tests.
+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 { apiAction, configureApi, _resetApiConfigForTest } from "./api.js";
+import { defineAction, _resetForTest as resetDefine } from "./define.js";
+import { _resetForTest as resetRegistry, recentLog } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+
+const mockFetch = vi.fn();
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  _resetApiConfigForTest();
+  mockFetch.mockReset();
+  vi.stubGlobal("fetch", mockFetch);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// 1. configureApi baseUrl joining — double slash
+// ---------------------------------------------------------------------------
+describe("configureApi baseUrl joining edge cases", () => {
+  it("does NOT produce double slash when baseUrl ends with / and path starts with /", async () => {
+    configureApi({ baseUrl: "https://api.example.com/" });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "base.dblslash",
+      request: (id) => ({ method: "GET", path: `/items/${id}` }),
+    });
+    await action.dispatch("42");
+    const url = mockFetch.mock.calls[0]![0] as string;
+    expect(url).toBe("https://api.example.com/items/42");
+    expect(url).not.toContain("//items");
+  });
+
+  it("handles baseUrl without trailing slash and path with leading slash", async () => {
+    configureApi({ baseUrl: "https://api.example.com" });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "base.noslash",
+      request: () => ({ method: "GET", path: "/items" }),
+    });
+    await action.dispatch("x");
+    expect(mockFetch.mock.calls[0]![0]).toBe("https://api.example.com/items");
+  });
+
+  it("handles baseUrl with trailing slash and path without leading slash", async () => {
+    configureApi({ baseUrl: "https://api.example.com/" });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "base.trailslash",
+      request: () => ({ method: "GET", path: "items" }),
+    });
+    await action.dispatch("x");
+    expect(mockFetch.mock.calls[0]![0]).toBe("https://api.example.com/items");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. prepareHeaders async rejection
+// ---------------------------------------------------------------------------
+describe("prepareHeaders async rejection", () => {
+  it("surfaces as an action error (not unhandled rejection)", async () => {
+    configureApi({
+      prepareHeaders: async () => {
+        throw new Error("token refresh failed");
+      },
+    });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "prep.reject",
+      request: () => ({ method: "GET", path: "/x" }),
+    });
+    const result = await action.dispatch("x");
+    expect(result).toBeNull();
+    expect(recentLog()[0]?.status).toBe("error");
+    expect(recentLog()[0]?.error?.message).toContain("token refresh failed");
+    // fetch should NOT have been called
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("prepareHeaders sync throw also surfaces as action error", async () => {
+    configureApi({
+      prepareHeaders: () => {
+        throw new Error("sync boom");
+      },
+    });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "prep.sync.throw",
+      request: () => ({ method: "GET", path: "/x" }),
+    });
+    const result = await action.dispatch("x");
+    expect(result).toBeNull();
+    expect(recentLog()[0]?.status).toBe("error");
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. fetchFn throwing synchronously
+// ---------------------------------------------------------------------------
+describe("fetchFn throwing synchronously", () => {
+  it("surfaces as a classified action error", async () => {
+    configureApi({
+      fetchFn: () => {
+        throw new TypeError("sync network failure");
+      },
+    });
+    const action = apiAction<string>({
+      name: "fetch.sync.throw",
+      request: () => ({ method: "GET", path: "/x" }),
+    });
+    const result = await action.dispatch("x");
+    expect(result).toBeNull();
+    expect(recentLog()[0]?.status).toBe("error");
+    expect(recentLog()[0]?.error?.code).toBe("network");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. abort handle — abort after settle (double-abort)
+// ---------------------------------------------------------------------------
+describe("abort handle edge cases", () => {
+  it("abort() after settlement is a no-op (no double-fire of callbacks)", async () => {
+    const onSettled = vi.fn();
+    const action = defineAction({
+      name: "abort.after.settle",
+      run: async () => "done",
+    });
+    const handle = action.dispatch("x", { onSettled });
+    const result = await handle;
+    expect(result).toBe("done");
+    expect(onSettled).toHaveBeenCalledTimes(1);
+    // abort after settle
+    handle.abort();
+    // Give microtask queue a chance to flush
+    await Promise.resolve();
+    expect(onSettled).toHaveBeenCalledTimes(1); // still 1
+  });
+
+  it("double-abort does not throw or double-fire", async () => {
+    const onSettled = vi.fn();
+    const action = defineAction({
+      name: "abort.double",
+      run: (_a, signal) =>
+        new Promise<string>((resolve, reject) => {
+          signal.addEventListener("abort", () => reject(new Error("aborted")));
+          setTimeout(() => resolve("late"), 1000);
+        }),
+    });
+    const handle = action.dispatch("x", { onSettled });
+    handle.abort();
+    handle.abort(); // second abort — should not throw
+    const result = await handle;
+    expect(result).toBeNull();
+    expect(onSettled).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. timeout + external signal interaction (AbortSignal.any cleanup)
+// ---------------------------------------------------------------------------
+describe("timeout + external signal interaction", () => {
+  it("cancel before timeout does not leave dangling timeout firing later", async () => {
+    vi.useFakeTimers();
+    const onError = vi.fn();
+    const action = defineAction({
+      name: "timeout.cancel.before",
+      timeout: 5000,
+      run: (_a, signal) =>
+        new Promise<string>((resolve, reject) => {
+          signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")));
+        }),
+    });
+    const handle = action.dispatch("x", { onError });
+    // Cancel immediately
+    handle.abort();
+    const result = await handle;
+    expect(result).toBeNull();
+    // Advance past the timeout — should not cause any additional errors
+    await vi.advanceTimersByTimeAsync(10000);
+    expect(onError).not.toHaveBeenCalled(); // cancellation doesn't fire onError
+    vi.useRealTimers();
+  });
+
+  it("timeout fires correctly with fake timers", async () => {
+    vi.useFakeTimers();
+    const action = defineAction({
+      name: "timeout.fake.timers",
+      timeout: 100,
+      run: (_a, signal) =>
+        new Promise<string>((resolve, reject) => {
+          signal.addEventListener("abort", () => reject(signal.reason));
+        }),
+    });
+    const handle = action.dispatch("x");
+    await vi.advanceTimersByTimeAsync(150);
+    const result = await handle;
+    expect(result).toBeNull();
+    expect(recentLog().find((e) => e.name === "timeout.fake.timers")?.status).toMatch(
+      /error|cancelled/,
+    );
+    vi.useRealTimers();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. idempotency key reuse across retries
+// ---------------------------------------------------------------------------
+describe("idempotency key reuse across retries", () => {
+  it("uses the SAME idempotency key for all retry attempts", async () => {
+    let attempt = 0;
+    const keys: string[] = [];
+    configureApi({
+      fetchFn: async (_url, init) => {
+        const hdrs = (init as RequestInit).headers as Record<string, string>;
+        keys.push(hdrs["idempotency-key"] ?? "");
+        attempt++;
+        if (attempt < 3) {
+          return new Response(JSON.stringify({ error: "busy" }), { status: 503 });
+        }
+        return new Response(JSON.stringify({ ok: true }), { status: 200 });
+      },
+    });
+    const action = apiAction<string>({
+      name: "idem.retry",
+      request: () => ({ method: "POST", path: "/x", body: {} }),
+      idempotencyKey: true,
+      retry: { count: 3, delay: 0 },
+      retryable: (err) => err.status === 503,
+    });
+    const result = await action.dispatch("x");
+    expect(result).toEqual({ ok: true });
+    expect(keys.length).toBe(3);
+    // All keys must be the same
+    expect(keys[0]).toBe(keys[1]);
+    expect(keys[1]).toBe(keys[2]);
+    expect(keys[0]!.length).toBeGreaterThan(5);
+  });
+});