@cplieger/actions 2.0.3 → 2.0.5

package/README.md

@@ -76,6 +76,8 @@ Options (mirrors RTK `fetchBaseQuery`):
 - `credentials` — `RequestInit.credentials` mode (e.g. `"include"` for cookies)
 - `fetchFn` — custom fetch implementation (SSR, testing)
 
+> **Path contract:** `RequestSpec.path` is expected to be a **relative** path. With `baseUrl` set, the configured scheme+host always precede it, so an absolute (`https://…`) or protocol-relative (`//host`) path is neutralised (kept as a path segment) and cannot override the origin. With `baseUrl` **unset**, `path` is passed to `fetch()` verbatim — the caller owns the full URL and must never pass untrusted input (e.g. a server-supplied string) as the whole path.
+
 Per-request headers can also be set directly on `RequestSpec`:
 
 ```typescript

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/actions",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "exports": {
     ".": "./src/index.ts",
     "./testing": "./src/testing.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/actions",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -19,10 +19,10 @@
     "@eslint/js": "10.0.1",
     "@types/node": "24.13.2",
     "@vitest/coverage-v8": "4.1.9",
-    "eslint": "10.5.0",
+    "eslint": "10.6.0",
     "fast-check": "4.8.0",
     "happy-dom": "20.10.6",
-    "prettier": "3.8.4",
+    "prettier": "3.9.0",
     "typescript-eslint": "8.62.0",
     "vitest": "4.1.9"
   },

package/src/api.ts

@@ -32,7 +32,11 @@ const JSON_CT = "application/json";
 
 /** 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"). */
+  /** Base URL prepended to every RequestSpec.path (e.g. "https://api.example.com/v1").
+   *  `RequestSpec.path` is treated as a RELATIVE path: when this is set, an absolute or
+   *  protocol-relative path cannot override the origin (it is kept as a path segment).
+   *  When this is UNSET, `RequestSpec.path` is passed to fetch() verbatim, so the caller
+   *  owns the full URL and must never pass untrusted input as the whole path. */
   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). */
@@ -124,13 +128,18 @@ async function executeRequest<T>(
       headers.set(k, v);
     }
   }
-  // Global prepareHeaders hook
+  // Global prepareHeaders hook. Honor a returned Headers (RTK convention), falling
+  // back to the mutated instance when the hook returns undefined.
+  let effectiveHeaders = headers;
   if (cfg.prepareHeaders !== undefined) {
-    await cfg.prepareHeaders(headers, { spec });
+    const prepared = await cfg.prepareHeaders(headers, { spec });
+    if (prepared !== undefined) {
+      effectiveHeaders = prepared;
+    }
   }
   // Convert Headers to plain object for RequestInit
   const headerObj: Record<string, string> = {};
-  headers.forEach((v, k) => {
+  effectiveHeaders.forEach((v, k) => {
     headerObj[k.toLowerCase()] = v;
   });
   if (Object.keys(headerObj).length > 0) {
@@ -144,6 +153,11 @@ async function executeRequest<T>(
 
   init.signal = withTimeout(signal, API_TIMEOUT_MS);
 
+  // CONTRACT: spec.path is a RELATIVE path. With baseUrl set, the base scheme+host
+  // precede it, so an absolute ('https://...') or protocol-relative ('//host') path is
+  // neutralised (kept as a path segment) and cannot override the origin. With baseUrl
+  // UNSET, spec.path is passed to fetch() verbatim, so the caller owns the full URL and
+  // must never pass untrusted input (e.g. a server-supplied string) as the whole path.
   // Resolve URL: prepend baseUrl if configured, normalizing double slashes at the join
   let url: string;
   if (cfg.baseUrl !== undefined) {

package/src/async-feedback.ts

@@ -162,6 +162,10 @@ export async function withAsyncFeedback(
   const origNodes = useTarget ? [] : [...btn.childNodes].map((n) => n.cloneNode(true));
   const origDisabled = btn.disabled;
   const origAriaBusy = btn.getAttribute("aria-busy");
+  // Capture focus BEFORE disabling: `btn.disabled = true` (below) blurs the
+  // button, moving focus to <body>. We restore it once the button re-enables
+  // so a keyboard user who activated it does not lose their place.
+  const hadFocus = document.activeElement === btn;
 
   const restoreAriaBusy = (): void => {
     if (origAriaBusy === null) {
@@ -171,6 +175,20 @@ export async function withAsyncFeedback(
     }
   };
 
+  // Restore keyboard focus to the button after it re-enables, but only if it
+  // held focus before being disabled, is still connected and focusable, and
+  // focus has not since moved to a competing element (activeElement is <body>
+  // or null). Mirrors loading.ts's bindLoadingState/setIdle guard so the two
+  // helpers behave consistently and neither steals focus the user moved away.
+  const restoreFocus = (): void => {
+    if (hadFocus && btn.isConnected && !btn.disabled) {
+      const active = document.activeElement;
+      if (active === null || active === document.body) {
+        btn.focus();
+      }
+    }
+  };
+
   btn.dataset["asyncStatus"] = "pending";
   btn.disabled = true;
   btn.setAttribute("aria-busy", "true");
@@ -217,6 +235,7 @@ export async function withAsyncFeedback(
   const reset = opts.resetMs ?? RESET_MS;
   if (reset <= 0) {
     btn.disabled = origDisabled;
+    restoreFocus();
     return;
   }
 
@@ -234,6 +253,7 @@ export async function withAsyncFeedback(
       btn.replaceChildren(...origNodes.map((n) => n.cloneNode(true)));
     }
     btn.disabled = origDisabled;
+    restoreFocus();
     delete btn.dataset["asyncStatus"];
   }, reset);
   resetTimers.set(btn, timerId);

package/src/define-helpers.ts

@@ -19,7 +19,7 @@ export function safeInvoke(actionName: string, hookName: string, fn: () => void)
  *  the same description are distinct values but String(sym) is identical,
  *  so we assign each unique symbol a stable numeric ID. */
 let _symbolCounter = 0;
-export const _symbolMap = new Map<symbol, number>();
+const _symbolMap = new Map<symbol, number>();
 export function symbolId(sym: symbol): number {
   let id = _symbolMap.get(sym);
   if (id === undefined) {
@@ -55,9 +55,15 @@ export function safeStringify(args: unknown): string {
     return `@@sym${String(symbolId(args))}`;
   }
   try {
-    return JSON.stringify(args, (_key, value: unknown) =>
+    const out = JSON.stringify(args, (_key, value: unknown) =>
       value === undefined ? "__undef__" : value,
     );
+    // A top-level non-serializable value (a bare function) makes JSON.stringify
+    // return the value `undefined` rather than throw, so the catch never fires.
+    // Coerce to a stable string so distinct function args don't collide on a
+    // single `${name}::undefined` dedupe key.
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string -- intentional fallback for non-serializable values
+    return typeof out === "string" ? out : String(args);
   } catch {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string -- intentional fallback for cyclic objects
     return String(args);
@@ -84,9 +90,6 @@ export function resolveNotification<TArgs, TPayload>(
   return spec(args, payload);
 }
 
-/** @deprecated Use {@link resolveNotification} instead. */
-export const resolveToast = resolveNotification;
-
 /** Build a default error notification prefix from the action name.
  *  Converts "chat.delete" -> "Delete failed". */
 export function defaultErrorPrefix(name: string): string {

package/src/define.ts

@@ -10,7 +10,6 @@ import { _registerAction } from "./cleanup.js";
 import {
   safeInvoke,
   safeStringify,
-  _symbolMap,
   _resetSymbols,
   resolveNotification,
   defaultErrorPrefix,
@@ -50,8 +49,13 @@ export const IDEMPOTENCY_HEADER = "Idempotency-Key";
 
 function generateIdempotencyKey(): string {
   const ts = Date.now().toString(36);
-  const rnd = Math.random().toString(36).slice(2, 16).padEnd(14, "0");
-  return `${ts}-${rnd}`;
+  const buf = new Uint8Array(10);
+  crypto.getRandomValues(buf);
+  let rnd = "";
+  for (const b of buf) {
+    rnd += b.toString(36).padStart(2, "0");
+  }
+  return `${ts}-${rnd.slice(0, 14)}`;
 }
 
 const scopeChains = new Map<string, Promise<unknown>>();
@@ -67,6 +71,7 @@ interface DedupeSlot {
   promise: Promise<unknown> | undefined;
   error?: ActionErrorLike;
   cancelled?: boolean;
+  succeeded?: boolean;
 }
 const activeDedupes = new Map<string, DedupeSlot>();
 
@@ -112,31 +117,37 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
     args: TArgs,
     opts: DispatchOptions<TArgs, TResult> = NO_OPTS,
   ): DispatchHandle<TResult> {
+    const fireSettledHooks = (): void => {
+      fireDefSettled(args);
+      const onSettledCb = opts.onSettled;
+      if (onSettledCb) {
+        safeInvoke(def.name, "onSettled", () => {
+          onSettledCb(args);
+        });
+      }
+    };
     const dedupeKey = dedupeKeyFor(args);
     if (dedupeKey !== null) {
       const entry = activeDedupes.get(dedupeKey);
       if (entry !== undefined) {
         const shared = entry.promise;
         if (shared === undefined) {
-          const onSettledCb = opts.onSettled;
-          if (onSettledCb) {
-            safeInvoke(def.name, "onSettled", () => {
-              onSettledCb(args);
-            });
-          }
+          fireSettledHooks();
           return makeHandle(Promise.resolve(null) as Promise<TResult | null>, NOOP);
         }
         const joined = (shared as Promise<TResult | null>).then(
           (v) => {
-            if (v !== null) {
+            if (v !== null || entry.succeeded === true) {
+              fireDefSuccess(v as TResult, args);
               const onSuccessCb = opts.onSuccess;
               if (onSuccessCb) {
                 safeInvoke(def.name, "onSuccess", () => {
-                  onSuccessCb(v, args);
+                  onSuccessCb(v as TResult, args);
                 });
               }
             } else if (entry.error !== undefined) {
               const capturedErr = entry.error;
+              fireDefError(capturedErr, args);
               const onErrorCb = opts.onError;
               if (onErrorCb) {
                 safeInvoke(def.name, "onError", () => {
@@ -144,28 +155,23 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
                 });
               }
             } else if (entry.cancelled !== true) {
+              const dedupeErr: ActionErrorLike = {
+                message: "deduped dispatch did not succeed",
+                code: "dedupe",
+              };
+              fireDefError(dedupeErr, args);
               const onErrorCb = opts.onError;
               if (onErrorCb) {
                 safeInvoke(def.name, "onError", () => {
-                  onErrorCb({ message: "deduped dispatch did not succeed", code: "dedupe" }, args);
+                  onErrorCb(dedupeErr, args);
                 });
               }
             }
-            const onSettledCb = opts.onSettled;
-            if (onSettledCb) {
-              safeInvoke(def.name, "onSettled", () => {
-                onSettledCb(args);
-              });
-            }
+            fireSettledHooks();
             return v;
           },
           () => {
-            const onSettledCb = opts.onSettled;
-            if (onSettledCb) {
-              safeInvoke(def.name, "onSettled", () => {
-                onSettledCb(args);
-              });
-            }
+            fireSettledHooks();
             return null;
           },
         );
@@ -234,13 +240,7 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
             completedAt: now,
           });
         } finally {
-          fireDefSettled(args);
-          const onSettledCb = opts.onSettled;
-          if (onSettledCb) {
-            safeInvoke(def.name, "onSettled", () => {
-              onSettledCb(args);
-            });
-          }
+          fireSettledHooks();
           earlyCancelResolve(null);
         }
       });
@@ -426,6 +426,9 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
         result,
         attempts,
       });
+      if (dedupeEntry !== null) {
+        dedupeEntry.succeeded = true;
+      }
       evictDedupeSlot(dedupeKey, dedupeEntry);
       emitSuccessToast(args, result, opts);
       fireDefSuccess(result, args);

package/src/loading.ts

@@ -18,10 +18,7 @@ import { isPending, pendingCount } from "./registry.js";
 
 /** Element types that have a `.disabled` writable boolean. */
 type DisableableElement =
-  | HTMLButtonElement
-  | HTMLInputElement
-  | HTMLSelectElement
-  | HTMLTextAreaElement;
+  HTMLButtonElement | HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
 
 interface BindLoadingOptions {
   ariaBusy?: boolean;

package/src/notifier.ts

@@ -12,7 +12,13 @@ export interface NotifierRetry {
  *  and pass it to `configure()` to wire up toast/notification display.
  *
  *  All methods are optional — when not provided, the framework silently
- *  drops the notification (useful for headless/test environments). */
+ *  drops the notification (useful for headless/test environments).
+ *
+ *  SECURITY: the `message` passed to `error()` (and `success()`) may contain
+ *  server-controlled text — e.g. an HTTP error body's `error` field surfaced via
+ *  ActionError.message, or a transport `r.error`. Render it as TEXT (textContent /
+ *  a text node), never via innerHTML, to avoid reflected XSS from a malicious or
+ *  compromised server response. */
 export interface Notifier {
   success?(message: string): void;
   error?(message: string, retry?: NotifierRetry): void;

package/src/poll.ts

@@ -126,6 +126,7 @@ export function pollAction<TArgs, TResult>(
       timer = undefined;
     }
     listenerCtrl.abort();
+    unregisterCleanup();
   }
 
   const listenerCtrl = new AbortController();
@@ -140,7 +141,7 @@ export function pollAction<TArgs, TResult>(
     window.addEventListener("focus", onFocus, { signal: listenerCtrl.signal });
   }
 
-  registerCleanup(stop);
+  const unregisterCleanup = registerCleanup(stop);
 
   if (!paused) {
     void tick();

package/src/registry.ts

@@ -222,7 +222,12 @@ export function recentLog(): readonly ActionInstance[] {
 }
 
 /** Read the recent action log. Useful for devtools integration and
- *  debugging panels. Returns a snapshot of all live entries. */
+ *  debugging panels. Returns a snapshot of all live entries.
+ *
+ *  SECURITY/PRIVACY: each entry retains the full dispatch `args` in memory (up to
+ *  MAX_LOG_SIZE entries), `subscribeToActions` fans `args` out to every listener, and
+ *  buildRetryButton retains a structuredClone of `args` in the error-notification
+ *  retry closure. Do NOT put secrets, tokens, or PII in action args. */
 export const getActionLog = recentLog;
 
 /** O(1) check: true if at least one instance of the named action is pending.

package/src/types.ts

@@ -50,9 +50,7 @@ export interface ActionInstance<TArgs = unknown, TResult = unknown> {
  *  computed from action args + result/error at call time. Pass false
  *  to opt out of the default notification for that branch. */
 export type NotificationSpec<TArgs, TPayload> =
-  | string
-  | ((args: TArgs, payload: TPayload) => string)
-  | false;
+  string | ((args: TArgs, payload: TPayload) => string) | false;
 
 /** @deprecated Use {@link NotificationSpec} instead. */
 export type ToastSpec<TArgs, TPayload> = NotificationSpec<TArgs, TPayload>;
@@ -97,7 +95,9 @@ export interface ActionDefinition<TArgs, TResult, TOp = unknown> {
   /** Optional optimistic mutation. Runs synchronously before run(). */
   optimistic?: (args: TArgs) => TOp | undefined;
 
-  /** Undo the optimistic mutation. Called only if run() throws. */
+  /** Undo the optimistic mutation. Called on error OR cancellation (including a
+   *  cancellation that lands after run() resolves), never on success. The `err`
+   *  carries {code:'cancelled'} on the cancellation path. */
   rollback?: (args: TArgs, op: TOp | undefined, err: ActionErrorLike) => void;
 
   /** Notification on success. Default: no notification. */