@plutoframework/frontend 0.1.3 → 0.2.0

package/README.md

@@ -213,3 +213,71 @@ code below. JavaScript and TypeScript lint/format checks enforce this convention
 including the start of a function or branch. Inline trailing comments are kept
 in place, and next-line compiler/linter directives retain their target. The
 cross-language convention is also recorded in AGENTS.md for future changes.
+
+## Responsive actions
+
+Use `@plutoframework/frontend/actions` for a dependency-free action controller,
+`useActions` from `/react` for lifecycle-owned React feedback, or
+`useActionMutation` from `/query` to receive your existing TanStack Query client.
+The query entrypoint requires the optional React and TanStack Query v5 peers;
+state/actions consumers install neither. These helpers do not add a transport,
+automatic retries or backend authorization.
+
+```tsx
+import { useActionMutation } from "@plutoframework/frontend/query";
+
+const action = useActionMutation({
+  scope: JSON.stringify([actor, session, tenant]),
+  execute: (id: string, { signal }) => removeRecord(id, signal),
+  confirm: (_result, id, client) => applyConfirmedRemoval(client, id),
+  reconcile: (_id, client) =>
+    client.invalidateQueries({ queryKey: recordsKey }),
+  classifyError: (error) =>
+    isDefiniteRejection(error) ? "rejected" : "uncertain",
+});
+
+const rows = action.project(query.data ?? [], {
+  mode: "optimistic",
+  project: (current, id) => current.filter((row) => row.id !== id),
+});
+
+// Default: render canonical rows and show entry.status === "pending" per row.
+// Opt in to the projection only when immediate removal is appropriate.
+void action.run(record.id, record.id);
+```
+
+The snippet's transport, cache updater, query key and rejection classifier belong
+to the feature; include actor/session/tenant in query keys. `scope` must change
+when captured resource authority changes. Each resource key is locked while
+pending or uncertain; separate keys can run concurrently. Controls must use
+`ready` and entry status, acknowledge immediately with accessible pending text,
+preserve input on failure and never announce success before confirmation.
+
+`run` resolves to whether the action was accepted, **not whether it succeeded**.
+Read the entry's outcome. `confirm` applies authoritative response data
+synchronously before success; reconciliation runs in the background. A refresh
+failure is `refreshError`, never a failed business write. Handle it visibly with
+a refresh option; no detached promise rejection is left unhandled.
+
+Optimistic projections run over current data without changing the cache. Rejection
+removes only that action's projection, preserving concurrent changes. Keep
+projectors pure; filtered, sorted or paginated collections may need feature-specific
+reconciliation. Success removes the projection, so update canonical data in
+`confirm` before it disappears. Cross-key operations on the same logical entity
+still need a host conflict policy.
+
+Unknown errors default to **uncertain**: timeouts, disconnects and server errors
+may happen after commit. Their projection remains and retries stay locked until
+an authoritative read or same-key replay establishes the outcome; call
+`resolve(key, "succeeded" | "rejected")` only then. A declared rejection permits
+retry. `forget` releases only terminal entries; retention is bounded to 1,000
+keys by default. Action keys deduplicate this controller only: keep stable backend
+idempotency keys separately for the same business intent.
+
+Constructors perform no effects. React owns a fresh store for each committed
+scope and disposes it on scope change/unmount, including StrictMode replay.
+`ready` is false during initialization/SSR. Disposal aborts cooperative requests
+and fences confirmations; it cannot undo a server write or already-started cache
+refresh. Use scoped queries and cancel/remove old reads in the host when changing
+identity. Headless hosts own disposal themselves. No persistence, cross-component
+locking, offline queue or exactly-once guarantee is implied.

package/dist/actions/index.d.ts

@@ -0,0 +1,15 @@
+import type { ActionEntry, ActionOptions, Feedback } from "./types.js";
+export type { ActionEntry, ActionOptions, FailureKind, Feedback, } from "./types.js";
+/** One store belongs to one actor/tenant scope; projections never mutate cache. */
+export declare function createActions<Input, Output>(options: ActionOptions<Input, Output>): {
+    getSnapshot: () => readonly ActionEntry<Input, Output>[];
+    getInitialSnapshot: () => readonly ActionEntry<Input, Output>[];
+    subscribe: (listener: () => void) => () => void;
+    run(key: string, input: Input): Promise<boolean>;
+    forget: (key: string) => Promise<boolean>;
+    /** Host must establish the outcome through authoritative reconciliation. */
+    resolve(key: string, status: "succeeded" | "rejected"): Promise<boolean>;
+    project<View>(current: View, feedback: Feedback<Input, View>): View;
+    dispose(): void;
+};
+export type Actions<Input, Output> = ReturnType<typeof createActions<Input, Output>>;

package/dist/actions/index.js

@@ -0,0 +1,177 @@
+import { createMachine } from "../state/index.js";
+/** One store belongs to one actor/tenant scope; projections never mutate cache. */
+export function createActions(options) {
+    const capacity = options.capacity ?? 1000;
+    if (!Number.isSafeInteger(capacity) || capacity < 1) {
+        throw new Error("Action capacity must be a positive integer");
+    }
+    let attempt = 0;
+    let disposed = false;
+    const initial = [];
+    const store = createMachine({
+        initial,
+        transition(current, event) {
+            const key = event.type === "forget" ? event.key : event.entry.key;
+            const previous = current.find((entry) => entry.key === key);
+            const locked = previous?.status === "pending" || previous?.status === "uncertain";
+            if (event.type === "start") {
+                if (locked || (!previous && current.length >= capacity)) {
+                    return {
+                        accepted: false,
+                        state: current,
+                    };
+                }
+                return {
+                    accepted: true,
+                    state: [...current.filter((entry) => entry.key !== key), event.entry],
+                    effect: event.entry,
+                };
+            }
+            if (event.type === "forget") {
+                if (!previous || locked) {
+                    return {
+                        accepted: false,
+                        state: current,
+                    };
+                }
+                return {
+                    accepted: true,
+                    state: current.filter((entry) => entry.key !== key),
+                };
+            }
+            if (!previous || previous.attempt !== event.entry.attempt) {
+                return {
+                    accepted: false,
+                    state: current,
+                };
+            }
+            return {
+                accepted: true,
+                state: current.map((entry) => entry.key === key ? event.entry : entry),
+            };
+        },
+        async execute(entry, { signal, send }) {
+            let completed;
+            try {
+                const output = await options.execute(entry.input, { signal });
+                if (signal.aborted) {
+                    return;
+                }
+                let refreshError;
+                try {
+                    options.confirm?.(output, entry.input);
+                }
+                catch (error) {
+                    refreshError = error;
+                }
+                completed = {
+                    ...entry,
+                    status: "succeeded",
+                    output,
+                    ...(refreshError === undefined ? {} : { refreshError }),
+                };
+            }
+            catch (error) {
+                if (signal.aborted) {
+                    return;
+                }
+                let status = "uncertain";
+                try {
+                    status = options.classifyError?.(error) ?? "uncertain";
+                }
+                catch {
+                    // Classification failure must not turn uncertainty into rejection.
+                }
+                completed = {
+                    ...entry,
+                    status,
+                    error,
+                };
+            }
+            if (signal.aborted ||
+                !(await send({
+                    type: "finish",
+                    entry: completed,
+                }))) {
+                return;
+            }
+            // Do not keep an acknowledged action pending while canonical reads refresh.
+            void Promise.resolve().then(async () => {
+                if (signal.aborted || disposed) {
+                    return;
+                }
+                try {
+                    await options.reconcile?.(entry.input);
+                }
+                catch (refreshError) {
+                    if (!signal.aborted && !disposed) {
+                        const latest = store
+                            .getSnapshot()
+                            .find((item) => item.key === entry.key);
+                        if (latest?.attempt === entry.attempt) {
+                            await store.send({
+                                type: "finish",
+                                entry: {
+                                    ...latest,
+                                    refreshError,
+                                },
+                            });
+                        }
+                    }
+                }
+            });
+        },
+    });
+    return {
+        getSnapshot: store.getSnapshot,
+        getInitialSnapshot: store.getInitialSnapshot,
+        subscribe: store.subscribe,
+        run(key, input) {
+            if (!key) {
+                return Promise.reject(new Error("An action key is required"));
+            }
+            return store.send({
+                type: "start",
+                entry: {
+                    key,
+                    input,
+                    attempt: ++attempt,
+                    status: "pending",
+                },
+            });
+        },
+        forget: (key) => store.send({
+            type: "forget",
+            key,
+        }),
+        /** Host must establish the outcome through authoritative reconciliation. */
+        resolve(key, status) {
+            const entry = store.getSnapshot().find((item) => item.key === key);
+            if (entry?.status !== "uncertain") {
+                return Promise.resolve(false);
+            }
+            return store.send({
+                type: "finish",
+                entry: {
+                    ...entry,
+                    status,
+                },
+            });
+        },
+        project(current, feedback) {
+            if (feedback.mode === "pending") {
+                return current;
+            }
+            return store.getSnapshot().reduce((view, entry) => {
+                if (entry.status !== "pending" && entry.status !== "uncertain") {
+                    return view;
+                }
+                return feedback.project(view, entry.input);
+            }, current);
+        },
+        dispose() {
+            disposed = true;
+            store.dispose();
+        },
+    };
+}

package/dist/actions/types.d.ts

@@ -0,0 +1,28 @@
+export type FailureKind = "rejected" | "uncertain";
+export interface ActionEntry<Input, Output> {
+    readonly key: string;
+    readonly attempt: number;
+    readonly input: Input;
+    readonly status: "pending" | "succeeded" | FailureKind;
+    readonly output?: Output;
+    readonly error?: unknown;
+    readonly refreshError?: unknown;
+}
+export interface ActionOptions<Input, Output> {
+    readonly execute: (input: Input, context: {
+        readonly signal: AbortSignal;
+    }) => Promise<Output>;
+    /** Only classify as rejected when the server definitely refused the write. */
+    readonly classifyError?: (error: unknown) => FailureKind;
+    /** Apply authoritative response data synchronously before success is visible. */
+    readonly confirm?: (output: Output, input: Input) => void;
+    /** Refresh in the background. Failure never reclassifies a confirmed write. */
+    readonly reconcile?: (input: Input) => void | Promise<void>;
+    readonly capacity?: number;
+}
+export type Feedback<Input, View> = {
+    readonly mode: "pending";
+} | {
+    readonly mode: "optimistic";
+    readonly project: (current: View, input: Input) => View;
+};

package/dist/actions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/query/index.d.ts

@@ -0,0 +1,16 @@
+import type { QueryClient } from "@tanstack/react-query";
+import type { ScopedActionOptions } from "../react/actions.js";
+export interface ActionMutationOptions<Input, Output> extends Omit<ScopedActionOptions<Input, Output>, "confirm" | "reconcile"> {
+    readonly confirm?: (output: Output, input: Input, client: QueryClient) => void;
+    readonly reconcile?: (input: Input, client: QueryClient) => void | Promise<void>;
+}
+/** Query integration is optional; use existing feature transport functions. */
+export declare function useActionMutation<Input, Output>(options: ActionMutationOptions<Input, Output>): {
+    ready: boolean;
+    entries: readonly import("../actions/types.js").ActionEntry<Input, Output>[];
+    get: (key: string) => import("../actions/types.js").ActionEntry<Input, Output> | undefined;
+    run: (key: string, input: Input) => Promise<boolean>;
+    resolve: (key: string, status: "succeeded" | "rejected") => Promise<boolean>;
+    forget: (key: string) => Promise<boolean>;
+    project<View>(value: View, feedback: import("../actions/types.js").Feedback<Input, View>): View;
+};

package/dist/query/index.js

@@ -0,0 +1,12 @@
+"use client";
+import { useQueryClient } from "@tanstack/react-query";
+import { useActions } from "../react/actions.js";
+/** Query integration is optional; use existing feature transport functions. */
+export function useActionMutation(options) {
+    const client = useQueryClient();
+    return useActions({
+        ...options,
+        confirm: (output, input) => options.confirm?.(output, input, client),
+        reconcile: (input) => options.reconcile?.(input, client),
+    });
+}

package/dist/react/actions.d.ts

@@ -0,0 +1,14 @@
+import type { ActionEntry, ActionOptions, Feedback } from "../actions/index.js";
+export interface ScopedActionOptions<Input, Output> extends ActionOptions<Input, Output> {
+    readonly scope: string;
+}
+/** Owns one action store per committed identity/tenant scope, including StrictMode. */
+export declare function useActions<Input, Output>(options: ScopedActionOptions<Input, Output>): {
+    ready: boolean;
+    entries: readonly ActionEntry<Input, Output>[];
+    get: (key: string) => ActionEntry<Input, Output> | undefined;
+    run: (key: string, input: Input) => Promise<boolean>;
+    resolve: (key: string, status: "succeeded" | "rejected") => Promise<boolean>;
+    forget: (key: string) => Promise<boolean>;
+    project<View>(value: View, feedback: Feedback<Input, View>): View;
+};

package/dist/react/actions.js

@@ -0,0 +1,42 @@
+"use client";
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
+import { createActions } from "../actions/index.js";
+const useCommittedEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+const empty = [];
+const subscribeEmpty = () => () => { };
+const getEmpty = () => empty;
+/** Owns one action store per committed identity/tenant scope, including StrictMode. */
+export function useActions(options) {
+    const current = useRef(options);
+    const [owned, setOwned] = useState(null);
+    useCommittedEffect(() => {
+        current.current = options;
+    });
+    useCommittedEffect(() => {
+        const store = createActions({
+            execute: (input, context) => current.current.execute(input, context),
+            classifyError: (error) => current.current.classifyError?.(error) ?? "uncertain",
+            confirm: (output, input) => current.current.confirm?.(output, input),
+            reconcile: (input) => current.current.reconcile?.(input),
+            ...(options.capacity === undefined ? {} : { capacity: options.capacity }),
+        });
+        setOwned({
+            scope: options.scope,
+            store,
+        });
+        return () => store.dispose();
+    }, [options.scope, options.capacity]);
+    const store = owned?.scope === options.scope ? owned.store : null;
+    const entries = useSyncExternalStore(store?.subscribe ?? subscribeEmpty, store?.getSnapshot ?? getEmpty, store?.getInitialSnapshot ?? getEmpty);
+    return {
+        ready: store !== null,
+        entries,
+        get: (key) => store?.getSnapshot().find((entry) => entry.key === key),
+        run: (key, input) => store?.run(key, input) ?? Promise.resolve(false),
+        resolve: (key, status) => store?.resolve(key, status) ?? Promise.resolve(false),
+        forget: (key) => store?.forget(key) ?? Promise.resolve(false),
+        project(value, feedback) {
+            return store?.project(value, feedback) ?? value;
+        },
+    };
+}

package/dist/react/index.d.ts

@@ -4,3 +4,5 @@ export declare function useMachine<State, Event>(machine: Machine<State, Event>)
     state: State;
     send: (event: Event) => Promise<boolean>;
 };
+export { useActions } from "./actions.js";
+export type { ScopedActionOptions } from "./actions.js";

package/dist/react/index.js

@@ -8,3 +8,4 @@ export function useMachine(machine) {
         send: machine.send,
     };
 }
+export { useActions } from "./actions.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plutoframework/frontend",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Explicit, typed frontend state transitions and React subscriptions for Pluto applications.",
   "type": "module",
   "license": "MIT",
@@ -23,17 +23,29 @@
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js"
+    },
+    "./actions": {
+      "types": "./dist/actions/index.d.ts",
+      "import": "./dist/actions/index.js"
+    },
+    "./query": {
+      "types": "./dist/query/index.d.ts",
+      "import": "./dist/query/index.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "react": "^18.3.1 || ^19.0.0"
+    "react": "^18.3.1 || ^19.0.0",
+    "@tanstack/react-query": "^5.105.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
     }
   },
   "scripts": {
@@ -59,6 +71,7 @@
     "react-dom": "19.3.1",
     "typescript": "5.9.3",
     "typescript-eslint": "8.72.1",
-    "vitest": "5.0.5"
+    "vitest": "5.0.5",
+    "@tanstack/react-query": "5.105.0"
   }
 }