@rangojs/router 0.0.0-experimental.0b82333f

package/src/build/runtime-discovery.ts

@@ -0,0 +1,231 @@
+import { dirname, join, basename, resolve } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+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). */
+  root: string;
+  /** Path to vite.config.ts. Auto-detected from root if omitted. */
+  configFile?: string;
+  /** Absolute path to the router entry file. */
+  entry: string;
+  /** Override resolve.alias (skips loading from vite config when provided). */
+  resolveAlias?: Record<string, string>;
+}
+
+/**
+ * Standalone Vite-based route discovery for the CLI.
+ * Creates a temporary Vite server with the RSC plugin, imports the entry via
+ * the module runner, reads the RouterRegistry, generates manifests, and writes
+ * named-routes.gen.ts files.
+ *
+ * This mirrors the logic in the Vite plugin's discoverRouters() + writeRouteTypesFiles()
+ * but without coupling to plugin closure state.
+ */
+export async function discoverAndWriteRouteTypes(
+  opts: RuntimeDiscoveryOptions,
+): Promise<{
+  routerCount: number;
+  routeCount: number;
+  outputFiles: string[];
+}> {
+  let createViteServer: typeof import("vite").createServer;
+  let loadConfigFromFile: typeof import("vite").loadConfigFromFile;
+  let rsc: any;
+
+  try {
+    const vite = await import("vite");
+    createViteServer = vite.createServer;
+    loadConfigFromFile = vite.loadConfigFromFile;
+  } catch {
+    throw new Error(
+      "Runtime discovery requires 'vite'. Install it with: pnpm add -D vite",
+    );
+  }
+
+  try {
+    const rscMod = await import("@vitejs/plugin-rsc");
+    rsc = rscMod.default;
+  } catch {
+    throw new Error(
+      "Runtime discovery requires '@vitejs/plugin-rsc'. Install it with: pnpm add -D @vitejs/plugin-rsc",
+    );
+  }
+
+  const { createVersionPlugin } =
+    await import("../vite/plugins/version-plugin.ts");
+  const { createVirtualStubPlugin } =
+    await import("../vite/plugins/virtual-stub-plugin.ts");
+
+  // Load user's vite config to get resolve.alias (unless provided directly)
+  let userResolveAlias: any = opts.resolveAlias;
+  if (!userResolveAlias) {
+    const configPath = opts.configFile;
+    try {
+      const loaded = await loadConfigFromFile(
+        { command: "serve", mode: "development" },
+        configPath,
+        opts.root,
+      );
+      if (loaded?.config?.resolve?.alias) {
+        userResolveAlias = loaded.config.resolve.alias;
+      }
+    } catch {
+      // Config loading failed; proceed without aliases
+    }
+  }
+
+  const entryPath = resolve(opts.entry);
+  let tempServer: any = null;
+
+  try {
+    tempServer = await createViteServer({
+      root: opts.root,
+      configFile: false,
+      server: { middlewareMode: true },
+      appType: "custom",
+      logLevel: "silent",
+      cacheDir: "node_modules/.vite_rango_generate",
+      resolve: userResolveAlias ? { alias: userResolveAlias } : undefined,
+      esbuild: { jsx: "automatic", jsxImportSource: "react" },
+      plugins: [
+        rsc({
+          entries: {
+            client: "virtual:entry-client",
+            ssr: "virtual:entry-ssr",
+            rsc: entryPath,
+          },
+        }),
+        createVersionPlugin(),
+        createVirtualStubPlugin(),
+      ],
+    });
+
+    const rscEnv = (tempServer.environments as any)?.rsc;
+    if (!rscEnv?.runner) {
+      throw new Error("RSC environment runner not available");
+    }
+
+    // Import the entry to trigger createRouter() registration
+    await rscEnv.runner.import(entryPath);
+
+    // Read the RouterRegistry
+    const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+    const registry: Map<string, any> = serverMod.RouterRegistry;
+
+    if (!registry || registry.size === 0) {
+      throw new Error(
+        `No routers found in registry after importing ${opts.entry}`,
+      );
+    }
+
+    // Import build utilities for manifest generation
+    const buildMod = await rscEnv.runner.import("@rangojs/router/build");
+    const generateManifest = buildMod.generateManifest;
+
+    if (!generateManifest) {
+      throw new Error("generateManifest not found in @rangojs/router/build");
+    }
+
+    const outputFiles: string[] = [];
+    let totalRouteCount = 0;
+    let routerMountIndex = 0;
+
+    for (const [id, router] of registry) {
+      if (!router.urlpatterns) continue;
+
+      const manifest = generateManifest(router.urlpatterns, routerMountIndex);
+      routerMountIndex++;
+
+      // 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;
+
+      // Determine output location from __sourceFile
+      const sourceFile: string | undefined = router.__sourceFile;
+      if (!sourceFile) {
+        console.warn(
+          `[rango] Router "${id}" has no __sourceFile, skipping gen file`,
+        );
+        continue;
+      }
+
+      // Guard against writing gen files into node_modules
+      if (sourceFile.includes("node_modules")) {
+        throw new Error(
+          `[rango] Router "${id}" has sourceFile inside node_modules: ${sourceFile}\n` +
+            `This means createRouter() stack trace parsing matched an internal frame.\n` +
+            `Set an explicit \`id\` on createRouter() or check the call site.`,
+        );
+      }
+
+      // Search schema fallback: runtime manifest may omit search schema metadata
+      // in some module-runner flows. Fall back to static source parsing.
+      if (!routeSearchSchemas || Object.keys(routeSearchSchemas).length === 0) {
+        const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+        if (Object.keys(staticParsed.searchSchemas).length > 0) {
+          const filtered: Record<string, Record<string, string>> = {};
+          for (const name of Object.keys(routeManifest)) {
+            const schema = staticParsed.searchSchemas[name];
+            if (schema) filtered[name] = schema;
+          }
+          if (Object.keys(filtered).length > 0) {
+            routeSearchSchemas = filtered;
+          }
+        }
+      }
+
+      const routerDir = dirname(sourceFile);
+      const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+      const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+
+      const source = generateRouteTypesSource(
+        routeManifest,
+        routeSearchSchemas && Object.keys(routeSearchSchemas).length > 0
+          ? routeSearchSchemas
+          : undefined,
+      );
+
+      const existing = existsSync(outPath)
+        ? readFileSync(outPath, "utf-8")
+        : null;
+      if (existing !== source) {
+        writeFileSync(outPath, source);
+      }
+
+      const routeCount = Object.keys(routeManifest).length;
+      totalRouteCount += routeCount;
+      outputFiles.push(outPath);
+
+      console.log(
+        `[rango] Generated route types (${routeCount} routes) -> ${outPath}`,
+      );
+    }
+
+    return {
+      routerCount: routerMountIndex,
+      routeCount: totalRouteCount,
+      outputFiles,
+    };
+  } finally {
+    if (tempServer) {
+      await tempServer.close();
+    }
+  }
+}

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;
+}