@rivetjs/router 0.1.0-alpha.0 → 0.1.0-alpha.1

package/server/app.js

@@ -4,6 +4,7 @@ import { inlineStylesFor } from "./inline-styles.js";
 import { escapeJSON } from "@rivetjs/runtime/resume-format";
 import { createHandler, _digest, encodeData } from "./handler.js";
 import { renderDocument } from "./render.js";
+import { SHELL_BUILD } from "./shell-build.js";
 // `route-cache.ts` `ROUTE_CACHE` (same registered symbol; that module loads only with rules).
 const ROUTE_CACHE = Symbol.for("rivet.routeCache");
 // `early-hints.ts` `EARLY_HINTS` (same registered symbol; that module loads only with `earlyHints`).
@@ -72,6 +73,7 @@ export function createApp(config) {
     const document = config.document ?? entry.document;
     if (!document)
         throw new TypeError("createApp: no document shell (pass `document` or generate the entry with one)");
+    const moveScript = (to, nonce) => to === undefined ? "" : `<script${scriptAttrs(nonce)}>location.replace(${JSON.stringify(to).replace(/</g, "\\u003c")})</script>`;
     const scriptAttrs = (nonce) => (nonce !== undefined ? ` nonce="${nonce.replace(/[^\w+/=-]/g, "")}"` : "");
     // Dev pages: what the data endpoint would answer for this URL, so the client mount needs no request.
     const devAround = (page, status, nonce, locale, mode) => {
@@ -134,6 +136,9 @@ export function createApp(config) {
         const built = (i18n && i18n.manifests?.[locale ?? i18n.locales[0]]) || manifest;
         const devMode = built || !config.devResume ? undefined : typeof config.devResume.mode === "function" ? config.devResume.mode(locale) : config.devResume.mode;
         const pageManifest = built || config.devResume?.manifest;
+        // Dev check mode streams nothing: a shell fill's deferred data waits in place there (not an in-order read).
+        if (page.shell && devMode === "check")
+            page.shell.plain = true;
         const dir = locals?.dir === "rtl" || locals?.dir === "ltr" ? locals.dir : undefined;
         const exports = page.head ? (levels.get(page.head) ?? ranked([page.head], config.head)) : ranked([], config.head);
         // Root layout component entries stay in the browser (that layout never re-renders there).
@@ -174,7 +179,9 @@ export function createApp(config) {
                 : {}),
             ...(pageManifest ? { manifest: pageManifest } : {}),
             ...(variant ? { variant } : {}),
-            ...(config.stream ? { stream: config.stream } : {}),
+            // Deferred loaders: their boundaries stream out of order (shell first) even when the app set no `stream`.
+            // Shell routes (`routeRules` `shell`) always stream: the stored shell ends where the first boundary would stream.
+            ...(config.stream ? { stream: config.stream } : page.deferred || page.shell ? { stream: {} } : {}),
             ...(background !== undefined || lean || ahead
                 ? { preload: { ...(background !== undefined ? { background } : {}), ...(lean ? { lean } : {}), ...(ahead ? { ahead } : {}) } }
                 : {}),
@@ -188,6 +195,8 @@ export function createApp(config) {
                 return digest;
             },
             ...(config.devScripts && !built ? { around: devAround(page, status, nonce, locale, devMode) } : {}),
+            // Deferred loaders' redirects (status already sent): the browser navigates at the document's end.
+            ...(page.moved ? { epilogue: () => moveScript(page.moved(), nonce) } : {}),
             ...(devMode === "check" ? { discardState: true } : {}),
         }, { status, headers });
         return withCache
@@ -253,11 +262,15 @@ export function createApp(config) {
         },
         render: (input) => respond({
             data: input.data,
-            url: input.url,
+            // Shell fills: a URL whose named query reads outside the rule's key are recorded (`shell-cache.ts`).
+            url: input.shell?.url ?? input.url,
             head: input.head,
             ...(input.action ? { action: input.action } : {}),
             ...(input.byURL ? { byURL: input.byURL } : {}),
             ...(input.deps ? { deps: input.deps } : {}),
+            ...(input.deferred ? { deferred: input.deferred } : {}),
+            ...(input.moved ? { moved: input.moved } : {}),
+            ...(input.shell ? { shell: input.shell } : {}),
         }, input.status, input.headers, input.nonce, input.request, input.locals, input.route.id),
         renderError: async (input) => respond({
             // The outermost layouts' data (error pages render inside the layouts that loaded).
@@ -270,10 +283,16 @@ export function createApp(config) {
     const given = config.routeRules ?? entry.routeRules;
     if (!given || !Object.keys(given).length)
         return app;
-    // Dev: headers only (a stored page would hide edits).
+    // Dev: headers only (a stored page would hide edits); `shell` rules probe (track reads, log why a shell would not be stored).
     const rules = dev
-        ? Object.fromEntries(Object.entries(given).map(([pattern, rule]) => [pattern, rule.headers ? { headers: rule.headers } : {}]))
+        ? Object.fromEntries(Object.entries(given).map(([pattern, rule]) => [
+            pattern,
+            { ...(rule.headers ? { headers: rule.headers } : {}), ...(rule.shell !== undefined ? { shell: devShell(rule) } : {}) },
+        ]))
         : given;
+    const shelled = Object.values(rules).some((rule) => rule.shell);
+    if (shelled && !SHELL_BUILD)
+        throw new TypeError("createApp: `shell` route rules need a build whose `rivetRouter({ routeRules })` has a `shell` rule (it bundles the shell cache)");
     // Route rules: their module loads at startup (pay-per-use); malformed rules reject there (unhandled: the process
     // fails like a synchronous throw would). Requests before it settles wait for it.
     const policy = {
@@ -282,11 +301,25 @@ export function createApp(config) {
         hash: config.csp === undefined ? {} : typeof config.csp === "object" ? config.csp : null,
     };
     let cached = null;
-    const loading = import("./route-cache.js").then(({ withRouteRules }) => (cached = withRouteRules(app, rules, policy, entry.base ?? "", config.routeCache)));
+    // Shell rules: the shell cache module loads with the rules module (pay-per-use: only apps with `shell` rules).
+    const loading = Promise.all([import("./route-cache.js"), SHELL_BUILD && shelled ? SHELL_BUILD() : undefined]).then(([{ withRouteRules }, shells]) => (cached = withRouteRules(app, rules, policy, entry.base ?? "", config.routeCache, shells, {
+        dev,
+        build: manifest?.runtime ?? "",
+    })));
     const handler = (request, context) => (cached ? cached(request, context) : loading.then((ready) => ready(request, context)));
     // The node adapter's fast path (a stored page before a Request is built), once the module loaded.
     Object.defineProperty(handler, ROUTE_CACHE, { get: () => (cached ? cached[ROUTE_CACHE] : undefined) });
     return handler;
+    // Dev shell rules: keys only (the probe never stores, so no times and no fixed origin).
+    function devShell(rule) {
+        if (rule.shell === false)
+            return false;
+        const own = typeof rule.shell === "object" ? rule.shell : {};
+        const cache = typeof rule.cache === "object" ? rule.cache : {};
+        const query = own.query ?? cache.query;
+        const varies = own.varies ?? cache.varies;
+        return { maxAge: 0, ...(query !== undefined ? { query } : {}), ...(varies ? { varies } : {}) };
+    }
     // Error pages without a settled locale: the app's resolver, else the URL's locale prefix.
     async function errorLocals(locals, request, url) {
         const i18n = config.i18n;

package/server/deferred.d.ts

@@ -0,0 +1,12 @@
+import type { RequestEvent } from "./handler.js";
+/**
+ * The `Deferred<T>` handle of a started deferred loader. Its only property (`then`) is non-enumerable: the resume encoder
+ * writes it as an empty object (a resumed page's layout data signal holds it; client navigations carry resolved values).
+ * Dev: a Proxy that throws `DeferredDataError` when code reads a field (`data.title`) instead of rendering the handle
+ * through a boundary.
+ */
+export declare function deferredHandle(promise: Promise<unknown>, dev: boolean): object;
+/** Start deferred loader `i` now (with the request); a rejection is the boundary's, never an unhandled one. */
+export declare function startDeferred(run: () => unknown): Promise<unknown>;
+/** A deferred loader's event view: reads like its loader view, but `setHeader(s)` / `cookies.set` / `cookies.delete` throw. */
+export declare function lateEvent(event: RequestEvent): RequestEvent;

package/server/deferred.js

@@ -0,0 +1,60 @@
+// One handle per deferred slot per request: a frozen object whose non-enumerable `then` follows the loader's promise, so
+// every await form works (`Async` / `resource` fetchers, `await data`, `Promise.all`). Ruling (PPR-T01): per request, not
+// spec D3's request-independent handle resolved against the render scope — that one failed `await data` (the
+// continuation runs outside the owner, the render scope is gone) and would need AsyncLocalStorage; shell-cache H-replay
+// (T3) re-runs the page with live handles anyway, H-holes (T6) must swap a retained handle for the hit's (frame swap).
+const DOCS = "https://rivetjs.severyn.pro/guides/routing/loading-data#deferred-loaders";
+// The only string keys a handle answers in dev: what promise / boundary / encoder / JSON code reads.
+const ALLOWED = new Set(["then", "toJSON", "constructor", "valueOf", "toString"]);
+const devGet = (target, key, receiver) => {
+    if (typeof key === "symbol" || ALLOWED.has(key))
+        return Reflect.get(target, key, receiver);
+    const error = new TypeError("Deferred loader data read synchronously (`data." +
+        key +
+        "`): `load(fn, { defer: true })` data is a Deferred handle — render it through `<Async load={() => data}>` or `resource(() => data)` (" +
+        DOCS +
+        ")");
+    error.name = "DeferredDataError";
+    throw error;
+};
+const DEV_TRAPS = { get: devGet };
+/**
+ * The `Deferred<T>` handle of a started deferred loader. Its only property (`then`) is non-enumerable: the resume encoder
+ * writes it as an empty object (a resumed page's layout data signal holds it; client navigations carry resolved values).
+ * Dev: a Proxy that throws `DeferredDataError` when code reads a field (`data.title`) instead of rendering the handle
+ * through a boundary.
+ */
+export function deferredHandle(promise, dev) {
+    const handle = Object.freeze(Object.defineProperty({}, "then", { value: (ok, fail) => promise.then(ok, fail) }));
+    return dev ? new Proxy(handle, DEV_TRAPS) : handle;
+}
+/** Start deferred loader `i` now (with the request); a rejection is the boundary's, never an unhandled one. */
+export function startDeferred(run) {
+    const promise = new Promise((resolve) => resolve(run()));
+    promise.catch(() => { });
+    return promise;
+}
+const late = (what) => () => {
+    throw new TypeError(`A deferred loader cannot ${what}: the response head is sent before it settles (use a non-deferred loader or a guard)`);
+};
+const lateCookies = (cookies) => ({
+    get: cookies.get,
+    getAll: cookies.getAll,
+    set: late("set cookies"),
+    delete: late("delete cookies"),
+});
+/** A deferred loader's event view: reads like its loader view, but `setHeader(s)` / `cookies.set` / `cookies.delete` throw. */
+export function lateEvent(event) {
+    return new Proxy(event, {
+        get(target, key) {
+            if (key === "setHeader")
+                return late("set headers");
+            if (key === "setHeaders")
+                return late("set headers");
+            if (key === "cookies")
+                return lateCookies(target.cookies);
+            const value = Reflect.get(target, key, target);
+            return value;
+        },
+    });
+}

package/server/handler.d.ts

@@ -63,9 +63,9 @@ export interface Platform {
 type Result = unknown;
 type Handler = (event: RequestEvent) => Response | undefined | void | Promise<Response | undefined | void>;
 /**
- * A route's or layout's server exports, normalized: in-file `serverLoad`… arrive here as `load`…
- * (sibling `*.server.ts` modules may still use the old names). `onRequest` and `on<Method>` request
- * handlers run outermost first before guards; a returned `Response` ends the request.
+ * A route's or layout's server exports, normalized by tag (`server/module.ts`): each key is the kind of
+ * the wrapper that made the export (`export const loader = load(…)` arrives as `load`). `onRequest` and
+ * `on<Method>` request handlers run outermost first before guards; a returned `Response` ends the request.
  */
 export interface ServerModule {
     onRequest?: Handler;
@@ -84,11 +84,6 @@ export interface ServerModule {
     csrf?: boolean;
     actions?: Record<string, (event: RequestEvent) => Result | Promise<Result>>;
     headers?(event: RequestEvent): HeadersInit | undefined;
-    GET?(event: RequestEvent): Response | Promise<Response>;
-    POST?(event: RequestEvent): Response | Promise<Response>;
-    PUT?(event: RequestEvent): Response | Promise<Response>;
-    PATCH?(event: RequestEvent): Response | Promise<Response>;
-    DELETE?(event: RequestEvent): Response | Promise<Response>;
 }
 type Load<T> = () => Promise<T>;
 /** One generated route-table entry. */
@@ -117,11 +112,47 @@ export interface RenderInput {
     readonly locals: Record<string, unknown>;
     /** Merged head (layouts → page) from `head` exports. */
     readonly head: Head | undefined;
+    /** Set when a `data` slot is a deferred loader's `Deferred` handle (`load(fn, { defer: true })`): the page streams. */
+    readonly deferred?: true;
+    /**
+     * A deferred loader's `redirect()` (same origin, or `{ external: true }`): its first target, read when the document
+     * ends — the status is long sent, so the page navigates there in the browser (`location.replace`).
+     */
+    readonly moved?: () => string | undefined;
+    /** @internal Route rule `shell` (`shell-cache.ts`): this render fills or replays a stored shell (always streams). */
+    readonly shell?: ShellPhase;
     /** Layouts (indices into `data`) whose loader read the request URL: their data follows every URL change. */
     readonly byURL?: readonly number[];
     /** Keys the loaders passed to `event.depends()` (index into `data`); absent when none called it. */
     readonly deps?: LoaderDeps;
 }
+/**
+ * @internal Route rule `shell` (`server/shell-cache.ts`): the route rules wrapper sets it on a document GET's Request
+ * (`SHELL`). After the guards and `headers()` the handler asks it how to load: a hit's stored shell data (the composed
+ * response already went out with the stored shell), a fill's read tracking, or nothing (render as usual).
+ */
+export interface ShellRequest {
+    begin(route: AppRoute, event: RequestEvent, headers: Headers): ShellPhase | undefined;
+}
+/** @internal One shell render (fill or hit replay). */
+export interface ShellPhase {
+    /** Hit: the fill's non-deferred loader results (those loaders are skipped) and URL / depends facts. */
+    readonly data?: readonly unknown[];
+    readonly byURL?: readonly number[];
+    readonly deps?: LoaderDeps;
+    /** Fill: a non-deferred loader's event view that records its request reads. */
+    event?(view: RequestEvent, index: number): RequestEvent;
+    /** Fill: the non-deferred loaders' results (deferred slots undefined), stored with the shell. */
+    loaded?(data: readonly unknown[], byURL: readonly number[], deps: LoaderDeps | undefined): void;
+    /** Fill: a deferred slot's handle (delivers only after the shell is out: in-order use is detected). */
+    handle?(promise: Promise<unknown>, dev: boolean): object;
+    /** Fill: the page's URL for the render (named query reads outside the key recorded). */
+    readonly url?: URL;
+    /** Set by `app.ts`: this render does not stream (dev `devResume` check mode), deferred data waits in place. */
+    plain?: boolean;
+}
+/** @internal Request property carrying a `ShellRequest` (`Symbol.for("rivet.shell")`). */
+export declare const SHELL: unique symbol;
 /** What the error renderer receives: request, matched route, status and a user-safe message. */
 export interface ErrorInput {
     readonly request: Request;
@@ -133,7 +164,7 @@ export interface ErrorInput {
     readonly message: string;
     readonly headers: Headers;
     readonly nonce: string | undefined;
-    /** The request's `locals` as guards/loaders left them (empty when no guard ran, e.g. unmatched URLs). */
+    /** The request's `locals` as guards/loaders left them (only the handler's seed, `context.locals`, when no guard ran, e.g. unmatched URLs). */
     readonly locals: Record<string, unknown>;
     /**
      * Data of the outermost layouts the error page renders inside (route data order): those whose guards
@@ -181,12 +212,25 @@ export interface ErrorInfo {
 }
 /** @internal Short random id tying a hidden 5xx message to its server log entry. */
 export declare const _digest: () => string;
-/** The app's web-standard request handler. */
-export type AppHandler = (request: Request, context?: {
+/** What the caller of the app handler passes with a request (adapters: `nonce`, `address`, `platform`). */
+export interface AppHandlerContext {
+    /** CSP nonce of this response (node adapter: fresh per request). */
     nonce?: string;
+    /** Client address (`event.platform.clientAddress`). */
     address?: string;
+    /** Adapter-provided request facts (`event.platform`). */
     platform?: Platform;
-}) => Promise<Response>;
+    /**
+     * Seeds `event.locals`: each request starts with a shallow copy, before any request handler, guard, loader or action
+     * runs (the caller's object is never changed). Only from the code that calls the handler (no adapter fills it from the
+     * request), e.g. a view model another server computed. Never sent to the browser unless a loader returns it. Requests
+     * that pass it bypass the route rules' page cache (their page depends on more than the URL). Client-navigation data
+     * requests (`?_rivet=data`) need the same seed.
+     */
+    locals?: Readonly<Record<string, unknown>>;
+}
+/** The app's web-standard request handler. */
+export type AppHandler = (request: Request, context?: AppHandlerContext) => Promise<Response>;
 /**
  * Encode a value with the resume table (Date/Map/Set/BigInt/undefined/cycles survive). With built-in entries (RegExp /
  * URLSearchParams / binary / errors) and a `builtins` chunk URL, `x` names it: the client imports it before decoding.

package/server/handler.js

@@ -11,6 +11,8 @@ import { crossSite, limitBody } from "./security.js";
 import { ABSOLUTE, unsafeTarget } from "../shared/redirect.js";
 import { slashPath, TRAILING_SLASH } from "../shared/slash.js";
 import { parseCookies } from "../shared/cookie.js";
+/** @internal Request property carrying a `ShellRequest` (`Symbol.for("rivet.shell")`). */
+export const SHELL = Symbol.for("rivet.shell");
 /** @internal Short random id tying a hidden 5xx message to its server log entry. */
 export const _digest = () => {
     const bytes = crypto.getRandomValues(new Uint8Array(5));
@@ -106,6 +108,9 @@ const seeOther = (failure) => {
     return out;
 };
 const NO_PLATFORM = Object.freeze({});
+/** `load(fn, { defer: true })` marker (`shared/server-exports.ts` `DEFER`). */
+const DEFER = Symbol.for("rivet.defer");
+let deferredModule;
 // `event.depends()` outside loaders.
 const noDeps = () => { };
 // Dev hint, once per layout: a layout loader that denies or redirects acts as access control, but
@@ -116,7 +121,7 @@ function accessHint(route, index, failure) {
     if (isHttpError(failure) && (failure.status === 401 || failure.status === 403 || isRedirect(failure)) && !hinted.has(layout)) {
         hinted.add(layout);
         console.warn(`[rivet] The loader of layout "${layout}" ${isRedirect(failure) ? "redirected" : "answered " + failure.status}: loaders are not access control. ` +
-            "Client navigations that keep this layout's data skip its loader, so pages below it would load anyway. Check access in `serverGuard` (guards always run).");
+            "Client navigations that keep this layout's data skip its loader, so pages below it would load anyway. Check access in a `guard(…)` export (guards always run).");
     }
     throw failure;
 }
@@ -205,7 +210,9 @@ export function createHandler(options) {
             url.search = withoutRivet(url.search);
         const headers = new Headers();
         const nonce = context.nonce;
-        const locals = {};
+        // Seeded by the caller (`context.locals`): a copy, so guards writing `locals` never reach the caller's object.
+        const seed = context.locals;
+        const locals = seed ? { ...seed } : {};
         const found = match(url);
         const route = found ? found.route.render(undefined, found) : undefined;
         const method = request.method === "HEAD" ? "GET" : request.method;
@@ -425,7 +432,7 @@ export function createHandler(options) {
             const allow = (options) => [
                 ...(route.page
                     ? ["GET, HEAD, POST", ...["PUT", "PATCH", "DELETE"].filter((m) => own?.[ON[m]])]
-                    : Object.keys(ON).filter((m) => own?.[ON[m]] || own?.[m]).map((m) => (m === "GET" ? "GET, HEAD" : m))),
+                    : Object.keys(ON).filter((m) => own?.[ON[m]]).map((m) => (m === "GET" ? "GET, HEAD" : m))),
                 ...(options ? ["OPTIONS"] : []),
             ].join(", ");
             if (route.page && method !== "GET" && method !== "OPTIONS" && action === undefined && !own?.[on]) {
@@ -481,8 +488,10 @@ export function createHandler(options) {
                 if (extra)
                     new Headers(extra).forEach((value, name) => headers.set(name, value));
             }
+            // Route rule `shell` (document GET of a page): a hit sends the stored shell now; a fill tracks request reads.
+            const shell = route.page && action === undefined && !data ? request[SHELL]?.begin(route, event, headers) : undefined;
             if (!route.page) {
-                const endpoint = own?.[on] ?? own?.[method];
+                const endpoint = own?.[on];
                 if (!endpoint) {
                     headers.set("allow", allow(false));
                     return fail(405, "Method not allowed");
@@ -491,7 +500,7 @@ export function createHandler(options) {
                 if (body.exceeded)
                     return fail(413, "Payload too large");
                 if (!(response instanceof Response))
-                    throw new Error(`${route.id}: ${own?.[on] ? on : method} must return a Response`);
+                    throw new Error(`${route.id}: ${on} must return a Response`);
                 return merge(response);
             }
             let performed;
@@ -568,13 +577,40 @@ export function createHandler(options) {
             }
             // Layout loaders that read the URL (or request) cannot be kept across URL changes: the client learns which.
             phase = "loader";
+            // Deferred loaders (`load(fn, { defer: true })`, document requests only; data requests await them like any loader):
+            // started now, not awaited; their slot is a `Deferred` handle (`deferred.ts`, imported on first use).
+            let lazy, promises, moved;
+            if (!data && modules.some((module) => module?.load && module.load[DEFER]))
+                lazy = await (deferredModule ??= import("./deferred.js"));
             const loaded = await Promise.all(modules.map((module, i) => {
                 if (skip.has(i) || !module?.load)
                     return (loads[i] = undefined);
-                const load = Promise.resolve(module.load(loaderEvent(i, i < route.layouts.length)));
+                if (lazy && module.load[DEFER]) {
+                    // Deferred loaders are the shell's holes: live on every request, never tracked.
+                    const view = lazy.lateEvent(loaderEvent(i, i < route.layouts.length));
+                    // Error pages await it like the other loaders (`errorLayouts`): they render after the failure, not streamed.
+                    const started = ((promises ??= [])[i] = loads[i] = lazy.startDeferred(() => module.load(view)));
+                    // A redirect after the head is out: a client redirect at the document's end (other origins need `external`).
+                    started.catch((failure) => {
+                        if (isHttpError(failure) &&
+                            isRedirect(failure) &&
+                            (failure.external || !ABSOLUTE.test(failure.location) || new URL(failure.location).origin === url.origin))
+                            moved ??= failure.location;
+                    });
+                    // The handle is a thenable: set after `Promise.all`, which would await it.
+                    return undefined;
+                }
+                // Shell hit: the stored shell's data (its loaders read no request input; the composed response is out).
+                if (shell?.data)
+                    return (loads[i] = undefined), shell.data[i];
+                const view = loaderEvent(i, i < route.layouts.length);
+                const load = Promise.resolve(module.load(shell?.event ? shell.event(view, i) : view));
                 // Dev: a layout loader used as access control is skipped for kept layouts (`_rivet_keep`).
                 return (loads[i] = dev && i < route.layouts.length ? load.catch((failure) => accessHint(route, i, failure)) : load);
             }));
+            shell?.loaded?.(loaded.slice(), [...byURL], depsOf().deps);
+            if (promises)
+                promises.forEach((promise, i) => (loaded[i] = shell?.handle ? shell.handle(promise, dev) : lazy.deferredHandle(promise, dev)));
             const head = await options.head?.(route, loaded, { params: found.params, url });
             if (data) {
                 if (!headers.has("cache-control"))
@@ -607,8 +643,10 @@ export function createHandler(options) {
                 action: performed,
                 locals: event.locals,
                 head,
-                byURL: byURL.size ? [...byURL] : NO_LAYOUTS,
-                ...depsOf(),
+                byURL: shell?.byURL ?? (byURL.size ? [...byURL] : NO_LAYOUTS),
+                ...(shell?.data ? (shell.deps ? { deps: shell.deps } : {}) : depsOf()),
+                ...(promises ? { deferred: true, moved: () => moved } : {}),
+                ...(shell ? { shell } : {}),
             });
         }
         catch (failure) {

package/server/index.d.ts

@@ -5,5 +5,5 @@ export { strictCSP } from "./strict-csp.js";
 export { createApp, mergeHeads, type AppConfig, type GeneratedEntry, type PageInput } from "./app.js";
 export { renderPage, renderDocument, failureMarker, headTags, type DocumentShell, type DocumentInput, type DocumentParts, type RenderPageOptions, } from "./render.js";
 export { serverExports, mergeServer, loadServer } from "./module.js";
-export type { CacheRule, RouteCacheOptions, RouteRule, RouteRules } from "./route-cache.js";
+export type { CacheRule, RouteCacheOptions, RouteRule, RouteRules, ShellRule } from "./route-cache.js";
 export type { EarlyHintsOptions } from "./early-hints.js";

package/server/module.d.ts

@@ -1,14 +1,14 @@
 import type { ServerModule } from "./handler.js";
 /**
- * Normalize one module's exports. `legacy`: a sibling `*.server.ts` (old names accepted; a module
- * exporting both `load` and `serverLoad` is an error). In-file (page/layout) modules use the new names
- * only: their `load`/`guard`… are ordinary exports.
+ * Normalize one module's exports by tag. `server`: a raw-loaded server module (sibling `*.server.ts`,
+ * plain `.ts` endpoint) — its former sibling names (`load`, `GET`…) are checked too. Errors (thrown at the
+ * first request that loads the module): two exports of one kind; an untagged export with a former magic name.
  */
-export declare function serverExports(module: Record<string, unknown> | undefined, legacy: boolean, file?: string): ServerModule;
+export declare function serverExports(module: Record<string, unknown> | undefined, file?: string, server?: boolean): ServerModule;
 /** Merge a route module's in-file server exports with its sibling `*.server.ts`. */
 export declare function mergeServer(inline: Record<string, unknown>, sibling: Record<string, unknown>, files?: readonly string[]): ServerModule;
 /**
- * Load and normalize a route table entry's server module. Generated loaders return in-file and merged
- * modules normalized, and sibling `*.server.ts` modules raw (old names accepted).
+ * Load a route table entry's server module. Generated loaders (`build/codegen.ts`) return it normalized
+ * (`serverExports` / `mergeServer`): `AppRoute.server` / `layouts` return `ServerModule`s.
  */
-export declare function loadServer(load: (() => Promise<unknown>) | undefined): Promise<ServerModule | undefined>;
+export declare function loadServer(load: (() => Promise<ServerModule>) | undefined): Promise<ServerModule> | undefined;

package/server/module.js

@@ -1,50 +1,72 @@
-/** In-file name → `ServerModule` key. */
-const RENAMED = {
+import { SERVER_EXPORT } from "../shared/server-exports.js";
+/** Former magic export names → the wrapper that replaces them (an untagged export with one is an error). */
+const MAGIC = {
     serverLoad: "load",
     serverGuard: "guard",
     serverActions: "actions",
     serverEntries: "entries",
     serverHeaders: "headers",
+    onRequest: "onRequest",
+    onGet: "onGet",
+    onPost: "onPost",
+    onPut: "onPut",
+    onPatch: "onPatch",
+    onDelete: "onDelete",
+    onOptions: "onOptions",
+};
+/** Former sibling `*.server.ts` names (raw-loaded server modules only). */
+const LEGACY = {
+    load: "load",
+    guard: "guard",
+    actions: "actions",
+    entries: "entries",
+    headers: "headers",
+    GET: "onGet",
+    POST: "onPost",
+    PUT: "onPut",
+    PATCH: "onPatch",
+    DELETE: "onDelete",
 };
-const KEPT = ["prerender", "csrf", "onRequest", "onGet", "onPost", "onPut", "onPatch", "onDelete", "onOptions"];
-/** Sibling-only names (migration; `rivet migrate server-exports` renames them). */
-const LEGACY = ["load", "guard", "actions", "entries", "headers", "GET", "POST", "PUT", "PATCH", "DELETE"];
 const cache = new WeakMap();
-const normalized = new WeakSet();
+const kindOf = (value) => typeof value === "function" || (typeof value === "object" && value !== null) ? value[SERVER_EXPORT] : undefined;
 /**
- * Normalize one module's exports. `legacy`: a sibling `*.server.ts` (old names accepted; a module
- * exporting both `load` and `serverLoad` is an error). In-file (page/layout) modules use the new names
- * only: their `load`/`guard`… are ordinary exports.
+ * Normalize one module's exports by tag. `server`: a raw-loaded server module (sibling `*.server.ts`,
+ * plain `.ts` endpoint) — its former sibling names (`load`, `GET`…) are checked too. Errors (thrown at the
+ * first request that loads the module): two exports of one kind; an untagged export with a former magic name.
  */
-export function serverExports(module, legacy, file = "route module") {
+export function serverExports(module, file = "route module", server = false) {
     if (!module)
         return {};
     const cached = cache.get(module);
     if (cached)
         return cached;
     const out = {};
-    for (const [name, key] of Object.entries(RENAMED)) {
-        if (module[name] === undefined)
+    const names = {};
+    for (const name of Object.keys(module)) {
+        const value = module[name];
+        const kind = kindOf(value);
+        if (kind === undefined) {
+            const wrapper = MAGIC[name] ?? (server ? LEGACY[name] : undefined);
+            if (wrapper !== undefined && value !== undefined)
+                throw new Error(`${file}: \`${name}\` is not a server export: wrap it — \`export const x = ${wrapper}(…)\` (\`${wrapper}\` is exported by @rivetjs/router)`);
             continue;
-        if (legacy && module[key] !== undefined)
-            throw new Error(`${file}: exports both \`${key}\` and \`${name}\`; keep \`${name}\``);
-        out[key] = module[name];
+        }
+        if (out[kind] !== undefined && out[kind] !== value)
+            throw new Error(`${file}: \`${names[kind]}\` and \`${name}\` are both \`${kind}(…)\`; keep one`);
+        out[kind] = value;
+        names[kind] = name;
     }
-    for (const name of KEPT)
-        if (module[name] !== undefined)
-            out[name] = module[name];
-    if (legacy)
-        for (const name of LEGACY)
-            if (module[name] !== undefined && out[name] === undefined)
-                out[name] = module[name];
+    if (module.prerender !== undefined)
+        out.prerender = module.prerender;
+    if (module.csrf !== undefined)
+        out.csrf = module.csrf;
     const result = out;
     cache.set(module, result);
-    normalized.add(result);
     return result;
 }
 /**
  * Merge a page/layout module's in-file server exports with its sibling `*.server.ts` (generated
- * loaders call this for routes that have both). One export defined in both is an error.
+ * loaders call this for routes that have both). One kind defined in both is an error.
  */
 const merges = new WeakMap();
 /** Merge a route module's in-file server exports with its sibling `*.server.ts`. */
@@ -53,13 +75,12 @@ export function mergeServer(inline, sibling, files = ["page", "sibling"]) {
     const cached = merges.get(inline)?.get(sibling);
     if (cached)
         return cached;
-    const a = serverExports(inline, false, files[0]);
-    const b = serverExports(sibling, true, files[1]);
+    const a = serverExports(inline, files[0]);
+    const b = serverExports(sibling, files[1], true);
     for (const key of Object.keys(b))
         if (key in a)
             throw new Error(`${files[0]} and ${files[1]} both define the route's \`${key}\`; keep one`);
     const merged = { ...b, ...a };
-    normalized.add(merged);
     let bySibling = merges.get(inline);
     if (!bySibling)
         merges.set(inline, (bySibling = new WeakMap()));
@@ -67,12 +88,9 @@ export function mergeServer(inline, sibling, files = ["page", "sibling"]) {
     return merged;
 }
 /**
- * Load and normalize a route table entry's server module. Generated loaders return in-file and merged
- * modules normalized, and sibling `*.server.ts` modules raw (old names accepted).
+ * Load a route table entry's server module. Generated loaders (`build/codegen.ts`) return it normalized
+ * (`serverExports` / `mergeServer`): `AppRoute.server` / `layouts` return `ServerModule`s.
  */
-export async function loadServer(load) {
-    const module = (await load?.());
-    if (!module)
-        return undefined;
-    return normalized.has(module) ? module : serverExports(module, true, "server module");
+export function loadServer(load) {
+    return load?.();
 }

package/server/render.d.ts

@@ -71,6 +71,8 @@ export interface RenderPageOptions {
      * page's root state and loader are cut (the browser client-renders). Not with `stream`.
      */
     discardState?: boolean;
+    /** Markup written after the app's output (and its streamed boundaries), before `around.end` (deferred loaders' client redirect). */
+    epilogue?: () => string;
 }
 /** Mid-stream failure marker: tells the page (and monitoring) the document is incomplete. */
 export declare function failureMarker(nonce: string | undefined, digest: string | undefined): string;

package/server/render.js

@@ -433,6 +433,9 @@ function stream(factory, input, options, init, deferred) {
                 await wait;
             }
             release();
+            const epilogue = options.epilogue?.();
+            if (epilogue && (wait = writer.write(epilogue)))
+                await wait;
             if (options.around && (wait = writer.write(options.around.end)))
                 await wait;
             if ((wait = writer.write(parts.end)))