@cplieger/actions 1.0.0 → 1.0.1

package/dist/src/api.d.ts

@@ -1,56 +0,0 @@
-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

@@ -1,158 +0,0 @@
-// 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

@@ -1,11 +0,0 @@
-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

@@ -1,63 +0,0 @@
-// 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

@@ -1,28 +0,0 @@
-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

@@ -1,91 +0,0 @@
-// 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

@@ -1,20 +0,0 @@
-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;

package/dist/src/define-helpers.js

@@ -1,83 +0,0 @@
-// ---------------------------------------------------------------------------
-// Pure utility helpers extracted from define.ts — independently testable
-// without instantiating the full action framework.
-// ---------------------------------------------------------------------------
-/** Invoke a callback safely — errors are caught and logged without
- *  disrupting the dispatch lifecycle. */
-export function safeInvoke(actionName, hookName, fn) {
-    try {
-        fn();
-    }
-    catch (e) {
-        console.error(`[actions] ${hookName} callback for ${actionName} threw`, e);
-    }
-}
-/** Monotonic counter for symbol identity in dedupe keys. Symbols with
- *  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();
-export function symbolId(sym) {
-    let id = _symbolMap.get(sym);
-    if (id === undefined) {
-        id = ++_symbolCounter;
-        _symbolMap.set(sym, id);
-    }
-    return id;
-}
-/** Reset symbol state — test-only. */
-export function _resetSymbols() {
-    _symbolCounter = 0;
-    _symbolMap.clear();
-}
-/** 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 function safeStringify(args) {
-    if (args === undefined) {
-        return "undefined";
-    }
-    if (args === null || typeof args === "number" || typeof args === "boolean") {
-        return String(args);
-    }
-    if (typeof args === "string") {
-        return JSON.stringify(args);
-    }
-    if (typeof args === "bigint") {
-        return `${String(args)}n`;
-    }
-    if (typeof args === "symbol") {
-        return `@@sym${String(symbolId(args))}`;
-    }
-    try {
-        return JSON.stringify(args, (_key, value) => value === undefined ? "__undef__" : value);
-    }
-    catch {
-        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- intentional fallback for cyclic objects
-        return String(args);
-    }
-}
-/** Resolve a NotificationSpec to its message string. Returns null when
- *  the spec is `false` (suppressed) or undefined and no fallback. */
-export function resolveNotification(spec, args, payload, fallback) {
-    if (spec === false) {
-        return null;
-    }
-    if (spec === undefined) {
-        return fallback ?? null;
-    }
-    if (typeof spec === "string") {
-        return spec;
-    }
-    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) {
-    const parts = name.split(".");
-    const tail = parts[parts.length - 1] ?? name;
-    const readable = tail.replace(/[_-]/g, " ");
-    return readable.charAt(0).toUpperCase() + readable.slice(1) + " failed";
-}

package/dist/src/define.d.ts

@@ -1,14 +0,0 @@
-import type { Action, ActionDefinition } from "./types.js";
-/** Header name used by apiAction when an idempotency key is generated. */
-export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
-/**
- * Create an action from a declarative definition.
- */
-export declare function defineAction<TArgs, TResult, TOp = unknown>(def: ActionDefinition<TArgs, TResult, TOp>): Action<TArgs, TResult>;
-/** Test-only: reset the instance counter + scope chains + dedupe map. */
-export declare function _resetForTest(): void;
-/** Test-only: expose internal map sizes for leak verification. */
-export declare function _internalsForTest(): {
-    scopeChains: number;
-    activeDedupes: number;
-};