@rangojs/router 0.5.2 → 0.6.0

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);
 

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

@@ -20,6 +20,8 @@ import {
   resolveImportedVariable,
   resolveImportPath,
   buildCombinedRouteMapWithSearch,
+  createScanMemo,
+  type ScanMemo,
   type UnresolvableInclude,
 } from "./include-resolution.js";
 import { findUrlsVariableNames } from "./per-module-writer.js";
@@ -197,18 +199,43 @@ 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, ... })
- *   3. createRouter(...).routes(({ path, ... }) => [...])
- *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
- * Returns either a variable name or an inline code block.
- */
-export function extractUrlsFromRouter(
-  code: string,
+function isCreateRouterCall(node: ts.Node): boolean {
+  if (!ts.isCallExpression(node)) return false;
+  const callee = node.expression;
+  return ts.isIdentifier(callee) && callee.text === "createRouter";
+}
+
+function extractUrlsArgument(
+  node: ts.Expression,
+  sourceFile: ts.SourceFile,
 ): UrlsExtractionResult | null {
+  if (ts.isIdentifier(node)) {
+    return { kind: "variable", name: node.text };
+  }
+  if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+    return { kind: "inline", block: node.getText(sourceFile) };
+  }
+  return null;
+}
+
+/** Return a createRouter call chain in runtime registration order. */
+function collectCreateRouterCallChain(
+  endpoint: ts.CallExpression,
+): ts.CallExpression[] | null {
+  const calls: ts.CallExpression[] = [];
+  let current = endpoint;
+
+  while (true) {
+    calls.push(current);
+    if (isCreateRouterCall(current)) return calls.reverse();
+    if (!ts.isPropertyAccessExpression(current.expression)) return null;
+    const receiver = current.expression.expression;
+    if (!ts.isCallExpression(receiver)) return null;
+    current = receiver;
+  }
+}
+
+function extractAllUrlsFromRouter(code: string): UrlsExtractionResult[] {
   const sourceFile = ts.createSourceFile(
     "router.tsx",
     code,
@@ -216,85 +243,71 @@ export function extractUrlsFromRouter(
     true,
     ts.ScriptKind.TSX,
   );
-  let result: UrlsExtractionResult | null = null;
-
-  function isCreateRouterCall(node: ts.Node): boolean {
-    if (!ts.isCallExpression(node)) return false;
-    const callee = node.expression;
-    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);
-  }
+  let result: UrlsExtractionResult[] | null = null;
 
   function visit(node: ts.Node) {
     if (result) return;
-
-    // Pattern 1 & 3: createRouter(...).routes(variableName | builder)
-    if (
-      ts.isCallExpression(node) &&
-      node.arguments.length >= 1 &&
-      isRoutesOnCreateRouter(node)
-    ) {
-      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 & 4: createRouter({ urls: variableName | builder, ... })
-    if (isCreateRouterCall(node)) {
-      const callExpr = node as ts.CallExpression;
-      for (const callArg of callExpr.arguments) {
-        if (ts.isObjectLiteralExpression(callArg)) {
+    if (ts.isCallExpression(node)) {
+      const chain = collectCreateRouterCallChain(node);
+      if (chain) {
+        const extracted: UrlsExtractionResult[] = [];
+        const createRouterCall = chain[0];
+
+        for (const callArg of createRouterCall.arguments) {
+          if (!ts.isObjectLiteralExpression(callArg)) continue;
           for (const prop of callArg.properties) {
             if (
-              ts.isPropertyAssignment(prop) &&
-              ts.isIdentifier(prop.name) &&
-              prop.name.text === "urls"
+              !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;
+              continue;
             }
+            const urls = extractUrlsArgument(prop.initializer, sourceFile);
+            if (urls) extracted.push(urls);
+            break;
           }
         }
+
+        for (const call of chain.slice(1)) {
+          if (
+            !ts.isPropertyAccessExpression(call.expression) ||
+            call.expression.name.text !== "routes" ||
+            call.arguments.length === 0
+          ) {
+            continue;
+          }
+          const urls = extractUrlsArgument(call.arguments[0], sourceFile);
+          if (urls) extracted.push(urls);
+        }
+
+        if (extracted.length > 0) {
+          result = extracted;
+          return;
+        }
       }
     }
-
     ts.forEachChild(node, visit);
   }
 
   visit(sourceFile);
-  return result;
+  return result ?? [];
+}
+
+/**
+ * Extract the url patterns from a router file using AST.
+ * Detects four patterns:
+ *   1. createRouter(...).routes(variableName)
+ *   2. createRouter({ urls: variableName, ... })
+ *   3. createRouter(...).routes(({ path, ... }) => [...])
+ *   4. createRouter({ urls: ({ path, ... }) => [...], ... })
+ * Returns either a variable name or an inline code block.
+ */
+export function extractUrlsFromRouter(
+  code: string,
+): UrlsExtractionResult | null {
+  const extractions = extractAllUrlsFromRouter(code);
+  return extractions[extractions.length - 1] ?? null;
 }
 
 /**
@@ -365,6 +378,77 @@ function applyBasenameToRoutes(
   return { routes: prefixed, searchSchemas: result.searchSchemas };
 }
 
+type RouteMapWithSearch = {
+  routes: Record<string, string>;
+  searchSchemas: Record<string, Record<string, string>>;
+};
+
+function resolveRouterUrlsExtraction(
+  routerFilePath: string,
+  routerSource: string,
+  extraction: UrlsExtractionResult,
+  diagnosticsOut: UnresolvableInclude[] | undefined,
+  memo: ScanMemo,
+): RouteMapWithSearch {
+  if (extraction.kind === "inline") {
+    return buildCombinedRouteMapWithSearch(
+      routerFilePath,
+      undefined,
+      new Set(),
+      diagnosticsOut,
+      extraction.block,
+      memo,
+    );
+  }
+
+  const imported = resolveImportedVariable(routerSource, extraction.name);
+  if (imported) {
+    const targetFile = resolveImportPath(imported.specifier, routerFilePath);
+    if (!targetFile) {
+      diagnosticsOut?.push({
+        pathPrefix: "/",
+        namePrefix: null,
+        reason: "file-not-found",
+        sourceFile: routerFilePath,
+        detail: `import "${imported.specifier}" resolved to no file`,
+      });
+      return { routes: {}, searchSchemas: {} };
+    }
+    return buildCombinedRouteMapWithSearch(
+      targetFile,
+      imported.exportedName,
+      new Set(),
+      diagnosticsOut,
+      undefined,
+      memo,
+    );
+  }
+
+  return buildCombinedRouteMapWithSearch(
+    routerFilePath,
+    extraction.name,
+    new Set(),
+    diagnosticsOut,
+    undefined,
+    memo,
+  );
+}
+
+function mergeRouteMaps(
+  target: RouteMapWithSearch,
+  source: RouteMapWithSearch,
+): void {
+  for (const [name, pattern] of Object.entries(source.routes)) {
+    target.routes[name] = pattern;
+    const search = source.searchSchemas[name];
+    if (search) {
+      target.searchSchemas[name] = search;
+    } else {
+      delete target.searchSchemas[name];
+    }
+  }
+}
+
 // Filesystem path of the generated route-types file for a router source file.
 // Native separators — matches the self-gen-tracking Map key the watcher compares.
 export function genFileTsPath(sourceFile: string): string {
@@ -396,9 +480,8 @@ export function resolveSearchSchemas(
 }
 
 /**
- * Resolve routes and search schemas from a router source file by following the
- * variable passed to `.routes(...)` or `urls: ...` in createRouter options,
- * or by parsing an inline builder function directly.
+ * Resolve routes and search schemas from every direct mount in a createRouter
+ * chain. Registrations are merged in runtime order, with later mounts winning.
  */
 export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
   routes: Record<string, string>;
@@ -411,8 +494,8 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     return { routes: {}, searchSchemas: {} };
   }
 
-  const extraction = extractUrlsFromRouter(routerSource);
-  if (!extraction) {
+  const extractions = extractAllUrlsFromRouter(routerSource);
+  if (extractions.length === 0) {
     return { routes: {}, searchSchemas: {} };
   }
 
@@ -422,40 +505,24 @@ export function buildCombinedRouteMapForRouterFile(routerFilePath: string): {
     ? ("/" + 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,
+  const result: RouteMapWithSearch = { routes: {}, searchSchemas: {} };
+  const memo = createScanMemo();
+  for (const extraction of extractions) {
+    mergeRouteMaps(
+      result,
+      resolveRouterUrlsExtraction(
+        routerFilePath,
+        routerSource,
+        extraction,
+        undefined,
+        memo,
+      ),
     );
-  } 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);
-    }
   }
 
   // Apply basename prefix to all extracted route patterns
   if (basename) {
-    result = applyBasenameToRoutes(result, basename);
+    return applyBasenameToRoutes(result, basename);
   }
 
   return result;
@@ -481,56 +548,20 @@ export function detectUnresolvableIncludes(
     return [];
   }
 
-  // Extract the urls source from the router file
-  const extraction = extractUrlsFromRouter(source);
-  if (!extraction) return [];
+  const extractions = extractAllUrlsFromRouter(source);
+  if (extractions.length === 0) return [];
 
   const diagnostics: UnresolvableInclude[] = [];
-
-  if (extraction.kind === "inline") {
-    // Inline builder: parse directly
-    buildCombinedRouteMapWithSearch(
+  const memo = createScanMemo();
+  for (const extraction of extractions) {
+    resolveRouterUrlsExtraction(
       realPath,
-      undefined,
-      new Set(),
+      source,
+      extraction,
       diagnostics,
-      extraction.block,
+      memo,
     );
-    return diagnostics;
-  }
-
-  // Variable reference: resolve where it comes from
-  const imported = resolveImportedVariable(source, extraction.name);
-  let targetFile: string;
-  let exportedName: string | undefined;
-
-  if (imported) {
-    const resolved = resolveImportPath(imported.specifier, realPath);
-    if (!resolved) {
-      return [
-        {
-          pathPrefix: "/",
-          namePrefix: null,
-          reason: "file-not-found",
-          sourceFile: realPath,
-          detail: `import "${imported.specifier}" resolved to no file`,
-        },
-      ];
-    }
-    targetFile = resolved;
-    exportedName = imported.exportedName;
-  } else {
-    // Same-file urls() definition
-    targetFile = realPath;
-    exportedName = extraction.name;
   }
-
-  buildCombinedRouteMapWithSearch(
-    targetFile,
-    exportedName,
-    new Set(),
-    diagnostics,
-  );
   return diagnostics;
 }
 

package/src/build/runtime-discovery.ts

@@ -5,6 +5,7 @@ import {
   genFileTsPath,
   resolveSearchSchemas,
 } from "./generate-route-types.ts";
+import { mergeFullManifests } from "./merge-full-manifests.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
 export interface RuntimeDiscoveryOptions {
@@ -126,24 +127,34 @@ export async function discoverAndWriteRouteTypes(
 
     // Import build utilities for manifest generation
     const buildMod = await rscEnv.runner.import("@rangojs/router/build");
-    const generateManifest = buildMod.generateManifest;
+    const generateManifestFull = buildMod.generateManifestFull;
 
-    if (!generateManifest) {
-      throw new Error("generateManifest not found in @rangojs/router/build");
+    if (!generateManifestFull) {
+      throw new Error(
+        "generateManifestFull not found in @rangojs/router/build",
+      );
     }
 
     const outputFiles: string[] = [];
     let totalRouteCount = 0;
-    let routerMountIndex = 0;
+    let globalMountIndex = 0;
+    let routerCount = 0;
 
     for (const [id, router] of registry) {
-      if (!router.urlpatterns) continue;
-
-      const manifest = await generateManifest(
-        router.urlpatterns,
-        routerMountIndex,
-      );
-      routerMountIndex++;
+      const mounts =
+        router.__urlpatternMounts ??
+        (router.urlpatterns ? [{ patterns: router.urlpatterns }] : []);
+      if (mounts.length === 0) continue;
+
+      const mountManifests = [];
+      for (const mount of mounts) {
+        mountManifests.push(
+          await generateManifestFull(mount.patterns, globalMountIndex),
+        );
+        globalMountIndex++;
+      }
+      const manifest = mergeFullManifests(mountManifests);
+      routerCount++;
 
       // Filter out auto-generated route names that the runtime creates for
       // unnamed routes (path() with no name option). These get names like
@@ -211,7 +222,7 @@ export async function discoverAndWriteRouteTypes(
     }
 
     return {
-      routerCount: routerMountIndex,
+      routerCount,
       routeCount: totalRouteCount,
       outputFiles,
     };

package/src/cache/cache-exec-scope.ts

@@ -0,0 +1,47 @@
+/**
+ * Execution-chain scope for "use cache" function bodies.
+ *
+ * The ambient guards (cookies(), headers(), ctx.set() reached via
+ * getRequestContext()) must fire for code running INSIDE a cached body and
+ * stay silent for everything else on the request. A property stamped on the
+ * shared RequestContext cannot express that: while a slow "use cache" body is
+ * in flight, every parallel read on the same request sees the stamp. Scar: a
+ * 2s cached product fetch running beside a sibling loader made the loader's
+ * cookies() read throw `cannot be called inside a "use cache" function` —
+ * same shared-object hazard as issue #684 plan 010, which fixed only the
+ * background-revalidation path. AsyncLocalStorage follows the cached body's
+ * own async chain, so parallel work is invisible to the guard while genuine
+ * in-body reads still throw.
+ *
+ * Deliberately NOT entered on the store-less bypass paths in cache-runtime.ts:
+ * there the body executes for real on every call, side effects take effect,
+ * and request-scoped reads are safe (see the bypass comments there).
+ *
+ * Kept separate from taint.ts so `node:async_hooks` stays out of that module —
+ * taint.ts is reachable from browser-bundled DSL helpers. The probe
+ * registration below wires assertNotInsideCacheExec to this scope without
+ * taint.ts importing it.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { _setCacheExecScopeProbe } from "./taint.js";
+
+const cacheExecStorage = new AsyncLocalStorage<true>();
+
+/**
+ * Run fn with the "use cache" execution scope active. Continuations spawned
+ * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ */
+export function runWithCacheExecScope<T>(fn: () => T): T {
+  return cacheExecStorage.run(true, fn);
+}
+
+/** True when the calling async chain is inside a "use cache" body. */
+export function isInsideCacheExecScope(): boolean {
+  return cacheExecStorage.getStore() === true;
+}
+
+// Wire the ambient ctx-method guards (assertNotInsideCacheExec in taint.ts)
+// to this scope. Module-init registration cannot be missed: exec scopes only
+// exist once cache-runtime.ts (which imports this module) is loaded.
+_setCacheExecScopeProbe(isInsideCacheExecScope);