@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/build/index.ts

@@ -17,15 +17,12 @@
 
 export {
   generateManifest,
+  generateManifestFull,
   generateManifestCode,
   type GeneratedManifest,
 } from "./generate-manifest.js";
 
-export {
-  buildRouteTrie,
-  type TrieNode,
-  type TrieLeaf,
-} from "./route-trie.js";
+export { buildRouteTrie, type TrieNode, type TrieLeaf } from "./route-trie.js";
 
 export {
   writePerModuleRouteTypes,
@@ -34,3 +31,5 @@ export {
   createScanFilter,
   type ScanFilter,
 } from "./generate-route-types.js";
+
+export { hashParams } from "../prerender/param-hash.js";

package/src/build/route-trie.ts

@@ -6,7 +6,10 @@
  * shortCodes for layout pruning.
  */
 
-import { parsePattern, type ParsedSegment } from "../router/pattern-matching.js";
+import {
+  parsePattern,
+  type ParsedSegment,
+} from "../router/pattern-matching.js";
 
 // -- Trie data structures (compact keys for JSON serialization) --
 
@@ -17,10 +20,13 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names (absent params get empty string value) */
+  /** Optional param names declared on the route. Absent params are
+   * omitted from the matched params record (read as `undefined`). */
   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 */
@@ -42,6 +48,8 @@ export interface TrieNode {
   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 };
 }
@@ -91,42 +99,46 @@ export function buildRouteTrie(
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` — the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
  */
 function insertRoute(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: Omit<TrieLeaf, "op" | "cv">,
+  leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
 ): void {
-  // Collect optional param names and constraints across all segments
+  // op (full optional list) and cv (full constraint map) are route-level and
+  // identical on every terminal, so compute them once on the shared base.
   const optionalParams: string[] = [];
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
-    if (seg.type === "param" && seg.optional) {
-      optionalParams.push(seg.value);
-    }
-    if (seg.type === "param" && seg.constraint) {
-      constraints[seg.value] = seg.constraint;
+    if (seg.type === "param") {
+      if (seg.optional) {
+        optionalParams.push(seg.value);
+      }
+      if (seg.constraint) {
+        constraints[seg.value] = seg.constraint;
+      }
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
     ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 
-  insertSegments(node, segments, index, fullLeaf);
+  insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * 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.
@@ -148,6 +160,11 @@ export function extractAncestryFromTrie(
         visit(child);
       }
     }
+    if (node.xp) {
+      for (const child of Object.values(node.xp)) {
+        visit(child.c);
+      }
+    }
     if (node.p) {
       visit(node.p.c);
     }
@@ -188,8 +205,8 @@ function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
     // 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 = [];
-    leaf.nv.push({ routeKey: existing.n, responseType: existing.rt });
     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;
   }
@@ -201,15 +218,25 @@ function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
   node.r = mergeLeaves(node.r, leaf);
 }
 
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
 function insertSegments(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: TrieLeaf,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
 ): void {
-  // Base case: all segments consumed, add terminal
+  // Base case: all segments consumed, add terminal with branch-local pa
   if (index >= segments.length) {
-    mergeLeaf(node, leaf);
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
     return;
   }
 
@@ -218,21 +245,47 @@ function insertSegments(
   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);
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
   } 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)
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
     }
-    if (!node.p) {
-      node.p = { n: segment.value, c: {} };
+    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, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
-    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;
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    const wildLeaf: TrieLeaf & { pn: string } = {
+      ...buildLeaf(leafBase, paramNames),
+      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> {}
+  }
+}
+`;
+}