@tanstack/react-router 1.78.3 → 1.81.0

package/src/router.ts

@@ -103,7 +103,7 @@ declare global {
       cleanScripts: () => void
       dehydrated?: any
     }
-    __TSR_ROUTER_CONTEXT__?: React.Context<Router<any, any>>
+    __TSR_ROUTER_CONTEXT__?: React.Context<Router<any, any, any>>
   }
 }
 
@@ -111,7 +111,7 @@ export interface Register {
   // router: Router
 }
 
-export type AnyRouter = Router<any, any, any, any>
+export type AnyRouter = Router<any, any, any, any, any>
 
 export type AnyRouterWithContext<TContext> = Router<
   AnyRouteWithContext<TContext>,
@@ -173,6 +173,7 @@ export type TrailingSlashOption = 'always' | 'never' | 'preserve'
 export interface RouterOptions<
   TRouteTree extends AnyRoute,
   TTrailingSlashOption extends TrailingSlashOption,
+  TDefaultStructuralSharingOption extends boolean = false,
   TDehydrated extends Record<string, any> = Record<string, any>,
   TSerializedError extends Record<string, any> = Record<string, any>,
 > {
@@ -464,6 +465,23 @@ export interface RouterOptions<
      */
     strict?: boolean
   }
+
+  /**
+   * Configures whether structural sharing is enabled by default for fine-grained selectors.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultstructuralsharing-property)
+   */
+  defaultStructuralSharing?: TDefaultStructuralSharingOption
+
+  /**
+   * Configures which URI characters are allowed in path params that would ordinarily be escaped by encodeURIComponent.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#pathparamsallowedcharacters-property)
+   * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/path-params#allowed-characters)
+   */
+  pathParamsAllowedCharacters?: Array<
+    ';' | ':' | '@' | '&' | '=' | '+' | '$' | ','
+  >
 }
 
 export interface RouterErrorSerializer<TSerializedError> {
@@ -530,12 +548,14 @@ export interface DehydratedRouter {
 export type RouterConstructorOptions<
   TRouteTree extends AnyRoute,
   TTrailingSlashOption extends TrailingSlashOption,
+  TDefaultStructuralSharingOption extends boolean,
   TDehydrated extends Record<string, any>,
   TSerializedError extends Record<string, any>,
 > = Omit<
   RouterOptions<
     TRouteTree,
     TTrailingSlashOption,
+    TDefaultStructuralSharingOption,
     TDehydrated,
     TSerializedError
   >,
@@ -627,6 +647,7 @@ export type RouterListener<TRouterEvent extends RouterEvent> = {
 export function createRouter<
   TRouteTree extends AnyRoute,
   TTrailingSlashOption extends TrailingSlashOption,
+  TDefaultStructuralSharingOption extends boolean,
   TDehydrated extends Record<string, any> = Record<string, any>,
   TSerializedError extends Record<string, any> = Record<string, any>,
 >(
@@ -635,6 +656,7 @@ export function createRouter<
     : RouterConstructorOptions<
         TRouteTree,
         TTrailingSlashOption,
+        TDefaultStructuralSharingOption,
         TDehydrated,
         TSerializedError
       >,
@@ -642,6 +664,7 @@ export function createRouter<
   return new Router<
     TRouteTree,
     TTrailingSlashOption,
+    TDefaultStructuralSharingOption,
     TDehydrated,
     TSerializedError
   >(options)
@@ -657,6 +680,7 @@ type MatchRoutesOpts = {
 export class Router<
   in out TRouteTree extends AnyRoute,
   in out TTrailingSlashOption extends TrailingSlashOption,
+  in out TDefaultStructuralSharingOption extends boolean,
   in out TDehydrated extends Record<string, any> = Record<string, any>,
   in out TSerializedError extends Record<string, any> = Record<string, any>,
 > {
@@ -694,6 +718,7 @@ export class Router<
       RouterOptions<
         TRouteTree,
         TTrailingSlashOption,
+        TDefaultStructuralSharingOption,
         TDehydrated,
         TSerializedError
       >,
@@ -711,6 +736,7 @@ export class Router<
   routesByPath!: RoutesByPath<TRouteTree>
   flatRoutes!: Array<AnyRoute>
   isServer!: boolean
+  pathParamsDecodeCharMap?: Map<string, string>
 
   /**
    * @deprecated Use the `createRouter` function instead
@@ -719,6 +745,7 @@ export class Router<
     options: RouterConstructorOptions<
       TRouteTree,
       TTrailingSlashOption,
+      TDefaultStructuralSharingOption,
       TDehydrated,
       TSerializedError
     >,
@@ -750,6 +777,7 @@ export class Router<
     newOptions: RouterConstructorOptions<
       TRouteTree,
       TTrailingSlashOption,
+      TDefaultStructuralSharingOption,
       TDehydrated,
       TSerializedError
     >,
@@ -768,6 +796,15 @@ export class Router<
 
     this.isServer = this.options.isServer ?? typeof document === 'undefined'
 
+    this.pathParamsDecodeCharMap = this.options.pathParamsAllowedCharacters
+      ? new Map(
+          this.options.pathParamsAllowedCharacters.map((char) => [
+            encodeURIComponent(char),
+            char,
+          ]),
+        )
+      : undefined
+
     if (
       !this.basepath ||
       (newOptions.basepath && newOptions.basepath !== previousOptions.basepath)
@@ -1187,6 +1224,7 @@ export class Router<
       const interpolatedPath = interpolatePath({
         path: route.fullPath,
         params: routeParams,
+        decodeCharMap: this.pathParamsDecodeCharMap,
       })
 
       const matchId =
@@ -1194,6 +1232,7 @@ export class Router<
           path: route.id,
           params: routeParams,
           leaveWildcards: true,
+          decodeCharMap: this.pathParamsDecodeCharMap,
         }) + loaderDepsHash
 
       // Waste not, want not. If we already have a match for this route,
@@ -1431,6 +1470,7 @@ export class Router<
               const interpolatedPath = interpolatePath({
                 path: route.fullPath,
                 params: matchedRoutesResult?.routeParams ?? {},
+                decodeCharMap: this.pathParamsDecodeCharMap,
               })
               const pathname = joinPaths([this.basepath, interpolatedPath])
               return pathname === fromPath
@@ -1467,6 +1507,7 @@ export class Router<
         params: nextParams ?? {},
         leaveWildcards: false,
         leaveParams: opts.leaveParams,
+        decodeCharMap: this.pathParamsDecodeCharMap,
       })
 
       let search = fromSearch
@@ -1637,6 +1678,7 @@ export class Router<
           }
           maskedNext = build(maskedDest)
         }
+        // console.log('buildWithMatches', {foundMask, dest, maskedDest, maskedNext})
       }
 
       const nextMatches = this.getMatchedRoutes(next, dest)
@@ -2186,6 +2228,8 @@ export class Router<
                   let pendingTimeout: ReturnType<typeof setTimeout>
 
                   if (shouldPending) {
+                    console.log('### 2186 setting timeout', pendingMs)
+
                     // If we might show a pending component, we need to wait for the
                     // pending promise to resolve before we start showing that state
                     pendingTimeout = setTimeout(() => {
@@ -2649,7 +2693,13 @@ export class Router<
     TMaskTo extends string = '',
   >(
     opts: NavigateOptions<
-      Router<TRouteTree, TTrailingSlashOption, TDehydrated, TSerializedError>,
+      Router<
+        TRouteTree,
+        TTrailingSlashOption,
+        TDefaultStructuralSharingOption,
+        TDehydrated,
+        TSerializedError
+      >,
       TFrom,
       TTo,
       TMaskFrom,
@@ -2723,7 +2773,13 @@ export class Router<
     TResolved = ResolveRelativePath<TFrom, NoInfer<TTo>>,
   >(
     location: ToOptions<
-      Router<TRouteTree, TTrailingSlashOption, TDehydrated, TSerializedError>,
+      Router<
+        TRouteTree,
+        TTrailingSlashOption,
+        TDefaultStructuralSharingOption,
+        TDehydrated,
+        TSerializedError
+      >,
       TFrom,
       TTo
     >,

package/src/routerContext.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import type { Router } from './router'
 
-const routerContext = React.createContext<Router<any, any>>(null!)
+const routerContext = React.createContext<Router<any, any, any>>(null!)
 
 export function getRouterContext() {
   if (typeof document === 'undefined') {

package/src/structuralSharing.ts

@@ -0,0 +1,49 @@
+import type { Constrain, ValidateJSON } from './utils'
+import type { AnyRouter } from './router'
+
+export type DefaultStructuralSharingEnabled<TRouter extends AnyRouter> =
+  boolean extends TRouter['options']['defaultStructuralSharing']
+    ? // for now, default to false.
+      // TODO in V2: default to true
+      false
+    : NonNullable<TRouter['options']['defaultStructuralSharing']>
+
+export interface OptionalStructuralSharing<TStructuralSharing, TConstraint> {
+  readonly structuralSharing?:
+    | Constrain<TStructuralSharing, TConstraint>
+    | undefined
+}
+
+export interface RequiredStructuralSharing<TStructuralSharing, TConstraint> {
+  readonly structuralSharing: Constrain<TStructuralSharing, TConstraint>
+}
+
+export type StructuralSharingOption<
+  TRouter extends AnyRouter,
+  TSelected,
+  TStructuralSharing,
+> = unknown extends TSelected
+  ? OptionalStructuralSharing<TStructuralSharing, boolean>
+  : unknown extends TRouter['routeTree']
+    ? OptionalStructuralSharing<TStructuralSharing, boolean>
+    : TSelected extends ValidateJSON<TSelected>
+      ? OptionalStructuralSharing<TStructuralSharing, boolean>
+      : DefaultStructuralSharingEnabled<TRouter> extends true
+        ? RequiredStructuralSharing<TStructuralSharing, false>
+        : OptionalStructuralSharing<TStructuralSharing, false>
+
+export type StructuralSharingEnabled<
+  TRouter extends AnyRouter,
+  TStructuralSharing,
+> = boolean extends TStructuralSharing
+  ? DefaultStructuralSharingEnabled<TRouter>
+  : TStructuralSharing
+
+export type ValidateSelected<
+  TRouter extends AnyRouter,
+  TSelected,
+  TStructuralSharing,
+> =
+  StructuralSharingEnabled<TRouter, TStructuralSharing> extends true
+    ? ValidateJSON<TSelected>
+    : TSelected

package/src/useLoaderData.tsx

@@ -1,45 +1,93 @@
 import { useMatch } from './useMatch'
-import type { RegisteredRouter } from './router'
-import type { AnyRoute } from './route'
-import type { MakeRouteMatch } from './Matches'
-import type { RouteIds } from './routeInfo'
-import type { Constrain, StrictOrFrom } from './utils'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { AllLoaderData, RouteById } from './routeInfo'
+import type { Expand, StrictOrFrom } from './utils'
 
-export type UseLoaderDataOptions<
-  TRouteTree extends AnyRoute,
+export interface UseLoaderDataBaseOptions<
+  TRouter extends AnyRouter,
   TFrom,
   TStrict extends boolean,
-  TRouteMatch extends MakeRouteMatch<TRouteTree, TFrom, TStrict>,
   TSelected,
-> = StrictOrFrom<Constrain<TFrom, RouteIds<TRouteTree>>, TStrict> & {
-  select?: (match: Required<TRouteMatch>['loaderData']) => TSelected
+  TStructuralSharing,
+> {
+  select?: (
+    match: ResolveLoaderData<TRouter, TFrom, TStrict>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
 }
 
+export type UseLoaderDataOptions<
+  TRouter extends AnyRouter,
+  TFrom extends string | undefined,
+  TStrict extends boolean,
+  TSelected,
+  TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseLoaderDataBaseOptions<
+    TRouter,
+    TFrom,
+    TStrict,
+    TSelected,
+    TStructuralSharing
+  > &
+  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type ResolveLoaderData<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? AllLoaderData<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['loaderData']>
+
+export type UseLoaderDataResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveLoaderData<TRouter, TFrom, TStrict>
+  : TSelected
+
+export type UseLoaderDataRoute<out TId> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseLoaderDataBaseOptions<
+    TRouter,
+    TId,
+    true,
+    TSelected,
+    TStructuralSharing
+  > &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseLoaderDataResult<TRouter, TId, true, TSelected>
+
 export function useLoaderData<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
+  TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
   TStrict extends boolean = true,
-  TRouteMatch extends MakeRouteMatch<
-    TRouteTree,
-    TFrom,
-    TStrict
-  > = MakeRouteMatch<TRouteTree, TFrom, TStrict>,
-  TSelected = Required<TRouteMatch>['loaderData'],
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
 >(
   opts: UseLoaderDataOptions<
-    TRouteTree,
+    TRouter,
     TFrom,
     TStrict,
-    TRouteMatch,
-    TSelected
+    TSelected,
+    TStructuralSharing
   >,
-): TSelected {
-  return useMatch<TRouteTree, TFrom, TStrict, TRouteMatch, TSelected>({
-    ...opts,
-    select: (s) => {
-      return typeof opts.select === 'function'
-        ? opts.select(s.loaderData)
-        : (s.loaderData as TSelected)
+): UseLoaderDataResult<TRouter, TFrom, TStrict, TSelected> {
+  return useMatch({
+    from: opts.from!,
+    strict: opts.strict,
+    structuralSharing: opts.structuralSharing,
+    select: (s: any) => {
+      return opts.select ? opts.select(s.loaderData) : s.loaderData
     },
-  })
+  } as any) as UseLoaderDataResult<TRouter, TFrom, TStrict, TSelected>
 }

package/src/useLoaderDeps.tsx

@@ -1,29 +1,64 @@
 import { useMatch } from './useMatch'
-import type { RegisteredRouter } from './router'
-import type { AnyRoute } from './route'
-import type { MakeRouteMatch } from './Matches'
-import type { RouteIds } from './routeInfo'
-import type { Constrain, StrictOrFrom } from './utils'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { RouteById } from './routeInfo'
+import type { Expand, StrictOrFrom } from './utils'
+
+export interface UseLoaderDepsBaseOptions<
+  TRouter extends AnyRouter,
+  TFrom,
+  TSelected,
+  TStructuralSharing,
+> {
+  select?: (
+    deps: ResolveLoaderDeps<TRouter, TFrom>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+}
+
+export type UseLoaderDepsOptions<
+  TRouter extends AnyRouter,
+  TFrom extends string | undefined,
+  TSelected,
+  TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom> &
+  UseLoaderDepsBaseOptions<TRouter, TFrom, TSelected, TStructuralSharing> &
+  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type ResolveLoaderDeps<TRouter extends AnyRouter, TFrom> = Expand<
+  RouteById<TRouter['routeTree'], TFrom>['types']['loaderDeps']
+>
+
+export type UseLoaderDepsResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TSelected,
+> = unknown extends TSelected ? ResolveLoaderDeps<TRouter, TFrom> : TSelected
+
+export type UseLoaderDepsRoute<out TId> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseLoaderDepsBaseOptions<TRouter, TId, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, false>,
+) => UseLoaderDepsResult<TRouter, TId, TSelected>
 
 export function useLoaderDeps<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
+  TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
-  TRouteMatch extends MakeRouteMatch<TRouteTree, TFrom> = MakeRouteMatch<
-    TRouteTree,
-    TFrom
-  >,
-  TSelected = Required<TRouteMatch>['loaderDeps'],
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
 >(
-  opts: StrictOrFrom<Constrain<TFrom, RouteIds<TRouteTree>>> & {
-    select?: (match: TRouteMatch) => TSelected
-  },
-): TSelected {
+  opts: UseLoaderDepsOptions<TRouter, TFrom, TSelected, TStructuralSharing>,
+): UseLoaderDepsResult<TRouter, TFrom, TSelected> {
+  const { select, ...rest } = opts
   return useMatch({
-    ...opts,
+    ...rest,
     select: (s) => {
-      return typeof opts.select === 'function'
-        ? opts.select(s.loaderDeps)
-        : s.loaderDeps
+      return select ? select(s.loaderDeps) : s.loaderDeps
     },
-  })
+  }) as UseLoaderDepsResult<TRouter, TFrom, TSelected>
 }

package/src/useLocation.tsx

@@ -1,15 +1,37 @@
 import { useRouterState } from './useRouterState'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
 import type { AnyRouter, RegisteredRouter, RouterState } from './router'
 
+export interface UseLocationBaseOptions<
+  TRouter extends AnyRouter,
+  TSelected,
+  TStructuralSharing extends boolean = boolean,
+> {
+  select?: (
+    state: RouterState<TRouter['routeTree']>['location'],
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+}
+
+export type UseLocationResult<
+  TRouter extends AnyRouter,
+  TSelected,
+> = unknown extends TSelected
+  ? RouterState<TRouter['routeTree']>['location']
+  : TSelected
+
 export function useLocation<
   TRouter extends AnyRouter = RegisteredRouter,
-  TLocationState = RouterState<TRouter['routeTree']>['location'],
-  TSelected = TLocationState,
->(opts?: { select?: (state: TLocationState) => TSelected }): TSelected {
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseLocationBaseOptions<TRouter, TSelected, TStructuralSharing> &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+): UseLocationResult<TRouter, TSelected> {
   return useRouterState({
-    select: (state) =>
-      opts?.select
-        ? opts.select(state.location as TLocationState)
-        : (state.location as TSelected),
-  })
+    select: (state: any) =>
+      opts?.select ? opts.select(state.location) : state.location,
+  } as any) as UseLocationResult<TRouter, TSelected>
 }

package/src/useMatch.tsx

@@ -2,44 +2,93 @@ import * as React from 'react'
 import invariant from 'tiny-invariant'
 import { useRouterState } from './useRouterState'
 import { matchContext } from './matchContext'
-import type { RegisteredRouter } from './router'
-import type { AnyRoute } from './route'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type { AnyRouter, RegisteredRouter } from './router'
 import type { MakeRouteMatch } from './Matches'
-import type { RouteIds } from './routeInfo'
-import type { Constrain, StrictOrFrom } from './utils'
+import type { StrictOrFrom, ThrowOrOptional } from './utils'
 
-export type UseMatchOptions<
+export interface UseMatchBaseOptions<
+  TRouter extends AnyRouter,
   TFrom,
   TStrict extends boolean,
-  TRouteMatch,
+  TThrow,
   TSelected,
-  TThrow extends boolean,
-> = StrictOrFrom<TFrom, TStrict> & {
-  select?: (match: TRouteMatch) => TSelected
+  TStructuralSharing extends boolean,
+> {
+  select?: (
+    match: MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
   shouldThrow?: TThrow
 }
 
+export type UseMatchRoute<out TFrom> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseMatchBaseOptions<
+    TRouter,
+    TFrom,
+    true,
+    true,
+    TSelected,
+    TStructuralSharing
+  > &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseMatchResult<TRouter, TFrom, true, TSelected>
+
+export type UseMatchOptions<
+  TRouter extends AnyRouter,
+  TFrom extends string | undefined,
+  TStrict extends boolean,
+  TSelected,
+  TThrow extends boolean,
+  TStructuralSharing extends boolean,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseMatchBaseOptions<
+    TRouter,
+    TFrom,
+    TStrict,
+    TThrow,
+    TSelected,
+    TStructuralSharing
+  > &
+  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type UseMatchResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>
+  : TSelected
+
 export function useMatch<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
+  TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
   TStrict extends boolean = true,
-  TRouteMatch = MakeRouteMatch<TRouteTree, TFrom, TStrict>,
-  TSelected = TRouteMatch,
   TThrow extends boolean = true,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
 >(
   opts: UseMatchOptions<
-    Constrain<TFrom, RouteIds<TRouteTree>>,
+    TRouter,
+    TFrom,
     TStrict,
-    TRouteMatch,
     TSelected,
-    TThrow
+    TThrow,
+    TStructuralSharing
   >,
-): TThrow extends true ? TSelected : TSelected | undefined {
+): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow> {
   const nearestMatchId = React.useContext(matchContext)
 
   const matchSelection = useRouterState({
-    select: (state) => {
-      const match = state.matches.find((d) =>
+    select: (state: any) => {
+      const match = state.matches.find((d: any) =>
         opts.from ? opts.from === d.routeId : d.id === nearestMatchId,
       )
       invariant(
@@ -51,9 +100,10 @@ export function useMatch<
         return undefined
       }
 
-      return opts.select ? opts.select(match as any) : match
+      return opts.select ? opts.select(match) : match
     },
-  })
+    structuralSharing: opts.structuralSharing,
+  } as any)
 
-  return matchSelection as TSelected
+  return matchSelection as any
 }