@rangojs/router 0.27.0 → 0.28.0

package/src/rsc/response-cache-serve.ts

@@ -5,18 +5,13 @@
  * matched entry tree, condition eval, key resolution (route key() > store
  * keyGenerator > default, CacheScope.resolveKeyFrom), tag resolution,
  * pre-handler-callback timing, and the fresh-hit / SWR-revalidate /
- * miss-write branches — for BOTH the production
- * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
- * primitive (testing/dispatch.ts), so the two can never drift.
+ * miss-write branches — for the response-route handler
+ * (rsc/response-route-handler.ts), which the production handler and the
+ * dispatch testing primitive both run (rsc/request-stages.ts
+ * serveResponseRoute), so the two can never drift.
  *
- * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
- * which the non-Vite unit-test runner cannot resolve, and this module is on the
- * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` is
- * NOT imported here at runtime — it is INJECTED by the caller (production
- * imports it statically; dispatch lazy-imports it only once a response route
- * matches). The only runtime imports here are plugin-rsc-free
- * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
- * type-only import (erased at build).
+ * `createCacheScope` is injected by the caller: the response-route handler
+ * passes the real one, unit tests a stub.
  */
 
 import { isRewrite } from "../route-definition/rewrite.js";
@@ -44,7 +39,7 @@ import {
 } from "../cache/tag-invalidation.js";
 import { hasPerClientSignal } from "../browser/cookie-name.js";
 
-/** Injected cache-scope builder (kept off this module's runtime import graph). */
+/** Injected cache-scope builder. */
 export interface CacheScopeDeps {
   createCacheScope: (
     config: EntryCacheConfig | undefined,
@@ -110,8 +105,9 @@ export async function serveResponseRouteWithCache(
   let cacheKey = `response:${responseType}:${requestKeyBase(reqCtx, url.host, url.pathname, url.searchParams, undefined, reqCtx._searchParamsFilter)}`;
 
   // Keyed like the segment record (CacheScope.resolveKeyFrom): with key()
-  // results on the cache() chain (a full override, namespaced, #975) or an
-  // enclosing scope on another store whose keyGenerator partitions (#974),
+  // results on the cache() chain (they replace the URL part, namespaced,
+  // #975; a response entry has no request kind to keep) or an enclosing
+  // scope on another store whose keyGenerator partitions (#974),
   // `response:` plus the composed key, so a nested cache() never shares an
   // entry across the enclosing partitions (#970); otherwise the store's
   // keyGenerator result (it modifies the default key), else the default key.

package/src/rsc/response-route-handler.ts

@@ -24,7 +24,7 @@ import {
   assertNonCacheableReadAllowed,
   type EntryData,
 } from "../server/context.js";
-import type { HandlerContext } from "./handler-context.js";
+import type { RequestStageContext } from "./request-stages.js";
 import { createProblemDetails } from "./response-error.js";
 import {
   createReloadResponse,
@@ -36,6 +36,7 @@ import {
 } from "./helpers.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import { stringifyJsonRouteResult } from "./json-route-result.js";
+import { WIRE } from "../wire-params.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -57,14 +58,17 @@ export interface ResponseRouteMatch {
  * so the browser triggers a hard navigation to the response route URL.
  */
 export async function handleResponseRoute<TEnv>(
-  handlerCtx: HandlerContext<TEnv>,
+  handlerCtx: Pick<
+    RequestStageContext<TEnv>,
+    "callOnError" | "getRequiredRouteMap" | "reportResponseRouteError"
+  >,
   preview: ResponseRouteMatch,
   request: Request,
   env: TEnv,
   url: URL,
   variables: Record<string, any>,
 ): Promise<Response> {
-  const isPartial = url.searchParams.has("_rsc_partial");
+  const isPartial = url.searchParams.has(WIRE.partial);
 
   // Partial requests (client-side navigation) to response routes
   // get X-RSC-Reload to trigger hard navigation in the browser
@@ -122,7 +126,7 @@ export async function handleResponseRoute<TEnv>(
         // Runtime guard: the json() return type rejects nested Promises at
         // compile time, but an `as`-cast or untyped (JS) handler can still slip
         // one through. stringifyJsonRouteResult throws a clear error instead of
-        // shipping empty data (shared with dispatch() so the two cannot drift).
+        // shipping empty data.
         const body = stringifyJsonRouteResult(result);
         return createResponseWithMergedHeaders(body, {
           status: 200,
@@ -145,7 +149,11 @@ export async function handleResponseRoute<TEnv>(
         `Response route handler for "${preview.responseType}" must return a Response object, got ${typeof result}`,
       );
     } catch (error) {
-      handlerCtx.callOnError(error, "handler", errorCtx);
+      if (handlerCtx.reportResponseRouteError) {
+        handlerCtx.reportResponseRouteError(error, errorCtx);
+      } else {
+        handlerCtx.callOnError(error, "handler", errorCtx);
+      }
       const isDev = process.env.NODE_ENV !== "production";
       const derivedStatus = error instanceof RouterError ? error.status : 500;
       // Resolve the effective status the same way createResponseWithMergedHeaders

package/src/rsc/rewrite-passes.ts

@@ -26,6 +26,7 @@ import {
   recordRewriteHop,
   recordRewriteShell,
 } from "../server/rewrite-trail.js";
+import { WIRE } from "../wire-params.js";
 
 /** Response header naming the route path a rewritten request rendered. */
 export const REWRITE_HEADER = "x-rango-rewrite";
@@ -138,7 +139,7 @@ export function applyRewrite(
 ): RewritePass {
   // A loader fetch first: `load()` with a body is a POST, and its refusal
   // is the loader fetch's.
-  if (reqCtx.originalUrl.searchParams.has("_rsc_loader")) {
+  if (reqCtx.originalUrl.searchParams.has(WIRE.loader)) {
     throw rewriteNotSupported(rewrite, "loader-fetch");
   }
   if (passRequest.method !== "GET" && passRequest.method !== "HEAD") {

package/src/rsc/routine-plan.ts

@@ -74,7 +74,7 @@ export function* step<T>(
  *
  * Settlement tracking follows the RETURNED value: a returned promise is
  * observed until it settles; a scheduler that fires-and-forgets internally
- * (e.g. scheduleShellCapture via runBackground) returns void, so its trace
+ * (e.g. planShellCapture via runBackground) returns void, so its trace
  * entry settles at the scheduling call, not at background completion. That is
  * deliberate — the plan's contract ends at the handoff.
  */