feat(router-core): validate params while matching

packages/router-core/src/route.ts

@@ -1188,9 +1188,46 @@ export interface UpdatableRouteOptions<
   in out TBeforeLoadFn,
 > extends UpdatableStaticRouteOption,
     UpdatableRouteOptionsExtensions {
-  // If true, this route will be matched as case-sensitive
+  /**
+   * 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
+   *
+   * @default false
+   */
   caseSensitive?: boolean
-  // If true, this route will be forcefully wrapped in a suspense boundary
+  /**
+   * If true, this route will be forcefully wrapped in a suspense boundary
+   */
   wrapInSuspense?: boolean
   // The content to be rendered when the route is matched. If no component is provided, defaults to `<Outlet />`
 

packages/router-core/src/router.ts

@@ -698,8 +698,12 @@ export type ParseLocationFn<TRouteTree extends AnyRoute> = (
 
 export type GetMatchRoutesFn = (pathname: string) => {
   matchedRoutes: ReadonlyArray<AnyRoute>
+  /** exhaustive params, still in their string form */
   routeParams: Record<string, string>
+  /** partial params, parsed from routeParams during matching */
+  parsedParams: Record<string, unknown> | undefined
   foundRoute: AnyRoute | undefined
+  parseError?: unknown
 }
 
 export type EmitFn = (routerEvent: RouterEvent) => void
@@ -1260,7 +1264,7 @@ export class RouterCore<
     opts?: MatchRoutesOpts,
   ): Array<AnyRouteMatch> {
     const matchedRoutesResult = this.getMatchedRoutes(next.pathname)
-    const { foundRoute, routeParams } = matchedRoutesResult
+    const { foundRoute, routeParams, parsedParams } = matchedRoutesResult
     let { matchedRoutes } = matchedRoutesResult
     let isGlobalNotFound = false
 
@@ -1401,26 +1405,34 @@ export class RouterCore<
       let paramsError: unknown = undefined
 
       if (!existingMatch) {
-        const strictParseParams =
-          route.options.params?.parse ?? route.options.parseParams
-
-        if (strictParseParams) {
-          try {
-            Object.assign(
-              strictParams,
-              strictParseParams(strictParams as Record<string, string>),
-            )
-          } catch (err: any) {
-            if (isNotFound(err) || isRedirect(err)) {
-              paramsError = err
-            } else {
-              paramsError = new PathParamError(err.message, {
-                cause: err,
-              })
+        if (route.options.skipRouteOnParseError) {
+          for (const key in usedParams) {
+            if (key in parsedParams!) {
+              strictParams[key] = parsedParams![key]
             }
+          }
+        } else {
+          const strictParseParams =
+            route.options.params?.parse ?? route.options.parseParams
 
-            if (opts?.throwOnError) {
-              throw paramsError
+          if (strictParseParams) {
+            try {
+              Object.assign(
+                strictParams,
+                strictParseParams(strictParams as Record<string, string>),
+              )
+            } catch (err: any) {
+              if (isNotFound(err) || isRedirect(err)) {
+                paramsError = err
+              } else {
+                paramsError = new PathParamError(err.message, {
+                  cause: err,
+                })
+              }
+
+              if (opts?.throwOnError) {
+                throw paramsError
+              }
             }
           }
         }
@@ -1802,7 +1814,7 @@ export class RouterCore<
             this.processedTree,
           )
           if (match) {
-            Object.assign(params, match.params) // Copy params, because they're cached
+            Object.assign(params, match.rawParams) // Copy params, because they're cached
             const {
               from: _from,
               params: maskParams,
@@ -2601,18 +2613,18 @@ export class RouterCore<
     }
 
     if (location.params) {
-      if (!deepEqual(match.params, location.params, { partial: true })) {
+      if (!deepEqual(match.rawParams, location.params, { partial: true })) {
         return false
       }
     }
 
     if (opts?.includeSearch ?? true) {
       return deepEqual(baseLocation.search, next.search, { partial: true })
-        ? match.params
+        ? match.rawParams
         : false
     }
 
-    return match.params
+    return match.rawParams
   }
 
   ssr?: {
@@ -2719,15 +2731,17 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
   const trimmedPath = trimPathRight(pathname)
 
   let foundRoute: TRouteLike | undefined = undefined
+  let parsedParams: Record<string, unknown> | undefined = undefined
   const match = findRouteMatch<TRouteLike>(trimmedPath, processedTree, true)
   if (match) {
     foundRoute = match.route
-    Object.assign(routeParams, match.params) // Copy params, because they're cached
+    Object.assign(routeParams, match.rawParams) // Copy params, because they're cached
+    parsedParams = Object.assign({}, match.parsedParams)
   }
 
   const matchedRoutes = match?.branch || [routesById[rootRouteId]!]
 
-  return { matchedRoutes, routeParams, foundRoute }
+  return { matchedRoutes, routeParams, foundRoute, parsedParams }
 }
 
 function applySearchMiddleware({

packages/router-core/tests/curly-params-smoke.test.ts

@@ -136,6 +136,6 @@ describe('curly params smoke tests', () => {
     }
     const processed = processRouteTree(tree)
     const res = findRouteMatch(nav, processed.processedTree)
-    expect(res?.params).toEqual(params)
+    expect(res?.rawParams).toEqual(params)
   })
 })

packages/router-core/tests/match-by-path.test.ts

@@ -26,7 +26,7 @@ describe('default path matching', () => {
     ['/b', '/a', undefined],
   ])('static %s %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, true, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -37,7 +37,7 @@ describe('default path matching', () => {
     ['/a/1/b/2', '/a/$id/b/$id', { id: '2' }],
   ])('params %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, true, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it('params support more than alphanumeric characters', () => {
@@ -49,7 +49,7 @@ describe('default path matching', () => {
       '/a/@&é"\'(§è!çà)-_°^¨$*€£`ù=+:;.,?~<>|î©#0123456789\\😀}{',
       processedTree,
     )
-    expect(anyValueResult?.params).toEqual({
+    expect(anyValueResult?.rawParams).toEqual({
       id: '@&é"\'(§è!çà)-_°^¨$*€£`ù=+:;.,?~<>|î©#0123456789\\😀}{',
     })
     // in the key: basically everything except / and % and $
@@ -60,7 +60,7 @@ describe('default path matching', () => {
       '/a/1',
       processedTree,
     )
-    expect(anyKeyResult?.params).toEqual({
+    expect(anyKeyResult?.rawParams).toEqual({
       '@&é"\'(§è!çà)-_°^¨*€£`ù=+:;.,?~<>|î©#0123456789\\😀}{': '1',
     })
   })
@@ -77,7 +77,7 @@ describe('default path matching', () => {
     ['/a/1/b/2', '/a/{-$id}/b/{-$id}', { id: '2' }],
   ])('optional %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, true, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -87,7 +87,7 @@ describe('default path matching', () => {
     ['/a/b/c', '/a/$/foo', { _splat: 'b/c', '*': 'b/c' }],
   ])('wildcard %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, true, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 })
 
@@ -106,7 +106,7 @@ describe('case insensitive path matching', () => {
     ['/', '/b', '/A', undefined],
   ])('static %s %s => %s', (base, path, pattern, result) => {
     const res = findSingleMatch(pattern, false, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -116,7 +116,7 @@ describe('case insensitive path matching', () => {
     ['/a/1/b/2', '/A/$id/B/$id', { id: '2' }],
   ])('params %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, false, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -133,7 +133,7 @@ describe('case insensitive path matching', () => {
     ['/a/1/b/2_', '/A/{-$id}/B/{-$id}', { id: '2_' }],
   ])('optional %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, false, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -143,7 +143,7 @@ describe('case insensitive path matching', () => {
     ['/a/b/c', '/A/$/foo', { _splat: 'b/c', '*': 'b/c' }],
   ])('wildcard %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, false, false, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 })
 
@@ -167,7 +167,7 @@ describe('fuzzy path matching', () => {
     ['/', '/a', '/b', undefined],
   ])('static %s %s => %s', (base, path, pattern, result) => {
     const res = findSingleMatch(pattern, true, true, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -178,7 +178,7 @@ describe('fuzzy path matching', () => {
     ['/a/1/b/2/c', '/a/$id/b/$other', { id: '1', other: '2', '**': 'c' }],
   ])('params %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, true, true, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -193,7 +193,7 @@ describe('fuzzy path matching', () => {
     ['/a/1/b/2/c', '/a/{-$id}/b/{-$other}', { id: '1', other: '2', '**': 'c' }],
   ])('optional %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, true, true, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 
   it.each([
@@ -203,6 +203,6 @@ describe('fuzzy path matching', () => {
     ['/a/b/c/d', '/a/$/foo', { _splat: 'b/c/d', '*': 'b/c/d' }],
   ])('wildcard %s => %s', (path, pattern, result) => {
     const res = findSingleMatch(pattern, true, true, path, processedTree)
-    expect(res?.params).toEqual(result)
+    expect(res?.rawParams).toEqual(result)
   })
 })