@tanstack/react-router 1.78.3 → 1.81.0

package/src/Match.tsx

@@ -120,9 +120,10 @@ export const MatchInner = React.memo(function MatchInnerImpl({
       return {
         routeId,
         matchIndex,
-        match: pick(match, ['id', 'status', 'error', 'loadPromise']),
+        match: pick(match, ['id', 'status', 'error']),
       }
     },
+    structuralSharing: true as any,
   })
 
   const route = router.routesById[routeId]!
@@ -180,7 +181,7 @@ export const MatchInner = React.memo(function MatchInnerImpl({
     //   false,
     //   'Tried to render a redirected route match! This is a weird circumstance, please file an issue!',
     // )
-    throw match.loadPromise
+    throw router.getMatch(match.id)?.loadPromise
   }
 
   if (match.status === 'error') {
@@ -237,7 +238,7 @@ export const MatchInner = React.memo(function MatchInnerImpl({
         }, pendingMinMs)
       }
     }
-    throw match.loadPromise
+    throw router.getMatch(match.id)?.loadPromise
   }
 
   return (
@@ -259,7 +260,7 @@ export const Outlet = React.memo(function OutletImpl() {
 
   const route = router.routesById[routeId]!
 
-  const { parentGlobalNotFound } = useRouterState({
+  const parentGlobalNotFound = useRouterState({
     select: (s) => {
       const matches = s.matches
       const parentMatch = matches.find((d) => d.id === matchId)
@@ -267,9 +268,7 @@ export const Outlet = React.memo(function OutletImpl() {
         parentMatch,
         `Could not find parent match for matchId "${matchId}"`,
       )
-      return {
-        parentGlobalNotFound: parentMatch.globalNotFound,
-      }
+      return parentMatch.globalNotFound
     },
   })
 

package/src/Matches.tsx

@@ -7,8 +7,12 @@ import { Transitioner } from './Transitioner'
 import { matchContext } from './matchContext'
 import { Match } from './Match'
 import { SafeFragment } from './SafeFragment'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
 import type { AnyRoute, ReactNode, StaticDataRouteOption } from './route'
-import type { AnyRouter, RegisteredRouter } from './router'
+import type { AnyRouter, RegisteredRouter, RouterState } from './router'
 import type { ResolveRelativePath, ToOptions } from './link'
 import type {
   AllContext,
@@ -288,6 +292,7 @@ export function useMatchRoute<TRouter extends AnyRouter = RegisteredRouter>() {
 
   useRouterState({
     select: (s) => [s.location.href, s.resolvedLocation.href, s.status],
+    structuralSharing: true as any,
   })
 
   return React.useCallback(
@@ -369,56 +374,79 @@ export type MakeRouteMatchUnion<
     >
   : never
 
+export interface UseMatchesBaseOptions<
+  TRouter extends AnyRouter,
+  TSelected,
+  TStructuralSharing,
+> {
+  select?: (
+    matches: Array<MakeRouteMatchUnion<TRouter>>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+}
+
+export type UseMatchesResult<
+  TRouter extends AnyRouter,
+  TSelected,
+> = unknown extends TSelected ? Array<MakeRouteMatchUnion<TRouter>> : TSelected
+
 export function useMatches<
   TRouter extends AnyRouter = RegisteredRouter,
-  TRouteMatch = MakeRouteMatchUnion<TRouter>,
-  T = Array<TRouteMatch>,
->(opts?: { select?: (matches: Array<TRouteMatch>) => T }): T {
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseMatchesBaseOptions<TRouter, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+): UseMatchesResult<TRouter, TSelected> {
   return useRouterState({
-    select: (state) => {
+    select: (state: RouterState<TRouter['routeTree']>) => {
       const matches = state.matches
       return opts?.select
-        ? opts.select(matches as Array<TRouteMatch>)
-        : (matches as T)
+        ? opts.select(matches as Array<MakeRouteMatchUnion<TRouter>>)
+        : matches
     },
-  })
+    structuralSharing: opts?.structuralSharing,
+  } as any) as UseMatchesResult<TRouter, TSelected>
 }
 
 export function useParentMatches<
   TRouter extends AnyRouter = RegisteredRouter,
-  TRouteMatch = MakeRouteMatchUnion<TRouter>,
-  T = Array<TRouteMatch>,
->(opts?: { select?: (matches: Array<TRouteMatch>) => T }): T {
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseMatchesBaseOptions<TRouter, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+): UseMatchesResult<TRouter, TSelected> {
   const contextMatchId = React.useContext(matchContext)
 
   return useMatches({
-    select: (matches) => {
+    select: (matches: Array<MakeRouteMatchUnion<TRouter>>) => {
       matches = matches.slice(
         0,
         matches.findIndex((d) => d.id === contextMatchId),
       )
-      return opts?.select
-        ? opts.select(matches as Array<TRouteMatch>)
-        : (matches as T)
+      return opts?.select ? opts.select(matches) : matches
     },
-  })
+    structuralSharing: opts?.structuralSharing,
+  } as any)
 }
 
 export function useChildMatches<
   TRouter extends AnyRouter = RegisteredRouter,
-  TRouteMatch = MakeRouteMatchUnion<TRouter>,
-  T = Array<TRouteMatch>,
->(opts?: { select?: (matches: Array<TRouteMatch>) => T }): T {
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseMatchesBaseOptions<TRouter, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+): UseMatchesResult<TRouter, TSelected> {
   const contextMatchId = React.useContext(matchContext)
 
   return useMatches({
-    select: (matches) => {
+    select: (matches: Array<MakeRouteMatchUnion<TRouter>>) => {
       matches = matches.slice(
         matches.findIndex((d) => d.id === contextMatchId) + 1,
       )
-      return opts?.select
-        ? opts.select(matches as Array<TRouteMatch>)
-        : (matches as T)
+      return opts?.select ? opts.select(matches) : matches
     },
-  })
+    structuralSharing: opts?.structuralSharing,
+  } as any)
 }

package/src/RouterProvider.tsx

@@ -105,18 +105,21 @@ export type RouterProps<
   RouterOptions<
     TRouter['routeTree'],
     NonNullable<TRouter['options']['trailingSlash']>,
+    NonNullable<TRouter['options']['defaultStructuralSharing']>,
     TDehydrated
   >,
   'context'
 > & {
   router: Router<
     TRouter['routeTree'],
-    NonNullable<TRouter['options']['trailingSlash']>
+    NonNullable<TRouter['options']['trailingSlash']>,
+    NonNullable<TRouter['options']['defaultStructuralSharing']>
   >
   context?: Partial<
     RouterOptions<
       TRouter['routeTree'],
       NonNullable<TRouter['options']['trailingSlash']>,
+      NonNullable<TRouter['options']['defaultStructuralSharing']>,
       TDehydrated
     >['context']
   >

package/src/Transitioner.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { pick, useLayoutEffect, usePrevious } from './utils'
+import { useLayoutEffect, usePrevious } from './utils'
 import { useRouter } from './useRouter'
 import { useRouterState } from './useRouterState'
 import { trimPathRight } from './path'
@@ -7,24 +7,23 @@ import { trimPathRight } from './path'
 export function Transitioner() {
   const router = useRouter()
   const mountLoadForRouter = React.useRef({ router, mounted: false })
-  const routerState = useRouterState({
-    select: (s) =>
-      pick(s, ['isLoading', 'location', 'resolvedLocation', 'isTransitioning']),
+  const isLoading = useRouterState({
+    select: ({ isLoading }) => isLoading,
   })
 
   const [isTransitioning, startReactTransition_] = React.useTransition()
   // Track pending state changes
   const hasPendingMatches = useRouterState({
     select: (s) => s.matches.some((d) => d.status === 'pending'),
+    structuralSharing: true,
   })
 
-  const previousIsLoading = usePrevious(routerState.isLoading)
+  const previousIsLoading = usePrevious(isLoading)
 
-  const isAnyPending =
-    routerState.isLoading || isTransitioning || hasPendingMatches
+  const isAnyPending = isLoading || isTransitioning || hasPendingMatches
   const previousIsAnyPending = usePrevious(isAnyPending)
 
-  const isPagePending = routerState.isLoading || hasPendingMatches
+  const isPagePending = isLoading || hasPendingMatches
   const previousIsPagePending = usePrevious(isPagePending)
 
   if (!router.isServer) {
@@ -81,7 +80,7 @@ export function Transitioner() {
 
   useLayoutEffect(() => {
     // The router was loading and now it's not
-    if (previousIsLoading && !routerState.isLoading) {
+    if (previousIsLoading && !isLoading) {
       const toLocation = router.state.location
       const fromLocation = router.state.resolvedLocation
       const pathChanged = fromLocation.pathname !== toLocation.pathname
@@ -93,7 +92,7 @@ export function Transitioner() {
         pathChanged,
       })
     }
-  }, [previousIsLoading, router, routerState.isLoading])
+  }, [previousIsLoading, router, isLoading])
 
   useLayoutEffect(() => {
     // emit onBeforeRouteMount

package/src/fileRoute.ts

@@ -1,11 +1,15 @@
 import warning from 'tiny-warning'
 import { createRoute } from './route'
+
 import { useMatch } from './useMatch'
 import { useLoaderDeps } from './useLoaderDeps'
 import { useLoaderData } from './useLoaderData'
 import { useSearch } from './useSearch'
 import { useParams } from './useParams'
 import { useNavigate } from './useNavigate'
+import type { UseParamsRoute } from './useParams'
+import type { UseMatchRoute } from './useMatch'
+import type { UseSearchRoute } from './useSearch'
 import type { Constrain } from './utils'
 import type {
   AnyContext,
@@ -20,9 +24,11 @@ import type {
   RouteLoaderFn,
   UpdatableRouteOptions,
 } from './route'
-import type { MakeRouteMatch } from './Matches'
 import type { RegisteredRouter } from './router'
 import type { RouteById, RouteIds } from './routeInfo'
+import type { UseLoaderDepsRoute } from './useLoaderDeps'
+import type { UseLoaderDataRoute } from './useLoaderData'
+import type { UseRouteContextRoute } from './useRouteContext'
 
 export interface FileRoutesByPath {
   // '/': {
@@ -208,48 +214,42 @@ export class LazyRoute<TRoute extends AnyRoute> {
     ;(this as any).$$typeof = Symbol.for('react.memo')
   }
 
-  useMatch = <
-    TRouteMatch = MakeRouteMatch<
-      RegisteredRouter['routeTree'],
-      TRoute['types']['id']
-    >,
-    TSelected = TRouteMatch,
-  >(opts?: {
-    select?: (match: TRouteMatch) => TSelected
-  }): TSelected => {
-    return useMatch({ select: opts?.select, from: this.options.id })
+  useMatch: UseMatchRoute<TRoute['id']> = (opts) => {
+    return useMatch({
+      select: opts?.select,
+      from: this.options.id,
+      structuralSharing: opts?.structuralSharing,
+    } as any) as any
   }
 
-  useRouteContext = <TSelected = TRoute['types']['allContext']>(opts?: {
-    select?: (s: TRoute['types']['allContext']) => TSelected
-  }): TSelected => {
+  useRouteContext: UseRouteContextRoute<TRoute['id']> = (opts) => {
     return useMatch({
       from: this.options.id,
       select: (d: any) => (opts?.select ? opts.select(d.context) : d.context),
-    })
+    }) as any
   }
 
-  useSearch = <TSelected = TRoute['types']['fullSearchSchema']>(opts?: {
-    select?: (s: TRoute['types']['fullSearchSchema']) => TSelected
-  }): TSelected => {
-    return useSearch({ ...opts, from: this.options.id })
+  useSearch: UseSearchRoute<TRoute['id']> = (opts) => {
+    return useSearch({
+      select: opts?.select,
+      structuralSharing: opts?.structuralSharing,
+      from: this.options.id,
+    } as any)
   }
 
-  useParams = <TSelected = TRoute['types']['allParams']>(opts?: {
-    select?: (s: TRoute['types']['allParams']) => TSelected
-  }): TSelected => {
-    return useParams({ ...opts, from: this.options.id })
+  useParams: UseParamsRoute<TRoute['id']> = (opts) => {
+    return useParams({
+      select: opts?.select,
+      structuralSharing: opts?.structuralSharing,
+      from: this.options.id,
+    } as any)
   }
 
-  useLoaderDeps = <TSelected = TRoute['types']['loaderDeps']>(opts?: {
-    select?: (s: TRoute['types']['loaderDeps']) => TSelected
-  }): TSelected => {
+  useLoaderDeps: UseLoaderDepsRoute<TRoute['id']> = (opts) => {
     return useLoaderDeps({ ...opts, from: this.options.id } as any)
   }
 
-  useLoaderData = <TSelected = TRoute['types']['loaderData']>(opts?: {
-    select?: (s: TRoute['types']['loaderData']) => TSelected
-  }): TSelected => {
+  useLoaderData: UseLoaderDataRoute<TRoute['id']> = (opts) => {
     return useLoaderData({ ...opts, from: this.options.id } as any)
   }
 

package/src/link.tsx

@@ -233,10 +233,10 @@ export interface MaskOptions<
 }
 
 export type ToMaskOptions<
-  TRouteTree extends AnyRouter = RegisteredRouter,
+  TRouter extends AnyRouter = RegisteredRouter,
   TMaskFrom extends string = string,
   TMaskTo extends string = '.',
-> = ToSubOptions<TRouteTree, TMaskFrom, TMaskTo> & {
+> = ToSubOptions<TRouter, TMaskFrom, TMaskTo> & {
   unmaskOnReload?: boolean
 }
 
@@ -645,7 +645,10 @@ export function useLinkProps<
   }, [to])
 
   // subscribe to search params to re-build location if it changes
-  const currentSearch = useRouterState({ select: (s) => s.location.search })
+  const currentSearch = useRouterState({
+    select: (s) => s.location.search,
+    structuralSharing: true as any,
+  })
 
   const next = React.useMemo(
     () => router.buildLocation(options as any),

package/src/path.ts

@@ -204,6 +204,8 @@ interface InterpolatePathOptions {
   params: Record<string, unknown>
   leaveWildcards?: boolean
   leaveParams?: boolean
+  // Map of encoded chars to decoded chars (e.g. '%40' -> '@') that should remain decoded in path params
+  decodeCharMap?: Map<string, string>
 }
 
 export function interpolatePath({
@@ -211,6 +213,7 @@ export function interpolatePath({
   params,
   leaveWildcards,
   leaveParams,
+  decodeCharMap,
 }: InterpolatePathOptions) {
   const interpolatedPathSegments = parsePathname(path)
   const encodedParams: any = {}
@@ -222,7 +225,9 @@ export function interpolatePath({
       // the splat/catch-all routes shouldn't have the '/' encoded out
       encodedParams[key] = isValueString ? encodeURI(value) : value
     } else {
-      encodedParams[key] = isValueString ? encodeURIComponent(value) : value
+      encodedParams[key] = isValueString
+        ? encodePathParam(value, decodeCharMap)
+        : value
     }
   }
 
@@ -247,6 +252,16 @@ export function interpolatePath({
   )
 }
 
+function encodePathParam(value: string, decodeCharMap?: Map<string, string>) {
+  let encoded = encodeURIComponent(value)
+  if (decodeCharMap) {
+    for (const [encodedChar, char] of decodeCharMap) {
+      encoded = encoded.replaceAll(encodedChar, char)
+    }
+  }
+  return encoded
+}
+
 export function matchPathname(
   basepath: string,
   currentPathname: string,

package/src/route.ts

@@ -1,18 +1,22 @@
 import invariant from 'tiny-invariant'
-import { useMatch } from './useMatch'
-import { useLoaderDeps } from './useLoaderDeps'
-import { useLoaderData } from './useLoaderData'
 import { joinPaths, trimPathLeft } from './path'
+import { useLoaderData } from './useLoaderData'
+import { useLoaderDeps } from './useLoaderDeps'
 import { useParams } from './useParams'
 import { useSearch } from './useSearch'
 import { notFound } from './not-found'
 import { useNavigate } from './useNavigate'
 import { rootRouteId } from './root'
+import { useMatch } from './useMatch'
+import type { UseLoaderDataRoute } from './useLoaderData'
+import type { UseMatchRoute } from './useMatch'
+import type { UseLoaderDepsRoute } from './useLoaderDeps'
+import type { UseParamsRoute } from './useParams'
+import type { UseSearchRoute } from './useSearch'
 import type * as React from 'react'
 import type { RootRouteId } from './root'
 import type { UseNavigateResult } from './useNavigate'
 import type {
-  MakeRouteMatch,
   MakeRouteMatchFromRoute,
   MakeRouteMatchUnion,
   RouteMatch,
@@ -25,6 +29,7 @@ import type { Assign, Constrain, Expand, NoInfer } from './utils'
 import type { BuildLocationFn, NavigateFn } from './RouterProvider'
 import type { NotFoundError } from './not-found'
 import type { LazyRoute } from './fileRoute'
+import type { UseRouteContextRoute } from './useRouteContext'
 
 export type AnyPathParams = {}
 
@@ -845,60 +850,42 @@ export class RouteApi<TId, TRouter extends AnyRouter = RegisteredRouter> {
     this.id = id as any
   }
 
-  useMatch = <
-    TRouteTree extends AnyRoute = TRouter['routeTree'],
-    TRouteMatch = MakeRouteMatch<TRouteTree, TId>,
-    TSelected = TRouteMatch,
-  >(opts?: {
-    select?: (match: TRouteMatch) => TSelected
-  }): TSelected => {
-    return useMatch({ select: opts?.select, from: this.id })
+  useMatch: UseMatchRoute<TId> = (opts) => {
+    return useMatch({
+      select: opts?.select,
+      from: this.id,
+      structuralSharing: opts?.structuralSharing,
+    } as any) as any
   }
 
-  useRouteContext = <
-    TSelected = Expand<RouteTypesById<TRouter, TId>['allContext']>,
-  >(opts?: {
-    select?: (
-      s: Expand<RouteTypesById<TRouter, TId>['allContext']>,
-    ) => TSelected
-  }): TSelected => {
+  useRouteContext: UseRouteContextRoute<TId> = (opts) => {
     return useMatch({
-      from: this.id,
-      select: (d: any) => (opts?.select ? opts.select(d.context) : d.context),
-    })
+      from: this.id as any,
+      select: (d) => (opts?.select ? opts.select(d.context) : d.context),
+    }) as any
   }
 
-  useSearch = <
-    TSelected = Expand<RouteTypesById<TRouter, TId>['fullSearchSchema']>,
-  >(opts?: {
-    select?: (
-      s: Expand<RouteTypesById<TRouter, TId>['fullSearchSchema']>,
-    ) => TSelected
-  }): TSelected => {
-    return useSearch({ ...opts, from: this.id })
+  useSearch: UseSearchRoute<TId> = (opts) => {
+    return useSearch({
+      select: opts?.select,
+      structuralSharing: opts?.structuralSharing,
+      from: this.id,
+    } as any)
   }
 
-  useParams = <
-    TSelected = Expand<RouteTypesById<TRouter, TId>['allParams']>,
-  >(opts?: {
-    select?: (s: Expand<RouteTypesById<TRouter, TId>['allParams']>) => TSelected
-  }): TSelected => {
-    return useParams({ ...opts, from: this.id })
+  useParams: UseParamsRoute<TId> = (opts) => {
+    return useParams({
+      select: opts?.select,
+      structuralSharing: opts?.structuralSharing,
+      from: this.id,
+    } as any)
   }
 
-  useLoaderDeps = <
-    TSelected = RouteTypesById<TRouter, TId>['loaderDeps'],
-  >(opts?: {
-    select?: (s: RouteTypesById<TRouter, TId>['loaderDeps']) => TSelected
-  }): TSelected => {
+  useLoaderDeps: UseLoaderDepsRoute<TId> = (opts) => {
     return useLoaderDeps({ ...opts, from: this.id, strict: false } as any)
   }
 
-  useLoaderData = <
-    TSelected = RouteTypesById<TRouter, TId>['loaderData'],
-  >(opts?: {
-    select?: (s: RouteTypesById<TRouter, TId>['loaderData']) => TSelected
-  }): TSelected => {
+  useLoaderData: UseLoaderDataRoute<TId> = (opts) => {
     return useLoaderData({ ...opts, from: this.id, strict: false } as any)
   }
 
@@ -1258,74 +1245,43 @@ export class Route<
     return this
   }
 
-  useMatch = <
-    TRouter extends AnyRouter = RegisteredRouter,
-    TRouteTree extends AnyRoute = TRouter['routeTree'],
-    TRouteMatch = MakeRouteMatch<TRouteTree, TId>,
-    TSelected = TRouteMatch,
-  >(opts?: {
-    select?: (match: TRouteMatch) => TSelected
-  }): TSelected => {
-    return useMatch({ ...opts, from: this.id })
+  useMatch: UseMatchRoute<TId> = (opts) => {
+    return useMatch({
+      select: opts?.select,
+      from: this.id,
+      structuralSharing: opts?.structuralSharing,
+    } as any) as any
   }
 
-  useRouteContext = <
-    TSelected = Expand<
-      ResolveAllContext<
-        TParentRoute,
-        TRouterContext,
-        TRouteContextFn,
-        TBeforeLoadFn
-      >
-    >,
-  >(opts?: {
-    select?: (
-      search: Expand<
-        ResolveAllContext<
-          TParentRoute,
-          TRouterContext,
-          TRouteContextFn,
-          TBeforeLoadFn
-        >
-      >,
-    ) => TSelected
-  }): TSelected => {
+  useRouteContext: UseRouteContextRoute<TId> = (opts?) => {
     return useMatch({
       ...opts,
       from: this.id,
-      select: (d: any) => (opts?.select ? opts.select(d.context) : d.context),
-    })
+      select: (d) => (opts?.select ? opts.select(d.context) : d.context),
+    }) as any
   }
 
-  useSearch = <
-    TSelected = Expand<ResolveFullSearchSchema<TParentRoute, TSearchValidator>>,
-  >(opts?: {
-    select?: (
-      search: Expand<ResolveFullSearchSchema<TParentRoute, TSearchValidator>>,
-    ) => TSelected
-  }): TSelected => {
-    return useSearch({ ...opts, from: this.id })
+  useSearch: UseSearchRoute<TId> = (opts) => {
+    return useSearch({
+      select: opts?.select,
+      structuralSharing: opts?.structuralSharing,
+      from: this.id,
+    } as any)
   }
 
-  useParams = <
-    TSelected = Expand<ResolveAllParamsFromParent<TParentRoute, TParams>>,
-  >(opts?: {
-    select?: (
-      search: Expand<ResolveAllParamsFromParent<TParentRoute, TParams>>,
-    ) => TSelected
-  }): TSelected => {
-    return useParams({ ...opts, from: this.id })
+  useParams: UseParamsRoute<TId> = (opts) => {
+    return useParams({
+      select: opts?.select,
+      structuralSharing: opts?.structuralSharing,
+      from: this.id,
+    } as any)
   }
 
-  useLoaderDeps = <TSelected = TLoaderDeps>(opts?: {
-    select?: (s: TLoaderDeps) => TSelected
-  }): TSelected => {
+  useLoaderDeps: UseLoaderDepsRoute<TId> = (opts) => {
     return useLoaderDeps({ ...opts, from: this.id } as any)
   }
 
-  useLoaderData = <TSelected = ResolveLoaderData<TLoaderFn>>(opts?: {
-    select?: (search: ResolveLoaderData<TLoaderFn>) => TSelected
-  }): TSelected => {
+  useLoaderData: UseLoaderDataRoute<TId> = (opts) => {
     return useLoaderData({ ...opts, from: this.id } as any)
   }
 
@@ -1643,7 +1599,7 @@ export function createRouteMask<
 >(
   opts: {
     routeTree: TRouteTree
-  } & ToMaskOptions<Router<TRouteTree, 'never'>, TFrom, TTo>,
+  } & ToMaskOptions<Router<TRouteTree, 'never', boolean>, TFrom, TTo>,
 ): RouteMask<TRouteTree> {
   return opts as any
 }