@rangojs/router 0.24.3 → 0.25.0

package/src/route-definition/rewrite.ts

@@ -27,11 +27,10 @@ export type RewriteTarget =
 
 const REWRITE_RULE =
   "rewrite() is for middleware: throw it from router.use() or route " +
-  "middleware (middleware() in urls()), before await next(), while it " +
-  "handles a GET or HEAD page request. Loaders and route handlers can't " +
-  "rewrite: throw rewrite() from the route's middleware instead. Intercept " +
-  "middleware and loader fetches can't either. In a server action use " +
-  "redirect(); for a mutation return a Response from middleware.";
+  "middleware (middleware() in urls()), before await next(). Loaders and " +
+  "route handlers can't rewrite: throw rewrite() from the route's " +
+  "middleware instead. Middleware in loader fetches can't either. In a " +
+  "server action use redirect().";
 
 export function describeRewriteTarget(target: RewriteTarget): string {
   return "path" in target
@@ -39,6 +38,17 @@ export function describeRewriteTarget(target: RewriteTarget): string {
     : `rewrite(${JSON.stringify(target.name)})`;
 }
 
+/**
+ * Which PPR shell a rewritten request reads and captures
+ * (`rewrite(...).shell()`); without a call, none.
+ * - `"visitor"`: its own, keyed by the visitor's URL and the target, captured
+ *   with the visitor's location and `ctx.rewrittenFrom`.
+ * - `"target"`: the target's shared shell. `usePathname()` reads the target's
+ *   path on a HIT, and values set before the throw are baked in: for a page
+ *   that renders neither (a lock or promo page).
+ */
+export type RewriteShell = "visitor" | "target";
+
 /**
  * The value `rewrite()` returns, thrown by middleware. An Error, so a throw
  * where a rewrite is not supported fails loudly with the rule in its message.
@@ -46,11 +56,60 @@ export function describeRewriteTarget(target: RewriteTarget): string {
 export class Rewrite extends Error {
   name = "Rewrite" as const;
   readonly target: RewriteTarget;
+  /** The `shell()` choice; undefined: no shell. */
+  readonly shellAudience: RewriteShell | undefined;
+  /** `disallowMutations()`: a mutation is refused, not moved, before its action runs. */
+  readonly mutationsDisallowed: boolean;
 
-  constructor(target: RewriteTarget) {
+  constructor(
+    target: RewriteTarget,
+    shellAudience?: RewriteShell,
+    mutationsDisallowed = false,
+  ) {
     super(`${describeRewriteTarget(target)}: ${REWRITE_RULE}`);
     Object.setPrototypeOf(this, Rewrite.prototype);
     this.target = target;
+    this.shellAudience = shellAudience;
+    this.mutationsDisallowed = mutationsDisallowed;
+  }
+
+  /**
+   * A copy that picks the PPR shell of a `ppr` target ({@link RewriteShell}),
+   * so a rewrite kept in a module constant keeps its own choice:
+   *
+   * ```ts
+   * throw rewrite("item", { id }).shell("visitor");
+   * ```
+   */
+  shell(audience: RewriteShell): Rewrite {
+    if (audience !== "visitor" && audience !== "target") {
+      throw new TypeError(
+        `${describeRewriteTarget(this.target)}.shell() takes "visitor" or "target", not ${JSON.stringify(audience)}.`,
+      );
+    }
+    return new Rewrite(this.target, audience, this.mutationsDisallowed);
+  }
+
+  /**
+   * A copy for a lock: global middleware's rewrite of a mutation (a server
+   * action, a form post, any non-GET request) is an error before the action
+   * runs, instead of moving the mutation to the target. GET and HEAD rewrite
+   * as usual.
+   *
+   * ```ts
+   * throw rewrite("maintenance").disallowMutations();
+   * ```
+   *
+   * Route middleware runs after the action, so there it cannot refuse it: the
+   * render moves to the target, dev warns, and production logs one error.
+   */
+  disallowMutations(): Rewrite {
+    if (arguments.length > 0) {
+      throw new TypeError(
+        `${describeRewriteTarget(this.target)}.disallowMutations() takes no arguments.`,
+      );
+    }
+    return new Rewrite(this.target, this.shellAudience, true);
   }
 }
 Object.defineProperty(Rewrite.prototype, REWRITE_BRAND, { value: true });
@@ -107,31 +166,39 @@ function createRewrite(
  * ```ts
  * router.use(async (ctx, next) => {
  *   if (!locked || ctx.pathname === "/maintenance") return next();
- *   throw rewrite("maintenance");
+ *   throw rewrite("maintenance").disallowMutations();
  * });
  * ```
  *
  * The request runs again as the target (global middleware, route
  * middleware, render) with the same request context: values set before the
  * throw stay readable. `ctx.url` is the target; `ctx.rewrittenFrom` is the
- * visitor's URL. See the `/middleware` skill.
+ * visitor's URL. A mutation that global middleware rewrites moves to the
+ * target before its action runs, so the page's forms keep working; a lock
+ * refuses it with `.disallowMutations()`. A `ppr` target gets no shell unless
+ * `.shell()` picks one ({@link RewriteShell}). See the `/middleware` skill.
  */
 export const rewrite: RewriteFunction = createRewrite as RewriteFunction;
 
-/** A dispatch site that cannot honor a rewrite. */
-export type RewriteSite = "mutation" | "loader-fetch" | "intercept";
+/**
+ * A dispatch site that cannot honor a rewrite. "mutation" is the refusal
+ * `.disallowMutations()` asked for, not a misuse.
+ */
+export type RewriteSite = "mutation" | "body-read" | "loader-fetch";
 
 const SITE_MESSAGE: Record<RewriteSite, string> = {
   mutation:
-    "middleware threw it while handling a non-GET request (a server action " +
-    "or a form post). Return a Response for mutations instead, e.g. " +
-    'new Response("Maintenance", { status: 503 }).',
+    "refused a mutation: .disallowMutations() was set, so a server action " +
+    "or form post (any request but GET and HEAD) fails before its action " +
+    "runs. To answer it instead, return a Response for mutations from " +
+    'middleware, e.g. new Response("Maintenance", { status: 503 }).',
+  "body-read":
+    "is not supported here: middleware read the request body before it " +
+    "threw it, and the request moves to the target with its body for the " +
+    "action to read. Read a copy instead: ctx.request.clone().formData().",
   "loader-fetch":
-    "middleware threw it during a loader fetch (useFetchLoader, load(), " +
-    "useRefreshLoaders). Return a Response there.",
-  intercept:
-    "intercept middleware threw it. Rewrite from router.use() or the " +
-    "route's middleware(), or return a Response.",
+    "is not supported here: middleware threw it during a loader fetch " +
+    "(useFetchLoader, load(), useRefreshLoaders). Return a Response there.",
 };
 
 /** The error a rewrite becomes at a site that cannot honor it. */
@@ -140,7 +207,7 @@ export function rewriteNotSupported(
   site: RewriteSite,
 ): Error {
   return new Error(
-    `${describeRewriteTarget(rewrite.target)} is not supported here: ${SITE_MESSAGE[site]}`,
+    `${describeRewriteTarget(rewrite.target)} ${SITE_MESSAGE[site]}`,
     { cause: rewrite },
   );
 }

package/src/route-types.ts

@@ -160,7 +160,7 @@ export type IncludeItem = {
      * include cannot collide with siblings declared outside it.
      */
     includeScope?: string;
-  };
+  } & import("./server/context.js").IncludeScopePosition;
 };
 
 /**
@@ -221,7 +221,6 @@ export type ParallelUseItem =
   | NotFoundBoundaryItem
   | TransitionItem;
 export type InterceptUseItem =
-  | MiddlewareItem
   | LoaderItem
   | LoadingItem
   | LayoutItem

package/src/router/find-match.ts

@@ -21,6 +21,30 @@ function cloneMatchResult<TEnv>(
   return r ? { ...r, params: { ...r.params } } : null;
 }
 
+function describeUnownedTrieRoute(
+  pathname: string,
+  routeKey: string,
+  sp: string,
+  entries: RouteEntry[],
+): string {
+  const includes = entries
+    .filter((e) => e.staticPrefix === sp)
+    .map((e) => {
+      const prefix = (e as { _lazyPrefix?: string })._lazyPrefix;
+      if (prefix === undefined) return "root routes";
+      const names = e.lazyContext?.namePrefix;
+      return `include("${prefix}")${names ? ` naming "${names}.*"` : ""}`;
+    });
+  return (
+    `[@rangojs/router] The route trie matched "${pathname}" to route ` +
+    `"${routeKey}" under static prefix "${sp}", but no include there ` +
+    `registered that name at runtime (checked: ${includes.join(", ")}). ` +
+    `Build discovery and the runtime named this route differently, so it ` +
+    `cannot render. If this follows a route edit, reload the page; if it ` +
+    `persists, please report it with your route configuration.`
+  );
+}
+
 export interface FindMatchDeps<TEnv = any> {
   routesEntries: RouteEntry<TEnv>[];
   // Returns a Promise only when it had to resolve an async include provider
@@ -100,7 +124,7 @@ export function createFindMatch<TEnv = any>(
             // this loop may evaluate a candidate that is NOT the route's owner.
             // Remember the failure and keep scanning: if another candidate owns
             // the route, this sibling's failure is correctly isolated (its
-            // _lazyInflight was cleared, so a later request retries). But if NO
+            // in-flight import was cleared, so a later request retries). But if NO
             // candidate ends up owning it, the failing one WAS the owner — a
             // real, trie-matched route whose module failed to import — and we
             // rethrow below as a 5xx rather than silently 404ing (see finding 3:
@@ -130,6 +154,18 @@ export function createFindMatch<TEnv = any>(
           throw candidateError;
         }
 
+        // No candidate owns the trie's key (#1104): dev throws, production keeps the 404 fallback.
+        if (!entry && fallbackEntry && process.env.NODE_ENV !== "production") {
+          throw new Error(
+            describeUnownedTrieRoute(
+              pathname,
+              trieResult.routeKey,
+              trieResult.sp,
+              deps.routesEntries,
+            ),
+          );
+        }
+
         if (!entry) entry = fallbackEntry;
 
         if (!entry) {

package/src/router/handler-context.ts

@@ -20,6 +20,9 @@ import {
 import {
   assertCachedHeaderWriteAllowed,
   assertNonCacheableReadAllowed,
+  scopeReverse,
+  type ReverseScope,
+  type ScopableReverse,
 } from "../server/context.js";
 import {
   guardRequestHeaders,
@@ -117,22 +120,8 @@ function resolveRouteName(
         ? currentRoutePrefix.substring(0, lastDot)
         : currentRoutePrefix;
 
-    // Try prefixed name at current level
-    const prefixedName = `${prefix}.${lookupName}`;
-    if (routeMap[prefixedName] !== undefined) {
-      return routeMap[prefixedName];
-    }
-
-    // Walk up parent prefixes for nested includes
-    let currentPrefix = prefix;
-    while (currentPrefix.includes(".")) {
-      const parentDot = currentPrefix.lastIndexOf(".");
-      currentPrefix = currentPrefix.substring(0, parentDot);
-      const parentPrefixedName = `${currentPrefix}.${lookupName}`;
-      if (routeMap[parentPrefixedName] !== undefined) {
-        return routeMap[parentPrefixedName];
-      }
-    }
+    const scoped = resolveInPrefix(lookupName, routeMap, prefix);
+    if (scoped !== undefined) return scoped;
 
     // Fallback: try bare name at root scope only.
     // Routes inside { name: "" } mounts are at root scope — their dot-local
@@ -159,6 +148,43 @@ function resolveRouteName(
   return routeMap[name];
 }
 
+/**
+ * `${prefix}.${lookupName}`, then the same name under each enclosing include
+ * prefix (nested includes reach their parents' routes).
+ */
+function resolveInPrefix(
+  lookupName: string,
+  routeMap: Record<string, string>,
+  prefix: string,
+): string | undefined {
+  let currentPrefix = prefix;
+  for (;;) {
+    const pattern = routeMap[`${currentPrefix}.${lookupName}`];
+    if (pattern !== undefined) return pattern;
+    const parentDot = currentPrefix.lastIndexOf(".");
+    if (parentDot === -1) return undefined;
+    currentPrefix = currentPrefix.substring(0, parentDot);
+  }
+}
+
+/**
+ * Dot-local name resolved from a segment's own include scope (ReverseScope,
+ * server/context.ts) instead of the matched route's name: a layout, parallel
+ * slot or their loader in a parent module links within that module on every
+ * route below it.
+ */
+function resolveScopedName(
+  lookupName: string,
+  routeMap: Record<string, string>,
+  scope: ReverseScope,
+): string | undefined {
+  if (scope.prefix) {
+    const scoped = resolveInPrefix(lookupName, routeMap, scope.prefix);
+    if (scoped !== undefined) return scoped;
+  }
+  return scope.rootScoped ? routeMap[lookupName] : undefined;
+}
+
 function createPrerenderPassthroughFn(
   build: boolean,
   isPassthroughRoute: boolean,
@@ -180,6 +206,26 @@ function createPrerenderPassthroughFn(
   };
 }
 
+/**
+ * The ctx a layout's or parallel slot's handler gets: a prototype child of
+ * the request's one handler ctx with its own `reverse` in the segment's
+ * ReverseScope, so `.name` resolves in the module that declared the segment.
+ * The scope rides the object, not the call frame: it holds after an `await`
+ * and in a component the ctx is handed to. Every other field reads through
+ * live (`_currentSegmentId` as resolution moves it, ctx.set values).
+ * `_reverseScope` keys a "use cache" call that takes this ctx (cache-runtime.ts).
+ */
+export function withReverseScope<C>(
+  ctx: C,
+  scope: ReverseScope | undefined,
+): C {
+  if (scope === undefined) return ctx;
+  const scoped = Object.create(ctx as object);
+  scoped.reverse = scopeReverse((ctx as any).reverse, scope);
+  scoped._reverseScope = scope;
+  return scoped;
+}
+
 /**
  * Create a reverse function for URL generation from route names.
  * Used by both HandlerContext and MiddlewareContext.
@@ -188,41 +234,40 @@ function createPrerenderPassthroughFn(
  * generation. This enables auto-filling mount params from include() prefixes:
  * inner handlers can call ctx.reverse(".sibling") without explicitly passing
  * params that are already known from the current URL match.
- * Explicitly passed hrefParams take priority over currentParams.
+ * Explicitly passed hrefParams take priority over currentParams. A required
+ * param that neither supplies throws `Missing param`.
  */
 export function createReverseFunction(
   routeMap: Record<string, string>,
   currentRoutePrefix?: string,
   currentParams?: Record<string, string>,
   rootScoped?: boolean,
-): (
-  name: string,
-  hrefParams?: Record<string, string>,
-  search?: Record<string, unknown>,
-) => string {
-  return (name, hrefParams, search) => {
-    // Resolve route name with namespace support
-    const pattern = resolveRouteName(
-      name,
-      routeMap,
-      currentRoutePrefix,
-      rootScoped,
-    );
+): ScopableReverse {
+  return (name, hrefParams, search, segmentScope) => {
+    // A dot-local name from a segment's handler or loader resolves in the
+    // segment's own include scope (withReverseScope); everything else from
+    // the route's name.
+    const scope = name.startsWith(".") ? segmentScope : undefined;
+    const pattern = scope
+      ? resolveScopedName(name.slice(1), routeMap, scope)
+      : resolveRouteName(name, routeMap, currentRoutePrefix, rootScoped);
 
     if (pattern === undefined) {
-      throw new Error(
-        `Unknown route: "${name}"${currentRoutePrefix ? ` (current route: ${currentRoutePrefix})` : ""}`,
-      );
+      const where = scope
+        ? ` (segment scope: ${scope.prefix ?? "root"})`
+        : currentRoutePrefix
+          ? ` (current route: ${currentRoutePrefix})`
+          : "";
+      throw new Error(`Unknown route: "${name}"${where}`);
     }
 
-    // Merge current request params as defaults, explicit params override
-    const effectiveParams = currentParams
-      ? { ...currentParams, ...hrefParams }
-      : hrefParams;
+    // Merge current request params as defaults, explicit params override.
+    // Always substitute, even with no params at all (middleware and
+    // response-route reverse pass neither): a route with a required param
+    // must throw `Missing param`, never return its raw `:param` pattern.
+    const effectiveParams = { ...currentParams, ...hrefParams };
 
-    let result = effectiveParams
-      ? substitutePatternParams(pattern, effectiveParams, name)
-      : pattern;
+    let result = substitutePatternParams(pattern, effectiveParams, name);
 
     // Append search params as query string
     if (search) {