npm - @ivogt/rsc-router - Versions diffs - 0.0.0-experimental.1 - Mend

@ivogt/rsc-router 0.0.0-experimental.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (123) hide show

package/README.md +19 -0
package/package.json +131 -0
package/src/__mocks__/version.ts +6 -0
package/src/__tests__/route-definition.test.ts +63 -0
package/src/browser/event-controller.ts +876 -0
package/src/browser/index.ts +18 -0
package/src/browser/link-interceptor.ts +121 -0
package/src/browser/lru-cache.ts +69 -0
package/src/browser/merge-segment-loaders.ts +126 -0
package/src/browser/navigation-bridge.ts +891 -0
package/src/browser/navigation-client.ts +155 -0
package/src/browser/navigation-store.ts +823 -0
package/src/browser/partial-update.ts +545 -0
package/src/browser/react/Link.tsx +248 -0
package/src/browser/react/NavigationProvider.tsx +228 -0
package/src/browser/react/ScrollRestoration.tsx +94 -0
package/src/browser/react/context.ts +53 -0
package/src/browser/react/index.ts +52 -0
package/src/browser/react/location-state-shared.ts +120 -0
package/src/browser/react/location-state.ts +62 -0
package/src/browser/react/use-action.ts +240 -0
package/src/browser/react/use-client-cache.ts +56 -0
package/src/browser/react/use-handle.ts +178 -0
package/src/browser/react/use-link-status.ts +134 -0
package/src/browser/react/use-navigation.ts +150 -0
package/src/browser/react/use-segments.ts +188 -0
package/src/browser/request-controller.ts +149 -0
package/src/browser/rsc-router.tsx +310 -0
package/src/browser/scroll-restoration.ts +324 -0
package/src/browser/server-action-bridge.ts +747 -0
package/src/browser/shallow.ts +35 -0
package/src/browser/types.ts +443 -0
package/src/cache/__tests__/memory-segment-store.test.ts +487 -0
package/src/cache/__tests__/memory-store.test.ts +484 -0
package/src/cache/cache-scope.ts +565 -0
package/src/cache/cf/__tests__/cf-cache-store.test.ts +361 -0
package/src/cache/cf/cf-cache-store.ts +274 -0
package/src/cache/cf/index.ts +19 -0
package/src/cache/index.ts +52 -0
package/src/cache/memory-segment-store.ts +150 -0
package/src/cache/memory-store.ts +253 -0
package/src/cache/types.ts +366 -0
package/src/client.rsc.tsx +88 -0
package/src/client.tsx +609 -0
package/src/components/DefaultDocument.tsx +20 -0
package/src/default-error-boundary.tsx +88 -0
package/src/deps/browser.ts +8 -0
package/src/deps/html-stream-client.ts +2 -0
package/src/deps/html-stream-server.ts +2 -0
package/src/deps/rsc.ts +10 -0
package/src/deps/ssr.ts +2 -0
package/src/errors.ts +259 -0
package/src/handle.ts +120 -0
package/src/handles/MetaTags.tsx +178 -0
package/src/handles/index.ts +6 -0
package/src/handles/meta.ts +247 -0
package/src/href-client.ts +128 -0
package/src/href.ts +139 -0
package/src/index.rsc.ts +69 -0
package/src/index.ts +84 -0
package/src/loader.rsc.ts +204 -0
package/src/loader.ts +47 -0
package/src/network-error-thrower.tsx +21 -0
package/src/outlet-context.ts +15 -0
package/src/root-error-boundary.tsx +277 -0
package/src/route-content-wrapper.tsx +198 -0
package/src/route-definition.ts +1333 -0
package/src/route-map-builder.ts +140 -0
package/src/route-types.ts +148 -0
package/src/route-utils.ts +89 -0
package/src/router/__tests__/match-context.test.ts +104 -0
package/src/router/__tests__/match-pipelines.test.ts +537 -0
package/src/router/__tests__/match-result.test.ts +566 -0
package/src/router/__tests__/on-error.test.ts +935 -0
package/src/router/__tests__/pattern-matching.test.ts +577 -0
package/src/router/error-handling.ts +287 -0
package/src/router/handler-context.ts +60 -0
package/src/router/loader-resolution.ts +326 -0
package/src/router/manifest.ts +116 -0
package/src/router/match-context.ts +261 -0
package/src/router/match-middleware/background-revalidation.ts +236 -0
package/src/router/match-middleware/cache-lookup.ts +261 -0
package/src/router/match-middleware/cache-store.ts +250 -0
package/src/router/match-middleware/index.ts +81 -0
package/src/router/match-middleware/intercept-resolution.ts +268 -0
package/src/router/match-middleware/segment-resolution.ts +174 -0
package/src/router/match-pipelines.ts +214 -0
package/src/router/match-result.ts +212 -0
package/src/router/metrics.ts +62 -0
package/src/router/middleware.test.ts +1355 -0
package/src/router/middleware.ts +748 -0
package/src/router/pattern-matching.ts +271 -0
package/src/router/revalidation.ts +190 -0
package/src/router/router-context.ts +299 -0
package/src/router/types.ts +96 -0
package/src/router.ts +3484 -0
package/src/rsc/__tests__/helpers.test.ts +175 -0
package/src/rsc/handler.ts +942 -0
package/src/rsc/helpers.ts +64 -0
package/src/rsc/index.ts +56 -0
package/src/rsc/nonce.ts +18 -0
package/src/rsc/types.ts +225 -0
package/src/segment-system.tsx +405 -0
package/src/server/__tests__/request-context.test.ts +171 -0
package/src/server/context.ts +340 -0
package/src/server/handle-store.ts +230 -0
package/src/server/loader-registry.ts +174 -0
package/src/server/request-context.ts +470 -0
package/src/server/root-layout.tsx +10 -0
package/src/server/tsconfig.json +14 -0
package/src/server.ts +126 -0
package/src/ssr/__tests__/ssr-handler.test.tsx +188 -0
package/src/ssr/index.tsx +215 -0
package/src/types.ts +1473 -0
package/src/use-loader.tsx +346 -0
package/src/vite/__tests__/expose-loader-id.test.ts +117 -0
package/src/vite/expose-action-id.ts +344 -0
package/src/vite/expose-handle-id.ts +209 -0
package/src/vite/expose-loader-id.ts +357 -0
package/src/vite/expose-location-state-id.ts +177 -0
package/src/vite/index.ts +608 -0
package/src/vite/version.d.ts +12 -0
package/src/vite/virtual-entries.ts +109 -0

package/src/server.ts ADDED Viewed

@@ -0,0 +1,126 @@
+/**
+ * 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 InterceptSelectorContext,
+  type InterceptSegmentsState,
+  type InterceptWhenFn,
+} from "./route-definition.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 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";
+// 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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,215 @@
+import React from "react";
+import { initHandleDataSync } from "../browser/react/use-handle.js";
+import { initSegmentsSync } from "../browser/react/use-segments.js";
+import type { HandleData } from "../browser/types.js";
+import type { ErrorPhase } from "../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;
+  };
+}
+/**
+ * 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);
+        // 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);
+        }
+        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;
+    }
+  };
+}