@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/skills/use-cache/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: use-cache
+description: Function-level caching with "use cache" directive for RSC data functions and components
+argument-hint: [profile-name]
+---
+
+# "use cache" Directive
+
+Function-level caching for async server functions and RSC components. Caches
+return values with TTL + stale-while-revalidate. Complementary to the route-level
+`cache()` DSL and build-time `Static()`/`Prerender()`.
+
+## Basic Usage
+
+### File-level (all exports cached with default profile)
+
+```typescript
+"use cache";
+
+export async function getProducts() {
+  return await db.query("SELECT * FROM products");
+}
+
+export async function getCategories() {
+  return await db.query("SELECT * FROM categories");
+}
+```
+
+### Function-level (per-function profile)
+
+```typescript
+export async function getProducts() {
+  "use cache: short";
+  return await db.query("SELECT * FROM products");
+}
+
+export async function getCategories() {
+  "use cache: long";
+  return await db.query("SELECT * FROM categories");
+}
+```
+
+### RSC component
+
+```typescript
+export async function ProductCard({ id }: { id: string }) {
+  "use cache: products"
+  const product = await db.query('SELECT * FROM products WHERE id = ?', [id]);
+  return <div>{product.name}</div>;
+}
+```
+
+## Named Cache Profiles
+
+Define profiles in createRouter. Profile names map to `"use cache: <name>"` and
+`cache('<name>')` in the DSL.
+
+```typescript
+createRouter({
+  cacheProfiles: {
+    default: { ttl: 900, swr: 1800 },
+    short: { ttl: 60, swr: 120 },
+    long: { ttl: 3600, swr: 7200 },
+    products: { ttl: 300, swr: 600, tags: ["products"] },
+  },
+});
+```
+
+- `"use cache"` (no name) resolves to `default`.
+- `"use cache: short"` resolves to the `short` profile.
+- Unknown profile names throw at build/boot time.
+
+## Cache Key
+
+```
+use-cache:{functionId}:{serializedArgs}
+```
+
+- `functionId` -- stable ID from Vite transform (module path + export name).
+- `serializedArgs` -- non-tainted arguments serialized via RSC `encodeReply()`.
+
+Different functions always produce different cache keys, even for the same route.
+This is important for intercepted routes -- the path handler and intercept handler
+each have their own `functionId` and therefore their own cache entries.
+
+## Tainted Arguments (ctx, env, req)
+
+Request-scoped objects are branded with `Symbol.for('rango:nocache')` at creation.
+When detected:
+
+1. **Excluded from cache key** -- request-scoped, not meaningful for keying.
+2. **Handle data captured on miss** -- side effects via `ctx.use(Handle)` are recorded.
+3. **Handle data replayed on hit** -- restored into the current request's HandleStore.
+
+```typescript
+export async function getProductData(ctx) {
+  "use cache: short";
+  const breadcrumb = ctx.use(Breadcrumbs);
+  breadcrumb({ label: "Products", href: "/products" });
+  return await db.query("SELECT * FROM products");
+}
+// On hit: return value restored, breadcrumb replayed.
+```
+
+## Request-Scoped Guards
+
+### Read Guards
+
+`cookies()` and `headers()` **throw** inside a `"use cache"` function because
+per-request values (cookies, headers) are not reflected in the cache key. Without
+this guard, one user's data would be served to another.
+
+Extract the value before the cached function and pass it as an argument:
+
+```typescript
+const locale = cookies().get("locale")?.value ?? "en";
+const data = await getCachedData(locale); // locale is now in the cache key
+```
+
+### Side-Effect Guards
+
+These ctx methods **throw** inside a `"use cache"` function because their effects
+are lost on cache hit (the function body is skipped):
+
+- `ctx.set()` / `ctx.get()` for passing values to children
+- `ctx.header()`
+- `ctx.setTheme()`
+- `ctx.setLocationState()`
+- `ctx.onResponse()`
+
+The error message recommends two alternatives:
+
+1. Extract the data fetch into a separate cached function and call ctx methods outside it.
+2. Use the route-level `cache()` DSL which caches all segments together.
+
+**`ctx.use(Handle)` is NOT guarded** -- handle push is captured on miss and replayed
+on hit. This is the correct way to pass data from cached functions.
+
+### Pattern: Separate cached function from ctx side effects
+
+```typescript
+// Cached data fetch (pure)
+async function getNavData() {
+  "use cache: short"
+  return await db.query('SELECT * FROM nav_items');
+}
+
+// Handler (uncached, calls ctx methods freely)
+async function NavLayout(ctx) {
+  const navData = await getNavData();
+  ctx.set("navItems", navData);  // Works -- outside "use cache"
+  return <Nav items={navData}><Outlet /></Nav>;
+}
+```
+
+## Misuse Guards
+
+### Cannot use as middleware
+
+Cached functions cannot be passed to `middleware()`. Middleware runs on every
+request (onion model) and must not be cached.
+
+```typescript
+// WRONG -- throws at boot time
+middleware(cachedFn);
+
+// RIGHT -- call cached function inside middleware
+middleware(async (ctx, next) => {
+  const data = await getCachedData();
+  ctx.set("data", data);
+  await next();
+});
+```
+
+### Cannot use as Static() handler
+
+Static handlers render once at build time. `"use cache"` is redundant.
+
+```typescript
+// WRONG -- throws at boot time
+export const Page = Static(cachedFn);
+
+// RIGHT -- remove "use cache", Static already caches
+export const Page = Static(async (ctx) => {
+  return <div>Built once</div>;
+});
+```
+
+### Cannot use as Prerender() handler or getParams
+
+Prerender handlers render at build time. `"use cache"` is redundant.
+
+```typescript
+// WRONG -- throws at boot time (handler)
+export const Page = Prerender(getParams, cachedFn);
+
+// WRONG -- throws at boot time (getParams)
+export const Page = Prerender(cachedGetParams, handler);
+
+// RIGHT -- remove "use cache"
+export const Page = Prerender(
+  async () => [{ slug: "a" }],
+  async (ctx) => <Page slug={ctx.params.slug} />,
+);
+```
+
+## Performance: waitUntil
+
+On cache miss, the function executes and the result is serialized inline (blocking).
+The cache **store write** (`setItem`) is deferred to `waitUntil` and does NOT block
+the response.
+
+On stale hit, stale data is returned immediately. Background revalidation (re-execute
+
+- store) runs entirely inside `waitUntil`.
+
+| Phase                                | Blocks response? |
+| ------------------------------------ | ---------------- |
+| Function execution (miss)            | Yes              |
+| Result serialization (miss)          | Yes              |
+| Cache store write (miss)             | No (waitUntil)   |
+| Stale value return (stale hit)       | No (immediate)   |
+| Background revalidation (stale)      | No (waitUntil)   |
+| Cache lookup + deserialization (hit) | Yes (fast)       |
+
+## Using with Loaders
+
+`"use cache"` works inside loaders. The loader runs every request, but the inner
+cached function returns cached data:
+
+```typescript
+// Cached data function
+export async function getProductData(slug: string) {
+  "use cache";
+  return await db.query("SELECT * FROM products WHERE slug = ?", [slug]);
+}
+
+// Loader runs every request, but inner call is cached
+export const ProductLoader = createLoader(async (ctx) => {
+  return getProductData(ctx.params.slug);
+});
+```
+
+## Using with Intercepted Routes
+
+Path handlers and intercept handlers have different `functionId` values from the
+Vite transform, so they naturally get distinct cache entries even for the same URL:
+
+```typescript
+// Path handler -- cached separately
+path("/product/:id", async (ctx) => {
+  "use cache"
+  return <FullProductPage id={ctx.params.id} />;
+}),
+
+// Intercept handler -- cached separately (different functionId)
+intercept("@modal", ".product", async (ctx) => {
+  "use cache"
+  return <ProductModal id={ctx.params.id} />;
+}),
+```
+
+## Vite Transform
+
+The `rango:use-cache` Vite plugin detects the directive and wraps exports with
+`registerCachedFunction()`:
+
+```typescript
+// Input
+"use cache"
+export async function getProducts() { ... }
+
+// Output
+import { registerCachedFunction } from '@rangojs/router/cache-runtime';
+export const getProducts = registerCachedFunction(
+  async function getProducts() { ... },
+  "src/data/products.ts#getProducts",
+  "default"
+);
+```
+
+Function-level directives are hoisted:
+
+```typescript
+// Input
+export async function getProducts() {
+  "use cache: short";
+  return await db.query("...");
+}
+
+// Output
+const __rango_cached_getProducts = registerCachedFunction(
+  async function getProducts() {
+    return await db.query("...");
+  },
+  "src/data/products.ts#getProducts",
+  "short",
+);
+export async function getProducts() {
+  return __rango_cached_getProducts();
+}
+```
+
+## Backing Store
+
+Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
+One store, one configuration, one invalidation API. Tag-based invalidation
+(`revalidateTag`) works across all mechanisms.
+
+## Interaction with Other Caching
+
+| Mechanism          | Granularity        | When       | Use case                                        |
+| ------------------ | ------------------ | ---------- | ----------------------------------------------- |
+| `"use cache"`      | Function/component | Runtime    | Cache individual data fetches or components     |
+| `cache()` DSL      | Route segment      | Runtime    | Cache entire route subtrees with children       |
+| `cache('profile')` | Route segment      | Runtime    | Same as cache() with a named profile            |
+| `Static()`         | Route segment      | Build-time | Render once, never re-render                    |
+| `Prerender()`      | Route segment      | Build-time | Pre-render known params, optional live fallback |
+
+## Dev Mode
+
+In development, the Vite transform still wraps functions, but the cache store is
+a `MemorySegmentCacheStore` that works locally. Functions cache normally in dev
+for testing cache behavior.

package/src/__internal.ts

@@ -108,7 +108,11 @@ export type {
  * @internal
  * Router context for AsyncLocalStorage.
  */
-export type { RouterContext, RevalidationContext, InterceptResult } from "./router/router-context.js";
+export type {
+  RouterContext,
+  RevalidationContext,
+  InterceptResult,
+} from "./router/router-context.js";
 
 // ============================================================================
 // Match Pipeline (Internal)
@@ -118,7 +122,10 @@ export type { RouterContext, RevalidationContext, InterceptResult } from "./rout
  * @internal
  * Route match context during pipeline processing.
  */
-export type { MatchContext, MatchPipelineState } from "./router/match-context.js";
+export type {
+  MatchContext,
+  MatchPipelineState,
+} from "./router/match-context.js";
 
 /**
  * @internal
@@ -153,7 +160,7 @@ export type {
 /**
  * @internal
  * Internal handler context with additional props for router internals.
- * Includes `_originalRequest` and `_currentSegmentId`.
+ * Includes `_currentSegmentId` and `_responseType`.
  */
 export type { InternalHandlerContext } from "./types.js";
 
@@ -172,4 +179,3 @@ export {
   type SerializedEntry,
   type SerializedManifest,
 } from "./debug.js";
-

package/src/bin/rango.ts

@@ -0,0 +1,321 @@
+import { resolve, dirname } from "node:path";
+import { readFileSync, statSync, existsSync } from "node:fs";
+import {
+  findTsFiles,
+  writePerModuleRouteTypesForFile,
+  writeCombinedRouteTypes,
+  detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
+  type UnresolvableInclude,
+} from "../build/generate-route-types.ts";
+
+const [command, ...rawArgs] = process.argv.slice(2);
+
+if (command === "generate") {
+  // Parse flags
+  let mode: "default" | "runtime" | "static" = "default";
+  let configFile: string | undefined;
+  const positionalArgs: string[] = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--runtime") {
+      mode = "runtime";
+    } else if (arg === "--static") {
+      mode = "static";
+    } else if (arg === "--config") {
+      configFile = rawArgs[++i];
+      if (!configFile) {
+        console.error("[rango] --config requires a path argument");
+        process.exit(1);
+      }
+    } else if (arg.startsWith("--")) {
+      console.error(`[rango] Unknown flag: ${arg}`);
+      process.exit(1);
+    } else {
+      positionalArgs.push(arg);
+    }
+  }
+
+  if (positionalArgs.length === 0) {
+    console.error(
+      "[rango] Usage: rango generate <file|dir> [file2 ...] [--runtime|--static] [--config <path>]",
+    );
+    process.exit(1);
+  }
+
+  if (configFile && mode !== "runtime") {
+    console.warn("[rango] --config is only used with --runtime, ignoring");
+  }
+
+  if (mode === "runtime") {
+    // Runtime discovery: dynamically import to avoid loading Vite for static-only usage
+    runRuntimeDiscovery(positionalArgs, configFile).catch((err) => {
+      console.error(`[rango] Runtime discovery failed: ${err.message}`);
+      process.exit(1);
+    });
+  } else {
+    runStaticGeneration(positionalArgs, mode);
+  }
+} else {
+  if (
+    command &&
+    command !== "help" &&
+    command !== "--help" &&
+    command !== "-h"
+  ) {
+    console.error(`[rango] Unknown command: ${command}\n`);
+  }
+  console.log(`Usage: rango generate <file|dir> [file2 ...] [--runtime|--static] [--config <path>]
+
+  Auto-detects file type (createRouter, urls) and generates
+  the appropriate .gen.ts route type files.
+
+Modes:
+  (default)   Static parser with error on unresolvable includes
+  --runtime   Vite-based runtime discovery (100% coverage)
+              Requires vite and @vitejs/plugin-rsc
+  --static    Static parser, accept partial output with warnings
+
+Options:
+  --config <path>  Path to vite.config.ts (--runtime only, auto-detected if omitted)
+
+Examples:
+  rango generate src/router.tsx
+  rango generate src/router.tsx --runtime
+  rango generate src/ --static`);
+  process.exit(
+    command && command !== "help" && command !== "--help" && command !== "-h"
+      ? 1
+      : 0,
+  );
+}
+
+/**
+ * Walk up from a file path to find the project root (directory containing
+ * package.json or vite.config.ts).
+ */
+function findProjectRoot(fromPath: string): string {
+  let dir = dirname(resolve(fromPath));
+  while (dir !== dirname(dir)) {
+    if (
+      existsSync(resolve(dir, "package.json")) ||
+      existsSync(resolve(dir, "vite.config.ts")) ||
+      existsSync(resolve(dir, "vite.config.js"))
+    ) {
+      return dir;
+    }
+    dir = dirname(dir);
+  }
+  // Fallback to cwd if no project root found
+  return process.cwd();
+}
+
+function runStaticGeneration(args: string[], mode: "default" | "static") {
+  // Expand args: files are used directly, directories are scanned
+  const files: string[] = [];
+  for (const arg of args) {
+    const resolved = resolve(arg);
+    try {
+      if (statSync(resolved).isDirectory()) {
+        files.push(...findTsFiles(resolved));
+      } else {
+        files.push(resolved);
+      }
+    } catch {
+      console.warn(`[rango] Skipping ${arg}: not found`);
+    }
+  }
+
+  if (files.length === 0) {
+    console.log("[rango] No files to process");
+    process.exit(0);
+  }
+
+  // Phase 1: Classify files
+  const routerFiles: string[] = [];
+  const urlsFiles: string[] = [];
+
+  for (const filePath of files) {
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        routerFiles.push(filePath);
+      }
+      if (source.includes("urls(")) {
+        urlsFiles.push(filePath);
+      }
+    } catch (err) {
+      console.warn(
+        `[rango] Failed to process ${filePath}: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  // Phase 2: Collect diagnostics from all files BEFORE writing anything
+  const allDiagnostics: Array<UnresolvableInclude & { routerFile: string }> =
+    [];
+
+  for (const routerFile of routerFiles) {
+    const diagnostics = detectUnresolvableIncludes(routerFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile });
+    }
+  }
+
+  // Also check standalone urls files not covered by router-level detection
+  const routerFileSet = new Set(routerFiles);
+  for (const urlsFile of urlsFiles) {
+    if (routerFileSet.has(urlsFile)) continue;
+    const diagnostics = detectUnresolvableIncludesForUrlsFile(urlsFile);
+    for (const d of diagnostics) {
+      allDiagnostics.push({ ...d, routerFile: urlsFile });
+    }
+  }
+
+  // Deduplicate diagnostics (router and urls detection may find the same issue)
+  const seen = new Set<string>();
+  const uniqueDiagnostics = allDiagnostics.filter((d) => {
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  if (uniqueDiagnostics.length > 0 && mode === "default") {
+    // Hard error: no files written
+    console.error("\n[rango] Unresolvable includes detected:\n");
+    formatDiagnostics(uniqueDiagnostics);
+    console.error(
+      "\nThe static parser cannot resolve these includes because they use " +
+        "factory functions or dynamic expressions.\n\n" +
+        "Options:\n" +
+        "  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n" +
+        "  rango generate <path> --static    Accept partial output (missing routes above)\n",
+    );
+    process.exit(1);
+  }
+
+  if (uniqueDiagnostics.length > 0 && mode === "static") {
+    // Warning: partial output accepted
+    console.warn(
+      "\n[rango] Warning: partial output (unresolvable includes):\n",
+    );
+    formatDiagnostics(uniqueDiagnostics);
+    console.warn("");
+  }
+
+  const nestedRouterConflict = findNestedRouterConflict(routerFiles);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
+  // Phase 3: Write all outputs (only reached if diagnostics pass or --static)
+  for (const urlsFile of urlsFiles) {
+    writePerModuleRouteTypesForFile(urlsFile);
+  }
+
+  for (const routerFile of routerFiles) {
+    const projectRoot = findProjectRoot(routerFile);
+    writeCombinedRouteTypes(projectRoot, [routerFile]);
+  }
+
+  console.log(
+    `[rango] Processed ${files.length} file(s)${routerFiles.length ? ` (${routerFiles.length} router)` : ""}`,
+  );
+  process.exit(0);
+}
+
+async function runRuntimeDiscovery(args: string[], configFile?: string) {
+  // Resolve the entry: find the router file from the arguments
+  const files: string[] = [];
+  for (const arg of args) {
+    const resolved = resolve(arg);
+    try {
+      if (statSync(resolved).isDirectory()) {
+        files.push(...findTsFiles(resolved));
+      } else {
+        files.push(resolved);
+      }
+    } catch {
+      console.warn(`[rango] Skipping ${arg}: not found`);
+    }
+  }
+
+  // Find router files among the inputs
+  const routerEntries: string[] = [];
+  for (const filePath of files) {
+    try {
+      const source = readFileSync(filePath, "utf-8");
+      if (/\bcreateRouter\s*[<(]/.test(source)) {
+        routerEntries.push(filePath);
+      }
+      // Also generate per-module types for urls files
+      if (source.includes("urls(")) {
+        writePerModuleRouteTypesForFile(filePath);
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  if (routerEntries.length === 0) {
+    console.error("[rango] No router files found in the provided paths");
+    process.exit(1);
+  }
+
+  const nestedRouterConflict = findNestedRouterConflict(routerEntries);
+  if (nestedRouterConflict) {
+    console.error(
+      `\n${formatNestedRouterConflictError(nestedRouterConflict, "[rango]")}\n`,
+    );
+    process.exit(1);
+  }
+
+  let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
+  try {
+    const mod = await import("../build/runtime-discovery.ts");
+    discoverAndWriteRouteTypes = mod.discoverAndWriteRouteTypes;
+  } catch (err: any) {
+    if (
+      err.code === "ERR_MODULE_NOT_FOUND" ||
+      err.code === "MODULE_NOT_FOUND"
+    ) {
+      console.error(
+        "[rango] Runtime discovery requires 'vite' and '@vitejs/plugin-rsc'.\n" +
+          "Install them with: pnpm add -D vite @vitejs/plugin-rsc",
+      );
+    } else {
+      console.error(`[rango] Failed to load runtime discovery: ${err.message}`);
+    }
+    process.exit(1);
+  }
+
+  for (const entry of routerEntries) {
+    const projectRoot = findProjectRoot(entry);
+    const result = await discoverAndWriteRouteTypes({
+      root: projectRoot,
+      configFile,
+      entry,
+    });
+    console.log(
+      `[rango] Runtime discovery: ${result.routerCount} router(s), ${result.routeCount} route(s)`,
+    );
+  }
+}
+
+function formatDiagnostics(
+  diagnostics: Array<UnresolvableInclude & { routerFile: string }>,
+) {
+  for (const d of diagnostics) {
+    const prefix = d.namePrefix ? `${d.namePrefix}.*` : `${d.pathPrefix}*`;
+    console.error(`  ${prefix}`);
+    console.error(`    Reason:  ${d.reason} -- ${d.detail}`);
+    console.error(`    Source:  ${d.sourceFile}`);
+  }
+}