@cplieger/actions 1.0.0 → 1.0.1

package/src/dispatch-options.test.ts

@@ -0,0 +1,197 @@
+// @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 } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+import { ActionError, retryNetwork } from "./error.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  vi.useFakeTimers();
+  vi.clearAllMocks();
+});
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("defineAction retry { count, delay, factor }", () => {
+  it("retries up to count times on retry-class errors then succeeds", async () => {
+    let attempts = 0;
+    const action = defineAction<{ id: string }, string>({
+      name: "test.retry_recovers",
+      retryable: retryNetwork,
+      retry: { count: 2, delay: 100 },
+      run: () => {
+        attempts++;
+        if (attempts < 3) {
+          throw new ActionError("flaky", { code: "network" });
+        }
+        return Promise.resolve("ok");
+      },
+    });
+    const promise = action.dispatch({ id: "x" });
+    await vi.advanceTimersByTimeAsync(100);
+    await vi.advanceTimersByTimeAsync(200);
+    expect(await promise).toBe("ok");
+    expect(attempts).toBe(3);
+  });
+
+  it("returns null after exhausting retries", async () => {
+    let attempts = 0;
+    const action = defineAction<void, void>({
+      name: "test.retry_exhausts",
+      retryable: retryNetwork,
+      retry: { count: 2, delay: 50 },
+      error: false,
+      run: () => {
+        attempts++;
+        return Promise.reject(new ActionError("permanent network fail", { code: "network" }));
+      },
+    });
+    const promise = action.dispatch();
+    await vi.advanceTimersByTimeAsync(50);
+    await vi.advanceTimersByTimeAsync(100);
+    expect(await promise).toBeNull();
+    expect(attempts).toBe(3);
+  });
+
+  it("does NOT retry non-retry-class errors even with retry config", async () => {
+    let attempts = 0;
+    const action = defineAction<void, void>({
+      name: "test.retry_skips_4xx",
+      retryable: retryNetwork,
+      retry: { count: 3, delay: 50 },
+      error: false,
+      run: () => {
+        attempts++;
+        return Promise.reject(new ActionError("validation", { status: 422 }));
+      },
+    });
+    await action.dispatch();
+    expect(attempts).toBe(1);
+  });
+
+  it("aborts retry chain if action.cancel() during backoff", async () => {
+    let attempts = 0;
+    const action = defineAction<void, void>({
+      name: "test.retry_cancel_mid_backoff",
+      retryable: retryNetwork,
+      retry: { count: 5, delay: 1000 },
+      error: false,
+      run: () => {
+        attempts++;
+        return Promise.reject(new ActionError("fail", { code: "network" }));
+      },
+    });
+    const promise = action.dispatch();
+    await vi.advanceTimersByTimeAsync(50);
+    action.cancel();
+    await vi.advanceTimersByTimeAsync(2000);
+    await promise;
+    expect(attempts).toBe(1);
+  });
+});
+
+describe("defineAction scope (serial dispatch)", () => {
+  it("serializes dispatches sharing a static scope string", async () => {
+    const log: string[] = [];
+    const action = defineAction<{ tag: string }, string>({
+      name: "test.scope_static",
+      scope: "shared",
+      run: async (args) => {
+        log.push(`start:${args.tag}`);
+        await new Promise<void>((r) => setTimeout(r, 50));
+        log.push(`end:${args.tag}`);
+        return args.tag;
+      },
+    });
+    const p1 = action.dispatch({ tag: "A" });
+    const p2 = action.dispatch({ tag: "B" });
+    const p3 = action.dispatch({ tag: "C" });
+    await vi.advanceTimersByTimeAsync(50);
+    await vi.advanceTimersByTimeAsync(50);
+    await vi.advanceTimersByTimeAsync(50);
+    await Promise.all([p1, p2, p3]);
+    expect(log).toEqual(["start:A", "end:A", "start:B", "end:B", "start:C", "end:C"]);
+  });
+
+  it("scope queue continues after a failed dispatch", async () => {
+    const log: string[] = [];
+    const action = defineAction<{ tag: string; fail: boolean }, void>({
+      name: "test.scope_after_fail",
+      scope: "q",
+      error: false,
+      run: async (args) => {
+        log.push(`run:${args.tag}`);
+        if (args.fail) {
+          throw new ActionError("nope");
+        }
+      },
+    });
+    const p1 = action.dispatch({ tag: "A", fail: true });
+    const p2 = action.dispatch({ tag: "B", fail: false });
+    await Promise.all([p1, p2]);
+    expect(log).toEqual(["run:A", "run:B"]);
+  });
+});
+
+describe("DispatchOptions onSuccess / onError / onSettled", () => {
+  it("onSuccess fires with result + args", async () => {
+    const action = defineAction<{ x: number }, number>({
+      name: "test.cb_success",
+      run: (args) => Promise.resolve(args.x * 2),
+    });
+    const onSuccess = vi.fn();
+    const onError = vi.fn();
+    const onSettled = vi.fn();
+    await action.dispatch({ x: 21 }, { onSuccess, onError, onSettled });
+    expect(onSuccess).toHaveBeenCalledWith(42, { x: 21 });
+    expect(onError).not.toHaveBeenCalled();
+    expect(onSettled).toHaveBeenCalledWith({ x: 21 });
+  });
+
+  it("onError fires with error + args", async () => {
+    const action = defineAction<{ tag: string }, void>({
+      name: "test.cb_error",
+      error: false,
+      run: () => Promise.reject(new ActionError("nope", { status: 422 })),
+    });
+    const onError = vi.fn();
+    const onSettled = vi.fn();
+    await action.dispatch({ tag: "z" }, { onError, onSettled });
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: "nope", status: 422 }),
+      { tag: "z" },
+    );
+    expect(onSettled).toHaveBeenCalledWith({ tag: "z" });
+  });
+
+  it("onSettled fires on cancellation; onSuccess/onError do NOT", async () => {
+    const action = defineAction<void, void>({
+      name: "test.cb_cancel",
+      run: (_args, signal) =>
+        new Promise<void>((_, reject) => {
+          signal.addEventListener("abort", () => {
+            reject(new Error("cancelled"));
+          });
+        }),
+    });
+    const onSuccess = vi.fn();
+    const onError = vi.fn();
+    const onSettled = vi.fn();
+    const promise = action.dispatch(undefined, { onSuccess, onError, onSettled });
+    action.cancel();
+    await promise;
+    expect(onSuccess).not.toHaveBeenCalled();
+    expect(onError).not.toHaveBeenCalled();
+    expect(onSettled).toHaveBeenCalledTimes(1);
+  });
+});

package/src/edge-cases.test.ts

@@ -0,0 +1,81 @@
+// @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 { configureTransport, transportAction, _resetTransportForTest } from "./transport.js";
+import { ActionError, retryNetwork } from "./error.js";
+
+const mockSend = vi.fn();
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  _resetTransportForTest();
+  vi.clearAllMocks();
+  configureTransport(mockSend);
+});
+
+describe("runWithRetry: no retry on abort even for retry-class errors", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("signal aborted externally before run() throws — no retry", async () => {
+    let attempts = 0;
+    const action = defineAction<void, string>({
+      name: "test.abort_no_retry",
+      retryable: retryNetwork,
+      retry: { count: 3, delay: 100 },
+      error: false,
+      run: async (_args, signal) => {
+        attempts++;
+        if (attempts === 1) {
+          await new Promise<void>((resolve) => {
+            signal.addEventListener(
+              "abort",
+              () => {
+                resolve();
+              },
+              { once: true },
+            );
+          });
+          throw new ActionError("network error", { code: "network" });
+        }
+        return "should not reach";
+      },
+    });
+    const p = action.dispatch();
+    action.cancel();
+    await vi.advanceTimersByTimeAsync(1000);
+    const result = await p;
+    expect(result).toBeNull();
+    expect(attempts).toBe(1);
+    expect(recentLog()[0]?.status).toBe("cancelled");
+  });
+});
+
+describe("transportAction: spread preserves type field", () => {
+  it("idempotencyKey spread preserves the command type field", async () => {
+    mockSend.mockResolvedValue({ ok: true, status: 200 });
+    const action = transportAction<{ chatID: string }>({
+      name: "test.type_preserved",
+      idempotencyKey: true,
+      command: ({ chatID }) => ({ type: "cancel" as const, chat_id: chatID }),
+      error: false,
+    });
+    await action.dispatch({ chatID: "c1" });
+    const sentCmd = mockSend.mock.calls[0]![0] as { type: string };
+    expect(sentCmd.type).toBe("cancel");
+  });
+});

package/src/error.test.ts

@@ -0,0 +1,268 @@
+import { describe, it, expect } from "vitest";
+import {
+  ActionError,
+  hasErrorString,
+  toActionError,
+  classifyFetchError,
+  retryNetwork,
+} from "./error.js";
+
+describe("ActionError", () => {
+  it("sets message, status, code, and cause", () => {
+    const cause = new Error("root");
+    const err = new ActionError("fail", { status: 409, code: "conflict", cause });
+    expect(err.message).toBe("fail");
+    expect(err.status).toBe(409);
+    expect(err.code).toBe("conflict");
+    expect(err.cause).toBe(cause);
+    expect(err.name).toBe("ActionError");
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it("works with no options", () => {
+    const err = new ActionError("simple");
+    expect(err.message).toBe("simple");
+    expect(err.status).toBeUndefined();
+    expect(err.code).toBeUndefined();
+    expect(err.cause).toBeUndefined();
+  });
+});
+
+describe("hasErrorString", () => {
+  it("returns true for { error: string }", () => {
+    expect(hasErrorString({ error: "bad" })).toBe(true);
+  });
+
+  it("returns false for null", () => {
+    expect(hasErrorString(null)).toBe(false);
+  });
+
+  it("returns false for non-object", () => {
+    expect(hasErrorString("string")).toBe(false);
+    expect(hasErrorString(42)).toBe(false);
+    expect(hasErrorString(undefined)).toBe(false);
+  });
+
+  it("returns false when error is not a string", () => {
+    expect(hasErrorString({ error: 123 })).toBe(false);
+    expect(hasErrorString({ error: null })).toBe(false);
+    expect(hasErrorString({})).toBe(false);
+  });
+});
+
+describe("toActionError", () => {
+  it("preserves ActionError fields", () => {
+    const err = new ActionError("x", { status: 404, code: "not_found" });
+    const result = toActionError(err);
+    expect(result.message).toBe("x");
+    expect(result.status).toBe(404);
+    expect(result.code).toBe("not_found");
+  });
+
+  it("maps DOMException TimeoutError", () => {
+    const dom = new DOMException("timed out", "TimeoutError");
+    const result = toActionError(dom);
+    expect(result.code).toBe("timeout");
+    expect(result.status).toBe(0);
+    expect(result.cause).toBe(dom);
+  });
+
+  it("maps DOMException AbortError", () => {
+    const dom = new DOMException("aborted", "AbortError");
+    const result = toActionError(dom);
+    expect(result.code).toBe("cancelled");
+    expect(result.status).toBeUndefined();
+  });
+
+  it("maps DOMException NetworkError", () => {
+    const dom = new DOMException("network", "NetworkError");
+    const result = toActionError(dom);
+    expect(result.code).toBe("network");
+    expect(result.status).toBe(0);
+  });
+
+  it("maps unknown DOMException name to lowercase", () => {
+    const dom = new DOMException("custom", "CustomError");
+    const result = toActionError(dom);
+    expect(result.code).toBe("customerror");
+  });
+
+  it("handles plain Error", () => {
+    const err = new Error("plain");
+    const result = toActionError(err);
+    expect(result.message).toBe("plain");
+    expect(result.cause).toBe(err);
+    expect(result.status).toBeUndefined();
+  });
+
+  it("preserves numeric status from Error-like objects", () => {
+    const err = Object.assign(new Error("http fail"), { status: 503 });
+    const result = toActionError(err);
+    expect(result.message).toBe("http fail");
+    expect(result.status).toBe(503);
+    expect(result.cause).toBe(err);
+  });
+
+  it("ignores non-numeric status on Error-like objects", () => {
+    const err = Object.assign(new Error("bad"), { status: "not a number" });
+    const result = toActionError(err);
+    expect(result.status).toBeUndefined();
+  });
+
+  it("handles non-Error values (string)", () => {
+    const result = toActionError("oops");
+    expect(result.message).toBe("oops");
+    expect(result.cause).toBe("oops");
+  });
+
+  it("handles non-Error values (number)", () => {
+    const result = toActionError(42);
+    expect(result.message).toBe("42");
+  });
+
+  it("handles empty string thrown", () => {
+    const result = toActionError("");
+    expect(result.message).toBe("Unknown error (empty value thrown)");
+    expect(result.code).toBe("unknown");
+    expect(result.cause).toBe("");
+  });
+
+  it("handles false thrown", () => {
+    const result = toActionError(false);
+    expect(result.message).toBe("false");
+    expect(result.cause).toBe(false);
+  });
+
+  it("handles null thrown", () => {
+    const result = toActionError(null);
+    expect(result.message).toBe("Unknown error (null thrown)");
+    expect(result.code).toBe("unknown");
+    expect(result.cause).toBeUndefined();
+  });
+
+  it("handles undefined thrown", () => {
+    const result = toActionError(undefined);
+    expect(result.message).toBe("Unknown error (undefined thrown)");
+    expect(result.code).toBe("unknown");
+    expect(result.cause).toBeUndefined();
+  });
+
+  it("handles object with null message", () => {
+    const obj = { message: null };
+    const result = toActionError(obj);
+    expect(result.message).toBe("null");
+    expect(result.cause).toBe(obj);
+  });
+
+  it("handles object with undefined message", () => {
+    const obj = { message: undefined };
+    const result = toActionError(obj);
+    expect(result.message).toBe("undefined");
+    expect(result.cause).toBe(obj);
+  });
+});
+
+describe("classifyFetchError", () => {
+  it("returns cancelled when signal is aborted", () => {
+    const ac = new AbortController();
+    ac.abort();
+    const err = classifyFetchError(new Error("fetch failed"), ac.signal);
+    expect(err).toBeInstanceOf(ActionError);
+    expect(err.code).toBe("cancelled");
+    expect(err.cause).toBeInstanceOf(Error);
+  });
+
+  it("returns timeout for DOMException TimeoutError", () => {
+    const ac = new AbortController();
+    const dom = new DOMException("timed out", "TimeoutError");
+    const err = classifyFetchError(dom, ac.signal);
+    expect(err.code).toBe("timeout");
+    expect(err.status).toBe(0);
+    expect(err.message).toBe("Request timed out");
+  });
+
+  it("returns timeout for DOMException AbortError when signal is NOT aborted", () => {
+    const ac = new AbortController();
+    const dom = new DOMException("aborted", "AbortError");
+    const err = classifyFetchError(dom, ac.signal);
+    expect(err.code).toBe("timeout");
+    expect(err.status).toBe(0);
+  });
+
+  it("returns network for non-DOMException errors", () => {
+    const ac = new AbortController();
+    const err = classifyFetchError(new TypeError("Failed to fetch"), ac.signal);
+    expect(err.code).toBe("network");
+    expect(err.status).toBe(0);
+    expect(err.message).toBe("Failed to fetch");
+  });
+
+  it("returns network with generic message for non-Error values", () => {
+    const ac = new AbortController();
+    const err = classifyFetchError(42, ac.signal);
+    expect(err.code).toBe("network");
+    expect(err.status).toBe(0);
+    expect(err.message).toBe("network error");
+  });
+});
+
+describe("retryNetwork preset", () => {
+  it("returns true for network/timeout codes", () => {
+    expect(retryNetwork({ message: "x", code: "network" })).toBe(true);
+    expect(retryNetwork({ message: "x", code: "timeout" })).toBe(true);
+    expect(retryNetwork({ message: "x", status: 0 })).toBe(true);
+  });
+
+  it("returns true for transient HTTP statuses (408/429/502/503/504)", () => {
+    expect(retryNetwork({ message: "x", status: 408 })).toBe(true);
+    expect(retryNetwork({ message: "x", status: 429 })).toBe(true);
+    expect(retryNetwork({ message: "x", status: 502 })).toBe(true);
+    expect(retryNetwork({ message: "x", status: 503 })).toBe(true);
+    expect(retryNetwork({ message: "x", status: 504 })).toBe(true);
+  });
+
+  it("returns false for non-transient statuses", () => {
+    expect(retryNetwork({ message: "x", status: 400 })).toBe(false);
+    expect(retryNetwork({ message: "x", status: 500 })).toBe(false);
+    expect(retryNetwork({ message: "x", status: 404 })).toBe(false);
+  });
+
+  it("returns false for cancelled regardless of status", () => {
+    expect(retryNetwork({ message: "x", code: "cancelled", status: 503 })).toBe(false);
+    expect(retryNetwork({ message: "x", code: "cancelled" })).toBe(false);
+  });
+
+  it("returns false for app-specific codes that don't match network signature", () => {
+    expect(retryNetwork({ message: "x", code: "send_failed" })).toBe(false);
+    expect(retryNetwork({ message: "x", code: "clipboard" })).toBe(false);
+    expect(retryNetwork({ message: "x", code: "unsupported" })).toBe(false);
+    expect(retryNetwork({ message: "x", code: "server_rejected" })).toBe(false);
+  });
+
+  it("composes with custom permanent-code filter", () => {
+    const PERMANENT = new Set(["custom_permanent"]);
+    const composed = (err: { code?: string; status?: number; message: string }): boolean =>
+      !PERMANENT.has(err.code ?? "") && retryNetwork(err);
+    expect(composed({ message: "x", code: "network" })).toBe(true);
+    expect(composed({ message: "x", code: "custom_permanent", status: 0 })).toBe(false);
+  });
+});
+
+describe("classifyFetchError — TypeError branch", () => {
+  it("returns network with TypeError message for TypeError", () => {
+    const ac = new AbortController();
+    const te = new TypeError("Failed to fetch");
+    const err = classifyFetchError(te, ac.signal);
+    expect(err.code).toBe("network");
+    expect(err.status).toBe(0);
+    expect(err.message).toBe("Failed to fetch");
+    expect(err.cause).toBe(te);
+  });
+
+  it("prefers cancelled over TypeError when signal is aborted", () => {
+    const ac = new AbortController();
+    ac.abort();
+    const err = classifyFetchError(new TypeError("Failed to fetch"), ac.signal);
+    expect(err.code).toBe("cancelled");
+  });
+});

package/src/leak-stress.test.ts

@@ -0,0 +1,117 @@
+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, pendingCount, recentLog } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+
+beforeEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+});
+afterEach(() => {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+});
+
+describe("memory leak stress — scopeChains", () => {
+  it("1000 scoped dispatches leave scopeChains empty", async () => {
+    const action = defineAction({ name: "stress.scope", scope: "s", run: async () => "ok" });
+    const promises: Promise<unknown>[] = [];
+    for (let i = 0; i < 1000; i++) {
+      promises.push(action.dispatch({ i }));
+    }
+    await Promise.all(promises);
+    expect(_internalsForTest().scopeChains).toBe(0);
+  });
+});
+
+describe("memory leak stress — activeDedupes", () => {
+  it("1000 deduped dispatches leave activeDedupes empty", async () => {
+    let callCount = 0;
+    const action = defineAction({
+      name: "stress.dedupe",
+      dedupe: true,
+      run: async (args: { v: number }) => {
+        callCount++;
+        return args.v;
+      },
+    });
+    const promises: Promise<unknown>[] = [];
+    for (let i = 0; i < 1000; i++) {
+      promises.push(action.dispatch({ v: i % 5 }));
+    }
+    await Promise.all(promises);
+    expect(_internalsForTest().activeDedupes).toBe(0);
+    expect(callCount).toBe(5);
+  });
+});
+
+describe("memory leak stress — inFlight (via pendingCount)", () => {
+  it("1000 parallel dispatches leave no pending entries", async () => {
+    const action = defineAction({ name: "stress.parallel", run: async () => "ok" });
+    const promises: Promise<unknown>[] = [];
+    for (let i = 0; i < 1000; i++) {
+      promises.push(action.dispatch({ i }));
+    }
+    await Promise.all(promises);
+    expect(pendingCount(["stress.parallel"])).toBe(0);
+  });
+
+  it("1000 dispatches with errors leave no pending entries", async () => {
+    const action = defineAction({
+      name: "stress.errors",
+      error: false,
+      run: async () => {
+        throw new Error("fail");
+      },
+    });
+    const promises: Promise<unknown>[] = [];
+    for (let i = 0; i < 1000; i++) {
+      promises.push(action.dispatch({ i }));
+    }
+    await Promise.all(promises);
+    expect(pendingCount(["stress.errors"])).toBe(0);
+  });
+});
+
+describe("memory leak stress — combined scope + dedupe", () => {
+  it("1000 scoped+deduped dispatches leave maps empty", async () => {
+    const action = defineAction({
+      name: "stress.both",
+      scope: "shared",
+      dedupe: true,
+      run: async (args: { v: number }) => args.v,
+    });
+    const promises: Promise<unknown>[] = [];
+    for (let i = 0; i < 1000; i++) {
+      promises.push(action.dispatch({ v: i % 3 }));
+    }
+    await Promise.all(promises);
+    const internals = _internalsForTest();
+    expect(internals.scopeChains).toBe(0);
+    expect(internals.activeDedupes).toBe(0);
+    expect(pendingCount(["stress.both"])).toBe(0);
+  });
+});
+
+describe("memory leak stress — registry log eviction", () => {
+  it("1000 dispatches with full lifecycle: log stays bounded at MAX_LOG_SIZE", async () => {
+    const action = defineAction({
+      name: "stress.registry",
+      run: async (args: { i: number }) => args.i,
+    });
+    for (let i = 0; i < 1000; i++) {
+      await action.dispatch({ i });
+    }
+    const log = recentLog();
+    expect(log.length).toBeLessThanOrEqual(200);
+    expect(log.every((e) => e.status !== "pending")).toBe(true);
+  });
+});