@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

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

@@ -1,28 +1,182 @@
-import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
-import { join, dirname, resolve, basename as pathBasename } from "node:path";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  unlinkSync,
+  readdirSync,
+} from "node:fs";
+import {
+  join,
+  dirname,
+  resolve,
+  sep,
+  basename as pathBasename,
+} from "node:path";
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
 import type { ScanFilter } from "./scan-filter.js";
-import { findTsFiles } from "./scan-filter.js";
 import {
   resolveImportedVariable,
   resolveImportPath,
   buildCombinedRouteMapWithSearch,
   type UnresolvableInclude,
 } from "./include-resolution.js";
+import { findUrlsVariableNames } from "./per-module-writer.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
+
+function countPublicRouteEntries(source: string): number {
+  const matches =
+    source.matchAll(/^\s+(?:"([^"]+)"|([a-zA-Z_$][^:]*)):\s*["{]/gm) ?? [];
+  let count = 0;
+  for (const match of matches) {
+    const routeName = match[1] || match[2];
+    if (routeName && !isAutoGeneratedRouteName(routeName.trim())) {
+      count++;
+    }
+  }
+  return count;
+}
+
+const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+
+function isRoutableSourceFile(name: string): boolean {
+  return (
+    (name.endsWith(".ts") ||
+      name.endsWith(".tsx") ||
+      name.endsWith(".js") ||
+      name.endsWith(".jsx")) &&
+    !name.includes(".gen.") &&
+    !name.includes(".test.") &&
+    !name.includes(".spec.")
+  );
+}
+
+function findRouterFilesRecursive(
+  dir: string,
+  filter: ScanFilter | undefined,
+  results: string[],
+): void {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(
+      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+    );
+    return;
+  }
+
+  const childDirs: string[] = [];
+  const routerFilesInDir: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      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;
+    }
+
+    if (!isRoutableSourceFile(entry.name)) continue;
+    if (filter && !filter(fullPath)) continue;
+
+    try {
+      const source = readFileSync(fullPath, "utf-8");
+      if (ROUTER_CALL_PATTERN.test(source)) {
+        routerFilesInDir.push(fullPath);
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  // A directory that contains a router file is treated as a router root.
+  // Once found, deeper directories are skipped to avoid redundant scans.
+  if (routerFilesInDir.length > 0) {
+    results.push(...routerFilesInDir);
+    return;
+  }
+
+  for (const childDir of childDirs) {
+    findRouterFilesRecursive(childDir, filter, results);
+  }
+}
+
+export function findNestedRouterConflict(
+  routerFiles: string[],
+): { ancestor: string; nested: string } | null {
+  const routerDirs = [
+    ...new Set(routerFiles.map((filePath) => dirname(resolve(filePath)))),
+  ].sort((a, b) => a.length - b.length);
+
+  for (let i = 0; i < routerDirs.length; i++) {
+    const ancestorDir = routerDirs[i];
+    const prefix = ancestorDir.endsWith(sep)
+      ? ancestorDir
+      : `${ancestorDir}${sep}`;
+    for (let j = i + 1; j < routerDirs.length; j++) {
+      const nestedDir = routerDirs[j];
+      if (!nestedDir.startsWith(prefix)) continue;
+      const ancestorFile = routerFiles.find(
+        (filePath) => dirname(resolve(filePath)) === ancestorDir,
+      );
+      const nestedFile = routerFiles.find(
+        (filePath) => dirname(resolve(filePath)) === nestedDir,
+      );
+      if (ancestorFile && nestedFile) {
+        return { ancestor: ancestorFile, nested: nestedFile };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function formatNestedRouterConflictError(
+  conflict: { ancestor: string; nested: string },
+  prefix = "[rsc-router]",
+): string {
+  return (
+    `${prefix} Nested router roots are not supported.\n` +
+    `Router root: ${conflict.ancestor}\n` +
+    `Nested router: ${conflict.nested}\n` +
+    `Move the nested router into a sibling directory or configure it as a separate app root.`
+  );
+}
 
 // ---------------------------------------------------------------------------
 // Router file URL extraction
 // ---------------------------------------------------------------------------
 
 /**
- * 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,
@@ -30,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;
@@ -38,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;
@@ -84,7 +302,6 @@ export function extractUrlsVariableFromRouter(code: string): string | null {
         }
       }
     }
-
     ts.forEachChild(node, visit);
   }
 
@@ -92,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>;
@@ -107,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -144,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[] = [];
 
-  // Resolve where the urls variable comes from
-  const imported = resolveImportedVariable(source, urlsVarName);
+  if (extraction.kind === "inline") {
+    // Inline builder: parse directly
+    buildCombinedRouteMapWithSearch(
+      realPath,
+      undefined,
+      new Set(),
+      diagnostics,
+      extraction.block,
+    );
+    return diagnostics;
+  }
+
+  // Variable reference: resolve where it comes from
+  const imported = resolveImportedVariable(source, extraction.name);
   let targetFile: string;
   let exportedName: string | undefined;
 
@@ -171,10 +466,9 @@ export function detectUnresolvableIncludes(
   } else {
     // Same-file urls() definition
     targetFile = realPath;
-    exportedName = urlsVarName;
+    exportedName = extraction.name;
   }
 
-  const diagnostics: UnresolvableInclude[] = [];
   buildCombinedRouteMapWithSearch(
     targetFile,
     exportedName,
@@ -184,6 +478,33 @@ export function detectUnresolvableIncludes(
   return diagnostics;
 }
 
+/**
+ * Walk the include tree for a standalone urls() module file and detect
+ * all unresolvable includes. Mirrors detectUnresolvableIncludes() but
+ * operates on urls() variable declarations instead of going through
+ * createRouter().
+ */
+export function detectUnresolvableIncludesForUrlsFile(
+  filePath: string,
+): UnresolvableInclude[] {
+  const realPath = resolve(filePath);
+  let source: string;
+  try {
+    source = readFileSync(realPath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const varNames = findUrlsVariableNames(source);
+  if (varNames.length === 0) return [];
+
+  const diagnostics: UnresolvableInclude[] = [];
+  for (const varName of varNames) {
+    buildCombinedRouteMapWithSearch(realPath, varName, new Set(), diagnostics);
+  }
+  return diagnostics;
+}
+
 // ---------------------------------------------------------------------------
 // Per-router named-routes.gen.ts writer
 // ---------------------------------------------------------------------------
@@ -193,19 +514,8 @@ export function detectUnresolvableIncludes(
  * Call once at startup; the result can be reused on subsequent watcher triggers.
  */
 export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
-  const files = findTsFiles(root, filter);
   const result: string[] = [];
-  for (const filePath of files) {
-    if (filePath.includes(".gen.")) continue;
-    try {
-      const source = readFileSync(filePath, "utf-8");
-      if (/\bcreateRouter\s*[<(]/.test(source)) {
-        result.push(filePath);
-      }
-    } catch {
-      continue;
-    }
-  }
+  findRouterFilesRecursive(root, filter, result);
   return result;
 }
 
@@ -234,35 +544,26 @@ export function writeCombinedRouteTypes(
   const routerFilePaths = knownRouterFiles ?? findRouterFiles(root);
   if (routerFilePaths.length === 0) return;
 
-  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 nestedRouterConflict = findNestedRouterConflict(routerFilePaths);
+  if (nestedRouterConflict) {
+    throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
+  }
 
-    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);
+  for (const routerFilePath of routerFilePaths) {
+    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(
@@ -300,10 +601,10 @@ export function writeCombinedRouteTypes(
       // or other dynamic code. During HMR (file watcher), always write so
       // newly added routes appear immediately.
       if (opts?.preserveIfLarger && existing) {
-        const existingCount = (
-          existing.match(/^\s+["a-zA-Z_$][^:]*:\s*["{]/gm) || []
+        const existingCount = countPublicRouteEntries(existing);
+        const newCount = Object.keys(result.routes).filter(
+          (name) => !isAutoGeneratedRouteName(name),
         ).length;
-        const newCount = Object.keys(result.routes).length;
         if (existingCount > newCount) {
           continue;
         }

package/src/build/runtime-discovery.ts

@@ -4,6 +4,7 @@ import {
   generateRouteTypesSource,
   buildCombinedRouteMapForRouterFile,
 } from "./generate-route-types.ts";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 
 export interface RuntimeDiscoveryOptions {
   /** Project root directory (where package.json / node_modules live). */
@@ -140,7 +141,18 @@ export async function discoverAndWriteRouteTypes(
       const manifest = generateManifest(router.urlpatterns, routerMountIndex);
       routerMountIndex++;
 
-      const routeManifest: Record<string, string> = manifest.routeManifest;
+      // Filter out auto-generated route names that the runtime creates for
+      // unnamed routes (path() with no name option). These get names like
+      // "$path__health" at root level or "docs.$path__health" under include().
+      // Match the Vite discovery writer's predicate: any name starting with "$"
+      // is internal. For prefixed names, check each dot-separated segment.
+      const rawManifest: Record<string, string> = manifest.routeManifest;
+      const routeManifest: Record<string, string> = {};
+      for (const [name, pattern] of Object.entries(rawManifest)) {
+        if (!isAutoGeneratedRouteName(name)) {
+          routeManifest[name] = pattern;
+        }
+      }
       let routeSearchSchemas:
         | Record<string, Record<string, string>>
         | undefined = manifest.routeSearchSchemas;

package/src/cache/background-task.ts

@@ -0,0 +1,34 @@
+/**
+ * Background Task Runner
+ *
+ * Unified helper for scheduling async work via waitUntil.
+ * When waitUntil is unavailable, falls back to blocking or skipping.
+ */
+
+interface WaitUntilHost {
+  waitUntil?: (fn: () => Promise<void>) => void;
+}
+
+/**
+ * Schedule an async task in the background via waitUntil.
+ *
+ * @param host - Object with optional waitUntil (request context or similar)
+ * @param task - Async function to execute
+ * @param blockWhenNoWaitUntil - If true, awaits the task when waitUntil is
+ *   unavailable (e.g., Node.js dev server). If false (default), the task
+ *   is silently skipped when waitUntil is unavailable.
+ * @returns A promise when blocking fallback is used, void otherwise.
+ */
+export function runBackground(
+  host: WaitUntilHost | null | undefined,
+  task: () => Promise<void>,
+  blockWhenNoWaitUntil = false,
+): Promise<void> | void {
+  if (host?.waitUntil) {
+    host.waitUntil(task);
+    return;
+  }
+  if (blockWhenNoWaitUntil) {
+    return task();
+  }
+}