fix(react-router): useMatch returns union of matches when strict = false

packages/react-router/src/useMatch.tsx

@@ -7,7 +7,7 @@ import type {
   ValidateSelected,
 } from './structuralSharing'
 import type { AnyRouter, RegisteredRouter } from './router'
-import type { MakeRouteMatch } from './Matches'
+import type { MakeRouteMatch, MakeRouteMatchUnion } from './Matches'
 import type { StrictOrFrom, ThrowOrOptional } from './utils'
 
 export interface UseMatchBaseOptions<
@@ -64,9 +64,16 @@ export type UseMatchResult<
   TStrict extends boolean,
   TSelected,
 > = unknown extends TSelected
-  ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>
+  ? TStrict extends true
+    ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>
+    : MakeRouteMatchUnion<TRouter>
   : TSelected
 
+type ThrowConstraint<
+  TStrict extends boolean,
+  TThrow extends boolean,
+> = TStrict extends false ? (TThrow extends true ? never : TThrow) : TThrow
+
 export function useMatch<
   TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
@@ -80,7 +87,7 @@ export function useMatch<
     TFrom,
     TStrict,
     TSelected,
-    TThrow,
+    ThrowConstraint<TStrict, TThrow>,
     TStructuralSharing
   >,
 ): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow> {

packages/react-router/tests/useMatch.test-d.tsx

@@ -1,6 +1,6 @@
 import { describe, expectTypeOf, test } from 'vitest'
 import { createRootRoute, createRoute, createRouter, useMatch } from '../src'
-import type { MakeRouteMatch } from '../src/Matches'
+import type { MakeRouteMatch, MakeRouteMatchUnion } from '../src/Matches'
 
 const rootRoute = createRootRoute()
 
@@ -24,30 +24,56 @@ type DefaultRouter = typeof defaultRouter
 type TRouteMatch = MakeRouteMatch<DefaultRouter['routeTree']>
 
 describe('useMatch', () => {
-  const from = '/invoices'
-  test('return type is `RouteMatch` when shouldThrow = true', () => {
-    const shouldThrow = true
-    const match = useMatch<
-      DefaultRouter,
-      typeof from,
-      true, // TStrict
-      typeof shouldThrow,
-      TRouteMatch
-    >({ from, shouldThrow })
+  describe('shouldThrow', () => {
+    const from = '/invoices'
+    test('return type is `RouteMatch` when shouldThrow = true', () => {
+      const shouldThrow = true
+      const match = useMatch<
+        DefaultRouter,
+        typeof from,
+        true, // TStrict
+        typeof shouldThrow,
+        TRouteMatch
+      >({ from, shouldThrow })
+
+      expectTypeOf(match).toEqualTypeOf<TRouteMatch>()
+    })
 
-    expectTypeOf(match).toEqualTypeOf<TRouteMatch>()
+    test('return type is `RouteMatch | undefined` when shouldThrow = false', () => {
+      const shouldThrow = false
+      const match = useMatch<
+        DefaultRouter,
+        typeof from,
+        true, // TStrict
+        typeof shouldThrow,
+        TRouteMatch
+      >({ from, shouldThrow })
+
+      expectTypeOf(match).toEqualTypeOf<TRouteMatch | undefined>()
+    })
   })
 
-  test('return type is `RouteMatch | undefined` when shouldThrow = false', () => {
-    const shouldThrow = false
-    const match = useMatch<
-      DefaultRouter,
-      typeof from,
-      true, // TStrict
-      typeof shouldThrow,
-      TRouteMatch
-    >({ from, shouldThrow })
+  test('return type is union of matches when strict = false', () => {
+    const strict = false as const
+    const match = useMatch<DefaultRouter, typeof undefined, typeof strict>({
+      strict,
+    })
 
-    expectTypeOf(match).toEqualTypeOf<TRouteMatch | undefined>()
+    expectTypeOf(match).toEqualTypeOf<MakeRouteMatchUnion<DefaultRouter>>()
+  })
+
+  test('shouldThrow must be false when strict is false', () => {
+    const strict = false as const
+    const shouldThrow = true as const
+    useMatch<
+      DefaultRouter,
+      typeof undefined,
+      typeof strict,
+      typeof shouldThrow
+    >({
+      strict,
+      // @ts-expect-error shouldThrow must be false when strict is false
+      shouldThrow,
+    })
   })
 })