@rangojs/router 0.0.0-experimental.002d056c

package/src/rsc/types.ts

@@ -0,0 +1,263 @@
+/**
+ * RSC Handler Types
+ *
+ * Type definitions for the RSC request handler, payload structures,
+ * and SSR integration.
+ */
+
+import type { ResolvedSegment, SlotState } from "../types.js";
+import type { HandleData } from "../server/handle-store.js";
+import type { RSCRouterInternal } from "../router/router-interfaces.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+
+/**
+ * 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 {
+  metadata?: {
+    pathname: string;
+    segments: ResolvedSegment[];
+    isPartial?: boolean;
+    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 }>;
+    /** Handle data accumulated across route segments (async generator that yields on each push) */
+    handles?: AsyncGenerator<HandleData, void, unknown>;
+    /** RSC version string for cache invalidation */
+    version?: string;
+    /** TTL in milliseconds for the client-side in-memory prefetch cache */
+    prefetchCacheTTL?: number;
+    /** Theme configuration for FOUC prevention */
+    themeConfig?: ResolvedThemeConfig | null;
+    /** Initial theme from cookie (for SSR hydration) */
+    initialTheme?: Theme;
+    /** 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;
+}
+
+/**
+ * React form state type for useActionState progressive enhancement
+ */
+export type ReactFormState = unknown;
+
+/**
+ * RSC dependencies from @vitejs/plugin-rsc/rsc
+ */
+export interface RSCDependencies {
+  /**
+   * renderToReadableStream from @vitejs/plugin-rsc/rsc
+   */
+  renderToReadableStream: <T>(
+    payload: T,
+    options?: { temporaryReferences?: unknown },
+  ) => ReadableStream<Uint8Array>;
+
+  /**
+   * decodeReply from @vitejs/plugin-rsc/rsc
+   */
+  decodeReply: (
+    body: FormData | string,
+    options?: { temporaryReferences?: unknown },
+  ) => Promise<unknown[]>;
+
+  /**
+   * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc
+   */
+  createTemporaryReferenceSet: () => unknown;
+
+  /**
+   * loadServerAction from @vitejs/plugin-rsc/rsc
+   */
+  loadServerAction: (actionId: string) => Promise<Function>;
+
+  /**
+   * decodeAction from @vitejs/plugin-rsc/rsc
+   * Decodes a FormData into a bound action function (for useActionState forms)
+   */
+  decodeAction: (body: FormData) => Promise<() => Promise<unknown>>;
+
+  /**
+   * decodeFormState from @vitejs/plugin-rsc/rsc
+   * Decodes the action result into a ReactFormState for useActionState progressive enhancement
+   */
+  decodeFormState: (
+    actionResult: unknown,
+    body: FormData,
+  ) => Promise<ReactFormState | null>;
+}
+
+/**
+ * Options for SSR HTML rendering
+ */
+export interface SSRRenderOptions {
+  /**
+   * Form state for useActionState progressive enhancement.
+   * This is the result of decodeFormState() and should be passed to
+   * react-dom's renderToReadableStream to enable useActionState to
+   * receive the action result during SSR.
+   */
+  formState?: ReactFormState | null;
+
+  /**
+   * 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;
+}
+
+/**
+ * SSR module interface for HTML rendering
+ */
+export interface SSRModule {
+  renderHTML: (
+    rscStream: ReadableStream<Uint8Array>,
+    options?: SSRRenderOptions,
+  ) => Promise<ReadableStream<Uint8Array>>;
+}
+
+/**
+ * Function to load SSR module dynamically
+ */
+export type LoadSSRModule = () => Promise<SSRModule>;
+
+/**
+ * Cache configuration for handler.
+ * TTL is configured via store.defaults or cache() boundaries.
+ */
+export interface HandlerCacheConfig {
+  /** Cache store implementation */
+  store: import("../cache/types.js").SegmentCacheStore;
+  /** Enable/disable caching (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Nonce provider function type.
+ * Can return a nonce string, or true to auto-generate one.
+ */
+export type NonceProvider<TEnv = unknown> = (
+  request: Request,
+  env: TEnv,
+) => string | true | Promise<string | true>;
+
+/**
+ * Options for creating an RSC handler
+ */
+export interface CreateRSCHandlerOptions<
+  TEnv = unknown,
+  TRoutes extends Record<string, string> = Record<string, string>,
+> {
+  /**
+   * The RSC router instance
+   */
+  router: RSCRouterInternal<TEnv, TRoutes>;
+
+  /**
+   * RSC dependencies from @vitejs/plugin-rsc/rsc.
+   * Defaults to the exports from @vitejs/plugin-rsc/rsc.
+   */
+  deps?: RSCDependencies;
+
+  /**
+   * Function to load the SSR module for HTML rendering.
+   * Defaults to: () => import.meta.viteRsc.loadModule("ssr", "index")
+   */
+  loadSSRModule?: LoadSSRModule;
+
+  /**
+   * Cache configuration for segment caching.
+   *
+   * Can be a static config object or a function that receives the env
+   * (useful for accessing Cloudflare bindings).
+   *
+   * If not provided, caching is disabled. TTL is configured via store.defaults
+   * or cache() boundaries in the route definition.
+   *
+   * @example Static config
+   * ```typescript
+   * cache: {
+   *   store: new MemorySegmentCacheStore({ defaults: { ttl: 60 } }),
+   * }
+   * ```
+   *
+   * @example Dynamic config with env
+   * ```typescript
+   * cache: (env) => ({
+   *   store: new KVSegmentCacheStore(env.Bindings.MY_CACHE, { defaults: { ttl: 60 } }),
+   * })
+   * ```
+   */
+  cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
+
+  /**
+   * RSC version string included in metadata.
+   * The browser sends this back on partial requests to detect version mismatches.
+   *
+   * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
+   * Only set this if you need a custom versioning strategy.
+   *
+   * @default VERSION from rsc-router:version
+   */
+  version?: string;
+
+  /**
+   * Nonce provider for Content Security Policy (CSP).
+   *
+   * Can be:
+   * - A function that returns a nonce string
+   * - A function that returns `true` to auto-generate a nonce
+   * - 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 the typed `nonce` token:
+   * `import { nonce } from "@rangojs/router"; ctx.get(nonce)`
+   *
+   * @example Auto-generate nonce
+   * ```tsx
+   * createRSCHandler({
+   *   router,
+   *   nonce: () => true,
+   * });
+   * ```
+   *
+   * @example Custom nonce from request context
+   * ```tsx
+   * createRSCHandler({
+   *   router,
+   *   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,230 @@
+/**
+ * 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.
+ *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
+ * @example
+ * type S = { q: "string"; page: "number?"; sort: "string?" };
+ * type R = ResolveSearchSchema<S>;
+ * // { q: string | undefined; page?: number; sort?: string }
+ */
+export type ResolveSearchSchema<T extends SearchSchema> = Simplify<
+  {
+    [K in RequiredKeys<T> & string]:
+      | ResolveBaseType<BaseType<T[K]>>
+      | undefined;
+  } & {
+    [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 params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
+ */
+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) {
+      // Missing params are omitted (undefined) regardless of required/optional
+      continue;
+    }
+
+    if (baseType === "string") {
+      result[key] = raw;
+    } else if (baseType === "number") {
+      const num = Number(raw);
+      if (!Number.isNaN(num)) {
+        result[key] = num;
+      }
+      // NaN treated as missing (undefined)
+    } 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("&");
+}