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

package/server/index.js

@@ -0,0 +1,6 @@
+// Server entry: request handler, page rendering and app assembly (web-standard APIs only).
+export * from "./handler.js";
+export { strictCSP } from "./strict-csp.js";
+export { createApp, mergeHeads } from "./app.js";
+export { renderPage, renderDocument, failureMarker, headTags, } from "./render.js";
+export { serverExports, mergeServer, loadServer } from "./module.js";

package/server/inline-styles.d.ts

@@ -0,0 +1,21 @@
+/** `.vite/rivet-inline-css.json`: the sheets that may be inlined and the rule the build was configured with. */
+export interface InlineStyleManifest {
+    /** `"always"`: every listed sheet; `"auto"`: the per-page brotli total, else the per-sheet limit. */
+    readonly mode: "auto" | "always";
+    /** `auto`: all of a page's listed sheets go inline when their brotli sizes add up to at most this (bytes). */
+    readonly maxTotalBrotli: number;
+    /** `auto` fallback: a listed sheet of at most this many bytes (raw CSS) goes inline on its own. */
+    readonly limit: number;
+    /** Stylesheet URL → its CSS, its UTF-8 size and its brotli size (bytes). Sheets with relative references are never listed. */
+    readonly sheets: Readonly<Record<string, {
+        readonly css: string;
+        readonly bytes: number;
+        readonly br: number;
+    }>>;
+}
+/**
+ * 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 declare function inlineStylesFor(manifest: InlineStyleManifest): (styles: readonly string[]) => Readonly<Record<string, string>> | undefined;

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 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, 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 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<ServerModule>) | undefined): Promise<ServerModule> | undefined;

package/server/module.js

@@ -0,0 +1,96 @@
+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 cache = new WeakMap();
+const kindOf = (value) => typeof value === "function" || (typeof value === "object" && value !== null) ? value[SERVER_EXPORT] : undefined;
+/**
+ * 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, file = "route module", server = false) {
+    if (!module)
+        return {};
+    const cached = cache.get(module);
+    if (cached)
+        return cached;
+    const out = {};
+    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 (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;
+    }
+    if (module.prerender !== undefined)
+        out.prerender = module.prerender;
+    if (module.csrf !== undefined)
+        out.csrf = module.csrf;
+    const result = out;
+    cache.set(module, 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 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`. */
+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, 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 };
+    let bySibling = merges.get(inline);
+    if (!bySibling)
+        merges.set(inline, (bySibling = new WeakMap()));
+    bySibling.set(sibling, merged);
+    return merged;
+}
+/**
+ * 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 function loadServer(load) {
+    return load?.();
+}

package/server/render.d.ts

@@ -0,0 +1,96 @@
+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;
+    /** 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;
+/**
+ * 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>;