@cplieger/actions 1.0.0

package/README.md

@@ -0,0 +1,176 @@
+# actions
+
+[![CI](https://github.com/cplieger/actions/actions/workflows/ci.yaml/badge.svg)](https://github.com/cplieger/actions/actions/workflows/ci.yaml)
+[![npm](https://img.shields.io/npm/v/@cplieger/actions)](https://www.npmjs.com/package/@cplieger/actions)
+[![JSR](https://jsr.io/badges/@cplieger/actions)](https://jsr.io/@cplieger/actions)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](./LICENSE)
+
+> Declarative UI-actions framework with lifecycle management, retry, debounce, and polling.
+
+A standalone TypeScript library for defining and dispatching UI actions with full lifecycle support: optimistic updates, automatic retry with backoff, scope serialization, dedupe collapsing, notification wiring, and a registry for observability. Zero runtime dependencies — notification display and streaming transport are injected by the consumer via small interfaces.
+
+## Install
+
+```sh
+npx jsr add @cplieger/actions
+# or
+npm i @cplieger/actions
+```
+
+Requires TypeScript ≥ 5.0 and a bundler that supports ESM.
+
+## Usage
+
+```typescript
+import { configure, defineAction, apiAction, retryNetwork } from "@cplieger/actions";
+
+// Wire up your notification adapter at boot
+configure({
+  success: (msg) => showToast("success", msg),
+  error: (msg, retry) => showToast("error", msg, retry?.onClick),
+});
+
+// Define an action backed by HTTP
+const deleteItem = apiAction<string>({
+  name: "items.delete",
+  request: (id) => ({ method: "DELETE", path: `/api/items/${id}` }),
+  error: "Couldn't delete item",
+  retryable: retryNetwork,
+  retry: { count: 2, delay: 300 },
+});
+
+// Dispatch it
+await deleteItem.dispatch(itemId);
+```
+
+## Injection Points
+
+The framework provides three adapter injection points:
+
+- **Notifier** (`configure()`): Provides `success(msg)` and `error(msg, retry?)` methods for displaying notifications. Without configuration, notifications are silently dropped.
+
+- **API** (`configureApi()`): Configures the HTTP layer used by all `apiAction` instances — base URL, auth/CSRF headers, credentials mode, or a custom fetch implementation. Without configuration, `apiAction` uses the global `fetch` with relative paths.
+
+- **Transport** (`configureTransport()`): Provides a `send(cmd, opts)` function for SSE/streaming actions. Only needed if using `transportAction`.
+
+### HTTP Customization (configureApi)
+
+```typescript
+import { configureApi } from "@cplieger/actions";
+
+configureApi({
+  baseUrl: "https://api.example.com/v1",
+  credentials: "include",
+  prepareHeaders: (headers, { spec }) => {
+    headers.set("Authorization", `Bearer ${getToken()}`);
+    headers.set("X-CSRF-Token", getCsrfToken());
+  },
+});
+```
+
+Options (mirrors RTK `fetchBaseQuery`):
+
+- `baseUrl` — prepended to every `RequestSpec.path`
+- `prepareHeaders(headers, { spec })` — inject headers per-request (may be async)
+- `credentials` — `RequestInit.credentials` mode (e.g. `"include"` for cookies)
+- `fetchFn` — custom fetch implementation (SSR, testing)
+
+Per-request headers can also be set directly on `RequestSpec`:
+
+```typescript
+const action = apiAction({
+  name: "items.create",
+  request: (item) => ({
+    method: "POST",
+    path: "/items",
+    body: item,
+    headers: { "X-Request-Id": crypto.randomUUID() },
+  }),
+});
+```
+
+## API
+
+- `configure(notifier)` — inject the notification adapter
+- `configureApi(opts)` — configure the HTTP layer (baseUrl, headers, credentials, fetchFn)
+- `configureTransport(fn)` — inject the streaming transport adapter
+- `defineAction(def)` — create an action from a declarative definition
+- `apiAction(def)` — create an HTTP-backed action (uses `fetch`)
+- `transportAction(def)` — create a transport/SSE-backed action
+- `debouncedDispatch(action, opts)` — debounce wrapper
+- `pollAction(action, args, opts)` — interval polling with pause/backoff
+- `bindLoadingState(name, el, opts?)` — bind element disabled state to action pending
+- `subscribeToActions(fn)` — subscribe to all lifecycle events
+- `subscribeByName(name, fn)` — subscribe to lifecycle events for a single action name
+- `getActionLog()` — read the recent action log (for devtools/debugging)
+- `pendingCount(names?)` — query pending action count
+- `isPending(name)` — O(1) check if a named action is in-flight
+- `registerCleanup(fn)` — register teardown hooks for page unload
+- `ActionError` — structured error class with status/code
+- `retryNetwork` — preset retry classifier for transient failures
+- `classifyFetchError(err)` — classify fetch errors (network vs timeout vs HTTP)
+- `hasErrorString(err)` — type guard for objects with a `.message` string
+- `withTimeout(signal, ms)` — compose an AbortSignal with a timeout
+- `API_TIMEOUT_MS` — default API request timeout (30 000 ms)
+- `RETRY_STANDARD` — standard retry config (2 retries, 300ms)
+
+### Definition-level callbacks (TanStack Query pattern)
+
+`ActionDefinition` supports `onSuccess`, `onError`, and `onSettled` callbacks that fire on every dispatch without the caller needing to pass them each time:
+
+```typescript
+const save = defineAction({
+  name: "doc.save",
+  run: async (id: string) => api.save(id),
+  onSuccess: (result, id) => invalidateCache(id),
+  onError: (err, id) => trackError("save", id, err),
+  onSettled: (id) => console.log("save settled for", id),
+});
+```
+
+### Per-dispatch abort handle (RTK pattern)
+
+`dispatch()` returns a `DispatchHandle` — a Promise augmented with an `abort()` method for per-dispatch cancellation:
+
+```typescript
+const handle = action.dispatch(args);
+// Cancel just this dispatch (others unaffected):
+handle.abort();
+// Still awaitable:
+const result = await handle;
+```
+
+### Timeout option
+
+`ActionDefinition` accepts a `timeout` (ms) that aborts `run()` via `AbortSignal.timeout()`:
+
+```typescript
+const slow = defineAction({
+  name: "slow.op",
+  timeout: 5000, // abort after 5s
+  run: async (args, signal) => fetch(url, { signal }),
+});
+```
+
+## Unsupported by Design (SKIP list)
+
+The following features are intentionally not implemented:
+
+| Feature                                | Reason                                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Query caching / stale-while-revalidate | Out of paradigm — this is an action runner, not a data cache. Use TanStack Query alongside.       |
+| Cache invalidation / revalidation      | Data-cache concern, out of scope.                                                                 |
+| Framework adapters (React/Vue/Svelte)  | Vanilla TS by design. Framework bindings belong in separate packages.                             |
+| Visual DevTools panel                  | Separate package concern. The registry API (`getActionLog`, `subscribeByName`) provides the data. |
+| SSR / hydration                        | Actions are imperative mutations — nothing to serialize across server→client.                     |
+| Debounce `maxWait`                     | Deliberate simplification. Use `flush()` for guaranteed-fire semantics.                           |
+| Throttle helper                        | Not action-specific. Consumers can throttle before calling `dispatch()`.                          |
+| `condition` / pre-execution guard      | Trivially implemented by callers with `if`. `dedupe` covers the primary use case.                 |
+| Typed discriminated-union result       | The callback model (onSuccess/onError/onSettled) is the chosen API shape.                         |
+| `onProgress` callback                  | Transport-specific. Consumers wire progress in their `run()` implementation.                      |
+| Batch dispatch                         | Store-level concern. This library doesn't own a store.                                            |
+| `dispose()` / action deregistration    | Actions are lightweight when idle. Not a leak concern for realistic app sizes.                    |
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE).

package/dist/src/api.d.ts

@@ -0,0 +1,56 @@
+import type { Action, ActionDefinition, RequestSpec } from "./types.js";
+/** Default request timeout in milliseconds. */
+export declare const API_TIMEOUT_MS = 30000;
+/**
+ * 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 declare function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal;
+/** 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;
+}
+/**
+ * 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 declare function configureApi(config: ApiConfig): void;
+/** Reset API config. @internal Test-only. */
+export declare function _resetApiConfigForTest(): void;
+/** 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 declare function apiAction<TArgs, TResult = unknown, TOp = unknown>(def: ApiActionDefinition<TArgs, TResult, TOp>): Action<TArgs, TResult>;

package/dist/src/api.js

@@ -0,0 +1,158 @@
+// 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";
+/** 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, ms) {
+    return signal !== undefined
+        ? AbortSignal.any([signal, AbortSignal.timeout(ms)])
+        : AbortSignal.timeout(ms);
+}
+const JSON_CT = "application/json";
+let _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 = config;
+}
+/** Reset API config. @internal Test-only. */
+export function _resetApiConfigForTest() {
+    _apiConfig = {};
+}
+/**
+ * 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(def) {
+    const { request, ...rest } = def;
+    return defineAction({
+        ...rest,
+        run: async (args, signal, ctx) => {
+            const spec = request(args);
+            return executeRequest(spec, signal, ctx);
+        },
+    });
+}
+async function executeRequest(spec, signal, ctx) {
+    const cfg = _apiConfig;
+    const init = { 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 = {};
+    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;
+    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;
+    try {
+        r = await fetchImpl(url, init);
+    }
+    catch (e) {
+        throw classifyFetchError(e, signal);
+    }
+    if (!r.ok) {
+        let serverError = "";
+        let serverCode;
+        try {
+            const body = await r.json();
+            if (hasErrorString(body)) {
+                serverError = body.error;
+            }
+            if (typeof body === "object" && body !== null && "code" in body) {
+                const code = body.code;
+                if (typeof code === "string") {
+                    serverCode = code;
+                }
+            }
+        }
+        catch {
+            // Body wasn't JSON — leave serverError empty.
+        }
+        const opts = { 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;
+    }
+    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;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw new ActionError(`response not JSON: ${e instanceof Error ? e.message : String(e)}`, {
+            status: r.status,
+            cause: e,
+        });
+    }
+}

package/dist/src/cleanup.d.ts

@@ -0,0 +1,11 @@
+import type { Action } from "./types.js";
+/** Internal: register an Action so cancelAllPending() can iterate it. */
+export declare function _registerAction<TArgs, TResult>(action: Action<TArgs, TResult>): void;
+/**
+ * Register a cleanup function to run on page unload (or test invoke).
+ */
+export declare function registerCleanup(fn: () => void): () => void;
+/** Test-only: invoke the same cleanup logic that beforeunload runs. */
+export declare function _cancelAllForTest(): void;
+/** Test-only: clear both registries + uninstall the listener. */
+export declare function _resetForTest(): void;

package/dist/src/cleanup.js

@@ -0,0 +1,63 @@
+// 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).
+// ---------------------------------------------------------------------------
+const trackedActions = new Set();
+const cleanupHooks = new Set();
+let beforeunloadInstalled = false;
+/** Internal: register an Action so cancelAllPending() can iterate it. */
+export function _registerAction(action) {
+    trackedActions.add(action);
+    installBeforeunloadOnce();
+}
+/**
+ * Register a cleanup function to run on page unload (or test invoke).
+ */
+export function registerCleanup(fn) {
+    cleanupHooks.add(fn);
+    installBeforeunloadOnce();
+    return () => cleanupHooks.delete(fn);
+}
+function cancelAllPending() {
+    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() {
+    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() {
+    cancelAllPending();
+}
+/** Test-only: clear both registries + uninstall the listener. */
+export function _resetForTest() {
+    trackedActions.clear();
+    cleanupHooks.clear();
+    if (beforeunloadInstalled && typeof window !== "undefined") {
+        window.removeEventListener("beforeunload", cancelAllPending);
+    }
+    beforeunloadInstalled = false;
+}

package/dist/src/debounce.d.ts

@@ -0,0 +1,28 @@
+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 declare function debouncedDispatch<TArgs, TResult>(action: Action<TArgs, TResult>, opts: DebounceOptions): DebouncedDispatch<TArgs>;
+export {};

package/dist/src/debounce.js

@@ -0,0 +1,91 @@
+// 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.
+// ---------------------------------------------------------------------------
+/**
+ * Wrap an action with a debounce timer so rapid calls coalesce into a
+ * single dispatch after a quiet window.
+ */
+export function debouncedDispatch(action, opts) {
+    let timer;
+    let lastArgs;
+    let pending = false;
+    let lastFiredAt = 0;
+    const fn = ((args) => {
+        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);
+    });
+    function fireTrailing() {
+        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) => {
+        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 = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        lastArgs = undefined;
+        pending = false;
+    };
+    fn.isPending = () => pending;
+    return fn;
+}

package/dist/src/define-helpers.d.ts

@@ -0,0 +1,20 @@
+import type { NotificationSpec } from "./types.js";
+/** Invoke a callback safely — errors are caught and logged without
+ *  disrupting the dispatch lifecycle. */
+export declare function safeInvoke(actionName: string, hookName: string, fn: () => void): void;
+export declare const _symbolMap: Map<symbol, number>;
+export declare function symbolId(sym: symbol): number;
+/** Reset symbol state — test-only. */
+export declare function _resetSymbols(): void;
+/** Defensive JSON.stringify — falls back to String(args) on cycles
+ *  or non-serializable values (DOM elements, functions). Used by
+ *  the default dedupe key computation. */
+export declare function safeStringify(args: unknown): string;
+/** Resolve a NotificationSpec to its message string. Returns null when
+ *  the spec is `false` (suppressed) or undefined and no fallback. */
+export declare function resolveNotification<TArgs, TPayload>(spec: NotificationSpec<TArgs, TPayload> | undefined, args: TArgs, payload: TPayload, fallback?: string): string | null;
+/** @deprecated Use {@link resolveNotification} instead. */
+export declare const resolveToast: typeof resolveNotification;
+/** Build a default error notification prefix from the action name.
+ *  Converts "chat.delete" -> "Delete failed". */
+export declare function defaultErrorPrefix(name: string): string;