@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20dbba0c

package/src/context-var.ts

@@ -0,0 +1,156 @@
+/**
+ * Typed context variables for ctx.set() / ctx.get().
+ *
+ * createVar<T>() produces a typed token that handlers set and layouts/middleware
+ * read. The token carries a unique Symbol used as the property key on the
+ * per-request variables object — no build-time processing, no IDs.
+ *
+ * @example
+ * ```ts
+ * import { createVar } from "@rangojs/router";
+ *
+ * interface PaginationData { current: number; total: number }
+ * export const Pagination = createVar<PaginationData>();
+ *
+ * // Non-cacheable var — throws if set/get inside cache() or "use cache"
+ * export const User = createVar<UserData>({ cache: false });
+ *
+ * // handler
+ * ctx.set(Pagination, { current: 1, total: 4 });
+ *
+ * // layout
+ * const pg = ctx.get(Pagination); // PaginationData | undefined
+ * ```
+ */
+
+export interface ContextVar<T> {
+  readonly __brand: "context-var";
+  readonly key: symbol;
+  /** When false, the var is non-cacheable — throws inside cache() / "use cache" */
+  readonly cache: boolean;
+  /** Phantom field to carry the type parameter. Never set at runtime. */
+  readonly __type?: T;
+}
+
+export interface ContextVarOptions {
+  /**
+   * When false, marks this variable as non-cacheable.
+   * Setting or getting this var inside a cache() boundary or "use cache"
+   * function will throw. Use for inherently request-specific data (user
+   * sessions, auth tokens, etc.) that must never be baked into cached segments.
+   *
+   * @default true
+   */
+  cache?: boolean;
+}
+
+/**
+ * Create a typed context variable token.
+ *
+ * The returned object is used with ctx.set(token, value) and ctx.get(token)
+ * for compile-time-checked data flow between handlers, layouts, and middleware.
+ */
+export function createVar<T>(options?: ContextVarOptions): ContextVar<T> {
+  return {
+    __brand: "context-var" as const,
+    key: Symbol(),
+    cache: options?.cache !== false,
+  };
+}
+
+/**
+ * Type guard: is the value a ContextVar token?
+ */
+export function isContextVar(value: unknown): value is ContextVar<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "context-var"
+  );
+}
+
+/**
+ * Symbol used as a Set stored on the variables object to track
+ * which keys hold non-cacheable values (from write-level { cache: false }).
+ */
+const NON_CACHEABLE_KEYS: unique symbol = Symbol.for(
+  "rango:non-cacheable-keys",
+) as any;
+
+function getNonCacheableKeys(variables: any): Set<string | symbol> {
+  if (!variables[NON_CACHEABLE_KEYS]) {
+    variables[NON_CACHEABLE_KEYS] = new Set();
+  }
+  return variables[NON_CACHEABLE_KEYS];
+}
+
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export function isNonCacheable(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): boolean {
+  if (typeof keyOrVar !== "string" && !keyOrVar.cache) {
+    return true; // var-level policy
+  }
+  const key = typeof keyOrVar === "string" ? keyOrVar : keyOrVar.key;
+  const set = variables[NON_CACHEABLE_KEYS] as Set<string | symbol> | undefined;
+  return set?.has(key) ?? false; // write-level policy
+}
+
+/**
+ * Read a variable from the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export function contextGet(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+): any {
+  if (typeof keyOrVar === "string") return variables[keyOrVar];
+  return variables[keyOrVar.key];
+}
+
+/** Keys that must never be used as string variable names */
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+export interface ContextSetOptions {
+  /**
+   * When false, marks this specific write as non-cacheable.
+   * "Least cacheable wins" — if either the var definition or this option
+   * says cache: false, the value is non-cacheable.
+   *
+   * @default true (inherits from createVar)
+   */
+  cache?: boolean;
+}
+
+/**
+ * Write a variable to the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export function contextSet(
+  variables: any,
+  keyOrVar: string | ContextVar<any>,
+  value: any,
+  options?: ContextSetOptions,
+): void {
+  if (typeof keyOrVar === "string") {
+    if (FORBIDDEN_KEYS.has(keyOrVar)) {
+      throw new Error(
+        `ctx.set(): "${keyOrVar}" is a reserved key and cannot be used as a variable name.`,
+      );
+    }
+    variables[keyOrVar] = value;
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar);
+    }
+  } else {
+    variables[keyOrVar.key] = value;
+    // Track write-level non-cacheable (var-level is checked via keyOrVar.cache)
+    if (options?.cache === false) {
+      getNonCacheableKeys(variables).add(keyOrVar.key);
+    }
+  }
+}

package/src/debug.ts

@@ -0,0 +1,243 @@
+/**
+ * Debug utilities for manifest inspection and comparison
+ */
+
+import { getParallelSlotCount, type EntryData } from "./server/context";
+
+/**
+ * Serialized entry for debug output
+ */
+export interface SerializedEntry {
+  id: string;
+  shortCode: string;
+  type: string;
+  parentShortCode: string | null;
+  pattern?: string;
+  hasLoader: boolean;
+  hasMiddleware: boolean;
+  hasErrorBoundary: boolean;
+  parallelCount: number;
+  interceptCount: number;
+}
+
+/**
+ * Serialized manifest structure
+ */
+export interface SerializedManifest {
+  routes: Record<string, SerializedEntry>;
+  layouts: Record<string, SerializedEntry>;
+  totalRoutes: number;
+  totalLayouts: number;
+}
+
+/**
+ * Serialize a manifest Map into a JSON-friendly structure
+ */
+export function serializeManifest(
+  manifest: Map<string, EntryData>,
+): SerializedManifest {
+  const routes: Record<string, SerializedEntry> = {};
+  const layouts: Record<string, SerializedEntry> = {};
+
+  // Collect all entries including parents
+  const allEntries = new Map<string, EntryData>();
+
+  for (const [key, entry] of manifest.entries()) {
+    allEntries.set(key, entry);
+
+    // Walk up parent chain to collect all layouts
+    let parent = entry.parent;
+    while (parent) {
+      if (!allEntries.has(parent.id)) {
+        allEntries.set(parent.id, parent);
+      }
+      parent = parent.parent;
+    }
+  }
+
+  for (const [key, entry] of allEntries.entries()) {
+    const serialized: SerializedEntry = {
+      id: entry.id,
+      shortCode: entry.shortCode,
+      type: entry.type,
+      parentShortCode: entry.parent?.shortCode ?? null,
+      hasLoader: entry.loader?.length > 0,
+      hasMiddleware: entry.middleware?.length > 0,
+      hasErrorBoundary: entry.errorBoundary?.length > 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
+      interceptCount: entry.intercept?.length ?? 0,
+    };
+
+    if (entry.type === "route" && "pattern" in entry) {
+      serialized.pattern = entry.pattern;
+    }
+
+    if (entry.type === "route") {
+      routes[key] = serialized;
+    } else if (entry.type === "layout" || entry.type === "cache") {
+      layouts[key] = serialized;
+    }
+  }
+
+  return {
+    routes,
+    layouts,
+    totalRoutes: Object.keys(routes).length,
+    totalLayouts: Object.keys(layouts).length,
+  };
+}
+
+/**
+ * Compare two manifests and return differences
+ */
+export function compareManifests(
+  oldManifest: SerializedManifest,
+  newManifest: SerializedManifest,
+): {
+  addedRoutes: string[];
+  removedRoutes: string[];
+  changedRoutes: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }>;
+  addedLayouts: string[];
+  removedLayouts: string[];
+  changedLayouts: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }>;
+} {
+  const addedRoutes: string[] = [];
+  const removedRoutes: string[] = [];
+  const changedRoutes: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }> = [];
+  const addedLayouts: string[] = [];
+  const removedLayouts: string[] = [];
+  const changedLayouts: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }> = [];
+
+  // Compare routes
+  const oldRouteKeys = new Set(Object.keys(oldManifest.routes));
+  const newRouteKeys = new Set(Object.keys(newManifest.routes));
+
+  for (const key of newRouteKeys) {
+    if (!oldRouteKeys.has(key)) {
+      addedRoutes.push(key);
+    }
+  }
+
+  for (const key of oldRouteKeys) {
+    if (!newRouteKeys.has(key)) {
+      removedRoutes.push(key);
+    } else {
+      // Compare fields
+      const oldEntry = oldManifest.routes[key];
+      const newEntry = newManifest.routes[key];
+      for (const field of Object.keys(oldEntry) as (keyof SerializedEntry)[]) {
+        if (oldEntry[field] !== newEntry[field]) {
+          changedRoutes.push({
+            key,
+            field,
+            old: oldEntry[field],
+            new: newEntry[field],
+          });
+        }
+      }
+    }
+  }
+
+  // Compare layouts
+  const oldLayoutKeys = new Set(Object.keys(oldManifest.layouts));
+  const newLayoutKeys = new Set(Object.keys(newManifest.layouts));
+
+  for (const key of newLayoutKeys) {
+    if (!oldLayoutKeys.has(key)) {
+      addedLayouts.push(key);
+    }
+  }
+
+  for (const key of oldLayoutKeys) {
+    if (!newLayoutKeys.has(key)) {
+      removedLayouts.push(key);
+    } else {
+      const oldEntry = oldManifest.layouts[key];
+      const newEntry = newManifest.layouts[key];
+      for (const field of Object.keys(oldEntry) as (keyof SerializedEntry)[]) {
+        if (oldEntry[field] !== newEntry[field]) {
+          changedLayouts.push({
+            key,
+            field,
+            old: oldEntry[field],
+            new: newEntry[field],
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    addedRoutes,
+    removedRoutes,
+    changedRoutes,
+    addedLayouts,
+    removedLayouts,
+    changedLayouts,
+  };
+}
+
+/**
+ * Format manifest diff as a human-readable string
+ */
+export function formatManifestDiff(
+  diff: ReturnType<typeof compareManifests>,
+): string {
+  const lines: string[] = [];
+
+  if (diff.addedRoutes.length > 0) {
+    lines.push("Added routes:");
+    diff.addedRoutes.forEach((r) => lines.push(`  + ${r}`));
+  }
+
+  if (diff.removedRoutes.length > 0) {
+    lines.push("Removed routes:");
+    diff.removedRoutes.forEach((r) => lines.push(`  - ${r}`));
+  }
+
+  if (diff.changedRoutes.length > 0) {
+    lines.push("Changed routes:");
+    diff.changedRoutes.forEach((c) =>
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
+    );
+  }
+
+  if (diff.addedLayouts.length > 0) {
+    lines.push("Added layouts:");
+    diff.addedLayouts.forEach((l) => lines.push(`  + ${l}`));
+  }
+
+  if (diff.removedLayouts.length > 0) {
+    lines.push("Removed layouts:");
+    diff.removedLayouts.forEach((l) => lines.push(`  - ${l}`));
+  }
+
+  if (diff.changedLayouts.length > 0) {
+    lines.push("Changed layouts:");
+    diff.changedLayouts.forEach((c) =>
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
+    );
+  }
+
+  return lines.length > 0 ? lines.join("\n") : "No differences found";
+}

package/src/errors.ts

@@ -22,6 +22,7 @@ export class RouteNotFoundError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, RouteNotFoundError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -45,6 +46,7 @@ export class DataNotFoundError extends Error {
 
   constructor(message: string = "Not found", options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, DataNotFoundError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -74,6 +76,7 @@ export class MiddlewareError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, MiddlewareError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -87,6 +90,7 @@ export class HandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, HandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -100,6 +104,7 @@ export class BuildError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, BuildError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -133,9 +138,10 @@ export class NetworkError extends Error {
     options?: ErrorOptions & {
       url?: string;
       operation?: "action" | "navigation" | "revalidation";
-    }
+    },
   ) {
     super(message);
+    Object.setPrototypeOf(this, NetworkError.prototype);
     this.cause = options?.cause;
     this.url = options?.url;
     this.operation = options?.operation;
@@ -171,6 +177,100 @@ export function isNetworkError(error: unknown): boolean {
   return false;
 }
 
+/**
+ * Structured error for JSON response routes.
+ * Thrown by handlers to return a typed error envelope with a specific HTTP status.
+ *
+ * Unlike standard Error, RouterError messages are always exposed to the client
+ * (the developer intentionally crafted them for consumers).
+ *
+ * @example
+ * ```typescript
+ * path("/products/:id", (ctx) => {
+ *   const product = products.find(p => p.id === ctx.params.id);
+ *   if (!product) throw new RouterError("NOT_FOUND", "Product not found", { status: 404 });
+ *   return product;
+ * }, { name: "productDetail" })
+ * ```
+ */
+export class RouterError extends Error {
+  name = "RouterError" as const;
+  code: string;
+  type?: string;
+  status: number;
+  cause?: unknown;
+
+  constructor(
+    code: string,
+    message: string,
+    options?: {
+      status?: number;
+      type?: string;
+      cause?: unknown;
+    },
+  ) {
+    super(message);
+    Object.setPrototypeOf(this, RouterError.prototype);
+    this.code = code;
+    this.status = options?.status ?? 500;
+    this.type = options?.type;
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Thrown inside a Prerender or Static handler at build time to signal
+ * "skip this entry, log it, and continue with the rest."
+ *
+ * When thrown, the entry is excluded from the pre-render manifest
+ * but the build continues normally. Regular throws (non-Skip)
+ * stop all further pre-rendering and fail the build.
+ *
+ * @example
+ * ```typescript
+ * export const BlogPost = Prerender(
+ *   async () => allPosts.map(p => ({ slug: p.slug })),
+ *   async (ctx) => {
+ *     const post = await getPost(ctx.params.slug);
+ *     if (post.draft) throw new Skip(`"${ctx.params.slug}" is a draft`);
+ *     return <PostPage post={post} />;
+ *   },
+ * );
+ * ```
+ */
+export class Skip extends Error {
+  name = "Skip" as const;
+  cause?: unknown;
+
+  constructor(message: string = "Entry skipped", options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, Skip.prototype);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Type guard to check if a thrown value is a Skip signal.
+ */
+export function isSkip(value: unknown): value is Skip {
+  return value instanceof Skip;
+}
+
+/**
+ * Thrown by the partial updater when the server responds with a redirect payload
+ * that carries location state. Caught by navigate() to re-navigate to the
+ * redirect target with the server-set state merged into history.pushState.
+ *
+ * Not an Error subclass -- this is a control flow signal, not a failure.
+ */
+export class ServerRedirect {
+  readonly name = "ServerRedirect";
+  constructor(
+    public readonly url: string,
+    public readonly state: Record<string, unknown> | undefined,
+  ) {}
+}
+
 /**
  * Thrown when route handler returns invalid type
  */
@@ -180,6 +280,7 @@ export class InvalidHandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, InvalidHandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -226,7 +327,12 @@ export function sanitizeError(error: unknown): Response {
     return error;
   }
 
-  const isDev = (import.meta as any).env?.DEV ?? true;
+  // Vite replaces import.meta.env.DEV at compile time. The fallback covers
+  // non-Vite environments (plain Node, test runners without Vite transforms).
+  // SECURITY: fail closed — default to production when the environment is ambiguous.
+  const isDev =
+    (import.meta as any).env?.DEV ??
+    globalThis.process?.env?.NODE_ENV === "development";
 
   if (isDev) {
     // Development: Send full error details for debugging

package/src/handle.ts

@@ -29,16 +29,6 @@ export interface Handle<TData, TAccumulated = TData[]> {
    * 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;
 }
 
 /**
@@ -48,10 +38,25 @@ function defaultCollect<T>(segments: T[][]): T[] {
   return segments.flat();
 }
 
+// Module-level registry mapping $$id to collect functions.
+// Populated when createHandle() runs (both server and client).
+// Used by useHandle() to recover collect when handle is deserialized from RSC prop.
+const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
+
+/**
+ * Look up a collect function from the registry by handle $$id.
+ * Returns undefined if not registered (falls back to defaultCollect in useHandle).
+ */
+export function getCollectFn(
+  id: string,
+): ((segments: unknown[][]) => unknown) | undefined {
+  return collectRegistry.get(id);
+}
+
 /**
  * Create a handle definition for accumulating data across route segments.
  *
- * The $$id is auto-generated by the Vite exposeHandleId plugin based on
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
  * file path and export name. No manual naming required.
  *
  * @param collect - Optional collect function (default: flatten into array)
@@ -86,24 +91,34 @@ function defaultCollect<T>(segments: T[][]): T[] {
  */
 export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
-  __injectedId?: string
+  __injectedId?: string,
 ): Handle<TData, TAccumulated> {
   const handleId = __injectedId ?? "";
 
-  if (!handleId && process.env.NODE_ENV !== "production") {
-    console.warn(
+  if (!handleId && process.env.NODE_ENV === "development") {
+    throw new Error(
       "[rsc-router] Handle is missing $$id. " +
-        "Make sure the exposeHandleId Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)"
+        "Make sure the exposeInternalIds Vite plugin is enabled and " +
+        "the handle is exported with: export const MyHandle = createHandle(...)",
+    );
+  }
+
+  const collectFn =
+    collect ??
+    (defaultCollect as unknown as (segments: TData[][]) => TAccumulated);
+
+  // Register collect in module-level registry so useHandle() can recover it
+  // when the handle is deserialized from RSC props (toJSON strips collect).
+  if (handleId) {
+    collectRegistry.set(
+      handleId,
+      collectFn as (segments: unknown[][]) => unknown,
     );
   }
 
   return {
     __brand: "handle" as const,
     $$id: handleId,
-    collect:
-      collect ??
-      (defaultCollect as unknown as (segments: TData[][]) => TAccumulated),
   };
 }
 
@@ -118,3 +133,43 @@ export function isHandle(value: unknown): value is Handle<unknown, unknown> {
     (value as { __brand: unknown }).__brand === "handle"
   );
 }
+
+/**
+ * Collect handle data from a HandleData map, applying the handle's collect
+ * function over segments in order. Shared between server-side rendered()
+ * reads and client-side useHandle().
+ *
+ * @param handle - The handle to collect data for
+ * @param data - Full handle data map (handleName -> segmentId -> entries[])
+ * @param segmentOrder - Segment IDs in parent -> child resolution order
+ */
+export function collectHandleData<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  data: Record<string, Record<string, unknown[]>>,
+  segmentOrder: string[],
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id);
+  if (!collectFn && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[rsc-router] Handle "${handle.$$id}" has no registered collect function. ` +
+        `Falling back to flat array. Ensure the handle module is imported so ` +
+        `createHandle() runs and registers the collect function.`,
+    );
+  }
+  const collect = (collectFn ??
+    (defaultCollect as unknown as (segments: unknown[][]) => unknown)) as (
+    segments: TData[][],
+  ) => TAccumulated;
+
+  const segmentData = data[handle.$$id];
+  if (!segmentData) return collect([]);
+
+  const segmentArrays: TData[][] = [];
+  for (const segmentId of segmentOrder) {
+    const entries = segmentData[segmentId];
+    if (entries && entries.length > 0) {
+      segmentArrays.push(entries as TData[]);
+    }
+  }
+  return collect(segmentArrays);
+}