@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

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

@@ -0,0 +1,85 @@
+import { join, relative } from "node:path";
+import { readdirSync } from "node:fs";
+// @ts-ignore -- picomatch ships no .d.ts; types are trivial
+import picomatch from "picomatch";
+
+/** Default exclude patterns for route type scanning. */
+export const DEFAULT_EXCLUDE_PATTERNS: string[] = [
+  "**/__tests__/**",
+  "**/__mocks__/**",
+  "**/dist/**",
+  "**/coverage/**",
+  "**/*.test.{ts,tsx,js,jsx}",
+  "**/*.spec.{ts,tsx,js,jsx}",
+];
+
+export type ScanFilter = (absolutePath: string) => boolean;
+
+/**
+ * Compile include/exclude glob patterns into a single predicate.
+ * Paths are made root-relative before matching.
+ * Returns undefined when no filtering is needed (no include, default exclude).
+ */
+export function createScanFilter(
+  root: string,
+  opts: { include?: string[]; exclude?: string[] },
+): ScanFilter | undefined {
+  const { include, exclude } = opts;
+  const hasInclude = include && include.length > 0;
+  const hasCustomExclude = exclude !== undefined;
+
+  if (!hasInclude && !hasCustomExclude) return undefined;
+
+  const effectiveExclude = exclude ?? DEFAULT_EXCLUDE_PATTERNS;
+  const includeMatcher = hasInclude ? picomatch(include) : null;
+  const excludeMatcher =
+    effectiveExclude.length > 0 ? picomatch(effectiveExclude) : null;
+
+  return (absolutePath: string) => {
+    const rel = relative(root, absolutePath);
+    if (excludeMatcher && excludeMatcher(rel)) return false;
+    if (includeMatcher) return includeMatcher(rel);
+    return true;
+  };
+}
+
+/**
+ * Recursively find .ts/.tsx files under a directory, skipping node_modules
+ * and .gen. files.
+ */
+export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
+  const results: string[] = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
+    );
+    return results;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      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") ||
+        entry.name.endsWith(".tsx") ||
+        entry.name.endsWith(".js") ||
+        entry.name.endsWith(".jsx")) &&
+      !entry.name.includes(".gen.")
+    ) {
+      if (filter && !filter(fullPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}

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

@@ -0,0 +1,118 @@
+// Allocation-light, linear-time source scanning for the build-time scanners.
+//
+// The router-file scanner, the HMR relevance check, and the unsupported-shape
+// warning all need to know whether a token like `createRouter(` / `createLoader(`
+// appears in REAL code versus inside a comment or string literal. Rather than
+// build a full comment/string-stripped copy of the source (which on a large
+// file allocates an O(n) string plus, naively, a per-char array), these helpers
+// run the regex over the whole source ONCE (the engine sweeps left-to-right,
+// O(n)) and classify each match's offset with a forward, O(1)-memory cursor that
+// advances monotonically across the source.
+//
+// Time: O(n) — one native regex sweep plus one forward classification pass.
+// Memory: O(1) for the boolean check; O(#matches) for the index list. No
+// stripped copy and no per-char array are ever materialized.
+//
+// Pragmatic scanner, not a full tokenizer: regex literals are not special-cased
+// (a target token inside one is implausible) and template interpolations are
+// treated as opaque string content. One intentional consequence: a token whose
+// match would only complete by treating an interleaved comment as whitespace
+// (e.g. `createRouter /* x */ (`) is not detected — real calls never interleave
+// a comment between the callee and its arguments.
+
+// JS line terminators end a `//` comment: LF, CR, LS (U+2028), PS (U+2029).
+function isLineTerminator(ch: string): boolean {
+  const c = ch.charCodeAt(0);
+  // LF, CR, LS (U+2028), PS (U+2029)
+  return c === 10 || c === 13 || c === 0x2028 || c === 0x2029;
+}
+
+/**
+ * Build a classifier that answers "is offset `q` in code (not a comment or
+ * string)?" for STRICTLY INCREASING `q`. The internal cursor only moves forward,
+ * so a full left-to-right sequence of queries costs O(n) total with O(1) memory.
+ */
+function makeCodeClassifier(code: string): (q: number) => boolean {
+  const n = code.length;
+  let i = 0; // forward cursor: everything before `i` is already classified
+  let skipStart = -1; // last detected comment/string region (cache)
+  let skipEnd = -1;
+
+  return (q: number): boolean => {
+    if (q >= skipStart && q < skipEnd) return false; // q in the cached region
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        // Comment/string region [i, end). `q >= i` here (loop condition).
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true; // reached q in code mode
+  };
+}
+
+/**
+ * Index of the first match of `pattern` that occurs in code (not in a comment
+ * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
+ * regex sweep with early-exit; O(1) extra memory.
+ */
+export function firstCodeMatchIndex(code: string, pattern: RegExp): number {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+
+/**
+ * Byte offsets of every match of `pattern` that occurs in code (not in a
+ * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
+ * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
+ * time, O(#matches) memory.
+ */
+export function codeMatchIndices(code: string, pattern: RegExp): number[] {
+  const inCode = makeCodeClassifier(code);
+  const indices: number[] = [];
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}

package/src/build/runtime-discovery.ts

@@ -0,0 +1,220 @@
+import { resolve } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  generateRouteTypesSource,
+  genFileTsPath,
+  resolveSearchSchemas,
+} 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.`,
+        );
+      }
+
+      routeSearchSchemas = resolveSearchSchemas(
+        Object.keys(routeManifest),
+        routeSearchSchemas,
+        sourceFile,
+      );
+
+      const outPath = genFileTsPath(sourceFile);
+
+      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;
+}