hono-preact 0.1.0 → 0.2.0

package/dist/iso/outcomes.js

@@ -0,0 +1,56 @@
+export function redirect(input) {
+    if (typeof input === 'string') {
+        return {
+            __outcome: 'redirect',
+            to: input,
+            status: 302,
+            headers: undefined,
+        };
+    }
+    return {
+        __outcome: 'redirect',
+        to: input.to,
+        status: input.status ?? 302,
+        headers: input.headers,
+    };
+}
+export function deny(a, b) {
+    // `JSON.stringify` drops `undefined` properties, so a deny outcome with no
+    // message would arrive at the client without a `message` field and the
+    // client decoders would fall back to a generic "Loader/Action failed with
+    // status N" string. Default to a status-aware message at construction time
+    // so the wire envelope always carries something useful. Callers can still
+    // pass a richer message; defense-in-depth on the client side fills in a
+    // similar fallback if a hand-rolled envelope ships without `message`.
+    if (typeof a === 'object') {
+        return {
+            __outcome: 'deny',
+            status: a.status,
+            message: a.message ?? `Request denied (${a.status})`,
+            headers: a.headers,
+        };
+    }
+    return {
+        __outcome: 'deny',
+        status: a,
+        message: b ?? `Request denied (${a})`,
+        headers: undefined,
+    };
+}
+export function isOutcome(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('__outcome' in value))
+        return false;
+    const tag = value.__outcome;
+    return tag === 'redirect' || tag === 'deny' || tag === 'render';
+}
+export function isRedirect(value) {
+    return isOutcome(value) && value.__outcome === 'redirect';
+}
+export function isDeny(value) {
+    return isOutcome(value) && value.__outcome === 'deny';
+}
+export function isRender(value) {
+    return isOutcome(value) && value.__outcome === 'render';
+}

package/dist/iso/page-only.d.ts

@@ -0,0 +1,5 @@
+import type { FunctionComponent } from 'preact';
+import type { RenderOutcome } from './outcomes.js';
+export { redirect, deny, isOutcome, isRedirect, isDeny, isRender, } from './outcomes.js';
+export type { Outcome, RedirectOutcome, DenyOutcome, RenderOutcome, RedirectStatusCode, ErrorStatusCode, } from './outcomes.js';
+export declare function render(Component: FunctionComponent): RenderOutcome;

package/dist/iso/page-only.js

@@ -0,0 +1,20 @@
+// @hono-preact/iso/page -- page-scope outcome kitchen sink.
+//
+// This subpath bundles every outcome a page-scope server middleware
+// reaches for in one import. `render` is the page-scope-only constructor
+// (loaders/actions can't replace the page tree), so it lives here and
+// nowhere else; the docs steer users at this subpath when they need it.
+// `redirect`/`deny` and the predicates (`isOutcome`/`isRedirect`/`isDeny`
+// /`isRender`) are re-exported here too so a page-scope file can write a
+// single `import { redirect, deny, render } from 'hono-preact/page'` line.
+//
+// Canonical export location for the cross-scope symbols is `./outcomes.js`.
+// Both this subpath and `./index.js` re-export from there; nothing here
+// hides surface. The predicates are scope-agnostic, so `index.ts` is their
+// primary home for consumers that don't already need the page-scope
+// subpath; the predicates are duplicated here only for the kitchen-sink
+// import path.
+export { redirect, deny, isOutcome, isRedirect, isDeny, isRender, } from './outcomes.js';
+export function render(Component) {
+    return { __outcome: 'render', Component };
+}

package/dist/iso/page.d.ts

@@ -1,6 +1,6 @@
 import type { ComponentChildren, ComponentType, JSX } from 'preact';
 import type { RouteHook } from 'preact-iso';
-import type { GuardFn } from './guard.js';
+import type { PageUse } from './internal/use-types.js';
 export type WrapperProps = {
     id: string;
     'data-loader': string;
@@ -8,9 +8,9 @@ export type WrapperProps = {
 };
 export type PageProps = {
     location: RouteHook;
-    guards?: GuardFn[];
+    use?: PageUse;
     errorFallback?: JSX.Element | ((error: Error, reset: () => void) => JSX.Element);
     Wrapper?: ComponentType<WrapperProps>;
     children: ComponentChildren;
 };
-export declare function Page({ location, guards, errorFallback, Wrapper, children, }: PageProps): JSX.Element;
+export declare function Page({ location, use, errorFallback, Wrapper, children, }: PageProps): JSX.Element;

package/dist/iso/page.js

@@ -1,10 +1,10 @@
 import { jsx as _jsx } from "preact/jsx-runtime";
 import { useId } from 'preact/hooks';
-import { Guards } from './internal/guards.js';
+import { PageMiddlewareHost } from './internal/page-middleware-host.js';
 import { RouteBoundary } from './internal/route-boundary.js';
 const DefaultWrapper = (props) => (_jsx("section", { ...props }));
-export function Page({ location, guards, errorFallback, Wrapper, children, }) {
+export function Page({ location, use, errorFallback, Wrapper, children, }) {
     const id = useId();
     const W = Wrapper ?? DefaultWrapper;
-    return (_jsx(RouteBoundary, { errorFallback: errorFallback, children: _jsx(Guards, { guards: guards, location: location, children: _jsx(W, { id: id, "data-loader": "null", children: children }) }) }));
+    return (_jsx(RouteBoundary, { errorFallback: errorFallback, children: _jsx(PageMiddlewareHost, { use: use, location: location, children: _jsx(W, { id: id, "data-loader": "null", children: children }) }) }));
 }

package/dist/page.d.ts

@@ -0,0 +1 @@
+export * from './iso/page-only';

package/dist/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAOA,cAAc,uBAAuB,CAAC"}

package/dist/page.js

@@ -0,0 +1,8 @@
+// hono-preact/page -- page-scope outcome kitchen sink (umbrella re-export).
+//
+// Forwards to @hono-preact/iso/page so consumers using the published
+// umbrella can write `import { redirect, deny, render } from 'hono-preact/page'`
+// exactly as the docs show. The iso subpath is where the constructors and
+// predicates actually live; this file exists so the umbrella's exports map
+// matches the consolidated subpath after `scripts/consolidate.mjs` runs.
+export * from './iso/page-only.js';

package/dist/server/actions-handler.d.ts

@@ -1,9 +1,8 @@
 import type { MiddlewareHandler } from 'hono';
-import { type ActionGuardFn } from '../iso/index';
+import { type AppConfig } from '../iso/index';
 type GlobModule = {
     __moduleKey?: unknown;
     serverActions?: Record<string, unknown>;
-    actionGuards?: ActionGuardFn[];
     [key: string]: unknown;
 };
 type LazyGlob = Record<string, () => Promise<unknown>>;
@@ -19,15 +18,30 @@ export interface ActionsHandlerOptions {
      */
     dev?: boolean;
     /**
-     * Called for every error an action throws (other than `ActionGuardError`,
-     * which is treated as a structured response). Use it to hook into your
-     * observability stack (Sentry, console, etc.). The handler still
-     * responds with a sanitized 500; the hook is purely a side channel.
+     * Called for every error an action throws (other than an outcome thrown
+     * by middleware, which is translated to its wire shape). Use it to hook
+     * into your observability stack (Sentry, console, etc.). The handler
+     * still responds with a sanitized 500; the hook is purely a side channel.
      */
     onError?: (err: unknown, ctx: {
         module: string;
         action: string;
     }) => void;
+    /**
+     * Root layer of the middleware chain. The framework's generated server
+     * entry threads the user's `defineApp({ use })` result here. Each action
+     * request composes the chain as
+     * `[...appConfig.use, ...resolvePageUse(module), ...action.use]`.
+     */
+    appConfig?: AppConfig;
+    /**
+     * Per-page layer lookup keyed by the action's owning module key (since an
+     * action always belongs unambiguously to one page module). Returns the
+     * `use` array declared on the matching page's `.server.*` module (as
+     * `export const pageUse = [...]`). May be sync or async; the handler
+     * awaits the result either way. Default returns an empty array.
+     */
+    resolvePageUse?: (moduleKey: string) => ReadonlyArray<unknown> | Promise<ReadonlyArray<unknown>>;
 }
 export declare function actionsHandler(glob: LazyGlob | EagerGlob, opts?: ActionsHandlerOptions): MiddlewareHandler;
 export {};

package/dist/server/actions-handler.js

@@ -1,5 +1,5 @@
-import { ActionGuardError, GuardRedirect, } from '../iso/index.js';
-import { runRequestScope } from '../iso/internal/index.js';
+import { isOutcome, } from '../iso/index.js';
+import { runRequestScope, dispatchServer, partitionUse, } from '../iso/internal.js';
 import { sseGeneratorResponse, sseReadableStreamResponse, isAsyncGenerator, } from './sse.js';
 async function buildActionsMap(glob) {
     const result = {};
@@ -11,39 +11,42 @@ async function buildActionsMap(glob) {
         if (typeof key === 'string' && mod.serverActions) {
             result[key] = {
                 actions: mod.serverActions,
-                guards: mod.actionGuards ?? [],
             };
         }
     }
     return result;
 }
-async function runActionGuards(guards, ctx) {
-    const run = async (index) => {
-        if (index >= guards.length)
-            return;
-        // Track whether the guard explicitly opted to pass control on. Without
-        // this check a guard that forgets `return next()` (or just `next()`)
-        // would silently fall through to the action body — the OPPOSITE of every
-        // other middleware system users have seen (Express, Hono, Koa: blocked
-        // by default; opt in to pass). Make ambiguous returns loud instead of
-        // silently insecure. To block, throw ActionGuardError. To pass, await
-        // (or return) next().
-        let nextCalled = false;
-        await guards[index](ctx, () => {
-            nextCalled = true;
-            return run(index + 1);
-        });
-        if (!nextCalled) {
-            throw new Error(`ActionGuard for '${ctx.module}.${ctx.action}' returned without ` +
-                `calling next() or throwing. Guards must either: (a) await/return ` +
-                `next() to pass control on, or (b) throw ActionGuardError to block. ` +
-                `Returning silently is ambiguous and would let the action run.`);
+function translateOutcomeForAction(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);
         }
-    };
-    await run(0);
+        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);
+    }
+    // render outcome should never reach the action RPC.
+    return c.json({
+        __outcome: 'error',
+        message: 'render outcome is page-scope only',
+    }, 500);
 }
 export function actionsHandler(glob, opts = {}) {
-    const { dev = false, onError } = opts;
+    const { dev = false, onError, appConfig, resolvePageUse } = opts;
     let cachedMapPromise = null;
     return async (c) => {
         const actionsMapPromise = dev
@@ -115,44 +118,77 @@ export function actionsHandler(glob, opts = {}) {
         if (!entry) {
             return c.json({ error: `Module '${module}' not found` }, 404);
         }
-        try {
-            await runActionGuards(entry.guards, { c, module, action, payload });
-        }
-        catch (err) {
-            if (err instanceof ActionGuardError) {
-                return c.json({ error: err.message }, err.status);
-            }
-            if (err instanceof GuardRedirect) {
-                return c.json({ __redirect: err.location });
-            }
-            throw err;
-        }
         const fn = entry.actions[action];
         if (typeof fn !== 'function') {
             return c.json({ error: `Action '${action}' not found in module '${module}'` }, 404);
         }
         const signal = c.req.raw.signal;
         const actionCtx = { c, signal };
+        // Chain ordering is outer -> inner: app-level middleware wraps every
+        // request, page-level wraps actions owned by that page, and per-action
+        // middleware (attached via defineAction(fn, { use })) 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). The action's owning page is unambiguous from `module`, so the
+        // page-layer lookup keys by module rather than by location path.
+        const rootUse = appConfig?.use ?? [];
+        const pageUse = (await resolvePageUse?.(module)) ?? [];
+        const actionUse = fn.use ?? [];
+        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 result;
         try {
-            result = await runRequestScope(() => fn(actionCtx, payload));
+            result = await runRequestScope(async () => {
+                const dispatch = await dispatchServer({
+                    middleware: serverMw,
+                    ctx,
+                    inner: async () => {
+                        const inner = await fn(actionCtx, payload);
+                        // An action 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 dispatch.outcome;
+                }
+                return dispatch.value;
+            });
         }
         catch (err) {
-            if (err instanceof ActionGuardError) {
-                return c.json({ error: err.message }, err.status);
-            }
-            if (err instanceof GuardRedirect) {
-                return c.json({ __redirect: err.location });
+            if (isOutcome(err)) {
+                return translateOutcomeForAction(c, err);
             }
             onError?.(err, { module, action });
             const message = dev && err instanceof Error ? err.message : 'Action failed';
             return c.json({ error: message }, 500);
         }
         if (isAsyncGenerator(result)) {
-            return sseGeneratorResponse(c, result, { emitResult: true });
+            return sseGeneratorResponse(c, result, {
+                emitResult: true,
+                observers,
+                observerCtx: ctx,
+            });
         }
         if (result instanceof ReadableStream) {
-            return sseReadableStreamResponse(c, result);
+            return sseReadableStreamResponse(c, result, {
+                observers,
+                observerCtx: ctx,
+            });
         }
         return c.json(result);
     };

package/dist/server/context.js

@@ -1,4 +1,4 @@
-import { HonoRequestContext } from '../iso/internal/index.js';
+import { HonoRequestContext } from '../iso/internal.js';
 import { useContext } from 'preact/hooks';
 export const HonoContext = HonoRequestContext;
 export function useHonoContext() {

package/dist/server/index.d.ts

@@ -2,4 +2,4 @@ export { HonoContext, useHonoContext } from './context.js';
 export { renderPage } from './render.js';
 export { actionsHandler } from './actions-handler.js';
 export { loadersHandler } from './loaders-handler.js';
-export { routeServerModules } from './route-server-modules.js';
+export { routeServerModules, makePageUseResolvers, } from './route-server-modules.js';

package/dist/server/index.js

@@ -2,4 +2,4 @@ export { HonoContext, useHonoContext } from './context.js';
 export { renderPage } from './render.js';
 export { actionsHandler } from './actions-handler.js';
 export { loadersHandler } from './loaders-handler.js';
-export { routeServerModules } from './route-server-modules.js';
+export { routeServerModules, makePageUseResolvers, } from './route-server-modules.js';

package/dist/server/loaders-handler.d.ts

@@ -1,4 +1,5 @@
 import type { MiddlewareHandler } from 'hono';
+import { type AppConfig } from '../iso/index';
 type GlobModule = {
     default?: unknown;
     __moduleKey?: unknown;
@@ -25,6 +26,21 @@ export interface LoadersHandlerOptions {
         module: string;
         loader: string;
     }) => void;
+    /**
+     * Root layer of the middleware chain. The framework's generated server
+     * entry threads the user's `defineApp({ use })` result here. Each loader
+     * request composes the chain as
+     * `[...appConfig.use, ...resolvePageUse(path), ...loader.use]`.
+     */
+    appConfig?: AppConfig;
+    /**
+     * Per-page layer lookup keyed by the matched route's location path.
+     * Returns the `use` array declared on the matching page's `.server.*`
+     * module (as `export const pageUse = [...]`). The lookup may be sync
+     * (an in-memory map) or async (loaded lazily on first request). The
+     * handler awaits the result either way. Default returns an empty array.
+     */
+    resolvePageUse?: (path: string) => ReadonlyArray<unknown> | Promise<ReadonlyArray<unknown>>;
 }
 export declare function loadersHandler(glob: LazyGlob | EagerGlob, opts?: LoadersHandlerOptions): MiddlewareHandler;
 export {};

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, } 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,14 @@ 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 ?? [] };
                 }
             }
         }
@@ -44,8 +46,37 @@ 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);
+    }
+    // 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 } = opts;
     let cachedMapPromise = null;
     return async (c) => {
         const loadersMapPromise = dev
@@ -82,28 +113,74 @@ 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;
+        // 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,
+                });
             }
             if (result instanceof ReadableStream) {
-                return sseReadableStreamResponse(c, result);
+                return sseReadableStreamResponse(c, result, {
+                    observers,
+                    observerCtx: ctx,
+                });
             }
             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);
             }
             onError?.(err, { module, loader: loaderName });
             // In production we never leak the loader's error message: it may

package/dist/server/render.d.ts

@@ -1,5 +1,7 @@
 import type { Context } from 'hono';
 import type { VNode } from 'preact';
+import { type AppConfig } from '../iso/index';
 export declare function renderPage(c: Context, node: VNode, options?: {
     defaultTitle?: string;
+    appConfig?: AppConfig;
 }): Promise<Response>;