Open History to see the last commit
1'use client'
2β
3import * as React from 'react'
4import { useSelector } from '@tanstack/react-store'
5import { invariant, replaceEqualDeep } from '@tanstack/router-core'
6import { isServer } from '@tanstack/router-core/isServer'
7import { dummyMatchContext, matchContext } from './matchContext'
8import { useRouter } from './useRouter'
9import type {
10 StructuralSharingOption,
11 ValidateSelected,
12} from './structuralSharing'
13import type {
14 AnyRouter,
15 MakeRouteMatch,
16 MakeRouteMatchUnion,
17 RegisteredRouter,
18 StrictOrFrom,
19 ThrowConstraint,
20 ThrowOrOptional,
21} from '@tanstack/router-core'
22β
23const dummyMatch = {}
24β
25export function useStructuralSharing<
26 TRouter extends AnyRouter,
27 TSelected,
28 TStructuralSharing extends boolean,
29 TStoreSlice,
30 TSelectSlice = TStoreSlice,
31>(
32 opts:
33 | {
34 select?: (
35 slice: TSelectSlice,
36 ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
37 structuralSharing?: boolean
38 }
39 | undefined,
40 router: TRouter,
41): (
42 slice: TStoreSlice,
43) => ValidateSelected<TRouter, TSelected, TStructuralSharing> {
44 const previousResult =
45 // @ts-expect-error -- init to undefined, but without writing `undefined` to shave bytes
46 React.useRef<ValidateSelected<TRouter, TSelected, TStructuralSharing>>()
47β
48 return (slice) => {
49 const selected = opts?.select
50 ? opts.select(slice as unknown as TSelectSlice)
51 : (slice as ValidateSelected<TRouter, TSelected, TStructuralSharing>)
52β
53 if (opts?.structuralSharing ?? router.options.defaultStructuralSharing) {
54 return (previousResult.current = replaceEqualDeep(
55 previousResult.current,
56 selected,
57 ))
58 }
59β
60 return selected
61 }
62}
63β
64export interface UseMatchBaseOptions<
65 TRouter extends AnyRouter,
66 TFrom,
67 TStrict extends boolean,
68 TThrow extends boolean,
69 TSelected,
70 TStructuralSharing extends boolean,
71> {
72 select?: (
73 match: MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>,
74 ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
75 shouldThrow?: TThrow
76}
77β
78export type UseMatchRoute<out TFrom> = <
79 TRouter extends AnyRouter = RegisteredRouter,
80 TSelected = unknown,
81 TStructuralSharing extends boolean = boolean,
82 TThrow extends boolean = true,
83>(
84 opts?: UseMatchBaseOptions<
85 TRouter,
86 TFrom,
87 true,
88 TThrow,
89 TSelected,
90 TStructuralSharing
91 > &
92 StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
93) => ThrowOrOptional<UseMatchResult<TRouter, TFrom, true, TSelected>, TThrow>
94β
95export type UseMatchOptions<
96 TRouter extends AnyRouter,
97 TFrom extends string | undefined,
98 TStrict extends boolean,
99 TThrow extends boolean,
100 TSelected,
101 TStructuralSharing extends boolean,
102> = StrictOrFrom<TRouter, TFrom, TStrict> &
103 UseMatchBaseOptions<
104 TRouter,
105 TFrom,
106 TStrict,
107 TThrow,
108 TSelected,
109 TStructuralSharing
110 > &
111 StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
112β
113export type UseMatchResult<
114 TRouter extends AnyRouter,
115 TFrom,
116 TStrict extends boolean,
117 TSelected,
118> = unknown extends TSelected
119 ? TStrict extends true
120 ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>
121 : MakeRouteMatchUnion<TRouter>
122 : TSelected
123β
124/**
125 * Read and select the nearest or targeted route match.
126 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/useMatchHook
127 */
128export function useMatch<
129 TRouter extends AnyRouter = RegisteredRouter,
130 const TFrom extends string | undefined = undefined,
131 TStrict extends boolean = true,
132 TThrow extends boolean = true,
133 TSelected = unknown,
134 TStructuralSharing extends boolean = boolean,
135>(
136 opts: UseMatchOptions<
137 TRouter,
138 TFrom,
139 TStrict,
140 ThrowConstraint<TStrict, TThrow>,
141 TSelected,
142 TStructuralSharing
143 >,
144): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow> {
145 const router = useRouter<TRouter>()
146 const nearestRouteId = React.useContext(
147 opts.from ? dummyMatchContext : matchContext,
148 )
149β
150 const routeId = opts.from ?? nearestRouteId
151 const matchStore = router.stores.getMatchStore(routeId!)
152β
153 if (isServer ?? router.isServer) {
154 const match = matchStore.get()
155 if (!match) {
156 if (opts.shouldThrow ?? true) {
157 if (process.env.NODE_ENV !== 'production') {
158 throw new Error(
159 `Invariant failed: Could not find ${opts.from ? `an active match from "${opts.from}"` : 'a nearest match!'}`,
160 )
161 }
162β
163 invariant()
164 }
165β
166 return undefined as any
167 }
168β
169 return (opts.select ? opts.select(match as any) : match) as any
170 }
171β
172 const selector =
173 // eslint-disable-next-line react-hooks/rules-of-hooks -- condition is static
174 useStructuralSharing(opts, router)
175β
176 // eslint-disable-next-line react-hooks/rules-of-hooks -- condition is static
177 const matchSelection = useSelector(matchStore, (match) =>
178 match ? selector(match as any) : dummyMatch,
179 )
180β
181 if (matchSelection !== dummyMatch) {
182 return matchSelection as any
183 }
184β
185 if (opts.shouldThrow ?? true) {
186 if (process.env.NODE_ENV !== 'production') {
187 throw new Error(
188 `Invariant failed: Could not find ${opts.from ? `an active match from "${opts.from}"` : 'a nearest match!'}`,
189 )
190 }
191β
192 invariant()
193 }
194β
195 return undefined as any
196}