@rangojs/router 0.23.0 → 0.24.1

package/src/client-urls/client-urls.ts

@@ -154,12 +154,14 @@ interface LoadingItem extends ItemBase {
 
 interface FlattenContext {
   readonly layouts: readonly ComponentType[];
+  readonly layoutKeys: readonly number[];
   readonly loaders: readonly ClientUrlLoaderRecord[];
   readonly loading: ReactNode | undefined;
 }
 
 const EMPTY_CONTEXT: FlattenContext = {
   layouts: [],
+  layoutKeys: [],
   loaders: [],
   loading: undefined,
 };
@@ -588,6 +590,7 @@ function applyConfig(
 
   return {
     layouts: context.layouts,
+    layoutKeys: context.layoutKeys,
     loaders,
     loading,
   };
@@ -614,6 +617,7 @@ function addPathRecord(
       options,
       component: item.component,
       layouts: Object.freeze([...routeContext.layouts]),
+      layoutKeys: Object.freeze([...routeContext.layoutKeys]),
       loaders: Object.freeze([...routeContext.loaders]),
       loading: routeContext.loading,
       transition: transitionItem
@@ -625,6 +629,7 @@ function addPathRecord(
 
 function flattenLayout(
   item: LayoutItem,
+  ordinal: number,
   context: FlattenContext,
   routes: ClientUrlRouteRecord[],
 ): void {
@@ -633,6 +638,7 @@ function flattenLayout(
     {
       ...context,
       layouts: [...context.layouts, item.component],
+      layoutKeys: [...context.layoutKeys, ordinal],
     },
     item.children,
   );
@@ -650,11 +656,12 @@ function flattenRoutes(
   context: FlattenContext,
   routes: ClientUrlRouteRecord[],
 ): void {
+  let layoutOrdinal = 0;
   for (const item of items) {
     if (item.type === "path") {
       addPathRecord(item, context, routes);
     } else if (item.type === "layout") {
-      flattenLayout(item, context, routes);
+      flattenLayout(item, layoutOrdinal++, context, routes);
     }
   }
 }

package/src/client-urls/types.ts

@@ -105,6 +105,14 @@ export interface ClientUrlRouteRecord {
   readonly options: Readonly<ClientPathOptions> | undefined;
   readonly component: ComponentType;
   readonly layouts: readonly ComponentType[];
+  /**
+   * One per entry in `layouts`: the layout() item's ordinal among its sibling
+   * layout()s, its React key. Routes under the same layout() share it, so
+   * ClientUrlsRoot keeps that layout's instance across them (#1124). Keys only
+   * need to be unique among siblings: a differing parent layout remounts the
+   * whole subtree anyway.
+   */
+  readonly layoutKeys: readonly number[];
   readonly loaders: readonly ClientUrlLoaderRecord[];
   readonly loading: ReactNode | undefined;
   readonly transition: Readonly<ClientTransitionConfig> | undefined;

package/src/context-var.ts

@@ -125,8 +125,38 @@ export function contextGet(
   return variables[keyOrVar.key];
 }
 
-/** Keys that must never be used as string variable names */
-const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Keys that must never be used as string variable names, nor as a fetchable
+ * loader's request params (rsc/loader-fetch.ts).
+ */
+export const FORBIDDEN_KEYS: ReadonlySet<string> = new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+]);
+
+/**
+ * `target[key] = value` as an own data property, `__proto__` included: that
+ * assignment would call Object.prototype's setter and replace the target's
+ * prototype, which Flight refuses to serialize (#1109). Loader data parsed
+ * from JSON, cookie names and the like can carry the key.
+ */
+export function assignOwn(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void {
+  if (key === "__proto__") {
+    Object.defineProperty(target, key, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  } else {
+    target[key] = value;
+  }
+}
 
 export interface ContextSetOptions {
   /**

package/src/errors.ts

@@ -296,6 +296,25 @@ export function isSkip(value: unknown): value is Skip {
   return value instanceof Skip;
 }
 
+/**
+ * A request middleware rewrote (`throw rewrite()`) more than `maxHops` times,
+ * or to the URL it was on. Reported through `onError` (phase "routing") and
+ * answered with 508. `trail` lists the URLs, the visitor's first.
+ */
+export class RewriteLoopError extends Error {
+  name = "RewriteLoopError" as const;
+  readonly trail: readonly string[];
+
+  constructor(trail: readonly string[], maxHops: number) {
+    super(
+      `Infinite rewrite loop: ${trail.join(" -> ")}. A request is rewritten ` +
+        `at most ${maxHops} times, and never to the URL it is on.`,
+    );
+    Object.setPrototypeOf(this, RewriteLoopError.prototype);
+    this.trail = trail;
+  }
+}
+
 /**
  * Thrown by the partial updater when the server responds with a redirect payload
  * that carries location state. Caught by navigate() to re-navigate to the

package/src/handles/pushed-by.ts

@@ -49,6 +49,32 @@ type PushedBy = readonly (string | null)[] | undefined;
 const keysOf = (a: object | undefined, b: object | undefined): Set<string> =>
   new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
 
+/**
+ * `target` with the buckets of the segments in `ids` taken from `source`.
+ * A pushedBy record is a snapshot key like a handle's, so a bucket's values
+ * and the record of the runs that pushed them always come from the same
+ * snapshot. New containers; the value arrays are shared, as cloneHandleData
+ * (navigation-store.ts) shares them.
+ */
+export function withSegmentHandles(
+  target: HandleData,
+  source: HandleData,
+  ids: ReadonlySet<string>,
+): HandleData {
+  const out: HandleData = {};
+  for (const name of keysOf(target, source)) {
+    const buckets: Record<string, unknown[]> = {};
+    for (const [id, values] of Object.entries(target[name] ?? {})) {
+      if (!ids.has(id)) buckets[id] = values;
+    }
+    for (const [id, values] of Object.entries(source[name] ?? {})) {
+      if (ids.has(id)) buckets[id] = values;
+    }
+    if (Object.keys(buckets).length > 0) out[name] = buckets;
+  }
+  return out;
+}
+
 /**
  * The handle data after a partial response's snapshot `incoming` (each stream
  * yield holds everything the response pushed so far). A segment outside

package/src/index.rsc.ts

@@ -119,6 +119,14 @@ export {
   transition,
 } from "./route-definition.js";
 
+// Render another route at the same URL from middleware (throw rewrite()).
+export {
+  rewrite,
+  type Rewrite,
+  type RewriteFunction,
+} from "./route-definition/rewrite.js";
+export { RewriteLoopError } from "./errors.js";
+
 // Composition types for reusable callback factories
 export type {
   RouteUseItem,

package/src/index.ts

@@ -155,6 +155,13 @@ export function redirect(): never {
   throw serverOnlyStubError("redirect");
 }
 
+/**
+ * Error-throwing stub for server-only `rewrite` function.
+ */
+export function rewrite(): never {
+  throw serverOnlyStubError("rewrite");
+}
+
 // Handle API (universal - works on both server and client)
 export { createHandle, isHandle, type Handle } from "./handle.js";
 export {

package/src/response-utils.ts

@@ -60,3 +60,22 @@ export function isRedirectResponse(response: Response): boolean {
     Boolean(response.headers.get("Location"))
   );
 }
+
+/**
+ * Set a header on a response the router hands to the host, skipping a
+ * WebSocket upgrade (its headers are not to be touched) and swallowing the
+ * TypeError of immutable headers (a passed-through platform Response):
+ * instrumentation and debug headers never fail a request.
+ */
+export function trySetHeader(
+  response: Response,
+  name: string,
+  value: string,
+): void {
+  if (isWebSocketUpgradeResponse(response)) return;
+  try {
+    response.headers.set(name, value);
+  } catch {
+    // Immutable headers: drop the header, never the response.
+  }
+}

package/src/reverse.ts

@@ -149,6 +149,7 @@ export type ReverseFunction<TRoutes> = {
 export type ScopedReverseFunction<
   TLocalRoutes,
   TGlobalRoutes = TLocalRoutes,
+  TResult = string,
 > = {
   /**
    * Global route without params
@@ -159,7 +160,7 @@ export type ScopedReverseFunction<
     > extends true
       ? TName
       : never,
-  ): string;
+  ): TResult;
 
   /**
    * Global route with params
@@ -167,7 +168,7 @@ export type ScopedReverseFunction<
   <TName extends keyof TGlobalRoutes & string>(
     name: TName,
     params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>,
-  ): string;
+  ): TResult;
 
   /**
    * Global route with params and search
@@ -176,7 +177,7 @@ export type ScopedReverseFunction<
     name: TName,
     params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>,
     search: ResolveSearchSchema<ExtractSearchSchema<TGlobalRoutes, TName>>,
-  ): string;
+  ): TResult;
 
   /**
    * Dot-prefixed local route without params
@@ -187,7 +188,7 @@ export type ScopedReverseFunction<
     > extends true
       ? `.${TName}`
       : never,
-  ): string;
+  ): TResult;
 
   /**
    * Dot-prefixed local route with params
@@ -195,7 +196,7 @@ export type ScopedReverseFunction<
   <TName extends keyof TLocalRoutes & string>(
     name: `.${TName}`,
     params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>,
-  ): string;
+  ): TResult;
 
   /**
    * Dot-prefixed local route with params and search
@@ -204,7 +205,7 @@ export type ScopedReverseFunction<
     name: `.${TName}`,
     params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>,
     search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
-  ): string;
+  ): TResult;
 };
 
 /**
@@ -235,14 +236,16 @@ export type ScopedReverseFunction<
  * reverse(".post", { slug: "hello" })     // compile error: no include() scope
  * ```
  */
-export type GlobalReverseFunction<TGlobalRoutes> =
-  string extends keyof TGlobalRoutes
-    ? <TName extends string>(
-        name: Exclude<TName, `.${string}`>,
-        params?: Record<string, string>,
-        search?: Record<string, unknown>,
-      ) => string
-    : ScopedReverseFunction<{}, TGlobalRoutes>;
+export type GlobalReverseFunction<
+  TGlobalRoutes,
+  TResult = string,
+> = string extends keyof TGlobalRoutes
+  ? <TName extends string>(
+      name: Exclude<TName, `.${string}`>,
+      params?: Record<string, string>,
+      search?: Record<string, unknown>,
+    ) => TResult
+  : ScopedReverseFunction<{}, TGlobalRoutes, TResult>;
 
 /**
  * Extract local routes type from UrlPatterns

package/src/route-definition/redirect.ts

@@ -8,6 +8,7 @@ import {
   attachRedirectState,
   markExternalRedirect,
 } from "../redirect-origin.js";
+import { prefixBasename } from "../router/basename.js";
 
 /**
  * Create a soft redirect Response for middleware short-circuit
@@ -84,21 +85,7 @@ export function redirect(
   }
 
   // Auto-prefix root-relative URLs with basename for app-local redirects.
-  // Treat the URL as already-prefixed when the basename is followed by a path
-  // separator, a query, a fragment, or end-of-string, so "/admin?tab=x" and
-  // "/admin#frag" are not double-prefixed into "/admin/admin?tab=x".
-  const bn = _getRequestContext()?._basename;
-  let resolvedUrl = url;
-  if (
-    bn &&
-    url.startsWith("/") &&
-    url !== bn &&
-    !url.startsWith(bn + "/") &&
-    !url.startsWith(bn + "?") &&
-    !url.startsWith(bn + "#")
-  ) {
-    resolvedUrl = url === "/" ? bn : bn + url;
-  }
+  const resolvedUrl = prefixBasename(url, _getRequestContext()?._basename);
 
   const headers: Record<string, string> = {
     Location: resolvedUrl,

package/src/route-definition/rewrite.ts

@@ -0,0 +1,146 @@
+/**
+ * `throw rewrite(target)`: middleware renders another route at the same URL.
+ *
+ * The value only: what middleware throws and how the router recognizes it.
+ * The pass loop that honors it lives in rsc/rewrite-passes.ts, the hop trail
+ * in server/rewrite-trail.ts.
+ */
+
+import type { GlobalReverseFunction } from "../reverse.js";
+import type { DefaultReverseRouteMap } from "../types/global-namespace.js";
+
+/**
+ * Cross-realm brand: a Vite dev server can load this module twice (the RSC
+ * and the SSR graph), so `instanceof` alone misses a Rewrite from the other
+ * copy.
+ */
+const REWRITE_BRAND: unique symbol = Symbol.for("rango.rewrite");
+
+/** The target as written: a path, or a global route name with its params. */
+export type RewriteTarget =
+  | { readonly path: string }
+  | {
+      readonly name: string;
+      readonly params?: Record<string, string>;
+      readonly search?: Record<string, unknown>;
+    };
+
+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.";
+
+export function describeRewriteTarget(target: RewriteTarget): string {
+  return "path" in target
+    ? `rewrite(${JSON.stringify(target.path)})`
+    : `rewrite(${JSON.stringify(target.name)})`;
+}
+
+/**
+ * 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.
+ */
+export class Rewrite extends Error {
+  name = "Rewrite" as const;
+  readonly target: RewriteTarget;
+
+  constructor(target: RewriteTarget) {
+    super(`${describeRewriteTarget(target)}: ${REWRITE_RULE}`);
+    Object.setPrototypeOf(this, Rewrite.prototype);
+    this.target = target;
+  }
+}
+Object.defineProperty(Rewrite.prototype, REWRITE_BRAND, { value: true });
+
+/** Whether `value` is a Rewrite thrown by `rewrite()` (ctx.isRewrite). */
+export function isRewrite(value: unknown): value is Rewrite {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [REWRITE_BRAND]?: unknown })[REWRITE_BRAND] === true
+  );
+}
+
+/**
+ * `rewrite(path)` or `rewrite(name, params?, search?)`: a path in this app
+ * (basename-prefixed like `redirect()`, may carry `?search`), or a global
+ * route name with the params and search `ctx.reverse` takes.
+ */
+export type RewriteFunction<TRoutes = DefaultReverseRouteMap> = ((
+  path: `/${string}`,
+) => Rewrite) &
+  GlobalReverseFunction<TRoutes, Rewrite>;
+
+function createRewrite(
+  target: string,
+  params?: Record<string, string>,
+  search?: Record<string, unknown>,
+): Rewrite {
+  if (typeof target !== "string" || target === "") {
+    throw new TypeError(
+      'rewrite() takes a path starting with "/" or a global route name.',
+    );
+  }
+  if (target.startsWith("/")) {
+    if (params !== undefined || search !== undefined) {
+      throw new TypeError(
+        `rewrite(${JSON.stringify(target)}) takes params only with a route name, not with a path.`,
+      );
+    }
+    return new Rewrite({ path: target });
+  }
+  if (target.startsWith(".")) {
+    throw new TypeError(
+      `rewrite(${JSON.stringify(target)}): a rewrite resolves global route names only (no include() scope).`,
+    );
+  }
+  return new Rewrite({ name: target, params, search });
+}
+
+/**
+ * Render another route at the same URL. Throw it from middleware, before
+ * `await next()`:
+ *
+ * ```ts
+ * router.use(async (ctx, next) => {
+ *   if (!locked || ctx.pathname === "/maintenance") return next();
+ *   throw rewrite("maintenance");
+ * });
+ * ```
+ *
+ * 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.
+ */
+export const rewrite: RewriteFunction = createRewrite as RewriteFunction;
+
+/** A dispatch site that cannot honor a rewrite. */
+export type RewriteSite = "mutation" | "loader-fetch" | "intercept";
+
+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 }).',
+  "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.",
+};
+
+/** The error a rewrite becomes at a site that cannot honor it. */
+export function rewriteNotSupported(
+  rewrite: Rewrite,
+  site: RewriteSite,
+): Error {
+  return new Error(
+    `${describeRewriteTarget(rewrite.target)} is not supported here: ${SITE_MESSAGE[site]}`,
+    { cause: rewrite },
+  );
+}

package/src/route-map-builder.ts

@@ -8,6 +8,11 @@
  * See docs/manifests.md for the full data flow.
  */
 
+import {
+  nullPrototypeStaticChildren,
+  type TrieNode,
+} from "./router/route-trie-builder.js";
+
 let globalRouteMap: Record<string, string> = {};
 
 let cachedManifest: Record<string, string> | null = null;
@@ -86,8 +91,7 @@ export function clearCachedManifest(): void {
 // precomputed entries so multi-router setups (e.g. site + admin via
 // createHostRouter()) don't see each other's routes.
 const perRouterManifestMap: Map<string, Record<string, string>> = new Map();
-const perRouterTrieMap: Map<string, import("./build/route-trie.js").TrieNode> =
-  new Map();
+const perRouterTrieMap: Map<string, TrieNode> = new Map();
 const perRouterPrecomputedEntriesMap: Map<
   string,
   Array<{ staticPrefix: string; routes: Record<string, string> }>
@@ -132,11 +136,12 @@ export function getRouterManifest(
   return perRouterManifestMap.get(routerId);
 }
 
-export function setRouterTrie(
-  routerId: string,
-  trie: import("./build/route-trie.js").TrieNode,
-): void {
-  perRouterTrieMap.set(routerId, trie);
+/**
+ * Install a router's trie. A trie that arrives as JSON (the build manifest)
+ * or across the dev runner boundary gets null-prototype static maps first.
+ */
+export function setRouterTrie(routerId: string, trie: TrieNode): void {
+  perRouterTrieMap.set(routerId, nullPrototypeStaticChildren(trie));
 }
 
 // Routers whose trie came from the COMPLETE build manifest (deserialized via
@@ -156,9 +161,7 @@ export function isRouterTrieAuthoritative(routerId: string): boolean {
   return authoritativeTrieRouters.has(routerId);
 }
 
-export function getRouterTrie(
-  routerId: string,
-): import("./build/route-trie.js").TrieNode | undefined {
+export function getRouterTrie(routerId: string): TrieNode | undefined {
   return perRouterTrieMap.get(routerId);
 }
 
@@ -199,7 +202,7 @@ export async function ensureRouterManifest(routerId: string): Promise<void> {
   if (loader) {
     const mod = await loader();
     if (mod.trie) {
-      perRouterTrieMap.set(routerId, mod.trie);
+      setRouterTrie(routerId, mod.trie);
       // A trie serialized into the build manifest comes from complete
       // discovery — misses are authoritative 404s (see find-match.ts).
       markRouterTrieAuthoritative(routerId);

package/src/router/basename.ts

@@ -12,3 +12,23 @@ export function normalizeBasename(basename?: string): string | undefined {
   const trimmed = basename.replace(/^\/+|\/+$/g, "");
   return trimmed ? "/" + trimmed : undefined;
 }
+
+/**
+ * Prefix a root-relative path with the basename unless it already carries it
+ * (the basename followed by "/", "?", "#" or the end), so "/admin?tab=x" and
+ * "/admin#frag" under basename "/admin" are not prefixed twice. Shared by
+ * redirect(), rewrite() and useRouter().
+ */
+export function prefixBasename(path: string, basename?: string): string {
+  if (
+    !basename ||
+    !path.startsWith("/") ||
+    path === basename ||
+    path.startsWith(basename + "/") ||
+    path.startsWith(basename + "?") ||
+    path.startsWith(basename + "#")
+  ) {
+    return path;
+  }
+  return path === "/" ? basename : basename + path;
+}

package/src/router/handler-context.ts

@@ -30,6 +30,7 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
 import { substitutePatternParams } from "./substitute-pattern-params.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
+import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 
 // Mutating Headers methods guarded so they throw inside "use cache" / cache()
 // scope. Module-level constant (read-only, .has() lookups) so it is allocated
@@ -87,19 +88,7 @@ export function guardHeaderWrites(
   });
 }
 
-/**
- * Strip internal _rsc* query params from a URL.
- * Returns a new URL with only user-facing params.
- */
-export function stripInternalParams(url: URL): URL {
-  const clean = new URL(url);
-  for (const key of [...clean.searchParams.keys()]) {
-    if (key.startsWith("_rsc")) {
-      clean.searchParams.delete(key);
-    }
-  }
-  return clean;
-}
+export { stripInternalParams } from "./internal-params.js";
 
 /**
  * Resolve route name with namespace prefix support.
@@ -362,6 +351,7 @@ export function createHandlerContext<TEnv>(
   (ctx as { [THEME_REQUEST_CONTEXT]?: unknown })[THEME_REQUEST_CONTEXT] =
     requestContext;
   Object.defineProperty(ctx, "theme", THEME_DESCRIPTOR);
+  defineRewrittenFrom(ctx, requestContext);
   // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;