@rangojs/router 0.0.0-experimental.21 → 0.0.0-experimental.21efdd86

package/src/build/route-trie.ts

@@ -47,6 +47,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 };
 }
@@ -158,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);
     }
@@ -235,10 +242,19 @@ function insertSegments(
       mergeLeaf(node, leaf);
       // AND continue with param child (param present)
     }
-    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, leaf);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leaf);
     }
-    insertSegments(node.p.c, segments, index + 1, leaf);
   } else if (segment.type === "wildcard") {
     // Wildcard consumes all remaining segments
     const wildLeaf = { ...leaf, pn: "*" };

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

@@ -357,12 +357,17 @@ function buildRouteMapFromBlock(
 /**
  * Build route map and search schemas together.
  * Internal helper used by the include resolution path.
+ *
+ * @param inlineBlock - Optional pre-extracted code block (e.g. from an inline
+ *   builder function). When provided, variableName is ignored and the block
+ *   is parsed directly for path()/include() calls.
  */
 export function buildCombinedRouteMapWithSearch(
   filePath: string,
   variableName?: string,
   visited?: Set<string>,
   diagnosticsOut?: UnresolvableInclude[],
+  inlineBlock?: string,
 ): {
   routes: Record<string, string>;
   searchSchemas: Record<string, Record<string, string>>;
@@ -384,7 +389,9 @@ export function buildCombinedRouteMapWithSearch(
   }
 
   let block: string;
-  if (variableName) {
+  if (inlineBlock) {
+    block = inlineBlock;
+  } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(source, variableName);
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;

package/src/build/route-types/router-processing.ts

@@ -45,7 +45,9 @@ function isRoutableSourceFile(name: string): boolean {
       name.endsWith(".tsx") ||
       name.endsWith(".js") ||
       name.endsWith(".jsx")) &&
-    !name.includes(".gen.")
+    !name.includes(".gen.") &&
+    !name.includes(".test.") &&
+    !name.includes(".spec.")
   );
 }
 
@@ -70,7 +72,15 @@ function findRouterFilesRecursive(
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      if (
+        entry.name === "node_modules" ||
+        entry.name === "dist" ||
+        entry.name === "coverage" ||
+        entry.name === "__tests__" ||
+        entry.name === "__mocks__" ||
+        entry.name.startsWith(".")
+      )
+        continue;
       childDirs.push(fullPath);
       continue;
     }
@@ -147,13 +157,26 @@ export function formatNestedRouterConflictError(
 // ---------------------------------------------------------------------------
 
 /**
- * Extract the url patterns variable from a router file using AST.
- * Detects two patterns:
+ * Result of extracting URL patterns from a router file.
+ * - "variable": a named variable reference (e.g., `.routes(patterns)` or `urls: patterns`)
+ * - "inline": an inline builder function (e.g., `.routes(({ path }) => [...])` or `urls: ({ path }) => [...]`)
+ */
+export type UrlsExtractionResult =
+  | { kind: "variable"; name: string }
+  | { kind: "inline"; block: string };
+
+/**
+ * Extract the url patterns from a router file using AST.
+ * Detects four patterns:
  *   1. createRouter(...).routes(variableName)
  *   2. createRouter({ urls: variableName, ... })
- * Returns the local variable name.
+ *   3. createRouter(...).routes(({ path, ... }) => [...])
+ *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
+ * Returns either a variable name or an inline code block.
  */
-export function extractUrlsVariableFromRouter(code: string): string | null {
+export function extractUrlsFromRouter(
+  code: string,
+): UrlsExtractionResult | null {
   const sourceFile = ts.createSourceFile(
     "router.tsx",
     code,
@@ -161,7 +184,7 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
     true,
     ts.ScriptKind.TSX,
   );
-  let result: string | null = null;
+  let result: UrlsExtractionResult | null = null;
 
   function isCreateRouterCall(node: ts.Node): boolean {
     if (!ts.isCallExpression(node)) return false;
@@ -169,44 +192,108 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
     return ts.isIdentifier(callee) && callee.text === "createRouter";
   }
 
+  /** Check if a node is an arrow/function expression (inline builder). */
+  function isInlineBuilder(node: ts.Node): boolean {
+    return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+  }
+
+  /** Check if a .routes() call chains from createRouter(). */
+  function isRoutesOnCreateRouter(node: ts.CallExpression): boolean {
+    if (
+      !ts.isPropertyAccessExpression(node.expression) ||
+      node.expression.name.text !== "routes"
+    )
+      return false;
+    let inner: ts.Expression = node.expression.expression;
+    while (
+      ts.isCallExpression(inner) &&
+      ts.isPropertyAccessExpression(inner.expression)
+    ) {
+      inner = inner.expression.expression;
+    }
+    return isCreateRouterCall(inner);
+  }
+
   function visit(node: ts.Node) {
     if (result) return;
 
-    // Pattern 1: createRouter(...).routes(variableName)
-    // The AST shape is CallExpression(.routes) -> PropertyAccessExpression -> CallExpression(createRouter)
+    // Pattern 1 & 3: createRouter(...).routes(variableName | builder)
     if (
       ts.isCallExpression(node) &&
-      ts.isPropertyAccessExpression(node.expression) &&
-      node.expression.name.text === "routes" &&
       node.arguments.length >= 1 &&
-      ts.isIdentifier(node.arguments[0])
+      isRoutesOnCreateRouter(node)
     ) {
-      // Walk up the chain: createRouter().middleware(...).routes(x) etc.
-      // The innermost call should be createRouter(...)
-      let inner: ts.Expression = node.expression.expression;
-      while (
-        ts.isCallExpression(inner) &&
-        ts.isPropertyAccessExpression(inner.expression)
-      ) {
-        inner = inner.expression.expression;
-      }
-      if (isCreateRouterCall(inner)) {
-        result = (node.arguments[0] as ts.Identifier).text;
-        return;
+      const arg = node.arguments[0];
+      if (ts.isIdentifier(arg)) {
+        result = { kind: "variable", name: arg.text };
+      } else if (isInlineBuilder(arg)) {
+        result = { kind: "inline", block: arg.getText(sourceFile) };
       }
+      return;
     }
 
-    // Pattern 2: createRouter({ urls: variableName, ... })
+    // Pattern 2 & 4: createRouter({ urls: variableName | builder, ... })
     if (isCreateRouterCall(node)) {
       const callExpr = node as ts.CallExpression;
-      for (const arg of callExpr.arguments) {
+      for (const callArg of callExpr.arguments) {
+        if (ts.isObjectLiteralExpression(callArg)) {
+          for (const prop of callArg.properties) {
+            if (
+              ts.isPropertyAssignment(prop) &&
+              ts.isIdentifier(prop.name) &&
+              prop.name.text === "urls"
+            ) {
+              if (ts.isIdentifier(prop.initializer)) {
+                result = { kind: "variable", name: prop.initializer.text };
+              } else if (isInlineBuilder(prop.initializer)) {
+                result = {
+                  kind: "inline",
+                  block: prop.initializer.getText(sourceFile),
+                };
+              }
+              return;
+            }
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return result;
+}
+
+/**
+ * Extract the `basename` string literal from createRouter({ basename: "..." }).
+ * Returns the basename value or undefined if not present.
+ */
+export function extractBasenameFromRouter(code: string): string | undefined {
+  const sourceFile = ts.createSourceFile(
+    "router.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let result: string | undefined;
+
+  function visit(node: ts.Node) {
+    if (result !== undefined) return;
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === "createRouter"
+    ) {
+      for (const arg of node.arguments) {
         if (ts.isObjectLiteralExpression(arg)) {
           for (const prop of arg.properties) {
             if (
               ts.isPropertyAssignment(prop) &&
               ts.isIdentifier(prop.name) &&
-              prop.name.text === "urls" &&
-              ts.isIdentifier(prop.initializer)
+              prop.name.text === "basename" &&
+              ts.isStringLiteral(prop.initializer)
             ) {
               result = prop.initializer.text;
               return;
@@ -215,7 +302,6 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
         }
       }
     }
-
     ts.forEachChild(node, visit);
   }
 
@@ -223,9 +309,40 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
   return result;
 }
 
+/** @deprecated Use extractUrlsFromRouter instead */
+export function extractUrlsVariableFromRouter(code: string): string | null {
+  const result = extractUrlsFromRouter(code);
+  return result?.kind === "variable" ? result.name : null;
+}
+
+/** Apply a basename prefix to all route patterns in a result set. */
+function applyBasenameToRoutes(
+  result: {
+    routes: Record<string, string>;
+    searchSchemas: Record<string, Record<string, string>>;
+  },
+  basename: string,
+): {
+  routes: Record<string, string>;
+  searchSchemas: Record<string, Record<string, string>>;
+} {
+  const prefixed: Record<string, string> = {};
+  for (const [name, pattern] of Object.entries(result.routes)) {
+    if (pattern === "/") {
+      prefixed[name] = basename;
+    } else if (basename.endsWith("/") && pattern.startsWith("/")) {
+      prefixed[name] = basename + pattern.slice(1);
+    } else {
+      prefixed[name] = basename + pattern;
+    }
+  }
+  return { routes: prefixed, searchSchemas: result.searchSchemas };
+}
+
 /**
  * Resolve routes and search schemas from a router source file by following the
- * variable passed to `.routes(...)` or `urls: ...` in createRouter options.
+ * variable passed to `.routes(...)` or `urls: ...` in createRouter options,
+ * or by parsing an inline builder function directly.
  */
 export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
   routes: Record<string, string>;
@@ -238,21 +355,54 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     return { routes: {}, searchSchemas: {} };
   }
 
-  const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-  if (!urlsVarName) {
+  const extraction = extractUrlsFromRouter(routerSource);
+  if (!extraction) {
     return { routes: {}, searchSchemas: {} };
   }
 
-  const imported = resolveImportedVariable(routerSource, urlsVarName);
-  if (imported) {
-    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-    if (!targetFile) {
-      return { routes: {}, searchSchemas: {} };
+  // Detect basename from createRouter({ basename: "..." })
+  const rawBasename = extractBasenameFromRouter(routerSource);
+  const basename = rawBasename
+    ? ("/" + rawBasename.replace(/^\/+|\/+$/g, "")).replace(/^\/$/, "")
+    : undefined;
+
+  let result: {
+    routes: Record<string, string>;
+    searchSchemas: Record<string, Record<string, string>>;
+  };
+
+  // Inline builder: extract routes directly from the function body
+  if (extraction.kind === "inline") {
+    result = buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      undefined,
+      undefined,
+      undefined,
+      extraction.block,
+    );
+  } else {
+    // Variable reference: follow imports or same-file declaration
+    const imported = resolveImportedVariable(routerSource, extraction.name);
+    if (imported) {
+      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+      if (!targetFile) {
+        return { routes: {}, searchSchemas: {} };
+      }
+      result = buildCombinedRouteMapWithSearch(
+        targetFile,
+        imported.exportedName,
+      );
+    } else {
+      result = buildCombinedRouteMapWithSearch(routerFilePath, extraction.name);
     }
-    return buildCombinedRouteMapWithSearch(targetFile, imported.exportedName);
   }
 
-  return buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+  // Apply basename prefix to all extracted route patterns
+  if (basename) {
+    result = applyBasenameToRoutes(result, basename);
+  }
+
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -275,12 +425,26 @@ export function detectUnresolvableIncludes(
     return [];
   }
 
-  // Extract the urls variable from the router file
-  const urlsVarName = extractUrlsVariableFromRouter(source);
-  if (!urlsVarName) return [];
+  // Extract the urls source from the router file
+  const extraction = extractUrlsFromRouter(source);
+  if (!extraction) return [];
+
+  const diagnostics: UnresolvableInclude[] = [];
+
+  if (extraction.kind === "inline") {
+    // Inline builder: parse directly
+    buildCombinedRouteMapWithSearch(
+      realPath,
+      undefined,
+      new Set(),
+      diagnostics,
+      extraction.block,
+    );
+    return diagnostics;
+  }
 
-  // Resolve where the urls variable comes from
-  const imported = resolveImportedVariable(source, urlsVarName);
+  // Variable reference: resolve where it comes from
+  const imported = resolveImportedVariable(source, extraction.name);
   let targetFile: string;
   let exportedName: string | undefined;
 
@@ -302,10 +466,9 @@ export function detectUnresolvableIncludes(
   } else {
     // Same-file urls() definition
     targetFile = realPath;
-    exportedName = urlsVarName;
+    exportedName = extraction.name;
   }
 
-  const diagnostics: UnresolvableInclude[] = [];
   buildCombinedRouteMapWithSearch(
     targetFile,
     exportedName,
@@ -387,34 +550,20 @@ export function writeCombinedRouteTypes(
   }
 
   for (const routerFilePath of routerFilePaths) {
-    let routerSource: string;
-    try {
-      routerSource = readFileSync(routerFilePath, "utf-8");
-    } catch {
-      continue;
-    }
-    // Extract the urls variable name from .routes(varName) or urls: varName
-    const urlsVarName = extractUrlsVariableFromRouter(routerSource);
-    if (!urlsVarName) continue;
-
-    // Resolve the variable to its source module
-    let result: {
-      routes: Record<string, string>;
-      searchSchemas: Record<string, Record<string, string>>;
-    };
-
-    const imported = resolveImportedVariable(routerSource, urlsVarName);
-    if (imported) {
-      // Variable is imported from another module
-      const targetFile = resolveImportPath(imported.specifier, routerFilePath);
-      if (!targetFile) continue;
-      result = buildCombinedRouteMapWithSearch(
-        targetFile,
-        imported.exportedName,
-      );
-    } else {
-      // Variable is defined in the same file
-      result = buildCombinedRouteMapWithSearch(routerFilePath, urlsVarName);
+    const result = buildCombinedRouteMapForRouterFile(routerFilePath);
+    if (
+      Object.keys(result.routes).length === 0 &&
+      Object.keys(result.searchSchemas).length === 0
+    ) {
+      // Check if the file even has a createRouter call — if not, skip entirely.
+      // If it does, fall through to write an empty placeholder below.
+      let routerSource: string;
+      try {
+        routerSource = readFileSync(routerFilePath, "utf-8");
+      } catch {
+        continue;
+      }
+      if (!extractUrlsFromRouter(routerSource)) continue;
     }
 
     const routerBasename = pathBasename(routerFilePath).replace(

package/src/build/route-types/scan-filter.ts

@@ -61,7 +61,14 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      if (
+        entry.name === "node_modules" ||
+        entry.name.startsWith(".") ||
+        entry.name === "dist" ||
+        entry.name === "build" ||
+        entry.name === "coverage"
+      )
+        continue;
       results.push(...findTsFiles(fullPath, filter));
     } else if (
       (entry.name.endsWith(".ts") ||

package/src/cache/cache-runtime.ts

@@ -214,11 +214,21 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted args and RequestContext so request-scoped
-          // reads (cookies, headers) and side effects (ctx.set, etc.)
-          // throw inside background revalidation, same as the miss path.
-          // Uses ref-counted stamp/unstamp so overlapping executions
-          // sharing the same ctx don't clear each other's guards.
+          // Stamp tainted ARGS only — not requestCtx. The args stamp guards
+          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
+          // which is sufficient for correctness.
+          //
+          // We intentionally skip stamping requestCtx here because:
+          // 1. runBackground starts the async task synchronously (before the
+          //    first await), so stampCacheExec would pollute the shared
+          //    requestCtx while the foreground pipeline is still running.
+          //    This causes assertNotInsideCacheExec to fire when cache-store
+          //    later calls requestCtx.onResponse().
+          // 2. requestCtx methods are closure-bound to the original ctx, so
+          //    neither Object.create() nor a proxy can isolate the stamp.
+          // 3. The foreground miss path already stamps requestCtx and catches
+          //    cookies()/headers() misuse on first execution. The background
+          //    re-runs the same function with the same request.
           const bgTaintedArgs: unknown[] = [];
           for (const arg of args) {
             if (isTainted(arg)) {
@@ -226,9 +236,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               bgTaintedArgs.push(arg);
             }
           }
-          if (requestCtx) {
-            stampCacheExec(requestCtx as object);
-          }
 
           try {
             const freshResult = await fn.apply(this, args);
@@ -249,9 +256,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
             }
-            if (requestCtx) {
-              unstampCacheExec(requestCtx as object);
-            }
             // Restore original handle store
             if (originalHandleStore && requestCtx) {
               requestCtx._handleStore = originalHandleStore;

package/src/cache/cache-scope.ts

@@ -73,7 +73,7 @@ function getDefaultRouteCacheKey(
   isIntercept?: boolean,
 ): string {
   const ctx = getRequestContext();
-  const isPartial = ctx?.url.searchParams.has("_rsc_partial") ?? false;
+  const isPartial = ctx?.originalUrl?.searchParams.has("_rsc_partial") ?? false;
   const searchParams = ctx?.url.searchParams;
   const host = ctx?.url.host ?? "localhost";
 
@@ -326,24 +326,61 @@ export class CacheScope {
     const key = await this.resolveKey(pathname, params, isIntercept);
 
     // Check if this is a partial request (navigation) vs document request
-    const isPartial = requestCtx.url.searchParams.has("_rsc_partial");
+    const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
+
+    if (INTERNAL_RANGO_DEBUG) {
+      debugCacheLog(
+        `[CacheScope] cacheRoute: scheduling waitUntil for ${key} (${nonLoaderSegments.length} segments, isPartial=${isPartial})`,
+      );
+    }
 
     requestCtx.waitUntil(async () => {
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(
+          `[CacheScope] waitUntil: awaiting handleStore.settled for ${key}`,
+        );
+      }
+
       await handleStore.settled;
 
-      // For document requests: only cache if ALL segments have components (complete render)
-      // For partial requests: null components are expected (client already has them)
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(`[CacheScope] waitUntil: handleStore settled for ${key}`);
+      }
+
+      // For document requests: only cache if layout segments have components
+      // (complete render). Parallel and route segments may legitimately have
+      // null components — UI-less @meta parallels return null, and void route
+      // handlers produce null when the UI lives in parallel slots/layouts.
+      // Partial requests always allow null components (client already has them).
       if (!isPartial) {
-        const hasAllComponents = nonLoaderSegments.every(
-          (s) => s.component !== null,
+        const hasIncompleteLayouts = nonLoaderSegments.some(
+          (s) => s.component === null && s.type === "layout",
         );
-        if (!hasAllComponents) return;
+        if (hasIncompleteLayouts) {
+          const nullSegments = nonLoaderSegments
+            .filter((s) => s.component === null && s.type === "layout")
+            .map((s) => s.id);
+          const error = new Error(
+            `[CacheScope] Cache write skipped: layout segments have null components ` +
+              `(${nullSegments.join(", ")}). This indicates an incomplete render — ` +
+              `layout handlers must return JSX for document requests to be cacheable.`,
+          );
+          error.name = "CacheScopeInvariantError";
+          console.error(error.message);
+          return;
+        }
       }
 
       // Collect handle data for non-loader segments only
       const handles = captureHandles(nonLoaderSegments, handleStore);
 
       try {
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(
+            `[CacheScope] waitUntil: serializing ${nonLoaderSegments.length} segments for ${key}`,
+          );
+        }
+
         // Serialize non-loader segments only
         const serializedSegments = await serializeSegments(nonLoaderSegments);
 
@@ -353,6 +390,10 @@ export class CacheScope {
           expiresAt: Date.now() + ttl * 1000,
         };
 
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
+        }
+
         await store.set(key, data, ttl, swr);
 
         if (INTERNAL_RANGO_DEBUG) {