@rangojs/router 0.0.0-experimental.2

package/src/router/error-handling.ts

@@ -0,0 +1,287 @@
+/**
+ * Router Error Handling Utilities
+ *
+ * Error boundary and not-found boundary handling for RSC Router.
+ * Also includes the shared invokeOnError utility for error callback invocation.
+ */
+
+import type { ReactNode } from "react";
+import type { EntryData } from "../server/context";
+import type {
+  ResolvedSegment,
+  ErrorInfo,
+  ErrorBoundaryHandler,
+  ErrorBoundaryFallbackProps,
+  NotFoundInfo,
+  NotFoundBoundaryHandler,
+  NotFoundBoundaryFallbackProps,
+  ErrorPhase,
+  OnErrorCallback,
+  OnErrorContext,
+} from "../types";
+
+/**
+ * Context required to invoke the onError callback.
+ * This is a subset of OnErrorContext that callers must provide.
+ */
+export interface InvokeOnErrorContext<TEnv = any> {
+  request: Request;
+  url: URL;
+  routeKey?: string;
+  params?: Record<string, string>;
+  segmentId?: string;
+  segmentType?: "layout" | "route" | "parallel" | "loader" | "middleware";
+  loaderName?: string;
+  middlewareId?: string;
+  actionId?: string;
+  env?: TEnv;
+  isPartial?: boolean;
+  handledByBoundary?: boolean;
+  metadata?: Record<string, unknown>;
+  /** Request start time from performance.now() for duration calculation */
+  requestStartTime?: number;
+}
+
+/**
+ * Invoke the onError callback with comprehensive context.
+ * Catches any errors in the callback itself to prevent masking the original error.
+ *
+ * This is a shared utility used by both the router and RSC handler to ensure
+ * consistent error callback behavior across the codebase.
+ *
+ * @param onError - The onError callback to invoke (may be undefined)
+ * @param error - The error that occurred
+ * @param phase - The phase where the error occurred
+ * @param context - Additional context about the error
+ * @param logPrefix - Prefix for console.error messages (e.g., "Router" or "RSC")
+ */
+export function invokeOnError<TEnv = any>(
+  onError: OnErrorCallback<TEnv> | undefined,
+  error: unknown,
+  phase: ErrorPhase,
+  context: InvokeOnErrorContext<TEnv>,
+  logPrefix: string = "Router"
+): void {
+  if (!onError) return;
+
+  const errorObj = error instanceof Error ? error : new Error(String(error));
+  const duration = context.requestStartTime
+    ? performance.now() - context.requestStartTime
+    : undefined;
+
+  const errorContext: OnErrorContext<TEnv> = {
+    error: errorObj,
+    phase,
+    request: context.request,
+    url: context.url,
+    pathname: context.url.pathname,
+    method: context.request.method,
+    routeKey: context.routeKey,
+    params: context.params,
+    segmentId: context.segmentId,
+    segmentType: context.segmentType,
+    loaderName: context.loaderName,
+    middlewareId: context.middlewareId,
+    actionId: context.actionId,
+    env: context.env,
+    duration,
+    isPartial: context.isPartial,
+    handledByBoundary: context.handledByBoundary,
+    stack: errorObj.stack,
+    metadata: context.metadata,
+  };
+
+  try {
+    const result = onError(errorContext);
+    // If onError returns a promise, catch any rejections
+    if (result instanceof Promise) {
+      result.catch((callbackError) => {
+        console.error(`[${logPrefix}.onError] Callback error:`, callbackError);
+      });
+    }
+  } catch (callbackError) {
+    // Log but don't throw - we don't want callback errors to mask the original error
+    console.error(`[${logPrefix}.onError] Callback error:`, callbackError);
+  }
+}
+
+/**
+ * Find the nearest error boundary by walking up the entry chain
+ * Also checks sibling layouts (orphan layouts) for error boundaries
+ * Returns the first fallback found, or the default error boundary if configured
+ */
+export function findNearestErrorBoundary(
+  entry: EntryData | null,
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler
+): ReactNode | ErrorBoundaryHandler | null {
+  let current: EntryData | null = entry;
+
+  while (current) {
+    // Check if this entry has error boundaries defined
+    if (current.errorBoundary && current.errorBoundary.length > 0) {
+      // Return the last error boundary (most recently defined takes precedence)
+      return current.errorBoundary[current.errorBoundary.length - 1];
+    }
+
+    // Check orphan layouts for error boundaries
+    // Orphan layouts are siblings that render alongside the main route chain
+    // They can define error boundaries that catch errors from routes in the same route group
+    // Check from first to last (first sibling takes precedence as the "outer" wrapper)
+    if (current.layout && current.layout.length > 0) {
+      for (const orphan of current.layout) {
+        if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
+          return orphan.errorBoundary[orphan.errorBoundary.length - 1];
+        }
+      }
+    }
+
+    current = current.parent;
+  }
+
+  // Return default error boundary if configured
+  return defaultErrorBoundary || null;
+}
+
+/**
+ * Find the nearest notFound boundary by walking up the entry chain
+ * Returns the first fallback found, or the default notFound boundary if configured
+ */
+export function findNearestNotFoundBoundary(
+  entry: EntryData | null,
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler
+): ReactNode | NotFoundBoundaryHandler | null {
+  let current: EntryData | null = entry;
+
+  while (current) {
+    // Check if this entry has notFound boundaries defined
+    if (current.notFoundBoundary && current.notFoundBoundary.length > 0) {
+      // Return the last notFound boundary (most recently defined takes precedence)
+      return current.notFoundBoundary[current.notFoundBoundary.length - 1];
+    }
+    current = current.parent;
+  }
+
+  // Return default notFound boundary if configured
+  return defaultNotFoundBoundary || null;
+}
+
+/**
+ * Create ErrorInfo from an error object
+ * Sanitizes error details in production
+ */
+export function createErrorInfo(
+  error: unknown,
+  segmentId: string,
+  segmentType: ErrorInfo["segmentType"]
+): ErrorInfo {
+  const isDev = process.env.NODE_ENV !== "production";
+
+  if (error instanceof Error) {
+    return {
+      message: isDev ? error.message : "An error occurred",
+      name: error.name,
+      code: (error as any).code,
+      stack: isDev ? error.stack : undefined,
+      cause: isDev ? error.cause : undefined,
+      segmentId,
+      segmentType,
+    };
+  }
+
+  // Non-Error thrown
+  return {
+    message: isDev ? String(error) : "An error occurred",
+    name: "Error",
+    segmentId,
+    segmentType,
+  };
+}
+
+/**
+ * Create an error segment with the fallback component
+ * Renders the fallback with error info and reset function
+ */
+export function createErrorSegment(
+  errorInfo: ErrorInfo,
+  fallback: ReactNode | ErrorBoundaryHandler,
+  entry: EntryData,
+  params: Record<string, string>
+): ResolvedSegment {
+  // Determine the component to render
+  let component: ReactNode;
+
+  if (typeof fallback === "function") {
+    // ErrorBoundaryHandler - call with error info
+    const props: ErrorBoundaryFallbackProps = {
+      error: errorInfo,
+    };
+    component = fallback(props);
+  } else {
+    // Static ReactNode fallback
+    component = fallback;
+  }
+
+  // Error segment uses the same ID as the layout that has the error boundary
+  // The error boundary content replaces the layout's outlet content
+  return {
+    id: entry.shortCode,
+    namespace: entry.id,
+    type: "error",
+    index: 0,
+    component,
+    params,
+    error: errorInfo,
+  };
+}
+
+/**
+ * Create NotFoundInfo from a DataNotFoundError
+ */
+export function createNotFoundInfo(
+  error: { message: string },
+  segmentId: string,
+  segmentType: NotFoundInfo["segmentType"],
+  pathname?: string
+): NotFoundInfo {
+  return {
+    message: error.message,
+    segmentId,
+    segmentType,
+    pathname,
+  };
+}
+
+/**
+ * Create a notFound segment with the fallback component
+ * Renders the fallback with not found info
+ */
+export function createNotFoundSegment(
+  notFoundInfo: NotFoundInfo,
+  fallback: ReactNode | NotFoundBoundaryHandler,
+  entry: EntryData,
+  params: Record<string, string>
+): ResolvedSegment {
+  // Determine the component to render
+  let component: ReactNode;
+
+  if (typeof fallback === "function") {
+    // NotFoundBoundaryHandler - call with props
+    const props: NotFoundBoundaryFallbackProps = {
+      notFound: notFoundInfo,
+    };
+    component = fallback(props);
+  } else {
+    // Static ReactNode fallback
+    component = fallback;
+  }
+
+  return {
+    id: `${entry.shortCode}.notFound`,
+    namespace: entry.id,
+    type: "notFound",
+    index: 0,
+    component,
+    params,
+    notFoundInfo,
+  };
+}

package/src/router/handler-context.ts

@@ -0,0 +1,158 @@
+/**
+ * Router Handler Context
+ *
+ * Creates the handler context object passed to route handlers, middleware, and loaders.
+ */
+
+import type { HandlerContext } from "../types";
+import { getRequestContext } from "../server/request-context.js";
+
+/**
+ * Resolve route name with namespace prefix support.
+ * Same logic as client-side useHref for consistency.
+ */
+function resolveRouteName(
+  name: string,
+  routeMap: Record<string, string>,
+  currentRoutePrefix?: string
+): string | undefined {
+  // 1. Path-based - starts with /
+  if (name.startsWith("/")) {
+    return name;
+  }
+
+  // 2. Absolute name - already has a dot (e.g., "shop.cart")
+  if (name.includes(".")) {
+    return routeMap[name];
+  }
+
+  // 3. Local name - try with current prefix first, then fall back to direct lookup
+  if (currentRoutePrefix) {
+    // Extract the prefix from current route name
+    // e.g., "blog.posts.detail" → prefix is "blog.posts"
+    const lastDot = currentRoutePrefix.lastIndexOf(".");
+    const prefix = lastDot > 0 ? currentRoutePrefix.substring(0, lastDot) : currentRoutePrefix;
+
+    // Try prefixed name
+    const prefixedName = `${prefix}.${name}`;
+    if (routeMap[prefixedName] !== undefined) {
+      return routeMap[prefixedName];
+    }
+
+    // If current route is a nested include, try parent prefixes
+    // e.g., for "blog.posts.detail", try "blog.posts.index", then "blog.index"
+    let currentPrefix = prefix;
+    while (currentPrefix.includes(".")) {
+      const parentDot = currentPrefix.lastIndexOf(".");
+      currentPrefix = currentPrefix.substring(0, parentDot);
+      const parentPrefixedName = `${currentPrefix}.${name}`;
+      if (routeMap[parentPrefixedName] !== undefined) {
+        return routeMap[parentPrefixedName];
+      }
+    }
+  }
+
+  // Fall back to direct lookup (route without prefix)
+  return routeMap[name];
+}
+
+/**
+ * Create HandlerContext with typed env/var/get/set
+ */
+export function createHandlerContext<TEnv>(
+  params: Record<string, string>,
+  request: Request,
+  searchParams: URLSearchParams,
+  pathname: string,
+  url: URL,
+  bindings: any = {},
+  routeMap: Record<string, string> = {},
+  routeName?: string
+): HandlerContext<any, TEnv> {
+  // Get variables from request context - this is the unified context
+  // shared between middleware and route handlers
+  const requestContext = getRequestContext();
+  const variables: any = requestContext?.var ?? {};
+
+  // Filter system parameters (starting with _rsc) from searchParams
+  // This ensures handlers only see user-facing query params
+  const cleanSearchParams = new URLSearchParams();
+  searchParams.forEach((value, key) => {
+    if (!key.startsWith("_rsc")) {
+      cleanSearchParams.set(key, value);
+    }
+  });
+
+  // Create clean URL without system params
+  const cleanUrl = new URL(url);
+  cleanUrl.search = cleanSearchParams.toString();
+
+  // Get stub response from request context for setting headers
+  const stubResponse = requestContext?.res ?? new Response(null, { status: 200 });
+
+  return {
+    params,
+    request,
+    searchParams: cleanSearchParams, // Filtered params
+    pathname,
+    url: cleanUrl, // Clean URL
+    env: bindings,
+    var: variables,
+    get: ((key: string) => variables[key]) as HandlerContext<
+      any,
+      TEnv
+    >["get"],
+    set: ((key: string, value: any) => {
+      variables[key] = value;
+    }) as HandlerContext<any, TEnv>["set"],
+    _originalRequest: request, // Raw request for advanced use
+    res: stubResponse, // Stub response for setting headers
+    headers: stubResponse.headers, // Shorthand for res.headers
+    // Placeholder use() - will be replaced with actual implementation during request
+    use: () => {
+      throw new Error("ctx.use() called before loaders were initialized");
+    },
+    // Theme support (when enabled via router config)
+    theme: requestContext?.theme,
+    setTheme: requestContext?.setTheme,
+    // Scoped href for URL generation
+    href: (name: string, hrefParams?: Record<string, string>) => {
+      // Path-based - return directly (optionally with param substitution)
+      if (name.startsWith("/")) {
+        if (hrefParams) {
+          return name.replace(/:([^/]+)/g, (_, key) => {
+            const value = hrefParams[key];
+            if (value === undefined) {
+              throw new Error(`Missing param "${key}" for path "${name}"`);
+            }
+            return encodeURIComponent(value);
+          });
+        }
+        return name;
+      }
+
+      // Resolve route name with namespace support
+      const pattern = resolveRouteName(name, routeMap, routeName);
+
+      if (pattern === undefined) {
+        throw new Error(
+          `Unknown route: "${name}"${routeName ? ` (current route: ${routeName})` : ""}`
+        );
+      }
+
+      // If no params, return pattern directly
+      if (!hrefParams) {
+        return pattern;
+      }
+
+      // Substitute params
+      return pattern.replace(/:([^/]+)/g, (_, key) => {
+        const value = hrefParams[key];
+        if (value === undefined) {
+          throw new Error(`Missing param "${key}" for route "${name}"`);
+        }
+        return encodeURIComponent(value);
+      });
+    },
+  };
+}