@rangojs/router 0.24.3 → 0.25.0

package/dist/types/types/loader-types.d.ts

@@ -2,7 +2,7 @@ import type { ContextVar } from "../context-var.js";
 import type { Handle } from "../handle.js";
 import type { HandlePush } from "../defer.js";
 import type { MiddlewareFn } from "../router/middleware.js";
-import type { ScopedReverseFunction } from "../reverse.js";
+import type { AutofillAwareReverseFunction } from "./handler-context.js";
 import type { SearchSchema, ResolveSearchSchema } from "../search-params.js";
 import type { UseItems, LoaderUseItem } from "../route-types.js";
 import type { DefaultEnv, DefaultReverseRouteMap, DefaultVars } from "./global-namespace.js";
@@ -118,9 +118,10 @@ export type LoaderContext<TParams = Record<string, string | undefined>, TEnv = D
     /**
      * Generate URLs from route names.
      * Same scoped reverse as route handlers — `.name` resolves within the
-     * current include() scope, `name` resolves globally.
+     * current include() scope, `name` resolves globally, and params the matched
+     * route already carries (e.g. include() mount params) are filled in.
      */
-    reverse: ScopedReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
+    reverse: AutofillAwareReverseFunction<Record<string, string>, DefaultReverseRouteMap>;
 };
 /**
  * Loader function signature

package/dist/types/types/route-entry.d.ts

@@ -1,6 +1,7 @@
 import type { AllUseItems } from "../route-types.js";
+import type { IncludeScopePosition } from "../server/context.js";
 import type { TrailingSlashMode, ResolvedRouteMap } from "./route-config.js";
-export interface LazyIncludeContext {
+export interface LazyIncludeContext extends IncludeScopePosition {
     urlPrefix: string;
     namePrefix: string | undefined;
     parent: unknown;

package/dist/types/urls/path-helper-types.d.ts

@@ -144,9 +144,11 @@ export type PathHelpers<TEnv> = {
         (fns: MiddlewareFn<TEnv>[], children: () => UseItems<LayoutUseItem>): MiddlewareItem;
     };
     /**
-     * Control when a segment should revalidate during navigation
+     * Control when a segment should revalidate during navigation.
+     * `revalidate(true)` / `revalidate(false)` are shorthand for
+     * `revalidate(() => true)` / `revalidate(() => false)`.
      */
-    revalidate: (fn: ShouldRevalidateFn<any, TEnv>) => RevalidateItem;
+    revalidate: (fn: ShouldRevalidateFn<any, TEnv> | boolean) => RevalidateItem;
     /**
      * Attach a data loader to the current route/layout.
      *

package/dist/types/urls/path-helper.d.ts

@@ -1,5 +1,10 @@
 import type { Handler } from "../types.js";
 import type { PathFn, ResponsePathFn, JsonResponsePathFn, TextResponsePathFn } from "./path-helper-types.js";
+/**
+ * The key path() registers a route under: its name, or a `$path_` name built
+ * from its pattern, behind the include's name prefix.
+ */
+export declare function routeKeyOf(namePrefix: string | undefined, pattern: string, name: string | undefined): string;
 /**
  * A retained on-demand producer must never render on a live production
  * request: bundle eviction is skipped for onDemand routes (the producer body

package/dist/types/vite/discovery/client-urls-projection.d.ts

@@ -1,3 +1,4 @@
+import { type EnvironmentModuleNode } from "vite";
 import { type ClientUrlProjection } from "../../client-urls/server-projection.js";
 import type { DiscoveryState } from "./state.js";
 interface ClientUrlSsrEnvironment {
@@ -9,7 +10,40 @@ interface ClientUrlProjectionServerModule {
     clearClientUrlProjections(): void;
     setClientUrlProjection(referenceId: string, projection: ClientUrlProjection): 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 declare const CLIENT_URLS_REVALIDATE_QUERY = "rango-revalidate";
+/** The id of the module registering `file`'s hoisted revalidate() predicates. */
+export declare function hoistedRevalidateId(file: string): string;
 export declare function recordClientUrlsModule(state: DiscoveryState, code: string, id: string): void;
+/** A module that imports the router's client entry (a cheap pre-filter). */
+export declare const CLIENT_IMPORT_RE: RegExp;
+/**
+ * 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 declare function isClientUrlsComponentUseSource(source: string): boolean;
+/**
+ * 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 declare function componentUseSignature(source: string, file: string): string | undefined;
 export declare function resolveClientUrlsSource(state: DiscoveryState, referenceId: string): string | undefined;
 /**
  * Deterministic filesystem discovery of clientUrls modules. Transform-based
@@ -33,11 +67,13 @@ export declare function scanForClientUrlModules(state: DiscoveryState): void;
  * 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 declare function refreshRecordedClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+export declare function refreshRecordedClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule, rscEnv: ClientUrlRscEnvironment): Promise<void>;
 /**
  * Strict projection discovery over every RECORDED clientUrls module. Recorded
  * modules — not router references — are the source of truth: include() mounts
@@ -49,5 +85,19 @@ export declare function refreshRecordedClientUrlProjections(state: DiscoveryStat
  * (recordClientUrlsModule never un-records, so deletions must self-heal here).
  * A present-but-broken module is a hard error: it is part of the app graph.
  */
-export declare function discoverClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule): Promise<void>;
+export declare function discoverClientUrlProjections(state: DiscoveryState, ssrEnv: ClientUrlSsrEnvironment | undefined, serverMod: ClientUrlProjectionServerModule, rscEnv: ClientUrlRscEnvironment): Promise<void>;
+/**
+ * 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 declare function assignClientUrlRevalidateFiles(state: Pick<DiscoveryState, "clientUrlRevalidate" | "clientUrlSourceByReferenceId">, rscEnv: ClientUrlRscEnvironment, projections: ReadonlyMap<string, ClientUrlProjection>): Promise<void>;
 export {};

package/dist/types/vite/discovery/state.d.ts

@@ -52,7 +52,26 @@ 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 declare function createClientUrlRevalidateIndex(): ClientUrlRevalidateIndex;
 export interface PrecomputedEntry {
     staticPrefix: string;
     routes: Record<string, string>;
@@ -122,6 +141,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;
     /**

package/dist/types/vite/plugins/client-urls-revalidate-hoist.d.ts

@@ -1,5 +1,6 @@
 import type { Plugin } from "vite";
 import MagicString from "magic-string";
+import type { ClientUrlRevalidateIndex } from "../discovery/state.js";
 /**
  * The key of the predicate `source` declared in `relativeFile` (relative to
  * the project root): a hash of the file and the predicate's syntax, so the
@@ -26,29 +27,40 @@ interface HoistClientUrlsRevalidateResult {
     readonly keys: readonly string[];
 }
 /**
- * Hoist every clientUrls() `revalidate()` predicate of a "use client"
- * module. Returns null when there is none. Throws, naming file:line, for a
- * predicate that is not pure.
+ * Hoist every clientUrls() `revalidate()` predicate of a module. Returns null
+ * when there is none (boolean literals stay in place). Throws, naming
+ * file:line, for a predicate that is not pure.
  */
 export declare function hoistClientUrlsRevalidates(code: string, id: string, deps: HoistClientUrlsRevalidateDeps): Promise<HoistClientUrlsRevalidateResult | null>;
 /** The file a `?rango-revalidate` id names, or null. */
 export declare function parseHoistedRevalidateId(id: string): string | null;
 /**
  * The plugins: a pre transform that hoists in every environment (markers in
- * the client and SSR copies, the server module recorded from the RSC
- * transform) and serves `?rango-revalidate`, and a post transform that
- * appends its import to the RSC client-reference proxy.
+ * the client and SSR copies, each key's file in `index`, the server module
+ * recorded from the RSC transform, the groups noted) and serves
+ * `?rango-revalidate`, a post transform that appends its import to the RSC
+ * client-reference proxy of each group, and in dev the client's `.use`
+ * update propagation. Pass one `index` to every instance of one rango():
+ * discovery's temp server records keys the dev server or build reads.
  *
- * `load` serves the module the RSC transform emitted, which hoisted the
- * pipeline code; the disk source is re-hoisted only when the transform has
- * not seen the current file (loadEmittedOrDisk). A file whose edit removed
- * every predicate serves an empty module to a proxy that still imports it.
+ * `load` serves the registrations the RSC transform emitted, which hoisted
+ * the pipeline code; the disk source is re-hoisted when the transform has not
+ * seen the current file (loadEmittedOrDisk), which is always the case for a
+ * component module: the RSC environment never transforms a module only a
+ * group imports. A group's module also imports the registrations of the
+ * files discovery assigned it. A file with neither serves an empty module.
  *
- * The transform's code filter skips a module that never mentions clientUrls,
- * so a file that stops doing so would keep its `emitted` entry: watchChange
- * drops it, together with the cached "use client" answer for an edited
- * dependency (isClientModule memoizes per resolved file; buildStart resets
- * it).
+ * A component module that exports only components is a Fast Refresh
+ * boundary, so a `.use` edit would leave the browser's group records stale
+ * (the group never re-evaluates). In dev, an update that changes a module's
+ * componentUseSignature also updates its importers, as a group edit does;
+ * any other edit keeps Fast Refresh.
+ *
+ * The transform's code filter skips a module that names neither clientUrls
+ * nor revalidate, so a file that stops doing so would keep its `emitted`
+ * entry: watchChange drops it, its group mark, and the cached "use client"
+ * answer for an edited dependency (isClientModule memoizes per resolved
+ * file; buildStart resets it).
  */
-export declare function clientUrlsRevalidateHoistPlugin(): Plugin[];
+export declare function clientUrlsRevalidateHoistPlugin(index: ClientUrlRevalidateIndex): Plugin[];
 export {};

package/dist/types/vite/plugins/hoist/source.d.ts

@@ -31,11 +31,12 @@ export interface EmittedEntry<T> {
 }
 export declare function recordEmitted<T>(emitted: Map<string, EmittedEntry<T>>, file: string, value: T): Promise<void>;
 /**
- * What a `?rango-*` load serves for `hoistedFile`: the transform's emission
- * when it saw the current disk source (or the file is gone), else
- * `rehoist(disk)`. The transform hoists the pipeline code, which an earlier
- * plugin may have changed, so re-hoisting the disk source is the fallback only
- * for an environment loading before the RSC transform ran or for an edit the
- * RSC environment has not re-transformed yet. Undefined when neither exists.
+ * What a `?rango-*` load serves for `hoistedFile`, whose source on disk is
+ * `disk` (readSource): the transform's emission when it saw that source (or
+ * the file is gone), else `rehoist(disk)`. The transform hoists the pipeline
+ * code, which an earlier plugin may have changed, so re-hoisting the disk
+ * source is the fallback only for an environment loading before the RSC
+ * transform ran or for an edit the RSC environment has not re-transformed
+ * yet. Undefined when neither exists.
  */
-export declare function loadEmittedOrDisk<T>(emitted: ReadonlyMap<string, EmittedEntry<T>>, hoistedFile: string, rehoist: (disk: string) => Promise<T | undefined>): Promise<T | undefined>;
+export declare function loadEmittedOrDisk<T>(emitted: ReadonlyMap<string, EmittedEntry<T>>, hoistedFile: string, disk: string | null, rehoist: (disk: string) => Promise<T | undefined>): Promise<T | undefined>;

package/dist/types/vite/plugins/virtual-entries.d.ts

@@ -36,6 +36,12 @@ export declare const VIRTUAL_IDS: {
     readonly rsc: "virtual:rsc-router/entry.rsc.js";
     readonly version: "@rangojs/router:version";
 };
+/**
+ * Non-RSC environments (client, ssr) get only PACKAGE_VERSION: the build
+ * module's ROUTER_VERSIONS token is replaced in server chunks only, so a
+ * client import of the full module would throw a ReferenceError.
+ */
+export declare function getVirtualPackageVersionContent(): string;
 /** Dev: one stamp for both versions of every router, bumped on RSC edits. */
 export declare function getVirtualVersionContent(version: string): string;
 /**

package/dist/types/vite/utils/prerender-utils.d.ts

@@ -1,4 +1,11 @@
 export declare function encodePathParam(value: unknown): string;
+/**
+ * `ctx.reverse` of a build-time `getParams()`. Substitutes like the dev-mode
+ * one (`createReverseFunction`, router/prerender-match.ts): a missing required
+ * param throws `Missing param`, with or without a params object, instead of
+ * leaving a literal `:param` in the URL.
+ */
+export declare function createGetParamsReverse(routes: Record<string, string>): (name: string, params?: Record<string, string>) => string;
 export declare function substituteRouteParams(pattern: string, params: Record<string, string>, encode?: (value: string) => string): string;
 export declare function runWithConcurrency<T>(items: T[], concurrency: number, fn: (item: T) => Promise<void>): Promise<void>;
 export declare function groupByConcurrency<T extends {