@rangojs/router 0.0.0-experimental.0f44aca1

package/src/build/route-trie.ts

@@ -0,0 +1,265 @@
+/**
+ * Build-time Route Trie Construction
+ *
+ * Builds a serializable trie from the route manifest for O(path_length)
+ * route matching at runtime. Each trie leaf embeds the route's ancestry
+ * shortCodes for layout pruning.
+ */
+
+import {
+  parsePattern,
+  type ParsedSegment,
+} from "../router/pattern-matching.js";
+
+// -- Trie data structures (compact keys for JSON serialization) --
+
+export interface TrieLeaf {
+  /** Route name (e.g., "site.l1_500") */
+  n: string;
+  /** Static prefix of the entry (e.g., "/site") */
+  sp: string;
+  /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
+  a: string[];
+  /** Optional param names (absent params get empty string value) */
+  op?: string[];
+  /** Constraint validation: paramName -> allowed values */
+  cv?: Record<string, string[]>;
+  /** Ordered param names for this route (positional) */
+  pa?: string[];
+  /** Trailing slash mode */
+  ts?: string;
+  /** Route has pre-rendered data available */
+  pr?: true;
+  /** Passthrough: handler kept in bundle for live fallback on unknown params */
+  pt?: true;
+  /** Response type for non-RSC routes (json, text, image, any) */
+  rt?: string;
+  /** Negotiate variants: response-type routes sharing this path */
+  nv?: Array<{ routeKey: string; responseType: string }>;
+  /** RSC-first: RSC route was defined before response-type variants */
+  rf?: true;
+}
+
+export interface TrieNode {
+  /** Route terminal at this node */
+  r?: TrieLeaf;
+  /** Static segment children */
+  s?: Record<string, TrieNode>;
+  /** Param child: { n: paramName, c: child node } */
+  p?: { n: string; c: TrieNode };
+  /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
+  xp?: Record<string, { n: string; c: TrieNode }>;
+  /** Wildcard terminal: leaf + paramName */
+  w?: TrieLeaf & { pn: string };
+}
+
+/**
+ * Build a route trie from build-time manifest data.
+ *
+ * @param routeManifest - Map of route name to full URL pattern
+ * @param routeAncestry - Map of route name to ancestry shortCodes
+ * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
+ * @param routeTrailingSlash - Optional map of route name to trailing slash mode
+ */
+export function buildRouteTrie(
+  routeManifest: Record<string, string>,
+  routeAncestry: Record<string, string[]>,
+  routeToStaticPrefix: Record<string, string>,
+  routeTrailingSlash?: Record<string, string>,
+  prerenderRouteNames?: Set<string>,
+  passthroughRouteNames?: Set<string>,
+  responseTypeRoutes?: Record<string, string>,
+): TrieNode {
+  const root: TrieNode = {};
+
+  for (const [routeName, pattern] of Object.entries(routeManifest)) {
+    const ancestry = routeAncestry[routeName] || [];
+    const staticPrefix = routeToStaticPrefix[routeName] || "";
+    const trailingSlash = routeTrailingSlash?.[routeName];
+    const responseType = responseTypeRoutes?.[routeName];
+
+    // Detect and strip trailing slash from pattern for parsing
+    const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    const normalizedPattern = hasTrailingSlash ? pattern.slice(0, -1) : pattern;
+
+    const segments = parsePattern(normalizedPattern);
+    insertRoute(root, segments, 0, {
+      n: routeName,
+      sp: staticPrefix,
+      a: ancestry,
+      ...(trailingSlash ? { ts: trailingSlash } : {}),
+      ...(prerenderRouteNames?.has(routeName) ? { pr: true } : {}),
+      ...(passthroughRouteNames?.has(routeName) ? { pt: true } : {}),
+      ...(responseType ? { rt: responseType } : {}),
+    });
+  }
+
+  return root;
+}
+
+/**
+ * Insert a route into the trie, handling optional params by forking
+ * the insertion path (one terminal without the param, one with).
+ */
+function insertRoute(
+  node: TrieNode,
+  segments: ParsedSegment[],
+  index: number,
+  leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
+): void {
+  // Collect param names, optional param names, and constraints across all segments
+  const paramNames: string[] = [];
+  const optionalParams: string[] = [];
+  const constraints: Record<string, string[]> = {};
+
+  for (const seg of segments) {
+    if (seg.type === "param") {
+      paramNames.push(seg.value);
+      if (seg.optional) {
+        optionalParams.push(seg.value);
+      }
+      if (seg.constraint) {
+        constraints[seg.value] = seg.constraint;
+      }
+    }
+  }
+
+  const fullLeaf: TrieLeaf = {
+    ...leaf,
+    ...(paramNames.length > 0 ? { pa: paramNames } : {}),
+    ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
+    ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
+  };
+
+  insertSegments(node, segments, index, fullLeaf);
+}
+
+/**
+ * Recursively insert segments into the trie.
+ * For optional params, we add a terminal at the current node (param absent)
+ * AND continue inserting into the param child (param present).
+ */
+/**
+ * Extract ancestry map from a built trie by visiting all leaf nodes.
+ * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
+ */
+export function extractAncestryFromTrie(
+  root: TrieNode,
+): Record<string, string[]> {
+  const result: Record<string, string[]> = {};
+
+  function visit(node: TrieNode): void {
+    if (node.r) {
+      result[node.r.n] = node.r.a;
+    }
+    if (node.w) {
+      result[node.w.n] = node.w.a;
+    }
+    if (node.s) {
+      for (const child of Object.values(node.s)) {
+        visit(child);
+      }
+    }
+    if (node.xp) {
+      for (const child of Object.values(node.xp)) {
+        visit(child.c);
+      }
+    }
+    if (node.p) {
+      visit(node.p.c);
+    }
+  }
+
+  visit(root);
+  return result;
+}
+
+/**
+ * Merge a new leaf with an existing leaf, handling content negotiation.
+ * When an RSC route and response-type routes share the same URL pattern,
+ * the RSC route becomes the primary leaf and response-type routes are
+ * appended to the nv (negotiate variants) array.
+ * Multiple response types on the same path are supported (json + text + xml).
+ */
+function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
+  if (!existing) return leaf;
+
+  if (existing.rt && leaf.rt) {
+    // Both are response-type: preserve old as variant
+    const merged = leaf;
+    merged.nv = existing.nv || [];
+    merged.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    return merged;
+  }
+  if (leaf.rt && !existing.rt) {
+    // RSC primary exists, new leaf is response-type: append variant
+    // RSC was defined first (it was already the existing leaf)
+    if (!existing.nv) {
+      existing.nv = [];
+      existing.rf = true;
+    }
+    existing.nv.push({ routeKey: leaf.n, responseType: leaf.rt });
+    return existing;
+  }
+  if (!leaf.rt && existing.rt) {
+    // Response-type was primary, new leaf is RSC: swap and move old to variants
+    // RSC was defined second (response-type was already the existing leaf)
+    if (!leaf.nv) leaf.nv = [];
+    if (existing.nv) leaf.nv.push(...existing.nv);
+    leaf.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    // rf intentionally not set — RSC came after response-type variants
+    return leaf;
+  }
+  // Both RSC (last wins): overwrite
+  return leaf;
+}
+
+function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
+  node.r = mergeLeaves(node.r, leaf);
+}
+
+function insertSegments(
+  node: TrieNode,
+  segments: ParsedSegment[],
+  index: number,
+  leaf: TrieLeaf,
+): void {
+  // Base case: all segments consumed, add terminal
+  if (index >= segments.length) {
+    mergeLeaf(node, leaf);
+    return;
+  }
+
+  const segment = segments[index];
+
+  if (segment.type === "static") {
+    if (!node.s) node.s = {};
+    if (!node.s[segment.value]) node.s[segment.value] = {};
+    insertSegments(node.s[segment.value], segments, index + 1, leaf);
+  } else if (segment.type === "param") {
+    if (segment.optional) {
+      // Optional param: add terminal at current node (param absent)
+      mergeLeaf(node, leaf);
+      // AND continue with param child (param present)
+    }
+    if (segment.suffix) {
+      // Suffix param: keyed by suffix string (e.g., ".html")
+      if (!node.xp) node.xp = {};
+      if (!node.xp[segment.suffix]) {
+        node.xp[segment.suffix] = { n: segment.value, c: {} };
+      }
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leaf);
+    }
+  } else if (segment.type === "wildcard") {
+    // Wildcard consumes all remaining segments
+    const wildLeaf = { ...leaf, pn: "*" };
+    const existing = node.w ? ({ ...node.w } as TrieLeaf) : undefined;
+    const merged = mergeLeaves(existing, wildLeaf);
+    node.w = merged as TrieLeaf & { pn: string };
+  }
+}

package/src/build/route-types/ast-helpers.ts

@@ -0,0 +1,25 @@
+import ts from "typescript";
+
+export function getStringValue(node: ts.Node): string | null {
+  if (ts.isStringLiteral(node)) return node.text;
+  if (ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  return null;
+}
+
+export function extractObjectStringProperties(
+  node: ts.ObjectLiteralExpression,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const prop of node.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const key = ts.isIdentifier(prop.name)
+      ? prop.name.text
+      : ts.isStringLiteral(prop.name)
+        ? prop.name.text
+        : null;
+    if (!key) continue;
+    const val = getStringValue(prop.initializer);
+    if (val !== null) result[key] = val;
+  }
+  return result;
+}

package/src/build/route-types/ast-route-extraction.ts

@@ -0,0 +1,98 @@
+import ts from "typescript";
+import {
+  getStringValue,
+  extractObjectStringProperties,
+} from "./ast-helpers.js";
+import { extractParamsFromPattern } from "./param-extraction.js";
+
+// ---------------------------------------------------------------------------
+// AST-based route extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract route definitions from source code by walking the TypeScript AST.
+ * Finds path() and path.json(), path.md(), etc. call expressions and extracts
+ * the pattern, name, params, and optional search schema from each.
+ * Skips unnamed paths (no { name: "..." }).
+ */
+export function extractRoutesFromSource(code: string): Array<{
+  name: string;
+  pattern: string;
+  params?: Record<string, string>;
+  search?: Record<string, string>;
+}> {
+  const sourceFile = ts.createSourceFile(
+    "input.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  const routes: Array<{
+    name: string;
+    pattern: string;
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+  }> = [];
+
+  function visit(node: ts.Node) {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      const isPath =
+        (ts.isIdentifier(callee) && callee.text === "path") ||
+        (ts.isPropertyAccessExpression(callee) &&
+          ts.isIdentifier(callee.expression) &&
+          callee.expression.text === "path");
+
+      if (isPath && node.arguments.length >= 1) {
+        const route = extractRouteFromCallExpression(node);
+        if (route) routes.push(route);
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return routes;
+}
+
+function extractRouteFromCallExpression(node: ts.CallExpression): {
+  name: string;
+  pattern: string;
+  params?: Record<string, string>;
+  search?: Record<string, string>;
+} | null {
+  const patternNode = node.arguments[0];
+  const pattern = getStringValue(patternNode);
+  if (pattern === null) return null;
+
+  let name: string | null = null;
+  let search: Record<string, string> | undefined;
+
+  for (let i = 1; i < node.arguments.length; i++) {
+    const arg = node.arguments[i];
+    if (ts.isObjectLiteralExpression(arg)) {
+      for (const prop of arg.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const propName = ts.isIdentifier(prop.name) ? prop.name.text : null;
+        if (propName === "name") {
+          name = getStringValue(prop.initializer);
+        } else if (
+          propName === "search" &&
+          ts.isObjectLiteralExpression(prop.initializer)
+        ) {
+          search = extractObjectStringProperties(prop.initializer);
+        }
+      }
+    }
+  }
+
+  if (!name) return null;
+  const params = extractParamsFromPattern(pattern);
+  return {
+    name,
+    pattern,
+    ...(params ? { params } : {}),
+    ...(search && Object.keys(search).length > 0 ? { search } : {}),
+  };
+}

package/src/build/route-types/codegen.ts

@@ -0,0 +1,102 @@
+import {
+  extractParamsFromPattern,
+  formatRouteEntry,
+} from "./param-extraction.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
+
+// ---------------------------------------------------------------------------
+// Code generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a per-module types file from extracted routes.
+ * Output has zero imports, preventing circular references.
+ */
+export function generatePerModuleTypesSource(
+  routes: Array<{
+    name: string;
+    pattern: string;
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+  }>,
+): string {
+  const valid = routes.filter(({ name }) => {
+    if (!name || /["'\\`\n\r]/.test(name)) {
+      console.warn(
+        `[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`,
+      );
+      return false;
+    }
+    return true;
+  });
+
+  // Deduplicate by name (first definition wins -- primary route before variants)
+  const deduped = new Map<
+    string,
+    {
+      pattern: string;
+      params?: Record<string, string>;
+      search?: Record<string, string>;
+    }
+  >();
+  for (const { name, pattern, params, search } of valid) {
+    if (deduped.has(name)) {
+      console.warn(
+        `[rsc-router] Duplicate route name "${name}" — keeping first definition`,
+      );
+      continue;
+    }
+    deduped.set(name, { pattern, params, search });
+  }
+  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const body = sorted
+    .map(([name, { pattern, params, search }]) => {
+      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+      return formatRouteEntry(key, pattern, params, search);
+    })
+    .join("\n");
+  return `// Auto-generated by @rangojs/router - do not edit\nexport const routes = {\n${body}\n} as const;\nexport type routes = typeof routes;\n`;
+}
+
+/**
+ * Generates a .ts file that augments RSCRouter.GeneratedRouteMap
+ * with route name -> pattern mappings. This enables Handler<"routeName">
+ * without circular references since the file has no imports from the app.
+ */
+export function generateRouteTypesSource(
+  routeManifest: Record<string, string>,
+  searchSchemas?: Record<string, Record<string, string>>,
+): string {
+  const entries = Object.entries(routeManifest)
+    .filter(([name]) => !isAutoGeneratedRouteName(name))
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  const filteredSearchSchemas = searchSchemas
+    ? Object.fromEntries(
+        Object.entries(searchSchemas).filter(
+          ([name]) => !isAutoGeneratedRouteName(name),
+        ),
+      )
+    : undefined;
+
+  const objectBody = entries
+    .map(([name, pattern]) => {
+      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+      const params = extractParamsFromPattern(pattern);
+      const search = filteredSearchSchemas?.[name];
+      return formatRouteEntry(key, pattern, params, search);
+    })
+    .join("\n");
+
+  return `// Auto-generated by @rangojs/router - do not edit
+export const NamedRoutes = {
+${objectBody}
+} as const;
+
+declare global {
+  namespace RSCRouter {
+    interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
+  }
+}
+`;
+}