@rangojs/router 0.0.0-experimental.6 → 0.0.0-experimental.60

package/src/router/pattern-matching.ts

@@ -6,15 +6,17 @@
 
 import type { RouteEntry, TrailingSlashMode } from "../types";
 import type { EntryData } from "../server/context";
+import { debugLog, isRouterDebugEnabled } from "./logging.js";
 
 /**
  * Parsed segment info
  */
-interface ParsedSegment {
+export interface ParsedSegment {
   type: "static" | "param" | "wildcard";
   value: string; // static text, param name, or "*"
   optional: boolean;
   constraint?: string[]; // enum values like ["en", "gb"]
+  suffix?: string; // literal text after param in same segment (e.g., ".html")
 }
 
 /**
@@ -28,7 +30,7 @@ interface ParsedSegment {
  * - Optional + Constrained: /:locale(en|gb)?
  * - Wildcard: /*
  */
-function parsePattern(pattern: string): ParsedSegment[] {
+export function parsePattern(pattern: string): ParsedSegment[] {
   const segments: ParsedSegment[] = [];
   // Match: /segment where segment can be:
   // - static text
@@ -37,11 +39,22 @@ function parsePattern(pattern: string): ParsedSegment[] {
   // - :param(a|b)
   // - :param(a|b)?
   // - *
-  const segmentRegex = /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?|(\*)|([^/]+))/g;
+  const segmentRegex =
+    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
 
   let match;
   while ((match = segmentRegex.exec(pattern)) !== null) {
-    const [, , paramName, , constraint, optional, wildcard, staticText] = match;
+    const [
+      ,
+      ,
+      paramName,
+      ,
+      constraint,
+      optional,
+      suffix,
+      wildcard,
+      staticText,
+    ] = match;
 
     if (wildcard) {
       segments.push({ type: "wildcard", value: "*", optional: false });
@@ -51,6 +64,7 @@ function parsePattern(pattern: string): ParsedSegment[] {
         value: paramName,
         optional: optional === "?",
         constraint: constraint ? constraint.split("|") : undefined,
+        suffix: suffix || undefined,
       });
     } else if (staticText) {
       segments.push({ type: "static", value: staticText, optional: false });
@@ -60,6 +74,48 @@ function parsePattern(pattern: string): ParsedSegment[] {
   return segments;
 }
 
+/**
+ * Compiled pattern result containing regex, param metadata, and trailing slash info.
+ */
+export interface CompiledPattern {
+  regex: RegExp;
+  paramNames: string[];
+  optionalParams: Set<string>;
+  hasTrailingSlash: boolean;
+}
+
+// Module-level cache for compiled patterns. Route patterns are a finite set
+// defined at build time, so this map is bounded by the number of routes.
+const compiledPatternCache = new Map<string, CompiledPattern>();
+
+/**
+ * Get a compiled pattern from cache or compile and cache it.
+ * Avoids O(routes) regex compilations per request in the fallback path.
+ */
+export function getCompiledPattern(pattern: string): CompiledPattern {
+  let compiled = compiledPatternCache.get(pattern);
+  if (compiled) return compiled;
+  compiled = compilePattern(pattern);
+  compiledPatternCache.set(pattern, compiled);
+  return compiled;
+}
+
+/**
+ * Return the current size of the compiled pattern cache.
+ * Exposed for testing.
+ */
+export function getPatternCacheSize(): number {
+  return compiledPatternCache.size;
+}
+
+/**
+ * Clear the compiled pattern cache.
+ * Exposed for testing.
+ */
+export function clearPatternCache(): void {
+  compiledPatternCache.clear();
+}
+
 /**
  * Compile a route pattern to regex
  *
@@ -77,12 +133,7 @@ function parsePattern(pattern: string): ParsedSegment[] {
  * compilePattern("/:locale(en|gb)/blog")  // matches /en/blog or /gb/blog
  * compilePattern("/:locale(en|gb)?/blog") // matches /blog, /en/blog, or /gb/blog
  */
-export function compilePattern(pattern: string): {
-  regex: RegExp;
-  paramNames: string[];
-  optionalParams: Set<string>;
-  hasTrailingSlash: boolean;
-} {
+export function compilePattern(pattern: string): CompiledPattern {
   // Detect if pattern has trailing slash (but not just "/")
   const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
   // Remove trailing slash for parsing (we'll add it back to regex if needed)
@@ -100,16 +151,19 @@ export function compilePattern(pattern: string): {
       regexPattern += "/(.*)";
     } else if (segment.type === "param") {
       paramNames.push(segment.value);
+      const suffixPattern = segment.suffix ? escapeRegex(segment.suffix) : "";
       const valuePattern = segment.constraint
-        ? `(${segment.constraint.join("|")})`
-        : "([^/]+)";
+        ? `(${segment.constraint.map(escapeRegex).join("|")})`
+        : segment.suffix
+          ? "([^/]+?)"
+          : "([^/]+)";
 
       if (segment.optional) {
         optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
-        regexPattern += `(?:/${valuePattern})?`;
+        regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
-        regexPattern += `/${valuePattern}`;
+        regexPattern += `/${valuePattern}${suffixPattern}`;
       }
     } else {
       // Static segment
@@ -214,6 +268,18 @@ export interface RouteMatchResult<TEnv = any> {
   params: Record<string, string>;
   optionalParams: Set<string>;
   redirectTo?: string;
+  /** Ancestry shortCodes for layout pruning (from trie match) */
+  ancestry?: string[];
+  /** Route has pre-rendered data available (from trie) */
+  pr?: true;
+  /** Passthrough: handler kept for live fallback on unknown params (from trie) */
+  pt?: true;
+  /** Response type for non-RSC routes (json, text, image, any) */
+  responseType?: string;
+  /** Negotiate variants: response-type routes sharing this path */
+  negotiateVariants?: Array<{ routeKey: string; responseType: string }>;
+  /** RSC-first: RSC route was defined before response-type variants */
+  rscFirst?: true;
 }
 
 /**
@@ -227,7 +293,7 @@ export interface LazyEvaluationNeeded<TEnv = any> {
  * Type guard to check if result is a lazy evaluation needed response
  */
 export function isLazyEvaluationNeeded<TEnv>(
-  result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null
+  result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null,
 ): result is LazyEvaluationNeeded<TEnv> {
   return result !== null && "lazyEntry" in result;
 }
@@ -248,22 +314,33 @@ export function enableMatchDebug(enabled: boolean): void {
 }
 
 export function getMatchDebugStats(): MatchDebugStats {
-  return { entriesChecked: debugStats.entriesChecked, entriesSkipped: debugStats.entriesSkipped, routesChecked: debugStats.routesChecked };
+  return {
+    entriesChecked: debugStats.entriesChecked,
+    entriesSkipped: debugStats.entriesSkipped,
+    routesChecked: debugStats.routesChecked,
+  };
 }
 
 export function findMatch<TEnv>(
   pathname: string,
-  routesEntries: RouteEntry<TEnv>[]
+  routesEntries: RouteEntry<TEnv>[],
 ): RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null {
-  if (debugEnabled) {
+  const effectiveDebug = debugEnabled || isRouterDebugEnabled();
+
+  if (effectiveDebug) {
     debugStats = { entriesChecked: 0, entriesSkipped: 0, routesChecked: 0 };
-    console.log(`[findMatch] pathname="${pathname}", entries=${routesEntries.length}`);
+    debugLog("findMatch", "start", { pathname, entries: routesEntries.length });
     for (const e of routesEntries) {
-      console.log(`  entry: prefix="${e.prefix}", staticPrefix="${e.staticPrefix}", routes=${Object.keys(e.routes).length}`);
+      debugLog("findMatch", "entry", {
+        prefix: e.prefix,
+        staticPrefix: e.staticPrefix,
+        routeCount: Object.keys(e.routes).length,
+      });
     }
   }
 
-  const pathnameHasTrailingSlash = pathname.length > 1 && pathname.endsWith("/");
+  const pathnameHasTrailingSlash =
+    pathname.length > 1 && pathname.endsWith("/");
   // Try alternate pathname for redirect matching
   const alternatePathname = pathnameHasTrailingSlash
     ? pathname.slice(0, -1)
@@ -273,9 +350,12 @@ export function findMatch<TEnv>(
     // Short-circuit: skip entry if pathname doesn't start with static prefix
     // staticPrefix is pre-computed at registration time, so this is O(1)
     if (entry.staticPrefix && !pathname.startsWith(entry.staticPrefix)) {
-      if (debugEnabled) {
+      if (effectiveDebug) {
         debugStats.entriesSkipped++;
-        console.log(`  SKIP entry prefix="${entry.prefix}" (staticPrefix="${entry.staticPrefix}" doesn't match)`);
+        debugLog("findMatch", "skipped entry", {
+          prefix: entry.prefix,
+          staticPrefix: entry.staticPrefix,
+        });
       }
       continue;
     }
@@ -283,20 +363,22 @@ export function findMatch<TEnv>(
     // Check if this is a lazy entry that needs evaluation
     // When staticPrefix matches but routes are not yet populated, signal caller to evaluate
     if (entry.lazy && !entry.lazyEvaluated) {
-      if (debugEnabled) {
-        console.log(`  LAZY entry needs evaluation: staticPrefix="${entry.staticPrefix}"`);
+      if (effectiveDebug) {
+        debugLog("findMatch", "lazy entry requires evaluation", {
+          staticPrefix: entry.staticPrefix,
+        });
       }
       return { lazyEntry: entry };
     }
 
-    if (debugEnabled) {
+    if (effectiveDebug) {
       debugStats.entriesChecked++;
     }
 
     const routeEntries = Object.entries(entry.routes);
 
     for (const [routeKey, pattern] of routeEntries) {
-      if (debugEnabled) {
+      if (effectiveDebug) {
         debugStats.routesChecked++;
       }
 
@@ -310,11 +392,20 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const { regex, paramNames, optionalParams, hasTrailingSlash } = compilePattern(fullPattern);
+      const { regex, paramNames, optionalParams, hasTrailingSlash } =
+        getCompiledPattern(fullPattern);
 
       // Get trailing slash mode for this route (per-route config or pattern-based)
-      const trailingSlashMode: TrailingSlashMode | undefined = entry.trailingSlash?.[routeKey];
+      const trailingSlashMode: TrailingSlashMode | undefined =
+        entry.trailingSlash?.[routeKey];
 
+      // Prerender flag from entry metadata (set by urls() for prerender handlers)
+      const prFlag = entry.prerenderRouteKeys?.has(routeKey)
+        ? { pr: true as const }
+        : {};
+      const ptFlag = entry.passthroughRouteKeys?.has(routeKey)
+        ? { pt: true as const }
+        : {};
 
       // Try exact match first
       const match = regex.exec(pathname);
@@ -324,21 +415,51 @@ export function findMatch<TEnv>(
           params[name] = match[index + 1] ?? "";
         });
 
-        if (debugEnabled) {
-          console.log(`  MATCH: routeKey="${routeKey}", pattern="${fullPattern}"`);
-          console.log(`  Stats: entriesChecked=${debugStats.entriesChecked}, entriesSkipped=${debugStats.entriesSkipped}, routesChecked=${debugStats.routesChecked}`);
+        if (effectiveDebug) {
+          debugLog("findMatch", "matched route", {
+            routeKey,
+            pattern: fullPattern,
+            stats: { ...debugStats },
+          });
         }
 
         // Check if trailing slash mode requires redirect even on exact match
-        if (trailingSlashMode === "always" && !pathnameHasTrailingSlash && pathname !== "/") {
+        if (
+          trailingSlashMode === "always" &&
+          !pathnameHasTrailingSlash &&
+          pathname !== "/"
+        ) {
           // Mode says always have trailing slash, but pathname doesn't have it
-          return { entry, routeKey, params, optionalParams, redirectTo: pathname + "/" };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            redirectTo: pathname + "/",
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
           // Mode says never have trailing slash, but pathname has it
-          return { entry, routeKey, params, optionalParams, redirectTo: pathname.slice(0, -1) };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            redirectTo: pathname.slice(0, -1),
+            ...prFlag,
+            ...ptFlag,
+          };
         }
 
-        return { entry, routeKey, params, optionalParams };
+        return {
+          entry,
+          routeKey,
+          params,
+          optionalParams,
+          ...prFlag,
+          ...ptFlag,
+        };
       }
 
       // Try alternate pathname (opposite trailing slash)
@@ -352,24 +473,71 @@ export function findMatch<TEnv>(
         // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
           // Match without redirect
-          return { entry, routeKey, params, optionalParams };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "never") {
           // Redirect to no trailing slash
           if (pathnameHasTrailingSlash) {
-            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname };
+            return {
+              entry,
+              routeKey,
+              params,
+              optionalParams,
+              redirectTo: alternatePathname,
+              ...prFlag,
+              ...ptFlag,
+            };
           }
-          return { entry, routeKey, params, optionalParams };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else if (trailingSlashMode === "always") {
           // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
-            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname };
+            return {
+              entry,
+              routeKey,
+              params,
+              optionalParams,
+              redirectTo: alternatePathname,
+              ...prFlag,
+              ...ptFlag,
+            };
           }
-          return { entry, routeKey, params, optionalParams };
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            ...prFlag,
+            ...ptFlag,
+          };
         } else {
           // No explicit mode - use pattern-based detection
           // Redirect to canonical form (what the pattern defines)
-          const canonicalPath = hasTrailingSlash ? alternatePathname : pathname.slice(0, -1);
-          return { entry, routeKey, params, optionalParams, redirectTo: canonicalPath };
+          const canonicalPath = hasTrailingSlash
+            ? alternatePathname
+            : pathname.slice(0, -1);
+          return {
+            entry,
+            routeKey,
+            params,
+            optionalParams,
+            redirectTo: canonicalPath,
+            ...prFlag,
+            ...ptFlag,
+          };
         }
       }
     }