@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20

package/src/rsc/server-action.ts

@@ -0,0 +1,344 @@
+/**
+ * Server Action Handler
+ *
+ * Handles server action execution and post-action revalidation as two
+ * separate phases:
+ *
+ * 1. executeServerAction — decodes args, runs the action, handles redirects
+ *    and error boundaries. Returns either a final Response (redirect/error)
+ *    or an ActionContinuation for the revalidation phase.
+ *
+ * 2. revalidateAfterAction — takes the continuation, matches affected
+ *    segments, builds the RSC payload, and returns the Flight response.
+ *
+ * The handler (handler.ts) runs the action BEFORE route middleware, then
+ * wraps revalidation inside route middleware — identical to a normal render.
+ */
+
+import {
+  requireRequestContext,
+  setRequestContextParams,
+  getLocationState,
+} from "../server/request-context.js";
+import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import type { RscPayload } from "./types.js";
+import {
+  hasBodyContent,
+  createResponseWithMergedHeaders,
+  createSimpleRedirectResponse,
+  carryOverRedirectHeaders,
+} from "./helpers.js";
+import type { HandlerContext } from "./handler-context.js";
+
+/**
+ * Attach location state set during the action to a payload's metadata.
+ * No-op if no location state was set.
+ */
+function attachLocationState(payload: RscPayload): void {
+  const locationState = getLocationState();
+  if (locationState) {
+    payload.metadata!.locationState =
+      resolveLocationStateEntries(locationState);
+  }
+}
+
+/**
+ * Data flowing from action execution to the revalidation phase.
+ * When the action completes without redirect/error-boundary, the handler
+ * passes this to route middleware → revalidateAfterAction.
+ */
+export interface ActionContinuation {
+  returnValue: { ok: boolean; data: unknown };
+  actionStatus: number;
+  temporaryReferences: ReturnType<
+    HandlerContext["createTemporaryReferenceSet"]
+  >;
+  actionContext: {
+    actionId: string;
+    actionUrl: URL;
+    actionResult: unknown;
+    formData?: FormData;
+  };
+}
+
+/**
+ * Phase 1: Execute the server action.
+ *
+ * Decodes arguments, runs the action, handles redirects and error
+ * boundaries. Returns a final Response (redirect, error boundary render)
+ * or an ActionContinuation for the revalidation phase.
+ */
+export async function executeServerAction<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  actionId: string,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+): Promise<Response | ActionContinuation> {
+  const temporaryReferences = ctx.createTemporaryReferenceSet();
+
+  // Decode action arguments from request body
+  const contentType = request.headers.get("content-type") || "";
+  let args: unknown[] = [];
+  let actionFormData: FormData | undefined;
+
+  try {
+    const body = contentType.includes("multipart/form-data")
+      ? await request.formData()
+      : await request.text();
+
+    if (body instanceof FormData) {
+      actionFormData = body;
+    }
+
+    if (hasBodyContent(body)) {
+      args = await ctx.decodeReply(body, { temporaryReferences });
+    }
+  } catch (error) {
+    throw new Error(`Failed to decode action arguments: ${error}`, {
+      cause: error,
+    });
+  }
+
+  // Execute the server action
+  let returnValue: { ok: boolean; data: unknown };
+  let actionStatus = 200;
+  let loadedAction: Function | undefined;
+
+  try {
+    loadedAction = await ctx.loadServerAction(actionId);
+    const data = await loadedAction!.apply(null, args);
+
+    // Intercept redirect responses from actions. Without this, the redirect
+    // Response would be serialized as the action returnValue (which fails)
+    // and the revalidation step would run unnecessarily.
+    if (data instanceof Response) {
+      const redirectUrl = data.headers.get("Location");
+      const isRedirect = data.status >= 300 && data.status < 400 && redirectUrl;
+      if (isRedirect) {
+        const locationState = getLocationState();
+        let redirect: Response;
+        if (locationState) {
+          redirect = ctx.createRedirectFlightResponse(
+            redirectUrl,
+            resolveLocationStateEntries(locationState),
+          );
+        } else {
+          redirect = createSimpleRedirectResponse(redirectUrl);
+        }
+        carryOverRedirectHeaders(data, redirect);
+        return redirect;
+      }
+    }
+
+    returnValue = { ok: true, data };
+  } catch (error) {
+    // Handle thrown redirect (e.g., throw redirect('/path'))
+    if (error instanceof Response) {
+      const redirectUrl = error.headers.get("Location");
+      const isRedirect =
+        error.status >= 300 && error.status < 400 && redirectUrl;
+      if (isRedirect) {
+        const locationState = getLocationState();
+        let redirect: Response;
+        if (locationState) {
+          redirect = ctx.createRedirectFlightResponse(
+            redirectUrl,
+            resolveLocationStateEntries(locationState),
+          );
+        } else {
+          redirect = createSimpleRedirectResponse(redirectUrl);
+        }
+        carryOverRedirectHeaders(error, redirect);
+        return redirect;
+      }
+
+      // Non-redirect Response thrown from action — this will be treated
+      // as a regular error and routed to the error boundary. Warn in dev
+      // since the intent is likely a redirect with a missing Location header.
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          `[@rangojs/router] Server action "${actionId}" threw a Response ` +
+            `(status ${error.status}) that is not a redirect. ` +
+            `Non-redirect Responses are treated as errors. ` +
+            `Use \`throw redirect('/path')\` for redirects.`,
+        );
+      }
+    }
+
+    returnValue = { ok: false, data: error };
+    actionStatus = 500;
+
+    // Try to render error boundary.
+    // Report the action error first so it is not lost if matchError throws.
+    let errorResult;
+    try {
+      errorResult = await ctx.router.matchError(
+        request,
+        { env },
+        error,
+        "route",
+      );
+    } catch (matchErr) {
+      // matchError failed — report the original action error as unhandled,
+      // then let the matchError failure propagate.
+      ctx.callOnError(error, "action", {
+        request,
+        url,
+        env,
+        actionId,
+        handledByBoundary: false,
+      });
+      throw matchErr;
+    }
+
+    ctx.callOnError(error, "action", {
+      request,
+      url,
+      env,
+      actionId,
+      handledByBoundary: !!errorResult,
+    });
+
+    if (errorResult) {
+      setRequestContextParams(errorResult.params, errorResult.routeName);
+
+      const payload: RscPayload = {
+        metadata: {
+          pathname: url.pathname,
+          segments: errorResult.segments,
+          isPartial: true,
+          matched: errorResult.matched,
+          diff: errorResult.diff,
+          isError: true,
+          handles: handleStore.stream(),
+          version: ctx.version,
+        },
+        returnValue,
+      };
+
+      // Intentionally omit attachLocationState for error payloads:
+      // location state is a success-only semantic. Error boundary responses
+      // update the error UI but should not mutate browser history state.
+
+      const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+        temporaryReferences,
+      });
+
+      return createResponseWithMergedHeaders(rscStream, {
+        status: actionStatus,
+        headers: { "content-type": "text/x-component;charset=utf-8" },
+      });
+    }
+  }
+
+  // Build continuation for the revalidation phase
+  const resolvedActionId =
+    (loadedAction as { $id?: string; $$id?: string } | undefined)?.$id ??
+    (loadedAction as { $$id?: string } | undefined)?.$$id ??
+    actionId;
+
+  return {
+    returnValue,
+    actionStatus,
+    temporaryReferences,
+    actionContext: {
+      actionId: resolvedActionId,
+      actionUrl: new URL(request.url),
+      actionResult: returnValue.data,
+      formData: actionFormData,
+    },
+  };
+}
+
+/**
+ * Phase 2: Revalidate after action.
+ *
+ * Matches affected segments, builds the RSC payload, and returns the
+ * Flight response. Called inside route middleware (same as a normal render).
+ *
+ * Invariant: the response payload MUST have isPartial: true. The client
+ * (server-action-bridge) rejects non-partial payloads because partial
+ * reconciliation requires matched/diff semantics that full renders don't
+ * provide. Redirects are the only non-partial outcome and are handled via
+ * X-RSC-Redirect headers before Flight deserialization.
+ */
+export async function revalidateAfterAction<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  continuation: ActionContinuation,
+): Promise<Response> {
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
+
+  const matchResult = await ctx.router.matchPartial(
+    request,
+    { env },
+    actionContext,
+  );
+
+  if (!matchResult) {
+    // matchPartial returns null when the route is a redirect or the request
+    // is missing required headers (previousUrl). Check for redirect first.
+    const fullMatch = await ctx.router.match(request, { env });
+    setRequestContextParams(fullMatch.params, fullMatch.routeName);
+
+    if (fullMatch.redirect) {
+      // Action context is always partial — use X-RSC-Redirect header so
+      // the client can perform SPA navigation instead of fetch auto-following
+      // a raw 308 to a URL that would render full HTML.
+      return createSimpleRedirectResponse(fullMatch.redirect);
+    }
+
+    // Non-redirect: this branch is only reachable when the action request
+    // is missing the X-RSC-Router-Client-Path header (defensive). The
+    // client requires isPartial for action responses, so producing a full
+    // payload here would be rejected. Return 500 instead.
+    throw new Error(
+      `[RSC] matchPartial returned null for a non-redirect route ` +
+        `during action revalidation (${url.pathname}). This indicates ` +
+        `a malformed action request (missing X-RSC-Router-Client-Path header).`,
+    );
+  }
+
+  // Return updated segments
+  setRequestContextParams(matchResult.params, matchResult.routeName);
+
+  const serverTiming = matchResult.serverTiming;
+
+  const payload: RscPayload = {
+    metadata: {
+      pathname: url.pathname,
+      segments: matchResult.segments,
+      isPartial: true,
+      matched: matchResult.matched,
+      diff: matchResult.diff,
+      slots: matchResult.slots,
+      handles: handleStore.stream(),
+      version: ctx.version,
+    },
+    returnValue,
+  };
+
+  attachLocationState(payload);
+
+  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    temporaryReferences,
+  });
+
+  const actionHeaders: Record<string, string> = {
+    "content-type": "text/x-component;charset=utf-8",
+  };
+  if (serverTiming) {
+    actionHeaders["Server-Timing"] = serverTiming;
+  }
+
+  return createResponseWithMergedHeaders(rscStream, {
+    status: actionStatus,
+    headers: actionHeaders,
+  });
+}

package/src/rsc/types.ts

@@ -7,14 +7,15 @@
 
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { HandleData } from "../server/handle-store.js";
-import type { RSCRouter } from "../router.js";
+import type { RSCRouterInternal } from "../router/router-interfaces.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 
 /**
- * RSC payload sent to the client
+ * RSC payload sent to the client.
+ * The tree is always reconstructed from metadata.segments by consumers
+ * (SSR via renderSegments, browser via renderSegments in bridges).
  */
 export interface RscPayload {
-  root: React.ReactNode | Promise<React.ReactNode>;
   metadata?: {
     pathname: string;
     segments: ResolvedSegment[];
@@ -22,6 +23,8 @@ export interface RscPayload {
     isError?: boolean;
     matched?: string[];
     diff?: string[];
+    /** Merged route params from the matched route */
+    params?: Record<string, string>;
     slots?: Record<string, SlotState>;
     /** Root layout component for browser-side re-renders (client component reference) */
     rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
@@ -33,10 +36,12 @@ export interface RscPayload {
     themeConfig?: ResolvedThemeConfig | null;
     /** Initial theme from cookie (for SSR hydration) */
     initialTheme?: Theme;
-    /** Route map for useHref() - maps route names to URL patterns */
-    routeMap?: Record<string, string>;
-    /** Current matched route name (for local name resolution in useHref) */
-    routeName?: string;
+    /** Whether connection warmup is enabled */
+    warmupEnabled?: boolean;
+    /** Server-side redirect with optional state (for partial requests) */
+    redirect?: { url: string };
+    /** Server-set location state to include in history.pushState */
+    locationState?: Record<string, unknown>;
   };
   returnValue?: { ok: boolean; data: unknown };
   formState?: unknown;
@@ -56,7 +61,7 @@ export interface RSCDependencies {
    */
   renderToReadableStream: <T>(
     payload: T,
-    options?: { temporaryReferences?: unknown }
+    options?: { temporaryReferences?: unknown },
   ) => ReadableStream<Uint8Array>;
 
   /**
@@ -64,7 +69,7 @@ export interface RSCDependencies {
    */
   decodeReply: (
     body: FormData | string,
-    options?: { temporaryReferences?: unknown }
+    options?: { temporaryReferences?: unknown },
   ) => Promise<unknown[]>;
 
   /**
@@ -89,7 +94,7 @@ export interface RSCDependencies {
    */
   decodeFormState: (
     actionResult: unknown,
-    body: FormData
+    body: FormData,
   ) => Promise<ReactFormState | null>;
 }
 
@@ -109,6 +114,14 @@ export interface SSRRenderOptions {
    * Nonce for Content Security Policy (CSP)
    */
   nonce?: string;
+
+  /**
+   * SSR stream mode.
+   *
+   * - `"stream"` (default) — start flushing HTML immediately.
+   * - `"allReady"` — await `stream.allReady` before returning.
+   */
+  streamMode?: import("../router/router-options.js").SSRStreamMode;
 }
 
 /**
@@ -117,7 +130,7 @@ export interface SSRRenderOptions {
 export interface SSRModule {
   renderHTML: (
     rscStream: ReadableStream<Uint8Array>,
-    options?: SSRRenderOptions
+    options?: SSRRenderOptions,
   ) => Promise<ReadableStream<Uint8Array>>;
 }
 
@@ -143,7 +156,7 @@ export interface HandlerCacheConfig {
  */
 export type NonceProvider<TEnv = unknown> = (
   request: Request,
-  env: TEnv
+  env: TEnv,
 ) => string | true | Promise<string | true>;
 
 /**
@@ -156,7 +169,7 @@ export interface CreateRSCHandlerOptions<
   /**
    * The RSC router instance
    */
-  router: RSCRouter<TEnv, TRoutes>;
+  router: RSCRouterInternal<TEnv, TRoutes>;
 
   /**
    * RSC dependencies from @vitejs/plugin-rsc/rsc.
@@ -215,7 +228,8 @@ export interface CreateRSCHandlerOptions<
    * - Undefined to disable nonce (default)
    *
    * The nonce will be applied to inline scripts injected by the RSC payload.
-   * It's also available to middleware via `ctx.get('nonce')`.
+   * It's also available to middleware via the typed `nonce` token:
+   * `import { nonce } from "@rangojs/router"; ctx.get(nonce)`
    *
    * @example Auto-generate nonce
    * ```tsx
@@ -232,6 +246,16 @@ export interface CreateRSCHandlerOptions<
    *   nonce: (request, env) => env.nonce,
    * });
    * ```
+   *
+   * @example Access nonce in middleware
+   * ```tsx
+   * import { nonce } from "@rangojs/router";
+   *
+   * const cspMiddleware: Middleware = async (ctx, next) => {
+   *   const value = ctx.get(nonce); // string | undefined
+   *   await next();
+   * };
+   * ```
    */
   nonce?: NonceProvider<TEnv>;
 }

package/src/search-params.ts

@@ -0,0 +1,227 @@
+/**
+ * Search parameter schema types and runtime utilities.
+ *
+ * Provides a lightweight schema system for typed query parameters.
+ * When a route defines a `search` schema, ctx.search provides a typed
+ * object with parsed values. ctx.searchParams always remains a standard
+ * URLSearchParams instance.
+ */
+
+// ============================================================================
+// Schema Types
+// ============================================================================
+
+/** Supported scalar types for search params (append ? for optional). */
+export type SearchSchemaValue =
+  | "string"
+  | "number"
+  | "boolean"
+  | "string?"
+  | "number?"
+  | "boolean?";
+
+/** A search schema maps param names to their type descriptors. */
+export type SearchSchema = Record<string, SearchSchemaValue>;
+
+// ============================================================================
+// Type-Level Schema Resolution
+// ============================================================================
+
+/** Strip trailing `?` from a schema value to get the base type. */
+type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
+
+/** Map a base type string to its TypeScript type. */
+type ResolveBaseType<T extends string> = T extends "string"
+  ? string
+  : T extends "number"
+    ? number
+    : T extends "boolean"
+      ? boolean
+      : never;
+
+/** Keys whose schema value does NOT end with `?`. */
+type RequiredKeys<T extends SearchSchema> = {
+  [K in keyof T]: T[K] extends `${string}?` ? never : K;
+}[keyof T];
+
+/** Keys whose schema value ends with `?`. */
+type OptionalKeys<T extends SearchSchema> = {
+  [K in keyof T]: T[K] extends `${string}?` ? K : never;
+}[keyof T];
+
+/** Flatten an intersection type into a single object type. */
+type Simplify<T> = { [K in keyof T]: T[K] };
+
+/**
+ * Resolve a SearchSchema to its typed object.
+ *
+ * @example
+ * type S = { q: "string"; page: "number?"; sort: "string?" };
+ * type R = ResolveSearchSchema<S>;
+ * // { q: string; page?: number; sort?: string }
+ */
+export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
+  {
+    [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>>;
+  } & {
+    [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
+  }
+>;
+
+// ============================================================================
+// Route-Level Type Extraction
+// ============================================================================
+
+/** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
+type GlobalRouteMap = keyof RSCRouter.RegisteredRoutes extends never
+  ? keyof RSCRouter.GeneratedRouteMap extends never
+    ? Record<string, string>
+    : RSCRouter.GeneratedRouteMap
+  : RSCRouter.RegisteredRoutes;
+
+/**
+ * Extract the resolved search params type for a named route.
+ * Looks up the search schema from the route map and resolves it.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/search", handler, { name: "search", search: { q: "string", page: "number?" } })
+ * type Params = RouteSearchParams<"search">;
+ * // { q: string; page?: number }
+ * ```
+ */
+export type RouteSearchParams<TName extends string, TRouteMap = never> = [
+  TRouteMap,
+] extends [never]
+  ? ExtractAndResolveSearch<GlobalRouteMap, TName>
+  : ExtractAndResolveSearch<TRouteMap, TName>;
+
+type ExtractAndResolveSearch<TRouteMap, TName> = TName extends keyof TRouteMap
+  ? TRouteMap[TName] extends { readonly search: infer S extends SearchSchema }
+    ? ResolveSearchSchema<S>
+    : {}
+  : {};
+
+/**
+ * Extract the route params type for a named route.
+ * Looks up the path pattern from the route map and extracts params.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/blog/:slug", handler, { name: "blogPost" })
+ * type Params = RouteParams<"blogPost">;
+ * // { slug: string }
+ * ```
+ */
+export type RouteParams<TName extends string, TRouteMap = never> = [
+  TRouteMap,
+] extends [never]
+  ? ExtractRouteParamsFromMap<GlobalRouteMap, TName>
+  : ExtractRouteParamsFromMap<TRouteMap, TName>;
+
+type ExtractRouteParamsFromMap<TRouteMap, TName> = TName extends keyof TRouteMap
+  ? TRouteMap[TName] extends string
+    ? ExtractParamsFromPattern<TRouteMap[TName]>
+    : TRouteMap[TName] extends { readonly path: infer P extends string }
+      ? ExtractParamsFromPattern<P>
+      : {}
+  : {};
+
+/** Parse "a|b|c" into "a" | "b" | "c" */
+type ParseConstraint<T extends string> =
+  T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+
+/** Minimal inline param extraction (avoids importing from types.ts to prevent circular deps). */
+type ExtractParamsFromPattern<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param extends `${infer Name}(${infer C})?`
+      ? {
+          [K in Name]?: ParseConstraint<C>;
+        } & ExtractParamsFromPattern<`/${Rest}`>
+      : Param extends `${infer Name}(${infer C})`
+        ? {
+            [K in Name]: ParseConstraint<C>;
+          } & ExtractParamsFromPattern<`/${Rest}`>
+        : Param extends `${infer Name}?`
+          ? { [K in Name]?: string } & ExtractParamsFromPattern<`/${Rest}`>
+          : { [K in Param]: string } & ExtractParamsFromPattern<`/${Rest}`>
+    : T extends `${string}:${infer Param}`
+      ? Param extends `${infer Name}(${infer C})?`
+        ? { [K in Name]?: ParseConstraint<C> }
+        : Param extends `${infer Name}(${infer C})`
+          ? { [K in Name]: ParseConstraint<C> }
+          : Param extends `${infer Name}?`
+            ? { [K in Name]?: string }
+            : { [K in Param]: string }
+      : {};
+
+// ============================================================================
+// Runtime Parser
+// ============================================================================
+
+/**
+ * Parse URLSearchParams into a typed object using the given schema.
+ *
+ * - `"string"` / `"string?"` - kept as-is
+ * - `"number"` / `"number?"` - coerced via `Number()`; NaN treated as missing
+ * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
+ *
+ * Missing required params are set to their zero value (empty string / 0 / false).
+ */
+export function parseSearchParams<T extends SearchSchema>(
+  searchParams: URLSearchParams,
+  schema: T,
+): ResolveSearchSchema<T> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, descriptor] of Object.entries(schema)) {
+    const isOptional = descriptor.endsWith("?");
+    const baseType = isOptional ? descriptor.slice(0, -1) : descriptor;
+    const raw = searchParams.get(key);
+
+    if (raw === null) {
+      if (!isOptional) {
+        // Required param missing: use zero value
+        if (baseType === "string") result[key] = "";
+        else if (baseType === "number") result[key] = 0;
+        else if (baseType === "boolean") result[key] = false;
+      }
+      // Optional params are omitted (undefined)
+      continue;
+    }
+
+    if (baseType === "string") {
+      result[key] = raw;
+    } else if (baseType === "number") {
+      const num = Number(raw);
+      if (Number.isNaN(num)) {
+        if (!isOptional) result[key] = 0;
+      } else {
+        result[key] = num;
+      }
+    } else if (baseType === "boolean") {
+      result[key] = raw === "true" || raw === "1";
+    }
+  }
+
+  return result as ResolveSearchSchema<T>;
+}
+
+// ============================================================================
+// Runtime Serializer
+// ============================================================================
+
+/**
+ * Serialize a typed search params object to a query string (without leading `?`).
+ * Skips `undefined` and `null` values.
+ */
+export function serializeSearchParams(params: Record<string, unknown>): string {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) continue;
+    parts.push(
+      `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`,
+    );
+  }
+  return parts.join("&");
+}