@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

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-error.ts

@@ -0,0 +1,104 @@
+/**
+ * Cache error reporting.
+ *
+ * Caches are best-effort: a read failure degrades to a miss (render fresh) and a
+ * write failure degrades to a no-op - they MUST NOT throw up and fail the
+ * request. But the failure must still be LOUD: it is logged to the console (so
+ * it is visible even in a background waitUntil task or when no hook is wired)
+ * AND routed through the router's onError callback (via the request context's
+ * deduped _reportBackgroundError) so consumers can observe cache degradation in
+ * their own telemetry.
+ *
+ * The one deliberate exception is the invalidation WRITE verb (updateTag ->
+ * store.invalidateTags): a failed durable marker write is rejected so an awaited
+ * updateTag() surfaces it (read-your-own-writes honesty). That is not a data
+ * read/write and does not go through this helper's swallow-and-degrade path.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+
+/**
+ * Minimal shape of a request context for error reporting. Passed explicitly by
+ * background tasks (waitUntil) where the ALS context is already gone, so the
+ * error can still reach the router's onError. Structural to avoid importing the
+ * full RequestContext type (request-context.ts imports CacheErrorCategory from
+ * here - a mutual type-only reference).
+ */
+export interface CacheErrorReporter {
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
+}
+
+export type CacheErrorCategory =
+  /** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */
+  | "cache-read"
+  /** A write failed. Degrade to a no-op (entry simply not cached). */
+  | "cache-write"
+  /** A delete/eviction failed. Best-effort. */
+  | "cache-delete"
+  /**
+   * A STORED entry could not be parsed/deserialized (partial KV read, truncated
+   * Cache API body, malformed envelope/RSC payload). The entry is faulty and is
+   * evicted so subsequent reads do not keep failing on it. Distinct from
+   * cache-read so consumers can tell corruption from a transient outage.
+   */
+  | "cache-corrupt"
+  /** A tag-invalidation side effect failed (e.g. the eager CDN purge hook). */
+  | "cache-invalidate"
+  /**
+   * A background stale-while-revalidate refresh failed (the `"use cache"`
+   * read-through path). The stale value was already served; the refresh that
+   * would have replaced it errored.
+   */
+  | "stale-revalidation";
+
+/**
+ * Report a non-fatal cache error loudly without failing the request: always logs
+ * (label + error) and, when a request context is available, routes the error
+ * through the router's onError callback. Never throws.
+ *
+ * `ctx` is for callers running in a detached background task (waitUntil), where
+ * the ALS request context is already gone (so `_getRequestContext()` is null):
+ * they capture the context up front and pass it here so onError still fires.
+ * Foreground callers omit it and fall back to the ALS context.
+ */
+export function reportCacheError(
+  error: unknown,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): void {
+  console.error(`${label}:`, error);
+  try {
+    const target = ctx ?? _getRequestContext();
+    target?._reportBackgroundError?.(error, category);
+  } catch {
+    // Reporting must never itself break the cache path.
+  }
+}
+
+/**
+ * Run a best-effort async cache task (typically scheduled via waitUntil), catching
+ * any rejection and routing it through reportCacheError so background cache work
+ * (non-blocking L1 writes, KV persistence, L1 promotion) reports failures via
+ * onError instead of throwing or silently swallowing. Never rejects.
+ *
+ * Pass `ctx` when the task runs detached (the ALS context is gone) and the
+ * failure should still reach onError; omit it to fall back to the ALS context.
+ *
+ * @example this.waitUntil(() => reportingAsync(() => cache.put(req, res), "cache-write", "[CFCacheStore] L1 write"))
+ */
+export async function reportingAsync(
+  task: () => Promise<unknown>,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): Promise<void> {
+  try {
+    await task();
+  } catch (error) {
+    reportCacheError(error, category, label, ctx);
+  }
+}

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("&");
+}