@rangojs/router 0.0.0-experimental.21 → 0.0.0-experimental.21efdd86

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

@@ -114,7 +114,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 +140,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 {

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.ts

@@ -19,6 +19,8 @@ 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,
@@ -133,6 +135,7 @@ export function createRouter<TEnv = any>(
   const {
     id: userProvidedId,
     $$id: injectedId,
+    basename: basenameOption,
     debugPerformance = false,
     document: documentOption,
     defaultErrorBoundary,
@@ -147,7 +150,7 @@ export function createRouter<TEnv = any>(
     $$sourceFile: injectedSourceFile,
     nonce,
     version,
-    prefetchCacheControl: prefetchCacheControlOption,
+    prefetchCacheTTL: prefetchCacheTTLOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -158,6 +161,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 +210,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 +373,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 +536,7 @@ export function createRouter<TEnv = any>(
     trackHandler,
     findNearestErrorBoundary,
     findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
     callOnError,
   };
 
@@ -544,6 +571,7 @@ export function createRouter<TEnv = any>(
     mergedRouteMap,
     nextMountIndex: () => mountIndex++,
     getPrecomputedByPrefix,
+    routerId,
   };
 
   function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
@@ -597,6 +625,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 +634,8 @@ export function createRouter<TEnv = any>(
       prerenderDeps,
       buildVars,
       isPassthroughRoute,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -611,12 +643,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 +677,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 +716,7 @@ export function createRouter<TEnv = any>(
         errorBoundary: [],
         notFoundBoundary: [],
         layout: [],
-        parallel: [],
+        parallel: {},
         intercept: [],
         loader: [],
       };
@@ -690,6 +733,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 +756,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 +782,7 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -754,6 +802,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          routerId,
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -797,6 +846,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: mountIndex++,
+          routerId,
           // Lazy evaluation fields
           lazy: true,
           lazyPatterns: lazyInclude.patterns,
@@ -835,8 +885,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 +929,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 +997,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 +1033,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 +1045,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, {}>;
   }