@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

package/src/router/params-util.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared route-param comparison helpers.
+ */
+
+/**
+ * Shallow equality for two route-param records. Same-reference is a fast path;
+ * otherwise compares key count then each value.
+ */
+export function paramsEqual(
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean {
+  if (a === b) return true;
+
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+}

package/src/router/pattern-matching.ts

@@ -33,13 +33,6 @@ export interface ParsedSegment {
  */
 export function parsePattern(pattern: string): ParsedSegment[] {
   const segments: ParsedSegment[] = [];
-  // Match: /segment where segment can be:
-  // - static text
-  // - :param
-  // - :param?
-  // - :param(a|b)
-  // - :param(a|b)?
-  // - *
   const segmentRegex =
     /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([^/]*)|(\*)|([^/]+))/g;
 
@@ -81,7 +74,6 @@ export function parsePattern(pattern: string): ParsedSegment[] {
 export interface CompiledPattern {
   regex: RegExp;
   paramNames: string[];
-  optionalParams: Set<string>;
   hasTrailingSlash: boolean;
   /**
    * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
@@ -149,7 +141,6 @@ export function compilePattern(pattern: string): CompiledPattern {
 
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
-  const optionalParams = new Set<string>();
   let constraints: Record<string, string[]> | undefined;
 
   let regexPattern = "";
@@ -171,7 +162,6 @@ export function compilePattern(pattern: string): CompiledPattern {
       }
 
       if (segment.optional) {
-        optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
         regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
@@ -183,11 +173,24 @@ export function compilePattern(pattern: string): CompiledPattern {
     }
   }
 
-  // Handle root path
   if (regexPattern === "") {
     regexPattern = "/";
   }
 
+  // Patterns of only optional segments (e.g. `/:locale?`, `/:a?/:b?`) need
+  // an explicit `/` alternative so a bare `/` matches the absent form. The
+  // optional template `(?:/X)?` matches `/X` or empty string, but pathnames
+  // are never empty. Arises from `include("/:locale?", routes)` + inner
+  // `path("/")`. Skip when an explicit trailing slash already anchors the
+  // match.
+  const hasOnlyOptionalSegments =
+    !hasTrailingSlash &&
+    segments.length > 0 &&
+    segments.every((segment) => segment.type === "param" && segment.optional);
+  if (hasOnlyOptionalSegments) {
+    regexPattern = `(?:/|${regexPattern})`;
+  }
+
   // Add trailing slash to regex if pattern has one
   if (hasTrailingSlash) {
     regexPattern += "/";
@@ -196,7 +199,6 @@ export function compilePattern(pattern: string): CompiledPattern {
   return {
     regex: new RegExp(`^${regexPattern}$`),
     paramNames,
-    optionalParams,
     hasTrailingSlash,
     ...(constraints ? { constraints } : {}),
   };
@@ -205,7 +207,9 @@ export function compilePattern(pattern: string): CompiledPattern {
 /**
  * Validate decoded params against a compiled pattern's constraints.
  * Returns false if any constrained param has a non-empty value not in the
- * allowed list (empty-string = absent optional, which is allowed).
+ * allowed list. Absent optionals (key missing or `undefined`) are allowed;
+ * `""` is also tolerated as "absent" so user-provided params or fixtures
+ * that pass empty strings explicitly behave the same way.
  */
 function satisfiesConstraints(
   params: Record<string, string>,
@@ -232,6 +236,27 @@ function escapeRegex(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+/**
+ * Build the named-params record from a regex match. Optional segments that
+ * didn't capture leave the corresponding group `undefined`; we skip those
+ * keys so `ctx.params.<name>` reads as `undefined` rather than `""`. This
+ * keeps the runtime aligned with the `ExtractParams` type and matches the
+ * trie matcher's contract (see `trie-matching.ts:validateAndBuild`).
+ */
+function buildParamsFromMatch(
+  match: RegExpExecArray,
+  paramNames: string[],
+): Record<string, string> {
+  const params: Record<string, string> = {};
+  paramNames.forEach((name, index) => {
+    const captured = match[index + 1];
+    if (captured !== undefined) {
+      params[name] = safeDecodeURIComponent(captured);
+    }
+  });
+  return params;
+}
+
 /**
  * Extract the static prefix from a route pattern.
  * Returns everything before the first param/wildcard.
@@ -248,7 +273,6 @@ function escapeRegex(str: string): string {
 export function extractStaticPrefix(pattern: string): string {
   if (!pattern || pattern === "/") return "";
 
-  // Find the first occurrence of : or *
   const paramIndex = pattern.indexOf(":");
   const wildcardIndex = pattern.indexOf("*");
 
@@ -262,16 +286,13 @@ export function extractStaticPrefix(pattern: string): string {
   }
 
   if (cutIndex === -1) {
-    // No params or wildcards - entire pattern is static
     return pattern;
   }
 
   if (cutIndex === 0) {
-    // Pattern starts with : or * - no static prefix
     return "";
   }
 
-  // Find the last / before the param
   const lastSlash = pattern.lastIndexOf("/", cutIndex - 1);
   if (lastSlash === -1 || lastSlash === 0) {
     return "";
@@ -280,11 +301,28 @@ export function extractStaticPrefix(pattern: string): string {
   return pattern.slice(0, lastSlash);
 }
 
+/**
+ * Join a URL prefix to a sub-prefix, collapsing the duplicate slash when the
+ * base ends with "/" and the sub-prefix starts with "/". This mirrors the
+ * canonical join in `include()` (urls/include-helper.ts) and `runWithPrefixes`
+ * (server/context.ts) so a nested lazy include's runtime staticPrefix matches
+ * the build-time trie's `sp` (e.g. `include("/parent/", …)` containing
+ * `include("/child", …)` resolves to `/parent/child`, not `/parent//child`).
+ */
+export function joinPrefix(base: string | undefined, prefix: string): string {
+  if (!base) return prefix;
+  return base.endsWith("/") && prefix.startsWith("/")
+    ? base + prefix.slice(1)
+    : base + prefix;
+}
+
 /**
  * Match a pathname against registered routes
  *
- * Note: Optional params that are absent in the path will have empty string value.
- * Use the pattern definition to determine if a param is optional.
+ * Note: Optional params that are absent in the path are omitted from the
+ * returned `params` (read as `undefined`), matching the trie matcher and
+ * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition to
+ * determine which keys are optional.
  *
  * Trailing slash handling (priority order):
  * 1. Per-route `trailingSlash` config from route()
@@ -302,10 +340,7 @@ export interface RouteMatchResult<TEnv = any> {
   entry: RouteEntry<TEnv>;
   routeKey: string;
   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) */
@@ -383,8 +418,6 @@ export function findMatch<TEnv>(
     : pathname + "/";
 
   for (const entry of routesEntries) {
-    // 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 (effectiveDebug) {
         debugStats.entriesSkipped++;
@@ -396,8 +429,6 @@ export function findMatch<TEnv>(
       continue;
     }
 
-    // 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 (effectiveDebug) {
         debugLog("findMatch", "lazy entry requires evaluation", {
@@ -418,7 +449,6 @@ export function findMatch<TEnv>(
         debugStats.routesChecked++;
       }
 
-      // Join prefix and pattern, handling edge cases
       let fullPattern: string;
       if (entry.prefix === "" || entry.prefix === "/") {
         fullPattern = pattern;
@@ -428,19 +458,12 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const {
-        regex,
-        paramNames,
-        optionalParams,
-        hasTrailingSlash,
-        constraints,
-      } = getCompiledPattern(fullPattern);
+      const { regex, paramNames, hasTrailingSlash, constraints } =
+        getCompiledPattern(fullPattern);
 
-      // Get trailing slash mode for this route (per-route config or pattern-based)
       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 }
         : {};
@@ -448,16 +471,10 @@ export function findMatch<TEnv>(
         ? { pt: true as const }
         : {};
 
-      // Try exact match first
       const match = regex.exec(pathname);
       if (match) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = safeDecodeURIComponent(match[index + 1] ?? "");
-        });
+        const params = buildParamsFromMatch(match, paramNames);
 
-        // Validate constraints against decoded values; a failure falls
-        // through to the next route so other patterns can still match.
         if (!satisfiesConstraints(params, constraints)) {
           continue;
         }
@@ -470,29 +487,24 @@ export function findMatch<TEnv>(
           });
         }
 
-        // Check if trailing slash mode requires redirect even on exact match
         if (
           trailingSlashMode === "always" &&
           !pathnameHasTrailingSlash &&
           pathname !== "/"
         ) {
-          // Mode says always have trailing slash, but pathname doesn't have it
           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),
             ...prFlag,
             ...ptFlag,
@@ -503,43 +515,33 @@ export function findMatch<TEnv>(
           entry,
           routeKey,
           params,
-          optionalParams,
           ...prFlag,
           ...ptFlag,
         };
       }
 
-      // Try alternate pathname (opposite trailing slash)
       const altMatch = regex.exec(alternatePathname);
       if (altMatch) {
-        const params: Record<string, string> = {};
-        paramNames.forEach((name, index) => {
-          params[name] = safeDecodeURIComponent(altMatch[index + 1] ?? "");
-        });
+        const params = buildParamsFromMatch(altMatch, paramNames);
 
         if (!satisfiesConstraints(params, constraints)) {
           continue;
         }
 
-        // Determine redirect behavior based on mode
         if (trailingSlashMode === "ignore") {
-          // Match without redirect
           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,
               ...prFlag,
               ...ptFlag,
@@ -549,18 +551,15 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             ...prFlag,
             ...ptFlag,
           };
         } else if (trailingSlashMode === "always") {
-          // Redirect to with trailing slash
           if (!pathnameHasTrailingSlash) {
             return {
               entry,
               routeKey,
               params,
-              optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
               ...ptFlag,
@@ -570,13 +569,10 @@ export function findMatch<TEnv>(
             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);
@@ -584,7 +580,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             redirectTo: canonicalPath,
             ...prFlag,
             ...ptFlag,
@@ -605,7 +600,7 @@ export function* traverseBack(entry: EntryData): Generator<EntryData> {
   let current: EntryData | null = entry;
   const items = [] as EntryData[];
   while (current !== null) {
-    items.push(current); // Move up to next parent
+    items.push(current);
     current = current.parent;
   }
   for (let i = items.length - 1; i >= 0; i--) {