@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.19

package/src/build/route-types/codegen.ts

@@ -2,6 +2,7 @@ import {
   extractParamsFromPattern,
   formatRouteEntry,
 } from "./param-extraction.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
 
 // ---------------------------------------------------------------------------
 // Code generation
@@ -66,15 +67,23 @@ export function generateRouteTypesSource(
   routeManifest: Record<string, string>,
   searchSchemas?: Record<string, Record<string, string>>,
 ): string {
-  const entries = Object.entries(routeManifest).sort(([a], [b]) =>
-    a.localeCompare(b),
-  );
+  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 = searchSchemas?.[name];
+      const search = filteredSearchSchemas?.[name];
       return formatRouteEntry(key, pattern, params, search);
     })
     .join("\n");

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

@@ -325,6 +325,13 @@ function buildRouteMapFromBlock(
       );
     }
 
+    // Includes without a name keep their child names private to the mounted
+    // module. They remain active at runtime via an internal scope prefix, but
+    // they are intentionally omitted from generated public route maps.
+    if (namePrefix === null) {
+      continue;
+    }
+
     // Apply prefixes
     for (const [name, pattern] of Object.entries(childResult.routes)) {
       const prefixedName = namePrefix ? `${namePrefix}.${name}` : name;
@@ -394,5 +401,11 @@ export function buildCombinedRouteMapWithSearch(
     searchSchemas,
     diagnosticsOut,
   );
+
+  // Remove from visited so sibling branches can include the same variable
+  // without false circular-include detection. Only ancestors in the current
+  // recursion path should trigger the cycle guard.
+  visited.delete(key);
+
   return { routes, searchSchemas };
 }

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

@@ -26,7 +26,7 @@ export function writePerModuleRouteTypes(
  * Find all variable names assigned to urls() calls in source code.
  * e.g. `export const patterns = urls(...)` -> ["patterns"]
  */
-function findUrlsVariableNames(code: string): string[] {
+export function findUrlsVariableNames(code: string): string[] {
   const sourceFile = ts.createSourceFile(
     "input.tsx",
     code,
@@ -97,9 +97,21 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       routes = extractRoutesFromSource(source);
     }
 
-    if (routes.length === 0) return;
-
     const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+
+    // When a urls() variable was found but static resolution yields zero
+    // routes, write an empty placeholder so generated imports stay
+    // resolvable until runtime discovery fills them in.
+    if (routes.length === 0) {
+      if (varNames.length > 0 && !existsSync(genPath)) {
+        writeFileSync(genPath, generatePerModuleTypesSource([]));
+        console.log(
+          `[rsc-router] Generated route types (placeholder) -> ${genPath}`,
+        );
+      }
+      return;
+    }
+
     const genSource = generatePerModuleTypesSource(routes);
     const existing = existsSync(genPath)
       ? readFileSync(genPath, "utf-8")

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

@@ -10,6 +10,21 @@ import {
   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;
+}
 
 // ---------------------------------------------------------------------------
 // Router file URL extraction
@@ -184,6 +199,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
 // ---------------------------------------------------------------------------
@@ -300,10 +342,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();
+  }
+}

package/src/cache/cache-key-utils.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared Cache Key Utilities
+ *
+ * Deterministic normalization of search params and route params
+ * for cache key generation. Used by cache-runtime, cache-scope,
+ * document-cache, and loader-cache.
+ */
+
+/**
+ * Build a sorted, deterministic query string from URLSearchParams,
+ * excluding internal _rsc* and __* params.
+ *
+ * Returns empty string when no user-facing params exist.
+ */
+export function sortedSearchString(searchParams: URLSearchParams): string {
+  const pairs: [string, string][] = [];
+  for (const [k, v] of searchParams) {
+    if (!k.startsWith("_rsc") && !k.startsWith("__")) {
+      pairs.push([k, v]);
+    }
+  }
+  if (pairs.length === 0) return "";
+  pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return pairs
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}
+
+/**
+ * Build a sorted, deterministic string from route params.
+ *
+ * Returns empty string when params is empty or undefined.
+ */
+export function sortedRouteParams(
+  params: Record<string, string> | undefined,
+): string {
+  if (!params) return "";
+  const entries = Object.entries(params);
+  if (entries.length === 0) return "";
+  return entries
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+    .join("&");
+}

package/src/cache/cache-policy.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared Cache Policy Utilities
+ *
+ * Resolution cascades for TTL, SWR, cache key, and cache store.
+ * Consolidates the multi-tier resolution pattern:
+ *   explicit option → store defaults → fallback constant
+ */
+
+import type { CacheDefaults, SegmentCacheStore } from "./types.js";
+import { _getRequestContext } from "../server/request-context.js";
+import type { RequestContext } from "../server/request-context.js";
+
+/**
+ * Default TTL for route-level cache() DSL and loader cache.
+ * Applied when neither the cache options nor the store defaults specify a TTL.
+ */
+export const DEFAULT_ROUTE_TTL = 60;
+
+/**
+ * Default TTL for function-level "use cache" (setItem).
+ * Applied when neither the item options nor the store defaults specify a TTL.
+ */
+export const DEFAULT_FUNCTION_TTL = 900;
+
+/**
+ * Resolve effective TTL from the 3-tier cascade:
+ * explicit → store defaults → fallback.
+ */
+export function resolveTtl(
+  explicit: number | undefined,
+  defaults: CacheDefaults | undefined,
+  fallback: number,
+): number {
+  if (explicit !== undefined) return explicit;
+  if (defaults?.ttl !== undefined) return defaults.ttl;
+  return fallback;
+}
+
+/**
+ * Resolve effective SWR window from the 2-tier cascade:
+ * explicit → store defaults.
+ * Returns 0 when unset (no SWR window).
+ */
+export function resolveSwrWindow(
+  explicit: number | undefined,
+  defaults: CacheDefaults | undefined,
+): number {
+  if (explicit !== undefined) return explicit;
+  if (defaults?.swr !== undefined) return defaults.swr;
+  return 0;
+}
+
+/**
+ * Compute staleAt and expiresAt timestamps from TTL and SWR window.
+ *
+ * - staleAt: when the entry becomes stale (TTL boundary)
+ * - expiresAt: when the entry should be evicted (TTL + SWR)
+ *
+ * When swrWindow is 0, staleAt === expiresAt (no SWR).
+ */
+export function computeExpiration(
+  ttlSeconds: number,
+  swrSeconds: number = 0,
+): { staleAt: number; expiresAt: number } {
+  const now = Date.now();
+  const staleAt = now + ttlSeconds * 1000;
+  const expiresAt = staleAt + swrSeconds * 1000;
+  return { staleAt, expiresAt };
+}
+
+// ============================================================================
+// Cache Key Resolution
+// ============================================================================
+
+/**
+ * Resolve cache key using the 3-tier priority:
+ * 1. keyFn (full override from route/loader cache options)
+ * 2. store.keyGenerator (modifies default key)
+ * 3. defaultKey (used when neither keyFn nor keyGenerator is provided)
+ *
+ * Errors from keyFn and store.keyGenerator propagate to the caller.
+ * Cache identity is correctness-critical: if explicit key logic throws,
+ * silently remapping to a different key could cause cache collisions or
+ * serve stale/wrong data. Callers must handle the error or let it surface.
+ *
+ * Uses _getRequestContext (non-throwing) so that calls outside ALS
+ * (e.g. build-time) gracefully fall back to defaultKey.
+ */
+export async function resolveCacheKey(
+  keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
+  store: SegmentCacheStore | null,
+  defaultKey: string,
+  _label: string,
+): Promise<string> {
+  const requestCtx = _getRequestContext();
+
+  // Priority 1: Route/loader-level key function (full override)
+  if (keyFn && requestCtx) {
+    return await keyFn(requestCtx);
+  }
+
+  // Priority 2: Store-level keyGenerator (modifies default key)
+  if (store?.keyGenerator && requestCtx) {
+    return await store.keyGenerator(requestCtx, defaultKey);
+  }
+
+  // Priority 3: Default key (no custom key logic provided)
+  return defaultKey;
+}
+
+// ============================================================================
+// Cache Store Resolution
+// ============================================================================
+
+/**
+ * Resolve cache store from the 2-tier priority:
+ * 1. Explicit store from cache options
+ * 2. App-level store from request context
+ */
+export function resolveCacheStore(
+  explicitStore: SegmentCacheStore | undefined,
+): SegmentCacheStore | null {
+  if (explicitStore) return explicitStore;
+  return _getRequestContext()?._cacheStore ?? null;
+}