@tanstack/react-router 1.79.0 → 1.81.0

package/src/useParams.tsx

@@ -1,38 +1,87 @@
 import { useMatch } from './useMatch'
-import type { AnyRoute } from './route'
-import type { AllParams, RouteById, RouteIds } from './routeInfo'
-import type { RegisteredRouter } from './router'
-import type { Constrain, StrictOrFrom } from './utils'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type { AllParams, RouteById } from './routeInfo'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { Expand, StrictOrFrom } from './utils'
 
-export type UseParamsOptions<
+export interface UseParamsBaseOptions<
+  TRouter extends AnyRouter,
   TFrom,
   TStrict extends boolean,
-  TParams,
   TSelected,
-> = StrictOrFrom<TFrom, TStrict> & {
-  select?: (params: TParams) => TSelected
+  TStructuralSharing,
+> {
+  select?: (
+    params: ResolveParams<TRouter, TFrom, TStrict>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
 }
 
+export type UseParamsOptions<
+  TRouter extends AnyRouter,
+  TFrom extends string | undefined,
+  TStrict extends boolean,
+  TSelected,
+  TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseParamsBaseOptions<TRouter, TFrom, TStrict, TSelected, TStructuralSharing> &
+  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type ResolveParams<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? AllParams<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['allParams']>
+
+export type UseParamsResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveParams<TRouter, TFrom, TStrict>
+  : TSelected
+
+export type UseParamsRoute<out TFrom> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseParamsBaseOptions<
+    TRouter,
+    TFrom,
+    true,
+    TSelected,
+    TStructuralSharing
+  > &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseParamsResult<TRouter, TFrom, true, TSelected>
+
 export function useParams<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
+  TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
   TStrict extends boolean = true,
-  TParams = TStrict extends false
-    ? AllParams<TRouteTree>
-    : RouteById<TRouteTree, TFrom>['types']['allParams'],
-  TSelected = TParams,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
 >(
   opts: UseParamsOptions<
-    Constrain<TFrom, RouteIds<TRouteTree>>,
+    TRouter,
+    TFrom,
     TStrict,
-    TParams,
-    TSelected
+    TSelected,
+    TStructuralSharing
   >,
-): TSelected {
+): UseParamsResult<TRouter, TFrom, TStrict, TSelected> {
   return useMatch({
-    ...opts,
-    select: (match) => {
-      return opts.select ? opts.select(match.params as TParams) : match.params
+    from: opts.from!,
+    strict: opts.strict,
+    structuralSharing: opts.structuralSharing,
+    select: (match: any) => {
+      return opts.select ? opts.select(match.params) : match.params
     },
-  }) as TSelected
+  } as any) as UseParamsResult<TRouter, TFrom, TStrict, TSelected>
 }

package/src/useRouteContext.ts

@@ -1,38 +1,60 @@
 import { useMatch } from './useMatch'
-import type { MakeRouteMatch } from './Matches'
-import type { AnyRoute } from './route'
-import type { AllContext, RouteById, RouteIds } from './routeInfo'
-import type { RegisteredRouter } from './router'
-import type { Constrain, Expand, StrictOrFrom } from './utils'
+import type { AllContext, RouteById } from './routeInfo'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { Expand, StrictOrFrom } from './utils'
 
-export type UseRouteContextOptions<
+export interface UseRouteContextBaseOptions<
+  TRouter extends AnyRouter,
   TFrom,
   TStrict extends boolean,
-  TRouteContext,
   TSelected,
-> = StrictOrFrom<TFrom, TStrict> & {
-  select?: (search: TRouteContext) => TSelected
+> {
+  select?: (search: ResolveRouteContext<TRouter, TFrom, TStrict>) => TSelected
 }
 
+export type UseRouteContextOptions<
+  TRouter extends AnyRouter,
+  TFrom extends string | undefined,
+  TStrict extends boolean,
+  TSelected,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseRouteContextBaseOptions<TRouter, TFrom, TStrict, TSelected>
+
+export type ResolveRouteContext<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? AllContext<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['allContext']>
+
+export type UseRouteContextResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveRouteContext<TRouter, TFrom, TStrict>
+  : TSelected
+
+export type UseRouteContextRoute<out TFrom> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+>(
+  opts?: UseRouteContextBaseOptions<TRouter, TFrom, true, TSelected>,
+) => UseRouteContextResult<TRouter, TFrom, true, TSelected>
+
 export function useRouteContext<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
+  TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
   TStrict extends boolean = true,
-  TRouteContext = TStrict extends false
-    ? AllContext<TRouteTree>
-    : Expand<RouteById<TRouteTree, TFrom>['types']['allContext']>,
-  TSelected = TRouteContext,
+  TSelected = unknown,
 >(
-  opts: UseRouteContextOptions<
-    Constrain<TFrom, RouteIds<TRouteTree>>,
-    TStrict,
-    TRouteContext,
-    TSelected
-  >,
-): TSelected {
+  opts: UseRouteContextOptions<TRouter, TFrom, TStrict, TSelected>,
+): UseRouteContextResult<TRouter, TFrom, TStrict, TSelected> {
   return useMatch({
     ...(opts as any),
-    select: (match: MakeRouteMatch<TRouteTree, TFrom>) =>
+    select: (match) =>
       opts.select ? opts.select(match.context) : match.context,
-  })
+  }) as UseRouteContextResult<TRouter, TFrom, TStrict, TSelected>
 }

package/src/useRouterState.tsx

@@ -1,16 +1,55 @@
 import { useStore } from '@tanstack/react-store'
+import { useRef } from 'react'
 import { useRouter } from './useRouter'
+import { replaceEqualDeep } from './utils'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
 import type { AnyRouter, RegisteredRouter, RouterState } from './router'
 
+export type UseRouterStateOptions<
+  TRouter extends AnyRouter,
+  TSelected,
+  TStructuralSharing,
+> = {
+  router?: TRouter
+  select?: (
+    state: RouterState<TRouter['routeTree']>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
+} & StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type UseRouterStateResult<
+  TRouter extends AnyRouter,
+  TSelected,
+> = unknown extends TSelected ? RouterState<TRouter['routeTree']> : TSelected
+
 export function useRouterState<
   TRouter extends AnyRouter = RegisteredRouter,
-  TSelected = RouterState<TRouter['routeTree']>,
->(opts?: {
-  router?: TRouter
-  select: (state: RouterState<RegisteredRouter['routeTree']>) => TSelected
-}): TSelected {
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseRouterStateOptions<TRouter, TSelected, TStructuralSharing>,
+): UseRouterStateResult<TRouter, TSelected> {
   const contextRouter = useRouter<TRouter>({
     warn: opts?.router === undefined,
   })
-  return useStore((opts?.router || contextRouter).__store, opts?.select as any)
+  const router = opts?.router || contextRouter
+  const previousResult =
+    useRef<ValidateSelected<TRouter, TSelected, TStructuralSharing>>()
+
+  return useStore(router.__store, (state) => {
+    if (opts?.select) {
+      if (opts.structuralSharing ?? router.options.defaultStructuralSharing) {
+        const newSlice = replaceEqualDeep(
+          previousResult.current,
+          opts.select(state),
+        )
+        previousResult.current = newSlice
+        return newSlice
+      }
+      return opts.select(state)
+    }
+    return state
+  }) as UseRouterStateResult<TRouter, TSelected>
 }

package/src/useSearch.tsx

@@ -1,38 +1,87 @@
 import { useMatch } from './useMatch'
-import type { AnyRoute } from './route'
-import type { FullSearchSchema, RouteById, RouteIds } from './routeInfo'
-import type { RegisteredRouter } from './router'
-import type { Constrain, Expand, StrictOrFrom } from './utils'
+import type {
+  StructuralSharingOption,
+  ValidateSelected,
+} from './structuralSharing'
+import type { FullSearchSchema, RouteById } from './routeInfo'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { Expand, StrictOrFrom } from './utils'
 
-export type UseSearchOptions<
+export interface UseSearchBaseOptions<
+  TRouter extends AnyRouter,
   TFrom,
   TStrict extends boolean,
-  TSearch,
   TSelected,
-> = StrictOrFrom<TFrom, TStrict> & {
-  select?: (search: TSearch) => TSelected
+  TStructuralSharing,
+> {
+  select?: (
+    state: ResolveSearch<TRouter, TFrom, TStrict>,
+  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>
 }
 
+export type UseSearchOptions<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+  TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseSearchBaseOptions<TRouter, TFrom, TStrict, TSelected, TStructuralSharing> &
+  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>
+
+export type UseSearchResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveSearch<TRouter, TFrom, TStrict>
+  : TSelected
+
+export type ResolveSearch<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? FullSearchSchema<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['fullSearchSchema']>
+
+export type UseSearchRoute<out TFrom> = <
+  TRouter extends AnyRouter = RegisteredRouter,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
+>(
+  opts?: UseSearchBaseOptions<
+    TRouter,
+    TFrom,
+    true,
+    TSelected,
+    TStructuralSharing
+  > &
+    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseSearchResult<TRouter, TFrom, true, TSelected>
+
 export function useSearch<
-  TRouteTree extends AnyRoute = RegisteredRouter['routeTree'],
+  TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
   TStrict extends boolean = true,
-  TSearch = TStrict extends false
-    ? FullSearchSchema<TRouteTree>
-    : Expand<RouteById<TRouteTree, TFrom>['types']['fullSearchSchema']>,
-  TSelected = TSearch,
+  TSelected = unknown,
+  TStructuralSharing extends boolean = boolean,
 >(
   opts: UseSearchOptions<
-    Constrain<TFrom, RouteIds<TRouteTree>>,
+    TRouter,
+    TFrom,
     TStrict,
-    TSearch,
-    TSelected
+    TSelected,
+    TStructuralSharing
   >,
-): TSelected {
+): UseSearchResult<TRouter, TFrom, TStrict, TSelected> {
   return useMatch({
-    ...opts,
-    select: (match) => {
+    from: opts.from!,
+    strict: opts.strict,
+    structuralSharing: opts.structuralSharing,
+    select: (match: any) => {
       return opts.select ? opts.select(match.search) : match.search
     },
-  })
+  }) as UseSearchResult<TRouter, TFrom, TStrict, TSelected>
 }

package/src/utils.ts

@@ -1,4 +1,6 @@
 import * as React from 'react'
+import type { RouteIds } from './routeInfo'
+import type { AnyRouter } from './router'
 
 export type NoInfer<T> = [T][T extends any ? 0 : never]
 export type IsAny<TValue, TYesResult, TNoResult = TValue> = 1 extends 0 & TValue
@@ -103,10 +105,16 @@ export type MergeUnion<TUnion> =
   | MergeUnionPrimitives<TUnion>
   | MergeUnionObject<TUnion>
 
-export type Constrain<T, TConstaint, TDefault = TConstaint> =
-  | (T extends TConstaint ? T : never)
+export type Constrain<T, TConstraint, TDefault = TConstraint> =
+  | (T extends TConstraint ? T : never)
   | TDefault
 
+export type ValidateJSON<T> = ((...args: Array<any>) => any) extends T
+  ? unknown extends T
+    ? never
+    : 'Function is not serializable'
+  : { [K in keyof T]: ValidateJSON<T[K]> }
+
 export function last<T>(arr: Array<T>) {
   return arr[arr.length - 1]
 }
@@ -308,6 +316,7 @@ export type StringLiteral<T> = T extends string
   : never
 
 export type StrictOrFrom<
+  TRouter extends AnyRouter,
   TFrom,
   TStrict extends boolean = true,
 > = TStrict extends false
@@ -316,10 +325,14 @@ export type StrictOrFrom<
       strict: TStrict
     }
   : {
-      from: StringLiteral<TFrom> | TFrom
+      from: StringLiteral<Constrain<TFrom, RouteIds<TRouter['routeTree']>>>
       strict?: TStrict
     }
 
+export type ThrowOrOptional<T, TThrow extends boolean> = TThrow extends true
+  ? T
+  : T | undefined
+
 export const useLayoutEffect =
   typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect