@rangojs/router 0.0.0-experimental.0f44aca1

package/src/prerender/store.ts

@@ -0,0 +1,185 @@
+/**
+ * Prerender Store
+ *
+ * Reads pre-rendered segment data from the worker bundle at build time.
+ * The manifest module is lazily loaded via globalThis.__loadPrerenderManifestModule,
+ * a function injected into the RSC entry that returns the manifest module
+ * containing a key-to-specifier map and a `loadPrerenderAsset` function
+ * that anchors import() resolution relative to the manifest file.
+ */
+
+import type {
+  SerializedSegmentData,
+  SegmentHandleData,
+} from "../cache/types.js";
+
+export interface PrerenderEntry {
+  segments: SerializedSegmentData[];
+  handles: Record<string, SegmentHandleData>;
+}
+
+export interface PrerenderStore {
+  get(
+    routeName: string,
+    paramHash: string,
+    meta?: { pathname: string; isPassthroughRoute?: boolean },
+  ): PrerenderEntry | null | Promise<PrerenderEntry | null>;
+}
+
+export interface StaticEntry {
+  encoded: string;
+  handles: Record<string, unknown[]>;
+}
+
+export interface StaticStore {
+  get(handlerId: string): Promise<StaticEntry | null>;
+}
+
+interface PrerenderManifestModule {
+  default: Record<string, string>;
+  loadPrerenderAsset: (
+    specifier: string,
+  ) => Promise<{ default: PrerenderEntry }>;
+}
+
+declare global {
+  // Injected by closeBundle post-processing: lazy loader for the prerender
+  // manifest module. The module exports a key→specifier map and a
+  // loadPrerenderAsset function that anchors import() relative to the manifest.
+  // eslint-disable-next-line no-var
+  var __loadPrerenderManifestModule:
+    | (() => Promise<PrerenderManifestModule>)
+    | undefined;
+  // Injected by closeBundle post-processing: map of handlerId -> () => import("./assets/__st-*.js")
+  // Asset default export is either a string (no handles) or { encoded, handles } object.
+  // eslint-disable-next-line no-var
+  var __STATIC_MANIFEST:
+    | Record<string, () => Promise<{ default: string | StaticEntry }>>
+    | undefined;
+  // Injected by virtual module in dev mode for on-demand prerender
+  // eslint-disable-next-line no-var
+  var __PRERENDER_DEV_URL: string | undefined;
+}
+
+/**
+ * Create a dev-mode prerender store that fetches on-demand from the
+ * Vite dev server's /__rsc_prerender endpoint (runs in Node.js where
+ * node:fs works, unlike workerd).
+ */
+export function createDevPrerenderStore(devUrl: string): PrerenderStore {
+  return {
+    async get(routeName, paramHash, meta) {
+      if (!meta?.pathname) return null;
+      const isIntercept = paramHash.endsWith("/i");
+      let url = `${devUrl}/__rsc_prerender?pathname=${encodeURIComponent(meta.pathname)}&routeName=${encodeURIComponent(routeName)}`;
+      if (isIntercept) url += "&intercept=1";
+      if (meta.isPassthroughRoute) url += "&passthrough=1";
+      try {
+        const res = await fetch(url);
+        if (!res.ok) return null;
+        return res.json();
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Create a prerender store.
+ * Dev mode: on-demand fetch from Vite dev server (node:fs works there).
+ * Production: backed by globalThis.__loadPrerenderManifestModule which lazily
+ * loads the manifest module on first access.
+ * Returns null if no prerender data is available.
+ */
+export function createPrerenderStore(): PrerenderStore | null {
+  if (globalThis.__PRERENDER_DEV_URL) {
+    return createDevPrerenderStore(globalThis.__PRERENDER_DEV_URL);
+  }
+  if (!globalThis.__loadPrerenderManifestModule) return null;
+
+  const cache = new Map<string, Promise<PrerenderEntry | null>>();
+  let manifestModulePromise: Promise<PrerenderManifestModule | null> | null =
+    null;
+
+  function loadManifestModule(): Promise<PrerenderManifestModule | null> {
+    if (!manifestModulePromise) {
+      manifestModulePromise = globalThis.__loadPrerenderManifestModule!().catch(
+        () => null,
+      );
+    }
+    return manifestModulePromise;
+  }
+
+  return {
+    get(routeName: string, paramHash: string): Promise<PrerenderEntry | null> {
+      const key = `${routeName}/${paramHash}`;
+      const cached = cache.get(key);
+      if (cached) return cached;
+
+      const promise = loadManifestModule().then((mod) => {
+        if (!mod) return null;
+        const specifier = mod.default[key];
+        if (!specifier) return null;
+        return mod
+          .loadPrerenderAsset(specifier)
+          .then((asset) => asset.default)
+          .catch(() => null);
+      });
+      cache.set(key, promise);
+      return promise;
+    },
+  };
+}
+
+/**
+ * Load the prerender manifest index for test introspection.
+ * Returns the key→specifier map or null if unavailable.
+ */
+export async function loadPrerenderManifestIndex(): Promise<Record<
+  string,
+  string
+> | null> {
+  if (!globalThis.__loadPrerenderManifestModule) return null;
+  try {
+    const mod = await globalThis.__loadPrerenderManifestModule();
+    return mod.default;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a static segment store.
+ * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.
+ * Returns null if no static data is available (dev mode or no Static handlers).
+ */
+export function createStaticStore(): StaticStore | null {
+  const manifest = globalThis.__STATIC_MANIFEST;
+  if (!manifest || Object.keys(manifest).length === 0) return null;
+
+  const cache = new Map<string, Promise<StaticEntry | null>>();
+
+  return {
+    get(handlerId: string): Promise<StaticEntry | null> {
+      const cached = cache.get(handlerId);
+      if (cached) return cached;
+
+      const importFn = manifest[handlerId];
+      if (!importFn) return Promise.resolve(null);
+
+      const promise = importFn()
+        .then((mod) => {
+          const val = mod.default;
+          // Normalize: string-only (no handles) or { encoded, handles }
+          if (typeof val === "string") {
+            return { encoded: val, handles: {} } as StaticEntry;
+          }
+          return val as StaticEntry;
+        })
+        .catch(() => null);
+      cache.set(handlerId, promise);
+      return promise;
+    },
+  };
+}

package/src/prerender.ts

@@ -0,0 +1,463 @@
+/**
+ * Pre-render handler definition for build-time rendering of route segments.
+ *
+ * Prerender wraps a handler so that in production (phase 2)
+ * it can be pre-rendered at build time and served as a static Flight payload.
+ * In dev mode (phase 1), it behaves as a normal handler — the handler runs
+ * on every request just like a regular path() handler.
+ *
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin
+ * based on file path and export name. No manual naming required.
+ *
+ * @example
+ * ```ts
+ * // Static page — no params
+ * export const DocsPage = Prerender(async (ctx) => {
+ *   return <div>Documentation</div>;
+ * });
+ *
+ * // Dynamic page — params first, handler second
+ * export const DocsArticle = Prerender(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => {
+ *     return <div>{ctx.params.slug}</div>;
+ *   }
+ * );
+ * ```
+ */
+import type { ReactNode } from "react";
+import type {
+  Handler,
+  HandlerContext,
+  DefaultEnv,
+  ExtractParams,
+} from "./types.js";
+import type { Handle } from "./handle.js";
+import type { ContextVar } from "./context-var.js";
+import type { ReverseFunction } from "./reverse.js";
+import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
+import { isCachedFunction } from "./cache/taint.js";
+
+// -- Named route resolution types -------------------------------------------
+
+/**
+ * Reverse function for build contexts (BuildContext, StaticBuildContext, GetParamsContext).
+ * Global names get full autocomplete and param validation from the generated route map.
+ * Local `.name` calls are accepted but not validated (the include() scope is unknown
+ * at the type level).
+ */
+type BuildReverseFunction = [DefaultReverseRouteMap] extends [
+  Record<string, string>,
+]
+  ? // No generated route map — permissive fallback
+    (
+      name: string,
+      params?: Record<string, string>,
+      search?: Record<string, unknown>,
+    ) => string
+  : // Generated route map available — typed globals + permissive locals
+    ReverseFunction<DefaultReverseRouteMap> & {
+      (
+        name: `.${string}`,
+        params?: Record<string, string>,
+        search?: Record<string, unknown>,
+      ): string;
+    };
+
+/**
+ * Default route map for Prerender named route resolution.
+ * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
+ */
+type DefaultPrerenderRouteMap = keyof RSCRouter.GeneratedRouteMap extends never
+  ? {}
+  : RSCRouter.GeneratedRouteMap;
+
+/** Extract params from a route map entry (string pattern or { path } object). */
+type ExtractParamsFromEntry<TEntry> = TEntry extends string
+  ? ExtractParams<TEntry>
+  : TEntry extends { readonly path: infer P extends string }
+    ? ExtractParams<P>
+    : Record<string, string>;
+
+/**
+ * Resolve params from Prerender's type parameter.
+ * Accepts named routes (global or .local) and explicit param objects.
+ *
+ * Resolution order:
+ * 1. ".local" string → look up in TRouteMap
+ * 2. Global route name string → look up in DefaultPrerenderRouteMap
+ * 3. Record<string, any> object → use as-is (explicit params)
+ * 4. Fallback → {}
+ */
+type ResolvePrerenderParams<
+  T,
+  TRouteMap extends {} = DefaultPrerenderRouteMap,
+> = T extends `.${infer Local}`
+  ? Local extends keyof TRouteMap
+    ? ExtractParamsFromEntry<TRouteMap[Local]>
+    : Record<string, string>
+  : T extends keyof DefaultPrerenderRouteMap
+    ? ExtractParamsFromEntry<DefaultPrerenderRouteMap[T]>
+    : T extends Record<string, any>
+      ? T
+      : {};
+
+// -- Types ------------------------------------------------------------------
+
+export interface PrerenderOptions {
+  /**
+   * Keep handler in server bundle for live fallback (default: false).
+   * false: handler replaced with stub, source-only APIs excluded from bundle.
+   * true: handler stays in bundle, unknown params render live at request time.
+   */
+  passthrough?: boolean;
+
+  /**
+   * Maximum number of param sets to render in parallel (default: 1).
+   * Only applies to dynamic Prerender handlers with getParams().
+   * Set to higher values to speed up builds with many routes.
+   *
+   * @example
+   * ```typescript
+   * export const BlogPost = Prerender(
+   *   async () => allPosts.map(p => ({ slug: p.slug })),
+   *   async (ctx) => <PostPage slug={ctx.params.slug} />,
+   *   { concurrency: 4 },
+   * );
+   * ```
+   */
+  concurrency?: number;
+}
+
+/**
+ * Context passed to Prerender() handlers at build time.
+ * Has a synthetic URL from getParams, params, and pathname.
+ * No request, env, headers, cookies.
+ */
+export interface BuildContext<TParams> {
+  /** Params extracted from the route pattern (populated from getParams). */
+  params: TParams;
+
+  /** True during build-time pre-rendering, false during passthrough live render. */
+  build: true;
+
+  /** Read a variable set by getParams or a parent handler. */
+  get: {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+    (key: string): any;
+  };
+
+  /** Set a variable readable by child layouts and parallels. */
+  set: {
+    <T>(contextVar: ContextVar<T>, value: T): void;
+    (key: string, value: any): void;
+  };
+
+  /** Push handle data (frozen into pre-rendered output at build time). */
+  use: <T>(handle: Handle<T>) => (data: T) => void;
+
+  /** Synthetic URL built from pattern + params (no real request). */
+  url: URL;
+
+  /** Pathname portion of the synthetic URL. */
+  pathname: string;
+
+  /** URLSearchParams from the synthetic URL (always empty for prerender). */
+  searchParams: URLSearchParams;
+
+  /** Typed search params — always {} for prerender (no real query string). */
+  search: {};
+
+  /** URL generation by route name. */
+  reverse: BuildReverseFunction;
+
+  /**
+   * Signal that this param set should not produce a local prerender artifact.
+   * At runtime the handler runs live instead. Only valid on routes declared
+   * with `{ passthrough: true }`.
+   */
+  passthrough: () => PrerenderPassthroughResult;
+}
+
+/**
+ * Context passed to Static() handlers at build time.
+ * No URL, no params, no pathname — just renders content.
+ */
+export interface StaticBuildContext {
+  /** Always true for Static handlers at build time. */
+  build: true;
+
+  /** Read a variable (available for type consistency with BuildContext). */
+  get: {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+    (key: string): any;
+  };
+
+  /** Set a variable (available for type consistency with BuildContext). */
+  set: {
+    <T>(contextVar: ContextVar<T>, value: T): void;
+    (key: string, value: any): void;
+  };
+
+  /** Push handle data (frozen into pre-rendered output at build time). */
+  use: <T>(handle: Handle<T>) => (data: T) => void;
+
+  /** URL generation by route name. */
+  reverse: BuildReverseFunction;
+}
+
+/**
+ * Context passed to getParams() at build time.
+ * Allows sharing data with handler invocations via set().
+ */
+export interface GetParamsContext {
+  /** Always true during build-time getParams execution. */
+  build: true;
+
+  /** Set a variable that will be available to each handler invocation via ctx.get(). */
+  set: {
+    <T>(contextVar: ContextVar<T>, value: T): void;
+    (key: string, value: any): void;
+  };
+
+  /** URL generation by route name. */
+  reverse: BuildReverseFunction;
+}
+
+/**
+ * Context type for passthrough Prerender handlers.
+ *
+ * When `passthrough: true`, the handler runs both at build time and at request
+ * time. The context is a full `HandlerContext` with `build: boolean`:
+ * - `ctx.build === true`: build-time, env/request/res throw at runtime
+ * - `ctx.build === false`: live request, full context available
+ *
+ * For `passthrough: false` (default), handlers receive `BuildContext` only.
+ */
+export type PrerenderPassthroughContext<
+  TParams = {},
+  TEnv = DefaultEnv,
+> = HandlerContext<TParams, TEnv> & {
+  passthrough: () => PrerenderPassthroughResult;
+};
+
+export interface PrerenderHandlerDefinition<
+  TParams extends Record<string, any> = any,
+> {
+  readonly __brand: "prerenderHandler";
+  /** Auto-generated unique ID (injected by Vite plugin). */
+  $$id: string;
+  /** In dev mode, the actual handler function that path() can call. */
+  handler: Handler<TParams>;
+  /** Returns the list of param objects to pre-render (dynamic routes). */
+  getParams?: (ctx: GetParamsContext) => Promise<TParams[]> | TParams[];
+  /** Pre-render options. */
+  options?: PrerenderOptions;
+}
+
+// -- Overloads --------------------------------------------------------------
+//
+// T accepts: named route string (global or .local) OR explicit param object.
+// Named routes resolve params from GeneratedRouteMap, e.g.:
+//   Prerender<"locale.detail">  → params = { locale: string; slug: string }
+// Explicit params work as before:
+//   Prerender<{ slug: string }> → params = { slug: string }
+
+// Overload 1: Static handler, no passthrough (build-time only)
+export function Prerender<
+  T extends
+    | keyof DefaultPrerenderRouteMap
+    | `.${keyof TRouteMap & string}`
+    | Record<string, any> = {},
+  TRouteMap extends {} = DefaultPrerenderRouteMap,
+>(
+  handler: (
+    ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
+  ) => ReactNode | Promise<ReactNode>,
+  options?: PrerenderOptions & { passthrough?: false },
+  __injectedId?: string,
+): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
+
+// Overload 2: Static handler, passthrough (build + live — full HandlerContext)
+export function Prerender<
+  T extends
+    | keyof DefaultPrerenderRouteMap
+    | `.${keyof TRouteMap & string}`
+    | Record<string, any> = {},
+  TRouteMap extends {} = DefaultPrerenderRouteMap,
+  TEnv = DefaultEnv,
+>(
+  handler: (
+    ctx: PrerenderPassthroughContext<
+      ResolvePrerenderParams<T, TRouteMap>,
+      TEnv
+    >,
+  ) =>
+    | ReactNode
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
+  options: PrerenderOptions & { passthrough: true },
+  __injectedId?: string,
+): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
+
+// Overload 3: Dynamic handler, no passthrough (build-time only)
+export function Prerender<
+  T extends
+    | keyof DefaultPrerenderRouteMap
+    | `.${keyof TRouteMap & string}`
+    | Record<string, any>,
+  TRouteMap extends {} = DefaultPrerenderRouteMap,
+>(
+  getParams: (
+    ctx: GetParamsContext,
+  ) =>
+    | Promise<ResolvePrerenderParams<T, TRouteMap>[]>
+    | ResolvePrerenderParams<T, TRouteMap>[],
+  handler: (
+    ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
+  ) => ReactNode | Promise<ReactNode>,
+  options?: PrerenderOptions & { passthrough?: false },
+  __injectedId?: string,
+): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
+
+// Overload 4: Dynamic handler, passthrough (build + live — full HandlerContext)
+export function Prerender<
+  T extends
+    | keyof DefaultPrerenderRouteMap
+    | `.${keyof TRouteMap & string}`
+    | Record<string, any>,
+  TRouteMap extends {} = DefaultPrerenderRouteMap,
+  TEnv = DefaultEnv,
+>(
+  getParams: (
+    ctx: GetParamsContext,
+  ) =>
+    | Promise<ResolvePrerenderParams<T, TRouteMap>[]>
+    | ResolvePrerenderParams<T, TRouteMap>[],
+  handler: (
+    ctx: PrerenderPassthroughContext<
+      ResolvePrerenderParams<T, TRouteMap>,
+      TEnv
+    >,
+  ) =>
+    | ReactNode
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
+  options: PrerenderOptions & { passthrough: true },
+  __injectedId?: string,
+): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
+
+// -- Implementation ---------------------------------------------------------
+
+export function Prerender<TParams extends Record<string, any>>(
+  handlerOrGetParams: Function,
+  handlerOrOptions?: Function | PrerenderOptions,
+  optionsOrId?: PrerenderOptions | string,
+  maybeId?: string,
+): PrerenderHandlerDefinition<TParams> {
+  // Resolve overloads:
+  // 1 fn arg:  Prerender(handler, options?, __injectedId?)
+  // 2 fn args: Prerender(getParams, handler, options?, __injectedId?)
+  let handler: Handler<TParams>;
+  let getParams: (() => Promise<TParams[]> | TParams[]) | undefined;
+  let options: PrerenderOptions | undefined;
+  let id: string;
+
+  if (typeof handlerOrOptions === "function") {
+    // Two function args: getParams + handler
+    getParams = handlerOrGetParams as () => Promise<TParams[]> | TParams[];
+    handler = handlerOrOptions as Handler<TParams>;
+    if (typeof optionsOrId === "string") {
+      id = optionsOrId;
+    } else {
+      options = optionsOrId as PrerenderOptions | undefined;
+      id = maybeId ?? "";
+    }
+  } else {
+    // Single function arg: handler only
+    handler = handlerOrGetParams as Handler<TParams>;
+    if (typeof handlerOrOptions === "object" && handlerOrOptions !== null) {
+      options = handlerOrOptions as PrerenderOptions;
+    }
+    if (typeof optionsOrId === "string") {
+      id = optionsOrId;
+    } else {
+      id = maybeId ?? "";
+    }
+  }
+
+  if (isCachedFunction(handler)) {
+    throw new Error(
+      'A "use cache" function cannot be used as a Prerender() handler. ' +
+        "Prerender handlers are rendered at build time. Remove the " +
+        '"use cache" directive — Prerender already provides caching.',
+    );
+  }
+  if (getParams && isCachedFunction(getParams)) {
+    throw new Error(
+      'A "use cache" function cannot be used as Prerender() getParams. ' +
+        "getParams runs at build time to enumerate params. Remove the " +
+        '"use cache" directive.',
+    );
+  }
+
+  if (!id) {
+    throw new Error(
+      "[rsc-router] Prerender: missing $$id. " +
+        "Ensure the exposeInternalIds Vite plugin is configured.",
+    );
+  }
+
+  return {
+    __brand: "prerenderHandler" as const,
+    $$id: id,
+    handler,
+    ...(getParams ? { getParams } : {}),
+    ...(options ? { options } : {}),
+  };
+}
+
+// -- Passthrough sentinel ---------------------------------------------------
+
+/**
+ * Sentinel returned by `ctx.passthrough()` to signal that a specific param set
+ * should not produce a local prerender artifact. The build skips writing the
+ * entry; at runtime the handler runs live (requires `{ passthrough: true }`).
+ */
+export const PRERENDER_PASSTHROUGH: Readonly<{
+  __brand: "prerenderPassthrough";
+}> = Object.freeze({
+  __brand: "prerenderPassthrough" as const,
+});
+
+export type PrerenderPassthroughResult = typeof PRERENDER_PASSTHROUGH;
+
+/**
+ * Type guard to check if a value is the passthrough sentinel.
+ */
+export function isPrerenderPassthrough(
+  value: unknown,
+): value is PrerenderPassthroughResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "prerenderPassthrough"
+  );
+}
+
+// -- Type guard -------------------------------------------------------------
+
+/**
+ * Type guard to check if a value is a PrerenderHandlerDefinition.
+ */
+export function isPrerenderHandler(
+  value: unknown,
+): value is PrerenderHandlerDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "prerenderHandler"
+  );
+}