@rangojs/router 0.24.4 → 0.25.0

package/src/vite/discovery/client-urls-projection.ts

@@ -1,6 +1,7 @@
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
-import { normalizePath, parseAst } from "vite";
+import { normalizePath, parseAst, type EnvironmentModuleNode } from "vite";
 import {
   projectClientUrlsModule,
   type ClientUrlProjection,
@@ -10,6 +11,9 @@ import {
   hashRefKey,
 } from "../plugins/client-ref-hashing.js";
 import { hasUseClientDirective } from "../utils/directive-prologue.js";
+import { firstCodeMatchIndex } from "../../build/route-types/source-scan.js";
+import { parseLang } from "../plugins/hoist/literal.js";
+import type { Node } from "../plugins/hoist/scope.js";
 import { createRangoDebugger, NS } from "../debug.js";
 import { findTsFiles } from "../../build/route-types/scan-filter.js";
 import type { DiscoveryState } from "./state.js";
@@ -30,6 +34,22 @@ interface ClientUrlProjectionServerModule {
   ): void;
 }
 
+/** The RSC environment whose realm `ClientUrlProjectionServerModule` is. */
+interface ClientUrlRscEnvironment {
+  readonly runner: { import(id: string): Promise<unknown> };
+  readonly moduleGraph?: {
+    getModuleById(id: string): EnvironmentModuleNode | undefined;
+    invalidateModule(mod: EnvironmentModuleNode): void;
+  };
+}
+
+export const CLIENT_URLS_REVALIDATE_QUERY = "rango-revalidate";
+
+/** The id of the module registering `file`'s hoisted revalidate() predicates. */
+export function hoistedRevalidateId(file: string): string {
+  return `${file}?${CLIENT_URLS_REVALIDATE_QUERY}`;
+}
+
 function hasDefaultExport(code: string): boolean {
   let program: { body?: any[] };
   try {
@@ -106,6 +126,69 @@ export function recordClientUrlsModule(
   }
 }
 
+/** A module that imports the router's client entry (a cheap pre-filter). */
+export const CLIENT_IMPORT_RE: RegExp = /["']@rangojs\/router\/client["']/;
+
+/**
+ * Whether an edited module can carry a clientUrls() component's own items: it
+ * imports "@rangojs/router/client" and assigns a `.use` in code (not in a
+ * comment or string). Such a module changes its groups' projections and
+ * hoisted revalidate() registrations like a group edit, with or without
+ * "use client".
+ */
+export function isClientUrlsComponentUseSource(source: string): boolean {
+  return (
+    source.includes(".use") &&
+    CLIENT_IMPORT_RE.test(source) &&
+    firstCodeMatchIndex(source, /\.use\s*=(?!=)/g) >= 0
+  );
+}
+
+/**
+ * A hash of the text of every `X.use = ...` assignment of a component-use
+ * module (isClientUrlsComponentUseSource), or undefined for any other module.
+ * Equal before and after a save, the edit (markup, hooks) left what its
+ * groups read unchanged: the dev watcher skips re-discovery and the client
+ * keeps Fast Refresh. An edit outside the assignments that changes what one
+ * means (a helper it calls, an import's source) is not seen. A module that
+ * does not parse hashes whole.
+ */
+export function componentUseSignature(
+  source: string,
+  file: string,
+): string | undefined {
+  if (!isClientUrlsComponentUseSource(source)) return undefined;
+  const hash = createHash("sha256");
+  let program: Node;
+  try {
+    program = parseAst(source, { lang: parseLang(file) });
+  } catch {
+    return hash.update(source).digest("base64");
+  }
+  const visit = (node: unknown): void => {
+    if (typeof node !== "object" || node === null) return;
+    if (Array.isArray(node)) {
+      for (const child of node) visit(child);
+      return;
+    }
+    const { type, left } = node as Node;
+    if (
+      type === "AssignmentExpression" &&
+      left.type === "MemberExpression" &&
+      !left.computed &&
+      left.property.type === "Identifier" &&
+      left.property.name === "use"
+    ) {
+      const { start, end } = node as Node;
+      hash.update(source.slice(start, end)).update("\0");
+      return;
+    }
+    for (const value of Object.values(node)) visit(value);
+  };
+  visit(program.body);
+  return hash.digest("base64");
+}
+
 export function resolveClientUrlsSource(
   state: DiscoveryState,
   referenceId: string,
@@ -162,14 +245,17 @@ function projectionError(
  * import, so `.routes(reference)` materialized the previous pass's projection.
  *
  * Errors are deliberately swallowed per source (a module mid-edit keeps its
- * last-known projection); the strict discoverClientUrlProjections() pass still
- * surfaces real failures afterwards. No-ops on cold start (nothing recorded
- * yet) and when the SSR runner is unavailable.
+ * last-known projection), and all refreshed projections keep their
+ * last-known state when any registration fails to load; the strict
+ * discoverClientUrlProjections() pass still surfaces real failures afterwards.
+ * No-ops on cold start (nothing recorded yet) and when the SSR runner is
+ * unavailable.
  */
 export async function refreshRecordedClientUrlProjections(
   state: DiscoveryState,
   ssrEnv: ClientUrlSsrEnvironment | undefined,
   serverMod: ClientUrlProjectionServerModule,
+  rscEnv: ClientUrlRscEnvironment,
 ): Promise<void> {
   const sourceByReferenceId = state.clientUrlSourceByReferenceId;
   if (
@@ -189,6 +275,7 @@ export async function refreshRecordedClientUrlProjections(
     }
   }
 
+  const refreshed = new Map<string, ClientUrlProjection>();
   for (const [source, referenceIds] of referenceIdsBySource) {
     let module: Record<string, unknown>;
     try {
@@ -209,15 +296,29 @@ export async function refreshRecordedClientUrlProjections(
       projection.routes.map((route) => route.pattern).join(", "),
     );
     for (const referenceId of referenceIds) {
-      serverMod.setClientUrlProjection(referenceId, projection);
-      // The eager routes-manifest virtual module REPLAYS this state map
-      // (clearClientUrlProjections + set) whenever it re-evaluates — and the
-      // watcher's gen-file write invalidates it right before the entry import,
-      // so a stale map here would clobber the registry install above before
-      // the router materializes its mount. Keep both in sync.
-      state.clientUrlProjectionMap?.set(referenceId, projection);
+      refreshed.set(referenceId, projection);
     }
   }
+  if (refreshed.size === 0) return;
+  // The eager routes-manifest virtual module REPLAYS the state map
+  // (clearClientUrlProjections + set) whenever it re-evaluates — and the
+  // watcher's gen-file write invalidates it right before the entry import, so
+  // a stale map would clobber the registry install before the router
+  // materializes its mount: the install keeps both in sync.
+  try {
+    await installClientUrlProjections(
+      state,
+      rscEnv,
+      serverMod,
+      refreshed,
+      false,
+    );
+  } catch (error) {
+    debug?.(
+      "pre-entry refresh: predicate registrations failed to load: %s",
+      error instanceof Error ? error.message : String(error),
+    );
+  }
 }
 
 /**
@@ -235,12 +336,18 @@ export async function discoverClientUrlProjections(
   state: DiscoveryState,
   ssrEnv: ClientUrlSsrEnvironment | undefined,
   serverMod: ClientUrlProjectionServerModule,
+  rscEnv: ClientUrlRscEnvironment,
 ): Promise<void> {
   scanForClientUrlModules(state);
   const sourceByReferenceId = state.clientUrlSourceByReferenceId;
   if (!sourceByReferenceId?.size) {
-    serverMod.clearClientUrlProjections();
-    state.clientUrlProjectionMap = new Map();
+    await installClientUrlProjections(
+      state,
+      rscEnv,
+      serverMod,
+      new Map(),
+      true,
+    );
     return;
   }
 
@@ -313,9 +420,91 @@ export async function discoverClientUrlProjections(
     }
   }
 
-  serverMod.clearClientUrlProjections();
-  for (const [id, projection] of nextProjections) {
+  await installClientUrlProjections(
+    state,
+    rscEnv,
+    serverMod,
+    nextProjections,
+    true,
+  );
+}
+
+/**
+ * Install `projections` in the realm of `serverMod` and in `state` (all of
+ * them with `replace`, else over the installed ones), once `rscEnv` has
+ * loaded the registrations of every revalidate() key they read
+ * (assignClientUrlRevalidateFiles). Node dev serves requests in that realm,
+ * and a request materializes the installed projection, so a key whose
+ * registration has not loaded must never be installed.
+ */
+async function installClientUrlProjections(
+  state: DiscoveryState,
+  rscEnv: ClientUrlRscEnvironment,
+  serverMod: ClientUrlProjectionServerModule,
+  projections: ReadonlyMap<string, ClientUrlProjection>,
+  replace: boolean,
+): Promise<void> {
+  const next = new Map(replace ? undefined : state.clientUrlProjectionMap);
+  for (const [id, projection] of projections) next.set(id, projection);
+  await assignClientUrlRevalidateFiles(state, rscEnv, next);
+  if (replace) serverMod.clearClientUrlProjections();
+  for (const [id, projection] of projections) {
     serverMod.setClientUrlProjection(id, projection);
   }
-  state.clientUrlProjectionMap = nextProjections;
+  state.clientUrlProjectionMap = next;
+}
+
+/**
+ * Assign each group of `projections` the other files holding the predicates
+ * it reads (each key's file, as the hoist transform recorded it: a key with
+ * none stays unregistered, and materialization names it), after loading their
+ * registrations into `rscEnv`. The group's own registrations load with its
+ * proxy, and its `?rango-revalidate` module imports the assigned files'
+ * (plugins/client-urls-revalidate-hoist.ts). When a group's files change, that
+ * module is invalidated, so a later evaluation (a reload, a request realm)
+ * imports the current ones. Another realm (workerd, a production bundle)
+ * loads a group only after discovery: its entry imports the routes-manifest
+ * module first, whose load waits for discovery (RSC_ENTRY_BOOTSTRAP_IMPORTS),
+ * and a build discovers in buildStart.
+ */
+export async function assignClientUrlRevalidateFiles(
+  state: Pick<
+    DiscoveryState,
+    "clientUrlRevalidate" | "clientUrlSourceByReferenceId"
+  >,
+  rscEnv: ClientUrlRscEnvironment,
+  projections: ReadonlyMap<string, ClientUrlProjection>,
+): Promise<void> {
+  const { fileByKey, filesByGroup } = state.clientUrlRevalidate;
+  const next = new Map<string, readonly string[]>();
+  for (const [referenceId, projection] of projections) {
+    const group = state.clientUrlSourceByReferenceId?.get(referenceId);
+    if (group === undefined || next.has(group)) continue;
+    const files = new Set<string>();
+    for (const owner of [
+      ...projection.routes,
+      ...(projection.intercepts ?? []),
+    ]) {
+      for (const key of owner.loaderRevalidate?.flat() ?? []) {
+        const file = typeof key === "string" ? fileByKey.get(key) : undefined;
+        if (file !== undefined && file !== group) files.add(file);
+      }
+    }
+    next.set(group, [...files].sort());
+  }
+  await Promise.all(
+    [...new Set([...next.values()].flat())].map((file) =>
+      rscEnv.runner.import(hoistedRevalidateId(file)),
+    ),
+  );
+  const graph = rscEnv.moduleGraph;
+  for (const [group, files] of next) {
+    if ((filesByGroup.get(group) ?? []).join("\0") === files.join("\0")) {
+      continue;
+    }
+    const mod = graph?.getModuleById(hoistedRevalidateId(group));
+    if (graph && mod) graph.invalidateModule(mod);
+  }
+  filesByGroup.clear();
+  for (const [group, files] of next) filesByGroup.set(group, files);
 }

package/src/vite/discovery/discover-routers.ts

@@ -138,7 +138,7 @@ async function discoverRoutersPass(
   serverMod: any,
 ): Promise<any> {
   await timed(debug, "inner: refresh recorded client URL projections", () =>
-    refreshRecordedClientUrlProjections(state, ssrEnv, serverMod),
+    refreshRecordedClientUrlProjections(state, ssrEnv, serverMod, rscEnv),
   );
 
   // Import the entry file via RSC environment.
@@ -194,7 +194,7 @@ async function discoverRoutersPass(
   }
 
   await timed(debug, "inner: discover client URL projections", () =>
-    discoverClientUrlProjections(state, ssrEnv, serverMod),
+    discoverClientUrlProjections(state, ssrEnv, serverMod, rscEnv),
   );
 
   // generateManifestFull must run in the RSC runner realm: it invokes the

package/src/vite/discovery/prerender-collection.ts

@@ -9,6 +9,7 @@
 import { contextSet, hasContextVars } from "../../context-var.js";
 import { sha256 } from "./build-versions.js";
 import {
+  createGetParamsReverse,
   encodePathParam,
   substituteRouteParams,
   runWithConcurrency,
@@ -76,12 +77,7 @@ export async function expandPrerenderRoutes(
   for (const { manifest: m } of allManifests) {
     if (m.routeManifest) Object.assign(allRoutes, m.routeManifest);
   }
-  const getParamsReverse = (name: string, params?: Record<string, string>) => {
-    const pattern = allRoutes[name];
-    if (!pattern) throw new Error(`Unknown route: "${name}"`);
-    if (!params) return pattern;
-    return substituteRouteParams(pattern, params);
-  };
+  const getParamsReverse = createGetParamsReverse(allRoutes);
 
   let resolvedRoutes = 0;
   let totalDynamic = 0;

package/src/vite/discovery/state.ts

@@ -52,6 +52,29 @@ export interface PluginOptions {
    * budget into its capture/render handlers.
    */
   progressiveChunkSize?: number;
+  /**
+   * The index rango()'s clientUrls() revalidate() hoist plugin shares, so
+   * discovery's temp server records keys into it and assigns the files the
+   * dev server's or build's group modules import.
+   */
+  clientUrlRevalidate?: ClientUrlRevalidateIndex;
+}
+
+/**
+ * What the clientUrls() revalidate() hoist
+ * (plugins/client-urls-revalidate-hoist.ts) shares with discovery across the
+ * plugin instances of one rango(), the dev server or build and discovery's
+ * temp server: the file of every key the hoist transform saw, in any
+ * environment, and each group's files, which discovery assigns from the
+ * group's projection and the group's `?rango-revalidate` module imports.
+ */
+export interface ClientUrlRevalidateIndex {
+  readonly fileByKey: Map<string, string>;
+  readonly filesByGroup: Map<string, readonly string[]>;
+}
+
+export function createClientUrlRevalidateIndex(): ClientUrlRevalidateIndex {
+  return { fileByKey: new Map(), filesByGroup: new Map() };
 }
 
 export interface PrecomputedEntry {
@@ -129,6 +152,7 @@ export interface DiscoveryState {
   perRouterManifestDataMap: Map<string, Record<string, string>>;
   clientUrlSourceByReferenceId?: Map<string, string>;
   clientUrlProjectionMap?: Map<string, ClientUrlProjection>;
+  clientUrlRevalidate: ClientUrlRevalidateIndex;
 
   prerenderManifestEntries: Record<string, string> | null;
   staticManifestEntries: Record<string, string> | null;
@@ -251,6 +275,8 @@ export function createDiscoveryState(
     perRouterManifestDataMap: new Map(),
     clientUrlSourceByReferenceId: new Map(),
     clientUrlProjectionMap: new Map(),
+    clientUrlRevalidate:
+      opts?.clientUrlRevalidate ?? createClientUrlRevalidateIndex(),
 
     prerenderManifestEntries: null,
     staticManifestEntries: null,