hono-preact 0.1.0 → 0.3.0

package/dist/server/loaders-handler.js

@@ -1,5 +1,5 @@
-import { GuardRedirect } from '../iso/index.js';
-import { runRequestScope } from '../iso/internal/index.js';
+import { isOutcome, timeoutOutcome, } from '../iso/index.js';
+import { runRequestScope, dispatchServer, partitionUse, } from '../iso/internal.js';
 import { sseGeneratorResponse, sseReadableStreamResponse, isAsyncGenerator, } from './sse.js';
 async function buildLoadersMap(glob) {
     const result = {};
@@ -16,12 +16,18 @@ async function buildLoadersMap(glob) {
                 // Two accepted shapes:
                 //   1. a raw loader function `(ctx) => ...` (used by unit-test fixtures)
                 //   2. a `LoaderRef` returned by `defineLoader(fn)`, whose `.fn`
-                //      property carries the original loader (used by user code)
+                //      property carries the original loader and `.use` carries any
+                //      attached middleware/observers.
                 if (typeof val === 'function') {
-                    result[`${moduleKey}::${name}`] = val;
+                    result[`${moduleKey}::${name}`] = { fn: val, use: [] };
                 }
                 else if (val && typeof val.fn === 'function') {
-                    result[`${moduleKey}::${name}`] = val.fn;
+                    const ref = val;
+                    result[`${moduleKey}::${name}`] = {
+                        fn: ref.fn,
+                        use: ref.use ?? [],
+                        timeoutMs: ref.timeoutMs,
+                    };
                 }
             }
         }
@@ -44,8 +50,40 @@ function validateLocation(loc) {
         searchParams: o.searchParams,
     };
 }
+function translateOutcomeForLoader(c, outcome) {
+    if (outcome.__outcome === 'redirect') {
+        // Headers from the outcome ride the HTTP response via `c.header()`. They
+        // are deliberately NOT embedded in the JSON envelope: the client only
+        // reads `to` and calls `window.location.assign(to)`; any embedded
+        // headers would be dead bytes the client never inspects.
+        if (outcome.headers) {
+            for (const [k, v] of Object.entries(outcome.headers))
+                c.header(k, v);
+        }
+        return c.json({
+            __outcome: 'redirect',
+            to: outcome.to,
+            status: outcome.status,
+        }, 200);
+    }
+    if (outcome.__outcome === 'deny') {
+        if (outcome.headers) {
+            for (const [k, v] of Object.entries(outcome.headers))
+                c.header(k, v);
+        }
+        return c.json({ __outcome: 'deny', message: outcome.message }, outcome.status);
+    }
+    if (outcome.__outcome === 'timeout') {
+        return c.json({ __outcome: 'timeout', timeoutMs: outcome.timeoutMs }, 504);
+    }
+    // render outcome should never reach the loader RPC; this is defense in depth.
+    return c.json({
+        __outcome: 'error',
+        message: 'render outcome is page-scope only',
+    }, 500);
+}
 export function loadersHandler(glob, opts = {}) {
-    const { dev = false, onError } = opts;
+    const { dev = false, onError, appConfig, resolvePageUse, defaultTimeoutMs = 30_000, } = opts;
     let cachedMapPromise = null;
     return async (c) => {
         const loadersMapPromise = dev
@@ -82,28 +120,100 @@ export function loadersHandler(glob, opts = {}) {
                 error: 'Request body must include object field: location with shape { path: string, pathParams: object, searchParams: object }',
             }, 400);
         }
-        const loaderFn = loadersMap[`${module}::${loaderName}`];
-        if (!loaderFn) {
+        const entry = loadersMap[`${module}::${loaderName}`];
+        if (!entry) {
             return c.json({ error: `Loader '${module}::${loaderName}' not found` }, 404);
         }
-        const signal = c.req.raw.signal;
+        const resolvedTimeoutMs = entry.timeoutMs !== undefined ? entry.timeoutMs : defaultTimeoutMs;
+        const timeoutSignal = resolvedTimeoutMs === false
+            ? undefined
+            : AbortSignal.timeout(resolvedTimeoutMs);
+        const signal = timeoutSignal
+            ? AbortSignal.any([c.req.raw.signal, timeoutSignal])
+            : c.req.raw.signal;
+        // Chain ordering is outer -> inner: app-level middleware wraps every
+        // request, page-level wraps loaders owned by that page, and per-loader
+        // middleware wraps just this call. Outer middleware runs first on the
+        // way in and last on the way out, matching every middleware system
+        // users have seen (Hono, Express, Koa).
+        const rootUse = appConfig?.use ?? [];
+        const pageUse = (await resolvePageUse?.(validatedLocation.path)) ?? [];
+        const fullUse = [...rootUse, ...pageUse, ...entry.use];
+        const { middleware: allMiddleware, observers } = partitionUse(fullUse);
+        const serverMw = allMiddleware.filter((m) => m.runs === 'server');
+        const ctx = {
+            scope: 'loader',
+            c,
+            signal,
+            location: validatedLocation,
+            module,
+            loader: loaderName,
+        };
         try {
-            const result = await runRequestScope(() => Promise.resolve(loaderFn({ c, location: validatedLocation, signal })), { honoContext: c });
+            const result = await runRequestScope(async () => {
+                const dispatch = await dispatchServer({
+                    middleware: serverMw,
+                    ctx,
+                    inner: async () => {
+                        const inner = await entry.fn({
+                            c,
+                            location: validatedLocation,
+                            signal,
+                        });
+                        // A loader that does `return redirect('/login')` instead of
+                        // `throw redirect('/login')` would otherwise ship the outcome
+                        // JSON shape as a normal 200 response and bypass envelope
+                        // translation. Normalize by re-throwing so the existing
+                        // outcome-catching path translates it.
+                        if (isOutcome(inner))
+                            throw inner;
+                        return inner;
+                    },
+                });
+                if (dispatch.kind === 'outcome') {
+                    // Throw to unify with non-outcome error translation below.
+                    throw dispatch.outcome;
+                }
+                return dispatch.value;
+            }, { honoContext: c });
             if (isAsyncGenerator(result)) {
-                return sseGeneratorResponse(c, result, { emitResult: false });
+                return sseGeneratorResponse(c, result, {
+                    emitResult: false,
+                    observers,
+                    observerCtx: ctx,
+                    signal: timeoutSignal,
+                    timeoutMs: typeof resolvedTimeoutMs === 'number'
+                        ? resolvedTimeoutMs
+                        : undefined,
+                });
             }
             if (result instanceof ReadableStream) {
-                return sseReadableStreamResponse(c, result);
+                return sseReadableStreamResponse(c, result, {
+                    observers,
+                    observerCtx: ctx,
+                    signal: timeoutSignal,
+                    timeoutMs: typeof resolvedTimeoutMs === 'number'
+                        ? resolvedTimeoutMs
+                        : undefined,
+                });
             }
             return c.json(result);
         }
         catch (err) {
-            // GuardRedirect thrown from a loader (or a guard that runs inside it)
-            // is a control-flow signal, not an error. The client RPC stub
-            // recognizes the `__redirect` envelope and navigates the browser
-            // rather than surfacing this as a thrown error in user code.
-            if (err instanceof GuardRedirect) {
-                return c.json({ __redirect: err.location });
+            if (isOutcome(err)) {
+                return translateOutcomeForLoader(c, err);
+            }
+            // Distinguish a deadline-driven abort from any other thrown error.
+            // AbortSignal.timeout sets signal.reason to a DOMException named
+            // 'TimeoutError'; AbortSignal.any propagates that reason. Re-check the
+            // composed signal because the loader's own throw may be the
+            // *consequence* of the signal aborting (e.g. fetch rejecting with the
+            // abort reason).
+            if (timeoutSignal?.aborted &&
+                timeoutSignal.reason instanceof DOMException &&
+                timeoutSignal.reason.name === 'TimeoutError' &&
+                typeof resolvedTimeoutMs === 'number') {
+                return translateOutcomeForLoader(c, timeoutOutcome(resolvedTimeoutMs));
             }
             onError?.(err, { module, loader: loaderName });
             // In production we never leak the loader's error message: it may

package/dist/server/page-action-handler.d.ts

@@ -0,0 +1,63 @@
+import type { Context, MiddlewareHandler } from 'hono';
+import { type AppConfig } from '../iso/index';
+import type { ActionEntry } from './page-action-resolvers.js';
+import type { VNode } from 'preact';
+export interface PageActionHandlerOptions {
+    /**
+     * Resolves the action map for the page at the given URL path. Returns a
+     * Map of action name to ActionEntry, merging actions from the page and
+     * all ancestor layouts.
+     */
+    resolverByPath: (path: string) => Promise<Map<string, ActionEntry>>;
+    /**
+     * Optional per-page middleware resolver, keyed by URL path. The handler
+     * composes the chain as [appConfig.use, resolvePageUseByPath(path), action.use].
+     * Pass `pageUseResolvers.byPath` from makePageUseResolvers (same resolver
+     * loadersHandler uses). Defaults to returning empty so the option is
+     * additive: handlers wired without it lose page-level middleware (matches
+     * the previous behavior of this handler, which dropped them entirely).
+     */
+    resolvePageUseByPath?: (path: string) => ReadonlyArray<unknown> | Promise<ReadonlyArray<unknown>>;
+    /**
+     * Re-renders the page after a deny or error outcome. The handler calls
+     * this inside a fresh runRequestScope after injecting the action result
+     * slot so the page tree can read it via useActionResult().
+     */
+    renderPage: (c: Context, node: VNode, opts: {
+        appConfig?: AppConfig;
+    }) => Promise<Response>;
+    /**
+     * Resolves the VNode to render for the given URL path. Returns null when
+     * no page is registered; the handler passes null through to renderPage,
+     * which is expected to produce a graceful error response in that case.
+     */
+    resolvePageNode: (path: string) => VNode | null;
+    /** App-level middleware/observer array from defineApp({ use }). */
+    appConfig?: AppConfig;
+    /**
+     * Default timeout in milliseconds for actions that don't declare their
+     * own timeoutMs. Defaults to 30000. Pass false to disable the default.
+     */
+    defaultTimeoutMs?: number | false;
+    /**
+     * Called for every unexpected error an action throws. Use it to hook into
+     * your observability stack. The handler still responds with a sanitized
+     * 500; this is a side channel only.
+     */
+    onError?: (err: unknown, ctx: {
+        module: string;
+        action: string;
+    }) => void;
+}
+type Accept = 'html' | 'json' | 'event-stream';
+/**
+ * Parse the Accept header and return the highest-priority recognized type.
+ * Follows RFC 9110 quality values (;q=0.9 etc) so that
+ * "application/json, text/event-stream;q=0.9" correctly resolves to 'json',
+ * not 'event-stream'. Unspecified quality defaults to 1.0.
+ *
+ * Internal: exported for unit testing only; not part of the public API.
+ */
+export declare function pickAccept(header: string | undefined): Accept;
+export declare function pageActionHandler(opts: PageActionHandlerOptions): MiddlewareHandler;
+export {};

package/dist/server/page-action-handler.js

@@ -0,0 +1,274 @@
+import { isOutcome, timeoutOutcome, } from '../iso/index.js';
+import { runRequestScope, setActionResultSlot, dispatchServer, partitionUse, serializeActionOutcome, } from '../iso/internal.js';
+import { sseGeneratorResponse, sseReadableStreamResponse, isAsyncGenerator, } from './sse.js';
+/**
+ * Parse the Accept header and return the highest-priority recognized type.
+ * Follows RFC 9110 quality values (;q=0.9 etc) so that
+ * "application/json, text/event-stream;q=0.9" correctly resolves to 'json',
+ * not 'event-stream'. Unspecified quality defaults to 1.0.
+ *
+ * Internal: exported for unit testing only; not part of the public API.
+ */
+export function pickAccept(header) {
+    const h = header ?? '';
+    const candidates = [];
+    for (const part of h.split(',')) {
+        const [mediaType, ...params] = part.trim().split(';');
+        const mt = (mediaType ?? '').trim().toLowerCase();
+        let q = 1.0;
+        for (const p of params) {
+            const kv = p.trim().split('=');
+            if (kv[0]?.trim() === 'q' && kv[1] !== undefined) {
+                const parsed = Number(kv[1].trim());
+                if (!Number.isNaN(parsed))
+                    q = parsed;
+            }
+        }
+        if (mt === 'text/event-stream')
+            candidates.push({ type: 'event-stream', q });
+        else if (mt === 'application/json')
+            candidates.push({ type: 'json', q });
+        else if (mt === 'text/html' || mt === '*/*')
+            candidates.push({ type: 'html', q });
+    }
+    if (candidates.length === 0)
+        return 'html';
+    candidates.sort((a, b) => b.q - a.q);
+    return candidates[0].type;
+}
+async function parseBody(c) {
+    const ct = (c.req.header('Content-Type') ?? '').toLowerCase();
+    if (ct.startsWith('application/json')) {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return { error: 'Invalid JSON body', status: 400 };
+        }
+        const { module: m, action: a, payload: p } = body;
+        if (typeof m !== 'string' || typeof a !== 'string') {
+            return {
+                error: 'JSON body must include string fields: module, action',
+                status: 400,
+            };
+        }
+        return { module: m, action: a, payload: p };
+    }
+    if (ct.startsWith('multipart/form-data') ||
+        ct.startsWith('application/x-www-form-urlencoded')) {
+        let fd;
+        try {
+            fd = await c.req.formData();
+        }
+        catch {
+            return { error: 'Invalid form data', status: 400 };
+        }
+        const m = fd.get('__module');
+        const a = fd.get('__action');
+        if (typeof m !== 'string' || typeof a !== 'string') {
+            return {
+                error: 'Form data must include __module and __action fields',
+                status: 400,
+            };
+        }
+        const payload = {};
+        for (const [key, value] of fd.entries()) {
+            if (key === '__module' || key === '__action')
+                continue;
+            const existing = payload[key];
+            if (existing !== undefined) {
+                payload[key] = Array.isArray(existing)
+                    ? [...existing, value]
+                    : [existing, value];
+            }
+            else {
+                payload[key] = value;
+            }
+        }
+        return { module: m, action: a, payload };
+    }
+    return {
+        error: `Unsupported Content-Type: ${ct || '(empty)'}`,
+        status: 415,
+    };
+}
+export function pageActionHandler(opts) {
+    const { resolverByPath, resolvePageUseByPath, renderPage, resolvePageNode, appConfig, defaultTimeoutMs = 30_000, onError, } = opts;
+    return async (c) => {
+        const accept = pickAccept(c.req.header('Accept'));
+        const parsed = await parseBody(c);
+        if ('error' in parsed) {
+            return accept === 'json'
+                ? c.json({ __outcome: 'error', message: parsed.error }, parsed.status)
+                : c.text(parsed.error, parsed.status);
+        }
+        const { module, action, payload } = parsed;
+        const urlPath = new URL(c.req.url).pathname;
+        const map = await resolverByPath(urlPath);
+        const entry = map.get(action);
+        if (!entry || entry.moduleKey !== module) {
+            const msg = `Action '${action}' not found on '${urlPath}'`;
+            return accept === 'json'
+                ? c.json({ __outcome: 'error', message: msg }, 404)
+                : c.text(msg, 404);
+        }
+        const { fn, use: actionUse, timeoutMs } = entry;
+        const resolvedTimeoutMs = timeoutMs !== undefined ? timeoutMs : defaultTimeoutMs;
+        const timeoutSignal = resolvedTimeoutMs === false
+            ? undefined
+            : AbortSignal.timeout(resolvedTimeoutMs);
+        const signal = timeoutSignal
+            ? AbortSignal.any([c.req.raw.signal, timeoutSignal])
+            : c.req.raw.signal;
+        const actionCtx = { c, signal };
+        // Chain order: app-level (outermost) -> page-level (from the page's
+        // `.server.ts` and ancestor layouts' pageUse arrays) -> action-level (from
+        // defineAction's `use` option). Outer middleware runs first on the way in,
+        // last on the way out, matching the convention every middleware system
+        // users have seen (Hono, Express, Koa).
+        const rootUse = appConfig?.use ?? [];
+        const pageUse = (await resolvePageUseByPath?.(urlPath)) ?? [];
+        const fullUse = [...rootUse, ...pageUse, ...actionUse];
+        const { middleware: allMiddleware, observers } = partitionUse(fullUse);
+        const serverMw = allMiddleware.filter((m) => m.runs === 'server');
+        const ctx = {
+            scope: 'action',
+            c,
+            signal,
+            module,
+            action,
+            payload,
+        };
+        let resolution;
+        let streamingResult;
+        try {
+            const value = await runRequestScope(async () => {
+                const dispatch = await dispatchServer({
+                    middleware: serverMw,
+                    ctx,
+                    inner: async () => {
+                        const inner = await fn(actionCtx, payload);
+                        // Normalize return-style outcomes to throw-style so the catch
+                        // path handles all outcomes uniformly.
+                        if (isOutcome(inner))
+                            throw inner;
+                        return inner;
+                    },
+                });
+                if (dispatch.kind === 'outcome')
+                    throw dispatch.outcome;
+                return dispatch.value;
+            });
+            if (isAsyncGenerator(value) || value instanceof ReadableStream) {
+                streamingResult = value;
+                if (accept !== 'event-stream') {
+                    const message = 'Streaming actions require Accept: text/event-stream';
+                    return accept === 'json'
+                        ? c.json({ __outcome: 'error', message }, 405)
+                        : c.text(message, 405);
+                }
+                resolution = { kind: 'success', data: undefined };
+            }
+            else {
+                resolution = { kind: 'success', data: value };
+            }
+        }
+        catch (err) {
+            if (isOutcome(err)) {
+                resolution = { kind: 'outcome', outcome: err };
+            }
+            else if (timeoutSignal?.aborted &&
+                timeoutSignal.reason instanceof DOMException &&
+                timeoutSignal.reason.name === 'TimeoutError' &&
+                typeof resolvedTimeoutMs === 'number') {
+                resolution = {
+                    kind: 'outcome',
+                    outcome: timeoutOutcome(resolvedTimeoutMs),
+                };
+            }
+            else {
+                onError?.(err, { module, action });
+                resolution = { kind: 'error', message: 'Action failed' };
+            }
+        }
+        // Streaming success: hand off to SSE responders.
+        if (streamingResult) {
+            const sseOpts = {
+                observers,
+                observerCtx: ctx,
+                signal: timeoutSignal,
+                timeoutMs: typeof resolvedTimeoutMs === 'number' ? resolvedTimeoutMs : undefined,
+            };
+            if (isAsyncGenerator(streamingResult)) {
+                return sseGeneratorResponse(c, streamingResult, {
+                    ...sseOpts,
+                    emitResult: true,
+                });
+            }
+            if (streamingResult instanceof ReadableStream) {
+                return sseReadableStreamResponse(c, streamingResult, sseOpts);
+            }
+        }
+        // JSON path: serialize the resolution into the uniform envelope.
+        if (accept === 'json') {
+            const env = serializeActionOutcome(resolution);
+            if (env.headers) {
+                for (const [k, v] of Object.entries(env.headers))
+                    c.header(k, v);
+            }
+            return c.json(env.body, env.status);
+        }
+        // HTML / PE path.
+        // Redirect: issue a real HTTP redirect so the browser follows it.
+        if (resolution.kind === 'outcome' &&
+            resolution.outcome.__outcome === 'redirect') {
+            const { to, status, headers } = resolution.outcome;
+            if (headers) {
+                for (const [k, v] of Object.entries(headers))
+                    c.header(k, v);
+            }
+            return c.redirect(to, status);
+        }
+        // Success: POST-Redirect-GET pattern. Auto 303 to the same URL so the
+        // browser re-GETs the page and loaders run fresh.
+        if (resolution.kind === 'success') {
+            return c.redirect(urlPath, 303);
+        }
+        // Timeout: plain text, no re-render needed.
+        if (resolution.kind === 'outcome' &&
+            resolution.outcome.__outcome === 'timeout') {
+            return c.text(`Action timed out after ${resolution.outcome.timeoutMs}ms`, 504);
+        }
+        // Deny or unexpected error: re-render the page with the resolution
+        // injected into the request scope so useActionResult() reads it.
+        return await runRequestScope(async () => {
+            setActionResultSlot({
+                module,
+                action,
+                resolution,
+                submittedPayload: payload,
+            });
+            const node = resolvePageNode(urlPath);
+            if (!node) {
+                if (resolution.kind === 'outcome' &&
+                    resolution.outcome.__outcome === 'deny') {
+                    return c.text(resolution.outcome.message, resolution.outcome.status);
+                }
+                return c.text('Action failed', 500);
+            }
+            const rendered = await renderPage(c, node, { appConfig });
+            if (resolution.kind === 'outcome' &&
+                resolution.outcome.__outcome === 'deny') {
+                return new Response(rendered.body, {
+                    status: resolution.outcome.status,
+                    headers: rendered.headers,
+                });
+            }
+            return new Response(rendered.body, {
+                status: 500,
+                headers: rendered.headers,
+            });
+        });
+    };
+}

package/dist/server/page-action-resolvers.d.ts

@@ -0,0 +1,28 @@
+import type { ServerRoute } from '../iso/index';
+type ActionFn = (ctx: unknown, payload: unknown) => Promise<unknown>;
+export type ActionEntry = {
+    fn: ActionFn;
+    use: ReadonlyArray<unknown>;
+    timeoutMs?: number | false;
+    moduleKey: string;
+};
+/**
+ * Build action resolvers keyed by route path and by module key. Each
+ * ServerRoute contributes its own serverActions and its ancestors' serverActions
+ * to the merged map for that path. Ancestor entries are written first so that
+ * a page-level action shadows a same-named layout action when names collide.
+ *
+ * Lazy semantics: the first call triggers loading all server modules. The result
+ * is cached for the process lifetime (unless dev=true, which rebuilds on every
+ * call so edits take effect without restarting the server).
+ *
+ * NOTE: framework-private. Intended consumer is the generated server entry and
+ * pageActionHandler.
+ */
+export declare function makePageActionResolvers(serverRoutes: ReadonlyArray<ServerRoute>, options?: {
+    dev?: boolean;
+}): {
+    byPath: (path: string) => Promise<Map<string, ActionEntry>>;
+    byModuleKey: (moduleKey: string, actionName: string) => Promise<ActionEntry | undefined>;
+};
+export {};