@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/reverse.ts

@@ -1,6 +1,7 @@
 import type { ExtractParams } from "./types.js";
 import type { SearchSchema, ResolveSearchSchema } from "./search-params.js";
 import { serializeSearchParams } from "./search-params.js";
+import { substitutePatternParams } from "./router/substitute-pattern-params.js";
 
 /**
  * Sanitize prefix string by removing leading slash
@@ -10,92 +11,38 @@ 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 createRouter, 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 = createRouter<AppEnv>()
- *   .routes(homeRoutes).map(...)
- *   .routes("/blog", blogRoutes).map(...);
- * type AppRoutes = typeof router.routeMap;
+ * type AppRoutes = MergeRoutes<[typeof siteRoutes, typeof apiRoutes]>;
  * ```
  */
 export type MergeRoutes<T extends unknown[]> = T extends [
   infer First,
-  ...infer Rest
+  ...infer Rest,
 ]
   ? 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,
-  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,
-  PathPrefix extends string
-> = {
-  [K in keyof T]: PathPrefix extends "" | "/"
-    ? T[K]
-    : T[K] extends "/"
-      ? PathPrefix
-      : T[K] extends string
-        ? `${PathPrefix}${T[K]}`
-        : 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,
-  KeyPrefix extends string,
-  PathPrefix extends string = KeyPrefix extends "" ? "" : `/${KeyPrefix}`
-> = PrefixRouteKeys<PrefixRoutePatterns<T, PathPrefix>, KeyPrefix>;
-
 /**
  * Helper to safely extract route patterns from a routes object
  * Handles string values, { path, response } objects, and interface types (like RegisteredRoutes)
  */
-type RoutePatternFor<TRoutes, TName extends keyof TRoutes> =
-  TRoutes[TName] extends string ? TRoutes[TName]
-  : TRoutes[TName] extends { readonly path: infer P extends string } ? P
-  : string;
+type RoutePatternFor<
+  TRoutes,
+  TName extends keyof TRoutes,
+> = TRoutes[TName] extends string
+  ? TRoutes[TName]
+  : TRoutes[TName] extends { readonly path: infer P extends string }
+    ? P
+    : string;
 
 /**
  * Extract params type for a route
  */
-export type ParamsFor<
-  TRoutes,
-  TName extends keyof TRoutes
-> = ExtractParams<RoutePatternFor<TRoutes, TName>>;
+export type ParamsFor<TRoutes, TName extends keyof TRoutes> = ExtractParams<
+  RoutePatternFor<TRoutes, TName>
+>;
 
 /**
  * Check if an object type has any keys
@@ -106,10 +53,12 @@ type IsEmptyObject<T> = keyof T extends never ? true : false;
  * Extract search schema from a route entry.
  * Returns {} if no search schema is defined.
  */
-type ExtractSearchSchema<TRoutes, TName extends keyof TRoutes> =
-  TRoutes[TName] extends { readonly search: infer S extends SearchSchema }
-    ? S
-    : {};
+type ExtractSearchSchema<
+  TRoutes,
+  TName extends keyof TRoutes,
+> = TRoutes[TName] extends { readonly search: infer S extends SearchSchema }
+  ? S
+  : {};
 
 /**
  * Type-safe reverse function signature (Django-style URL reversal)
@@ -128,7 +77,11 @@ export type ReverseFunction<TRoutes> = {
    * Route without params - validates route name exists
    */
   <TName extends keyof TRoutes & string>(
-    name: IsEmptyObject<ExtractParams<RoutePatternFor<TRoutes, TName>>> extends true ? TName : never
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TRoutes, TName>>
+    > extends true
+      ? TName
+      : never,
   ): string;
 
   /**
@@ -136,7 +89,7 @@ export type ReverseFunction<TRoutes> = {
    */
   <TName extends keyof TRoutes & string>(
     name: TName,
-    params: ExtractParams<RoutePatternFor<TRoutes, TName>>
+    params: ExtractParams<RoutePatternFor<TRoutes, TName>>,
   ): string;
 
   /**
@@ -145,48 +98,112 @@ export type ReverseFunction<TRoutes> = {
   <TName extends keyof TRoutes & string>(
     name: TName,
     params: ExtractParams<RoutePatternFor<TRoutes, TName>>,
-    search: ResolveSearchSchema<ExtractSearchSchema<TRoutes, TName>>
+    search: ResolveSearchSchema<ExtractSearchSchema<TRoutes, TName>>,
+  ): string;
+
+  /**
+   * Dot-prefixed route without params - strictly local resolution
+   */
+  <TName extends keyof TRoutes & string>(
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TRoutes, TName>>
+    > extends true
+      ? `.${TName}`
+      : never,
+  ): string;
+
+  /**
+   * Dot-prefixed route with params - strictly local resolution
+   */
+  <TName extends keyof TRoutes & string>(
+    name: `.${TName}`,
+    params: ExtractParams<RoutePatternFor<TRoutes, TName>>,
+  ): string;
+
+  /**
+   * Dot-prefixed route with params and search - strictly local resolution
+   */
+  <TName extends keyof TRoutes & string>(
+    name: `.${TName}`,
+    params: ExtractParams<RoutePatternFor<TRoutes, TName>>,
+    search: ResolveSearchSchema<ExtractSearchSchema<TRoutes, TName>>,
   ): string;
 };
 
 /**
- * Type-safe scoped reverse function that validates all route names and params.
+ * Type-safe scoped reverse function with separate local and global namespaces.
  *
- * When used via HandlerContext or scopedReverse(), local routes are merged with
- * global RegisteredRoutes so all names are fully type-checked.
+ * - `.name` — local resolution within the current include() scope
+ * - `name` — global resolution against the named-routes definition
  *
  * @example
  * ```typescript
- * reverse("cart")                           // ✓ Validates local route
- * reverse("blog.post", { slug: "hello" })   // ✓ Validates global route + params
- * reverse("typo")                           // ✗ Compile error
+ * reverse(".article", { slug: "hello" })     // ✓ Local route (resolves with mount prefix)
+ * reverse(".index")                           // ✓ Local route (no params)
+ * reverse("magazine.index")                   // ✓ Global route (fully qualified)
+ * reverse("blog.post", { slug: "hello" })     // ✓ Global route + params
+ * reverse(".typo")                            // ✗ Compile error (not in local routes)
+ * reverse("typo")                             // ✗ Compile error (not in global routes)
  * ```
  */
-export type ScopedReverseFunction<TLocalRoutes> = {
+export type ScopedReverseFunction<
+  TLocalRoutes,
+  TGlobalRoutes = TLocalRoutes,
+> = {
   /**
-   * Route without params - validates route name exists
-   * @recommended Use this for type-safe URL generation
+   * Global route without params
+   */
+  <TName extends keyof TGlobalRoutes & string>(
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>
+    > extends true
+      ? TName
+      : never,
+  ): string;
+
+  /**
+   * Global route with params
+   */
+  <TName extends keyof TGlobalRoutes & string>(
+    name: TName,
+    params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>,
+  ): string;
+
+  /**
+   * Global route with params and search
+   */
+  <TName extends keyof TGlobalRoutes & string>(
+    name: TName,
+    params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>,
+    search: ResolveSearchSchema<ExtractSearchSchema<TGlobalRoutes, TName>>,
+  ): string;
+
+  /**
+   * Dot-prefixed local route without params
    */
   <TName extends keyof TLocalRoutes & string>(
-    name: IsEmptyObject<ExtractParams<RoutePatternFor<TLocalRoutes, TName>>> extends true ? TName : never
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
+    > extends true
+      ? `.${TName}`
+      : never,
   ): string;
 
   /**
-   * Route with params - validates both route name and params
-   * @recommended Use this for type-safe URL generation with parameters
+   * Dot-prefixed local route with params
    */
   <TName extends keyof TLocalRoutes & string>(
-    name: TName,
-    params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
+    name: `.${TName}`,
+    params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>,
   ): string;
 
   /**
-   * Route with params and search - validates route name, params, and search
+   * Dot-prefixed local route with params and search
    */
   <TName extends keyof TLocalRoutes & string>(
-    name: TName,
+    name: `.${TName}`,
     params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>,
-    search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>
+    search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
   ): string;
 };
 
@@ -194,12 +211,74 @@ export type ScopedReverseFunction<TLocalRoutes> = {
  * Extract local routes type from UrlPatterns
  * Used with scopedReverse() to get the routes type from patterns
  */
-export type ExtractLocalRoutes<TPatterns> =
-  TPatterns extends { readonly _routes?: infer TRoutes }
-    ? TRoutes
-    : TPatterns extends Record<string, string>
-      ? TPatterns
-      : Record<string, string>;
+export type ExtractLocalRoutes<TPatterns> = TPatterns extends {
+  readonly _routes?: infer TRoutes;
+}
+  ? TRoutes
+  : TPatterns extends Record<string, string>
+    ? TPatterns
+    : Record<string, string>;
+
+/**
+ * Params accepted by `useReverse(routes)`. The route's own params are
+ * required, and additional string keys are permitted so callers can
+ * override values that would otherwise be auto-filled from the matched
+ * route's `useParams()` (e.g. an enclosing `:tenantId` mount segment).
+ */
+export type LocalReverseParams<TPattern extends string> =
+  ExtractParams<TPattern> & {
+    readonly [extra: string]: string | undefined;
+  };
+
+/**
+ * Type-safe local reverse function.
+ *
+ * Returned by `useReverse(routes)` on the client. The route map is the
+ * exposure boundary (a generated `routes` from a `urls()` module) and the
+ * scope is implicit from that import. Names may be written with or without a
+ * leading dot — `reverse("post")` and `reverse(".post")` are identical. The dot
+ * is a cosmetic readability convention (and parity with `ctx.reverse(".name")`);
+ * there is no separate global namespace here, so it carries no meaning.
+ *
+ * @example
+ * ```typescript
+ * const reverse = useReverse(blogRoutes);
+ * reverse("index");                          // ✓ no params (dot optional)
+ * reverse(".index");                         // ✓ identical to the above
+ * reverse("post", { postId: "hello" });      // ✓ with params
+ * reverse("search", {}, { q: "hi" });        // ✓ with search schema
+ * reverse("typo");                           // ✗ compile error
+ * ```
+ */
+export type LocalReverseFunction<TLocalRoutes> = {
+  /**
+   * Route without params (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
+    > extends true
+      ? TName | `.${TName}`
+      : never,
+  ): string;
+
+  /**
+   * Route with params (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName | `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+  ): string;
+
+  /**
+   * Route with params and search (leading dot optional)
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName | `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+    search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
+  ): string;
+};
 
 /**
  * Extract the response data type for a named route from a UrlPatterns instance.
@@ -210,24 +289,23 @@ export type { RouteResponse } from "./urls.js";
 /**
  * Get a locally-typed reverse function from ctx.reverse for composable modules.
  *
- * This is a type-only cast - ctx.reverse already resolves local names at runtime
- * based on the current route prefix. This helper just provides type safety
- * for local route names within a url module.
+ * This is a type-only cast - ctx.reverse already resolves names at runtime.
+ * Provides type safety: `.name` validates against local routes,
+ * `name` validates against global named-routes.
  *
  * @param reverse - The ctx.reverse function from HandlerContext
- * @returns The same reverse function, but typed for local routes
+ * @returns The same reverse function, typed with local + global routes
  *
  * @example
  * ```typescript
  * // urls/blog.tsx
  * export const blogPatterns = urls(({ path }) => [
  *   path("/", (ctx) => {
- *     // Get locally-typed reverse for this module's routes
  *     const reverse = scopedReverse<typeof blogPatterns>(ctx.reverse);
  *
- *     reverse("index");              // ✓ Type-safe local route
- *     reverse("post", { slug: "x" }); // ✓ Type-safe with params
- *     reverse("shop.cart");          // ✓ Type-safe global route
+ *     reverse(".index");              // ✓ Local route
+ *     reverse(".post", { slug: "x" }); // ✓ Local with params
+ *     reverse("shop.cart");           // ✓ Global route
  *
  *     return <BlogIndex />;
  *   }, { name: "index" }),
@@ -237,7 +315,7 @@ export type { RouteResponse } from "./urls.js";
  * ```
  */
 export function scopedReverse<TPatterns>(
-  reverse: ((...args: any[]) => string)
+  reverse: (...args: any[]) => string,
 ): ScopedReverseFunction<ExtractLocalRoutes<TPatterns>> {
   return reverse as ScopedReverseFunction<ExtractLocalRoutes<TPatterns>>;
 }
@@ -258,24 +336,24 @@ export function scopedReverse<TPatterns>(
  */
 type RouteMapEntry = string | { path: string; search?: Record<string, string> };
 
-function resolveRoutePattern(entry: RouteMapEntry | undefined): string | undefined {
+function resolveRoutePattern(
+  entry: RouteMapEntry | undefined,
+): string | undefined {
   if (!entry) return undefined;
   return typeof entry === "string" ? entry : entry.path;
 }
 
 export function createReverse<TRoutes extends Record<string, string>>(
   routeMap: TRoutes,
-  getFallbackMap?: () => Record<string, RouteMapEntry> | undefined,
 ): ReverseFunction<TRoutes & Record<string, string>> {
-  return ((name: string, params?: Record<string, string>, search?: Record<string, unknown>) => {
-    let pattern = resolveRoutePattern(routeMap[name] as unknown as RouteMapEntry);
-    if (!pattern) {
-      // Try the static route names from the generated file (O(1) fallback)
-      const fallback = getFallbackMap?.();
-      if (fallback) {
-        pattern = resolveRoutePattern(fallback[name]);
-      }
-    }
+  return ((
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => {
+    const pattern = resolveRoutePattern(
+      routeMap[name] as unknown as RouteMapEntry,
+    );
     if (!pattern) {
       // During build-time discovery, lazy includes haven't resolved yet.
       // Return a placeholder instead of crashing the build.
@@ -285,17 +363,9 @@ export function createReverse<TRoutes extends Record<string, string>>(
       throw new Error(`Unknown route: ${name}`);
     }
 
-    let result = pattern;
-    if (params) {
-      // Replace :param placeholders with actual values
-      result = result.replace(/:([^/]+)/g, (_: string, key: string) => {
-        const value = params[key];
-        if (value === undefined) {
-          throw new Error(`Missing param "${key}" for route "${name}"`);
-        }
-        return encodeURIComponent(value);
-      });
-    }
+    let result = params
+      ? substitutePatternParams(pattern, params, name)
+      : pattern;
 
     // Append search params as query string
     if (search) {

package/src/root-error-boundary.tsx

@@ -3,26 +3,17 @@
 import { Component, useState, type ReactNode } from "react";
 import type { ClientErrorBoundaryFallbackProps } from "./types.js";
 
-/**
- * Check if an error is a network-related error
- */
 function isNetworkError(error: Error): boolean {
   return error.name === "NetworkError";
 }
 
-/**
- * Network error fallback UI with retry functionality
- * Shows a connection-specific message and allows retrying via page refresh
- */
 function NetworkErrorFallback({
   error,
-  reset,
 }: ClientErrorBoundaryFallbackProps): ReactNode {
   const [isRetrying, setIsRetrying] = useState(false);
 
   const handleRetry = (): void => {
     setIsRetrying(true);
-    // Refresh the page to retry the request
     window.location.reload();
   };
 
@@ -42,7 +33,6 @@ function NetworkErrorFallback({
           marginBottom: "1rem",
         }}
       >
-        {/* Simple cloud with x icon using CSS */}
         <span style={{ color: "#9ca3af" }}>&#9729;</span>
       </div>
       <h1
@@ -60,7 +50,8 @@ function NetworkErrorFallback({
           marginBottom: "1.5rem",
         }}
       >
-        {error.message || "Unable to connect to the server. Please check your internet connection."}
+        {error.message ||
+          "Unable to connect to the server. Please check your internet connection."}
       </p>
       <div style={{ display: "flex", gap: "1rem", justifyContent: "center" }}>
         <button
@@ -100,11 +91,12 @@ function NetworkErrorFallback({
   );
 }
 
-/**
- * Default fallback UI for root error boundary
- * This is shown when an unhandled error bubbles up to the root
- */
-function RootErrorFallback({ error, reset }: ClientErrorBoundaryFallbackProps): ReactNode {
+function RootErrorFallback({
+  error,
+  reset,
+}: ClientErrorBoundaryFallbackProps): ReactNode {
+  const isDev = process.env.NODE_ENV !== "production";
+
   return (
     <div
       style={{
@@ -131,38 +123,40 @@ function RootErrorFallback({ error, reset }: ClientErrorBoundaryFallbackProps):
       >
         An unexpected error occurred while processing your request.
       </p>
-      <div
-        style={{
-          background: "#fef2f2",
-          border: "1px solid #fecaca",
-          borderRadius: "0.5rem",
-          padding: "1rem",
-          marginBottom: "1rem",
-        }}
-      >
-        <p
+      {isDev && (
+        <div
           style={{
-            fontWeight: 600,
-            color: "#991b1b",
-            marginBottom: "0.5rem",
+            background: "#fef2f2",
+            border: "1px solid #fecaca",
+            borderRadius: "0.5rem",
+            padding: "1rem",
+            marginBottom: "1rem",
           }}
         >
-          {error.name}: {error.message}
-        </p>
-        {error.stack && (
-          <pre
+          <p
             style={{
-              fontSize: "0.75rem",
-              color: "#6b7280",
-              overflow: "auto",
-              whiteSpace: "pre-wrap",
-              wordBreak: "break-word",
+              fontWeight: 600,
+              color: "#991b1b",
+              marginBottom: "0.5rem",
             }}
           >
-            {error.stack}
-          </pre>
-        )}
-      </div>
+            {error.name}: {error.message}
+          </p>
+          {error.stack && (
+            <pre
+              style={{
+                fontSize: "0.75rem",
+                color: "#6b7280",
+                overflow: "auto",
+                whiteSpace: "pre-wrap",
+                wordBreak: "break-word",
+              }}
+            >
+              {error.stack}
+            </pre>
+          )}
+        </div>
+      )}
       <div style={{ display: "flex", gap: "1rem" }}>
         <button
           type="button"
@@ -222,7 +216,6 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidMount(): void {
-    // Listen for popstate (back/forward navigation) to reset error state
     window.addEventListener("popstate", this.handlePopState);
   }
 
@@ -231,19 +224,21 @@ export class RootErrorBoundary extends Component<
   }
 
   componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
-    console.error("[RootErrorBoundary] Unhandled error caught:", error, errorInfo);
+    console.error(
+      "[RootErrorBoundary] Unhandled error caught:",
+      error,
+      errorInfo,
+    );
   }
 
   componentDidUpdate(prevProps: { children: ReactNode }): void {
-    // Reset error state when children change (e.g., navigation)
-    // This allows the app to recover after navigation away from an errored route
+    // Reset error on children change (navigation).
     if (this.state.hasError && prevProps.children !== this.props.children) {
       this.setState({ hasError: false, error: null });
     }
   }
 
   handlePopState = (): void => {
-    // Reset error state on back/forward navigation
     if (this.state.hasError) {
       this.setState({ hasError: false, error: null });
     }
@@ -264,7 +259,6 @@ export class RootErrorBoundary extends Component<
         segmentType: "route" as const,
       };
 
-      // Use specialized fallback for network errors
       if (isNetworkError(this.state.error)) {
         return <NetworkErrorFallback error={errorInfo} reset={this.reset} />;
       }