@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.20dbba0c

package/src/router/segment-wrappers.ts

@@ -204,6 +204,7 @@ export function createSegmentWrappers<TEnv = any>(
     interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
     return _resolveAllSegmentsWithRevalidation(
       entries,
@@ -221,6 +222,7 @@ export function createSegmentWrappers<TEnv = any>(
       localRouteName,
       pathname,
       segmentDeps,
+      stale,
     );
   }
 

package/src/router/trie-matching.ts

@@ -6,6 +6,7 @@
  */
 
 import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -114,7 +115,25 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 2: Param match
+  // Priority 2: Suffix-param match (e.g., :productId.html)
+  if (node.xp) {
+    for (const suffix in node.xp) {
+      if (segment.endsWith(suffix) && segment.length > suffix.length) {
+        const paramValue = segment.slice(0, -suffix.length);
+        paramValues.push(paramValue);
+        const result = walkTrie(
+          node.xp[suffix].c,
+          segments,
+          index + 1,
+          paramValues,
+        );
+        paramValues.pop();
+        if (result) return result;
+      }
+    }
+  }
+
+  // Priority 3: Param match
   if (node.p) {
     paramValues.push(segment);
     const result = walkTrie(node.p.c, segments, index + 1, paramValues);
@@ -122,7 +141,7 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 3: Wildcard match (consumes rest)
+  // Priority 4: Wildcard match (consumes rest)
   if (node.w) {
     const rest = joinRemainingSegments(segments, index);
     return {
@@ -155,20 +174,25 @@ function validateAndBuild(
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues
+  // Build named params by zipping leaf.pa with positional paramValues.
+  // Params are URL-decoded at this boundary so ctx.params holds the values
+  // apps expect (matching Express/React Router) and round-trip cleanly
+  // through ctx.reverse.
   const params: Record<string, string> = {};
   if (leaf.pa) {
     for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
-      params[leaf.pa[i]] = paramValues[i];
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
     }
   }
 
   // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
   if (wildcardValue !== undefined && "pn" in leaf) {
-    params[(leaf as TrieLeaf & { pn: string }).pn] = wildcardValue;
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
   }
 
-  // Validate constraints
+  // Validate constraints against decoded values so constraint lists can be
+  // written in decoded form (e.g. ["en-GB", "en US"]).
   if (leaf.cv) {
     for (const paramName in leaf.cv) {
       const allowed = leaf.cv[paramName]!;

package/src/router/types.ts

@@ -96,6 +96,7 @@ export interface SegmentResolutionDeps<TEnv = any> {
   findNearestNotFoundBoundary: (
     entry: EntryData | null,
   ) => ReactNode | NotFoundBoundaryHandler | null;
+  notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
 }
 

package/src/router/url-params.ts

@@ -0,0 +1,49 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+// encodeURIComponent over-encodes for path segments. After running it,
+// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
+// keeps human-readable characters that are legal in a path segment.
+// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
+// encoded.
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}

package/src/router.ts

@@ -19,9 +19,10 @@ import {
 import MapRootLayout from "./server/root-layout.js";
 import type { AllUseItems } from "./route-types.js";
 import type { UrlPatterns } from "./urls.js";
+import type { UrlBuilder } from "./urls/pattern-types.js";
+import { urls } from "./urls.js";
 import {
-  EntryData,
-  InterceptSelectorContext,
+  type EntryData,
   getContext,
   RSCRouterContext,
   type MetricsStore,
@@ -133,6 +134,7 @@ export function createRouter<TEnv = any>(
   const {
     id: userProvidedId,
     $$id: injectedId,
+    basename: basenameOption,
     debugPerformance = false,
     document: documentOption,
     defaultErrorBoundary,
@@ -147,7 +149,7 @@ export function createRouter<TEnv = any>(
     $$sourceFile: injectedSourceFile,
     nonce,
     version,
-    prefetchCacheControl: prefetchCacheControlOption,
+    prefetchCacheTTL: prefetchCacheTTLOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -158,6 +160,13 @@ export function createRouter<TEnv = any>(
     originCheck: originCheckOption,
   } = options;
 
+  // Normalize basename: ensure leading slash, strip trailing slash.
+  // A bare "/" is equivalent to no basename.
+  const basename =
+    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
+      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
+      : undefined;
+
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
 
@@ -200,11 +209,17 @@ export function createRouter<TEnv = any>(
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
 
-  // Resolve prefetch cache control (default: 'private, max-age=300')
-  const prefetchCacheControl =
-    prefetchCacheControlOption !== undefined
-      ? prefetchCacheControlOption
-      : "private, max-age=300";
+  // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
+  // Clamp to a non-negative integer for valid Cache-Control max-age.
+  const rawTTL =
+    prefetchCacheTTLOption !== undefined ? prefetchCacheTTLOption : 300;
+  const prefetchCacheTTLSeconds =
+    rawTTL === false ? 0 : Math.max(0, Math.floor(rawTTL));
+  const prefetchCacheTTL = prefetchCacheTTLSeconds * 1000;
+  const prefetchCacheControl: string | false =
+    prefetchCacheTTLSeconds === 0
+      ? false
+      : `private, max-age=${prefetchCacheTTLSeconds}`;
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
@@ -357,8 +372,18 @@ export function createRouter<TEnv = any>(
     return precomputedByPrefix;
   }
 
-  // Wrapper to pass debugPerformance to external createMetricsStore
-  const getMetricsStore = () => createMetricsStore(debugPerformance);
+  // Wrapper to pass debugPerformance to external createMetricsStore.
+  // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  const getMetricsStore = () => {
+    const reqCtx = _getRequestContext();
+    const enabled = debugPerformance || !!reqCtx?._debugPerformance;
+    if (!enabled) return undefined;
+    if (!reqCtx) {
+      return createMetricsStore(true);
+    }
+    reqCtx._metricsStore ??= createMetricsStore(true);
+    return reqCtx._metricsStore;
+  };
 
   // Wrapper to pass defaults to error/notFound boundary finders
   const findNearestErrorBoundary = (entry: EntryData | null) =>
@@ -510,6 +535,7 @@ export function createRouter<TEnv = any>(
     trackHandler,
     findNearestErrorBoundary,
     findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
     callOnError,
   };
 
@@ -544,6 +570,7 @@ export function createRouter<TEnv = any>(
     mergedRouteMap,
     nextMountIndex: () => mountIndex++,
     getPrecomputedByPrefix,
+    routerId,
   };
 
   function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
@@ -597,6 +624,8 @@ export function createRouter<TEnv = any>(
     params: Record<string, string>,
     buildVars?: Record<string, any>,
     isPassthroughRoute?: boolean,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _matchForPrerender(
       pathname,
@@ -604,6 +633,8 @@ export function createRouter<TEnv = any>(
       prerenderDeps,
       buildVars,
       isPassthroughRoute,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -611,12 +642,16 @@ export function createRouter<TEnv = any>(
     handler: Function,
     handlerId: string,
     routeName?: string,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _renderStaticSegment<TEnv>(
       handler,
       handlerId,
       mergedRouteMap,
       routeName,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -641,8 +676,15 @@ export function createRouter<TEnv = any>(
   const router: RSCRouterInternal<TEnv, {}> = {
     __brand: RSC_ROUTER_BRAND,
     id: routerId,
+    basename,
+
+    routes(patternsOrBuilder: UrlPatterns<TEnv> | UrlBuilder<TEnv>): any {
+      // Wrap builder functions in urls() automatically
+      const urlPatterns: UrlPatterns<TEnv> =
+        typeof patternsOrBuilder === "function"
+          ? (urls(patternsOrBuilder) as UrlPatterns<TEnv>)
+          : patternsOrBuilder;
 
-    routes(urlPatterns: UrlPatterns<TEnv>): any {
       // Store reference for runtime manifest generation
       storedUrlPatterns = urlPatterns;
       const currentMountIndex = mountIndex++;
@@ -673,7 +715,7 @@ export function createRouter<TEnv = any>(
         errorBoundary: [],
         notFoundBoundary: [],
         layout: [],
-        parallel: [],
+        parallel: {},
         intercept: [],
         loader: [],
       };
@@ -690,6 +732,10 @@ export function createRouter<TEnv = any>(
           counters: {},
           mountIndex: currentMountIndex,
           cacheProfiles: resolvedCacheProfiles,
+          // basename sets the initial URL prefix so all path() patterns
+          // are registered with the prefix (e.g. "/admin" + "/users" = "/admin/users").
+          // No namePrefix — route names stay unprefixed.
+          ...(basename ? { urlPrefix: basename } : {}),
         },
         () => {
           handlerResult = urlPatterns.handler() as AllUseItems[];
@@ -709,7 +755,7 @@ export function createRouter<TEnv = any>(
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
           prerenderRouteKeys.add(name);
-          if (entry.prerenderDef?.options?.passthrough === true) {
+          if (entry.isPassthrough === true) {
             if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
             passthroughRouteKeys.add(name);
           }
@@ -735,6 +781,7 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -754,6 +801,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          routerId,
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -797,6 +845,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: mountIndex++,
+          routerId,
           // Lazy evaluation fields
           lazy: true,
           lazyPatterns: lazyInclude.patterns,
@@ -835,8 +884,18 @@ export function createRouter<TEnv = any>(
       patternOrMiddleware: string | MiddlewareFn<TEnv>,
       middleware?: MiddlewareFn<TEnv>,
     ): any {
-      // Global middleware - no mount prefix
-      addMiddleware(patternOrMiddleware, middleware, null);
+      // Auto-prefix pattern with basename so router-level middleware
+      // patterns are router-relative (e.g. "/users/*" matches "/app/users/*").
+      if (basename && typeof patternOrMiddleware === "string") {
+        const pattern = patternOrMiddleware;
+        const prefixed =
+          pattern === "/*" || pattern === "*"
+            ? `${basename}/*`
+            : `${basename}${pattern}`;
+        addMiddleware(prefixed, middleware, null);
+      } else {
+        addMiddleware(patternOrMiddleware, middleware, null);
+      }
       return router;
     },
 
@@ -869,12 +928,16 @@ export function createRouter<TEnv = any>(
     // Expose resolved cache profiles for per-request resolution
     cacheProfiles: resolvedCacheProfiles,
 
-    // Expose prefetch cache control for RSC handler
+    // Expose prefetch cache settings
     prefetchCacheControl,
+    prefetchCacheTTL,
 
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 
+    // Expose router-wide performance debugging for request-level metrics setup
+    debugPerformance,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 
@@ -933,6 +996,9 @@ export function createRouter<TEnv = any>(
     // Expose source file for per-router type generation
     __sourceFile,
 
+    // Expose basename for runtime manifest generation
+    __basename: basename,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused
@@ -966,6 +1032,10 @@ export function createRouter<TEnv = any>(
       };
     })(),
 
+    // Low-level route matching for request classification
+    findMatch: (pathname: string, metricsStore?: any) =>
+      findMatch(pathname, metricsStore),
+
     // Debug utility for manifest inspection
     debugManifest: () => buildDebugManifest<TEnv>(routesEntries),
   };
@@ -974,7 +1044,9 @@ export function createRouter<TEnv = any>(
   RouterRegistry.set(routerId, router);
 
   // If urls option was provided, auto-register them
-  if (urlsOption) {
+  if (typeof urlsOption === "function") {
+    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+  } else if (urlsOption) {
     return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
   }