@ivogt/rsc-router 0.0.0-experimental.1

package/src/deps/browser.ts

@@ -0,0 +1,8 @@
+// Re-export @vitejs/plugin-rsc/browser for internal use by virtual entries
+export {
+  createFromReadableStream,
+  createFromFetch,
+  setServerCallback,
+  encodeReply,
+  createTemporaryReferenceSet,
+} from "@vitejs/plugin-rsc/browser";

package/src/deps/html-stream-client.ts

@@ -0,0 +1,2 @@
+// Re-export rsc-html-stream/client for internal use by virtual entries
+export { rscStream } from "rsc-html-stream/client";

package/src/deps/html-stream-server.ts

@@ -0,0 +1,2 @@
+// Re-export rsc-html-stream/server for internal use by virtual entries
+export { injectRSCPayload } from "rsc-html-stream/server";

package/src/deps/rsc.ts

@@ -0,0 +1,10 @@
+/// <reference types="@vitejs/plugin-rsc/types" />
+// Re-export @vitejs/plugin-rsc/rsc for internal use by virtual entries
+export {
+  renderToReadableStream,
+  decodeReply,
+  createTemporaryReferenceSet,
+  loadServerAction,
+  decodeAction,
+  decodeFormState,
+} from "@vitejs/plugin-rsc/rsc";

package/src/deps/ssr.ts

@@ -0,0 +1,2 @@
+// Re-export @vitejs/plugin-rsc/ssr for internal use by virtual entries
+export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";

package/src/errors.ts

@@ -0,0 +1,259 @@
+/**
+ * Custom error classes for RSC Router
+ *
+ * All errors include:
+ * - Descriptive names for easy identification
+ * - Cause property for structured debugging data
+ */
+
+/**
+ * Options for error construction
+ */
+interface ErrorOptions {
+  cause?: unknown;
+}
+
+/**
+ * Thrown when no route matches the requested pathname
+ */
+export class RouteNotFoundError extends Error {
+  name = "RouteNotFoundError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Thrown when data is not found (e.g., product with ID doesn't exist)
+ * Use this in handlers/loaders to trigger the nearest notFoundBoundary
+ *
+ * @example
+ * ```typescript
+ * route("products.detail", async (ctx) => {
+ *   const product = await db.products.get(ctx.params.slug);
+ *   if (!product) throw new DataNotFoundError("Product not found");
+ *   return <ProductDetail product={product} />;
+ * });
+ * ```
+ */
+export class DataNotFoundError extends Error {
+  name = "DataNotFoundError" as const;
+  cause?: unknown;
+
+  constructor(message: string = "Not found", options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Convenience function to throw a DataNotFoundError
+ * Shorter syntax for common not-found scenarios
+ *
+ * @example
+ * ```typescript
+ * const product = await db.products.get(slug);
+ * if (!product) throw notFound("Product not found");
+ * // or simply:
+ * if (!product) throw notFound();
+ * ```
+ */
+export function notFound(message?: string): never {
+  throw new DataNotFoundError(message);
+}
+
+/**
+ * Thrown when middleware execution fails
+ */
+export class MiddlewareError extends Error {
+  name = "MiddlewareError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Thrown when a route handler fails
+ */
+export class HandlerError extends Error {
+  name = "HandlerError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Thrown when segment building fails
+ */
+export class BuildError extends Error {
+  name = "BuildError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Thrown when a network request fails (server unreachable, no internet, etc.)
+ * This error triggers the root error boundary with retry capability.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await fetch(url);
+ * } catch (error) {
+ *   if (error instanceof TypeError) {
+ *     throw new NetworkError("Unable to connect to server", { cause: error });
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export class NetworkError extends Error {
+  name = "NetworkError" as const;
+  cause?: unknown;
+  /** The URL that failed to fetch */
+  url?: string;
+  /** Whether this was during an action, navigation, or revalidation */
+  operation?: "action" | "navigation" | "revalidation";
+
+  constructor(
+    message: string = "Network request failed",
+    options?: ErrorOptions & {
+      url?: string;
+      operation?: "action" | "navigation" | "revalidation";
+    }
+  ) {
+    super(message);
+    this.cause = options?.cause;
+    this.url = options?.url;
+    this.operation = options?.operation;
+  }
+}
+
+/**
+ * Check if an error is a network-level failure (server unreachable, no internet)
+ * These are typically TypeError from fetch when the network request itself fails.
+ */
+export function isNetworkError(error: unknown): boolean {
+  // NetworkError we throw ourselves
+  if (error instanceof NetworkError) {
+    return true;
+  }
+
+  // TypeError from fetch() when network fails (e.g., "Failed to fetch")
+  if (error instanceof TypeError) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("failed to fetch") ||
+      message.includes("network request failed") ||
+      message.includes("networkerror") ||
+      message.includes("load failed")
+    );
+  }
+
+  // DOMException with network-related names
+  if (error instanceof DOMException) {
+    return error.name === "NetworkError";
+  }
+
+  return false;
+}
+
+/**
+ * Thrown when route handler returns invalid type
+ */
+export class InvalidHandlerError extends Error {
+  name = "InvalidHandlerError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Internal invariant assertion for development-time checks
+ *
+ * @internal
+ * @param condition - Condition that must be true
+ * @param message - Error message to throw if condition is false
+ * @throws {Error} If condition is false
+ *
+ * @example
+ * ```typescript
+ * invariant(user !== null, 'User must be defined');
+ * invariant(node.type === 'layout', `Expected layout, got ${node.type}`);
+ * ```
+ */
+export function invariant(condition: any, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(`Invariant: ${message}`);
+  }
+}
+
+/**
+ * Sanitize errors for production - prevents leaking sensitive information
+ *
+ * SECURITY CRITICAL:
+ * - In production: NEVER send stack traces, file paths, or internal state
+ * - In development: Show full error details for debugging
+ * - ALWAYS consume error.stack to prevent memory leaks
+ *
+ * @param error - Error to sanitize
+ * @returns Response suitable for sending to client
+ */
+export function sanitizeError(error: unknown): Response {
+  // CRITICAL: Consume stack trace to prevent memory leaks
+  if (error && typeof error === "object" && "stack" in error) {
+    const _ = error.stack; // Force V8 to generate/consume stack trace
+  }
+
+  // Response objects are safe to return as-is
+  if (error instanceof Response) {
+    return error;
+  }
+
+  const isDev = (import.meta as any).env?.DEV ?? true;
+
+  if (isDev) {
+    // Development: Send full error details for debugging
+    const errorDetails = {
+      name: error instanceof Error ? error.name : "Error",
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      cause:
+        error && typeof error === "object" && "cause" in error
+          ? (error as any).cause
+          : undefined,
+    };
+
+    return new Response(JSON.stringify(errorDetails, null, 2), {
+      status: 500,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  }
+
+  // Production: Generic error only - NO internal details
+  // SECURITY: Never leak stack traces, file paths, or application state
+  return new Response("Internal Server Error", {
+    status: 500,
+    headers: {
+      "Content-Type": "text/plain",
+    },
+  });
+}

package/src/handle.ts

@@ -0,0 +1,120 @@
+/**
+ * Handle definition for accumulating data across route segments.
+ *
+ * Handles allow server-side route handlers to pass accumulated data to client
+ * components. Unlike loaders (which fetch data for specific routes), handles
+ * accumulate data across all matched route segments.
+ *
+ * @example
+ * ```ts
+ * // Define a handle (name auto-generated from file + export)
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ *
+ * // Use in handler
+ * const push = ctx.use(Breadcrumbs);
+ * push({ label: "Home", href: "/" });
+ *
+ * // Consume on client
+ * const crumbs = useHandle(Breadcrumbs);
+ * ```
+ */
+export interface Handle<TData, TAccumulated = TData[]> {
+  /**
+   * Brand to distinguish handles from loaders in ctx.use()
+   */
+  readonly __brand: "handle";
+
+  /**
+   * Auto-generated unique ID for this handle (used as key in storage)
+   * Format: "filePath#ExportName" in dev, "hash#ExportName" in production
+   */
+  readonly $$id: string;
+
+  /**
+   * Collect function to transform segment data into final value.
+   * Receives array of arrays - each inner array contains values pushed
+   * by one segment, ordered parent-to-child.
+   *
+   * @param segments - Array of segment data arrays, e.g. [[a, b], [c], [d, e]]
+   * @returns The accumulated value
+   */
+  readonly collect: (segments: TData[][]) => TAccumulated;
+}
+
+/**
+ * Default collect function that flattens segment arrays into a single array.
+ */
+function defaultCollect<T>(segments: T[][]): T[] {
+  return segments.flat();
+}
+
+/**
+ * Create a handle definition for accumulating data across route segments.
+ *
+ * The $$id is auto-generated by the Vite exposeHandleId plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * @param collect - Optional collect function (default: flatten into array)
+ * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
+ *
+ * @example
+ * ```ts
+ * // Default: flatten into array
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Result type: BreadcrumbItem[]
+ *
+ * // Custom: last value wins
+ * export const PageTitle = createHandle<string, string>(
+ *   (segments) => segments.flat().at(-1) ?? "Default Title"
+ * );
+ * // Result type: string
+ *
+ * // Custom: object merge
+ * export const Meta = createHandle<Partial<MetaTags>, MetaTags>(
+ *   (segments) => Object.assign({ robots: "index,follow" }, ...segments.flat())
+ * );
+ * // Result type: MetaTags
+ *
+ * // Custom: dedupe by href
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>(
+ *   (segments) => {
+ *     const all = segments.flat();
+ *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
+ *   }
+ * );
+ * ```
+ */
+export function createHandle<TData, TAccumulated = TData[]>(
+  collect?: (segments: TData[][]) => TAccumulated,
+  __injectedId?: string
+): Handle<TData, TAccumulated> {
+  const handleId = __injectedId ?? "";
+
+  if (!handleId && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[rsc-router] Handle is missing $$id. " +
+        "Make sure the exposeHandleId Vite plugin is enabled and " +
+        "the handle is exported with: export const MyHandle = createHandle(...)"
+    );
+  }
+
+  return {
+    __brand: "handle" as const,
+    $$id: handleId,
+    collect:
+      collect ??
+      (defaultCollect as unknown as (segments: TData[][]) => TAccumulated),
+  };
+}
+
+/**
+ * Type guard to check if a value is a Handle.
+ */
+export function isHandle(value: unknown): value is Handle<unknown, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "handle"
+  );
+}

package/src/handles/MetaTags.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+/**
+ * Component to render collected meta descriptors in the document head.
+ *
+ * Supports both sync and async meta descriptors. Async descriptors
+ * (Promise<MetaDescriptorBase>) are resolved using React's use() hook.
+ *
+ * @example
+ * ```tsx
+ * function RootLayout() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <MetaTags />
+ *       </head>
+ *       <body>...</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+
+import { use } from "react";
+import { useHandle } from "../browser/react/use-handle.ts";
+import { Meta } from "./meta.ts";
+import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.ts";
+
+// Type guards for MetaDescriptorBase variants
+function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
+  return "charSet" in d && d.charSet === "utf-8";
+}
+
+function hasTitle(d: MetaDescriptorBase): d is { title: string } {
+  return "title" in d && typeof (d as { title?: unknown }).title === "string";
+}
+
+function hasNameContent(d: MetaDescriptorBase): d is { name: string; content: string } {
+  return "name" in d && "content" in d &&
+    typeof (d as { name?: unknown }).name === "string" &&
+    typeof (d as { content?: unknown }).content === "string";
+}
+
+function hasPropertyContent(d: MetaDescriptorBase): d is { property: string; content: string } {
+  return "property" in d && "content" in d &&
+    typeof (d as { property?: unknown }).property === "string" &&
+    typeof (d as { content?: unknown }).content === "string";
+}
+
+function hasHttpEquivContent(d: MetaDescriptorBase): d is { httpEquiv: string; content: string } {
+  return "httpEquiv" in d && "content" in d &&
+    typeof (d as { httpEquiv?: unknown }).httpEquiv === "string" &&
+    typeof (d as { content?: unknown }).content === "string";
+}
+
+function hasScriptLdJson(d: MetaDescriptorBase): d is { "script:ld+json": object } {
+  return "script:ld+json" in d;
+}
+
+function hasTagName(d: MetaDescriptorBase): d is { tagName: "meta" | "link"; [name: string]: string } {
+  return "tagName" in d && ((d as { tagName?: unknown }).tagName === "meta" || (d as { tagName?: unknown }).tagName === "link");
+}
+
+/**
+ * Check if a value is a Promise.
+ */
+function isPromise(value: unknown): value is Promise<unknown> {
+  return value !== null && typeof value === "object" && "then" in value;
+}
+
+/**
+ * Render a single meta descriptor as a React element.
+ */
+function renderMetaDescriptor(
+  descriptor: MetaDescriptorBase,
+  index: number
+): React.ReactNode {
+  // charset
+  if (hasCharSet(descriptor)) {
+    return <meta key="charSet" charSet={descriptor.charSet} />;
+  }
+
+  // title
+  if (hasTitle(descriptor)) {
+    return <title key="title">{descriptor.title}</title>;
+  }
+
+  // name + content (description, viewport, etc.)
+  if (hasNameContent(descriptor)) {
+    return (
+      <meta
+        key={`name-${descriptor.name}`}
+        name={descriptor.name}
+        content={descriptor.content}
+      />
+    );
+  }
+
+  // property + content (Open Graph, etc.)
+  if (hasPropertyContent(descriptor)) {
+    return (
+      <meta
+        key={`property-${descriptor.property}`}
+        property={descriptor.property}
+        content={descriptor.content}
+      />
+    );
+  }
+
+  // http-equiv + content
+  if (hasHttpEquivContent(descriptor)) {
+    return (
+      <meta
+        key={`httpEquiv-${descriptor.httpEquiv}`}
+        httpEquiv={descriptor.httpEquiv}
+        content={descriptor.content}
+      />
+    );
+  }
+
+  // JSON-LD structured data
+  if (hasScriptLdJson(descriptor)) {
+    const json = JSON.stringify(descriptor["script:ld+json"]);
+    return (
+      <script
+        key={`ld-json-${index}`}
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: json }}
+      />
+    );
+  }
+
+  // Custom tagName (meta or link with arbitrary attributes)
+  if (hasTagName(descriptor)) {
+    const { tagName, ...rest } = descriptor;
+    if (tagName === "link") {
+      return <link key={`link-${index}`} {...(rest as React.LinkHTMLAttributes<HTMLLinkElement>)} />;
+    }
+    if (tagName === "meta") {
+      return <meta key={`meta-${index}`} {...(rest as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+    }
+  }
+
+  // Fallback: treat as meta attributes
+  return <meta key={`meta-fallback-${index}`} {...(descriptor as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+}
+
+/**
+ * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
+ */
+function AsyncMetaTag({ promise, index }: { promise: Promise<MetaDescriptorBase>; index: number }): React.ReactNode {
+  const resolved = use(promise);
+  return renderMetaDescriptor(resolved, index);
+}
+
+/**
+ * Renders all collected meta descriptors from route handlers.
+ *
+ * Place this component inside the `<head>` element of your document.
+ * It will automatically update when meta descriptors change during navigation.
+ *
+ * Async meta descriptors (Promise<MetaDescriptorBase>) are resolved using
+ * React's use() hook. RSC streaming handles the Promise resolution.
+ */
+export function MetaTags(): React.ReactNode {
+  const descriptors = useHandle(Meta) as MetaDescriptor[];
+
+  return (
+    <>
+      {descriptors.map((descriptor, index) => {
+        if (isPromise(descriptor)) {
+          return <AsyncMetaTag key={`async-${index}`} promise={descriptor} index={index} />;
+        }
+        return renderMetaDescriptor(descriptor, index);
+      })}
+    </>
+  );
+}

package/src/handles/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in handles for rsc-router.
+ */
+
+export { Meta } from "./meta.ts";
+export { MetaTags } from "./MetaTags.tsx";