@tanstack/router-core 1.121.0-alpha.27 → 1.121.0-alpha.28

package/src/path.ts

@@ -1,13 +1,24 @@
 import { last } from './utils'
+import type { LRUCache } from './lru-cache'
 import type { MatchLocation } from './RouterProvider'
 import type { AnyPathParams } from './route'
 
+export const SEGMENT_TYPE_PATHNAME = 0
+export const SEGMENT_TYPE_PARAM = 1
+export const SEGMENT_TYPE_WILDCARD = 2
+export const SEGMENT_TYPE_OPTIONAL_PARAM = 3
+
 export interface Segment {
-  type: 'pathname' | 'param' | 'wildcard'
-  value: string
-  // Add a new property to store the static segment if present
-  prefixSegment?: string
-  suffixSegment?: string
+  readonly type:
+    | typeof SEGMENT_TYPE_PATHNAME
+    | typeof SEGMENT_TYPE_PARAM
+    | typeof SEGMENT_TYPE_WILDCARD
+    | typeof SEGMENT_TYPE_OPTIONAL_PARAM
+  readonly value: string
+  readonly prefixSegment?: string
+  readonly suffixSegment?: string
+  // Indicates if there is a static segment after this required/optional param
+  readonly hasStaticAfter?: boolean
 }
 
 export function joinPaths(paths: Array<string | undefined>) {
@@ -91,6 +102,52 @@ interface ResolvePathOptions {
   to: string
   trailingSlash?: 'always' | 'never' | 'preserve'
   caseSensitive?: boolean
+  parseCache?: ParsePathnameCache
+}
+
+function segmentToString(segment: Segment): string {
+  const { type, value } = segment
+  if (type === SEGMENT_TYPE_PATHNAME) {
+    return value
+  }
+
+  const { prefixSegment, suffixSegment } = segment
+
+  if (type === SEGMENT_TYPE_PARAM) {
+    const param = value.substring(1)
+    if (prefixSegment && suffixSegment) {
+      return `${prefixSegment}{$${param}}${suffixSegment}`
+    } else if (prefixSegment) {
+      return `${prefixSegment}{$${param}}`
+    } else if (suffixSegment) {
+      return `{$${param}}${suffixSegment}`
+    }
+  }
+
+  if (type === SEGMENT_TYPE_OPTIONAL_PARAM) {
+    const param = value.substring(1)
+    if (prefixSegment && suffixSegment) {
+      return `${prefixSegment}{-$${param}}${suffixSegment}`
+    } else if (prefixSegment) {
+      return `${prefixSegment}{-$${param}}`
+    } else if (suffixSegment) {
+      return `{-$${param}}${suffixSegment}`
+    }
+    return `{-$${param}}`
+  }
+
+  if (type === SEGMENT_TYPE_WILDCARD) {
+    if (prefixSegment && suffixSegment) {
+      return `${prefixSegment}{$}${suffixSegment}`
+    } else if (prefixSegment) {
+      return `${prefixSegment}{$}`
+    } else if (suffixSegment) {
+      return `{$}${suffixSegment}`
+    }
+  }
+
+  // This case should never happen, should we throw instead?
+  return value
 }
 
 export function resolvePath({
@@ -99,75 +156,73 @@ export function resolvePath({
   to,
   trailingSlash = 'never',
   caseSensitive,
+  parseCache,
 }: ResolvePathOptions) {
   base = removeBasepath(basepath, base, caseSensitive)
   to = removeBasepath(basepath, to, caseSensitive)
 
-  let baseSegments = parsePathname(base)
-  const toSegments = parsePathname(to)
+  let baseSegments = parsePathname(base, parseCache).slice()
+  const toSegments = parsePathname(to, parseCache)
 
   if (baseSegments.length > 1 && last(baseSegments)?.value === '/') {
     baseSegments.pop()
   }
 
-  toSegments.forEach((toSegment, index) => {
-    if (toSegment.value === '/') {
+  for (let index = 0, length = toSegments.length; index < length; index++) {
+    const toSegment = toSegments[index]!
+    const value = toSegment.value
+    if (value === '/') {
       if (!index) {
         // Leading slash
         baseSegments = [toSegment]
-      } else if (index === toSegments.length - 1) {
+      } else if (index === length - 1) {
         // Trailing Slash
         baseSegments.push(toSegment)
       } else {
         // ignore inter-slashes
       }
-    } else if (toSegment.value === '..') {
+    } else if (value === '..') {
       baseSegments.pop()
-    } else if (toSegment.value === '.') {
+    } else if (value === '.') {
       // ignore
     } else {
       baseSegments.push(toSegment)
     }
-  })
+  }
 
   if (baseSegments.length > 1) {
-    if (last(baseSegments)?.value === '/') {
+    if (last(baseSegments)!.value === '/') {
       if (trailingSlash === 'never') {
         baseSegments.pop()
       }
     } else if (trailingSlash === 'always') {
-      baseSegments.push({ type: 'pathname', value: '/' })
+      baseSegments.push({ type: SEGMENT_TYPE_PATHNAME, value: '/' })
     }
   }
 
-  const segmentValues = baseSegments.map((segment) => {
-    if (segment.type === '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}`
-      }
-    }
-    if (segment.type === 'wildcard') {
-      if (segment.prefixSegment && segment.suffixSegment) {
-        return `${segment.prefixSegment}{$}${segment.suffixSegment}`
-      } else if (segment.prefixSegment) {
-        return `${segment.prefixSegment}{$}`
-      } else if (segment.suffixSegment) {
-        return `{$}${segment.suffixSegment}`
-      }
-    }
-    return segment.value
-  })
+  const segmentValues = baseSegments.map(segmentToString)
   const joined = joinPaths([basepath, ...segmentValues])
-  return cleanPath(joined)
+  return joined
+}
+
+export type ParsePathnameCache = LRUCache<string, ReadonlyArray<Segment>>
+export const parsePathname = (
+  pathname?: string,
+  cache?: ParsePathnameCache,
+): ReadonlyArray<Segment> => {
+  if (!pathname) return []
+  const cached = cache?.get(pathname)
+  if (cached) return cached
+  const parsed = baseParsePathname(pathname)
+  cache?.set(pathname, parsed)
+  return parsed
 }
 
 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 +232,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:
@@ -186,11 +243,7 @@ const WILDCARD_W_CURLY_BRACES_RE = /^(.*?)\{\$\}(.*)$/ // prefix{$}suffix
  * - `/foo/[$]{$foo} - Dynamic route with a static prefix of `$`
  * - `/foo/{$foo}[$]` - Dynamic route with a static suffix of `$`
  */
-export function parsePathname(pathname?: string): Array<Segment> {
-  if (!pathname) {
-    return []
-  }
-
+function baseParsePathname(pathname: string): ReadonlyArray<Segment> {
   pathname = cleanPath(pathname)
 
   const segments: Array<Segment> = []
@@ -198,7 +251,7 @@ export function parsePathname(pathname?: string): Array<Segment> {
   if (pathname.slice(0, 1) === '/') {
     pathname = pathname.substring(1)
     segments.push({
-      type: 'pathname',
+      type: SEGMENT_TYPE_PATHNAME,
       value: '/',
     })
   }
@@ -218,13 +271,29 @@ export function parsePathname(pathname?: string): Array<Segment> {
         const prefix = wildcardBracesMatch[1]
         const suffix = wildcardBracesMatch[2]
         return {
-          type: 'wildcard',
+          type: SEGMENT_TYPE_WILDCARD,
           value: '$',
           prefixSegment: prefix || undefined,
           suffixSegment: suffix || undefined,
         }
       }
 
+      // 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: SEGMENT_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) {
@@ -232,7 +301,7 @@ export function parsePathname(pathname?: string): Array<Segment> {
         const paramName = paramBracesMatch[2]
         const suffix = paramBracesMatch[3]
         return {
-          type: 'param',
+          type: SEGMENT_TYPE_PARAM,
           value: '' + paramName,
           prefixSegment: prefix || undefined,
           suffixSegment: suffix || undefined,
@@ -243,7 +312,7 @@ export function parsePathname(pathname?: string): Array<Segment> {
       if (PARAM_RE.test(part)) {
         const paramName = part.substring(1)
         return {
-          type: 'param',
+          type: SEGMENT_TYPE_PARAM,
           value: '$' + paramName,
           prefixSegment: undefined,
           suffixSegment: undefined,
@@ -253,7 +322,7 @@ export function parsePathname(pathname?: string): Array<Segment> {
       // Check for bare wildcard: $ (without curly braces)
       if (WILDCARD_RE.test(part)) {
         return {
-          type: 'wildcard',
+          type: SEGMENT_TYPE_WILDCARD,
           value: '$',
           prefixSegment: undefined,
           suffixSegment: undefined,
@@ -262,7 +331,7 @@ export function parsePathname(pathname?: string): Array<Segment> {
 
       // Handle regular pathname segment
       return {
-        type: 'pathname',
+        type: SEGMENT_TYPE_PATHNAME,
         value: part.includes('%25')
           ? part
               .split('%25')
@@ -276,7 +345,7 @@ export function parsePathname(pathname?: string): Array<Segment> {
   if (pathname.slice(-1) === '/') {
     pathname = pathname.substring(1)
     segments.push({
-      type: 'pathname',
+      type: SEGMENT_TYPE_PATHNAME,
       value: '/',
     })
   }
@@ -291,6 +360,7 @@ interface InterpolatePathOptions {
   leaveParams?: boolean
   // Map of encoded chars to decoded chars (e.g. '%40' -> '@') that should remain decoded in path params
   decodeCharMap?: Map<string, string>
+  parseCache?: ParsePathnameCache
 }
 
 type InterPolatePathResult = {
@@ -304,14 +374,15 @@ export function interpolatePath({
   leaveWildcards,
   leaveParams,
   decodeCharMap,
+  parseCache,
 }: InterpolatePathOptions): InterPolatePathResult {
-  const interpolatedPathSegments = parsePathname(path)
+  const interpolatedPathSegments = parsePathname(path, parseCache)
 
   function encodeParam(key: string): any {
     const value = params[key]
     const isValueString = typeof value === 'string'
 
-    if (['*', '_splat'].includes(key)) {
+    if (key === '*' || key === '_splat') {
       // the splat/catch-all routes shouldn't have the '/' encoded out
       return isValueString ? encodeURI(value) : value
     } else {
@@ -326,10 +397,29 @@ export function interpolatePath({
   const usedParams: Record<string, unknown> = {}
   const interpolatedPath = joinPaths(
     interpolatedPathSegments.map((segment) => {
-      if (segment.type === 'wildcard') {
+      if (segment.type === SEGMENT_TYPE_PATHNAME) {
+        return segment.value
+      }
+
+      if (segment.type === SEGMENT_TYPE_WILDCARD) {
         usedParams._splat = params._splat
         const segmentPrefix = segment.prefixSegment || ''
         const segmentSuffix = segment.suffixSegment || ''
+
+        // Check if _splat parameter is missing
+        if (!('_splat' in params)) {
+          isMissingParams = true
+          // For missing splat parameters, just return the prefix and suffix without the wildcard
+          if (leaveWildcards) {
+            return `${segmentPrefix}${segment.value}${segmentSuffix}`
+          }
+          // If there is a prefix or suffix, return them joined, otherwise omit the segment
+          if (segmentPrefix || segmentSuffix) {
+            return `${segmentPrefix}${segmentSuffix}`
+          }
+          return undefined
+        }
+
         const value = encodeParam('_splat')
         if (leaveWildcards) {
           return `${segmentPrefix}${segment.value}${value ?? ''}${segmentSuffix}`
@@ -337,7 +427,7 @@ export function interpolatePath({
         return `${segmentPrefix}${value}${segmentSuffix}`
       }
 
-      if (segment.type === 'param') {
+      if (segment.type === SEGMENT_TYPE_PARAM) {
         const key = segment.value.substring(1)
         if (!isMissingParams && !(key in params)) {
           isMissingParams = true
@@ -353,6 +443,37 @@ export function interpolatePath({
         return `${segmentPrefix}${encodeParam(key) ?? 'undefined'}${segmentSuffix}`
       }
 
+      if (segment.type === 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) {
+          if (leaveWildcards) {
+            return `${segmentPrefix}${key}${segmentSuffix}`
+          }
+          // 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}`
+        }
+        if (leaveWildcards) {
+          return `${segmentPrefix}${key}${encodeParam(key) ?? ''}${segmentSuffix}`
+        }
+        return `${segmentPrefix}${encodeParam(key) ?? ''}${segmentSuffix}`
+      }
+
       return segment.value
     }),
   )
@@ -373,8 +494,14 @@ export function matchPathname(
   basepath: string,
   currentPathname: string,
   matchLocation: Pick<MatchLocation, 'to' | 'fuzzy' | 'caseSensitive'>,
+  parseCache?: ParsePathnameCache,
 ): AnyPathParams | undefined {
-  const pathParams = matchByPath(basepath, currentPathname, matchLocation)
+  const pathParams = matchByPath(
+    basepath,
+    currentPathname,
+    matchLocation,
+    parseCache,
+  )
   // const searchMatched = matchBySearch(location.search, matchLocation)
 
   if (matchLocation.to && !pathParams) {
@@ -428,156 +555,221 @@ export function removeBasepath(
 export function matchByPath(
   basepath: string,
   from: string,
-  matchLocation: Pick<MatchLocation, 'to' | 'caseSensitive' | 'fuzzy'>,
+  {
+    to,
+    fuzzy,
+    caseSensitive,
+  }: Pick<MatchLocation, 'to' | 'caseSensitive' | 'fuzzy'>,
+  parseCache?: ParsePathnameCache,
 ): Record<string, string> | undefined {
   // check basepath first
   if (basepath !== '/' && !from.startsWith(basepath)) {
     return undefined
   }
   // Remove the base path from the pathname
-  from = removeBasepath(basepath, from, matchLocation.caseSensitive)
+  from = removeBasepath(basepath, from, caseSensitive)
   // Default to to $ (wildcard)
-  const to = removeBasepath(
-    basepath,
-    `${matchLocation.to ?? '$'}`,
-    matchLocation.caseSensitive,
-  )
+  to = removeBasepath(basepath, `${to ?? '$'}`, caseSensitive)
 
   // Parse the from and to
-  const baseSegments = parsePathname(from)
-  const routeSegments = parsePathname(to)
+  const baseSegments = parsePathname(
+    from.startsWith('/') ? from : `/${from}`,
+    parseCache,
+  )
+  const routeSegments = parsePathname(
+    to.startsWith('/') ? to : `/${to}`,
+    parseCache,
+  )
 
-  if (!from.startsWith('/')) {
-    baseSegments.unshift({
-      type: 'pathname',
-      value: '/',
-    })
-  }
+  const params: Record<string, string> = {}
 
-  if (!to.startsWith('/')) {
-    routeSegments.unshift({
-      type: 'pathname',
-      value: '/',
-    })
-  }
+  const result = isMatch(
+    baseSegments,
+    routeSegments,
+    params,
+    fuzzy,
+    caseSensitive,
+  )
 
-  const params: Record<string, string> = {}
+  return result ? params : undefined
+}
 
-  const isMatch = (() => {
-    for (
-      let i = 0;
-      i < Math.max(baseSegments.length, routeSegments.length);
-      i++
-    ) {
-      const baseSegment = baseSegments[i]
-      const routeSegment = routeSegments[i]
-
-      const isLastBaseSegment = i >= baseSegments.length - 1
-      const isLastRouteSegment = i >= routeSegments.length - 1
-
-      if (routeSegment) {
-        if (routeSegment.type === 'wildcard') {
-          // Capture all remaining segments for a wildcard
-          const remainingBaseSegments = baseSegments.slice(i)
-
-          let _splat: string
-
-          // If this is a wildcard with prefix/suffix, we need to handle the first segment specially
-          if (routeSegment.prefixSegment || routeSegment.suffixSegment) {
-            if (!baseSegment) return false
-
-            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 ('prefixSegment' in routeSegment) {
-              if (!baseValue.startsWith(prefix)) {
-                return false
-              }
-            }
-            if ('suffixSegment' in routeSegment) {
-              if (
-                !baseSegments[baseSegments.length - 1]?.value.endsWith(suffix)
-              ) {
-                return false
-              }
-            }
+function isMatch(
+  baseSegments: ReadonlyArray<Segment>,
+  routeSegments: ReadonlyArray<Segment>,
+  params: Record<string, string>,
+  fuzzy?: boolean,
+  caseSensitive?: boolean,
+): boolean {
+  let baseIndex = 0
+  let routeIndex = 0
 
-            let rejoinedSplat = decodeURI(
-              joinPaths(remainingBaseSegments.map((d) => d.value)),
-            )
+  while (baseIndex < baseSegments.length || routeIndex < routeSegments.length) {
+    const baseSegment = baseSegments[baseIndex]
+    const routeSegment = routeSegments[routeIndex]
 
-            // Remove the prefix and suffix from the rejoined splat
-            if (prefix && rejoinedSplat.startsWith(prefix)) {
-              rejoinedSplat = rejoinedSplat.slice(prefix.length)
-            }
+    if (routeSegment) {
+      if (routeSegment.type === SEGMENT_TYPE_WILDCARD) {
+        // Capture all remaining segments for a wildcard
+        const remainingBaseSegments = baseSegments.slice(baseIndex)
 
-            if (suffix && rejoinedSplat.endsWith(suffix)) {
-              rejoinedSplat = rejoinedSplat.slice(
-                0,
-                rejoinedSplat.length - suffix.length,
-              )
+        let _splat: string
+
+        // If this is a wildcard with prefix/suffix, we need to handle the first segment specially
+        if (routeSegment.prefixSegment || routeSegment.suffixSegment) {
+          if (!baseSegment) return false
+
+          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 ('prefixSegment' in routeSegment) {
+            if (!baseValue.startsWith(prefix)) {
+              return false
+            }
+          }
+          if ('suffixSegment' in routeSegment) {
+            if (
+              !baseSegments[baseSegments.length - 1]?.value.endsWith(suffix)
+            ) {
+              return false
             }
+          }
+
+          let rejoinedSplat = decodeURI(
+            joinPaths(remainingBaseSegments.map((d) => d.value)),
+          )
 
-            _splat = rejoinedSplat
-          } else {
-            // If no prefix/suffix, just rejoin the remaining segments
-            _splat = decodeURI(
-              joinPaths(remainingBaseSegments.map((d) => d.value)),
+          // Remove the prefix and suffix from the rejoined splat
+          if (prefix && rejoinedSplat.startsWith(prefix)) {
+            rejoinedSplat = rejoinedSplat.slice(prefix.length)
+          }
+
+          if (suffix && rejoinedSplat.endsWith(suffix)) {
+            rejoinedSplat = rejoinedSplat.slice(
+              0,
+              rejoinedSplat.length - suffix.length,
             )
           }
 
-          // TODO: Deprecate *
-          params['*'] = _splat
-          params['_splat'] = _splat
-          return true
+          _splat = rejoinedSplat
+        } else {
+          // If no prefix/suffix, just rejoin the remaining segments
+          _splat = decodeURI(
+            joinPaths(remainingBaseSegments.map((d) => d.value)),
+          )
         }
 
-        if (routeSegment.type === 'pathname') {
-          if (routeSegment.value === '/' && !baseSegment?.value) {
-            return true
-          }
+        // TODO: Deprecate *
+        params['*'] = _splat
+        params['_splat'] = _splat
+        return true
+      }
 
-          if (baseSegment) {
-            if (matchLocation.caseSensitive) {
-              if (routeSegment.value !== baseSegment.value) {
-                return false
-              }
-            } else if (
-              routeSegment.value.toLowerCase() !==
-              baseSegment.value.toLowerCase()
-            ) {
+      if (routeSegment.type === SEGMENT_TYPE_PATHNAME) {
+        if (routeSegment.value === '/' && !baseSegment?.value) {
+          routeIndex++
+          continue
+        }
+
+        if (baseSegment) {
+          if (caseSensitive) {
+            if (routeSegment.value !== baseSegment.value) {
               return false
             }
+          } else if (
+            routeSegment.value.toLowerCase() !== baseSegment.value.toLowerCase()
+          ) {
+            return false
           }
+          baseIndex++
+          routeIndex++
+          continue
+        } else {
+          return false
         }
+      }
 
+      if (routeSegment.type === SEGMENT_TYPE_PARAM) {
         if (!baseSegment) {
           return false
         }
 
-        if (routeSegment.type === 'param') {
-          if (baseSegment.value === '/') {
+        if (baseSegment.value === '/') {
+          return false
+        }
+
+        let _paramValue = ''
+        let matched = false
+
+        // If this 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)) {
+            return false
+          }
+          if (suffix && !baseValue.endsWith(suffix)) {
             return false
           }
 
-          let _paramValue: string
+          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)
+          }
 
-          // If this 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 || ''
+          _paramValue = decodeURIComponent(paramValue)
+          matched = true
+        } else {
+          // If no prefix/suffix, just decode the base segment value
+          _paramValue = decodeURIComponent(baseSegment.value)
+          matched = true
+        }
 
-            // Check if the base segment starts with prefix and ends with suffix
-            const baseValue = baseSegment.value
-            if (prefix && !baseValue.startsWith(prefix)) {
-              return false
-            }
-            if (suffix && !baseValue.endsWith(suffix)) {
-              return false
-            }
+        if (matched) {
+          params[routeSegment.value.substring(1)] = _paramValue
+          baseIndex++
+        }
+
+        routeIndex++
+        continue
+      }
+
+      if (routeSegment.type === SEGMENT_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)
@@ -590,23 +782,81 @@ export function matchByPath(
             }
 
             _paramValue = decodeURIComponent(paramValue)
-          } else {
+            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 === SEGMENT_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 === SEGMENT_TYPE_PARAM ||
+              futureRouteSegment?.type === SEGMENT_TYPE_WILDCARD
+            ) {
+              if (baseSegments.length < routeSegments.length) {
+                shouldMatchOptional = false
+              }
+              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))
-        return !!matchLocation.fuzzy && routeSegment?.value !== '/'
+    // If we have base segments left but no route segments, it's a fuzzy match
+    if (baseIndex < baseSegments.length && routeIndex >= routeSegments.length) {
+      params['**'] = joinPaths(
+        baseSegments.slice(baseIndex).map((d) => d.value),
+      )
+      return !!fuzzy && routeSegments[routeSegments.length - 1]?.value !== '/'
+    }
+
+    // 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 !== SEGMENT_TYPE_OPTIONAL_PARAM) {
+          return false
+        }
       }
+      // All remaining are optional, so we can finish
+      break
     }
 
-    return true
-  })()
+    break
+  }
 
-  return isMatch ? params : undefined
+  return true
 }