@rivetjs/router 0.0.0-stage → 0.1.0-alpha.0

package/server/inline-styles.js

@@ -0,0 +1,28 @@
+// Per-page stylesheet inlining (`rivetRouter({ inlineStylesheets })`): which of a page's stylesheet URLs the shell
+// writes as `<style>` (`DocumentInput.inlineStyles`), from the client build's `.vite/rivet-inline-css.json`.
+/**
+ * The subset of `styles` (URL → CSS) a page writes inline. `auto`: every listed sheet when their brotli total is at
+ * most `maxTotalBrotli` (one render-blocking round trip less: all of the page's sheets arrive with the HTML), else
+ * each listed sheet of at most `limit` raw bytes. Results are cached per stylesheet list (bounded by the routes).
+ */
+export function inlineStylesFor(manifest) {
+    const cache = new Map();
+    const { sheets } = manifest;
+    return (styles) => {
+        const key = styles.join("\n");
+        if (cache.has(key))
+            return cache.get(key);
+        const listed = styles.filter((href) => Object.hasOwn(sheets, href));
+        let total = 0;
+        for (const href of listed)
+            total += sheets[href].br;
+        const all = manifest.mode === "always" || total <= manifest.maxTotalBrotli;
+        const out = {};
+        for (const href of listed)
+            if (all || sheets[href].bytes <= manifest.limit)
+                out[href] = sheets[href].css;
+        const result = Object.keys(out).length ? out : undefined;
+        cache.set(key, result);
+        return result;
+    };
+}

package/server/module.d.ts

@@ -0,0 +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.
+ */
+export declare function serverExports(module: Record<string, unknown> | undefined, legacy: boolean, file?: string): 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).
+ */
+export declare function loadServer(load: (() => Promise<unknown>) | undefined): Promise<ServerModule | undefined>;

package/server/module.js

@@ -0,0 +1,78 @@
+/** In-file name → `ServerModule` key. */
+const RENAMED = {
+    serverLoad: "load",
+    serverGuard: "guard",
+    serverActions: "actions",
+    serverEntries: "entries",
+    serverHeaders: "headers",
+};
+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();
+/**
+ * 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.
+ */
+export function serverExports(module, legacy, file = "route module") {
+    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)
+            continue;
+        if (legacy && module[key] !== undefined)
+            throw new Error(`${file}: exports both \`${key}\` and \`${name}\`; keep \`${name}\``);
+        out[key] = module[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];
+    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.
+ */
+const merges = new WeakMap();
+/** Merge a route module's in-file server exports with its sibling `*.server.ts`. */
+export function mergeServer(inline, sibling, files = ["page", "sibling"]) {
+    // Per (inline, sibling) module pair: a hot edit brings new module objects, hence a new merge.
+    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]);
+    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()));
+    bySibling.set(sibling, merged);
+    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).
+ */
+export async function loadServer(load) {
+    const module = (await load?.());
+    if (!module)
+        return undefined;
+    return normalized.has(module) ? module : serverExports(module, true, "server module");
+}

package/server/render.d.ts

@@ -0,0 +1,94 @@
+import { type ServerValue } from "@rivetjs/runtime/server";
+import { type ResumeManifest } from "@rivetjs/runtime/server-resume";
+import type { Head } from "../shared/data.js";
+import type { HeadManaged } from "../shared/head.js";
+export { headTags, htmlAttributes, bodyAttributes, type HeadTagOptions, type HeadManaged } from "../shared/head.js";
+/** Document around the app. `start` ends inside the app container; `end` closes it. */
+export interface DocumentParts {
+    start: string;
+    end: string;
+}
+/** What a document shell receives: head, nonce, URL, status and stylesheets. */
+export interface DocumentInput {
+    readonly head: Head | undefined;
+    readonly nonce: string | undefined;
+    readonly url: URL;
+    readonly status: number;
+    /** Stylesheet URLs to link (Vite manifest CSS in production, source paths in dev): global, then the route's. */
+    readonly styles: readonly string[];
+    /** Stylesheets of `styles` written as `<style>` (URL → CSS; `rivetRouter({ inlineStylesheets })`): `headTags` reads it. */
+    readonly inlineStyles?: Readonly<Record<string, string>>;
+    /** Request locale (i18n `locals.locale`); shells write `<html lang dir>` from it. */
+    readonly locale?: string;
+    readonly dir?: "ltr" | "rtl";
+    /** Head tags are client-managed (`@rivetjs/kit`): shells pass the input to `headTags(head, input)`. */
+    readonly managed?: HeadManaged;
+}
+/** Renders the HTML document around a page. */
+export type DocumentShell = (input: DocumentInput) => DocumentParts;
+/** Options of `renderPage()`. */
+export interface RenderPageOptions {
+    /** Resume manifest (production client build). Without it the page renders without resumability. */
+    manifest?: ResumeManifest;
+    document: DocumentShell;
+    /** Out-of-order streaming for pending `Async` boundaries; `deadline` ms hands the rest to the browser. */
+    stream?: {
+        deadline?: number;
+    };
+    /**
+     * Preload planner (`renderResumable` `preload`): `background` byte budget of idle-time visible prefetch; `lean`: nothing
+     * before an interaction; `ahead`: bridge D-lean pages keep the runtime fetch-ahead.
+     */
+    preload?: {
+        background?: number;
+        lean?: boolean;
+        ahead?: boolean;
+    };
+    signal?: AbortSignal;
+    nonce?: string;
+    /**
+     * Failures after the response started (status already sent): this reports; a returned digest goes
+     * into the failure marker. The document then ends cleanly: a nonce'd script dispatching
+     * `rivet:resume-error` (`detail: { phase: "render", digest, error }`) and the shell's `end`.
+     */
+    onError?: (error: unknown) => string | void;
+    /** Markup written right before and after the app (dev: client mount container, data, scripts). */
+    around?: {
+        start: string;
+        end: string;
+    };
+    /** Locale variant index of translated templates (i18n; default 0). */
+    variant?: number;
+    /**
+     * Head hold (`@rivetjs/kit` components): app output is buffered until the shell has rendered, then
+     * the document starts with `head()` (route exports merged with what components pushed).
+     */
+    hold?: {
+        head(): Head | undefined;
+    };
+    /**
+     * Dev check (`AppConfig.devResume` mode `"check"`): the recorder runs, so its errors surface, but the
+     * page's root state and loader are cut (the browser client-renders). Not with `stream`.
+     */
+    discardState?: boolean;
+}
+/** Mid-stream failure marker: tells the page (and monitoring) the document is incomplete. */
+export declare function failureMarker(nonce: string | undefined, digest: string | undefined): string;
+/**
+ * Render `factory` between the document parts as a streamed UTF-8 body. Writes respect the
+ * consumer's pace: the renderer waits while the stream's queue is full. Always a `Response`: a
+ * failure before any byte left errors the body (`renderDocument` rejects instead).
+ */
+export declare function renderPage(factory: () => ServerValue, input: DocumentInput, options: RenderPageOptions, init: {
+    status: number;
+    headers: Headers;
+}): Response;
+/**
+ * `renderPage`, but the `Response` is created once the first body bytes are ready (or the render
+ * ended): a failure before that throws / rejects, so the caller can answer with an error page and
+ * status instead of a 200 with a broken body. A synchronous page answers synchronously.
+ */
+export declare function renderDocument(factory: () => ServerValue, input: DocumentInput, options: RenderPageOptions, init: {
+    status: number;
+    headers: Headers;
+}): Response | Promise<Response>;