@rangojs/router 0.16.0 → 0.17.0

package/src/theme/ThemeScript.tsx

@@ -8,14 +8,14 @@
  *
  * Must be placed in the <head> element of your document, before any stylesheets.
  *
- * Note: when theme is enabled in the router config, `<MetaTags />` ALREADY
+ * Note: when theme is enabled in the router config, `<Html.Meta />` ALREADY
  * renders this FOUC script. Use `<ThemeScript />` only if you do NOT render
- * `<MetaTags />`. Rendering both is safe — the inline script guards the
+ * `<Html.Meta />`. Rendering both is safe — the inline script guards the
  * matchMedia listener registration against double-running — but it is redundant.
  *
  * @example
  * ```tsx
- * // In your document component. Use ThemeScript only when you do not render MetaTags.
+ * // In your document component. Use ThemeScript only when you do not render Html.Meta.
  * import { ThemeScript } from "@rangojs/router/theme";
  *
  * export function Document({ children }) {

package/src/types/cache-types.ts

@@ -1,12 +1,13 @@
 /**
- * Context passed to cache condition/key/tags functions.
+ * Context passed to cache condition/key/tags functions (the full
+ * RequestContext).
  *
- * This is a subset of RequestContext that's guaranteed to be available
- * during cache key generation (before middleware runs).
- *
- * Note: While the full RequestContext is passed, middleware-set variables
- * read via `ctx.get()` may not be populated yet since cache lookup happens
- * before middleware execution.
+ * Ordering: global middleware wraps the whole request, and on RSC routes route
+ * middleware wraps the match/render pipeline (rsc/handler.ts executeRender), so
+ * variables they set before `next()` are readable via `ctx.get()`. On response
+ * routes the cache lookup runs BEFORE route middleware, which wraps only the
+ * handler run on a miss (rsc/response-route-handler.ts); only global-middleware
+ * variables are populated there.
  */
 export type { RequestContext as CacheContext } from "../server/request-context.js";
 
@@ -109,7 +110,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Return false to skip cache for this request (always fetch fresh).
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   * Runs after global and route middleware on RSC routes; on response routes,
+   * before route middleware (see CacheContext).
    *
    * @example
    * ```typescript
@@ -131,7 +133,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Bypasses default key generation AND store's keyGenerator.
    *
    * Has access to full RequestContext including env, request, params, cookies, etc.
-   * Note: Middleware-set variables read via `ctx.get()` may not be populated yet.
+   * Runs after global and route middleware on RSC routes; on response routes,
+   * before route middleware (see CacheContext).
    *
    * @example
    * ```typescript
@@ -153,7 +156,8 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
-   * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+   * The built-in `MemorySegmentCacheStore`, `CFCacheStore`, and
+   * `VercelCacheStore` index by tag.
    * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
    * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
    * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed

package/src/types/handler-context.ts

@@ -455,6 +455,20 @@ export type InternalHandlerContext<
    * table (so a loader cannot await its own in-flight memoized promise).
    */
   _loaderCacheOriginalUse?: (item: any) => any;
+  /**
+   * @internal A loader-cache HIT asks before replaying a loader's recorded
+   * pushes: true when that loader has not run in this request and no other
+   * replay delivered it; its later run then replaces the replayed values
+   * (HandleStore.pushReplayed). One copy per loader per request. See
+   * setupLoaderAccess.
+   */
+  _claimLoaderPushes?: (loaderId: string) => boolean;
+  /**
+   * @internal Run a loader on a fresh executor (own memo map): a loader-cache
+   * stale refresh, whose diverted pushes must not take a dependency's run
+   * from the page. See setupLoaderAccess.
+   */
+  _runLoaderIsolated?: (loader: any) => Promise<any>;
 };
 
 /**

package/src/types/loader-types.ts

@@ -28,9 +28,10 @@ import type { RequestScope } from "./request-scope.js";
  *   return await db.cart.get(user.id);
  * });
  *
- * // With typed params:
- * const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  * ```
@@ -243,9 +244,10 @@ export type LoadOptions =
  *   return await db.cart.get(ctx.get("user").id);
  * });
  *
- * // With typed params:
- * export const ProductLoader = createLoader<Product, { slug: string }>(async (ctx) => {
- *   const { slug } = ctx.params;  // slug is typed as string
+ * // createLoader's one type parameter is the data type; params are
+ * // Record<string, string | undefined>:
+ * export const ProductLoader = createLoader<Product>(async (ctx) => {
+ *   const { slug } = ctx.params;  // string | undefined
  *   return await db.products.findBySlug(slug);
  * });
  *

package/src/urls/response-types.ts

@@ -1,5 +1,5 @@
 import type { ContextVar } from "../context-var.js";
-import type { ReverseFunction } from "../reverse.js";
+import type { GlobalReverseFunction } from "../reverse.js";
 import type {
   DefaultReverseRouteMap,
   DefaultVars,
@@ -7,27 +7,6 @@ import type {
 import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
 import type { RequestScope } from "../types/request-scope.js";
 
-/**
- * Reverse function for response handler contexts.
- * Global names get autocomplete and param validation from the generated route map.
- * Local `.name` calls are accepted but not validated (scope unknown at type level).
- */
-type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
-  Record<string, string>,
-]
-  ? (
-      name: string,
-      params?: Record<string, string>,
-      search?: Record<string, unknown>,
-    ) => string
-  : ReverseFunction<DefaultReverseRouteMap> & {
-      (
-        name: `.${string}`,
-        params?: Record<string, string>,
-        search?: Record<string, unknown>,
-      ): string;
-    };
-
 /**
  * Symbol marking a route as a response route (non-RSC).
  * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
@@ -99,7 +78,8 @@ export interface ResponseHandlerContext<
   params: TParams;
   /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
   readonly _paramCheck?: (params: TParams) => TParams;
-  reverse: ResponseReverseFunction;
+  /** Global route names only; see {@link GlobalReverseFunction}. */
+  reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;

package/src/use-loader.tsx

@@ -117,6 +117,14 @@ export type LoadFunction<T> = (options?: LoadOptions) => Promise<T>;
 
 export interface UseLoaderResult<T> {
   data: T;
+  /**
+   * True while this loader family (`loader.$$id`) is in flight: a `load()` /
+   * group refresh, or a held navigation still streaming a re-run of this
+   * loader. Family-keyed, not segment-keyed: a layout `useLoader` of the same
+   * `createLoader` the child route is re-running also reports true, even if
+   * the layout copy is not replaced. Not used for the initial streamed read
+   * (that suspends).
+   */
   isLoading: boolean;
   error: Error | null;
   load: LoadFunction<T>;
@@ -125,6 +133,7 @@ export interface UseLoaderResult<T> {
 
 export interface UseFetchLoaderResult<T> {
   data: T | undefined;
+  /** Same family-keyed contract as {@link UseLoaderResult.isLoading}. */
   isLoading: boolean;
   error: Error | null;
   load: LoadFunction<T>;
@@ -560,7 +569,7 @@ function useLoaderInternal<T>(
  * @example Basic usage - accessing route loader data
  * ```tsx
  * "use client";
- * import { useLoader } from "rsc-router/client";
+ * import { useLoader } from "@rangojs/router/client";
  * import { CartLoader } from "../loaders/cart";
  *
  * // In route definition: loader(CartLoader)
@@ -608,7 +617,7 @@ export function useLoader<T>(
  * @example On-demand fetching
  * ```tsx
  * "use client";
- * import { useFetchLoader } from "rsc-router/client";
+ * import { useFetchLoader } from "@rangojs/router/client";
  * import { SearchLoader } from "../loaders/search";
  *
  * export function SearchResults() {
@@ -670,7 +679,7 @@ export function useFetchLoader<T>(
  * @example
  * ```tsx
  * "use client";
- * import { useLoader, useRefreshLoaders } from "rsc-router/client";
+ * import { useLoader, useRefreshLoaders } from "@rangojs/router/client";
  *
  * function Profile() {
  *   const { data } = useLoader(ProfileLoader, { key: userId, refreshGroup: "account" });

package/src/vite/plugins/use-cache-transform.ts

@@ -16,14 +16,18 @@
  * - transformHoistInlineDirective() for function-level hoisting
  */
 
-import type { Plugin } from "vite";
+import type { Plugin, Rollup } from "vite";
 import type { ModuleExportMeta } from "@vitejs/plugin-rsc/transforms";
 import path from "node:path";
-import MagicString from "magic-string";
 import { normalizePath, hashId } from "./expose-id-utils.js";
-import { createRangoDebugger, createCounter, NS } from "../debug.js";
+import type { Counter } from "../debug.js";
 
-const debug = createRangoDebugger(NS.transform);
+// No static import of `magic-string` or `../debug.js` (the `debug` package):
+// `rangoUseCacheTransform()` bundles this module into `dist/testing/vitest.js`,
+// whose static imports are node builtins only, and every package it needs
+// loads lazily, as `rangoUseClientTransform()`'s `vite` and plugin-rsc
+// imports do. src/__tests__/installed-vitest-config.test.ts loads that file
+// from a fixture holding only `package.json` and `dist/`.
 
 const CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 
@@ -33,12 +37,13 @@ const LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
 
 export const USE_CACHE_DIRECTIVE_RE: RegExp = /^use cache(:\s*[\w-]+)?$/;
 
-export function useCacheTransform(): Plugin {
+/**
+ * @param counter `rango:transform` timing counter, created by `rango()`
+ *   (`createCounter` in ../debug.js); omitted when debugging is off.
+ */
+export function useCacheTransform(counter?: Counter): Plugin {
   let projectRoot = "";
   let isBuild = false;
-  let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null =
-    null;
-  const counter = createCounter(debug, "use-cache");
 
   return {
     name: "@rangojs/router:use-cache",
@@ -56,75 +61,15 @@ export function useCacheTransform(): Plugin {
     async transform(code, id) {
       // Only process in RSC environment
       if (this.environment?.name !== "rsc") return;
-
-      // Quick bail: no "use cache" in source
-      if (!code.includes("use cache")) return;
-
-      // Skip node_modules and virtual modules
-      if (id.includes("/node_modules/") || id.startsWith("\0")) return;
-
-      // Only JS/TS files
-      if (!/\.(tsx?|jsx?|mjs)$/.test(id)) return;
+      if (!isUseCacheCandidate(code, id)) return;
 
       const start = counter ? performance.now() : 0;
       try {
-        if (!rscTransforms) {
-          try {
-            rscTransforms = await import("@vitejs/plugin-rsc/transforms");
-          } catch {
-            return;
-          }
-        }
-
-        const {
-          hasDirective,
-          transformWrapExport,
-          transformHoistInlineDirective,
-        } = rscTransforms;
-
-        let ast: any;
-        try {
-          const { parseAst } = await import("vite");
-          ast = parseAst(code, { lang: "tsx" });
-        } catch {
-          return;
-        }
-
-        // plugin-rsc 0.5.34 `matchDirective` does `stmt.directive.match(...)`
-        // after `"directive" in node`. Vite/oxc parseAst now emits
-        // `directive: null` on ordinary ExpressionStatements, so a file that
-        // mixes a `"use cache"` function with a sibling handler whose first
-        // statement is an expression throws and the wrap is dropped.
-        stripNullDirectiveFields(ast);
-
-        const filePath = normalizePath(path.relative(projectRoot, id));
-        const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
-
-        if (hasDirective(ast.body, "use cache")) {
-          return transformFileLevelUseCache(
-            code,
-            ast,
-            filePath,
-            id,
-            isBuild,
-            isLayoutOrTemplate,
-            transformWrapExport,
-            hasDirective,
-          );
-        }
-
-        const functionResult = transformFunctionLevelUseCache(
-          code,
-          ast,
-          filePath,
-          id,
+        return await transformUseCache(code, id, {
+          root: projectRoot,
           isBuild,
-          transformHoistInlineDirective,
-        );
-
-        warnOnNearMissDirectives(ast, id, this.warn.bind(this));
-
-        if (functionResult) return functionResult;
+          warn: (message) => this.warn(message),
+        });
       } finally {
         counter?.record(id, performance.now() - start);
       }
@@ -132,7 +77,105 @@ export function useCacheTransform(): Plugin {
   };
 }
 
-function transformFileLevelUseCache(
+/** Options for {@link transformUseCache}. */
+export interface UseCacheTransformOptions {
+  /** Root the ids are relative to (Vite's `config.root`). */
+  root: string;
+  /** Build ids hash the path (`hashId`); dev ids are `<path>#<export>`. */
+  isBuild: boolean;
+  /** Sink for the near-miss directive warning. */
+  warn: (message: string) => void;
+  /**
+   * Called when `@vitejs/plugin-rsc/transforms` fails to load; the module is
+   * then left unwrapped. The rango plugin omits it (skip silently).
+   */
+  onTransformsError?: (error: unknown) => void;
+}
+
+/** Whether a module may carry a `"use cache"` directive the transform wraps. */
+export function isUseCacheCandidate(code: string, id: string): boolean {
+  return (
+    // Quick bail: no "use cache" in source
+    code.includes("use cache") &&
+    // Skip node_modules and virtual modules
+    !id.includes("/node_modules/") &&
+    !id.startsWith("\0") &&
+    // Only JS/TS files
+    /\.(tsx?|jsx?|mjs)$/.test(id)
+  );
+}
+
+let rscTransforms: typeof import("@vitejs/plugin-rsc/transforms") | null = null;
+
+/**
+ * Wrap a module's `"use cache"` functions with `registerCachedFunction`. The
+ * rango plugin runs it in the rsc environment; `rangoUseCacheTransform()`
+ * (testing/vitest.ts) runs it in a Vitest project, whose environment is `ssr`.
+ * Call it only for an {@link isUseCacheCandidate} module.
+ */
+export async function transformUseCache(
+  code: string,
+  id: string,
+  options: UseCacheTransformOptions,
+): Promise<{ code: string; map: Rollup.ExistingRawSourceMap } | undefined> {
+  if (!rscTransforms) {
+    try {
+      rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+    } catch (error) {
+      options.onTransformsError?.(error);
+      return;
+    }
+  }
+
+  const { hasDirective, transformWrapExport, transformHoistInlineDirective } =
+    rscTransforms;
+
+  let ast: any;
+  try {
+    const { parseAst } = await import("vite");
+    ast = parseAst(code, { lang: "tsx" });
+  } catch {
+    return;
+  }
+
+  // plugin-rsc 0.5.34 `matchDirective` does `stmt.directive.match(...)`
+  // after `"directive" in node`. Vite/oxc parseAst now emits
+  // `directive: null` on ordinary ExpressionStatements, so a file that
+  // mixes a `"use cache"` function with a sibling handler whose first
+  // statement is an expression throws and the wrap is dropped.
+  stripNullDirectiveFields(ast);
+
+  const filePath = normalizePath(path.relative(options.root, id));
+  const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+
+  if (hasDirective(ast.body, "use cache")) {
+    return transformFileLevelUseCache(
+      code,
+      ast,
+      filePath,
+      id,
+      options.isBuild,
+      isLayoutOrTemplate,
+      transformWrapExport,
+      hasDirective,
+    );
+  }
+
+  const functionResult = transformFunctionLevelUseCache(
+    code,
+    ast,
+    filePath,
+    id,
+    options.isBuild,
+    transformHoistInlineDirective,
+  );
+
+  warnOnNearMissDirectives(ast, id, options.warn);
+
+  if (functionResult) return functionResult;
+}
+
+async function transformFileLevelUseCache(
   code: string,
   ast: any,
   filePath: string,
@@ -193,6 +236,7 @@ function transformFileLevelUseCache(
   }
 
   if (exportNames.length === 0) {
+    const { default: MagicString } = await import("magic-string");
     const s = new MagicString(code);
     const directive = findFileLevelDirective(ast);
     if (directive) {

package/src/vite/rango.ts

@@ -45,7 +45,7 @@ import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
 import { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
 import { createRouterDiscoveryPlugin } from "./router-discovery.js";
 import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
-import { createRangoDebugger, NS } from "./debug.js";
+import { createCounter, createRangoDebugger, NS } from "./debug.js";
 
 const debugConfig = createRangoDebugger(NS.config);
 
@@ -100,7 +100,7 @@ export { hasUseClientDirective };
  *   plugins: [
  *     react(),
  *     rango({ preset: 'cloudflare' }),
- *     cloudflare({ viteEnvironment: { name: 'rsc' } }),
+ *     cloudflare({ viteEnvironment: { name: 'rsc', childEnvironments: ['ssr'] } }),
  *   ],
  * });
  * ```
@@ -565,7 +565,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   plugins.push(createLoaderDirectiveGuardPlugin());
   plugins.push(createLoaderScanStubPlugin());
   plugins.push(exposeActionId());
-  plugins.push(useCacheTransform());
+  plugins.push(
+    useCacheTransform(
+      createCounter(createRangoDebugger(NS.transform), "use-cache"),
+    ),
+  );
   plugins.push(exposeInternalIds());
   plugins.push(exposeRouterId());
   plugins.push(createVersionPlugin());