@rangojs/router 0.0.0-experimental.2

package/src/href.ts

@@ -0,0 +1,177 @@
+import type { ExtractParams } from "./types.js";
+
+/**
+ * Sanitize prefix string by removing leading slash
+ * "/shop" -> "shop", "blog" -> "blog", "" -> ""
+ */
+export type SanitizePrefix<T extends string> = T extends `/${infer P}` ? P : T;
+
+/**
+ * Helper type to merge multiple route definitions into a single accumulated type.
+ * Note: When using createRSCRouter, types accumulate automatically through the
+ * builder chain, so this type is typically not needed.
+ *
+ * @example
+ * ```typescript
+ * // Manual type merging (rarely needed):
+ * type AppRoutes = MergeRoutes<[
+ *   typeof homeRoutes,
+ *   PrefixRoutePatterns<typeof blogRoutes, "/blog">,
+ * ]>;
+ *
+ * // Preferred: Let router accumulate types automatically
+ * const router = createRSCRouter<AppEnv>()
+ *   .routes(homeRoutes).map(...)
+ *   .routes("/blog", blogRoutes).map(...);
+ * type AppRoutes = typeof router.routeMap;
+ * ```
+ */
+export type MergeRoutes<T extends Record<string, string>[]> = T extends [
+  infer First extends Record<string, string>,
+  ...infer Rest extends Record<string, string>[]
+]
+  ? First & MergeRoutes<Rest>
+  : {};
+
+/**
+ * Add key prefix to all entries in a route map
+ * { "cart": "/cart" } with prefix "shop" -> { "shop.cart": "/shop/cart" }
+ */
+export type PrefixRouteKeys<
+  T extends Record<string, string>,
+  Prefix extends string
+> = Prefix extends ""
+  ? T
+  : { [K in keyof T as `${Prefix}.${K & string}`]: T[K] };
+
+/**
+ * Add path prefix to all patterns in a route map
+ * { "cart": "/cart" } with prefix "/shop" -> { "cart": "/shop/cart" }
+ */
+export type PrefixRoutePatterns<
+  T extends Record<string, string>,
+  PathPrefix extends string
+> = {
+  [K in keyof T]: PathPrefix extends "" | "/"
+    ? T[K]
+    : T[K] extends "/"
+      ? PathPrefix
+      : `${PathPrefix}${T[K]}`;
+};
+
+/**
+ * Combined: prefix both keys and patterns
+ * Used for module augmentation registration
+ *
+ * @example
+ * ```typescript
+ * // Given shopRoutes = { "index": "/", "cart": "/cart", "products.detail": "/product/:slug" }
+ * // PrefixedRoutes<typeof shopRoutes, "shop"> produces:
+ * // { "shop.index": "/shop", "shop.cart": "/shop/cart", "shop.products.detail": "/shop/product/:slug" }
+ * ```
+ */
+export type PrefixedRoutes<
+  T extends Record<string, string>,
+  KeyPrefix extends string,
+  PathPrefix extends string = KeyPrefix extends "" ? "" : `/${KeyPrefix}`
+> = PrefixRouteKeys<PrefixRoutePatterns<T, PathPrefix>, KeyPrefix>;
+
+/**
+ * Extract params type for a route
+ */
+export type ParamsFor<
+  TRoutes extends Record<string, string>,
+  TName extends keyof TRoutes
+> = TRoutes[TName] extends string ? ExtractParams<TRoutes[TName]> : never;
+
+/**
+ * Check if an object type has any keys
+ */
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+
+/**
+ * Type-safe href function signature
+ * Provides overloads for routes with and without params
+ */
+export type HrefFunction<TRoutes extends Record<string, string>> = {
+  // Overload 1: Routes without params - second arg optional
+  <TName extends keyof TRoutes & string>(
+    name: IsEmptyObject<ParamsFor<TRoutes, TName>> extends true ? TName : never
+  ): string;
+
+  // Overload 2: Routes with params - params required
+  <TName extends keyof TRoutes & string>(
+    name: TName,
+    params: ParamsFor<TRoutes, TName>
+  ): string;
+};
+
+/**
+ * Type-safe scoped href function signature for use with useHref<typeof patterns>()
+ * Accepts local route names (from the patterns), absolute names (with dot), or path-based URLs.
+ *
+ * @example
+ * ```typescript
+ * // In a component rendered by blog routes:
+ * const href = useHref<typeof blogPatterns>();
+ *
+ * href("index")                    // Local name → resolved with current prefix
+ * href("post", { slug: "hello" })  // Local name with params
+ * href("shop.cart")                // Absolute name → global lookup
+ * href("/about")                   // Path-based → used directly
+ * ```
+ */
+export type ScopedHrefFunction<TLocalRoutes extends Record<string, string>> = {
+  // Overload 1: Local routes without params
+  <TName extends keyof TLocalRoutes & string>(
+    name: IsEmptyObject<ParamsFor<TLocalRoutes, TName>> extends true ? TName : never
+  ): string;
+
+  // Overload 2: Local routes with params
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName,
+    params: ParamsFor<TLocalRoutes, TName>
+  ): string;
+
+  // Overload 3: Absolute name (contains dot) - global lookup
+  (name: `${string}.${string}`, params?: Record<string, string>): string;
+
+  // Overload 4: Path-based URL - used directly
+  (name: `/${string}`, params?: Record<string, string>): string;
+};
+
+/**
+ * Create a type-safe href function for URL generation
+ *
+ * @param routeMap - Flattened route map with all registered routes
+ * @returns Type-safe href function
+ *
+ * @example
+ * ```typescript
+ * // Given routes: { cart: "/shop/cart", detail: "/shop/product/:slug" }
+ * const href = createHref(routeMap);
+ * href("cart"); // "/shop/cart"
+ * href("detail", { slug: "my-product" }); // "/shop/product/my-product"
+ * ```
+ */
+export function createHref<TRoutes extends Record<string, string>>(
+  routeMap: TRoutes
+): HrefFunction<TRoutes> {
+  return ((name: string, params?: Record<string, string>) => {
+    const pattern = routeMap[name];
+    if (!pattern) {
+      throw new Error(`Unknown route: ${name}`);
+    }
+
+    if (!params) return pattern;
+
+    // Replace :param placeholders with actual values
+    return pattern.replace(/:([^/]+)/g, (_, key) => {
+      const value = params[key];
+      if (value === undefined) {
+        throw new Error(`Missing param "${key}" for route "${name}"`);
+      }
+      return encodeURIComponent(value);
+    });
+  }) as HrefFunction<TRoutes>;
+}

package/src/index.rsc.ts

@@ -0,0 +1,79 @@
+/**
+ * rsc-router (react-server environment)
+ *
+ * This file is used when importing "rsc-router" from RSC (server components).
+ * It re-exports everything from the universal index.ts plus adds server-side
+ * createLoader that includes the actual loader function.
+ *
+ * The bundler uses the "react-server" export condition to select this file
+ * in RSC context, while the regular index.ts is used in client components.
+ */
+
+// Re-export all universal exports from index.ts
+export {
+  // Universal rendering utilities
+  renderSegments,
+  // Error classes
+  RouteNotFoundError,
+  DataNotFoundError,
+  notFound,
+  MiddlewareError,
+  HandlerError,
+  BuildError,
+  InvalidHandlerError,
+  NetworkError,
+  isNetworkError,
+  sanitizeError,
+  // Route pattern definition
+  route,
+} from "./index.js";
+
+// Re-export all types from index.ts
+export type {
+  RouterEnv,
+  DefaultEnv,
+  RouteDefinition,
+  ResolvedRouteMap,
+  Handler,
+  HandlerContext,
+  HandlersForRouteMap,
+  ResolvedSegment,
+  SegmentMetadata,
+  MatchResult,
+  ExtractParams,
+  GenericParams,
+  RevalidateParams,
+  ShouldRevalidateFn,
+  MiddlewareFn,
+  RouteKeys,
+  RouteHandler,
+  RouteRevalidateFn,
+  RouteMiddlewareFn,
+  LoaderDefinition,
+  LoaderFn,
+  LoaderContext,
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+  RSCRouterOptions,
+  PerformanceMetric,
+  MetricsStore,
+} from "./index.js";
+
+// Server-side createLoader - includes the actual loader function
+// This is the key addition for RSC context
+export { createLoader } from "./route-definition.js";
+
+// Django-style URL patterns (RSC/server context)
+export {
+  urls,
+  type PathHelpers,
+  type PathOptions,
+  type UrlPatterns,
+  type IncludeOptions,
+  type IncludeItem,
+} from "./urls.js";

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * rsc-router
+ *
+ * Universal exports - types and utilities safe for both server and client
+ *
+ * For server-only exports (route, map, createRSCRouter, etc.):
+ *   import from "rsc-router/server"
+ *
+ * For client-only exports (Outlet, useOutlet, etc.):
+ *   import from "rsc-router/client"
+ */
+
+// Universal rendering utilities (work on both server and client)
+export { renderSegments } from "./segment-system.js";
+
+// Error classes (can be used on both server and client)
+export {
+  RouteNotFoundError,
+  DataNotFoundError,
+  notFound,
+  MiddlewareError,
+  HandlerError,
+  BuildError,
+  InvalidHandlerError,
+  NetworkError,
+  isNetworkError,
+  sanitizeError,
+} from "./errors.js";
+
+// Types (safe to import anywhere - no runtime code)
+export type {
+  DocumentProps,
+  RouterEnv,
+  DefaultEnv,
+  RouteDefinition,
+  ResolvedRouteMap,
+  Handler,
+  HandlerContext,
+  HandlersForRouteMap,
+  ResolvedSegment,
+  SegmentMetadata,
+  MatchResult,
+  ExtractParams,
+  GenericParams,
+  RevalidateParams,
+  ShouldRevalidateFn,
+  MiddlewareFn,
+  RouteKeys,
+  RouteHandler,
+  RouteRevalidateFn,
+  RouteMiddlewareFn,
+  LoaderDefinition,
+  LoaderFn,
+  LoaderContext,
+  // Fetchable loader types
+  FetchableLoaderOptions,
+  LoadOptions,
+  LoaderActionContext,
+  LoaderAction,
+  LoaderMiddlewareFn,
+  // Error boundary types
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  // NotFound boundary types
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+} from "./types.js";
+
+// Router options type
+export type { RSCRouterOptions } from "./router.js";
+
+// Metrics types
+export type { PerformanceMetric, MetricsStore } from "./server/context.js";
+
+// Client-safe createLoader - only stores the $$id, function is not included
+// Use this when defining loaders that will be imported by client components
+export { createLoader } from "./loader.js";
+
+// Route pattern definition helper
+// Used to define route patterns in a shared routes.ts file
+export { route } from "./route-utils.js";
+
+// Django-style URL patterns API - types only (urls() is in /server)
+export type { UrlPatterns, PathHelpers } from "./urls.js";

package/src/loader.rsc.ts

@@ -0,0 +1,204 @@
+/**
+ * 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, return a simple stub with fn included
+  if (fetchable === undefined) {
+    return {
+      __brand: "loader",
+      $$id: loaderId,
+      fn: fn as LoaderFn<Awaited<T>, Record<string, string | undefined>, any>,
+    };
+  }
+
+  // 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 loader object with action for form-based fetching
+  // The exposeLoaderId plugin will set $$id on this object
+  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);