@rangojs/router 0.0.0-experimental.2

package/src/server.ts

@@ -0,0 +1,146 @@
+/**
+ * rsc-router/server
+ *
+ * Server-only exports for route definition and building
+ * These should only be imported in server-side handler files
+ */
+
+// Route definition helpers (server-only)
+export {
+  route,
+  map,
+  createLoader,
+  redirect,
+  type RouteHelpers,
+  type RouteHandlers,
+  type InterceptSelectorContext,
+  type InterceptSegmentsState,
+  type InterceptWhenFn,
+} from "./route-definition.js";
+
+// Django-style URL patterns (server-only)
+export {
+  urls,
+  type PathHelpers,
+  type PathOptions,
+  type UrlPatterns,
+  type IncludeOptions,
+} from "./urls.js";
+
+// Re-export IncludeItem from route-types
+export type { IncludeItem } from "./route-types.js";
+
+// Core router (server-only)
+export {
+  createRSCRouter,
+  type RSCRouter,
+  type RSCRouterOptions,
+  type RootLayoutProps,
+} from "./router.js";
+
+// Type-safe href utilities
+export {
+  createHref,
+  type HrefFunction,
+  type PrefixedRoutes,
+  type PrefixRoutePatterns,
+  type ParamsFor,
+  type SanitizePrefix,
+  type MergeRoutes,
+} from "./href.js";
+
+// Segment system (server-only)
+export { renderSegments } from "./segment-system.js";
+
+// Performance tracking (server-only)
+export { track } from "./server/context.js";
+
+// Handle API (works in both server and client contexts)
+export { createHandle, isHandle, type Handle } from "./handle.js";
+
+// Built-in handles
+export { Meta } from "./handles/meta.js";
+
+// Loader registry (for GET-based loader fetching)
+export { registerLoaderById, setLoaderImports } from "./server/loader-registry.js";
+
+// Request context (for accessing request data in server components/actions)
+export {
+  getRequestContext,
+  requireRequestContext,
+  createRequestContext,
+  type RequestContext,
+  type CreateRequestContextOptions,
+} from "./server/request-context.js";
+
+// Meta types
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+
+// Middleware types
+export type {
+  MiddlewareFn,
+  MiddlewareFn as AppMiddlewareFn, // Alias for backwards compatibility
+  MiddlewareContext,
+  CookieOptions,
+} from "./router/middleware.js";
+
+// Error classes and utilities
+export {
+  RouteNotFoundError,
+  DataNotFoundError,
+  notFound,
+  MiddlewareError,
+  HandlerError,
+  BuildError,
+  InvalidHandlerError,
+  sanitizeError,
+} from "./errors.js";
+
+// Component utilities
+export {
+  isClientComponent,
+  assertClientComponent,
+} from "./component-utils.js";
+
+// Types (re-exported for convenience)
+export type {
+  RouterEnv,
+  DefaultEnv,
+  RouteDefinition,
+  RouteConfig,
+  RouteDefinitionOptions,
+  TrailingSlashMode,
+  ResolvedRouteMap,
+  Handler,
+  HandlerContext,
+  HandlersForRouteMap,
+  ResolvedSegment,
+  SegmentMetadata,
+  MatchResult,
+  SlotState,
+  ExtractParams,
+  GenericParams,
+  RevalidateParams,
+  ShouldRevalidateFn,
+  RouteKeys,
+  RouteHandler,
+  RouteRevalidateFn,
+  RouteMiddlewareFn,
+  LoaderDefinition,
+  LoaderFn,
+  LoaderContext,
+  GetRegisteredRoutes,
+  // Error boundary types
+  ErrorInfo,
+  ErrorBoundaryFallbackProps,
+  ErrorBoundaryHandler,
+  ClientErrorBoundaryFallbackProps,
+  // NotFound boundary types
+  NotFoundInfo,
+  NotFoundBoundaryFallbackProps,
+  NotFoundBoundaryHandler,
+  // Error handling callback types
+  ErrorPhase,
+  OnErrorContext,
+  OnErrorCallback,
+} from "./types.js";

package/src/ssr/__tests__/ssr-handler.test.tsx

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi } from "vitest";
+import React from "react";
+import { createSSRHandler, type SSRDependencies } from "../index";
+
+describe("createSSRHandler", () => {
+  // Mock dependencies
+  const createMockDeps = (
+    overrides: Partial<SSRDependencies> = {}
+  ): SSRDependencies => ({
+    createFromReadableStream: vi.fn().mockResolvedValue({
+      root: React.createElement("div", null, "Test"),
+      metadata: { matched: ["/"], pathname: "/" },
+    }),
+    renderToReadableStream: vi.fn().mockResolvedValue(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode("<html><body>Test</body></html>"));
+          controller.close();
+        },
+      })
+    ),
+    injectRSCPayload: vi.fn().mockReturnValue(
+      new TransformStream({
+        transform(chunk, controller) {
+          controller.enqueue(chunk);
+        },
+      })
+    ),
+    loadBootstrapScriptContent: vi.fn().mockResolvedValue("console.log('bootstrap')"),
+    ...overrides,
+  });
+
+  const createMockRscStream = () =>
+    new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("mock rsc payload"));
+        controller.close();
+      },
+    });
+
+  describe("onError callback", () => {
+    it("should call onError when rendering fails", async () => {
+      const onError = vi.fn();
+      const renderError = new Error("Rendering failed");
+
+      const deps = createMockDeps({
+        renderToReadableStream: vi.fn().mockRejectedValue(renderError),
+        onError,
+      });
+
+      const renderHTML = createSSRHandler(deps);
+
+      await expect(renderHTML(createMockRscStream())).rejects.toThrow("Rendering failed");
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(onError).toHaveBeenCalledWith(renderError, { phase: "rendering" });
+    });
+
+    it("should call onError with phase: rendering", async () => {
+      const onError = vi.fn();
+
+      const deps = createMockDeps({
+        // Use loadBootstrapScriptContent error since it happens before React.use()
+        loadBootstrapScriptContent: vi.fn().mockRejectedValue(new Error("Bootstrap failed")),
+        onError,
+      });
+
+      const renderHTML = createSSRHandler(deps);
+
+      await expect(renderHTML(createMockRscStream())).rejects.toThrow("Bootstrap failed");
+
+      expect(onError).toHaveBeenCalledWith(
+        expect.any(Error),
+        { phase: "rendering" }
+      );
+    });
+
+    it("should convert non-Error objects to Error", async () => {
+      const onError = vi.fn();
+
+      const deps = createMockDeps({
+        renderToReadableStream: vi.fn().mockRejectedValue("string error"),
+        onError,
+      });
+
+      const renderHTML = createSSRHandler(deps);
+
+      await expect(renderHTML(createMockRscStream())).rejects.toThrow();
+
+      expect(onError).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: "string error",
+        }),
+        { phase: "rendering" }
+      );
+    });
+
+    it("should still throw original error after calling onError", async () => {
+      const onError = vi.fn();
+      const originalError = new Error("Original error");
+
+      const deps = createMockDeps({
+        loadBootstrapScriptContent: vi.fn().mockRejectedValue(originalError),
+        onError,
+      });
+
+      const renderHTML = createSSRHandler(deps);
+
+      await expect(renderHTML(createMockRscStream())).rejects.toThrow("Original error");
+
+      // Verify onError was called before error was thrown
+      expect(onError).toHaveBeenCalled();
+    });
+
+    it("should catch errors in onError callback and not break the flow", async () => {
+      const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      const callbackError = new Error("Callback exploded");
+      const onError = vi.fn().mockImplementation(() => {
+        throw callbackError;
+      });
+      const originalError = new Error("Original rendering error");
+
+      const deps = createMockDeps({
+        renderToReadableStream: vi.fn().mockRejectedValue(originalError),
+        onError,
+      });
+
+      const renderHTML = createSSRHandler(deps);
+
+      // Should throw original error, not callback error
+      await expect(renderHTML(createMockRscStream())).rejects.toThrow("Original rendering error");
+
+      expect(onError).toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        "[SSRHandler.onError] Callback error:",
+        callbackError
+      );
+
+      consoleErrorSpy.mockRestore();
+    });
+
+    it("should not call onError when rendering succeeds", async () => {
+      const onError = vi.fn();
+
+      const deps = createMockDeps({ onError });
+      const renderHTML = createSSRHandler(deps);
+
+      const result = await renderHTML(createMockRscStream());
+
+      expect(result).toBeInstanceOf(ReadableStream);
+      expect(onError).not.toHaveBeenCalled();
+    });
+
+    it("should work without onError callback", async () => {
+      const deps = createMockDeps({
+        renderToReadableStream: vi.fn().mockRejectedValue(new Error("No callback test")),
+        onError: undefined,
+      });
+
+      const renderHTML = createSSRHandler(deps);
+
+      // Should not throw because of missing onError
+      await expect(renderHTML(createMockRscStream())).rejects.toThrow("No callback test");
+    });
+  });
+
+  describe("successful rendering", () => {
+    it("should return a ReadableStream on success", async () => {
+      const deps = createMockDeps();
+      const renderHTML = createSSRHandler(deps);
+
+      const result = await renderHTML(createMockRscStream());
+
+      expect(result).toBeInstanceOf(ReadableStream);
+    });
+
+    it("should call all dependencies in correct order", async () => {
+      const deps = createMockDeps();
+      const renderHTML = createSSRHandler(deps);
+
+      await renderHTML(createMockRscStream());
+
+      expect(deps.loadBootstrapScriptContent).toHaveBeenCalled();
+      expect(deps.renderToReadableStream).toHaveBeenCalled();
+      expect(deps.injectRSCPayload).toHaveBeenCalled();
+    });
+  });
+});

package/src/ssr/index.tsx

@@ -0,0 +1,234 @@
+import React from "react";
+import { initHandleDataSync } from "../browser/react/use-handle.js";
+import { initSegmentsSync } from "../browser/react/use-segments.js";
+import { initThemeConfigSync } from "../theme/theme-context.js";
+import { ThemeProvider } from "../theme/ThemeProvider.js";
+import type { HandleData } from "../browser/types.js";
+import type { ErrorPhase } from "../types.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+
+/**
+ * Options for injectRSCPayload
+ */
+export interface InjectRSCPayloadOptions {
+  /**
+   * Nonce for Content Security Policy (CSP)
+   */
+  nonce?: string;
+}
+
+/**
+ * Options for renderToReadableStream from react-dom/server
+ */
+interface RenderToReadableStreamOptions {
+  bootstrapScriptContent?: string;
+  nonce?: string;
+  formState?: unknown;
+}
+
+/**
+ * Options for the renderHTML function
+ */
+export interface SSRRenderOptions {
+  /**
+   * Form state for useActionState progressive enhancement.
+   * This is the result of decodeFormState() and should be passed to
+   * react-dom's renderToReadableStream to enable useActionState to
+   * receive the action result during SSR.
+   */
+  formState?: unknown;
+
+  /**
+   * Nonce for Content Security Policy (CSP)
+   */
+  nonce?: string;
+}
+
+/**
+ * SSR dependencies from external packages
+ */
+export interface SSRDependencies<TEnv = unknown> {
+  /**
+   * createFromReadableStream from @vitejs/plugin-rsc/ssr
+   */
+  createFromReadableStream: <T>(stream: ReadableStream<Uint8Array>) => Promise<T>;
+
+  /**
+   * renderToReadableStream from react-dom/server.edge
+   */
+  renderToReadableStream: (
+    element: React.ReactNode,
+    options?: RenderToReadableStreamOptions
+  ) => Promise<ReadableStream<Uint8Array>>;
+
+  /**
+   * injectRSCPayload from rsc-html-stream/server
+   */
+  injectRSCPayload: (
+    rscStream: ReadableStream<Uint8Array>,
+    options?: InjectRSCPayloadOptions
+  ) => TransformStream<Uint8Array, Uint8Array>;
+
+  /**
+   * Function to load bootstrap script content
+   * Typically: () => import.meta.viteRsc.loadBootstrapScriptContent("index")
+   */
+  loadBootstrapScriptContent: () => Promise<string>;
+
+  /**
+   * Optional callback invoked when an error occurs during SSR rendering.
+   *
+   * This callback is for notification/logging purposes.
+   *
+   * @example
+   * ```typescript
+   * export const renderHTML = createSSRHandler({
+   *   // ... other deps
+   *   onError: (error, context) => {
+   *     console.error('[SSR] Rendering error:', error);
+   *     Sentry.captureException(error);
+   *   },
+   * });
+   * ```
+   */
+  onError?: (error: Error, context: { phase: ErrorPhase }) => void;
+}
+
+/**
+ * RSC payload type (minimal interface for SSR)
+ */
+interface RscPayload {
+  root: React.ReactNode;
+  metadata?: {
+    handles?: AsyncGenerator<HandleData, void, unknown>;
+    matched?: string[];
+    pathname?: string;
+    themeConfig?: ResolvedThemeConfig | null;
+    initialTheme?: Theme;
+  };
+}
+
+/**
+ * Consume an async generator and return a Promise that resolves with the final value.
+ * Used for SSR where we need to await all handle data before rendering.
+ */
+async function consumeAsyncGenerator(
+  generator: AsyncGenerator<HandleData, void, unknown>
+): Promise<HandleData> {
+  let lastData: HandleData = {};
+  for await (const data of generator) {
+    lastData = data;
+  }
+  return lastData;
+}
+
+/**
+ * Create an SSR handler that converts RSC streams to HTML.
+ *
+ * @example
+ * ```tsx
+ * import { createSSRHandler } from "rsc-router/ssr";
+ * import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+ * import { renderToReadableStream } from "react-dom/server.edge";
+ * import { injectRSCPayload } from "rsc-html-stream/server";
+ *
+ * export const renderHTML = createSSRHandler({
+ *   createFromReadableStream,
+ *   renderToReadableStream,
+ *   injectRSCPayload,
+ *   loadBootstrapScriptContent: () =>
+ *     import.meta.viteRsc.loadBootstrapScriptContent("index"),
+ * });
+ * ```
+ */
+export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
+  const {
+    createFromReadableStream,
+    renderToReadableStream,
+    injectRSCPayload,
+    loadBootstrapScriptContent,
+    onError,
+  } = deps;
+
+  /**
+   * Render RSC stream to HTML stream
+   *
+   * @param rscStream - The RSC stream to render
+   * @param options - Optional render options including formState for useActionState and nonce for CSP
+   */
+  return async function renderHTML(
+    rscStream: ReadableStream<Uint8Array>,
+    options?: SSRRenderOptions
+  ): Promise<ReadableStream<Uint8Array>> {
+    const { nonce, formState } = options ?? {};
+
+    try {
+      // Tee the stream:
+      // - rscStream1: For SSR rendering (deserialize to React VDOM)
+      // - rscStream2: For browser hydration (inject as __FLIGHT_DATA__)
+      const [rscStream1, rscStream2] = rscStream.tee();
+
+      // Deserialize RSC stream to React tree
+      let payload: Promise<RscPayload> | undefined;
+      let handlesPromise: Promise<HandleData> | undefined;
+      function SsrRoot() {
+        payload ??= createFromReadableStream<RscPayload>(rscStream1);
+        const resolved = React.use(payload);
+
+        // Initialize segments state before children render (for useSegments hook)
+        initSegmentsSync(resolved.metadata?.matched, resolved.metadata?.pathname);
+
+        // Initialize theme config for MetaTags to render theme script
+        const themeConfig = resolved.metadata?.themeConfig ?? null;
+        initThemeConfigSync(themeConfig);
+
+        // Await handles and initialize state before children render
+        // The handles property is an async generator that yields on each push
+        // Memoize the promise since async generators can only be iterated once
+        if (resolved.metadata?.handles) {
+          handlesPromise ??= consumeAsyncGenerator(resolved.metadata.handles);
+          const handleData = React.use(handlesPromise);
+          initHandleDataSync(handleData, resolved.metadata.matched);
+        }
+
+        // Wrap content with ThemeProvider if theme is enabled
+        // This provides the theme context for client components that use useTheme
+        if (themeConfig) {
+          return (
+            <ThemeProvider config={themeConfig} initialTheme={resolved.metadata?.initialTheme}>
+              {resolved.root}
+            </ThemeProvider>
+          );
+        }
+
+        return resolved.root;
+      }
+
+      // Get bootstrap script content
+      const bootstrapScriptContent = await loadBootstrapScriptContent();
+
+      // Render React tree to HTML stream
+      // Pass formState for useActionState progressive enhancement if provided
+      // Pass nonce for CSP if provided
+      const htmlStream = await renderToReadableStream(<SsrRoot />, {
+        bootstrapScriptContent,
+        formState,
+        nonce,
+      });
+
+      // Inject RSC payload into HTML as <script nonce="...">__FLIGHT_DATA__</script>
+      return htmlStream.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
+    } catch (error) {
+      // Invoke onError callback if provided
+      if (onError) {
+        const errorObj = error instanceof Error ? error : new Error(String(error));
+        try {
+          onError(errorObj, { phase: "rendering" });
+        } catch (callbackError) {
+          console.error("[SSRHandler.onError] Callback error:", callbackError);
+        }
+      }
+      throw error;
+    }
+  };
+}