@rangojs/router 0.0.0-experimental.10

package/src/loader.rsc.ts

@@ -0,0 +1,207 @@
+/**
+ * rsc-router/loader (RSC/server version)
+ *
+ * Server-side createLoader implementation with full loader functionality.
+ * Only used in react-server context via export conditions.
+ *
+ * For non-fetchable loaders: returns a loader definition with fn included
+ * For fetchable loaders: stores fn in registry and returns a serializable loader with action
+ *
+ * The $$id is injected by the Vite exposeLoaderId plugin as a hidden parameter.
+ * Users don't need to pass any name - IDs are auto-generated from file path.
+ */
+
+import type {
+  FetchableLoaderOptions,
+  LoaderDefinition,
+  LoaderFn,
+} from "./types.js";
+import type { MiddlewareFn } from "./router/middleware.js";
+import { getRequestContext } from "./server/request-context.js";
+
+// Internal registry for fetchable loaders (server-side only)
+// Maps loader $$id to its function and middleware
+//
+// WHY TWO REGISTRIES?
+// This registry (fetchableLoaderRegistry) is populated immediately when createLoader() runs.
+// The other registry in loader-registry.ts (loaderRegistry) is a cache used by the RSC handler
+// for GET-based fetching. The RSC handler calls getFetchableLoader() from here to populate
+// its cache. This separation allows:
+// 1. Server actions to look up loaders directly without going through lazy loading
+// 2. The RSC handler to use lazy loading for production builds
+// 3. Both to share the same source of truth (this registry)
+const fetchableLoaderRegistry = new Map<
+  string,
+  { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] }
+>();
+
+/**
+ * Register a fetchable loader's function internally
+ * Called during module initialization with the $$id
+ */
+function registerFetchableLoader(
+  id: string,
+  fn: LoaderFn<any, any, any>,
+  middleware: MiddlewareFn[]
+): void {
+  fetchableLoaderRegistry.set(id, { fn, middleware });
+}
+
+/**
+ * Get a fetchable loader's function from the internal registry by $$id
+ *
+ * This is used internally by:
+ * - Server actions (loaderAction) to execute loader functions
+ * - loader-registry.ts to populate the main registry for GET-based fetching
+ *
+ * Loaders are registered here when createLoader() is called with fetchable: true.
+ * The $$id is injected by the Vite exposeLoaderId plugin.
+ *
+ * @param id - The loader's $$id (auto-generated from file path + export name)
+ * @returns The loader function and middleware, or undefined if not found
+ *
+ * @internal This is primarily for internal use by the router infrastructure
+ */
+export function getFetchableLoader(
+  id: string
+): { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] } | undefined {
+  return fetchableLoaderRegistry.get(id);
+}
+
+// Overload 1: With function only (not fetchable)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 2: Fetchable with `true` (no middleware)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable: true
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 3: Fetchable with middleware options
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  options: FetchableLoaderOptions
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Implementation - the $$id parameter is injected by Vite plugin, not user-provided
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable?: true | FetchableLoaderOptions,
+  // Hidden parameter injected by Vite exposeLoaderId plugin
+  __injectedId?: string
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
+  // The $$id will be set on the returned object by Vite plugin
+  // For fetchable loaders, __injectedId is also passed as a parameter
+  const loaderId = __injectedId || "";
+
+  // If not fetchable, store fn in registry and return a plain object.
+  // Server-side code looks up fn via getFetchableLoader($$id).
+  if (fetchable === undefined) {
+    if (fn && loaderId) {
+      registerFetchableLoader(loaderId, fn, []);
+    }
+    return {
+      __brand: "loader",
+      $$id: loaderId,
+    };
+  }
+
+  // Fetchable loader - store fn in registry and return a serializable object
+  const middleware: MiddlewareFn[] =
+    fetchable === true ? [] : fetchable?.middleware || [];
+
+  // Register the function in the internal registry by $$id (server-side only)
+  // The server action will look it up by $$id when executed
+  if (fn && loaderId) {
+    registerFetchableLoader(loaderId, fn, middleware);
+  }
+
+  // Create server action for form-based fetching
+  // This action is serializable and can be passed to client components
+  // The loaderId is captured in closure (it's a primitive string)
+  //
+  // IMPORTANT: The signature must be (prevState, formData) for useActionState compatibility.
+  // When used with useActionState, React passes the previous state as the first argument.
+  // The prevState is ignored here since loaders are stateless data fetchers.
+  async function loaderAction(
+    _prevState: Awaited<T> | null,
+    formData: FormData
+  ): Promise<Awaited<T>> {
+    "use server";
+
+    // Look up the loader from registry by $$id
+    const registered = fetchableLoaderRegistry.get(loaderId);
+    if (!registered) {
+      throw new Error(`Loader "${loaderId}" not found in registry`);
+    }
+
+    // Get request context (env, request, url, variables) from the RSC handler
+    // This is set by runWithRequestContext in rsc/index.ts when executing actions
+    const requestCtx = getRequestContext();
+
+    // Convert FormData to params object
+    const params: Record<string, string> = {};
+    formData.forEach((value, key) => {
+      if (typeof value === "string") {
+        params[key] = value;
+      }
+    });
+
+    // Use real request/url from context, or fall back to synthetic for edge cases
+    const actionUrl = requestCtx?.url ?? new URL("http://localhost/");
+    const actionRequest = requestCtx?.request ?? new Request(actionUrl, { method: "POST" });
+    const env = requestCtx?.env ?? {};
+
+    // Merge variables from request context (app-level middleware) with loader-specific variables
+    // requestCtx.var is the shared variables object from the handler
+    const variables: Record<string, any> = { ...requestCtx?.var };
+
+    // Execute middleware for auth checks, headers, cookies
+    // Headers/cookies set on ctx.res will be merged into the final response
+    if (registered.middleware.length > 0 && requestCtx?.res) {
+      const { executeServerActionMiddleware } = await import(
+        "./router/middleware.js"
+      );
+      await executeServerActionMiddleware(
+        registered.middleware,
+        actionRequest,
+        env,
+        params,
+        variables,
+        requestCtx.res
+      );
+    }
+
+    // Build context using createHandlerContext for consistency with route handlers
+    // Variables are now accessed from request context via getRequestContext()
+    const { createHandlerContext } = await import("./router/handler-context.js");
+    const baseCtx = createHandlerContext(
+      params,
+      actionRequest,
+      actionUrl.searchParams,
+      actionUrl.pathname,
+      actionUrl,
+      env
+    );
+
+    // Extend with server action specific properties
+    const ctx: any = {
+      ...baseCtx,
+      method: "POST",
+      formData,
+    };
+
+    // Execute and return result
+    return registered.fn(ctx);
+  }
+
+  // Return a plain object with action for form-based fetching.
+  // loaderAction has "use server" so RSC Flight serializes it natively as a server action reference.
+  return {
+    __brand: "loader",
+    $$id: loaderId,
+    action: loaderAction,
+  };
+}

package/src/loader.ts

@@ -0,0 +1,47 @@
+/**
+ * rsc-router/loader (client version)
+ *
+ * Client-only stub for createLoader. Returns a minimal loader definition
+ * that can be passed to hooks like useLoader. The actual loader function
+ * is not included - it only exists on the server.
+ *
+ * The $$id is injected by the Vite exposeLoaderId plugin.
+ */
+
+import type {
+  FetchableLoaderOptions,
+  LoaderDefinition,
+  LoaderFn,
+} from "./types.js";
+
+// Overload 1: With function only (not fetchable)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 2: Fetchable with `true` (no middleware)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable: true
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 3: Fetchable with middleware options
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  options: FetchableLoaderOptions
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Implementation - client stub that just returns the loader definition
+// The $$id parameter is injected by Vite plugin, not user-provided
+export function createLoader<T>(
+  _fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  _fetchable?: true | FetchableLoaderOptions,
+  __injectedId?: string
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
+  // Client only needs the $$id for identification
+  // The actual loader function is only used on the server
+  return {
+    __brand: "loader",
+    $$id: __injectedId || "",
+  };
+}

package/src/network-error-thrower.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { NetworkError } from "./errors.js";
+
+interface NetworkErrorThrowerProps {
+  error: NetworkError;
+}
+
+/**
+ * Client component that throws a NetworkError during render.
+ * Used to trigger the root error boundary when a network error occurs
+ * during navigation or server actions.
+ *
+ * This must be a separate component because:
+ * 1. Errors must be thrown during React's render phase to be caught by error boundaries
+ * 2. The error occurs in async code (fetch), so we need to propagate it to React's render
+ */
+export function NetworkErrorThrower({ error }: NetworkErrorThrowerProps): ReactNode {
+  throw error;
+}

package/src/outlet-context.ts

@@ -0,0 +1,15 @@
+import { Context, createContext, type ReactNode } from "react";
+import type { ResolvedSegment } from "./types";
+
+export interface OutletContextValue {
+  content: ReactNode;
+  parallel?: ResolvedSegment[];
+  segment?: ResolvedSegment;
+  loaderData?: Record<string, any>;
+  parent?: OutletContextValue | null;
+  /** Loading component for Suspense fallback (from segment's loading() definition) */
+  loading?: ReactNode;
+}
+
+export const OutletContext: Context<OutletContextValue | null> =
+  createContext<OutletContextValue | null>(null);

package/src/prerender/param-hash.ts

@@ -0,0 +1,35 @@
+/**
+ * Deterministic param hashing for prerender storage keys.
+ *
+ * Used at build time (child process) to generate filenames and at
+ * runtime (worker) to look up pre-rendered data. Both environments
+ * must produce identical hashes for the same params.
+ *
+ * Uses a simple DJB2-based hash that works in all JS environments
+ * (Node.js, Cloudflare Workers, browsers) without crypto imports.
+ */
+
+/**
+ * Compute a deterministic hash string from route params.
+ * For static routes (no params), returns "_".
+ */
+export function hashParams(params: Record<string, string>): string {
+  const entries = Object.entries(params);
+  if (entries.length === 0) return "_";
+
+  const sorted = entries.sort(([a], [b]) => a.localeCompare(b));
+  const str = sorted.map(([k, v]) => `${k}=${v}`).join("&");
+  return djb2Hex(str);
+}
+
+/**
+ * DJB2 hash returning an 8-char hex string.
+ * Deterministic across all JS runtimes.
+ */
+function djb2Hex(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}

package/src/prerender/store.ts

@@ -0,0 +1,40 @@
+/**
+ * Prerender Store
+ *
+ * Reads pre-rendered segment data injected into the worker bundle at build time.
+ * The data is stored as globalThis.__PRERENDER_DATA, a JSON object keyed by
+ * "<routeName>/<paramHash>".
+ */
+
+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): PrerenderEntry | null;
+}
+
+declare global {
+  // Injected by closeBundle post-processing
+  // eslint-disable-next-line no-var
+  var __PRERENDER_DATA: Record<string, PrerenderEntry> | undefined;
+}
+
+/**
+ * Create a prerender store backed by globalThis.__PRERENDER_DATA.
+ * Returns null if no prerender data is available (dev mode or no prerendered routes).
+ */
+export function createPrerenderStore(): PrerenderStore | null {
+  const data = globalThis.__PRERENDER_DATA;
+  if (!data || Object.keys(data).length === 0) return null;
+
+  return {
+    get(routeName: string, paramHash: string): PrerenderEntry | null {
+      const key = `${routeName}/${paramHash}`;
+      return data[key] ?? null;
+    },
+  };
+}

package/src/prerender.ts

@@ -0,0 +1,156 @@
+/**
+ * Pre-render handler definition for build-time rendering of route segments.
+ *
+ * createPrerenderHandler 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
+ * based on file path and export name. No manual naming required.
+ *
+ * @example
+ * ```ts
+ * // Static page — no params
+ * export const DocsPage = createPrerenderHandler(async (ctx) => {
+ *   return <div>Documentation</div>;
+ * });
+ *
+ * // Dynamic page — params first, handler second
+ * export const DocsArticle = createPrerenderHandler(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => {
+ *     return <div>{ctx.params.slug}</div>;
+ *   }
+ * );
+ * ```
+ */
+import type { ReactNode } from "react";
+import type { Handler, HandlerContext } from "./types.js";
+import type { Handle } from "./handle.js";
+
+// -- 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;
+}
+
+export interface BuildContext<TParams> {
+  /** Params extracted from the route pattern (populated from getParams). */
+  params: TParams;
+
+  /** 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;
+}
+
+export interface PrerenderHandlerDefinition<TParams = 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[];
+  /** Pre-render options. */
+  options?: PrerenderOptions;
+}
+
+// -- Overloads --------------------------------------------------------------
+
+// Overload 1: Static handler (no params)
+export function createPrerenderHandler<TParams = {}>(
+  handler: (ctx: HandlerContext<TParams>) => ReactNode | Promise<ReactNode>,
+  options?: PrerenderOptions,
+  __injectedId?: string,
+): PrerenderHandlerDefinition<TParams>;
+
+// Overload 2: Dynamic handler (getParams + handler)
+export function createPrerenderHandler<TParams>(
+  getParams: () => Promise<TParams[]> | TParams[],
+  handler: (ctx: HandlerContext<TParams>) => ReactNode | Promise<ReactNode>,
+  options?: PrerenderOptions,
+  __injectedId?: string,
+): PrerenderHandlerDefinition<TParams>;
+
+// -- Implementation ---------------------------------------------------------
+
+export function createPrerenderHandler<TParams>(
+  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?)
+  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 (!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(...)"
+    );
+  }
+
+  return {
+    __brand: "prerenderHandler" as const,
+    $$id: id,
+    handler,
+    ...(getParams ? { getParams } : {}),
+    ...(options ? { options } : {}),
+  };
+}
+
+// -- 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"
+  );
+}