@cplieger/ui 0.0.0 → 1.0.0-dev.1

package/src/actions/api.ts

@@ -0,0 +1,268 @@
+// actions holds its own fetch instance (the fetch module is
+// instances-only), fully isolated from any instance a consuming app builds,
+// and maps fetch's ApiResult envelope onto ActionError.
+
+import { createFetch } from "../fetch/instance.js";
+import type { FetchInstance } from "../fetch/instance.js";
+import { API_TIMEOUT_MS } from "../fetch/timeout.js";
+import type { ApiErr, FetchConfig, RequestOptions } from "../fetch/types.js";
+
+import { defineAction, IDEMPOTENCY_HEADER } from "./define.js";
+import { ActionError } from "./error.js";
+import type {
+  Action,
+  ActionContext,
+  ActionDefinition,
+  ActionErrorLike,
+  RequestSpec,
+} from "./types.js";
+
+const JSON_CT = "application/json";
+
+/** Configuration for the global API fetch layer (mirrors RTK's
+ *  fetchBaseQuery). Set via `configureApi()`. */
+export interface ApiConfig {
+  /** 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). */
+  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;
+}
+
+// A fetch instance's config is frozen at construction, so configureApi's
+// replace-not-merge semantics rebuild the instance rather than mutate it.
+// prepareHeaders stays here rather than on the instance: it is spec-aware
+// (`(headers, { spec })`), a shape fetch's `(headers)`-only hook can't express.
+let apiFetch: FetchInstance = createFetch();
+let apiPrepareHeaders: ApiConfig["prepareHeaders"];
+
+/** Configure the global HTTP layer used by all `apiAction` instances. Call
+ *  once at app boot; a later call replaces the whole previous config. */
+export function configureApi(config: ApiConfig): void {
+  const fetchConfig: FetchConfig = {};
+  if (config.baseUrl !== undefined) {
+    fetchConfig.baseUrl = config.baseUrl;
+  }
+  if (config.credentials !== undefined) {
+    fetchConfig.credentials = config.credentials;
+  }
+  if (config.fetchFn !== undefined) {
+    fetchConfig.fetchFn = config.fetchFn;
+  }
+  // Fetch instances are immutable; replace-not-merge needs a fresh one.
+  apiFetch = createFetch(fetchConfig);
+  apiPrepareHeaders = config.prepareHeaders;
+}
+
+/** Reset API config. @internal Test-only. */
+export function _resetApiConfigForTest(): void {
+  apiFetch = createFetch();
+  apiPrepareHeaders = undefined;
+}
+
+/** Context passed to the {@link ApiActionDefinition.decode} hook. */
+export interface ApiDecodeContext {
+  /** HTTP status of the 2xx response being decoded. */
+  readonly status: number;
+  /** The request descriptor this response answers. */
+  readonly spec: RequestSpec;
+}
+
+/** A failed request as seen by {@link ApiActionDefinition.decodeError}: the
+ *  real HTTP response's status, the message the fetch layer lifted, the
+ *  server-supplied code (when present), the parsed JSON body (when one
+ *  parsed), and the response headers. Transport-level failures (network /
+ *  timeout / cancellation / invalid — status 0) never reach the hook. */
+export interface ApiErrorInfo {
+  readonly status: number;
+  readonly message: string;
+  readonly code?: string;
+  /** Parsed JSON body of the failed response. Server-controlled input —
+   *  validate the shape before reading fields. */
+  readonly body?: unknown;
+  readonly headers?: Headers;
+}
+
+/** Return shape of {@link ApiActionDefinition.decodeError}: resolve the
+ *  dispatch as a success carrying `value`, or replace the default error. */
+export type ApiErrorDecision<TResult> =
+  | { readonly kind: "success"; readonly value: TResult }
+  | { readonly kind: "error"; readonly error: ActionErrorLike };
+
+/** 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;
+
+  /** Decode / validate a 2xx response body. Receives the raw decoded body
+   *  (`undefined` for a 204 / empty-body response) and returns the action
+   *  result; throw (an {@link ActionError}) to route the dispatch to the
+   *  error branch instead (rollback + error notification + registry error) —
+   *  the seam for 200-with-error envelopes. Absent: the body is returned as
+   *  `TResult` unchanged. */
+  decode?: (data: unknown, ctx: ApiDecodeContext) => TResult;
+
+  /** Reinterpret a failed request that produced a real HTTP response. Return
+   *  `{ kind: "success", value }` to resolve the dispatch as success (e.g. a
+   *  409 whose body is a meaningful payload), `{ kind: "error", error }` to
+   *  replace the default error, or `undefined` to keep the default
+   *  {@link ActionError} mapping. Transport failures (status 0: network /
+   *  timeout / cancelled / invalid) never reach this hook, so retry
+   *  classification and cancellation semantics are preserved. */
+  decodeError?: (
+    info: ApiErrorInfo,
+    ctx: { readonly spec: RequestSpec },
+  ) => ApiErrorDecision<TResult> | undefined;
+}
+
+/**
+ * Build an Action from an HTTP request descriptor.
+ * Wraps `defineAction` with a generated `run()` that dispatches the
+ * {@link RequestSpec} through the {@link ApiConfig} layer configured with
+ * {@link configureApi} (backed by an isolated `@cplieger/ui/fetch` instance).
+ */
+export function apiAction<TArgs, TResult = unknown, TOp = unknown>(
+  def: ApiActionDefinition<TArgs, TResult, TOp>,
+): Action<TArgs, TResult> {
+  const { request, decode, decodeError, ...rest } = def;
+  return defineAction<TArgs, TResult, TOp>({
+    ...rest,
+    run: async (args, signal, ctx) => {
+      const spec = request(args);
+      return executeRequest<TResult>(spec, signal, ctx, decode, decodeError);
+    },
+  });
+}
+
+async function executeRequest<T>(
+  spec: RequestSpec,
+  signal: AbortSignal,
+  ctx?: ActionContext,
+  decode?: (data: unknown, dctx: ApiDecodeContext) => T,
+  decodeError?: (
+    info: ApiErrorInfo,
+    dctx: { readonly spec: RequestSpec },
+  ) => ApiErrorDecision<T> | undefined,
+): Promise<T> {
+  // Content-Type is set before prepareHeaders so the hook can see/override it.
+  const headers = new Headers();
+  if (spec.method !== "GET" && spec.body !== undefined) {
+    headers.set("Content-Type", JSON_CT);
+  }
+  if (ctx?.idempotencyKey !== undefined) {
+    headers.set(IDEMPOTENCY_HEADER, ctx.idempotencyKey);
+  }
+  if (spec.headers !== undefined) {
+    for (const [k, v] of Object.entries(spec.headers)) {
+      headers.set(k, v);
+    }
+  }
+  // A returned Headers wins (RTK convention); a throw here propagates before
+  // fetch is ever called.
+  let effectiveHeaders = headers;
+  if (apiPrepareHeaders !== undefined) {
+    const prepared = await apiPrepareHeaders(headers, { spec });
+    if (prepared !== undefined) {
+      effectiveHeaders = prepared;
+    }
+  }
+
+  const opts: RequestOptions<T> = {
+    signal,
+    timeoutMs: API_TIMEOUT_MS,
+    headers: effectiveHeaders,
+  };
+  if (spec.method !== "GET") {
+    if (spec.rawBody !== undefined) {
+      // Sent as-is: no JSON encoding, no automatic Content-Type.
+      opts.rawBody = spec.rawBody;
+    } else if (spec.body !== undefined) {
+      opts.body = spec.body;
+    }
+  }
+
+  const result = await apiFetch.requestRaw<T>(spec.method, spec.path, opts);
+  if (result.ok) {
+    if (decode !== undefined) {
+      // A decode throw routes the dispatch to the error branch — the seam
+      // for 200-with-error envelopes.
+      return decode(result.data, { status: result.status, spec });
+    }
+    // fetch collapses a 204 and an empty-body 2xx to data === undefined.
+    if (result.data === undefined && result.status !== 204 && spec.method !== "DELETE") {
+      console.warn(
+        `[actions] ${spec.method} ${spec.path} returned empty body — callers expecting data will receive undefined`,
+      );
+    }
+    return result.data;
+  }
+  // Transport failures (status 0) never reach decodeError, so retryNetwork
+  // classification and cancellation semantics can't be rewritten by the hook.
+  if (decodeError !== undefined && result.status > 0) {
+    const decision = decodeError(
+      {
+        status: result.status,
+        message: result.error,
+        ...(result.code !== undefined && { code: result.code }),
+        ...(result.body !== undefined && { body: result.body }),
+        ...(result.headers !== undefined && { headers: result.headers }),
+      },
+      { spec },
+    );
+    if (decision !== undefined) {
+      if (decision.kind === "success") {
+        return decision.value;
+      }
+      const e = decision.error;
+      throw e instanceof ActionError
+        ? e
+        : new ActionError(e.message, {
+            ...(e.status !== undefined && { status: e.status }),
+            ...(e.code !== undefined && { code: e.code }),
+            ...(e.cause !== undefined && { cause: e.cause }),
+          });
+    }
+  }
+  throw actionErrorFromApiErr(result);
+}
+
+/**
+ * Map a fetch {@link ApiErr} envelope onto an {@link ActionError}. A `status`
+ * of 0 marks a transport failure (`code: network | timeout | cancelled |
+ * invalid`); any other status is a real HTTP response.
+ */
+function actionErrorFromApiErr(err: ApiErr): ActionError {
+  const { status, error, code } = err;
+  if (status === 0) {
+    if (code === "cancelled") {
+      return new ActionError("Request cancelled", { code: "cancelled" });
+    }
+    if (code === "timeout") {
+      return new ActionError("Request timed out", { status: 0, code: "timeout" });
+    }
+    if (code === "invalid") {
+      // No HTTP status: retryNetwork treats a status-less error as non-retryable.
+      return new ActionError(error, { code: "invalid" });
+    }
+    return new ActionError(error, { status: 0, code: "network" });
+  }
+  const opts: { status: number; code?: string } = { status };
+  if (code !== undefined) {
+    opts.code = code;
+  }
+  return new ActionError(error, opts);
+}

package/src/actions/async-feedback.ts

@@ -0,0 +1,217 @@
+import { el } from "../dom/el.js";
+
+const RESET_MS = 1200;
+
+const DEFAULT_ANNOUNCE = { success: "Action completed", error: "Action failed" } as const;
+
+const CHECK_HTML =
+  '<svg class="btn-async-glyph" width="14" height="14" viewBox="0 0 24 24" fill="none" ' +
+  'stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" ' +
+  'aria-hidden="true"><polyline points="20 6 9 17 4 12"/></svg>';
+
+const X_HTML =
+  '<svg class="btn-async-glyph" width="14" height="14" viewBox="0 0 24 24" fill="none" ' +
+  'stroke="currentColor" stroke-width="3" stroke-linecap="round" ' +
+  'aria-hidden="true"><path d="M18 6L6 18M6 6l12 12"/></svg>';
+
+/** Parse a static SVG string via <template> and return a fresh clone. The
+ *  markup is a library-controlled constant, so a single root element is
+ *  guaranteed. */
+function svgNode(svg: string): Node {
+  const template = document.createElement("template");
+  template.innerHTML = svg;
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- default glyph markup always has a single root element
+  return template.content.firstElementChild!.cloneNode(true);
+}
+
+const defaultRenderPending = (): Node =>
+  el("span", { className: "spinner-sm btn-async-spinner", "aria-hidden": "true" });
+const defaultRenderSuccess = (): Node => svgNode(CHECK_HTML);
+const defaultRenderError = (): Node => svgNode(X_HTML);
+
+const resetTimers = new WeakMap<HTMLButtonElement, ReturnType<typeof setTimeout>>();
+
+// Keyed on this, not `data-async-status`, so a persisted outcome glyph
+// (resetMs<=0) can't permanently block re-dispatch.
+const inFlight = new WeakSet<HTMLButtonElement>();
+
+let liveRegion: HTMLElement | null = null;
+
+function announce(message: string): void {
+  if (liveRegion === null) {
+    liveRegion = el("span", {
+      className: "sr-only",
+      "aria-live": "polite",
+      "aria-atomic": "true",
+    });
+    document.body.appendChild(liveRegion);
+  }
+  const region = liveRegion;
+  // Clear then set: re-announces an identical message.
+  region.textContent = "";
+  setTimeout(() => {
+    region.textContent = message;
+  }, 50);
+}
+
+/** Options for {@link withAsyncFeedback}. All fields are optional; the glyph
+ *  renderers default to built-in inline SVGs. */
+export interface AsyncFeedbackOptions {
+  /** Post-completion glyph hold in ms before content reverts. Default 1200;
+   *  `<= 0` persists the glyph indefinitely (button still re-enables, but
+   *  `data-async-status` keeps its terminal value). */
+  resetMs?: number;
+  /** When true, prepend the spinner before the existing content (e.g.
+   *  "⟳ Cloning…") instead of replacing the content with just the spinner.
+   *  Default false (icon-only replace). Ignored when {@link target} is set. */
+  keepLabel?: boolean;
+  /** Drive a single child slot via element replacement
+   *  (`current.replaceWith(next)`) instead of the button's whole content;
+   *  other children of `btn` are untouched and the original node is restored
+   *  on a non-persist reset. Expected to be a descendant of `btn` (not
+   *  validated). `keepLabel` is ignored when set. */
+  target?: HTMLElement;
+  /** Pending-state node factory. Returns a fresh node per call. */
+  renderPending?: () => Node;
+  /** Success-glyph node factory. Returns a fresh node per call. */
+  renderSuccess?: () => Node;
+  /** Error-glyph node factory. Returns a fresh node per call. */
+  renderError?: () => Node;
+  /** Live-region announcement text, or `false` to disable announcing. */
+  announce?: { readonly success: string; readonly error: string } | false;
+}
+
+/** Run an async function with consistent button feedback. The button is
+ *  disabled during the call. Re-entrant calls (clicking again while a cycle
+ *  is active) are ignored. */
+export async function withAsyncFeedback(
+  btn: HTMLButtonElement,
+  fn: () => Promise<unknown>,
+  opts: AsyncFeedbackOptions = {},
+): Promise<void> {
+  // `data-async-status` would deadlock the persist path, whose terminal
+  // status is never cleared.
+  if (inFlight.has(btn)) {
+    return;
+  }
+  inFlight.add(btn);
+
+  // Avoids a stale restore from a prior cycle.
+  const prevTimer = resetTimers.get(btn);
+  if (prevTimer !== undefined) {
+    clearTimeout(prevTimer);
+    resetTimers.delete(btn);
+  }
+
+  const renderPending = opts.renderPending ?? defaultRenderPending;
+  const renderSuccess = opts.renderSuccess ?? defaultRenderSuccess;
+  const renderError = opts.renderError ?? defaultRenderError;
+  const announceCfg = opts.announce ?? DEFAULT_ANNOUNCE;
+
+  // `originalTarget` keeps the exact node so a non-persist reset restores it;
+  // `currentSlot` tracks whichever node currently occupies the slot.
+  const target = opts.target;
+  const useTarget = target !== undefined;
+  const originalTarget: ChildNode | null = useTarget ? target : null;
+  let currentSlot: ChildNode | null = useTarget ? target : null;
+
+  // Render factories return Element/Text, both ChildNode at runtime.
+  const swapSlot = (next: Node): void => {
+    if (currentSlot === null) {
+      return;
+    }
+    currentSlot.replaceWith(next);
+    currentSlot = next as ChildNode;
+  };
+
+  const origNodes = useTarget ? [] : [...btn.childNodes].map((n) => n.cloneNode(true));
+  const origDisabled = btn.disabled;
+  const origAriaBusy = btn.getAttribute("aria-busy");
+  // Captured before disabling: `btn.disabled = true` below blurs the button.
+  const hadFocus = document.activeElement === btn;
+
+  const restoreAriaBusy = (): void => {
+    if (origAriaBusy === null) {
+      btn.removeAttribute("aria-busy");
+    } else {
+      btn.setAttribute("aria-busy", origAriaBusy);
+    }
+  };
+
+  // Only restores if focus has not since moved to a competing element.
+  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");
+  if (useTarget) {
+    swapSlot(renderPending());
+  } else if (opts.keepLabel === true) {
+    btn.prepend(renderPending(), document.createTextNode(" "));
+  } else {
+    btn.replaceChildren(renderPending());
+  }
+
+  let ok = true;
+  try {
+    await fn();
+  } catch {
+    ok = false;
+  }
+
+  // The async op may have removed btn from the DOM (e.g. a re-rendered list);
+  // the new DOM already reflects the result.
+  if (!btn.isConnected) {
+    inFlight.delete(btn);
+    restoreAriaBusy();
+    delete btn.dataset["asyncStatus"];
+    return;
+  }
+
+  btn.dataset["asyncStatus"] = ok ? "success" : "error";
+  if (useTarget) {
+    swapSlot(ok ? renderSuccess() : renderError());
+  } else {
+    btn.replaceChildren(ok ? renderSuccess() : renderError());
+  }
+  restoreAriaBusy();
+  inFlight.delete(btn);
+  if (announceCfg !== false) {
+    announce(ok ? announceCfg.success : announceCfg.error);
+  }
+
+  // `resetMs <= 0` persists: no revert timer, but re-enable now since no
+  // later callback will.
+  const reset = opts.resetMs ?? RESET_MS;
+  if (reset <= 0) {
+    btn.disabled = origDisabled;
+    restoreFocus();
+    return;
+  }
+
+  const timerId = setTimeout(() => {
+    resetTimers.delete(btn);
+    if (!btn.isConnected) {
+      return;
+    }
+    if (useTarget) {
+      if (currentSlot !== null && originalTarget !== null) {
+        currentSlot.replaceWith(originalTarget);
+        currentSlot = originalTarget;
+      }
+    } else {
+      btn.replaceChildren(...origNodes.map((n) => n.cloneNode(true)));
+    }
+    btn.disabled = origDisabled;
+    restoreFocus();
+    delete btn.dataset["asyncStatus"];
+  }, reset);
+  resetTimers.set(btn, timerId);
+}

package/src/actions/cleanup.ts

@@ -0,0 +1,66 @@
+import type { Action } from "./types.js";
+
+// Cleanup hooks must be idempotent: cancellation can fire multiple times
+// (e.g. a cancelled navigation followed by a confirmed one).
+
+/** 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: 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/actions/debounce.ts

@@ -0,0 +1,150 @@
+import { createRoot } from "../signal/signal.js";
+
+import type { Action } from "./types.js";
+
+// A no-argument action's args ARE `undefined`, so it can't double as the
+// empty-state marker; this sentinel is module-private and unforgeable as TArgs.
+const NO_ARGS = Symbol("debounce.noArgs");
+
+/** The callable {@link debouncedDispatch} returns: invoking it schedules a
+ *  dispatch rather than performing one (except under `leading: true`, where the
+ *  call that opens a window dispatches immediately), and the extra members
+ *  drive whatever is currently scheduled. Only `flush` hands back the action's
+ *  promise — every other path drops it, so results and errors are observed
+ *  through the action's own notifications and callbacks. */
+export interface DebouncedDispatch<TArgs> {
+  /** Replaces any pending dispatch's args. */
+  (args: TArgs): void;
+
+  /** Fires immediately with the most-recent args, or the args given here.
+   *  No-op if nothing is pending and no args supplied. */
+  flush(args?: TArgs): Promise<unknown> | undefined;
+
+  cancel(): void;
+
+  isPending(): boolean;
+}
+
+interface DebounceOptions {
+  readonly wait: number;
+  /** Default false (trailing edge). */
+  readonly leading?: boolean;
+}
+
+/** Wrap an action so a burst of calls collapses into one dispatch per `wait`
+ *  window. Trailing edge by default (each call restarts the timer, last args
+ *  win); `leading: true` fires the first call at once and holds the rest for
+ *  one trailing fire. There is no `maxWait`: call `flush()` for a guaranteed
+ *  fire. `cancel()` drops scheduled args only, never a dispatch already
+ *  started. Disposing the owner it was created under cancels it for good. */
+export function debouncedDispatch<TArgs, TResult>(
+  action: Action<TArgs, TResult>,
+  opts: DebounceOptions,
+): DebouncedDispatch<TArgs> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let lastArgs: TArgs | typeof NO_ARGS = NO_ARGS;
+  let pending = false;
+  let lastFiredAt = 0;
+  let ended = false;
+
+  const fn = ((args: TArgs): void => {
+    if (ended) {
+      return;
+    }
+    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);
+      // The action's synchronous prefix may have disposed the owner.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- set by owner disposal during dispatch
+      if (ended) {
+        return;
+      }
+      lastFiredAt = now;
+      lastArgs = NO_ARGS;
+      // The timer below is a cooldown re-arm, not a pending dispatch.
+      pending = false;
+      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 = NO_ARGS;
+      if (a !== NO_ARGS) {
+        void action.dispatch(a);
+      }
+    }, opts.wait);
+  }) as DebouncedDispatch<TArgs>;
+
+  function fireTrailing(): void {
+    timer = undefined;
+    const a = lastArgs;
+    lastArgs = NO_ARGS;
+    if (a !== NO_ARGS) {
+      lastFiredAt = Date.now();
+      pending = false;
+      timer = setTimeout(fireTrailing, opts.wait);
+      void action.dispatch(a);
+    } else {
+      pending = false;
+    }
+  }
+
+  fn.flush = (args?: TArgs): Promise<unknown> | undefined => {
+    if (ended) {
+      return undefined;
+    }
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    const a = args ?? lastArgs;
+    lastArgs = NO_ARGS;
+    pending = false;
+    if (a !== NO_ARGS) {
+      if (opts.leading === true) {
+        lastFiredAt = Date.now();
+      }
+      return action.dispatch(a);
+    }
+    return undefined;
+  };
+
+  fn.cancel = (): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    lastArgs = NO_ARGS;
+    pending = false;
+  };
+
+  fn.isPending = (): boolean => pending;
+
+  createRoot((_dispose, owner) => {
+    owner.onDispose(() => {
+      ended = true;
+      fn.cancel();
+    });
+  });
+
+  return fn;
+}