hono-preact 0.2.0 → 0.3.0

package/dist/iso/action-result-context.d.ts

@@ -0,0 +1,22 @@
+export type ActionResultContextValue = {
+    module: string;
+    action: string;
+    kind: 'success';
+    data: unknown;
+    submittedPayload: unknown;
+} | {
+    module: string;
+    action: string;
+    kind: 'deny';
+    status: number;
+    message: string;
+    data?: unknown;
+    submittedPayload: unknown;
+} | {
+    module: string;
+    action: string;
+    kind: 'error';
+    message: string;
+    submittedPayload: unknown;
+} | null;
+export declare const ActionResultContext: import("preact").Context<ActionResultContextValue>;

package/dist/iso/action-result-context.js

@@ -0,0 +1,2 @@
+import { createContext } from 'preact';
+export const ActionResultContext = createContext(null);

package/dist/iso/action.d.ts

@@ -15,13 +15,34 @@ export type ActionFn<TPayload, TResult, TChunk = never> = ((ctx: ActionCtx, payl
 export type DefineActionOpts<TChunk = never, TResult = unknown> = {
     /**
      * Per-action middleware and (for streaming actions) stream observers.
-     * Attached to the function as a non-enumerable-feeling property; the
-     * actions-handler reads it via the dispatcher (Task 18).
+     * Attached to the function as a non-enumerable property; the
+     * page-action-handler reads it through the typed `ActionEntry` map built at
+     * module-load time (`packages/server/src/page-action-handler.ts`).
      */
     use?: ActionUse<TChunk, TResult, boolean>;
+    /**
+     * Per-action timeout in milliseconds. When omitted, the handler applies
+     * its configured default (30s). Pass `false` to disable the timeout for
+     * this action.
+     */
+    timeoutMs?: number | false;
+    /**
+     * The module key the client-side `useAction` hook will reference in its
+     * RPC envelope. Production wires this through the Vite plugin's
+     * client-stub emission; test code can pass it directly to construct a
+     * properly-shaped stub without bypassing the type system.
+     */
+    __module?: string;
+    /** The action name the client-side `useAction` hook will reference. */
+    __action?: string;
 };
+export declare class TimeoutError extends Error {
+    readonly kind: "timeout";
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
 export declare function defineAction<TPayload, TResult, TChunk = never>(fn: ActionFn<TPayload, TResult, TChunk>, opts?: DefineActionOpts<TChunk, TResult>): ActionStub<TPayload, TResult, TChunk>;
-export type UseActionOptions<TPayload, TResult, TChunk = never, TSnapshot = unknown> = {
+type UseActionOptionsCommon<TChunk = never> = {
     /**
      * How to update loader caches after the action commits. Three modes:
      *
@@ -37,30 +58,47 @@ export type UseActionOptions<TPayload, TResult, TChunk = never, TSnapshot = unkn
      * See `/docs/reloading` for the full mental model.
      */
     invalidate?: 'auto' | false | ReadonlyArray<LoaderRef<unknown>>;
-    onMutate?: (payload: TPayload) => TSnapshot;
     onChunk?: (chunk: TChunk) => void;
+};
+/**
+ * Options when `onMutate` is provided. `onSuccess` / `onError` receive the
+ * value `onMutate` returned for this specific mutation as the second
+ * parameter, so concurrent calls can be paired with their own snapshot.
+ */
+type UseActionWithMutate<TPayload, TResult, TChunk, TSnapshot> = UseActionOptionsCommon<TChunk> & {
+    onMutate: (payload: TPayload) => TSnapshot;
     onError?: (err: Error, snapshot: TSnapshot) => void;
     onSuccess?: (data: TResult, snapshot: TSnapshot) => void;
 };
+/**
+ * Options when `onMutate` is not provided. `onSuccess` / `onError` take
+ * only the result / error — there is no snapshot to thread through.
+ */
+type UseActionWithoutMutate<TResult, TChunk> = UseActionOptionsCommon<TChunk> & {
+    onMutate?: undefined;
+    onError?: (err: Error) => void;
+    onSuccess?: (data: TResult) => void;
+};
+/**
+ * Discriminated by `onMutate`. Providing `onMutate` requires the
+ * `onSuccess` / `onError` callbacks to accept the snapshot; omitting
+ * `onMutate` types those callbacks as single-argument.
+ */
+export type UseActionOptions<TPayload, TResult, TChunk = never, TSnapshot = unknown> = UseActionWithMutate<TPayload, TResult, TChunk, TSnapshot> | UseActionWithoutMutate<TResult, TChunk>;
 /**
  * The value `mutate` resolves to. A discriminated union so callers can
  * chain on success without awaiting then probing the hook's `data`/`error`
  * state, and without leaking unhandled rejections in fire-and-forget callers.
  *
- * - Success: `{ ok: true, data }`. For streaming actions that emit no
- *   `result` SSE event, `data` is `undefined`; declare `TResult = void` (or
- *   include `undefined` in its union) if your action doesn't emit a result.
+ * - Success: `{ ok: true, data }`. `data` is `undefined` for streaming
+ *   actions that close without emitting a `result` SSE event (the type
+ *   reflects this honestly: callers must narrow before using `data`).
  * - Failure: `{ ok: false, error }`. The same `Error` instance is also
  *   written to the hook's `error` state and passed to `onError`.
- *
- * Returning a union (rather than throwing) keeps `mutate(...)` ergonomic
- * for non-awaiting call sites — the existing `error` state field is the
- * idiomatic way to render an error UI — while still letting awaiting
- * callers do `if (result.ok) navigate(...)`.
  */
 export type MutateResult<TResult> = {
     ok: true;
-    data: TResult;
+    data: TResult | undefined;
 } | {
     ok: false;
     error: Error;
@@ -72,3 +110,4 @@ export type UseActionResult<TPayload, TResult> = {
     data: TResult | null;
 };
 export declare function useAction<TPayload, TResult, TChunk = never, TSnapshot = unknown>(stub: ActionStub<TPayload, TResult, TChunk>, options?: UseActionOptions<TPayload, TResult, TChunk, TSnapshot>): UseActionResult<TPayload, TResult>;
+export {};

package/dist/iso/action.js

@@ -1,25 +1,62 @@
 import { useCallback, useContext, useRef, useState } from 'preact/hooks';
 import { ReloadContext } from './reload-context.js';
 import { ActiveLoaderIdContext } from './internal/contexts.js';
+import { beginSubmit, endSubmit } from './internal/form-submit-store.js';
+import { assignSafeRedirect } from './internal/safe-redirect.js';
+import { setLastActionResult, } from './internal/action-result-store.js';
+export class TimeoutError extends Error {
+    kind = 'timeout';
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+function validateTimeoutMs(value, context) {
+    if (value === undefined || value === false)
+        return;
+    if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${context}: timeoutMs must be a non-negative finite number or false, got ${String(value)}`);
+    }
+}
 export function defineAction(fn, opts) {
-    // Runtime no-op for the call itself: returns fn as-is. The ActionStub type
-    // is enforced only by TypeScript and the Vite plugin. The dispatcher reads
-    // `use` off the function-as-stub when running the chain.
+    validateTimeoutMs(opts?.timeoutMs, 'defineAction');
+    // SHAPE NOTE: `ActionStub` describes the CLIENT-side shape produced by the
+    // Vite plugin (`packages/vite/src/server-only.ts`) — an object with
+    // `__module`, `__action`, and a `useAction` method. `defineAction` runs on
+    // the SERVER side and returns the raw function with metadata attached via
+    // `Object.defineProperty`. These are two different runtime shapes unified
+    // under one type so consumers can import a server action and use it
+    // identically on both sides; the plugin handles the substitution at the
+    // value level. The `as unknown as` cast at the return is the single
+    // bounded acknowledgement of this dual-shape contract. A future cleanup
+    // could split into `ServerActionImpl` / `ActionStub` types if the lie
+    // starts to bite, but for now it's localized and documented.
     //
-    // Use `Object.defineProperty` instead of direct assignment so a frozen
-    // module export (strict ESM, HMR-frozen modules) doesn't throw. The
-    // actions-handler reads via `(fn as { use?: ReadonlyArray<unknown> }).use`,
-    // which works whether the property was set by assignment or defineProperty.
-    if (opts?.use) {
-        Object.defineProperty(fn, 'use', {
-            value: opts.use,
+    // `Object.defineProperty` is used instead of direct assignment so a frozen
+    // module export (strict ESM, HMR-frozen modules) does not throw.
+    const attach = (key, value) => {
+        Object.defineProperty(fn, key, {
+            value,
             configurable: true,
             writable: true,
             enumerable: false,
         });
-    }
+    };
+    if (opts?.use)
+        attach('use', opts.use);
+    if (opts?.timeoutMs !== undefined)
+        attach('timeoutMs', opts.timeoutMs);
+    if (opts?.__module !== undefined)
+        attach('__module', opts.__module);
+    if (opts?.__action !== undefined)
+        attach('__action', opts.__action);
     return fn;
 }
+function recordOutcome(module, action, result) {
+    setLastActionResult(module, action, result);
+}
 function hasFileValues(payload) {
     if (typeof File === 'undefined')
         return false;
@@ -42,18 +79,49 @@ export function useAction(stub, options) {
         setError(null);
         const currentStub = stubRef.current;
         const currentOptions = optionsRef.current;
-        let snapshot;
-        if (currentOptions?.onMutate) {
-            snapshot = currentOptions.onMutate(payload);
-        }
+        const callbacks = currentOptions?.onMutate
+            ? {
+                kind: 'with-mutate',
+                snapshot: currentOptions.onMutate(payload),
+                onSuccess: currentOptions.onSuccess,
+                onError: currentOptions.onError,
+            }
+            : {
+                kind: 'without-mutate',
+                onSuccess: currentOptions?.onSuccess,
+                onError: currentOptions?.onError,
+            };
+        const invokeSuccess = (data) => {
+            if (callbacks.kind === 'with-mutate') {
+                callbacks.onSuccess?.(data, callbacks.snapshot);
+            }
+            else {
+                callbacks.onSuccess?.(data);
+            }
+        };
+        const invokeError = (err) => {
+            if (callbacks.kind === 'with-mutate') {
+                callbacks.onError?.(err, callbacks.snapshot);
+            }
+            else {
+                callbacks.onError?.(err);
+            }
+        };
+        const target = typeof window !== 'undefined'
+            ? window.location.pathname + window.location.search
+            : '/';
         let finalResult;
+        // Tracks whether a branch has already written to the action-result store.
+        // The outer catch writes for unclassified errors (network failures, parse
+        // errors) only when no branch has already recorded the outcome.
+        let outcomeRecorded = false;
+        beginSubmit(currentStub.__module, currentStub.__action);
         try {
-            const stub = currentStub;
             let response;
             if (hasFileValues(payload)) {
                 const fd = new FormData();
-                fd.append('__module', stub.__module);
-                fd.append('__action', stub.__action);
+                fd.append('__module', currentStub.__module);
+                fd.append('__action', currentStub.__action);
                 for (const [key, value] of Object.entries(payload)) {
                     if (key === '__module' || key === '__action')
                         continue;
@@ -67,75 +135,27 @@ export function useAction(stub, options) {
                         fd.append(key, JSON.stringify(value));
                     }
                 }
-                response = await fetch('/__actions', { method: 'POST', body: fd });
+                response = await fetch(target, {
+                    method: 'POST',
+                    headers: { Accept: 'application/json, text/event-stream;q=0.9' },
+                    body: fd,
+                });
             }
             else {
-                response = await fetch('/__actions', {
+                response = await fetch(target, {
                     method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Accept: 'application/json, text/event-stream;q=0.9',
+                    },
                     body: JSON.stringify({
-                        module: stub.__module,
-                        action: stub.__action,
+                        module: currentStub.__module,
+                        action: currentStub.__action,
                         payload,
                     }),
                 });
             }
-            if (!response.ok) {
-                const body = (await response.json().catch(() => ({})));
-                // Deny outcomes carry `message` instead of the legacy `error`
-                // field; prefer the descriptive message when present. The deny()
-                // constructor defaults the message for first-party callers, but a
-                // hand-rolled envelope from custom server middleware might still
-                // ship without one; fall back to a deny-aware label so the user
-                // sees a hint that the status came from an explicit deny rather
-                // than a generic transport failure.
-                let msg;
-                if (body.__outcome === 'deny') {
-                    msg =
-                        typeof body.message === 'string'
-                            ? body.message
-                            : `Request denied (${response.status})`;
-                }
-                else {
-                    msg = body.error ?? `Action failed with status ${response.status}`;
-                }
-                throw new Error(msg);
-            }
             const contentType = response.headers.get('Content-Type') ?? '';
-            // Server-side middleware that throws `redirect(...)` comes back as
-            // a redirect outcome envelope. Hand off to the browser; the rest of
-            // this promise will never settle, but the page is navigating away
-            // anyway.
-            //
-            // Trust boundary: `to` is taken straight from the JSON body and
-            // passed to `window.location.assign`. The framework's own handlers
-            // emit safe (typically same-origin) values, but a compromised or
-            // misconfigured server (or a proxy injecting JSON) could push the
-            // client anywhere. We don't validate origin here for v0.1; treat
-            // your own server as part of the trusted boundary. A same-origin
-            // check is a deferred enhancement (see C4 in the middleware review).
-            //
-            // We use `response.clone().json()` to peek at the body without
-            // consuming it: if the response is NOT a redirect outcome the
-            // downstream `await response.json()` still needs to read it. Clone
-            // is cheap on a small JSON payload.
-            if (!contentType.includes('text/event-stream')) {
-                const peek = (await response
-                    .clone()
-                    .json()
-                    .catch(() => undefined));
-                if (peek !== null &&
-                    typeof peek === 'object' &&
-                    peek.__outcome === 'redirect' &&
-                    typeof peek.to === 'string') {
-                    const to = peek.to;
-                    if (typeof window !== 'undefined') {
-                        window.location.assign(to);
-                    }
-                    // Cast through `as` because TS can't see this promise never settles.
-                    return await new Promise(() => { });
-                }
-            }
             if (contentType.includes('text/event-stream') && response.body) {
                 const { readSSE } = await import('./internal/sse-decoder.js');
                 let resultValue;
@@ -157,6 +177,15 @@ export function useAction(stub, options) {
                             streamError = new Error(`Malformed result event in stream: ${e instanceof Error ? e.message : String(e)}`);
                         }
                     }
+                    else if (ev.event === 'timeout') {
+                        try {
+                            const parsed = JSON.parse(ev.data);
+                            streamError = new TimeoutError(parsed.timeoutMs ?? 0);
+                        }
+                        catch (e) {
+                            streamError = new Error(`Malformed timeout event in stream: ${e instanceof Error ? e.message : String(e)}`);
+                        }
+                    }
                     else if (ev.event === 'error') {
                         try {
                             const parsed = JSON.parse(ev.data);
@@ -170,26 +199,101 @@ export function useAction(stub, options) {
                     }
                 }
                 if (streamError) {
+                    recordOutcome(currentStub.__module, currentStub.__action, {
+                        kind: 'error',
+                        message: streamError.message,
+                        submittedPayload: payload,
+                    });
+                    outcomeRecorded = true;
                     throw streamError;
                 }
                 if (resultValue !== undefined) {
                     setData(resultValue);
-                    currentOptions?.onSuccess?.(resultValue, snapshot);
+                    invokeSuccess(resultValue);
                     finalResult = resultValue;
+                    recordOutcome(currentStub.__module, currentStub.__action, {
+                        kind: 'success',
+                        data: resultValue,
+                        submittedPayload: payload,
+                    });
+                    outcomeRecorded = true;
                 }
                 else {
-                    currentOptions?.onSuccess?.(undefined, snapshot);
-                    // Streaming actions with no `result` event resolve with undefined.
-                    // Consumers should type `TResult = void` (or include `undefined`)
-                    // when their action doesn't emit a result.
+                    // Streaming action closed without emitting a `result` event;
+                    // resolve with `data: undefined`. `onSuccess` is not called
+                    // in this branch since there is no result value to deliver
+                    // (matches the static-action path where onSuccess only fires
+                    // with a real value).
                     finalResult = undefined;
                 }
             }
             else {
-                const result = (await response.json());
-                setData(result);
-                currentOptions?.onSuccess?.(result, snapshot);
-                finalResult = result;
+                // Uniform envelope path. All non-streaming responses carry a JSON
+                // body shaped as { __outcome, ... } regardless of HTTP status.
+                let env;
+                try {
+                    env = (await response.json());
+                }
+                catch {
+                    throw new Error(`Malformed envelope (HTTP ${response.status})`);
+                }
+                if (env.__outcome === 'success') {
+                    const data = env.data;
+                    setData(data);
+                    invokeSuccess(data);
+                    finalResult = data;
+                    recordOutcome(currentStub.__module, currentStub.__action, {
+                        kind: 'success',
+                        data,
+                        submittedPayload: payload,
+                    });
+                    outcomeRecorded = true;
+                }
+                else if (env.__outcome === 'redirect' &&
+                    typeof env.to === 'string') {
+                    if (assignSafeRedirect(env.to)) {
+                        // Navigation issued; this promise never settles.
+                        return await new Promise(() => { });
+                    }
+                    // Cross-origin: surface as an error so the caller can handle it.
+                    throw new Error(`Refused cross-origin redirect to ${env.to}`);
+                }
+                else if (env.__outcome === 'deny') {
+                    const msg = env.message ??
+                        `Request denied (${env.status ?? response.status})`;
+                    recordOutcome(currentStub.__module, currentStub.__action, {
+                        kind: 'deny',
+                        status: env.status ?? response.status,
+                        message: msg,
+                        data: env.data,
+                        submittedPayload: payload,
+                    });
+                    outcomeRecorded = true;
+                    throw new Error(msg);
+                }
+                else if (env.__outcome === 'timeout' &&
+                    typeof env.timeoutMs === 'number') {
+                    recordOutcome(currentStub.__module, currentStub.__action, {
+                        kind: 'error',
+                        message: `Request timed out after ${env.timeoutMs}ms`,
+                        submittedPayload: payload,
+                    });
+                    outcomeRecorded = true;
+                    throw new TimeoutError(env.timeoutMs);
+                }
+                else if (env.__outcome === 'error') {
+                    const msg = env.message ?? 'Action failed';
+                    recordOutcome(currentStub.__module, currentStub.__action, {
+                        kind: 'error',
+                        message: msg,
+                        submittedPayload: payload,
+                    });
+                    outcomeRecorded = true;
+                    throw new Error(msg);
+                }
+                else {
+                    throw new Error(`Unknown action outcome: ${env.__outcome}`);
+                }
             }
             if (currentOptions?.invalidate === 'auto') {
                 reloadCtx?.reload();
@@ -213,11 +317,23 @@ export function useAction(stub, options) {
         }
         catch (err) {
             const e = err instanceof Error ? err : new Error(String(err));
+            // Write to the store only for unclassified errors (network failures,
+            // parse errors). Per-branch errors set outcomeRecorded before throwing.
+            if (!outcomeRecorded) {
+                recordOutcome(currentStub.__module, currentStub.__action, {
+                    kind: 'error',
+                    message: e.message,
+                    submittedPayload: payload,
+                });
+            }
             setError(e);
-            currentOptions?.onError?.(e, snapshot);
+            invokeError(e);
             setPending(false);
             return { ok: false, error: e };
         }
+        finally {
+            endSubmit(currentStub.__module, currentStub.__action);
+        }
         setPending(false);
         return { ok: true, data: finalResult };
     }, []);

package/dist/iso/cache.d.ts

@@ -1,4 +1,5 @@
 import type { Loader } from './define-loader.js';
+import type { ActionResolution } from './internal/action-envelope.js';
 export interface LoaderCache<T> {
     get(locKey?: string): T | null;
     set(value: T, locKey?: string): void;
@@ -9,6 +10,14 @@ export interface LoaderCache<T> {
 type RequestStore = Map<symbol, unknown>;
 export declare function getRequestStore(): RequestStore | undefined;
 export declare function getRequestHonoContext<T = unknown>(): T | undefined;
+export type ActionResultSlot = {
+    module: string;
+    action: string;
+    resolution: ActionResolution;
+    submittedPayload: unknown;
+};
+export declare function getActionResultSlot(): ActionResultSlot | null;
+export declare function setActionResultSlot(slot: ActionResultSlot): void;
 export declare function runRequestScope<R>(fn: () => R | Promise<R>, initial?: {
     honoContext?: unknown;
 }): R | Promise<R>;

package/dist/iso/cache.js

@@ -18,6 +18,7 @@ if (!looksLikeBrowser) {
     }
 }
 const HONO_CONTEXT_KEY = Symbol('@hono-preact/iso/honoContext');
+const ACTION_RESULT_KEY = Symbol('@hono-preact/iso/actionResult');
 export function getRequestStore() {
     return alsInstance?.getStore();
 }
@@ -36,9 +37,34 @@ export function getRequestHonoContext() {
     }
     return ctx;
 }
+export function getActionResultSlot() {
+    const store = getRequestStore();
+    if (!store)
+        return null;
+    const slot = store.get(ACTION_RESULT_KEY);
+    return (slot ?? null);
+}
+export function setActionResultSlot(slot) {
+    const store = getRequestStore();
+    if (!store) {
+        throw new Error('setActionResultSlot must be called inside runRequestScope');
+    }
+    store.set(ACTION_RESULT_KEY, slot);
+}
 export function runRequestScope(fn, initial) {
     if (!alsInstance)
         return fn();
+    const existing = alsInstance.getStore();
+    if (existing) {
+        // Nested call: inherit the parent store. Seeded values are written
+        // additively so the inner caller's overrides take effect without
+        // wiping the parent's per-request state (e.g. the action-result
+        // slot set by pageActionHandler before it invokes renderPage).
+        if (initial?.honoContext !== undefined) {
+            existing.set(HONO_CONTEXT_KEY, initial.honoContext);
+        }
+        return fn();
+    }
     const store = new Map();
     if (initial?.honoContext !== undefined) {
         store.set(HONO_CONTEXT_KEY, initial.honoContext);

package/dist/iso/define-app.d.ts

@@ -3,5 +3,12 @@ import type { StreamObserver } from './define-stream-observer.js';
 export type AppUseElement = ServerMiddleware<'page'> | ClientMiddleware | StreamObserver<unknown, never>;
 export type AppConfig = {
     use?: ReadonlyArray<AppUseElement>;
+    /**
+     * When `true`, the server emits a `<script type="speculationrules">` tag
+     * into `<head>` that instructs supporting browsers to prefetch same-origin
+     * `<a href>` links on moderate eagerness. Defaults to `false`. Individual
+     * links opt out with `data-no-prefetch`.
+     */
+    speculation?: boolean;
 };
 export declare function defineApp(config: AppConfig): AppConfig;

package/dist/iso/define-loader.d.ts

@@ -18,6 +18,12 @@ export interface LoaderRef<T> {
     readonly fn: Loader<T>;
     readonly cache: LoaderCache<T>;
     readonly params: string[] | '*';
+    /**
+     * Raw value as authored on `defineLoader({ timeoutMs })`. `undefined`
+     * means "use the handler's configured default"; `false` means "no
+     * timeout, only the request signal aborts".
+     */
+    readonly timeoutMs?: number | false;
     /**
      * Per-loader middleware and (for streaming loaders) stream observers,
      * exactly as authored on `defineLoader({ use })`. The handler-side
@@ -55,6 +61,12 @@ export type DefineLoaderOpts<T> = {
     __loaderName?: string;
     cache?: LoaderCache<T>;
     params?: string[] | '*';
+    /**
+     * Per-loader timeout in milliseconds. When omitted, the handler applies
+     * its configured default (30s). Pass `false` to disable the timeout for
+     * this loader (rely solely on the request signal).
+     */
+    timeoutMs?: number | false;
     /**
      * Per-loader middleware and (for streaming loaders) stream observers.
      * The element type LoaderUse<T, Streaming> structurally gates stream