@ivogt/rsc-router 0.0.0-experimental.1

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,60 @@
+/**
+ * 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";
+
+/**
+ * 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 = {}
+): 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();
+
+  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
+    // Placeholder use() - will be replaced with actual implementation during request
+    use: () => {
+      throw new Error("ctx.use() called before loaders were initialized");
+    },
+  };
+}

package/src/router/loader-resolution.ts

@@ -0,0 +1,326 @@
+/**
+ * Router Loader Resolution
+ *
+ * Loader execution, memoization, and error handling utilities.
+ */
+
+import type { ReactNode } from "react";
+import { track } from "../server/context";
+import type { EntryData } from "../server/context";
+import type {
+  ResolvedSegment,
+  HandlerContext,
+  LoaderDefinition,
+  LoaderContext,
+  LoaderDataResult,
+  ErrorBoundaryHandler,
+  ErrorBoundaryFallbackProps,
+  ErrorInfo,
+} from "../types";
+import type { LoaderRevalidationResult, ActionContext } from "./types";
+import { isHandle, type Handle } from "../handle.js";
+import type { HandleStore } from "../server/handle-store.js";
+import { getFetchableLoader } from "../loader.rsc.js";
+import { getRequestContext } from "../server/request-context.js";
+
+/**
+ * Internal callback signature for loader error notifications.
+ * This is a simplified callback for internal use in wrapLoaderWithErrorHandling.
+ * The caller (wrapLoaderPromise in router.ts) bridges this to the full OnErrorCallback.
+ */
+export type LoaderErrorCallback = (
+  error: unknown,
+  context: {
+    segmentId: string;
+    loaderName: string;
+    handledByBoundary: boolean;
+  }
+) => void;
+
+/**
+ * Wrap a loader promise with error handling for deferred client-side resolution.
+ * Catches errors and converts them to LoaderDataResult objects that include
+ * error info and pre-rendered fallback UI when an error boundary is available.
+ *
+ * @param onError - Optional callback invoked when loader errors occur.
+ *   This has a simplified signature for internal use - the caller (typically
+ *   wrapLoaderPromise in router.ts) is responsible for bridging to the full
+ *   OnErrorCallback with complete request context (request, url, env, etc.).
+ */
+export function wrapLoaderWithErrorHandling<T>(
+  promise: Promise<T>,
+  entry: EntryData,
+  segmentId: string,
+  pathname: string,
+  findNearestErrorBoundary: (
+    entry: EntryData | null
+  ) => ReactNode | ErrorBoundaryHandler | null,
+  createErrorInfo: (
+    error: unknown,
+    segmentId: string,
+    segmentType: ErrorInfo["segmentType"]
+  ) => ErrorInfo,
+  onError?: LoaderErrorCallback
+): Promise<LoaderDataResult<T>> {
+  // Extract loader name from segmentId (format: "M1L0D0.loaderName")
+  const loaderName = segmentId.split(".").pop() || "unknown";
+
+  return Promise.resolve(promise)
+    .then(
+      (data): LoaderDataResult<T> => ({
+        __loaderResult: true,
+        ok: true,
+        data,
+      })
+    )
+    .catch((error): LoaderDataResult<T> => {
+      // Find nearest error boundary
+      const fallback = findNearestErrorBoundary(entry);
+
+      // Create error info
+      const errorInfo = createErrorInfo(error, segmentId, "loader");
+
+      // Invoke onError callback if provided
+      onError?.(error, {
+        segmentId,
+        loaderName,
+        handledByBoundary: !!fallback,
+      });
+
+      if (!fallback) {
+        // No error boundary - return error result without fallback
+        // Client will throw this error
+        return {
+          __loaderResult: true,
+          ok: false,
+          error: errorInfo,
+          fallback: null,
+        };
+      }
+
+      // Render fallback on server
+      let renderedFallback: ReactNode;
+      if (typeof fallback === "function") {
+        // ErrorBoundaryHandler - call with error info
+        const props: ErrorBoundaryFallbackProps = {
+          error: errorInfo,
+        };
+        renderedFallback = fallback(props);
+      } else {
+        renderedFallback = fallback;
+      }
+
+      console.log(
+        `[Router] Loader error wrapped with boundary fallback in ${segmentId}:`,
+        errorInfo.message
+      );
+
+      return {
+        __loaderResult: true,
+        ok: false,
+        error: errorInfo,
+        fallback: renderedFallback,
+      };
+    });
+}
+
+/**
+ * Set up the use() method on handler context to access loaders and handles.
+ *
+ * For loaders: Lazily runs loaders, memoizes results per request.
+ * For handles: Returns a push function bound to the current segment.
+ */
+export function setupLoaderAccess<TEnv>(
+  ctx: HandlerContext<any, TEnv>,
+  loaderPromises: Map<string, Promise<any>>
+): void {
+  // Get HandleStore from request context
+  const getHandleStore = (): HandleStore | undefined => {
+    return getRequestContext()?._handleStore;
+  };
+
+  // The use() function handles both loaders and handles
+  ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+    // Handle case: return a push function
+    if (isHandle(item)) {
+      const handle = item;
+      const store = getHandleStore();
+      const segmentId = ctx._currentSegmentId;
+
+      if (!segmentId) {
+        throw new Error(
+          `Handle "${handle.$$id}" used outside of handler context. ` +
+            `Handles must be used within route/layout handlers.`
+        );
+      }
+
+      // Return a push function bound to this handle and segment
+      // Accepts: value, Promise, or async callback (executed immediately)
+      // Promises are pushed directly - RSC will serialize and stream them
+      return (dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>)) => {
+        if (!store) return;
+
+        // If it's a function, call it immediately to get the promise
+        const valueOrPromise = typeof dataOrFn === "function"
+          ? (dataOrFn as () => Promise<unknown>)()
+          : dataOrFn;
+
+        // Push directly - promises will be serialized by RSC and streamed
+        store.push(handle.$$id, segmentId, valueOrPromise);
+      };
+    }
+
+    // Loader case: existing behavior
+    const loader = item as LoaderDefinition<any, any>;
+
+    // Return cached promise if already started
+    if (loaderPromises.has(loader.$$id)) {
+      return loaderPromises.get(loader.$$id);
+    }
+
+    // Get loader function - either from loader object or fetchable registry
+    // Fetchable loaders store fn in registry (not on object) to avoid client bundling issues
+    let loaderFn = loader.fn;
+    if (!loaderFn) {
+      const fetchable = getFetchableLoader(loader.$$id);
+      if (fetchable) {
+        loaderFn = fetchable.fn;
+      }
+    }
+
+    // Ensure loader has a function
+    if (!loaderFn) {
+      throw new Error(
+        `Loader "${loader.$$id}" has no function. This usually means the loader was defined without "use server" and the function was not included in the build.`
+      );
+    }
+
+    // Create loader context with recursive use() support
+    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
+      params: ctx.params,
+      request: ctx.request,
+      searchParams: ctx.searchParams,
+      pathname: ctx.pathname,
+      url: ctx.url,
+      env: ctx.env,
+      var: ctx.var,
+      get: ctx.get,
+      use: <TDep, TDepParams = any>(
+        dep: LoaderDefinition<TDep, TDepParams>
+      ): Promise<TDep> => {
+        // Recursive call - will start dep loader if not already started
+        return ctx.use(dep);
+      },
+      // Default to GET for loaders called through route handlers
+      method: "GET",
+      body: undefined,
+    };
+
+    // Start loader execution with tracking
+    const doneLoader = track(`loader:${loader.$$id}`);
+    const promise = Promise.resolve(
+      loaderFn(loaderCtx as LoaderContext<any, TEnv>)
+    ).finally(() => {
+      doneLoader();
+    });
+
+    // Memoize for subsequent calls
+    loaderPromises.set(loader.$$id, promise);
+
+    return promise;
+  }) as typeof ctx.use;
+}
+
+/**
+ * Set up ctx.use() for proactive caching (silent mode).
+ * Handles are silently ignored (no push to HandleStore).
+ * Loaders work normally but with fresh memoization.
+ *
+ * This prevents duplicate handle data (breadcrumbs, meta) from being
+ * pushed to the response stream during background proactive caching.
+ */
+export function setupLoaderAccessSilent<TEnv>(
+  ctx: HandlerContext<any, TEnv>,
+  loaderPromises: Map<string, Promise<any>>
+): void {
+  ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
+    // Handle case: return a no-op push function
+    if (isHandle(item)) {
+      // Silent mode - return a function that does nothing
+      return (_dataOrFn: unknown) => {
+        // Intentionally empty - don't push handle data during proactive caching
+      };
+    }
+
+    // Loader case: same as setupLoaderAccess
+    const loader = item as LoaderDefinition<any, any>;
+
+    // Return cached promise if already started
+    if (loaderPromises.has(loader.$$id)) {
+      return loaderPromises.get(loader.$$id);
+    }
+
+    // Get loader function
+    let loaderFn = loader.fn;
+    if (!loaderFn) {
+      const fetchable = getFetchableLoader(loader.$$id);
+      if (fetchable) {
+        loaderFn = fetchable.fn;
+      }
+    }
+
+    if (!loaderFn) {
+      throw new Error(
+        `Loader "${loader.$$id}" has no function. This usually means the loader was defined without "use server" and the function was not included in the build.`
+      );
+    }
+
+    // Create loader context with recursive use() support
+    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
+      params: ctx.params,
+      request: ctx.request,
+      searchParams: ctx.searchParams,
+      pathname: ctx.pathname,
+      url: ctx.url,
+      env: ctx.env,
+      var: ctx.var,
+      get: ctx.get,
+      use: <TDep, TDepParams = any>(
+        dep: LoaderDefinition<TDep, TDepParams>
+      ): Promise<TDep> => {
+        return ctx.use(dep);
+      },
+      method: "GET",
+      body: undefined,
+    };
+
+    // Start loader execution with tracking
+    const doneLoader = track(`loader:${loader.$$id}`);
+    const promise = Promise.resolve(
+      loaderFn(loaderCtx as LoaderContext<any, TEnv>)
+    ).finally(() => {
+      doneLoader();
+    });
+
+    loaderPromises.set(loader.$$id, promise);
+    return promise;
+  }) as typeof ctx.use;
+}
+
+/**
+ * Conditional execution based on revalidation
+ * Evaluates revalidation logic lazily, then executes appropriate callback
+ *
+ * @param shouldRevalidate - Async function that determines if revalidation is needed
+ * @param onRevalidate - Callback executed if revalidation returns true
+ * @param onSkip - Callback executed if revalidation returns false
+ * @returns Result from either onRevalidate or onSkip
+ */
+export async function revalidate<T>(
+  shouldRevalidate: () => Promise<boolean>,
+  onRevalidate: () => Promise<T>,
+  onSkip: () => T
+): Promise<T> {
+  const needsRevalidation = await shouldRevalidate();
+  return needsRevalidation ? await onRevalidate() : onSkip();
+}