@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/server/loader-registry.ts

@@ -6,13 +6,10 @@
  */
 
 import type { LoaderFn } from "../types.js";
-import type { MiddlewareFn } from "../router/middleware.js";
-import { getFetchableLoader } from "./fetchable-loader-store.js";
-
-interface RegisteredLoader {
-  fn: LoaderFn<any, any, any>;
-  middleware: MiddlewareFn[];
-}
+import {
+  getFetchableLoader,
+  type LoaderRegistryEntry,
+} from "./fetchable-loader-store.js";
 
 // Server-side cache - maps loader $$id to function and middleware
 // This is a CACHE populated by getLoaderLazy() when loaders are first accessed.
@@ -21,7 +18,7 @@ interface RegisteredLoader {
 // 1. Avoid repeated lookups/imports for the same loader
 // 2. Support lazy loading in production (loaders imported on-demand)
 // 3. Provide a stable reference for the RSC handler
-const loaderRegistry = new Map<string, RegisteredLoader>();
+const loaderRegistry = new Map<string, LoaderRegistryEntry>();
 
 // Lazy import map - set by the loader manifest
 // Maps loader $$id to a function that imports the loader module
@@ -37,28 +34,6 @@ export function setLoaderImports(
   lazyLoaderImports = new Map(Object.entries(imports));
 }
 
-/**
- * Register a fetchable loader by $$id
- * Called by createLoader when fetchable option is provided
- */
-export function registerLoader(
-  id: string,
-  fn: LoaderFn<any, any, any>,
-  middleware: MiddlewareFn[] = [],
-): void {
-  // Always update the registry entry. During HMR, the module is re-executed
-  // with the new loader function, so we must replace the stale reference.
-  loaderRegistry.set(id, { fn, middleware });
-}
-
-/**
- * Get a registered loader by $$id (synchronous)
- * Returns undefined if loader is not registered
- */
-export function getLoader(id: string): RegisteredLoader | undefined {
-  return loaderRegistry.get(id);
-}
-
 /**
  * Get a loader by $$id, loading it lazily if needed
  * This is the primary method for the RSC handler to get loaders
@@ -68,21 +43,22 @@ export function getLoader(id: string): RegisteredLoader | undefined {
  */
 export async function getLoaderLazy(
   id: string,
-): Promise<RegisteredLoader | undefined> {
-  // Check if already cached in main registry
-  const existing = loaderRegistry.get(id);
-  if (existing) {
-    return existing;
-  }
-
-  // Check the fetchable loader registry (populated by createLoader)
+): Promise<LoaderRegistryEntry | undefined> {
+  // Always check fetchableLoaderRegistry first — it's the source of truth.
+  // createLoader() updates it during module re-evaluation (HMR), so checking
+  // here ensures we pick up the fresh function after a loader file change.
   const fetchable = getFetchableLoader(id);
   if (fetchable) {
-    // Cache in main registry for future requests
     loaderRegistry.set(id, fetchable);
     return fetchable;
   }
 
+  // Fall back to local cache (populated by previous lazy imports in production)
+  const existing = loaderRegistry.get(id);
+  if (existing) {
+    return existing;
+  }
+
   // Try to lazy load from the import map (production mode)
   if (lazyLoaderImports && lazyLoaderImports.size > 0) {
     const lazyImport = lazyLoaderImports.get(id);
@@ -128,20 +104,6 @@ export async function getLoaderLazy(
   return undefined;
 }
 
-/**
- * Check if a loader is registered by $$id
- */
-export function hasLoader(id: string): boolean {
-  return loaderRegistry.has(id) || getFetchableLoader(id) !== undefined;
-}
-
-/**
- * Get all registered loader IDs (for debugging)
- */
-export function getRegisteredLoaderIds(): string[] {
-  return Array.from(loaderRegistry.keys());
-}
-
 /**
  * Register a loader by its $$id (injected by Vite plugin)
  * This is called during module loading to cache loaders
@@ -163,6 +125,10 @@ export function registerLoaderById(loader: {
 
   // Fall back to using fn from the loader object (non-fetchable loaders)
   if (loader.fn) {
-    loaderRegistry.set(loader.$$id, { fn: loader.fn, middleware: [] });
+    loaderRegistry.set(loader.$$id, {
+      fn: loader.fn,
+      middleware: [],
+      fetchable: false,
+    });
   }
 }

package/src/server/request-context.ts

@@ -14,21 +14,35 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import type { CookieOptions } from "../router/middleware.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
 import type { ScopedReverseFunction } from "../reverse.js";
-import type { DefaultReverseRouteMap } from "../types/global-namespace.js";
+import type {
+  DefaultEnv,
+  DefaultReverseRouteMap,
+  DefaultRouteName,
+} from "../types/global-namespace.js";
 import type { Handle } from "../handle.js";
-import { type ContextVar, contextGet, contextSet } from "../context-var.js";
+import {
+  type ContextVar,
+  contextGet,
+  contextSet,
+  isNonCacheable,
+} from "../context-var.js";
 import { createHandleStore, type HandleStore } from "./handle-store.js";
 import { isHandle } from "../handle.js";
-import { track } from "./context.js";
+import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import { THEME_COOKIE } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
-import { createReverseFunction } from "../router/handler-context.js";
-import { getGlobalRouteMap } from "../route-map-builder.js";
+import { isInsideCacheScope } from "./context.js";
+import {
+  createReverseFunction,
+  stripInternalParams,
+} from "../router/handler-context.js";
+import { getGlobalRouteMap, isRouteRootScoped } from "../route-map-builder.js";
 import { invariant } from "../errors.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 
 /**
  * Unified request context available via getRequestContext()
@@ -37,21 +51,26 @@ import { invariant } from "../errors.js";
  * Use this when you need access to request data outside of route handlers.
  */
 export interface RequestContext<
-  TEnv = unknown,
+  TEnv = DefaultEnv,
   TParams = Record<string, string>,
 > {
   /** Platform bindings (Cloudflare env, etc.) */
   env: TEnv;
   /** Original HTTP request */
   request: Request;
-  /** Parsed URL (system params like _rsc* are NOT filtered here) */
+  /** Parsed URL (with internal `_rsc*` params stripped) */
   url: URL;
+  /**
+   * The original request URL with all parameters intact, including
+   * internal `_rsc*` transport params.
+   */
+  originalUrl: URL;
   /** URL pathname */
   pathname: string;
-  /** URL search params (system params like _rsc* are NOT filtered here) */
+  /** URL search params (with internal `_rsc*` params stripped, same as `url.searchParams`) */
   searchParams: URLSearchParams;
-  /** Variables set by middleware (same as ctx.var) */
-  var: Record<string, any>;
+  /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
+  _variables: Record<string, any>;
   /** Get a variable set by middleware */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -59,20 +78,19 @@ export interface RequestContext<
   };
   /** Set a variable (shared with middleware and handlers) */
   set: {
-    <T>(contextVar: ContextVar<T>, value: T): void;
-    <K extends string>(key: K, value: any): void;
+    <T>(
+      contextVar: ContextVar<T>,
+      value: T,
+      options?: { cache?: boolean },
+    ): void;
+    <K extends string>(key: K, value: any, options?: { cache?: boolean }): void;
   };
   /**
    * Route params (populated after route matching)
    * Initially empty, then set to matched params
    */
   params: TParams;
-  /**
-   * Stub response for setting headers/cookies (read-only).
-   * Headers set here are merged into the final response.
-   * Use header() or setStatus() to mutate response headers/status.
-   * Use cookies().set()/cookies().delete() for cookie mutations.
-   */
+  /** @internal Stub response for collecting headers/cookies. Use ctx.headers or ctx.header() instead. */
   readonly res: Response;
 
   /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
@@ -90,6 +108,8 @@ export interface RequestContext<
   header(name: string, value: string): void;
   /** Set the response status code */
   setStatus(status: number): void;
+  /** @internal Set status bypassing cache-exec guard (for framework error handling) */
+  _setStatus(status: number): void;
 
   /**
    * Access loader data or push handle data.
@@ -128,6 +148,12 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /** @internal Cache profiles for "use cache" profile resolution (per-router) */
+  _cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+
   /**
    * Schedule work to run after the response is sent.
    * On Cloudflare Workers, uses ctx.waitUntil().
@@ -214,14 +240,21 @@ export interface RequestContext<
    *
    * @example
    * ```typescript
-   * ctx.setLocationState([Flash({ text: "Item saved!" })]);
+   * ctx.setLocationState(Flash({ text: "Item saved!" }));
    * ```
    */
-  setLocationState(entries: LocationStateEntry[]): void;
+  setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
 
   /** @internal Accumulated location state entries */
   _locationState?: LocationStateEntry[];
 
+  /**
+   * The matched route name, if the route has an explicit name.
+   * Undefined before route matching or for unnamed routes.
+   * Includes the namespace prefix from include() (e.g., "blog.post").
+   */
+  routeName?: DefaultRouteName;
+
   /**
    * Generate URLs from route names.
    * Uses the global route map. After route matching, scoped (`.name`) resolution
@@ -234,6 +267,29 @@ export interface RequestContext<
 
   /** @internal Route name from route matching, used for scoped reverse resolution */
   _routeName?: string;
+
+  /** @internal Previous route key (from the navigation source), used for revalidation */
+  _prevRouteKey?: string;
+
+  /** @internal Per-request error dedup set for onError reporting */
+  _reportedErrors: WeakSet<object>;
+
+  /**
+   * @internal Report a non-fatal background error through the router's
+   * onError callback. Wired by the RSC handler / router during request
+   * creation. Cache-runtime and other subsystems call this to surface
+   * errors without failing the response.
+   */
+  _reportBackgroundError?: (error: unknown, category: string) => void;
+
+  /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
+  _debugPerformance?: boolean;
+
+  /** @internal Request-scoped performance metrics store */
+  _metricsStore?: MetricsStore;
+
+  /** @internal Router basename for this request (used by redirect()) */
+  _basename?: string;
 }
 
 /**
@@ -243,7 +299,7 @@ export interface RequestContext<
  * use the full RequestContext interface directly.
  */
 export type PublicRequestContext<
-  TEnv = unknown,
+  TEnv = DefaultEnv,
   TParams = Record<string, string>,
 > = Omit<
   RequestContext<TEnv, TParams>,
@@ -253,10 +309,20 @@ export type PublicRequestContext<
   | "deleteCookie"
   | "_handleStore"
   | "_cacheStore"
+  | "_cacheProfiles"
   | "_onResponseCallbacks"
   | "_themeConfig"
   | "_locationState"
   | "_routeName"
+  | "_prevRouteKey"
+  | "_reportedErrors"
+  | "_reportBackgroundError"
+  | "_debugPerformance"
+  | "_metricsStore"
+  | "_basename"
+  | "_setStatus"
+  | "_variables"
+  | "res"
 >;
 
 // AsyncLocalStorage instance for request context
@@ -277,7 +343,7 @@ export function runWithRequestContext<TEnv, T>(
  * Get the current request context
  * Throws if called outside of a request context
  */
-export function getRequestContext<TEnv = unknown>(): RequestContext<TEnv> {
+export function getRequestContext<TEnv = DefaultEnv>(): RequestContext<TEnv> {
   const ctx = requestContextStorage.getStore() as
     | RequestContext<TEnv>
     | undefined;
@@ -294,7 +360,7 @@ export function getRequestContext<TEnv = unknown>(): RequestContext<TEnv> {
  * @internal Get the request context without throwing — for internal code that
  * may run outside a request context (cache stores, optional handle lookups, etc.)
  */
-export function _getRequestContext<TEnv = unknown>():
+export function _getRequestContext<TEnv = DefaultEnv>():
   | RequestContext<TEnv>
   | undefined {
   return requestContextStorage.getStore() as RequestContext<TEnv> | undefined;
@@ -313,9 +379,34 @@ export function setRequestContextParams(
     ctx.params = params;
     if (routeName !== undefined) {
       ctx._routeName = routeName;
+      ctx.routeName = (
+        routeName && !isAutoGeneratedRouteName(routeName)
+          ? routeName
+          : undefined
+      ) as DefaultRouteName | undefined;
     }
     // Update reverse with scoped resolution now that route is known
-    ctx.reverse = createReverseFunction(getGlobalRouteMap(), routeName, params);
+    ctx.reverse = createReverseFunction(
+      getGlobalRouteMap(),
+      routeName,
+      params,
+      routeName ? isRouteRootScoped(routeName) : undefined,
+    );
+  }
+}
+
+/**
+ * Store the previous route key on the request context.
+ * Called during partial-match context creation to make the navigation source
+ * route key available for revalidation and intercept evaluation.
+ * @internal
+ */
+export function setRequestContextPrevRouteKey(
+  prevRouteKey: string | undefined,
+): void {
+  const ctx = requestContextStorage.getStore();
+  if (ctx && prevRouteKey !== undefined) {
+    ctx._prevRouteKey = prevRouteKey;
   }
 }
 
@@ -334,7 +425,9 @@ export function getLocationState(): LocationStateEntry[] | undefined {
  * Get the current request context, throwing if not available
  * @deprecated Use getRequestContext() directly — it now throws if outside context
  */
-export function requireRequestContext<TEnv = unknown>(): RequestContext<TEnv> {
+export function requireRequestContext<
+  TEnv = DefaultEnv,
+>(): RequestContext<TEnv> {
   return getRequestContext<TEnv>();
 }
 
@@ -354,8 +447,15 @@ export interface CreateRequestContextOptions<TEnv> {
   request: Request;
   url: URL;
   variables: Record<string, any>;
+  /** Optional initial response stub headers/status to seed effective cookie reads */
+  initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /** Optional cache profiles for "use cache" resolution (per-router) */
+  cacheProfiles?: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
   /** Optional Cloudflare execution context for waitUntil support */
   executionContext?: ExecutionContext;
   /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
@@ -378,7 +478,9 @@ export function createRequestContext<TEnv>(
     request,
     url,
     variables,
+    initialResponse,
     cacheStore,
+    cacheProfiles,
     executionContext,
     themeConfig,
   } = options;
@@ -387,7 +489,13 @@ export function createRequestContext<TEnv>(
 
   // Create stub response for collecting headers/cookies.
   // All cookie/header mutations go here; cookie reads derive from it.
-  let stubResponse = new Response(null, { status: 200 });
+  let stubResponse = initialResponse
+    ? new Response(null, {
+        status: initialResponse.status,
+        statusText: initialResponse.statusText,
+        headers: new Headers(initialResponse.headers),
+      })
+    : new Response(null, { status: 200 });
 
   // Create handle store and loader memoization for this request
   const handleStore = createHandleStore();
@@ -413,6 +521,18 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
+  // Guard: throw if a response-level side effect is called inside a cache() scope.
+  // Uses ALS to detect the scope (set during segment resolution).
+  function assertNotInsideCacheScopeALS(methodName: string): void {
+    if (isInsideCacheScope()) {
+      throw new Error(
+        `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+          `On cache hit the handler is skipped, so this side effect would be lost. ` +
+          `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+      );
+    }
+  }
+
   // Effective cookie read: response stub Set-Cookie wins, then original header.
   // The stub IS the source of truth for same-request mutations.
   const effectiveCookie = (name: string): string | undefined => {
@@ -465,19 +585,31 @@ export function createRequestContext<TEnv>(
     invalidateResponseCookieCache();
   };
 
+  // Strip internal _rsc* params so userland sees a clean URL.
+  const cleanUrl = stripInternalParams(url);
+
   // Build the context object first (without use), then add use
   const ctx: RequestContext<TEnv> = {
     env,
     request,
-    url,
+    url: cleanUrl,
+    originalUrl: new URL(request.url),
     pathname: url.pathname,
-    searchParams: url.searchParams,
-    var: variables,
-    get: ((keyOrVar: any) =>
-      contextGet(variables, keyOrVar)) as RequestContext<TEnv>["get"],
-    set: ((keyOrVar: any, value: any) => {
+    searchParams: cleanUrl.searchParams,
+    _variables: variables,
+    get: ((keyOrVar: any) => {
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as RequestContext<TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: any) => {
       assertNotInsideCacheExec(ctx, "set");
-      contextSet(variables, keyOrVar, value);
+      contextSet(variables, keyOrVar, value, options);
     }) as RequestContext<TEnv>["set"],
     params: {} as Record<string, string>,
 
@@ -515,6 +647,7 @@ export function createRequestContext<TEnv>(
 
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
+      assertNotInsideCacheScopeALS("setCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, value, options),
@@ -527,6 +660,7 @@ export function createRequestContext<TEnv>(
       options?: Pick<CookieOptions, "domain" | "path">,
     ): void {
       assertNotInsideCacheExec(ctx, "deleteCookie");
+      assertNotInsideCacheScopeALS("deleteCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, "", { ...options, maxAge: 0 }),
@@ -536,13 +670,20 @@ export function createRequestContext<TEnv>(
 
     header(name: string, value: string): void {
       assertNotInsideCacheExec(ctx, "header");
+      assertNotInsideCacheScopeALS("header");
       stubResponse.headers.set(name, value);
     },
 
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
-      // Response.status is read-only, so we must create a new Response.
-      // Headers are passed by reference — no cookie cache invalidation needed.
+      assertNotInsideCacheScopeALS("setStatus");
+      stubResponse = new Response(null, {
+        status,
+        headers: stubResponse.headers,
+      });
+    },
+
+    _setStatus(status: number): void {
       stubResponse = new Response(null, {
         status,
         headers: stubResponse.headers,
@@ -556,6 +697,7 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
@@ -573,6 +715,7 @@ export function createRequestContext<TEnv>(
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");
+      assertNotInsideCacheScopeALS("onResponse");
       this._onResponseCallbacks.push(callback);
     },
 
@@ -588,14 +731,18 @@ export function createRequestContext<TEnv>(
       : undefined,
     _themeConfig: themeConfig,
 
-    setLocationState(entries: LocationStateEntry[]): void {
+    setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void {
       assertNotInsideCacheExec(ctx, "setLocationState");
+      const arr = Array.isArray(entries) ? entries : [entries];
       this._locationState = this._locationState
-        ? [...this._locationState, ...entries]
-        : entries;
+        ? [...this._locationState, ...arr]
+        : arr;
     },
     _locationState: undefined,
 
+    _reportedErrors: new WeakSet<object>(),
+    _metricsStore: undefined,
+
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
@@ -774,13 +921,13 @@ export function createUseFunction<TEnv>(
     // Create loader context with recursive use() support
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
+      routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
       searchParams: ctx.searchParams,
       search: (ctx as any).search ?? {},
       pathname: ctx.pathname,
       url: ctx.url,
       env: ctx.env as any,
-      var: ctx.var as any,
       get: ctx.get as any,
       use: <TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
@@ -794,11 +941,11 @@ export function createUseFunction<TEnv>(
         getGlobalRouteMap(),
         ctx._routeName,
         ctx.params as Record<string, string>,
+        ctx._routeName ? isRouteRootScoped(ctx._routeName) : undefined,
       ),
     };
 
-    // Start loader execution with tracking
-    const doneLoader = track(`loader:${loader.$$id}`);
+    const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
       doneLoader();
     });

package/src/server.ts

@@ -11,6 +11,12 @@
 // Router registry (used by Vite plugin for build-time discovery)
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router.js";
 
+// Host router registry (used by Vite plugin for host-router lazy discovery)
+export {
+  HostRouterRegistry,
+  type HostRouterRegistryEntry,
+} from "./host/router.js";
+
 // Route map builder (Vite plugin injects these via virtual modules)
 export {
   registerRouteMap,