@benjavicente/router-core 1.168.9 → 1.169.2

package/src/new-process-route-tree.ts

@@ -207,10 +207,8 @@ function parseSegments<TRouteLike extends RouteLike>(
     const path = route.fullPath ?? route.from
     const length = path.length
     const caseSensitive = route.options?.caseSensitive ?? defaultCaseSensitive
-    const skipOnParamError = !!(
-      route.options?.params?.parse &&
-      route.options?.skipRouteOnParseError?.params
-    )
+    const parseParams =
+      route.options?.params?.parse ?? route.options?.parseParams
     while (cursor < length) {
       const segment = parseSegment(path, cursor, data)
       let nextNode: AnySegmentNode<TRouteLike>
@@ -270,10 +268,10 @@ function parseSegments<TRouteLike extends RouteLike>(
               ? suffix_raw
               : suffix_raw.toLowerCase()
           const existingNode =
-            !skipOnParamError &&
+            !parseParams &&
             node.dynamic?.find(
               (s) =>
-                !s.skipOnParamError &&
+                !s.parse &&
                 s.caseSensitive === actuallyCaseSensitive &&
                 s.prefix === prefix &&
                 s.suffix === suffix,
@@ -312,10 +310,10 @@ function parseSegments<TRouteLike extends RouteLike>(
               ? suffix_raw
               : suffix_raw.toLowerCase()
           const existingNode =
-            !skipOnParamError &&
+            !parseParams &&
             node.optional?.find(
               (s) =>
-                !s.skipOnParamError &&
+                !s.parse &&
                 s.caseSensitive === actuallyCaseSensitive &&
                 s.prefix === prefix &&
                 s.suffix === suffix,
@@ -372,7 +370,7 @@ function parseSegments<TRouteLike extends RouteLike>(
 
     // create pathless node
     if (
-      skipOnParamError &&
+      parseParams &&
       route.children &&
       !route.isRoot &&
       route.id &&
@@ -404,9 +402,7 @@ function parseSegments<TRouteLike extends RouteLike>(
       node = indexNode
     }
 
-    node.parse = route.options?.params?.parse ?? null
-    node.skipOnParamError = skipOnParamError
-    node.parsingPriority = route.options?.skipRouteOnParseError?.priority ?? 0
+    node.parse = parseParams ?? null
 
     // make node "matchable"
     if (isLeaf && !node.route) {
@@ -433,25 +429,17 @@ function sortDynamic(
     prefix?: string
     suffix?: string
     caseSensitive: boolean
-    skipOnParamError: boolean
-    parsingPriority: number
+    parse: null | ((params: Record<string, string>) => unknown)
   },
   b: {
     prefix?: string
     suffix?: string
     caseSensitive: boolean
-    skipOnParamError: boolean
-    parsingPriority: number
+    parse: null | ((params: Record<string, string>) => unknown)
   },
 ) {
-  if (a.skipOnParamError && !b.skipOnParamError) return -1
-  if (!a.skipOnParamError && b.skipOnParamError) return 1
-  if (
-    a.skipOnParamError &&
-    b.skipOnParamError &&
-    (a.parsingPriority || b.parsingPriority)
-  )
-    return b.parsingPriority - a.parsingPriority
+  if (a.parse && !b.parse) return -1
+  if (!a.parse && b.parse) return 1
   if (a.prefix && b.prefix && a.prefix !== b.prefix) {
     if (a.prefix.startsWith(b.prefix)) return -1
     if (b.prefix.startsWith(a.prefix)) return 1
@@ -467,8 +455,7 @@ function sortDynamic(
   if (a.caseSensitive && !b.caseSensitive) return -1
   if (!a.caseSensitive && b.caseSensitive) return 1
 
-  // we don't need a tiebreaker here
-  // at this point the 2 nodes cannot conflict during matching
+  // Equal specificity preserves route declaration order through stable sort.
   return 0
 }
 
@@ -525,8 +512,6 @@ function createStaticNode<T extends RouteLike>(
     fullPath,
     parent: null,
     parse: null,
-    skipOnParamError: false,
-    parsingPriority: 0,
   }
 }
 
@@ -558,8 +543,6 @@ function createDynamicNode<T extends RouteLike>(
     fullPath,
     parent: null,
     parse: null,
-    skipOnParamError: false,
-    parsingPriority: 0,
     caseSensitive,
     prefix,
     suffix,
@@ -621,13 +604,7 @@ type SegmentNode<T extends RouteLike> = {
   depth: number
 
   /** route.options.params.parse function, set on the last node of the route */
-  parse: null | ((params: Record<string, string>) => any)
-
-  /** options.skipRouteOnParseError.params ?? false */
-  skipOnParamError: boolean
-
-  /** options.skipRouteOnParseError.priority ?? 0 */
-  parsingPriority: number
+  parse: null | ((params: Record<string, string>) => unknown)
 }
 
 type RouteLike = {
@@ -637,13 +614,10 @@ type RouteLike = {
   parentRoute?: RouteLike // parent route,
   isRoot?: boolean
   options?: {
-    skipRouteOnParseError?: {
-      params?: boolean
-      priority?: number
-    }
     caseSensitive?: boolean
+    parseParams?: (params: Record<string, string>) => unknown
     params?: {
-      parse?: (params: Record<string, string>) => any
+      parse?: (params: Record<string, string>) => unknown
     }
   }
 } &
@@ -734,7 +708,6 @@ export function findSingleMatch(
 type RouteMatch<T extends Extract<RouteLike, { fullPath: string }>> = {
   route: T
   rawParams: Record<string, string>
-  parsedParams?: Record<string, unknown>
   branch: ReadonlyArray<T>
 }
 
@@ -858,11 +831,6 @@ function findMatch<T extends RouteLike>(
    * This will be the exhaustive list of all params defined in the route's path.
    */
   rawParams: Record<string, string>
-  /**
-   * The accumlulated parsed params of each route in the branch that had `skipRouteOnParseError` enabled.
-   * Will not contain all params defined in the route's path. Those w/ a `params.parse` but no `skipRouteOnParseError` will need to be parsed separately.
-   */
-  parsedParams?: Record<string, unknown>
 } | null {
   const parts = path.split('/')
   const leaf = getNodeMatch(path, parts, segmentTree, fuzzy)
@@ -871,7 +839,6 @@ function findMatch<T extends RouteLike>(
   return {
     route: leaf.node.route!,
     rawParams,
-    parsedParams: leaf.parsedParams,
   }
 }
 
@@ -991,7 +958,7 @@ function extractParams<T extends RouteLike>(
   ]
 }
 
-function buildRouteBranch<T extends RouteLike>(route: T) {
+export function buildRouteBranch<T extends RouteLike>(route: T) {
   const list = [route]
   while (route.parentRoute) {
     route = route.parentRoute as T
@@ -1023,6 +990,7 @@ type MatchStackFrame<T extends RouteLike> = {
    * If we really really need to support more than 32 segments we can switch to using a `BigInt` here. It's about 2x slower in worst case scenarios.
    */
   skipped: number
+  /** Positional bitmasks tracking which consumed URL segments matched each segment kind. */
   statics: number
   dynamics: number
   optionals: number
@@ -1030,7 +998,6 @@ type MatchStackFrame<T extends RouteLike> = {
   extract?: ParamExtractionState
   /** intermediary params from param extraction */
   rawParams?: Record<string, string>
-  parsedParams?: Record<string, unknown>
 }
 
 function getNodeMatch<T extends RouteLike>(
@@ -1044,7 +1011,7 @@ function getNodeMatch<T extends RouteLike>(
   if (path === '/' && segmentTree.index)
     return { node: segmentTree.index, skipped: 0 } as Pick<
       Frame,
-      'node' | 'skipped' | 'parsedParams'
+      'node' | 'skipped'
     >
 
   const trailingSlash = !last(parts)
@@ -1066,27 +1033,37 @@ function getNodeMatch<T extends RouteLike>(
       index: 1,
       skipped: 0,
       depth: 1,
-      statics: 1,
+      statics: 0,
       dynamics: 0,
       optionals: 0,
     },
   ]
 
-  let wildcardMatch: Frame | null = null
   let bestFuzzy: Frame | null = null
   let bestMatch: Frame | null = null
 
   while (stack.length) {
     const frame = stack.pop()!
     const { node, index, skipped, depth, statics, dynamics, optionals } = frame
-    let { extract, rawParams, parsedParams } = frame
+    let { extract, rawParams } = frame
 
-    if (node.skipOnParamError) {
-      const result = validateMatchParams(path, parts, frame)
+    // Wildcard candidates are pushed speculatively as fallbacks in case a
+    // higher-priority wildcard later fails params.parse. If a better wildcard
+    // has already validated and become bestMatch, lower-priority wildcard
+    // fallbacks cannot win anymore and should not run params.parse.
+    if (
+      node.kind === SEGMENT_TYPE_WILDCARD &&
+      node.route &&
+      !isFrameMoreSpecific(bestMatch, frame)
+    ) {
+      continue
+    }
+
+    if (node.parse) {
+      const result = validateParseParams(path, parts, frame)
       if (!result) continue
       rawParams = frame.rawParams
       extract = frame.extract
-      parsedParams = frame.parsedParams
     }
 
     // In fuzzy mode, track the best partial match we've found so far
@@ -1101,7 +1078,13 @@ function getNodeMatch<T extends RouteLike>(
 
     const isBeyondPath = index === partsLength
     if (isBeyondPath) {
-      if (node.route && !pathIsIndex && isFrameMoreSpecific(bestMatch, frame)) {
+      if (
+        node.route &&
+        (!pathIsIndex ||
+          node.kind === SEGMENT_TYPE_INDEX ||
+          node.kind === SEGMENT_TYPE_WILDCARD) &&
+        isFrameMoreSpecific(bestMatch, frame)
+      ) {
         bestMatch = frame
       }
       // beyond the length of the path parts, only some segment types can match
@@ -1124,17 +1107,21 @@ function getNodeMatch<T extends RouteLike>(
         optionals,
         extract,
         rawParams,
-        parsedParams,
       }
       let indexValid = true
-      if (node.index.skipOnParamError) {
-        const result = validateMatchParams(path, parts, indexFrame)
+      if (node.index.parse) {
+        const result = validateParseParams(path, parts, indexFrame)
         if (!result) indexValid = false
       }
       if (indexValid) {
         // perfect match, no need to continue
         // this is an optimization, algorithm should work correctly without this block
-        if (statics === partsLength && !dynamics && !optionals && !skipped) {
+        if (
+          !dynamics &&
+          !optionals &&
+          !skipped &&
+          isPerfectStaticMatch(statics, partsLength)
+        ) {
           return indexFrame
         }
         if (isFrameMoreSpecific(bestMatch, indexFrame)) {
@@ -1145,8 +1132,9 @@ function getNodeMatch<T extends RouteLike>(
     }
 
     // 5. Try wildcard match
-    if (node.wildcard && isFrameMoreSpecific(wildcardMatch, frame)) {
-      for (const segment of node.wildcard) {
+    if (node.wildcard) {
+      for (let i = node.wildcard.length - 1; i >= 0; i--) {
+        const segment = node.wildcard[i]!
         const { prefix, suffix } = segment
         if (prefix) {
           if (isBeyondPath) continue
@@ -1161,26 +1149,18 @@ function getNodeMatch<T extends RouteLike>(
           const casePart = segment.caseSensitive ? end : end.toLowerCase()
           if (casePart !== suffix) continue
         }
-        // the first wildcard match is the highest priority one
-        // wildcard matches skip the stack because they cannot have children
-        const frame = {
+        // wildcard matches consume the rest of the URL and cannot have children
+        stack.push({
           node: segment,
           index: partsLength,
           skipped,
-          depth,
+          depth: depth + 1,
           statics,
           dynamics,
           optionals,
           extract,
           rawParams,
-          parsedParams,
-        }
-        if (segment.skipOnParamError) {
-          const result = validateMatchParams(path, parts, frame)
-          if (!result) continue
-        }
-        wildcardMatch = frame
-        break
+        })
       }
     }
 
@@ -1201,7 +1181,6 @@ function getNodeMatch<T extends RouteLike>(
           optionals,
           extract,
           rawParams,
-          parsedParams,
         }) // enqueue skipping the optional
       }
       if (!isBeyondPath) {
@@ -1222,10 +1201,9 @@ function getNodeMatch<T extends RouteLike>(
             depth: nextDepth,
             statics,
             dynamics,
-            optionals: optionals + 1,
+            optionals: optionals + segmentScore(partsLength, index),
             extract,
             rawParams,
-            parsedParams,
           })
         }
       }
@@ -1249,11 +1227,10 @@ function getNodeMatch<T extends RouteLike>(
           skipped,
           depth: depth + 1,
           statics,
-          dynamics: dynamics + 1,
+          dynamics: dynamics + segmentScore(partsLength, index),
           optionals,
           extract,
           rawParams,
-          parsedParams,
         })
       }
     }
@@ -1269,12 +1246,11 @@ function getNodeMatch<T extends RouteLike>(
           index: index + 1,
           skipped,
           depth: depth + 1,
-          statics: statics + 1,
+          statics: statics + segmentScore(partsLength, index),
           dynamics,
           optionals,
           extract,
           rawParams,
-          parsedParams,
         })
       }
     }
@@ -1288,12 +1264,11 @@ function getNodeMatch<T extends RouteLike>(
           index: index + 1,
           skipped,
           depth: depth + 1,
-          statics: statics + 1,
+          statics: statics + segmentScore(partsLength, index),
           dynamics,
           optionals,
           extract,
           rawParams,
-          parsedParams,
         })
       }
     }
@@ -1313,22 +1288,13 @@ function getNodeMatch<T extends RouteLike>(
           optionals,
           extract,
           rawParams,
-          parsedParams,
         })
       }
     }
   }
 
-  if (bestMatch && wildcardMatch) {
-    return isFrameMoreSpecific(wildcardMatch, bestMatch)
-      ? bestMatch
-      : wildcardMatch
-  }
-
   if (bestMatch) return bestMatch
 
-  if (wildcardMatch) return wildcardMatch
-
   if (fuzzy && bestFuzzy) {
     let sliceIndex = bestFuzzy.index
     for (let i = 0; i < bestFuzzy.index; i++) {
@@ -1343,25 +1309,46 @@ function getNodeMatch<T extends RouteLike>(
   return null
 }
 
-function validateMatchParams<T extends RouteLike>(
+function segmentScore(partsLength: number, index: number): number {
+  // The specificity scores are bitmasks over consumed URL segments. Earlier
+  // URL segments should dominate later ones when comparing scores, so the
+  // first real segment gets the highest bit and the last gets bit 0. Since
+  // `parts[0]` is the empty string before the leading slash, real URL segments
+  // are [1, partsLength), making this segment's bit `partsLength - index - 1`.
+  return 2 ** (partsLength - index - 1)
+}
+
+function isPerfectStaticMatch(statics: number, partsLength: number): boolean {
+  return statics === 2 ** (partsLength - 1) - 1
+}
+
+function validateParseParams<T extends RouteLike>(
   path: string,
   parts: Array<string>,
   frame: MatchStackFrame<T>,
 ) {
+  let rawParams: Record<string, string>
+  let state: ParamExtractionState
+
   try {
-    const [rawParams, state] = extractParams(path, parts, frame)
-    frame.rawParams = rawParams
-    frame.extract = state
-    const parsed = frame.node.parse!(rawParams)
-    frame.parsedParams = Object.assign(
-      Object.create(null),
-      frame.parsedParams,
-      parsed,
-    )
-    return true
+    ;[rawParams, state] = extractParams(path, parts, frame)
   } catch {
     return null
   }
+
+  frame.rawParams = rawParams
+  frame.extract = state
+
+  if (!frame.node.parse) return true
+
+  try {
+    if (frame.node.parse(rawParams) === false) return null
+  } catch {
+    // Thrown parse errors should be surfaced on the selected match by
+    // extractStrictParams, not used as fallback route selection.
+  }
+
+  return true
 }
 
 function isFrameMoreSpecific(

package/src/not-found.ts

@@ -37,5 +37,5 @@ export function notFound(options: NotFoundError = {}) {
 
 /** Determine if a value is a TanStack Router not-found error. */
 export function isNotFound(obj: any): obj is NotFoundError {
-  return !!obj?.isNotFound
+  return obj?.isNotFound === true
 }

package/src/path.ts

@@ -167,33 +167,7 @@ export function resolvePath({
     }
   }
 
-  let segment
-  let joined = ''
-  for (let i = 0; i < baseSegments.length; i++) {
-    if (i > 0) joined += '/'
-    const part = baseSegments[i]!
-    if (!part) continue
-    segment = parseSegment(part, 0, segment)
-    const kind = segment[0]
-    if (kind === SEGMENT_TYPE_PATHNAME) {
-      joined += part
-      continue
-    }
-    const end = segment[5]
-    const prefix = part.substring(0, segment[1])
-    const suffix = part.substring(segment[4], end)
-    const value = part.substring(segment[2], segment[3])
-    if (kind === SEGMENT_TYPE_PARAM) {
-      joined += prefix || suffix ? `${prefix}{$${value}}${suffix}` : `$${value}`
-    } else if (kind === SEGMENT_TYPE_WILDCARD) {
-      joined += prefix || suffix ? `${prefix}{$}${suffix}` : '$'
-    } else {
-      // SEGMENT_TYPE_OPTIONAL_PARAM
-      joined += `${prefix}{-$${value}}${suffix}`
-    }
-  }
-  joined = cleanPath(joined)
-  const result = joined || '/'
+  const result = cleanPath(baseSegments.join('/')) || '/'
   if (key && cache) cache.set(key, result)
   return result
 }

package/src/route.ts

@@ -173,9 +173,13 @@ export type ResolveParams<
 
 export type ParseParamsFn<in out TPath extends string, in out TParams> = (
   rawParams: Expand<ResolveParams<TPath>>,
-) => TParams extends ResolveParams<TPath, any>
-  ? TParams
-  : ResolveParams<TPath, any>
+) => TParams | false
+
+type ValidateParsedParams<TPath extends string, TParams> = [TParams] extends [
+  ResolveParams<TPath, any>,
+]
+  ? unknown
+  : never
 
 export type StringifyParamsFn<in out TPath extends string, in out TParams> = (
   params: TParams,
@@ -183,14 +187,15 @@ export type StringifyParamsFn<in out TPath extends string, in out TParams> = (
 
 export type ParamsOptions<in out TPath extends string, in out TParams> = {
   params?: {
-    parse?: ParseParamsFn<TPath, TParams>
+    parse?: ParseParamsFn<TPath, TParams> & ValidateParsedParams<TPath, TParams>
     stringify?: StringifyParamsFn<TPath, TParams>
   }
 
   /** 
   @deprecated Use params.parse instead
   */
-  parseParams?: ParseParamsFn<TPath, TParams>
+  parseParams?: ParseParamsFn<TPath, TParams> &
+    ValidateParsedParams<TPath, TParams>
 
   /** 
   @deprecated Use params.stringify instead
@@ -1293,37 +1298,6 @@ export interface UpdatableRouteOptions<
   in out TBeforeLoadFn,
 >
   extends UpdatableStaticRouteOption, UpdatableRouteOptionsExtensions {
-  /**
-   * Options to control route matching behavior with runtime code.
-   *
-   * @experimental 🚧 this feature is subject to change
-   *
-   * @link https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType
-   */
-  skipRouteOnParseError?: {
-    /**
-     * If `true`, skip this route during matching if `params.parse` fails.
-     *
-     * Without this option, a `/$param` route could match *any* value for `param`,
-     * and only later during the route lifecycle would `params.parse` run and potentially
-     * show the `errorComponent` if validation failed.
-     *
-     * With this option enabled, the route will only match if `params.parse` succeeds.
-     * If it fails, the router will continue trying to match other routes, potentially
-     * finding a different route that works, or ultimately showing the `notFoundComponent`.
-     *
-     * @default false
-     */
-    params?: boolean
-    /**
-     * In cases where multiple routes would need to run `params.parse` during matching
-     * to determine which route to pick, this priority number can be used as a tie-breaker
-     * for which route to try first. Higher number = higher priority.
-     *
-     * @default 0
-     */
-    priority?: number
-  }
   /**
    * If true, this route will be matched as case-sensitive
    *