@cplieger/actions 1.0.0 → 1.0.1

package/src/configure-api.test.ts

@@ -0,0 +1,219 @@
+// @vitest-environment happy-dom
+// Tests for the configureApi HTTP-customization seam.
+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 { _resetForTest as resetDefine } from "./define.js";
+import { _resetForTest as resetRegistry } 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();
+});
+
+describe("configureApi — baseUrl", () => {
+  it("prepends baseUrl to request path", async () => {
+    configureApi({ baseUrl: "https://api.example.com/v1" });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    const action = apiAction<string>({
+      name: "base.url",
+      request: (id) => ({ method: "GET", path: `/items/${id}` }),
+    });
+    await action.dispatch("42");
+    expect(mockFetch.mock.calls[0]![0]).toBe("https://api.example.com/v1/items/42");
+  });
+
+  it("works without baseUrl (relative path)", async () => {
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    const action = apiAction<string>({
+      name: "no.base",
+      request: (id) => ({ method: "GET", path: `/items/${id}` }),
+    });
+    await action.dispatch("1");
+    expect(mockFetch.mock.calls[0]![0]).toBe("/items/1");
+  });
+});
+
+describe("configureApi — prepareHeaders", () => {
+  it("injects auth headers on every request", async () => {
+    configureApi({
+      prepareHeaders: (headers) => {
+        headers.set("Authorization", "Bearer test-token");
+      },
+    });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "auth.header",
+      request: () => ({ method: "GET", path: "/me" }),
+    });
+    await action.dispatch("x");
+    const headers = mockFetch.mock.calls[0]![1].headers as Record<string, string>;
+    expect(headers["authorization"]).toBe("Bearer test-token");
+  });
+
+  it("supports async prepareHeaders", async () => {
+    configureApi({
+      prepareHeaders: async (headers) => {
+        await Promise.resolve();
+        headers.set("X-CSRF", "async-token");
+      },
+    });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "async.header",
+      request: () => ({ method: "GET", path: "/x" }),
+    });
+    await action.dispatch("x");
+    const headers = mockFetch.mock.calls[0]![1].headers as Record<string, string>;
+    expect(headers["x-csrf"]).toBe("async-token");
+  });
+
+  it("receives the request spec as context", async () => {
+    const spy = vi.fn();
+    configureApi({
+      prepareHeaders: (headers, ctx) => {
+        spy(ctx.spec);
+      },
+    });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "ctx.spec",
+      request: (id) => ({ method: "POST", path: `/items/${id}`, body: { id } }),
+    });
+    await action.dispatch("5");
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ method: "POST", path: "/items/5" }));
+  });
+
+  it("does not override per-request headers set in RequestSpec", async () => {
+    configureApi({
+      prepareHeaders: (headers) => {
+        headers.set("X-Global", "global");
+        headers.set("X-Override", "from-global");
+      },
+    });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    // Per-request headers are set before prepareHeaders, so prepareHeaders wins
+    // This matches RTK behavior where prepareHeaders runs last
+    const action = apiAction<string>({
+      name: "override.test",
+      request: () => ({ method: "GET", path: "/x", headers: { "X-Override": "from-spec" } }),
+    });
+    await action.dispatch("x");
+    const headers = mockFetch.mock.calls[0]![1].headers as Record<string, string>;
+    expect(headers["x-global"]).toBe("global");
+    // prepareHeaders runs after spec headers, so it overrides
+    expect(headers["x-override"]).toBe("from-global");
+  });
+});
+
+describe("configureApi — credentials", () => {
+  it("sets credentials on every request", async () => {
+    configureApi({ credentials: "include" });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "creds",
+      request: () => ({ method: "GET", path: "/x" }),
+    });
+    await action.dispatch("x");
+    expect(mockFetch.mock.calls[0]![1].credentials).toBe("include");
+  });
+
+  it("omits credentials when not configured", async () => {
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "no.creds",
+      request: () => ({ method: "GET", path: "/x" }),
+    });
+    await action.dispatch("x");
+    expect(mockFetch.mock.calls[0]![1].credentials).toBeUndefined();
+  });
+});
+
+describe("configureApi — fetchFn", () => {
+  it("uses custom fetch implementation", async () => {
+    const customFetch = vi
+      .fn()
+      .mockResolvedValue(new Response(JSON.stringify({ custom: true }), { status: 200 }));
+    configureApi({ fetchFn: customFetch });
+    const action = apiAction<string>({
+      name: "custom.fetch",
+      request: () => ({ method: "GET", path: "/x" }),
+    });
+    const result = await action.dispatch("x");
+    expect(customFetch).toHaveBeenCalled();
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(result).toEqual({ custom: true });
+  });
+});
+
+describe("configureApi — combined", () => {
+  it("baseUrl + prepareHeaders + credentials work together", async () => {
+    configureApi({
+      baseUrl: "https://api.test.io",
+      credentials: "include",
+      prepareHeaders: (headers) => {
+        headers.set("Authorization", "Bearer combo");
+      },
+    });
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    const action = apiAction<{ name: string }>({
+      name: "combo",
+      request: ({ name }) => ({ method: "POST", path: "/items", body: { name } }),
+    });
+    await action.dispatch({ name: "test" });
+    const [url, opts] = mockFetch.mock.calls[0]!;
+    expect(url).toBe("https://api.test.io/items");
+    expect(opts.credentials).toBe("include");
+    const headers = opts.headers as Record<string, string>;
+    expect(headers["authorization"]).toBe("Bearer combo");
+    expect(headers["content-type"]).toBe("application/json");
+  });
+});
+
+describe("RequestSpec.headers — per-request headers", () => {
+  it("sends per-request headers on GET", async () => {
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "per.req.get",
+      request: () => ({ method: "GET", path: "/x", headers: { "X-Custom": "val" } }),
+    });
+    await action.dispatch("x");
+    const headers = mockFetch.mock.calls[0]![1].headers as Record<string, string>;
+    expect(headers["x-custom"]).toBe("val");
+  });
+
+  it("sends per-request headers on POST alongside Content-Type", async () => {
+    mockFetch.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+    const action = apiAction<string>({
+      name: "per.req.post",
+      request: () => ({
+        method: "POST",
+        path: "/x",
+        body: { a: 1 },
+        headers: { "X-Request-Id": "abc" },
+      }),
+    });
+    await action.dispatch("x");
+    const headers = mockFetch.mock.calls[0]![1].headers as Record<string, string>;
+    expect(headers["content-type"]).toBe("application/json");
+    expect(headers["x-request-id"]).toBe("abc");
+  });
+});

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

@@ -0,0 +1,176 @@
+// @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 } from "./define.js";
+import { _resetForTest as resetRegistry, recentLog } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+import { ActionError, retryNetwork } from "./error.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.clearAllMocks();
+});
+
+describe("two retry-configured actions in the same scope", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("second action waits for first action's retries to complete before starting", async () => {
+    let attemptA = 0;
+    let attemptB = 0;
+    const actionA = defineAction<void, string>({
+      name: "test.scope_retry_A",
+      scope: "shared",
+      retryable: retryNetwork,
+      retry: { count: 2, delay: 100 },
+      error: false,
+      run: () => {
+        attemptA++;
+        if (attemptA < 3) {
+          throw new ActionError("net", { code: "network" });
+        }
+        return Promise.resolve("A-done");
+      },
+    });
+    const actionB = defineAction<void, string>({
+      name: "test.scope_retry_B",
+      scope: "shared",
+      retryable: retryNetwork,
+      retry: { count: 1, delay: 50 },
+      error: false,
+      run: () => {
+        attemptB++;
+        return Promise.resolve("B-done");
+      },
+    });
+    const pA = actionA.dispatch();
+    await Promise.resolve();
+    const pB = actionB.dispatch();
+    await Promise.resolve();
+    expect(attemptA).toBe(1);
+    expect(attemptB).toBe(0);
+    await vi.advanceTimersByTimeAsync(100);
+    expect(attemptA).toBe(2);
+    expect(attemptB).toBe(0);
+    await vi.advanceTimersByTimeAsync(200);
+    const rA = await pA;
+    expect(rA).toBe("A-done");
+    await Promise.resolve();
+    const rB = await pB;
+    expect(rB).toBe("B-done");
+    expect(attemptB).toBe(1);
+  });
+});
+
+describe("onSuccess → dispatch chain with same scope", () => {
+  it("chained dispatch via onSuccess runs after the triggering action completes", async () => {
+    const order: string[] = [];
+    const actionA = defineAction<void, string>({
+      name: "test.chain_A",
+      scope: "chain",
+      run: () => {
+        order.push("A-run");
+        return Promise.resolve("A-result");
+      },
+    });
+    const actionB = defineAction<void, string>({
+      name: "test.chain_B",
+      scope: "chain",
+      run: () => {
+        order.push("B-run");
+        return Promise.resolve("B-result");
+      },
+    });
+    let chainedPromise: Promise<string | null> | null = null;
+    const pA = actionA.dispatch(undefined, {
+      onSuccess: () => {
+        order.push("A-onSuccess");
+        chainedPromise = actionB.dispatch();
+      },
+    });
+    const rA = await pA;
+    expect(rA).toBe("A-result");
+    const rB = await chainedPromise!;
+    expect(rB).toBe("B-result");
+    expect(order).toEqual(["A-run", "A-onSuccess", "B-run"]);
+  });
+});
+
+describe("cancellation during retry unblocks queued action", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("cancelling a retrying action lets the queued action proceed", async () => {
+    let attemptA = 0;
+    let attemptB = 0;
+    const actionA = defineAction<void, string>({
+      name: "test.cancel_retry_A",
+      scope: "cancel-scope",
+      retryable: (err) => err.code !== "cancelled",
+      retry: { count: 5, delay: 100 },
+      error: false,
+      run: () => {
+        attemptA++;
+        throw new ActionError("fail", { status: 500 });
+      },
+    });
+    const actionB = defineAction<void, string>({
+      name: "test.cancel_retry_B",
+      scope: "cancel-scope",
+      error: false,
+      run: () => {
+        attemptB++;
+        return Promise.resolve("B-done");
+      },
+    });
+    const pA = actionA.dispatch();
+    await Promise.resolve();
+    const pB = actionB.dispatch();
+    await Promise.resolve();
+    expect(attemptA).toBe(1);
+    expect(attemptB).toBe(0);
+    actionA.cancel();
+    const rA = await pA;
+    expect(rA).toBeNull();
+    await Promise.resolve();
+    const rB = await pB;
+    expect(rB).toBe("B-done");
+    expect(attemptB).toBe(1);
+  });
+});
+
+describe("throwing callbacks don't break scope chain", () => {
+  it("onSuccess throwing does not re-record action as error", async () => {
+    const action = defineAction<void, string>({
+      name: "test.cb_throw_success",
+      scope: "cb-scope",
+      run: () => Promise.resolve("ok"),
+    });
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const result = await action.dispatch(undefined, {
+      onSuccess: () => {
+        throw new Error("callback boom");
+      },
+    });
+    consoleSpy.mockRestore();
+    expect(result).toBe("ok");
+    const log = recentLog();
+    const entry = log.find((e) => e.name === "test.cb_throw_success");
+    expect(entry?.status).toBe("success");
+  });
+});

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

@@ -0,0 +1,231 @@
+// @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, retryNetwork } from "./error.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.clearAllMocks();
+});
+
+describe("dedupe + scope combined behavior", () => {
+  it("deduped dispatch shares the scope-queued promise without double-queuing", async () => {
+    let runCount = 0;
+    let resolveRun: ((v: string) => void) | null = null;
+    const action = defineAction<string, string>({
+      name: "test.dedupe_scope",
+      dedupe: true,
+      scope: "ds",
+      run: () => {
+        runCount++;
+        return new Promise<string>((r) => {
+          resolveRun = r;
+        });
+      },
+    });
+    const p1 = action.dispatch("x");
+    const p2 = action.dispatch("x");
+    await Promise.resolve();
+    expect(runCount).toBe(1);
+    resolveRun!("done");
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r1).toBe("done");
+    expect(r2).toBe("done");
+  });
+});
+
+describe("optimistic persistence across retries", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("rollback fires exactly once after all retries exhaust", async () => {
+    const rollbackCalls: string[] = [];
+    let attempt = 0;
+    const action = defineAction<string, string, string>({
+      name: "test.opt_retry_rollback",
+      retryable: (err) => err.code !== "cancelled",
+      retry: { count: 2, delay: 50 },
+      error: false,
+      optimistic: (args) => `snap-${args}`,
+      rollback: (_args, op) => {
+        rollbackCalls.push(op ?? "none");
+      },
+      run: () => {
+        attempt++;
+        throw new ActionError("fail", { status: 500 });
+      },
+    });
+    const p = action.dispatch("x");
+    await vi.advanceTimersByTimeAsync(50);
+    await vi.advanceTimersByTimeAsync(100);
+    await p;
+    expect(attempt).toBe(3);
+    expect(rollbackCalls).toEqual(["snap-x"]);
+  });
+
+  it("rollback does NOT fire when retries eventually succeed", async () => {
+    const rollbackCalls: string[] = [];
+    let attempt = 0;
+    const action = defineAction<string, string, string>({
+      name: "test.opt_retry_success",
+      retryable: retryNetwork,
+      retry: { count: 2, delay: 30 },
+      optimistic: (args) => `snap-${args}`,
+      rollback: (_args, op) => {
+        rollbackCalls.push(op ?? "none");
+      },
+      run: () => {
+        attempt++;
+        if (attempt < 3) {
+          throw new ActionError("net", { code: "network" });
+        }
+        return Promise.resolve("recovered");
+      },
+    });
+    const p = action.dispatch("y");
+    await vi.advanceTimersByTimeAsync(30);
+    await vi.advanceTimersByTimeAsync(60);
+    const result = await p;
+    expect(result).toBe("recovered");
+    expect(rollbackCalls).toEqual([]);
+  });
+});
+
+describe("onSettled re-dispatch with dedupe", () => {
+  it("dispatch from onSettled with same dedupe key starts a fresh run", async () => {
+    let runCount = 0;
+    const action = defineAction<string, string>({
+      name: "test.settled_redispatch",
+      dedupe: true,
+      run: () => {
+        runCount++;
+        return Promise.resolve(`run-${String(runCount)}`);
+      },
+    });
+    let chainedPromise: Promise<string | null> | null = null;
+    await action.dispatch("k", {
+      onSettled: () => {
+        chainedPromise = action.dispatch("k");
+      },
+    });
+    const result = await chainedPromise!;
+    expect(runCount).toBe(2);
+    expect(result).toBe("run-2");
+  });
+});
+
+describe("scope chain after optimistic throw", () => {
+  it("next action in scope runs after optimistic throw", async () => {
+    const order: string[] = [];
+    const broken = defineAction<void, string>({
+      name: "test.opt_throw",
+      scope: "opt-throw",
+      error: false,
+      optimistic: () => {
+        throw new Error("optimistic boom");
+      },
+      run: () => Promise.resolve("never"),
+    });
+    const follower = defineAction<void, string>({
+      name: "test.opt_throw_follower",
+      scope: "opt-throw",
+      run: () => {
+        order.push("follower-run");
+        return Promise.resolve("ok");
+      },
+    });
+    const pBroken = broken.dispatch();
+    const pFollower = follower.dispatch();
+    const rBroken = await pBroken;
+    expect(rBroken).toBeNull();
+    const rFollower = await pFollower;
+    expect(rFollower).toBe("ok");
+    expect(order).toEqual(["follower-run"]);
+  });
+});
+
+describe("rapid cancel + re-dispatch", () => {
+  it("re-dispatch after cancel uses a fresh AbortController", async () => {
+    const signalAborted: boolean[] = [];
+    const action = defineAction<void, string>({
+      name: "test.rapid_cancel",
+      error: false,
+      run: (_args, signal) => {
+        signalAborted.push(signal.aborted);
+        if (signal.aborted) {
+          throw new DOMException("aborted", "AbortError");
+        }
+        return Promise.resolve("ok");
+      },
+    });
+    const p1 = action.dispatch();
+    action.cancel();
+    await p1;
+    const p2 = action.dispatch();
+    const r2 = await p2;
+    expect(r2).toBe("ok");
+    expect(signalAborted[1]).toBe(false);
+  });
+});
+
+describe("idempotency key stability across retries", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("same idempotency key is passed to all retry attempts", async () => {
+    const keys: (string | undefined)[] = [];
+    const action = defineAction<void, string>({
+      name: "test.idem_retry",
+      idempotencyKey: true,
+      retryable: (err) => err.code !== "cancelled",
+      retry: { count: 2, delay: 20 },
+      error: false,
+      run: (_args, _signal, ctx) => {
+        keys.push(ctx?.idempotencyKey);
+        throw new ActionError("fail", { status: 500 });
+      },
+    });
+    const p = action.dispatch();
+    await vi.advanceTimersByTimeAsync(20);
+    await vi.advanceTimersByTimeAsync(40);
+    await p;
+    expect(keys.length).toBe(3);
+    expect(keys[0]).toBeDefined();
+    expect(keys[0]).toBe(keys[1]);
+    expect(keys[1]).toBe(keys[2]);
+  });
+
+  it("different dispatches get different idempotency keys", async () => {
+    const keys: (string | undefined)[] = [];
+    const action = defineAction<void, string>({
+      name: "test.idem_unique",
+      idempotencyKey: true,
+      run: (_args, _signal, ctx) => {
+        keys.push(ctx?.idempotencyKey);
+        return Promise.resolve("ok");
+      },
+    });
+    await action.dispatch();
+    await action.dispatch();
+    expect(keys.length).toBe(2);
+    expect(keys[0]).not.toBe(keys[1]);
+  });
+});