@rangojs/router 0.5.1 → 0.6.0

package/src/build/route-trie.ts

@@ -1,153 +1,19 @@
 /**
  * Build-time Route Trie Construction
  *
- * Builds a serializable trie from the route manifest for O(path_length)
- * route matching at runtime.
+ * Adapts generated manifests to the runtime-owned route trie builder.
  */
 
-import {
-  parsePattern,
-  type ParsedSegment,
-} from "../router/pattern-matching.js";
-import { buildRouteToStaticPrefix } from "./prefix-tree-utils.js";
+import { buildRouteTrie, type TrieNode } from "../router/route-trie-builder.js";
 import type { FullManifest } from "./generate-manifest.js";
+import { buildRouteToStaticPrefix } from "./prefix-tree-utils.js";
 
-// -- Trie data structures (compact keys for JSON serialization) --
-
-/**
- * A response-type variant folded into a primary leaf's negotiate list. `pa` is
- * the variant's own positional param-name array, carried so the runtime can
- * re-key the matched params under the variant's names when it wins negotiation
- * (the trie match extracts params under the PRIMARY leaf's pa). Omitted when the
- * variant has no params; absent/identical pa means no re-key is needed.
- */
-export interface NegotiateVariant {
-  routeKey: string;
-  responseType: string;
-  pa?: string[];
-}
-
-export interface TrieLeaf {
-  /** Route name (e.g., "site.l1_500") */
-  n: string;
-  /** Static prefix of the entry (e.g., "/site") */
-  sp: 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?: NegotiateVariant[];
-  /** 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 (`pn`). `pn` is "*" for the bare `/*`
-   * form and the param name for a named catch-all (`:name+`/`:name*`). `w1`
-   * marks a one-or-more catch-all (`:name+`): the runtime walker then rejects
-   * the zero-segment/empty-remainder case. Absent `w1` is zero-or-more.
-   */
-  w?: TrieLeaf & { pn: string; w1?: true };
-}
-
-/**
- * Build a route trie from build-time manifest data.
- *
- * @param routeManifest - Map of route name to full URL pattern
- * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
- * @param routeTrailingSlash - Optional map of route name to trailing slash mode
- * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
- * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
- * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
- */
-export function buildRouteTrie(
-  routeManifest: 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 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,
-      ...(trailingSlash ? { ts: trailingSlash } : {}),
-      ...(prerenderRouteNames?.has(routeName) ? { pr: true } : {}),
-      ...(passthroughRouteNames?.has(routeName) ? { pt: true } : {}),
-      ...(responseType ? { rt: responseType } : {}),
-    });
-  }
-
-  sortSuffixParams(root);
-  return root;
-}
-
-/**
- * Sort every node's suffix-param map (`node.xp`) by descending suffix length so
- * the matcher tries the most specific suffix first. Overlapping suffixes like
- * `.min.js` and `.js` must resolve by specificity, not route declaration order:
- * a request for `/app.min.js` should match `:file.min.js`, not `:file.js`.
- *
- * This started as a bug — `walkTrie` iterates `node.xp` in object order and
- * returns the first suffix the segment ends with, so the winner depended on
- * which route was declared first. Sorting at build time fixes it allocation-free
- * on the match hot path: the serialized production trie preserves this key order
- * through JSON.parse, so dev (per-request rebuild) and production match
- * identically. Array.prototype.sort is stable (ES2019+), so equal-length
- * suffixes keep their declaration order — the router's existing tiebreak.
- */
-function sortSuffixParams(node: TrieNode): void {
-  if (node.xp) {
-    const sorted: Record<string, { n: string; c: TrieNode }> = {};
-    for (const suffix of Object.keys(node.xp).sort(
-      (a, b) => b.length - a.length,
-    )) {
-      sorted[suffix] = node.xp[suffix];
-    }
-    node.xp = sorted;
-    for (const child of Object.values(node.xp)) {
-      sortSuffixParams(child.c);
-    }
-  }
-  if (node.s) {
-    for (const child of Object.values(node.s)) {
-      sortSuffixParams(child);
-    }
-  }
-  if (node.p) {
-    sortSuffixParams(node.p.c);
-  }
-}
+export { buildRouteTrie };
+export type {
+  NegotiateVariant,
+  TrieLeaf,
+  TrieNode,
+} from "../router/route-trie-builder.js";
 
 /**
  * Build a per-router trie from a generated manifest. This is the single
@@ -186,192 +52,3 @@ export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
     manifest.responseTypeRoutes,
   );
 }
-
-/**
- * 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, "cv" | "pa">,
-): void {
-  // cv (full constraint map) is route-level and identical on every terminal,
-  // so compute it once on the shared base.
-  const constraints: Record<string, string[]> = {};
-
-  for (const seg of segments) {
-    if (seg.type === "param") {
-      if (seg.constraint) {
-        constraints[seg.value] = seg.constraint;
-      }
-    }
-  }
-
-  const leafBase: Omit<TrieLeaf, "pa"> = {
-    ...leaf,
-    ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
-  };
-
-  insertSegments(node, segments, index, leafBase, []);
-}
-
-/**
- * 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).
- */
-/**
- * Build a negotiate-variant entry from a leaf being folded into another leaf's
- * nv list. Carries the variant's positional param names (`pa`) so the runtime
- * can re-key matched params under the variant's names; omitted when the variant
- * has none (the common case where primary and variant share the same names is a
- * no-op re-key regardless).
- */
-function toVariant(leaf: TrieLeaf, responseType: string): NegotiateVariant {
-  return leaf.pa
-    ? { routeKey: leaf.n, responseType, pa: leaf.pa }
-    : { routeKey: leaf.n, responseType };
-}
-
-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(toVariant(existing, 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(toVariant(leaf, 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(toVariant(existing, 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 buildLeaf(
-  leafBase: Omit<TrieLeaf, "pa">,
-  paramNames: string[],
-): TrieLeaf {
-  return paramNames.length > 0
-    ? { ...leafBase, pa: [...paramNames] }
-    : { ...leafBase };
-}
-
-function insertSegments(
-  node: TrieNode,
-  segments: ParsedSegment[],
-  index: number,
-  leafBase: Omit<TrieLeaf, "pa">,
-  paramNames: string[],
-): void {
-  // Base case: all segments consumed, add terminal with branch-local pa
-  if (index >= segments.length) {
-    mergeLeaf(node, buildLeaf(leafBase, paramNames));
-    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,
-      leafBase,
-      paramNames,
-    );
-  } else if (segment.type === "param") {
-    if (segment.optional) {
-      // 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 (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,
-      ]);
-    }
-  } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments. Carry any params bound before
-    // the wildcard in pa so they zip correctly against paramValues at match.
-    // `pn` is "*" for the bare `/*` and the param name for a named catch-all;
-    // `w1` marks the one-or-more variant (`:name+`) so the walker rejects the
-    // empty-remainder case.
-    const wildLeaf: TrieLeaf & { pn: string; w1?: true } = {
-      ...buildLeaf(leafBase, paramNames),
-      pn: segment.value,
-      ...(segment.oneOrMore ? { w1: true as const } : {}),
-    };
-    const existing = node.w;
-    // Merge when there's no existing wildcard, when this is a response-type
-    // content-negotiation variant of the same catch-all (one side carries `rt`),
-    // or when it's the SAME catch-all identity (same param name + arity).
-    // Otherwise two DISTINCT catch-all forms (`/x/*` vs `/x/:p+`) would collide on
-    // the single wildcard slot with no non-lossy merge — so keep the first-declared
-    // (matching the regex matcher's declaration-order tiebreak) rather than let
-    // mergeLeaves' last-wins overwrite silently drop its `pn`/`w1` identity (which
-    // stranded the first route and fell through to a corrupt regex-fallback redirect).
-    const canMerge =
-      existing === undefined ||
-      Boolean(existing.rt) ||
-      Boolean(wildLeaf.rt) ||
-      (existing.pn === wildLeaf.pn &&
-        Boolean(existing.w1) === Boolean(wildLeaf.w1));
-    if (canMerge) {
-      const merged = mergeLeaves(
-        existing ? ({ ...existing } as TrieLeaf) : undefined,
-        wildLeaf,
-      );
-      node.w = merged as TrieLeaf & { pn: string; w1?: true };
-    }
-  }
-}

package/src/build/route-types/include-resolution.ts

@@ -77,6 +77,14 @@ function readSourceMemoized(
   return source;
 }
 
+function isUrlsDefinitionCall(node: ts.CallExpression): boolean {
+  const callee = node.expression;
+  return (
+    ts.isIdentifier(callee) &&
+    (callee.text === "urls" || callee.text === "clientUrls")
+  );
+}
+
 // ---------------------------------------------------------------------------
 // AST-based include() parsing
 // ---------------------------------------------------------------------------
@@ -206,10 +214,9 @@ function extractDynamicImportSpecifier(node: ts.Expression): string | null {
 }
 
 /**
- * Resolve a module's `export default` to either a same-file `urls()` variable
- * name (`export default shopPatterns`) or the inline call block
- * (`export default urls(...)`). Used to walk async include modules
- * (`() => import("./mod")`), whose convention is `export default urls(...)`.
+ * Resolve a module's `export default` to either a same-file route variable name
+ * (`export default shopPatterns`) or an inline urls()/clientUrls() call block.
+ * Used for default imports and to walk async include modules.
  */
 function resolveDefaultExportTarget(
   code: string,
@@ -223,11 +230,8 @@ function resolveDefaultExportTarget(
       const expr = node.expression;
       if (ts.isIdentifier(expr)) {
         result = { variableName: expr.text };
-      } else if (ts.isCallExpression(expr)) {
-        const callee = expr.expression;
-        if (ts.isIdentifier(callee) && callee.text === "urls") {
-          result = { inlineBlock: expr.getText(sourceFile) };
-        }
+      } else if (ts.isCallExpression(expr) && isUrlsDefinitionCall(expr)) {
+        result = { inlineBlock: expr.getText(sourceFile) };
       }
       return;
     }
@@ -358,6 +362,16 @@ export function resolveImportedVariable(
   code: string,
   localName: string,
 ): { specifier: string; exportedName: string } | null {
+  const defaultImportRegex =
+    /import\s+([\w$]+)\s*(?:,\s*\{[^}]*\})?\s+from\s*["']([^"']+)["']/g;
+  let defaultMatch;
+
+  while ((defaultMatch = defaultImportRegex.exec(code)) !== null) {
+    if (defaultMatch[1] === localName) {
+      return { specifier: defaultMatch[2], exportedName: "default" };
+    }
+  }
+
   // Allow an optional leading default binding before the named-import brace so
   // a combined `import Foo, { bar } from "..."` is matched (the named members
   // are the only part we resolve; the default binding is skipped). Without the
@@ -453,8 +467,7 @@ function extractUrlsBlockForVariable(
       node.initializer &&
       ts.isCallExpression(node.initializer)
     ) {
-      const callee = node.initializer.expression;
-      if (ts.isIdentifier(callee) && callee.text === "urls") {
+      if (isUrlsDefinitionCall(node.initializer)) {
         result = node.initializer.getText(sourceFile);
         return;
       }
@@ -780,6 +793,48 @@ export function buildCombinedRouteMapWithSearch(
   let block: string;
   if (inlineBlock) {
     block = inlineBlock;
+  } else if (variableName === "default") {
+    const defaultTarget = resolveDefaultExportTarget(
+      source,
+      parseBlock(memo, source),
+    );
+    if (!defaultTarget) {
+      visited.delete(key);
+      return { routes: {}, searchSchemas: {} };
+    }
+    if (defaultTarget.inlineBlock) {
+      block = defaultTarget.inlineBlock;
+    } else {
+      const targetName = defaultTarget.variableName!;
+      const imported = resolveImportedVariable(source, targetName);
+      if (imported) {
+        const targetFile = resolveImportPath(imported.specifier, realPath);
+        if (!targetFile) {
+          visited.delete(key);
+          return { routes: {}, searchSchemas: {} };
+        }
+        const result = buildCombinedRouteMapWithSearch(
+          targetFile,
+          imported.exportedName,
+          visited,
+          diagnosticsOut,
+          undefined,
+          memo,
+        );
+        visited.delete(key);
+        return result;
+      }
+      const extracted = extractUrlsBlockForVariable(
+        source,
+        targetName,
+        parseBlock(memo, source),
+      );
+      if (!extracted) {
+        visited.delete(key);
+        return { routes: {}, searchSchemas: {} };
+      }
+      block = extracted;
+    }
   } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(
       source,

package/src/build/route-types/per-module-writer.ts

@@ -12,8 +12,9 @@ import { findTsFiles } from "./scan-filter.js";
 
 /**
  * Generate per-module route type files by statically parsing url module source.
- * Scans for files containing `urls(` and writes a sibling `.gen.ts` with the
- * extracted route name/pattern pairs. Only writes when content has changed.
+ * Scans for files containing `urls(` or `clientUrls(` and writes a sibling
+ * `.gen.ts` with the extracted route name/pattern pairs. Only writes when
+ * content has changed.
  */
 export function writePerModuleRouteTypes(
   root: string,
@@ -26,7 +27,7 @@ export function writePerModuleRouteTypes(
 }
 
 /**
- * Find all variable names assigned to urls() calls in source code.
+ * Find all variable names assigned to urls() or clientUrls() calls in source.
  * e.g. `export const patterns = urls(...)` -> ["patterns"]
  */
 export function findUrlsVariableNames(code: string): string[] {
@@ -47,7 +48,10 @@ export function findUrlsVariableNames(code: string): string[] {
       ts.isCallExpression(node.initializer)
     ) {
       const callee = node.initializer.expression;
-      if (ts.isIdentifier(callee) && callee.text === "urls") {
+      if (
+        ts.isIdentifier(callee) &&
+        (callee.text === "urls" || callee.text === "clientUrls")
+      ) {
         names.push(node.name.text);
       }
     }
@@ -61,12 +65,13 @@ export function findUrlsVariableNames(code: string): string[] {
 /**
  * Generate per-module route types for a single url module file.
  * Follows include() calls recursively to produce the full route tree.
- * No-ops if the file doesn't contain `urls(` or has no named routes.
+ * No-ops if the file doesn't contain `urls(`/`clientUrls(` or has no named
+ * routes.
  */
 export function writePerModuleRouteTypesForFile(filePath: string): void {
   try {
     const source = readFileSync(filePath, "utf-8");
-    if (!source.includes("urls(")) return;
+    if (!source.includes("urls(") && !source.includes("clientUrls(")) return;
 
     const varNames = findUrlsVariableNames(source);