@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

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 — ctx.get(User) throws inside a cache() boundary
+ * 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, ctx.get(var) throws inside a cache() boundary. */
+  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.
+   * Reading this var with ctx.get() inside a cache() boundary throws. 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/decode-loader-results.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import { isLoaderDataResult } from "./types.js";
+
+// Shared by segment-system (server) and LoaderResolver (client) so the
+// legacy/ok/error-fallback/throw decode of resolved loader values lives once.
+// Last failing loader wins errorFallback; an error without a fallback throws.
+export function decodeLoaderResults(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+
+    if (!isLoaderDataResult(result)) {
+      loaderData[id] = result;
+      continue;
+    }
+
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+
+    if (result.fallback) {
+      errorFallback = result.fallback;
+    } else {
+      throw new Error(result.error.message);
+    }
+  }
+
+  return { loaderData, errorFallback };
+}

package/src/errors.ts

@@ -1,5 +1,5 @@
 /**
- * Custom error classes for RSC Router
+ * Custom error classes for Rango
  *
  * All errors include:
  * - Descriptive names for easy identification
@@ -22,10 +22,22 @@ export class RouteNotFoundError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, RouteNotFoundError.prototype);
     this.cause = options?.cause;
   }
 }
 
+// name fallback covers cross-realm errors (Vite dev dupes, RSC serialization)
+// where instanceof fails.
+export function isRouteNotFoundError(
+  error: unknown,
+): error is RouteNotFoundError {
+  return (
+    error instanceof RouteNotFoundError ||
+    (error instanceof Error && error.name === "RouteNotFoundError")
+  );
+}
+
 /**
  * Thrown when data is not found (e.g., product with ID doesn't exist)
  * Use this in handlers/loaders to trigger the nearest notFoundBoundary
@@ -45,6 +57,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 +87,7 @@ export class MiddlewareError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, MiddlewareError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -87,6 +101,7 @@ export class HandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, HandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -100,6 +115,25 @@ export class BuildError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, BuildError.prototype);
+    this.cause = options?.cause;
+  }
+}
+
+/**
+ * Thrown when a route-definition DSL helper (route/layout/loader/cache/…) is
+ * called outside an active urls()/map() builder, so there is no
+ * AsyncLocalStorage build context to attach to. The message names the specific
+ * helper and how to fix it; the `cause` records the mechanical reason so the
+ * failure mode is identifiable (not conflated with an unrelated throw).
+ */
+export class DslContextError extends Error {
+  name = "DslContextError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, DslContextError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -133,9 +167,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 +206,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 +309,7 @@ export class InvalidHandlerError extends Error {
 
   constructor(message: string, options?: ErrorOptions) {
     super(message);
+    Object.setPrototypeOf(this, InvalidHandlerError.prototype);
     this.cause = options?.cause;
   }
 }
@@ -226,7 +356,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