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

package/src/route-types.ts

@@ -5,28 +5,29 @@
  */
 
 /**
- * Branded return types for route helpers
+ * Brand for UrlPatterns nominal typing (see pattern-types.ts). The route-item
+ * types below are discriminated by their `type` literal, so they carry no brand.
  */
-export declare const LayoutBrand: unique symbol;
-export declare const RouteBrand: unique symbol;
-export declare const ParallelBrand: unique symbol;
-export declare const InterceptBrand: unique symbol;
-export declare const MiddlewareBrand: unique symbol;
-export declare const RevalidateBrand: unique symbol;
-export declare const LoaderBrand: unique symbol;
-export declare const LoadingBrand: unique symbol;
-export declare const ErrorBoundaryBrand: unique symbol;
-export declare const NotFoundBoundaryBrand: unique symbol;
-export declare const WhenBrand: unique symbol;
-export declare const CacheBrand: unique symbol;
-export declare const IncludeBrand: unique symbol;
 export declare const UrlPatternsBrand: unique symbol;
 
 export type LayoutItem = {
   name: string;
   type: "layout";
   uses?: AllUseItems[];
-  [LayoutBrand]: void;
+};
+
+/**
+ * Phantom inference fields attached to wrapper items (layout/cache/transition)
+ * so the urls() type extractor can read their child routes/responses. The fields
+ * never exist at runtime.
+ */
+type WithChildren<
+  TBase,
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = TBase & {
+  readonly __childRoutes?: TChildRoutes;
+  readonly __childResponses?: TChildResponses;
 };
 
 /**
@@ -34,15 +35,13 @@ export type LayoutItem = {
  * Used for type inference in urls() API
  */
 export type TypedLayoutItem<
-  TChildRoutes extends Record<string, string> = Record<string, string>
-> = LayoutItem & {
-  readonly __childRoutes?: TChildRoutes;
-};
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = WithChildren<LayoutItem, TChildRoutes, TChildResponses>;
 export type RouteItem = {
   name: string;
   type: "route";
   uses?: AllUseItems[];
-  [RouteBrand]: void;
 };
 
 /**
@@ -51,79 +50,85 @@ export type RouteItem = {
  */
 export type TypedRouteItem<
   TName extends string = string,
-  TPattern extends string = string
+  TPattern extends string = string,
+  TData = unknown,
+  TSearch = {},
 > = RouteItem & {
   readonly __name?: TName;
   readonly __pattern?: TPattern;
+  readonly __data?: TData;
+  readonly __search?: TSearch;
 };
 export type ParallelItem = {
   name: string;
   type: "parallel";
   uses?: ParallelUseItem[];
-  [ParallelBrand]: void;
 };
 export type InterceptItem = {
   name: string;
   type: "intercept";
   uses?: InterceptUseItem[];
-  [InterceptBrand]: void;
 };
 export type LoaderItem = {
   name: string;
   type: "loader";
   uses?: LoaderUseItem[];
-  [LoaderBrand]: void;
 };
 export type MiddlewareItem = {
   name: string;
   type: "middleware";
   uses?: AllUseItems[];
-  [MiddlewareBrand]: void;
 };
 export type RevalidateItem = {
   name: string;
   type: "revalidate";
   uses?: AllUseItems[];
-  [RevalidateBrand]: void;
 };
 export type LoadingItem = {
   name: string;
   type: "loading";
-  [LoadingBrand]: void;
 };
 export type ErrorBoundaryItem = {
   name: string;
   type: "errorBoundary";
   uses?: AllUseItems[];
-  [ErrorBoundaryBrand]: void;
 };
 export type NotFoundBoundaryItem = {
   name: string;
   type: "notFoundBoundary";
   uses?: AllUseItems[];
-  [NotFoundBoundaryBrand]: void;
 };
 export type WhenItem = {
   name: string;
   type: "when";
-  [WhenBrand]: void;
 };
 export type CacheItem = {
   name: string;
   type: "cache";
   uses?: AllUseItems[];
-  [CacheBrand]: void;
 };
+export type TransitionItem = {
+  name: string;
+  type: "transition";
+};
+
+/**
+ * Typed transition item that carries child routes as phantom type
+ * Used for type inference when transition() wraps child routes
+ */
+export type TypedTransitionItem<
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = WithChildren<TransitionItem, TChildRoutes, TChildResponses>;
 
 /**
  * Typed cache item that carries child routes as phantom type
  * Used for type inference in urls() API
  */
 export type TypedCacheItem<
-  TChildRoutes extends Record<string, string> = Record<string, string>
-> = CacheItem & {
-  readonly __childRoutes?: TChildRoutes;
-};
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = WithChildren<CacheItem, TChildRoutes, TChildResponses>;
 
 /**
  * Include item for URL pattern composition (used by urls() API)
@@ -133,8 +138,31 @@ export type IncludeItem = {
   name: string;
   prefix: string;
   patterns: unknown; // UrlPatterns - avoid circular ref
-  options?: { name?: string };
-  [IncludeBrand]: void;
+  options?: { name?: string; lazy?: boolean };
+  /** Whether this include should be lazily evaluated on first request */
+  lazy?: boolean;
+  /** Captured context for deferred lazy evaluation */
+  _lazyContext?: {
+    urlPrefix: string;
+    namePrefix: string | undefined;
+    parent: unknown; // EntryData - avoid circular import
+    /** Counter snapshot from pattern extraction for consistent shortCode indices */
+    counters?: Record<string, number>;
+    /** Cache profiles for DSL-time cache("profileName") resolution */
+    cacheProfiles?: Record<
+      string,
+      import("./cache/profile-registry.js").CacheProfile
+    >;
+    /** Root scope flag for dot-local reverse resolution */
+    rootScoped?: boolean;
+    /**
+     * Positional include scope token composed from the parent scope plus this
+     * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+     * descendant shortCodes during lazy evaluation so routes inside the
+     * include cannot collide with siblings declared outside it.
+     */
+    includeScope?: string;
+  };
 };
 
 /**
@@ -142,11 +170,15 @@ export type IncludeItem = {
  * Used for type inference in urls() API
  */
 export type TypedIncludeItem<
-  TRoutes extends Record<string, string> = Record<string, string>,
-  TNamePrefix extends string = string
+  TRoutes extends Record<string, any> = Record<string, string>,
+  TNamePrefix extends string = string,
+  TUrlPrefix extends string = string,
+  TResponses extends Record<string, unknown> = Record<string, unknown>,
 > = IncludeItem & {
   readonly __routes?: TRoutes;
   readonly __namePrefix?: TNamePrefix;
+  readonly __urlPrefix?: TUrlPrefix;
+  readonly __responses?: TResponses;
 };
 
 /**
@@ -164,6 +196,7 @@ export type AllUseItems =
   | ErrorBoundaryItem
   | NotFoundBoundaryItem
   | CacheItem
+  | TransitionItem
   | IncludeItem;
 
 /** Items that can be used inside a layout callback */
@@ -178,13 +211,17 @@ export type RouteUseItem =
   | LoadingItem
   | ErrorBoundaryItem
   | NotFoundBoundaryItem
-  | CacheItem;
+  | CacheItem
+  | TransitionItem;
+/** Items that can be used inside a response route (path.json(), etc.) */
+export type ResponseRouteUseItem = MiddlewareItem | CacheItem;
 export type ParallelUseItem =
   | RevalidateItem
   | LoaderItem
   | LoadingItem
   | ErrorBoundaryItem
-  | NotFoundBoundaryItem;
+  | NotFoundBoundaryItem
+  | TransitionItem;
 export type InterceptUseItem =
   | MiddlewareItem
   | RevalidateItem
@@ -194,5 +231,25 @@ export type InterceptUseItem =
   | NotFoundBoundaryItem
   | LayoutItem
   | RouteItem
-  | WhenItem;
+  | WhenItem
+  | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
+
+/**
+ * Allow composition factories in use() callbacks.
+ * Factories return T[], which placed inside a use() callback array
+ * creates nested arrays like (T | T[])[]. These are flattened at
+ * runtime via .flat(3).
+ */
+export type UseItems<T> = (T | readonly T[])[];
+
+/**
+ * Union of all items that handler.use() may return.
+ * A handler doesn't know its mount site at definition time, so the type
+ * is intentionally broad — validation happens per-mount-site at runtime.
+ */
+export type HandlerUseItem =
+  | RouteUseItem
+  | LayoutUseItem
+  | ParallelUseItem
+  | InterceptUseItem;

package/src/router/basename.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize a router basename to its canonical form: a single leading slash,
+ * no trailing slash, and `undefined` for an empty or bare-"/" value.
+ *
+ * This is the single source of truth used by both createRouter() (so the RSC
+ * handler stores a canonical basename on the request context) and the testing
+ * primitives (so a consumer can pass the same un-normalized string their
+ * createRouter() accepts and observe the same redirect() prefixing).
+ */
+export function normalizeBasename(basename?: string): string | undefined {
+  if (!basename) return undefined;
+  const trimmed = basename.replace(/^\/+|\/+$/g, "");
+  return trimmed ? "/" + trimmed : undefined;
+}

package/src/router/content-negotiation.ts

@@ -0,0 +1,228 @@
+/**
+ * Content Negotiation Utilities
+ *
+ * Pure functions for HTTP Accept header parsing and response type matching.
+ * Used by previewMatch and classifyRequest for content negotiation between
+ * RSC routes and response routes (JSON, text, image, stream, etc.).
+ */
+
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import { loadManifest } from "./manifest.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { RouteSnapshot } from "./route-snapshot.js";
+
+// Response type -> MIME type used for Accept header matching
+export const RESPONSE_TYPE_MIME: Record<string, string> = {
+  json: "application/json",
+  text: "text/plain",
+  xml: "application/xml",
+  html: "text/html",
+  md: "text/markdown",
+};
+
+// Reverse lookup: MIME type -> response type tag (e.g. "text/html" -> "html")
+export const MIME_RESPONSE_TYPE: Record<string, string> = Object.fromEntries(
+  Object.entries(RESPONSE_TYPE_MIME).map(([tag, mime]) => [mime, tag]),
+);
+
+export type NamedRouteEntry =
+  | string
+  | { path: string; search?: Record<string, string> };
+
+export function flattenNamedRoutes(
+  routeNames?: Record<string, NamedRouteEntry>,
+): Record<string, string> {
+  if (!routeNames) return {};
+  const flattened: Record<string, string> = {};
+  for (const [name, entry] of Object.entries(routeNames)) {
+    flattened[name] = typeof entry === "string" ? entry : entry.path;
+  }
+  return flattened;
+}
+
+export interface AcceptEntry {
+  mime: string;
+  q: number;
+  order: number;
+}
+
+/**
+ * Parse an Accept header into a sorted array of MIME entries.
+ * Respects q-values (default 1.0) and uses client order as tiebreaker
+ * when q-values are equal (matching Express/Hono behavior).
+ */
+export function parseAcceptTypes(accept: string): AcceptEntry[] {
+  const entries: AcceptEntry[] = [];
+  const parts = accept.split(",");
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    const segments = part.split(";");
+    const mime = segments[0]!.trim().toLowerCase();
+    if (!mime) continue;
+    let q = 1.0;
+    for (let j = 1; j < segments.length; j++) {
+      const param = segments[j]!.trim();
+      if (param.startsWith("q=")) {
+        q = Math.max(0, Math.min(1, Number(param.slice(2)) || 0));
+      }
+    }
+    entries.push({ mime, q, order: i });
+  }
+  // Sort: highest q first, then lowest client order first (stable)
+  entries.sort((a, b) => b.q - a.q || a.order - b.order);
+  return entries;
+}
+
+// Sentinel response type for RSC routes in negotiation candidates
+export const RSC_RESPONSE_TYPE = "__rsc__";
+
+/**
+ * Pick the best negotiate variant by walking the client's sorted Accept list.
+ * For each accepted MIME type (in q-value/order priority), check if any
+ * candidate serves that type. Wildcards match the first candidate.
+ * Falls back to the first candidate if nothing matches.
+ */
+export function pickNegotiateVariant(
+  acceptEntries: AcceptEntry[],
+  candidates: Array<{ routeKey: string; responseType: string }>,
+): { routeKey: string; responseType: string } {
+  // Build a MIME -> candidate lookup for O(1) matching
+  const byCandidateMime = new Map<
+    string,
+    { routeKey: string; responseType: string }
+  >();
+  for (const c of candidates) {
+    const mime =
+      c.responseType === RSC_RESPONSE_TYPE
+        ? "text/html"
+        : RESPONSE_TYPE_MIME[c.responseType];
+    if (mime && !byCandidateMime.has(mime)) {
+      byCandidateMime.set(mime, c);
+    }
+  }
+
+  for (const entry of acceptEntries) {
+    if (entry.q === 0) continue;
+    // Wildcard matches first candidate
+    if (entry.mime === "*/*") return candidates[0]!;
+    // Type wildcard (e.g. "text/*") -- match first candidate with that type
+    if (entry.mime.endsWith("/*")) {
+      const typePrefix = entry.mime.slice(0, entry.mime.indexOf("/"));
+      for (const [mime, candidate] of byCandidateMime) {
+        if (mime.startsWith(typePrefix + "/")) return candidate;
+      }
+      continue;
+    }
+    const match = byCandidateMime.get(entry.mime);
+    if (match) return match;
+  }
+  // No match -- use first candidate as default
+  return candidates[0]!;
+}
+
+/**
+ * Result of content negotiation for a route with negotiate variants.
+ */
+export interface NegotiationResult {
+  /** The winning response type */
+  responseType: string;
+  /** Handler function for the winning variant */
+  handler: Function;
+  /** Manifest entry for the winning variant (may differ from primary) */
+  manifestEntry: EntryData;
+  /** Route middleware for the winning variant */
+  routeMiddleware: CollectedMiddleware[];
+  /** True when negotiation selected a variant; false for a plain response route. */
+  negotiated: boolean;
+}
+
+/**
+ * Perform content negotiation for a route with negotiate variants.
+ *
+ * Returns a NegotiationResult when a response route wins negotiation.
+ * Returns null when RSC wins or no negotiation is needed.
+ *
+ * Shared by previewMatch and classifyRequest to avoid duplicating
+ * the candidate-building and variant-loading logic.
+ */
+export async function negotiateRoute(
+  request: Request,
+  pathname: string,
+  snapshot: RouteSnapshot,
+): Promise<NegotiationResult | null> {
+  const { matched, manifestEntry, routeMiddleware, responseType } = snapshot;
+  if (!matched.negotiateVariants || matched.negotiateVariants.length === 0) {
+    // No variants: a plain response route still yields a result (negotiated:false)
+    // so callers don't re-derive it; RSC routes (no responseType/handler) -> null.
+    const handler =
+      manifestEntry.type === "route" ? manifestEntry.handler : undefined;
+    if (responseType && handler) {
+      return {
+        responseType,
+        handler: handler as Function,
+        manifestEntry,
+        routeMiddleware,
+        negotiated: false,
+      };
+    }
+    return null;
+  }
+
+  const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
+
+  // Build candidate list preserving definition order.
+  const variants = matched.negotiateVariants;
+  let candidates: Array<{ routeKey: string; responseType: string }>;
+  if (responseType) {
+    candidates = [...variants, { routeKey: matched.routeKey, responseType }];
+  } else {
+    const rscCandidate = {
+      routeKey: matched.routeKey,
+      responseType: RSC_RESPONSE_TYPE,
+    };
+    candidates = matched.rscFirst
+      ? [rscCandidate, ...variants]
+      : [...variants, rscCandidate];
+  }
+
+  const variant = pickNegotiateVariant(acceptEntries, candidates);
+
+  // RSC won negotiation
+  if (variant.responseType === RSC_RESPONSE_TYPE) {
+    return null;
+  }
+
+  // Primary response-type won — use existing manifest entry and middleware
+  if (responseType && variant.routeKey === matched.routeKey) {
+    return {
+      responseType,
+      handler: manifestEntry.handler as Function,
+      manifestEntry,
+      routeMiddleware,
+      negotiated: true,
+    };
+  }
+
+  // Different variant won — load its manifest entry
+  const negotiateEntry = await loadManifest(
+    matched.entry,
+    variant.routeKey,
+    pathname,
+    undefined,
+    false,
+  );
+  const variantMiddleware = collectRouteMiddleware(
+    traverseBack(negotiateEntry),
+    matched.params,
+  );
+  return {
+    responseType: variant.responseType,
+    handler: negotiateEntry.handler as Function,
+    manifestEntry: negotiateEntry,
+    routeMiddleware: variantMiddleware,
+    negotiated: true,
+  };
+}

package/src/router/debug-manifest.ts

@@ -0,0 +1,72 @@
+import { type EntryData, getContext } from "../server/context";
+import { serializeManifest, type SerializedManifest } from "../debug.js";
+import { createRouteHelpers } from "../route-definition.js";
+import MapRootLayout from "../server/root-layout.js";
+import type { RouteEntry, TrailingSlashMode } from "../types";
+
+/**
+ * Build a serialized manifest from all route entries for debug inspection.
+ * Used by the `debugManifest()` method on the router instance.
+ */
+export async function buildDebugManifest<TEnv = any>(
+  routesEntries: RouteEntry<TEnv>[],
+): Promise<SerializedManifest> {
+  const manifest = new Map<string, EntryData>();
+
+  for (const entry of routesEntries) {
+    const Store = {
+      manifest,
+      namespace: `debug.M${entry.mountIndex}`,
+      parent: null as EntryData | null,
+      counters: {} as Record<string, number>,
+      mountIndex: entry.mountIndex,
+      patterns: new Map<string, string>(),
+      trailingSlash: new Map<string, TrailingSlashMode>(),
+    };
+
+    await getContext().runWithStore(
+      Store,
+      `debug.M${entry.mountIndex}`,
+      null,
+      async () => {
+        const helpers = createRouteHelpers();
+
+        // Wrap handler execution in root layout (same as loadManifest)
+        let promiseResult: Promise<any> | null = null;
+        helpers.layout(MapRootLayout, () => {
+          const result = entry.handler();
+          if (result instanceof Promise) {
+            promiseResult = result;
+            return [];
+          }
+          return result;
+        });
+
+        if (promiseResult !== null) {
+          const load = await (promiseResult as Promise<any>);
+          if (load && typeof load === "object" && "default" in load) {
+            // Promise<{ default: fn }> — e.g. dynamic import
+            if (typeof load.default !== "function") {
+              throw new Error(
+                `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
+                  `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
+              );
+            }
+            load.default(helpers);
+          } else if (typeof load === "function") {
+            // Promise<fn>
+            load(helpers);
+          } else {
+            // Reject unsupported async handler results (same policy as manifest.ts)
+            throw new Error(
+              `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+                `Lazy route handlers must resolve to a function or { default: fn }.`,
+            );
+          }
+        }
+      },
+    );
+  }
+
+  return serializeManifest(manifest);
+}

package/src/router/error-handling.ts

@@ -1,7 +1,7 @@
 /**
  * Router Error Handling Utilities
  *
- * Error boundary and not-found boundary handling for RSC Router.
+ * Error boundary and not-found boundary handling for Rango.
  * Also includes the shared invokeOnError utility for error callback invocation.
  */
 
@@ -60,7 +60,7 @@ export function invokeOnError<TEnv = any>(
   error: unknown,
   phase: ErrorPhase,
   context: InvokeOnErrorContext<TEnv>,
-  logPrefix: string = "Router"
+  logPrefix: string = "Router",
 ): void {
   if (!onError) return;
 
@@ -74,8 +74,8 @@ export function invokeOnError<TEnv = any>(
     phase,
     request: context.request,
     url: context.url,
-    pathname: context.url.pathname,
-    method: context.request.method,
+    pathname: context.url?.pathname,
+    method: context.request?.method,
     routeKey: context.routeKey,
     params: context.params,
     segmentId: context.segmentId,
@@ -112,7 +112,7 @@ export function invokeOnError<TEnv = any>(
  */
 export function findNearestErrorBoundary(
   entry: EntryData | null,
-  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler
+  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler,
 ): ReactNode | ErrorBoundaryHandler | null {
   let current: EntryData | null = entry;
 
@@ -148,7 +148,7 @@ export function findNearestErrorBoundary(
  */
 export function findNearestNotFoundBoundary(
   entry: EntryData | null,
-  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler
+  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler,
 ): ReactNode | NotFoundBoundaryHandler | null {
   let current: EntryData | null = entry;
 
@@ -172,7 +172,7 @@ export function findNearestNotFoundBoundary(
 export function createErrorInfo(
   error: unknown,
   segmentId: string,
-  segmentType: ErrorInfo["segmentType"]
+  segmentType: ErrorInfo["segmentType"],
 ): ErrorInfo {
   const isDev = process.env.NODE_ENV !== "production";
 
@@ -205,7 +205,7 @@ export function createErrorSegment(
   errorInfo: ErrorInfo,
   fallback: ReactNode | ErrorBoundaryHandler,
   entry: EntryData,
-  params: Record<string, string>
+  params: Record<string, string>,
 ): ResolvedSegment {
   // Determine the component to render
   let component: ReactNode;
@@ -241,7 +241,7 @@ export function createNotFoundInfo(
   error: { message: string },
   segmentId: string,
   segmentType: NotFoundInfo["segmentType"],
-  pathname?: string
+  pathname?: string,
 ): NotFoundInfo {
   return {
     message: error.message,
@@ -259,7 +259,7 @@ export function createNotFoundSegment(
   notFoundInfo: NotFoundInfo,
   fallback: ReactNode | NotFoundBoundaryHandler,
   entry: EntryData,
-  params: Record<string, string>
+  params: Record<string, string>,
 ): ResolvedSegment {
   // Determine the component to render
   let component: ReactNode;