@rangojs/router 0.0.0-experimental.10

package/src/reverse.ts

@@ -0,0 +1,267 @@
+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 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;
+ * ```
+ */
+export type MergeRoutes<T extends unknown[]> = T extends [
+  infer First,
+  ...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;
+
+/**
+ * Extract params type for a route
+ */
+export type ParamsFor<
+  TRoutes,
+  TName extends keyof TRoutes
+> = ExtractParams<RoutePatternFor<TRoutes, TName>>;
+
+/**
+ * Check if an object type has any keys
+ */
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+
+/**
+ * Type-safe reverse function signature (Django-style URL reversal)
+ *
+ * Validates route names and params at compile time.
+ * Use route names instead of raw paths for full type safety.
+ *
+ * @example
+ * ```typescript
+ * reverse("cart")                           // ✓ Validates route exists
+ * reverse("product.detail", { id: "123" })  // ✓ Validates route + params
+ * ```
+ */
+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
+  ): string;
+
+  /**
+   * Route with params - validates both route name and params
+   */
+  <TName extends keyof TRoutes & string>(
+    name: TName,
+    params: ExtractParams<RoutePatternFor<TRoutes, TName>>
+  ): string;
+};
+
+/**
+ * Type-safe scoped reverse function signature for use with scopedReverse<typeof patterns>()
+ *
+ * **Recommended: Use route names for type safety.**
+ * Route names validate both the route exists and params are correct.
+ * Path-based URLs (`/...`) are an escape hatch with no validation.
+ *
+ * @example
+ * ```typescript
+ * // RECOMMENDED: Use route names for type safety
+ * reverse("blog.post", { slug: "hello" })  // ✓ Validates route + params
+ * reverse("shop.cart")                      // ✓ Validates route exists
+ *
+ * // ESCAPE HATCH: Path-based URLs (no validation)
+ * reverse("/about")                         // ⚠ No type checking
+ * reverse("/typo/in/path")                  // ⚠ Won't catch errors
+ * ```
+ */
+export type ScopedReverseFunction<TLocalRoutes> = {
+  /**
+   * Route without params - validates route name exists
+   * @recommended Use this for type-safe URL generation
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    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
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: TName,
+    params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
+  ): string;
+
+  /**
+   * Absolute route name (contains dot) - global lookup
+   * Use for cross-module navigation: "shop.cart", "blog.post"
+   */
+  (name: `${string}.${string}`, params?: Record<string, string>): string;
+
+  /**
+   * Path-based URL - ESCAPE HATCH, no type validation
+   * Prefer route names for type safety. Only use paths when necessary.
+   */
+  (name: `/${string}`, params?: Record<string, string>): string;
+};
+
+/**
+ * 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>;
+
+/**
+ * Extract the response data type for a named route from a UrlPatterns instance.
+ * Re-exported from urls.ts for consumer convenience.
+ */
+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.
+ *
+ * @param reverse - The ctx.reverse function from HandlerContext
+ * @returns The same reverse function, but typed for local 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");          // ✓ Cross-module (absolute name)
+ *
+ *     return <BlogIndex />;
+ *   }, { name: "index" }),
+ *
+ *   path("/:slug", BlogPost, { name: "post" }),
+ * ]);
+ * ```
+ */
+export function scopedReverse<TPatterns>(
+  reverse: ((...args: any[]) => string)
+): ScopedReverseFunction<ExtractLocalRoutes<TPatterns>> {
+  return reverse as ScopedReverseFunction<ExtractLocalRoutes<TPatterns>>;
+}
+
+/**
+ * Create a type-safe reverse function for URL generation
+ *
+ * @param routeMap - Flattened route map with all registered routes
+ * @returns Type-safe reverse function
+ *
+ * @example
+ * ```typescript
+ * // Given routes: { cart: "/shop/cart", detail: "/shop/product/:slug" }
+ * const reverse = createReverse(routeMap);
+ * reverse("cart"); // "/shop/cart"
+ * reverse("detail", { slug: "my-product" }); // "/shop/product/my-product"
+ * ```
+ */
+export function createReverse<TRoutes extends Record<string, string>>(
+  routeMap: TRoutes
+): ReverseFunction<TRoutes & Record<string, string>> {
+  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 ReverseFunction<TRoutes>;
+}

package/src/root-error-boundary.tsx

@@ -0,0 +1,277 @@
+"use client";
+
+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();
+  };
+
+  return (
+    <div
+      style={{
+        fontFamily: "system-ui, -apple-system, sans-serif",
+        padding: "2rem",
+        maxWidth: "600px",
+        margin: "2rem auto",
+        textAlign: "center",
+      }}
+    >
+      <div
+        style={{
+          fontSize: "3rem",
+          marginBottom: "1rem",
+        }}
+      >
+        {/* Simple cloud with x icon using CSS */}
+        <span style={{ color: "#9ca3af" }}>&#9729;</span>
+      </div>
+      <h1
+        style={{
+          color: "#374151",
+          fontSize: "1.5rem",
+          marginBottom: "0.5rem",
+        }}
+      >
+        Connection Error
+      </h1>
+      <p
+        style={{
+          color: "#6b7280",
+          marginBottom: "1.5rem",
+        }}
+      >
+        {error.message || "Unable to connect to the server. Please check your internet connection."}
+      </p>
+      <div style={{ display: "flex", gap: "1rem", justifyContent: "center" }}>
+        <button
+          type="button"
+          onClick={handleRetry}
+          disabled={isRetrying}
+          style={{
+            padding: "0.75rem 1.5rem",
+            backgroundColor: isRetrying ? "#9ca3af" : "#2563eb",
+            color: "white",
+            border: "none",
+            borderRadius: "0.375rem",
+            cursor: isRetrying ? "not-allowed" : "pointer",
+            fontSize: "1rem",
+            fontWeight: 500,
+          }}
+        >
+          {isRetrying ? "Retrying..." : "Retry"}
+        </button>
+        <button
+          type="button"
+          onClick={() => window.history.back()}
+          style={{
+            padding: "0.75rem 1.5rem",
+            backgroundColor: "transparent",
+            color: "#6b7280",
+            border: "1px solid #d1d5db",
+            borderRadius: "0.375rem",
+            cursor: "pointer",
+            fontSize: "1rem",
+          }}
+        >
+          Go Back
+        </button>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * 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 {
+  return (
+    <div
+      style={{
+        fontFamily: "system-ui, -apple-system, sans-serif",
+        padding: "2rem",
+        maxWidth: "600px",
+        margin: "2rem auto",
+      }}
+    >
+      <h1
+        style={{
+          color: "#dc2626",
+          fontSize: "1.5rem",
+          marginBottom: "1rem",
+        }}
+      >
+        Internal Server Error
+      </h1>
+      <p
+        style={{
+          color: "#374151",
+          marginBottom: "1rem",
+        }}
+      >
+        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
+          style={{
+            fontWeight: 600,
+            color: "#991b1b",
+            marginBottom: "0.5rem",
+          }}
+        >
+          {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"
+          onClick={reset}
+          style={{
+            padding: "0.5rem 1rem",
+            backgroundColor: "#2563eb",
+            color: "white",
+            border: "none",
+            borderRadius: "0.25rem",
+            cursor: "pointer",
+          }}
+        >
+          Try Again
+        </button>
+        <a
+          href="/"
+          style={{
+            display: "inline-block",
+            padding: "0.5rem 1rem",
+            color: "#2563eb",
+            textDecoration: "underline",
+          }}
+        >
+          Go to homepage
+        </a>
+      </div>
+    </div>
+  );
+}
+
+interface RootErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+/**
+ * Root error boundary component
+ *
+ * Wraps the entire segment tree to catch any unhandled errors that bubble up.
+ * This prevents the entire app from crashing with a white screen.
+ *
+ * This is a client component with an inline fallback to avoid the
+ * "Functions cannot be passed to Client Components" RSC error.
+ */
+export class RootErrorBoundary extends Component<
+  { children: ReactNode },
+  RootErrorBoundaryState
+> {
+  constructor(props: { children: ReactNode }) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): RootErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidMount(): void {
+    // Listen for popstate (back/forward navigation) to reset error state
+    window.addEventListener("popstate", this.handlePopState);
+  }
+
+  componentWillUnmount(): void {
+    window.removeEventListener("popstate", this.handlePopState);
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    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
+    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 });
+    }
+  };
+
+  reset = (): void => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.hasError && this.state.error) {
+      const errorInfo = {
+        message: this.state.error.message,
+        name: this.state.error.name,
+        stack: this.state.error.stack,
+        cause: this.state.error.cause,
+        segmentId: "root",
+        segmentType: "route" as const,
+      };
+
+      // Use specialized fallback for network errors
+      if (isNetworkError(this.state.error)) {
+        return <NetworkErrorFallback error={errorInfo} reset={this.reset} />;
+      }
+
+      return <RootErrorFallback error={errorInfo} reset={this.reset} />;
+    }
+
+    return this.props.children;
+  }
+}