@rangojs/router 0.0.0-experimental.10

package/src/href-client.ts

@@ -0,0 +1,202 @@
+/**
+ * Client-safe type-safe href function
+ *
+ * This is a compile-time only href that validates paths against registered routes.
+ * No runtime route map lookup - just an identity function with TypeScript validation.
+ *
+ * @example
+ * ```typescript
+ * import { href } from "rsc-router/client";
+ *
+ * href("/blog/my-post");           // ✓ matches /blog/:slug
+ * href("/shop/product/widget");    // ✓ matches /shop/product/:slug
+ * href("/invalid");                // ✗ TypeScript error
+ * ```
+ */
+
+import type { GetRegisteredRoutes } from "./types.js";
+import type { ResponseEnvelope } from "./urls.js";
+
+/**
+ * Parse constraint values into a union type for paths
+ * "a|b|c" → "a" | "b" | "c"
+ */
+type ParseConstraintPath<T extends string> =
+  T extends `${infer First}|${infer Rest}`
+    ? First | ParseConstraintPath<Rest>
+    : T;
+
+/**
+ * Convert a route pattern to a template literal type
+ *
+ * Supports:
+ * - Static: /about → "/about"
+ * - Dynamic: /blog/:slug → `/blog/${string}`
+ * - Optional: /:locale?/blog → "/blog" | `/${string}/blog`
+ * - Constrained: /:locale(en|gb)/blog → "/en/blog" | "/gb/blog"
+ * - Optional + Constrained: /:locale(en|gb)?/blog → "/blog" | "/en/blog" | "/gb/blog"
+ *
+ * @example
+ * PatternToPath<"/blog/:slug"> = `/blog/${string}`
+ * PatternToPath<"/:locale?/blog"> = "/blog" | `/${string}/blog`
+ * PatternToPath<"/:locale(en|gb)/blog"> = "/en/blog" | "/gb/blog"
+ * PatternToPath<"/:locale(en|gb)?/blog"> = "/blog" | "/en/blog" | "/gb/blog"
+ */
+export type PatternToPath<T extends string> =
+  // Optional + constrained param in middle: /:param(a|b)?/rest
+  T extends `${infer Before}:${infer _Name}(${infer Constraint})?/${infer After}`
+    ? PatternToPath<`${Before}${After}`> | `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+  // Optional + constrained param at end: /path/:param(a|b)?
+  : T extends `${infer Before}:${infer _Name}(${infer Constraint})?`
+    ? Before | `${Before}${ParseConstraintPath<Constraint>}`
+  // Constrained param in middle: /:param(a|b)/rest
+  : T extends `${infer Before}:${infer _Name}(${infer Constraint})/${infer After}`
+    ? `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+  // Constrained param at end: /path/:param(a|b)
+  : T extends `${infer Before}:${infer _Name}(${infer Constraint})`
+    ? `${Before}${ParseConstraintPath<Constraint>}`
+  // Optional param in middle: /:param?/rest
+  : T extends `${infer Before}:${infer _Param}?/${infer After}`
+    ? PatternToPath<`${Before}${After}`> | `${Before}${string}/${PatternToPath<After>}`
+  // Optional param at end: /path/:param?
+  : T extends `${infer Before}:${infer _Param}?`
+    ? Before | `${Before}${string}`
+  // Required param in middle: /:param/rest
+  : T extends `${infer Before}:${infer _Param}/${infer After}`
+    ? `${Before}${string}/${PatternToPath<After>}`
+  // Required param at end: /path/:param
+  : T extends `${infer Before}:${infer _Param}`
+    ? `${Before}${string}`
+  // Static path
+  : T;
+
+/**
+ * Allow optional query string (?...) and/or hash fragment (#...) suffix
+ *
+ * @example
+ * WithSuffix<"/about"> = "/about" | "/about?..." | "/about#..." | "/about?...#..."
+ */
+type WithSuffix<T extends string> =
+  | T
+  | `${T}?${string}`
+  | `${T}#${string}`
+  | `${T}?${string}#${string}`;
+
+/**
+ * Helper type to get pattern from routes, handling string values and { path, response } objects
+ */
+type RoutePattern<TRoutes, K extends keyof TRoutes> =
+  TRoutes[K] extends string ? TRoutes[K]
+  : TRoutes[K] extends { readonly path: infer P extends string } ? P
+  : string;
+
+/**
+ * Reverse lookup: find route name where the pattern matches TPattern
+ */
+type NameForPattern<
+  TPattern extends string,
+  TRoutes = GetRegisteredRoutes
+> = {
+  [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern ? K : never
+}[keyof TRoutes];
+
+/**
+ * Look up the response data type for a route pattern from RegisteredRoutes.
+ *
+ * Works by reverse-looking up the route name for the given pattern,
+ * then extracting the response type from the route entry.
+ *
+ * For static routes (no params), pattern === path:
+ *   PathResponse<"/api/health"> → { status: string; timestamp: number }
+ *
+ * For dynamic routes, use the pattern:
+ *   PathResponse<"/api/products/:id"> → Product
+ */
+export type PathResponse<TPattern extends string, TRoutes = GetRegisteredRoutes> =
+  ResponseEnvelope<{
+    [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern
+      ? TRoutes[K] extends { readonly response: infer R } ? Exclude<R, Response> : never
+      : never
+  }[keyof TRoutes]>;
+
+/**
+ * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
+ * Allows navigation to include() prefixes without requiring trailing slash
+ */
+type OptionalTrailingSlash<T extends string> =
+  T extends `${infer Base}/` ? (Base extends "" ? T : Base | T) : T;
+
+/**
+ * Union of all valid paths from registered routes
+ *
+ * Generated from RSCRouter.RegisteredRoutes via module augmentation.
+ * Allows optional query strings and hash fragments.
+ */
+export type ValidPaths<TRoutes = GetRegisteredRoutes> =
+  keyof TRoutes extends never
+    ? `/${string}` // Fallback when no routes are registered
+    : WithSuffix<{
+        [K in keyof TRoutes]: OptionalTrailingSlash<PatternToPath<RoutePattern<TRoutes, K>>>
+      }[keyof TRoutes]>;
+
+/**
+ * Type-safe href function for client-side use
+ *
+ * Without mount: identity function, validates absolute paths at compile time.
+ * With mount: prepends mount path, for use with useMount() inside include() scopes.
+ *
+ * @param path - A valid path matching one of the registered route patterns
+ * @param mount - Optional mount prefix from useMount() for include-scoped paths
+ * @returns The resolved path
+ *
+ * @example
+ * ```typescript
+ * // Absolute paths (type-safe)
+ * href("/blog/hello");           // "/blog/hello"
+ * href("/shop/product/widget");  // "/shop/product/widget"
+ *
+ * // With mount (inside an include)
+ * const mount = useMount();      // "/articles"
+ * href("/", mount);              // "/articles/"
+ * href("/my-post", mount);       // "/articles/my-post"
+ *
+ * // Query strings and hashes pass through
+ * href("/blog/hello?page=1");
+ * href("/about#contact");
+ * ```
+ */
+export function href<T extends ValidPaths>(path: T, mount?: string): string {
+  if (mount && mount !== "/") {
+    return mount + path;
+  }
+  return path;
+}
+
+/**
+ * Props shape returned by href.json() etc. for spreading on <Link>.
+ * Sets data-external to trigger hard navigation (skips RSC fetch).
+ */
+export interface ResponseHrefProps {
+  to: string;
+  "data-external": "";
+}
+
+type ResponseHrefFn = <T extends ValidPaths>(path: T, mount?: string) => ResponseHrefProps;
+
+function createResponseHrefTag(): ResponseHrefFn {
+  return (path, mount) => ({
+    to: href(path, mount),
+    "data-external": "" as const,
+  });
+}
+
+export namespace href {
+  export const json: ResponseHrefFn = createResponseHrefTag();
+  export const text: ResponseHrefFn = createResponseHrefTag();
+  export const html: ResponseHrefFn = createResponseHrefTag();
+  export const xml: ResponseHrefFn = createResponseHrefTag();
+  export const md: ResponseHrefFn = createResponseHrefTag();
+  export const image: ResponseHrefFn = createResponseHrefTag();
+  export const stream: ResponseHrefFn = createResponseHrefTag();
+  export const any: ResponseHrefFn = createResponseHrefTag();
+}

package/src/href-context.ts

@@ -0,0 +1,33 @@
+"use client";
+
+/**
+ * Href Context for route name resolution
+ *
+ * This module is marked "use client" so it can be imported by both:
+ * - Server (segment-system): Gets a client reference for createElement
+ * - Client (useHref): Uses the actual context for useContext
+ *
+ * The context stores:
+ * - routeMap: Map of route names to URL patterns
+ * - routeName: Current matched route name (for local name resolution)
+ */
+import { createContext, type Context } from "react";
+
+/**
+ * Context value for href resolution
+ */
+export interface HrefContextValue {
+  /** Route map: route name -> URL pattern */
+  routeMap: Record<string, string>;
+  /** Current matched route name (includes name prefix from include()) */
+  routeName?: string;
+}
+
+/**
+ * Context for href resolution (route map and current route name)
+ *
+ * On the server: Populated by renderSegments() via HrefContext.Provider
+ * On the client: Populated by NavigationProvider from RSC metadata
+ */
+export const HrefContext: Context<HrefContextValue | null> =
+  createContext<HrefContextValue | null>(null);

package/src/index.rsc.ts

@@ -0,0 +1,121 @@
+/**
+ * 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,
+  RouterError,
+} from "./index.js";
+
+// Re-export all types from types.ts (user-facing types only)
+export type {
+  // Configuration types
+  DocumentProps,
+  RouterEnv,
+  DefaultEnv,
+  RouteDefinition,
+  // Handler types
+  Handler,
+  ScopedRouteMap,
+  HandlerContext,
+  ExtractParams,
+  GenericParams,
+  // Middleware types
+  Middleware,
+  // Revalidation types
+  RevalidateParams,
+  Revalidate,
+  RouteKeys,
+  // Loader types
+  LoaderDefinition,
+  LoaderFn,
+  LoaderContext,
+  FetchableLoaderOptions,
+  LoadOptions,
+  LoaderActionContext,
+  LoaderAction,
+  LoaderMiddlewareFn,
+  // Error boundary types
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  // NotFound boundary types
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+} from "./types.js";
+
+// Router options type (server-only, so import directly)
+export type { RSCRouterOptions } from "./router.js";
+
+// Server-side createLoader and redirect
+export { createLoader, redirect } from "./route-definition.js";
+
+// Handle API
+export { createHandle, isHandle, type Handle } from "./handle.js";
+
+// Pre-render handler API
+export {
+  createPrerenderHandler,
+  isPrerenderHandler,
+  type PrerenderHandlerDefinition,
+  type PrerenderOptions,
+  type BuildContext,
+} from "./prerender.js";
+
+// Django-style URL patterns (RSC/server context)
+export {
+  urls,
+  type PathHelpers,
+  type PathOptions,
+  type UrlPatterns,
+  type IncludeOptions,
+  type IncludeItem,
+  type RouteResponse,
+  type ResponseError,
+  type ResponseEnvelope,
+} from "./urls.js";
+
+// Core router (server-side)
+export {
+  createRouter,
+  type RSCRouter,
+  type RootLayoutProps,
+} from "./router.js";
+
+// RSC handler types (server-side)
+export type { HandlerCacheConfig } from "./rsc/types.js";
+
+// Built-in handles (server-side)
+export { Meta } from "./handles/meta.js";
+
+// Request context (for accessing request data in server actions/components)
+export { getRequestContext, type RequestContext } from "./server/request-context.js";
+
+// Meta types
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+
+// Reverse type utilities for type-safe URL generation (Django-style URL reversal)
+export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes } from "./reverse.js";
+export { scopedReverse } from "./reverse.js";

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * rsc-router
+ *
+ * Universal exports - types and utilities safe for both server and client
+ *
+ * For server-only exports (urls, createRouter, createLoader, 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,
+  RouterError,
+} from "./errors.js";
+
+// Types (safe to import anywhere - no runtime code)
+export type {
+  // Configuration types
+  DocumentProps,
+  RouterEnv,
+  DefaultEnv,
+  RouteDefinition,
+  // Handler types
+  Handler,            // Supports params object, path pattern, or route name
+  ScopedRouteMap,     // Scoped view of GeneratedRouteMap for Handler<"localName", ScopedRouteMap<"prefix">>
+  HandlerContext,
+  ExtractParams,
+  GenericParams,
+  // Middleware types
+  Middleware,
+  // Revalidation types
+  RevalidateParams,
+  Revalidate,
+  RouteKeys,
+  // Loader types
+  LoaderDefinition,
+  LoaderFn,
+  LoaderContext,
+  FetchableLoaderOptions,
+  LoadOptions,
+  LoaderActionContext,
+  LoaderAction,
+  LoaderMiddlewareFn,
+  // Error boundary types
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  // NotFound boundary types
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+} from "./types.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";
+
+// Response route types (usable in both server and client contexts)
+export type {
+  ResponseHandler,
+  ResponseHandlerContext,
+  JsonResponseHandler,
+  TextResponseHandler,
+  JsonValue,
+  ResponsePathFn,
+  JsonResponsePathFn,
+  TextResponsePathFn,
+  RouteResponse,
+  ResponseError,
+  ResponseEnvelope,
+} from "./urls.js";
+
+/**
+ * Error-throwing stub for server-only `urls` function.
+ * Import from "@rangojs/router/server" or use within RSC context instead.
+ */
+export function urls(): never {
+  throw new Error(
+    'urls() is server-only. Import from "@rangojs/router/server" instead, or ensure you\'re using it in a server component.'
+  );
+}
+
+/**
+ * Error-throwing stub for server-only `createRouter` function.
+ * Import from "@rangojs/router/server" instead.
+ */
+export function createRouter(): never {
+  throw new Error(
+    'createRouter() is server-only. Import from "@rangojs/router/server" instead.'
+  );
+}
+
+/**
+ * Error-throwing stub for server-only `redirect` function.
+ * Import from "@rangojs/router/server" or use within RSC context instead.
+ */
+export function redirect(): never {
+  throw new Error(
+    'redirect() is server-only. Import from "@rangojs/router/server" instead.'
+  );
+}
+
+/**
+ * Error-throwing stub for server-only `createHandle` function.
+ * Import from "@rangojs/router/server" or use within RSC context instead.
+ */
+export function createHandle(): never {
+  throw new Error(
+    'createHandle() is server-only. Import from "@rangojs/router/server" instead.'
+  );
+}
+
+/**
+ * Error-throwing stub for server-only `createPrerenderHandler` function.
+ * Import from "@rangojs/router/server" or use within RSC context instead.
+ */
+export function createPrerenderHandler(): never {
+  throw new Error(
+    'createPrerenderHandler() is server-only. Import from "@rangojs/router/server" instead.'
+  );
+}
+
+// Handle API (type-only exports safe for client)
+export { isHandle, type Handle } from "./handle.js";
+
+/**
+ * Error-throwing stub for server-only `getRequestContext` function.
+ * Import from "@rangojs/router/server" or use within RSC context instead.
+ */
+export function getRequestContext(): never {
+  throw new Error(
+    'getRequestContext() is server-only. Import from "@rangojs/router/server" instead.'
+  );
+}
+
+// Request context type (safe for client)
+export type { RequestContext } from "./server/request-context.js";
+
+// Meta types
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+
+// Reverse type utilities for type-safe URL generation (Django-style URL reversal)
+// ScopedReverseFunction is used with scopedReverse<typeof patterns>() for composable modules
+export type { ScopedReverseFunction, ReverseFunction, ExtractLocalRoutes } from "./reverse.js";
+// scopedReverse() helper for handlers to get locally-typed reverse
+export { scopedReverse } from "./reverse.js";
+
+// Path-based response type lookup from RegisteredRoutes
+export type { PathResponse } from "./href-client.js";