fix: parse params union inference (#7306)

schiller-manuel · web-flow · commit 4a1e63f1d123 · 2026-05-01T02:04:12.000+02:00
diff --git a/.changeset/fix-parse-params-union.md b/.changeset/fix-parse-params-union.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/router-core': patch
+---
+
+Fix params.parse inference for discriminated union path params while preserving path key validation.
diff --git a/packages/react-router/tests/fileRoute.test-d.tsx b/packages/react-router/tests/fileRoute.test-d.tsx
@@ -17,6 +17,31 @@ const postRoute = createFileRoute('/_postLayout/posts/$postId_')()
 
 const protectedRoute = createFileRoute('/(auth)/protected')()
 
+const attachmentRoute = createFileRoute(
+  '/projects/$observationDocId/attachments/$driveId/$type/$variant/$name',
+)({
+  params: {
+    parse: ({ driveId, type, variant, name, ...rest }) => {
+      const blobId =
+        type === 'audio'
+          ? {
+              type: 'audio' as const,
+              variant: 'original' as const,
+              driveId,
+              name,
+            }
+          : {
+              type: 'photo' as const,
+              variant: variant as 'original' | 'preview' | 'thumbnail',
+              driveId,
+              name,
+            }
+
+      return { ...rest, ...blobId }
+    },
+  },
+})
+
 declare module '@tanstack/router-core' {
   interface FileRoutesByPath {
     '/': {
@@ -68,6 +93,13 @@ declare module '@tanstack/router-core' {
       fullPath: '/posts/$postId'
       path: '/$postId_'
     }
+    '/projects/$observationDocId/attachments/$driveId/$type/$variant/$name': {
+      preLoaderRoute: typeof attachmentRoute
+      parentRoute: typeof rootRoute
+      id: '/projects/$observationDocId/attachments/$driveId/$type/$variant/$name'
+      fullPath: '/projects/$observationDocId/attachments/$driveId/$type/$variant/$name'
+      path: '/projects/$observationDocId/attachments/$driveId/$type/$variant/$name'
+    }
   }
 }
 
@@ -100,3 +132,31 @@ test('when creating a folder group', () => {
   expectTypeOf<'(auth)/protected'>(protectedRoute.path)
   expectTypeOf<'/protected'>(protectedRoute.id)
 })
+
+test('when file route params.parse returns a discriminated union', () => {
+  expectTypeOf(attachmentRoute.types.params).toEqualTypeOf<
+    | {
+        observationDocId: string
+        driveId: string
+        type: 'audio'
+        variant: 'original'
+        name: string
+      }
+    | {
+        observationDocId: string
+        driveId: string
+        type: 'photo'
+        variant: 'original' | 'preview' | 'thumbnail'
+        name: string
+      }
+  >()
+})
+
+test('when file route params.parse drops a path param', () => {
+  createFileRoute('/invoices/$invoiceId')({
+    params: {
+      // @ts-expect-error parsed params must keep path param keys
+      parse: () => ({}),
+    },
+  })
+})
diff --git a/packages/router-core/src/route.ts b/packages/router-core/src/route.ts
@@ -173,26 +173,29 @@ 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>)
-  | false
+) => 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,
 ) => ResolveParams<TPath>
 
 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

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/router-core': patch
 +---
++
 +Fix params.parse inference for discriminated union path params while preserving path key validation.