@ivogt/rsc-router 0.0.0-experimental.1

package/src/loader.rsc.ts

@@ -0,0 +1,204 @@
+/**
+ * rsc-router/loader (RSC/server version)
+ *
+ * Server-side createLoader implementation with full loader functionality.
+ * Only used in react-server context via export conditions.
+ *
+ * For non-fetchable loaders: returns a loader definition with fn included
+ * For fetchable loaders: stores fn in registry and returns a serializable loader with action
+ *
+ * The $$id is injected by the Vite exposeLoaderId plugin as a hidden parameter.
+ * Users don't need to pass any name - IDs are auto-generated from file path.
+ */
+
+import type {
+  FetchableLoaderOptions,
+  LoaderDefinition,
+  LoaderFn,
+} from "./types.js";
+import type { MiddlewareFn } from "./router/middleware.js";
+import { getRequestContext } from "./server/request-context.js";
+
+// Internal registry for fetchable loaders (server-side only)
+// Maps loader $$id to its function and middleware
+//
+// WHY TWO REGISTRIES?
+// This registry (fetchableLoaderRegistry) is populated immediately when createLoader() runs.
+// The other registry in loader-registry.ts (loaderRegistry) is a cache used by the RSC handler
+// for GET-based fetching. The RSC handler calls getFetchableLoader() from here to populate
+// its cache. This separation allows:
+// 1. Server actions to look up loaders directly without going through lazy loading
+// 2. The RSC handler to use lazy loading for production builds
+// 3. Both to share the same source of truth (this registry)
+const fetchableLoaderRegistry = new Map<
+  string,
+  { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] }
+>();
+
+/**
+ * Register a fetchable loader's function internally
+ * Called during module initialization with the $$id
+ */
+function registerFetchableLoader(
+  id: string,
+  fn: LoaderFn<any, any, any>,
+  middleware: MiddlewareFn[]
+): void {
+  fetchableLoaderRegistry.set(id, { fn, middleware });
+}
+
+/**
+ * Get a fetchable loader's function from the internal registry by $$id
+ *
+ * This is used internally by:
+ * - Server actions (loaderAction) to execute loader functions
+ * - loader-registry.ts to populate the main registry for GET-based fetching
+ *
+ * Loaders are registered here when createLoader() is called with fetchable: true.
+ * The $$id is injected by the Vite exposeLoaderId plugin.
+ *
+ * @param id - The loader's $$id (auto-generated from file path + export name)
+ * @returns The loader function and middleware, or undefined if not found
+ *
+ * @internal This is primarily for internal use by the router infrastructure
+ */
+export function getFetchableLoader(
+  id: string
+): { fn: LoaderFn<any, any, any>; middleware: MiddlewareFn[] } | undefined {
+  return fetchableLoaderRegistry.get(id);
+}
+
+// Overload 1: With function only (not fetchable)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 2: Fetchable with `true` (no middleware)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable: true
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 3: Fetchable with middleware options
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  options: FetchableLoaderOptions
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Implementation - the $$id parameter is injected by Vite plugin, not user-provided
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable?: true | FetchableLoaderOptions,
+  // Hidden parameter injected by Vite exposeLoaderId plugin
+  __injectedId?: string
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
+  // The $$id will be set on the returned object by Vite plugin
+  // For fetchable loaders, __injectedId is also passed as a parameter
+  const loaderId = __injectedId || "";
+
+  // If not fetchable, return a simple stub with fn included
+  if (fetchable === undefined) {
+    return {
+      __brand: "loader",
+      $$id: loaderId,
+      fn: fn as LoaderFn<Awaited<T>, Record<string, string | undefined>, any>,
+    };
+  }
+
+  // Fetchable loader - store fn in registry and return a serializable object
+  const middleware: MiddlewareFn[] =
+    fetchable === true ? [] : fetchable?.middleware || [];
+
+  // Register the function in the internal registry by $$id (server-side only)
+  // The server action will look it up by $$id when executed
+  if (fn && loaderId) {
+    registerFetchableLoader(loaderId, fn, middleware);
+  }
+
+  // Create server action for form-based fetching
+  // This action is serializable and can be passed to client components
+  // The loaderId is captured in closure (it's a primitive string)
+  //
+  // IMPORTANT: The signature must be (prevState, formData) for useActionState compatibility.
+  // When used with useActionState, React passes the previous state as the first argument.
+  // The prevState is ignored here since loaders are stateless data fetchers.
+  async function loaderAction(
+    _prevState: Awaited<T> | null,
+    formData: FormData
+  ): Promise<Awaited<T>> {
+    "use server";
+
+    // Look up the loader from registry by $$id
+    const registered = fetchableLoaderRegistry.get(loaderId);
+    if (!registered) {
+      throw new Error(`Loader "${loaderId}" not found in registry`);
+    }
+
+    // Get request context (env, request, url, variables) from the RSC handler
+    // This is set by runWithRequestContext in rsc/index.ts when executing actions
+    const requestCtx = getRequestContext();
+
+    // Convert FormData to params object
+    const params: Record<string, string> = {};
+    formData.forEach((value, key) => {
+      if (typeof value === "string") {
+        params[key] = value;
+      }
+    });
+
+    // Use real request/url from context, or fall back to synthetic for edge cases
+    const actionUrl = requestCtx?.url ?? new URL("http://localhost/");
+    const actionRequest = requestCtx?.request ?? new Request(actionUrl, { method: "POST" });
+    const env = requestCtx?.env ?? {};
+
+    // Merge variables from request context (app-level middleware) with loader-specific variables
+    // requestCtx.var is the shared variables object from the handler
+    const variables: Record<string, any> = { ...requestCtx?.var };
+
+    // Execute middleware for auth checks, headers, cookies
+    // Headers/cookies set on ctx.res will be merged into the final response
+    if (registered.middleware.length > 0 && requestCtx?.res) {
+      const { executeServerActionMiddleware } = await import(
+        "./router/middleware.js"
+      );
+      await executeServerActionMiddleware(
+        registered.middleware,
+        actionRequest,
+        env,
+        params,
+        variables,
+        requestCtx.res
+      );
+    }
+
+    // Build context using createHandlerContext for consistency with route handlers
+    // Variables are now accessed from request context via getRequestContext()
+    const { createHandlerContext } = await import("./router/handler-context.js");
+    const baseCtx = createHandlerContext(
+      params,
+      actionRequest,
+      actionUrl.searchParams,
+      actionUrl.pathname,
+      actionUrl,
+      env
+    );
+
+    // Extend with server action specific properties
+    const ctx: any = {
+      ...baseCtx,
+      method: "POST",
+      formData,
+    };
+
+    // Execute and return result
+    return registered.fn(ctx);
+  }
+
+  // Return a loader object with action for form-based fetching
+  // The exposeLoaderId plugin will set $$id on this object
+  return {
+    __brand: "loader",
+    $$id: loaderId,
+    action: loaderAction,
+  };
+}

package/src/loader.ts

@@ -0,0 +1,47 @@
+/**
+ * rsc-router/loader (client version)
+ *
+ * Client-only stub for createLoader. Returns a minimal loader definition
+ * that can be passed to hooks like useLoader. The actual loader function
+ * is not included - it only exists on the server.
+ *
+ * The $$id is injected by the Vite exposeLoaderId plugin.
+ */
+
+import type {
+  FetchableLoaderOptions,
+  LoaderDefinition,
+  LoaderFn,
+} from "./types.js";
+
+// Overload 1: With function only (not fetchable)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 2: Fetchable with `true` (no middleware)
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  fetchable: true
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Overload 3: Fetchable with middleware options
+export function createLoader<T>(
+  fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  options: FetchableLoaderOptions
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>>;
+
+// Implementation - client stub that just returns the loader definition
+// The $$id parameter is injected by Vite plugin, not user-provided
+export function createLoader<T>(
+  _fn: LoaderFn<T, Record<string, string | undefined>, any>,
+  _fetchable?: true | FetchableLoaderOptions,
+  __injectedId?: string
+): LoaderDefinition<Awaited<T>, Record<string, string | undefined>> {
+  // Client only needs the $$id for identification
+  // The actual loader function is only used on the server
+  return {
+    __brand: "loader",
+    $$id: __injectedId || "",
+  };
+}

package/src/network-error-thrower.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { NetworkError } from "./errors.js";
+
+interface NetworkErrorThrowerProps {
+  error: NetworkError;
+}
+
+/**
+ * Client component that throws a NetworkError during render.
+ * Used to trigger the root error boundary when a network error occurs
+ * during navigation or server actions.
+ *
+ * This must be a separate component because:
+ * 1. Errors must be thrown during React's render phase to be caught by error boundaries
+ * 2. The error occurs in async code (fetch), so we need to propagate it to React's render
+ */
+export function NetworkErrorThrower({ error }: NetworkErrorThrowerProps): ReactNode {
+  throw error;
+}

package/src/outlet-context.ts

@@ -0,0 +1,15 @@
+import { Context, createContext, type ReactNode } from "react";
+import type { ResolvedSegment } from "./types";
+
+export interface OutletContextValue {
+  content: ReactNode;
+  parallel?: ResolvedSegment[];
+  segment?: ResolvedSegment;
+  loaderData?: Record<string, any>;
+  parent?: OutletContextValue | null;
+  /** Loading component for Suspense fallback (from segment's loading() definition) */
+  loading?: ReactNode;
+}
+
+export const OutletContext: Context<OutletContextValue | null> =
+  createContext<OutletContextValue | null>(null);

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;
+  }
+}