@cplieger/actions 1.0.0

package/eslint.config.base.mjs

@@ -0,0 +1,186 @@
+// Strict typed-linting config.
+// References:
+//   https://typescript-eslint.io/users/configs/#strict-type-checked
+//   https://typescript-eslint.io/users/configs/#stylistic-type-checked
+//   https://typescript-eslint.io/getting-started/typed-linting
+
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default [
+  // 1. Ignore generated/build outputs and configs that don't need linting.
+  {
+    ignores: [
+      // Dependencies (any depth)
+      "**/node_modules/**",
+      // Build output / generated bundles (TS->JS, CSS bundles, etc.)
+      "**/static/**",
+      "**/dist/**",
+      "**/build/**",
+      "**/.next/**",
+      "**/.cache/**",
+      "**/coverage/**",
+      // Minified / generated source
+      "**/*.min.*",
+      "**/*.gen.ts",
+      "**/*.gen.js",
+      "**/wire/*.gen.ts",
+      // Test fixtures that aren't real code
+      "**/test-stubs/**",
+      "**/__mocks__/**",
+    ],
+  },
+  // 2. Strictest official preset combination (typed linting required).
+  js.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  ...tseslint.configs.stylisticTypeChecked,
+
+  // 3. Project setup — projectService auto-discovers tsconfig per file.
+  {
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: "module",
+      parserOptions: {
+        projectService: {
+          allowDefaultProject: ["*.test.ts", "*.property.test.ts", "fc-strict-setup.ts"],
+          maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING: 20,
+        },
+        tsconfigRootDir: import.meta.dirname,
+      },
+      globals: {
+        // Browser
+        window: "readonly",
+        document: "readonly",
+        navigator: "readonly",
+        console: "readonly",
+        fetch: "readonly",
+        URL: "readonly",
+        URLSearchParams: "readonly",
+        setTimeout: "readonly",
+        clearTimeout: "readonly",
+        setInterval: "readonly",
+        clearInterval: "readonly",
+        requestAnimationFrame: "readonly",
+        cancelAnimationFrame: "readonly",
+        queueMicrotask: "readonly",
+        WebSocket: "readonly",
+        EventSource: "readonly",
+        AbortController: "readonly",
+        Headers: "readonly",
+        Request: "readonly",
+        Response: "readonly",
+        FormData: "readonly",
+        Blob: "readonly",
+        File: "readonly",
+        FileReader: "readonly",
+        IntersectionObserver: "readonly",
+        MutationObserver: "readonly",
+        ResizeObserver: "readonly",
+        CustomEvent: "readonly",
+        Event: "readonly",
+        EventTarget: "readonly",
+        TextEncoder: "readonly",
+        TextDecoder: "readonly",
+        crypto: "readonly",
+        btoa: "readonly",
+        atob: "readonly",
+        // Service Worker
+        self: "readonly",
+        ServiceWorkerGlobalScope: "readonly",
+        clients: "readonly",
+        // Test runner globals (vitest auto-injected)
+        describe: "readonly",
+        it: "readonly",
+        test: "readonly",
+        expect: "readonly",
+        beforeAll: "readonly",
+        beforeEach: "readonly",
+        afterAll: "readonly",
+        afterEach: "readonly",
+        vi: "readonly",
+      },
+    },
+    rules: {
+      // Allow `_`-prefixed unused names.
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+          ignoreRestSiblings: true,
+        },
+      ],
+      // Enforce `import type {...}` for types.
+      "@typescript-eslint/consistent-type-imports": [
+        "error",
+        { prefer: "type-imports", fixStyle: "inline-type-imports" },
+      ],
+      // Discourage `any`, prefer `unknown`.
+      "@typescript-eslint/no-explicit-any": "error",
+      // Avoid silent fall-through bugs in async event handlers.
+      "@typescript-eslint/no-misused-promises": [
+        "error",
+        { checksVoidReturn: { attributes: false } },
+      ],
+      // Prefer literal numeric/string template parts (catches accidental coercion).
+      "@typescript-eslint/restrict-template-expressions": [
+        "error",
+        { allowNumber: true, allowBoolean: true, allowNullish: false },
+      ],
+      // Console policy.
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+      // Equality: enforce strict ===.
+      eqeqeq: ["error", "always", { null: "ignore" }],
+      curly: ["error", "all"],
+      "no-var": "error",
+      "prefer-const": "error",
+      "no-throw-literal": "error",
+    },
+  },
+
+  // 4. Tests: typed but with relaxed rules (tests deliberately break invariants).
+  {
+    files: [
+      "**/*.test.ts",
+      "**/*.fuzz.test.ts",
+      "**/*.property.test.ts",
+      "**/test-helpers/**",
+      "**/__mocks__/**",
+    ],
+    rules: {
+      "@typescript-eslint/no-non-null-assertion": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/no-unsafe-call": "off",
+      "@typescript-eslint/no-unsafe-argument": "off",
+      "@typescript-eslint/no-unsafe-return": "off",
+      "@typescript-eslint/no-extraneous-class": "off",
+      "@typescript-eslint/no-unnecessary-condition": "off",
+      "@typescript-eslint/no-misused-spread": "off",
+      "@typescript-eslint/unbound-method": "off",
+      "@typescript-eslint/require-await": "off",
+      "no-console": "off",
+    },
+  },
+
+  // 5. Generated and config files + tests: drop type-checked rules.
+  {
+    files: [
+      "**/*.gen.ts",
+      "**/wire/*.ts",
+      "vitest.config.ts",
+      "*.config.ts",
+      "*.config.mjs",
+      "*.config.js",
+      "**/*.test.ts",
+      "**/*.fuzz.test.ts",
+      "**/*.property.test.ts",
+      "fc-strict-setup.ts",
+      "test-stubs/**",
+    ],
+    ...tseslint.configs.disableTypeChecked,
+  },
+];

package/jsr.json

@@ -0,0 +1,22 @@
+{
+  "name": "@cplieger/actions",
+  "version": "0.1.0",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publish": {
+    "exclude": [
+      "**/*.test.ts",
+      "**/__test-helpers__",
+      "**/fc-strict-setup.ts",
+      "eslint.config.mjs",
+      "tsconfig.json",
+      "tsconfig.test.json",
+      "tsconfig.tests.json",
+      "vitest.config.ts",
+      "renovate.json",
+      "package-lock.json",
+      ".prettierrc.json"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cplieger/actions",
+  "version": "1.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsgo -project tsconfig.json",
+    "typecheck:tests": "tsgo -project tsconfig.test.json",
+    "test": "vitest --run"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.12.4",
+    "@vitest/coverage-v8": "4.1.7",
+    "eslint": "10.4.1",
+    "fast-check": "4.8.0",
+    "happy-dom": "20.9.0",
+    "prettier": "3.8.3",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.60.0",
+    "vitest": "4.1.7"
+  },
+  "description": "Declarative async UI-action framework for TypeScript",
+  "license": "GPL-3.0-or-later",
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cplieger/actions.git"
+  }
+}

package/src/api.ts

@@ -0,0 +1,209 @@
+// apiAction: factory for HTTP-backed actions. Wraps fetch so the run()
+// implementation is just the request descriptor.
+// ---------------------------------------------------------------------------
+
+import { defineAction, IDEMPOTENCY_HEADER } from "./define.js";
+import { ActionError, classifyFetchError, hasErrorString } from "./error.js";
+import type { Action, ActionContext, ActionDefinition, RequestSpec } from "./types.js";
+
+/** Default request timeout in milliseconds. */
+export const API_TIMEOUT_MS = 30_000;
+
+/**
+ * Compose an optional caller signal with a fresh timeout signal.
+ * If the caller provides an existing signal, the result aborts when
+ * either the caller signal or the timeout fires — whichever comes first.
+ *
+ * @param signal - Existing signal to compose with (may be undefined).
+ * @param ms - Timeout in milliseconds.
+ * @returns A composed AbortSignal.
+ */
+export function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal {
+  return signal !== undefined
+    ? AbortSignal.any([signal, AbortSignal.timeout(ms)])
+    : AbortSignal.timeout(ms);
+}
+
+const JSON_CT = "application/json";
+
+// ---------------------------------------------------------------------------
+// HTTP customization seam (mirrors RTK fetchBaseQuery pattern)
+// ---------------------------------------------------------------------------
+
+/** Configuration for the global API fetch layer. Set via `configureApi()`. */
+export interface ApiConfig {
+  /** Base URL prepended to every RequestSpec.path (e.g. "https://api.example.com/v1"). */
+  readonly baseUrl?: string;
+  /** Inject headers on every request. Receives current headers + the request spec.
+   *  Mutate and/or return the headers object. May be async (e.g. to read a token store). */
+  readonly prepareHeaders?: (
+    headers: Headers,
+    context: { spec: RequestSpec },
+  ) => Headers | undefined | Promise<Headers | undefined>;
+  /** RequestInit.credentials mode applied to every request (e.g. "include" for cookies). */
+  readonly credentials?: RequestCredentials;
+  /** Custom fetch implementation. Useful for SSR (isomorphic-fetch) or testing. */
+  readonly fetchFn?: typeof fetch;
+}
+
+let _apiConfig: ApiConfig = {};
+
+/**
+ * Configure the global HTTP layer used by all `apiAction` instances.
+ * Call once at app boot. Subsequent calls replace the previous config.
+ *
+ * @example
+ * ```ts
+ * configureApi({
+ *   baseUrl: "https://api.example.com",
+ *   credentials: "include",
+ *   prepareHeaders: (headers) => {
+ *     headers.set("Authorization", `Bearer ${getToken()}`);
+ *   },
+ * });
+ * ```
+ */
+export function configureApi(config: ApiConfig): void {
+  _apiConfig = config;
+}
+
+/** Reset API config. @internal Test-only. */
+export function _resetApiConfigForTest(): void {
+  _apiConfig = {};
+}
+
+// ---------------------------------------------------------------------------
+
+/** Caller-facing shape of an apiAction definition. Replaces `run` with
+ *  a `request` function that returns an HTTP {@link RequestSpec}. */
+export interface ApiActionDefinition<TArgs, TResult, TOp = unknown> extends Omit<
+  ActionDefinition<TArgs, TResult, TOp>,
+  "run"
+> {
+  request: (args: TArgs) => RequestSpec;
+}
+
+/**
+ * Build an Action from an HTTP request descriptor.
+ * Wraps `defineAction` with a generated `run()` that calls `fetch`
+ * via the global {@link ApiConfig} layer configured with {@link configureApi}.
+ */
+export function apiAction<TArgs, TResult = unknown, TOp = unknown>(
+  def: ApiActionDefinition<TArgs, TResult, TOp>,
+): Action<TArgs, TResult> {
+  const { request, ...rest } = def;
+  return defineAction<TArgs, TResult, TOp>({
+    ...rest,
+    run: async (args, signal, ctx) => {
+      const spec = request(args);
+      return executeRequest<TResult>(spec, signal, ctx);
+    },
+  });
+}
+
+async function executeRequest<T>(
+  spec: RequestSpec,
+  signal: AbortSignal,
+  ctx?: ActionContext,
+): Promise<T> {
+  const cfg = _apiConfig;
+  const init: RequestInit = { method: spec.method };
+
+  // Build headers via Headers API for prepareHeaders compatibility
+  const headers = new Headers();
+  if (spec.method !== "GET" && spec.body !== undefined) {
+    headers.set("Content-Type", JSON_CT);
+    init.body = JSON.stringify(spec.body);
+  }
+  if (ctx?.idempotencyKey !== undefined) {
+    headers.set(IDEMPOTENCY_HEADER, ctx.idempotencyKey);
+  }
+  // Per-request headers from RequestSpec
+  if (spec.headers !== undefined) {
+    for (const [k, v] of Object.entries(spec.headers)) {
+      headers.set(k, v);
+    }
+  }
+  // Global prepareHeaders hook
+  if (cfg.prepareHeaders !== undefined) {
+    await cfg.prepareHeaders(headers, { spec });
+  }
+  // Convert Headers to plain object for RequestInit
+  const headerObj: Record<string, string> = {};
+  headers.forEach((v, k) => {
+    headerObj[k.toLowerCase()] = v;
+  });
+  if (Object.keys(headerObj).length > 0) {
+    init.headers = headerObj;
+  }
+
+  // Credentials
+  if (cfg.credentials !== undefined) {
+    init.credentials = cfg.credentials;
+  }
+
+  init.signal = withTimeout(signal, API_TIMEOUT_MS);
+
+  // Resolve URL: prepend baseUrl if configured, normalizing double slashes at the join
+  let url: string;
+  if (cfg.baseUrl !== undefined) {
+    const base = cfg.baseUrl.endsWith("/") ? cfg.baseUrl.slice(0, -1) : cfg.baseUrl;
+    const path = spec.path.startsWith("/") ? spec.path : `/${spec.path}`;
+    url = `${base}${path}`;
+  } else {
+    url = spec.path;
+  }
+
+  // Use custom fetchFn or global fetch
+  const fetchImpl = cfg.fetchFn ?? fetch;
+
+  let r: Response;
+  try {
+    r = await fetchImpl(url, init);
+  } catch (e) {
+    throw classifyFetchError(e, signal);
+  }
+  if (!r.ok) {
+    let serverError = "";
+    let serverCode: string | undefined;
+    try {
+      const body: unknown = await r.json();
+      if (hasErrorString(body)) {
+        serverError = body.error;
+      }
+      if (typeof body === "object" && body !== null && "code" in body) {
+        const code = (body as Record<"code", unknown>).code;
+        if (typeof code === "string") {
+          serverCode = code;
+        }
+      }
+    } catch {
+      // Body wasn't JSON — leave serverError empty.
+    }
+    const opts: { status: number; code?: string } = { status: r.status };
+    if (serverCode !== undefined) {
+      opts.code = serverCode;
+    }
+    throw new ActionError(serverError !== "" ? serverError : `HTTP ${String(r.status)}`, opts);
+  }
+  if (r.status === 204) {
+    return undefined as T;
+  }
+  const text = await r.text();
+  if (text === "") {
+    if (spec.method !== "DELETE") {
+      console.warn(
+        `[actions] ${spec.method} ${spec.path} returned empty body — callers expecting data will receive undefined`,
+      );
+    }
+    return undefined as T;
+  }
+  try {
+    return JSON.parse(text) as T;
+  } catch (e) {
+    throw new ActionError(`response not JSON: ${e instanceof Error ? e.message : String(e)}`, {
+      status: r.status,
+      cause: e,
+    });
+  }
+}

package/src/cleanup.ts

@@ -0,0 +1,76 @@
+// Global cleanup: cancel all in-flight actions + run registered
+// cleanup hooks. Wired to window.beforeunload so navigation away
+// from the page aborts everything cleanly.
+//
+// Cleanup hooks must be idempotent. Cancellation is allowed to fire
+// multiple times (e.g., cancelled navigation followed by confirmed).
+// ---------------------------------------------------------------------------
+
+import type { Action } from "./types.js";
+
+/** Minimal shape needed for cleanup — avoids variance-unsafe casts. */
+interface Cancellable {
+  readonly name: string;
+  cancel(): void;
+}
+
+const trackedActions = new Set<Cancellable>();
+const cleanupHooks = new Set<() => void>();
+let beforeunloadInstalled = false;
+
+/** Internal: register an Action so cancelAllPending() can iterate it. */
+export function _registerAction<TArgs, TResult>(action: Action<TArgs, TResult>): void {
+  trackedActions.add(action);
+  installBeforeunloadOnce();
+}
+
+/**
+ * Register a cleanup function to run on page unload (or test invoke).
+ */
+export function registerCleanup(fn: () => void): () => void {
+  cleanupHooks.add(fn);
+  installBeforeunloadOnce();
+  return () => cleanupHooks.delete(fn);
+}
+
+function cancelAllPending(): void {
+  for (const action of trackedActions) {
+    try {
+      action.cancel();
+    } catch (e) {
+      console.error(`[actions] cancel for ${action.name} threw`, e);
+    }
+  }
+  for (const fn of [...cleanupHooks]) {
+    try {
+      fn();
+    } catch (e) {
+      console.error("[actions] cleanup hook threw", e);
+    }
+  }
+}
+
+function installBeforeunloadOnce(): void {
+  if (beforeunloadInstalled) {
+    return;
+  }
+  beforeunloadInstalled = true;
+  if (typeof window !== "undefined") {
+    window.addEventListener("beforeunload", cancelAllPending);
+  }
+}
+
+/** Test-only: invoke the same cleanup logic that beforeunload runs. */
+export function _cancelAllForTest(): void {
+  cancelAllPending();
+}
+
+/** Test-only: clear both registries + uninstall the listener. */
+export function _resetForTest(): void {
+  trackedActions.clear();
+  cleanupHooks.clear();
+  if (beforeunloadInstalled && typeof window !== "undefined") {
+    window.removeEventListener("beforeunload", cancelAllPending);
+  }
+  beforeunloadInstalled = false;
+}

package/src/debounce.ts

@@ -0,0 +1,128 @@
+// debouncedDispatch: wrap an Action so that rapid calls coalesce into
+// a single dispatch after a quiet window. Replaces ad-hoc setTimeout
+// + clearTimeout chains with a single helper that adds flush/cancel.
+// ---------------------------------------------------------------------------
+
+import type { Action } from "./types.js";
+
+/** A debounced action dispatcher. Callable to schedule a dispatch,
+ *  with `flush`, `cancel`, and `isPending` control methods. */
+export interface DebouncedDispatch<TArgs> {
+  /** Schedule a dispatch with the given args. Replaces any pending
+   *  dispatch's args. */
+  (args: TArgs): void;
+
+  /** Fire immediately with the most-recent args (or args supplied
+   *  here, overriding the pending). No-op if nothing is pending and
+   *  no args supplied. */
+  flush(args?: TArgs): Promise<unknown> | undefined;
+
+  /** Discard any pending dispatch without firing. */
+  cancel(): void;
+
+  /** True if there's a scheduled dispatch waiting for the timer. */
+  isPending(): boolean;
+}
+
+interface DebounceOptions {
+  /** Quiet window in ms. */
+  readonly wait: number;
+  /** Fire on the leading edge instead of the trailing edge. Default false. */
+  readonly leading?: boolean;
+}
+
+/**
+ * Wrap an action with a debounce timer so rapid calls coalesce into a
+ * single dispatch after a quiet window.
+ */
+export function debouncedDispatch<TArgs, TResult>(
+  action: Action<TArgs, TResult>,
+  opts: DebounceOptions,
+): DebouncedDispatch<TArgs> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let lastArgs: TArgs | undefined;
+  let pending = false;
+  let lastFiredAt = 0;
+
+  const fn = ((args: TArgs): void => {
+    if (opts.leading === true) {
+      const now = Date.now();
+      if (now - lastFiredAt < opts.wait) {
+        lastArgs = args;
+        pending = true;
+        if (timer === undefined) {
+          const remaining = Math.max(0, opts.wait - (now - lastFiredAt));
+          timer = setTimeout(fireTrailing, remaining);
+        }
+        return;
+      }
+      void action.dispatch(args);
+      lastFiredAt = now;
+      lastArgs = undefined;
+      pending = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      timer = setTimeout(fireTrailing, opts.wait);
+      return;
+    }
+    lastArgs = args;
+    pending = true;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = undefined;
+      pending = false;
+      const a = lastArgs;
+      lastArgs = undefined;
+      if (a !== undefined) {
+        void action.dispatch(a);
+      }
+    }, opts.wait);
+  }) as DebouncedDispatch<TArgs>;
+
+  function fireTrailing(): void {
+    timer = undefined;
+    const a = lastArgs;
+    lastArgs = undefined;
+    if (a !== undefined) {
+      lastFiredAt = Date.now();
+      pending = true;
+      timer = setTimeout(fireTrailing, opts.wait);
+      void action.dispatch(a);
+    } else {
+      pending = false;
+    }
+  }
+
+  fn.flush = (args?: TArgs): Promise<unknown> | undefined => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    const a = args ?? lastArgs;
+    lastArgs = undefined;
+    pending = false;
+    if (a !== undefined) {
+      if (opts.leading === true) {
+        lastFiredAt = Date.now();
+      }
+      return action.dispatch(a);
+    }
+    return undefined;
+  };
+
+  fn.cancel = (): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    lastArgs = undefined;
+    pending = false;
+  };
+
+  fn.isPending = (): boolean => pending;
+
+  return fn;
+}