@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80

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

@@ -2,7 +2,7 @@
  * Debug utilities for manifest inspection and comparison
  */
 
-import type { EntryData } from "./server/context";
+import { getParallelSlotCount, type EntryData } from "./server/context";
 
 /**
  * Serialized entry for debug output
@@ -34,7 +34,7 @@ export interface SerializedManifest {
  * Serialize a manifest Map into a JSON-friendly structure
  */
 export function serializeManifest(
-  manifest: Map<string, EntryData>
+  manifest: Map<string, EntryData>,
 ): SerializedManifest {
   const routes: Record<string, SerializedEntry> = {};
   const layouts: Record<string, SerializedEntry> = {};
@@ -64,7 +64,7 @@ export function serializeManifest(
       hasLoader: entry.loader?.length > 0,
       hasMiddleware: entry.middleware?.length > 0,
       hasErrorBoundary: entry.errorBoundary?.length > 0,
-      parallelCount: entry.parallel?.length ?? 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
       interceptCount: entry.intercept?.length ?? 0,
     };
 
@@ -92,7 +92,7 @@ export function serializeManifest(
  */
 export function compareManifests(
   oldManifest: SerializedManifest,
-  newManifest: SerializedManifest
+  newManifest: SerializedManifest,
 ): {
   addedRoutes: string[];
   removedRoutes: string[];
@@ -113,10 +113,20 @@ export function compareManifests(
 } {
   const addedRoutes: string[] = [];
   const removedRoutes: string[] = [];
-  const changedRoutes: Array<{ key: string; field: string; old: any; new: any }> = [];
+  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 }> = [];
+  const changedLayouts: Array<{
+    key: string;
+    field: string;
+    old: any;
+    new: any;
+  }> = [];
 
   // Compare routes
   const oldRouteKeys = new Set(Object.keys(oldManifest.routes));
@@ -191,7 +201,7 @@ export function compareManifests(
  * Format manifest diff as a human-readable string
  */
 export function formatManifestDiff(
-  diff: ReturnType<typeof compareManifests>
+  diff: ReturnType<typeof compareManifests>,
 ): string {
   const lines: string[] = [];
 
@@ -208,7 +218,7 @@ export function formatManifestDiff(
   if (diff.changedRoutes.length > 0) {
     lines.push("Changed routes:");
     diff.changedRoutes.forEach((c) =>
-      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
     );
   }
 
@@ -225,7 +235,7 @@ export function formatManifestDiff(
   if (diff.changedLayouts.length > 0) {
     lines.push("Changed layouts:");
     diff.changedLayouts.forEach((c) =>
-      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`)
+      lines.push(`  ~ ${c.key}.${c.field}: ${c.old} -> ${c.new}`),
     );
   }
 

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,24 +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.
-   * Optional because RSC serialization (toJSON) strips it. On the client,
-   * useHandle() recovers collect from the module-level registry.
-   *
-   * @param segments - Array of segment data arrays, e.g. [[a, b], [c], [d, e]]
-   * @returns The accumulated value
-   */
-  readonly collect?: (segments: TData[][]) => TAccumulated;
-
-  /**
-   * RSC serialization - strips collect function, keeps only brand + id.
-   * When passed as a prop to a client component, RSC Flight calls toJSON.
-   */
-  toJSON?: () => { __brand: "handle"; $$id: string };
 }
 
 /**
@@ -65,14 +47,16 @@ 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 {
+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)
@@ -107,32 +91,34 @@ export function getCollectFn(id: string): ((segments: unknown[][]) => unknown) |
  */
 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 ??
+  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);
+    collectRegistry.set(
+      handleId,
+      collectFn as (segments: unknown[][]) => unknown,
+    );
   }
 
   return {
     __brand: "handle" as const,
     $$id: handleId,
-    collect: collectFn,
-    toJSON: () => ({ __brand: "handle" as const, $$id: handleId }),
   };
 }
 
@@ -147,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);
+}