@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.91

package/src/prerender.ts

@@ -1,23 +1,23 @@
 /**
  * Pre-render handler definition for build-time rendering of route segments.
  *
- * createPrerenderHandler wraps a handler so that in production (phase 2)
+ * 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 exposePrerenderHandlerId plugin
+ * 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 = createPrerenderHandler(async (ctx) => {
+ * export const DocsPage = Prerender(async (ctx) => {
  *   return <div>Documentation</div>;
  * });
  *
  * // Dynamic page — params first, handler second
- * export const DocsArticle = createPrerenderHandler(
+ * export const DocsArticle = Prerender(
  *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
  *   async (ctx) => {
  *     return <div>{ctx.params.slug}</div>;
@@ -26,24 +26,144 @@
  * ```
  */
 import type { ReactNode } from "react";
-import type { Handler, HandlerContext } from "./types.js";
+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 type { UseItems, HandlerUseItem } from "./route-types.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.
+   * 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 },
+   * );
+   * ```
    */
-  passthrough?: boolean;
+  concurrency?: number;
 }
 
+/**
+ * Context passed to Prerender() handlers at build time.
+ * Has a synthetic URL from getParams, params, pathname, and optionally env.
+ * No request, 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;
+
+  /**
+   * True when running in Vite dev mode (on-demand prerender), false during
+   * production `vite build`. Use this to branch on runtime mode without
+   * changing build semantics.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings (KV, D1, etc.) supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   * Throws with a clear error if not configured.
+   *
+   * This is NOT the live request env — it is shared across all prerender
+   * invocations for the build.
+   */
+  env: DefaultEnv;
+
+  /** 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;
 
@@ -52,48 +172,167 @@ export interface BuildContext<TParams> {
 
   /** 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 live handler runs instead. Only valid on routes wrapped
+   * with `Passthrough()`.
+   */
+  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;
+
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
+  /** 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;
 }
 
-export interface PrerenderHandlerDefinition<TParams = any> {
+/**
+ * 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;
+
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
+  /** 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;
+}
+
+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?: () => Promise<TParams[]> | TParams[];
+  getParams?: (ctx: GetParamsContext) => Promise<TParams[]> | TParams[];
   /** Pre-render options. */
   options?: PrerenderOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
 // -- 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 params)
-export function createPrerenderHandler<TParams = {}>(
-  handler: (ctx: HandlerContext<TParams>) => ReactNode | Promise<ReactNode>,
+// Overload 1: Static handler (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
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
   options?: PrerenderOptions,
   __injectedId?: string,
-): PrerenderHandlerDefinition<TParams>;
+): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
-// Overload 2: Dynamic handler (getParams + handler)
-export function createPrerenderHandler<TParams>(
-  getParams: () => Promise<TParams[]> | TParams[],
-  handler: (ctx: HandlerContext<TParams>) => ReactNode | Promise<ReactNode>,
+// Overload 2: Dynamic handler (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
+    | PrerenderPassthroughResult
+    | Promise<ReactNode | PrerenderPassthroughResult>,
   options?: PrerenderOptions,
   __injectedId?: string,
-): PrerenderHandlerDefinition<TParams>;
+): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
 // -- Implementation ---------------------------------------------------------
 
-export function createPrerenderHandler<TParams>(
+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:  createPrerenderHandler(handler, options?, __injectedId?)
-  // 2 fn args: createPrerenderHandler(getParams, handler, options?, __injectedId?)
+  // 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;
@@ -122,11 +361,25 @@ export function createPrerenderHandler<TParams>(
     }
   }
 
-  if (!id && process.env.NODE_ENV !== "production") {
-    console.warn(
-      "[rsc-router] PrerenderHandler is missing $$id. " +
-        "Make sure the exposePrerenderHandlerId Vite plugin is enabled and " +
-        "the handler is exported with: export const MyPage = createPrerenderHandler(...)"
+  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.",
     );
   }
 
@@ -139,7 +392,36 @@ export function createPrerenderHandler<TParams>(
   };
 }
 
-// -- Type guard -------------------------------------------------------------
+// -- 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 Passthrough live handler runs instead.
+ */
+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 guards ------------------------------------------------------------
 
 /**
  * Type guard to check if a value is a PrerenderHandlerDefinition.
@@ -154,3 +436,89 @@ export function isPrerenderHandler(
     (value as { __brand: unknown }).__brand === "prerenderHandler"
   );
 }
+
+// -- Passthrough wrapper ----------------------------------------------------
+
+/**
+ * A prerender route with a live fallback handler for unknown params at runtime.
+ *
+ * Wraps a `Prerender(...)` definition with a separate handler that runs at
+ * request time for params not covered by `getParams()`.
+ *
+ * - Build time: `prerenderDef` provides getParams + build handler.
+ * - Runtime: `liveHandler` runs for unknown params with full HandlerContext.
+ *
+ * @example
+ * ```ts
+ * const BlogPrerender = Prerender(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => <BlogPost slug={ctx.params.slug} />,
+ * );
+ *
+ * // In route definition:
+ * path("/blog/:slug", Passthrough(BlogPrerender, async (ctx) => {
+ *   const post = await ctx.env.DB.get(ctx.params.slug);
+ *   return <BlogPost slug={ctx.params.slug} post={post} />;
+ * }))
+ * ```
+ */
+export interface PassthroughHandlerDefinition<
+  TParams extends Record<string, any> = any,
+  TEnv = DefaultEnv,
+> {
+  readonly __brand: "passthroughHandler";
+  /** The underlying prerender definition (build-time rendering). */
+  prerenderDef: PrerenderHandlerDefinition<TParams>;
+  /** Live handler for runtime fallback on unknown params. */
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
+}
+
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv>;
+
+// Implementation
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv> {
+  if (!isPrerenderHandler(prerenderDef)) {
+    throw new Error(
+      "[rsc-router] Passthrough: first argument must be a Prerender() definition.",
+    );
+  }
+  return {
+    __brand: "passthroughHandler" as const,
+    prerenderDef,
+    liveHandler,
+  };
+}
+
+/**
+ * Type guard to check if a value is a PassthroughHandlerDefinition.
+ */
+export function isPassthroughHandler(
+  value: unknown,
+): value is PassthroughHandlerDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "passthroughHandler"
+  );
+}

package/src/response-utils.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime-neutral Response shape utilities.
+ *
+ * Kept at the src/ root so both `router/` and `rsc/` can depend on it
+ * without creating a cross-layer import cycle.
+ */
+
+/**
+ * True when a Response represents a WebSocket upgrade handoff and must not
+ * be reconstructed or mutated:
+ *
+ * - Status 101 (Switching Protocols) is outside the standard Response
+ *   constructor's 200–599 range, so `new Response(body, { status: 101 })`
+ *   throws RangeError on Node/undici and any spec-compliant runtime.
+ * - Cloudflare's workerd attaches a non-standard `webSocket` property on
+ *   the upgrade Response (e.g. from `acceptWebSocket`/`handleWebSocketUpgrade`
+ *   or the `agents` library's `routeAgentRequest`). That property is dropped
+ *   by a `new Response(...)` copy, breaking the upgrade even on workerd
+ *   where the status range is relaxed.
+ *
+ * Callers should short-circuit header/body merges for these responses.
+ */
+export function isWebSocketUpgradeResponse(response: Response): boolean {
+  return (
+    response.status === 101 ||
+    (response as unknown as { webSocket?: unknown }).webSocket != null
+  );
+}