@tanstack/router-core 1.127.8 → 1.128.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/router-core",
-  "version": "1.127.8",
+  "version": "1.128.3",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",

package/src/path.ts

@@ -3,9 +3,8 @@ import type { MatchLocation } from './RouterProvider'
 import type { AnyPathParams } from './route'
 
 export interface Segment {
-  type: 'pathname' | 'param' | 'wildcard'
+  type: 'pathname' | 'param' | 'wildcard' | 'optional-param'
   value: string
-  // Add a new property to store the static segment if present
   prefixSegment?: string
   suffixSegment?: string
 }
@@ -151,6 +150,18 @@ export function resolvePath({
         return `{$${param}}${segment.suffixSegment}`
       }
     }
+    if (segment.type === 'optional-param') {
+      const param = segment.value.substring(1)
+      if (segment.prefixSegment && segment.suffixSegment) {
+        return `${segment.prefixSegment}{-$${param}}${segment.suffixSegment}`
+      } else if (segment.prefixSegment) {
+        return `${segment.prefixSegment}{-$${param}}`
+      } else if (segment.suffixSegment) {
+        return `{-$${param}}${segment.suffixSegment}`
+      }
+      return `{-$${param}}`
+    }
+
     if (segment.type === 'wildcard') {
       if (segment.prefixSegment && segment.suffixSegment) {
         return `${segment.prefixSegment}{$}${segment.suffixSegment}`
@@ -168,6 +179,9 @@ export function resolvePath({
 
 const PARAM_RE = /^\$.{1,}$/ // $paramName
 const PARAM_W_CURLY_BRACES_RE = /^(.*?)\{(\$[a-zA-Z_$][a-zA-Z0-9_$]*)\}(.*)$/ // prefix{$paramName}suffix
+const OPTIONAL_PARAM_W_CURLY_BRACES_RE =
+  /^(.*?)\{-(\$[a-zA-Z_$][a-zA-Z0-9_$]*)\}(.*)$/ // prefix{-$paramName}suffix
+
 const WILDCARD_RE = /^\$$/ // $
 const WILDCARD_W_CURLY_BRACES_RE = /^(.*?)\{\$\}(.*)$/ // prefix{$}suffix
 
@@ -177,8 +191,10 @@ const WILDCARD_W_CURLY_BRACES_RE = /^(.*?)\{\$\}(.*)$/ // prefix{$}suffix
  * Wildcard: `/foo/$` ✅
  * Wildcard with Prefix and Suffix: `/foo/prefix{$}suffix` ✅
  *
+ * Optional param: `/foo/{-$bar}`
+ * Optional param with Prefix and Suffix: `/foo/prefix{-$bar}suffix`
+
  * Future:
- * Optional: `/foo/{-bar}`
  * Optional named segment: `/foo/{bar}`
  * Optional named segment with Prefix and Suffix: `/foo/prefix{-bar}suffix`
  * Escape special characters:
@@ -225,6 +241,22 @@ export function parsePathname(pathname?: string): Array<Segment> {
         }
       }
 
+      // Check for optional parameter format: prefix{-$paramName}suffix
+      const optionalParamBracesMatch = part.match(
+        OPTIONAL_PARAM_W_CURLY_BRACES_RE,
+      )
+      if (optionalParamBracesMatch) {
+        const prefix = optionalParamBracesMatch[1]
+        const paramName = optionalParamBracesMatch[2]!
+        const suffix = optionalParamBracesMatch[3]
+        return {
+          type: 'optional-param',
+          value: paramName, // Now just $paramName (no prefix)
+          prefixSegment: prefix || undefined,
+          suffixSegment: suffix || undefined,
+        }
+      }
+
       // Check for the new parameter format: prefix{$paramName}suffix
       const paramBracesMatch = part.match(PARAM_W_CURLY_BRACES_RE)
       if (paramBracesMatch) {
@@ -368,6 +400,31 @@ export function interpolatePath({
         return `${segmentPrefix}${encodeParam(key) ?? 'undefined'}${segmentSuffix}`
       }
 
+      if (segment.type === 'optional-param') {
+        const key = segment.value.substring(1)
+
+        const segmentPrefix = segment.prefixSegment || ''
+        const segmentSuffix = segment.suffixSegment || ''
+
+        // Check if optional parameter is missing or undefined
+        if (!(key in params) || params[key] == null) {
+          // For optional params with prefix/suffix, keep the prefix/suffix but omit the param
+          if (segmentPrefix || segmentSuffix) {
+            return `${segmentPrefix}${segmentSuffix}`
+          }
+          // If no prefix/suffix, omit the entire segment
+          return undefined
+        }
+
+        usedParams[key] = params[key]
+
+        if (leaveParams) {
+          const value = encodeParam(segment.value)
+          return `${segmentPrefix}${segment.value}${value ?? ''}${segmentSuffix}`
+        }
+        return `${segmentPrefix}${encodeParam(key) ?? ''}${segmentSuffix}`
+      }
+
       return segment.value
     }),
   )
@@ -479,21 +536,23 @@ export function matchByPath(
   const params: Record<string, string> = {}
 
   const isMatch = (() => {
-    for (
-      let i = 0;
-      i < Math.max(baseSegments.length, routeSegments.length);
-      i++
+    let baseIndex = 0
+    let routeIndex = 0
+
+    while (
+      baseIndex < baseSegments.length ||
+      routeIndex < routeSegments.length
     ) {
-      const baseSegment = baseSegments[i]
-      const routeSegment = routeSegments[i]
+      const baseSegment = baseSegments[baseIndex]
+      const routeSegment = routeSegments[routeIndex]
 
-      const isLastBaseSegment = i >= baseSegments.length - 1
-      const isLastRouteSegment = i >= routeSegments.length - 1
+      const isLastBaseSegment = baseIndex >= baseSegments.length - 1
+      const isLastRouteSegment = routeIndex >= routeSegments.length - 1
 
       if (routeSegment) {
         if (routeSegment.type === 'wildcard') {
           // Capture all remaining segments for a wildcard
-          const remainingBaseSegments = baseSegments.slice(i)
+          const remainingBaseSegments = baseSegments.slice(baseIndex)
 
           let _splat: string
 
@@ -551,7 +610,8 @@ export function matchByPath(
 
         if (routeSegment.type === 'pathname') {
           if (routeSegment.value === '/' && !baseSegment?.value) {
-            return true
+            routeIndex++
+            continue
           }
 
           if (baseSegment) {
@@ -565,19 +625,25 @@ export function matchByPath(
             ) {
               return false
             }
+            baseIndex++
+            routeIndex++
+            continue
+          } else {
+            return false
           }
         }
 
-        if (!baseSegment) {
-          return false
-        }
-
         if (routeSegment.type === 'param') {
+          if (!baseSegment) {
+            return false
+          }
+
           if (baseSegment.value === '/') {
             return false
           }
 
-          let _paramValue: string
+          let _paramValue = ''
+          let matched = false
 
           // If this param has prefix/suffix, we need to extract the actual parameter value
           if (routeSegment.prefixSegment || routeSegment.suffixSegment) {
@@ -605,19 +671,143 @@ export function matchByPath(
             }
 
             _paramValue = decodeURIComponent(paramValue)
+            matched = true
           } else {
             // If no prefix/suffix, just decode the base segment value
             _paramValue = decodeURIComponent(baseSegment.value)
+            matched = true
+          }
+
+          if (matched) {
+            params[routeSegment.value.substring(1)] = _paramValue
+            baseIndex++
           }
 
-          params[routeSegment.value.substring(1)] = _paramValue
+          routeIndex++
+          continue
+        }
+
+        if (routeSegment.type === 'optional-param') {
+          // Optional parameters can be missing - don't fail the match
+          if (!baseSegment) {
+            // No base segment for optional param - skip this route segment
+            routeIndex++
+            continue
+          }
+
+          if (baseSegment.value === '/') {
+            // Skip slash segments for optional params
+            routeIndex++
+            continue
+          }
+
+          let _paramValue = ''
+          let matched = false
+
+          // If this optional param has prefix/suffix, we need to extract the actual parameter value
+          if (routeSegment.prefixSegment || routeSegment.suffixSegment) {
+            const prefix = routeSegment.prefixSegment || ''
+            const suffix = routeSegment.suffixSegment || ''
+
+            // Check if the base segment starts with prefix and ends with suffix
+            const baseValue = baseSegment.value
+            if (
+              (!prefix || baseValue.startsWith(prefix)) &&
+              (!suffix || baseValue.endsWith(suffix))
+            ) {
+              let paramValue = baseValue
+              if (prefix && paramValue.startsWith(prefix)) {
+                paramValue = paramValue.slice(prefix.length)
+              }
+              if (suffix && paramValue.endsWith(suffix)) {
+                paramValue = paramValue.slice(
+                  0,
+                  paramValue.length - suffix.length,
+                )
+              }
+
+              _paramValue = decodeURIComponent(paramValue)
+              matched = true
+            }
+          } else {
+            // For optional params without prefix/suffix, we need to check if the current
+            // base segment should match this optional param or a later route segment
+
+            // Look ahead to see if there's a later route segment that matches the current base segment
+            let shouldMatchOptional = true
+            for (
+              let lookAhead = routeIndex + 1;
+              lookAhead < routeSegments.length;
+              lookAhead++
+            ) {
+              const futureRouteSegment = routeSegments[lookAhead]
+              if (
+                futureRouteSegment?.type === 'pathname' &&
+                futureRouteSegment.value === baseSegment.value
+              ) {
+                // The current base segment matches a future pathname segment,
+                // so we should skip this optional parameter
+                shouldMatchOptional = false
+                break
+              }
+
+              // If we encounter a required param or wildcard, stop looking ahead
+              if (
+                futureRouteSegment?.type === 'param' ||
+                futureRouteSegment?.type === 'wildcard'
+              ) {
+                break
+              }
+            }
+
+            if (shouldMatchOptional) {
+              // If no prefix/suffix, just decode the base segment value
+              _paramValue = decodeURIComponent(baseSegment.value)
+              matched = true
+            }
+          }
+
+          if (matched) {
+            params[routeSegment.value.substring(1)] = _paramValue
+            baseIndex++
+          }
+
+          routeIndex++
+          continue
         }
       }
 
       if (!isLastBaseSegment && isLastRouteSegment) {
-        params['**'] = joinPaths(baseSegments.slice(i + 1).map((d) => d.value))
+        params['**'] = joinPaths(
+          baseSegments.slice(baseIndex + 1).map((d) => d.value),
+        )
         return !!matchLocation.fuzzy && routeSegment?.value !== '/'
       }
+
+      // If we have base segments left but no route segments, it's not a match
+      if (
+        baseIndex < baseSegments.length &&
+        routeIndex >= routeSegments.length
+      ) {
+        return false
+      }
+
+      // If we have route segments left but no base segments, check if remaining are optional
+      if (
+        routeIndex < routeSegments.length &&
+        baseIndex >= baseSegments.length
+      ) {
+        // Check if all remaining route segments are optional
+        for (let i = routeIndex; i < routeSegments.length; i++) {
+          if (routeSegments[i]?.type !== 'optional-param') {
+            return false
+          }
+        }
+        // All remaining are optional, so we can finish
+        break
+      }
+
+      break
     }
 
     return true

package/src/router.ts

@@ -1450,15 +1450,23 @@ export class RouterCore<
 
       // Resolve the next params
       let nextParams =
-        (dest.params ?? true) === true
-          ? fromParams
-          : {
-              ...fromParams,
-              ...functionalUpdate(dest.params as any, fromParams),
-            }
+        dest.params === false || dest.params === null
+          ? {}
+          : (dest.params ?? true) === true
+            ? fromParams
+            : {
+                ...fromParams,
+                ...functionalUpdate(dest.params as any, fromParams),
+              }
+
+      // Interpolate the path first to get the actual resolved path, then match against that
+      const interpolatedNextTo = interpolatePath({
+        path: nextTo,
+        params: nextParams ?? {},
+      }).interpolatedPath
 
       const destRoutes = this.matchRoutes(
-        nextTo,
+        interpolatedNextTo,
         {},
         {
           _buildLocation: true,
@@ -1479,8 +1487,9 @@ export class RouterCore<
           })
       }
 
-      // Interpolate the next to into the next pathname
       const nextPathname = interpolatePath({
+        // Use the original template path for interpolation
+        // This preserves the original parameter syntax including optional parameters
         path: nextTo,
         params: nextParams ?? {},
         leaveWildcards: false,
@@ -1785,7 +1794,21 @@ export class RouterCore<
         state: true,
         _includeValidateSearch: true,
       })
-      if (trimPath(this.latestLocation.href) !== trimPath(nextLocation.href)) {
+
+      // Normalize URLs for comparison to handle encoding differences
+      // Browser history always stores encoded URLs while buildLocation may produce decoded URLs
+      const normalizeUrl = (url: string) => {
+        try {
+          return encodeURI(decodeURI(url))
+        } catch {
+          return url
+        }
+      }
+
+      if (
+        trimPath(normalizeUrl(this.latestLocation.href)) !==
+        trimPath(normalizeUrl(nextLocation.href))
+      ) {
         throw redirect({ href: nextLocation.href })
       }
     }
@@ -1796,6 +1819,7 @@ export class RouterCore<
     this.__store.setState((s) => ({
       ...s,
       status: 'pending',
+      statusCode: 200,
       isLoading: true,
       location: this.latestLocation,
       pendingMatches,
@@ -3225,43 +3249,51 @@ export function processRouteTree<TRouteLike extends RouteLike>({
         return 0.75
       }
 
-      if (
-        segment.type === 'param' &&
-        segment.prefixSegment &&
-        segment.suffixSegment
-      ) {
-        return 0.55
-      }
+      if (segment.type === 'param') {
+        if (segment.prefixSegment && segment.suffixSegment) {
+          return 0.55
+        }
 
-      if (segment.type === 'param' && segment.prefixSegment) {
-        return 0.52
-      }
+        if (segment.prefixSegment) {
+          return 0.52
+        }
 
-      if (segment.type === 'param' && segment.suffixSegment) {
-        return 0.51
-      }
+        if (segment.suffixSegment) {
+          return 0.51
+        }
 
-      if (segment.type === 'param') {
         return 0.5
       }
 
-      if (
-        segment.type === 'wildcard' &&
-        segment.prefixSegment &&
-        segment.suffixSegment
-      ) {
-        return 0.3
-      }
+      if (segment.type === 'optional-param') {
+        if (segment.prefixSegment && segment.suffixSegment) {
+          return 0.45
+        }
 
-      if (segment.type === 'wildcard' && segment.prefixSegment) {
-        return 0.27
-      }
+        if (segment.prefixSegment) {
+          return 0.42
+        }
 
-      if (segment.type === 'wildcard' && segment.suffixSegment) {
-        return 0.26
+        if (segment.suffixSegment) {
+          return 0.41
+        }
+
+        return 0.4
       }
 
       if (segment.type === 'wildcard') {
+        if (segment.prefixSegment && segment.suffixSegment) {
+          return 0.3
+        }
+
+        if (segment.prefixSegment) {
+          return 0.27
+        }
+
+        if (segment.suffixSegment) {
+          return 0.26
+        }
+
         return 0.25
       }
 
@@ -3275,19 +3307,33 @@ export function processRouteTree<TRouteLike extends RouteLike>({
     .sort((a, b) => {
       const minLength = Math.min(a.scores.length, b.scores.length)
 
-      // Sort by min available score
+      // Sort by segment-by-segment score comparison ONLY for the common prefix
       for (let i = 0; i < minLength; i++) {
         if (a.scores[i] !== b.scores[i]) {
           return b.scores[i]! - a.scores[i]!
         }
       }
 
-      // Sort by length of score
+      // If all common segments have equal scores, then consider length and specificity
       if (a.scores.length !== b.scores.length) {
+        // Count optional parameters in each route
+        const aOptionalCount = a.parsed.filter(
+          (seg) => seg.type === 'optional-param',
+        ).length
+        const bOptionalCount = b.parsed.filter(
+          (seg) => seg.type === 'optional-param',
+        ).length
+
+        // If different number of optional parameters, fewer optional parameters wins (more specific)
+        if (aOptionalCount !== bOptionalCount) {
+          return aOptionalCount - bOptionalCount
+        }
+
+        // If same number of optional parameters, longer path wins (for static segments)
         return b.scores.length - a.scores.length
       }
 
-      // Sort by min available parsed value
+      // Sort by min available parsed value for alphabetical ordering
       for (let i = 0; i < minLength; i++) {
         if (a.parsed[i]!.value !== b.parsed[i]!.value) {
           return a.parsed[i]!.value > b.parsed[i]!.value ? 1 : -1
@@ -3328,7 +3374,7 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
     const result = matchPathname(basepath, trimmedPath, {
       to: route.fullPath,
       caseSensitive: route.options?.caseSensitive ?? caseSensitive,
-      fuzzy: true,
+      fuzzy: false,
     })
     return result
   }