@tanstack/router-core 1.111.3 → 1.111.7

package/src/index.ts

@@ -85,6 +85,12 @@ export type {
   IsMatchResult,
   IsMatchParse,
   IsMatch,
+  RouteMatch,
+  RouteMatchExtensions,
+  MakeRouteMatchUnion,
+  MakeRouteMatch,
+  AnyRouteMatch,
+  MakeRouteMatchFromRoute,
 } from './Matches'
 export {
   joinPaths,
@@ -167,6 +173,19 @@ export type {
   MakeRemountDepsOptionsUnion,
   ResolveFullPath,
   AnyRouteWithContext,
+  RouteOptions,
+  FileBaseRouteOptions,
+  BaseRouteOptions,
+  UpdatableRouteOptions,
+  RouteLoaderFn,
+  LoaderFnContext,
+  RouteContextFn,
+  RouteContextOptions,
+  BeforeLoadFn,
+  BeforeLoadContextOptions,
+  ContextOptions,
+  RootRouteOptions,
+  UpdatableRouteOptionsExtensions,
 } from './route'
 
 export { defaultSerializeError, getLocationChangeInfo } from './router'
@@ -181,6 +200,7 @@ export type {
   Register,
   AnyRouter,
   AnyRouterWithContext,
+  RegisteredRouter,
 } from './router'
 
 export type {
@@ -245,6 +265,7 @@ export type {
   MergeAllObjects,
   MergeAll,
   ValidateJSON,
+  StrictOrFrom,
 } from './utils'
 
 export type {
@@ -274,3 +295,21 @@ export type {
   ResolveValidatorOutputFn,
   ResolveValidatorOutput,
 } from './validators'
+
+export type {
+  UseRouteContextBaseOptions,
+  UseRouteContextOptions,
+  UseRouteContextResult,
+} from './useRouteContext'
+
+export type { UseSearchResult, ResolveUseSearch } from './useSearch'
+
+export type { UseParamsResult, ResolveUseParams } from './useParams'
+
+export type { UseNavigateResult } from './useNavigate'
+
+export type { UseLoaderDepsResult, ResolveUseLoaderDeps } from './useLoaderDeps'
+
+export type { UseLoaderDataResult, ResolveUseLoaderData } from './useLoaderData'
+
+export type { Redirect, ResolvedRedirect, AnyRedirect } from './redirect'

package/src/path.ts

@@ -183,7 +183,12 @@ export function parsePathname(pathname?: string): Array<Segment> {
 
       return {
         type: 'pathname',
-        value: decodeURI(part),
+        value: part.includes('%25')
+          ? part
+              .split('%25')
+              .map((segment) => decodeURI(segment))
+              .join('%25')
+          : decodeURI(part),
       }
     }),
   )

package/src/redirect.ts

@@ -0,0 +1,36 @@
+import type { NavigateOptions } from './link'
+import type { RoutePaths } from './routeInfo'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { PickAsRequired } from './utils'
+
+export type AnyRedirect = Redirect<any, any, any, any, any>
+
+export type Redirect<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends RoutePaths<TRouter['routeTree']> | string = '/',
+  TTo extends string | undefined = '.',
+  TMaskFrom extends RoutePaths<TRouter['routeTree']> | string = TFrom,
+  TMaskTo extends string = '.',
+> = {
+  href?: string
+  /**
+   * @deprecated Use `statusCode` instead
+   **/
+  code?: number
+  statusCode?: number
+  throw?: any
+  headers?: HeadersInit
+} & NavigateOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>
+
+export type ResolvedRedirect<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends RoutePaths<TRouter['routeTree']> = '/',
+  TTo extends string = '',
+  TMaskFrom extends RoutePaths<TRouter['routeTree']> = TFrom,
+  TMaskTo extends string = '',
+> = PickAsRequired<
+  Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
+  'code' | 'statusCode' | 'headers'
+> & {
+  href: string
+}

package/src/route.ts

@@ -1,13 +1,29 @@
-import type { ParsePathParams } from './link'
+import type { NavigateOptions, ParsePathParams } from './link'
+import type { ParsedLocation } from './location'
+import type {
+  AnyRouteMatch,
+  MakeRouteMatchFromRoute,
+  MakeRouteMatchUnion,
+  RouteMatch,
+} from './Matches'
 import type { RootRouteId } from './root'
 import type { ParseRoute } from './routeInfo'
-import type { RegisteredRouter } from './router'
-import type { Assign, Expand, IntersectAssign } from './utils'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { BuildLocationFn, NavigateFn } from './RouterProvider'
+import type {
+  Assign,
+  Constrain,
+  Expand,
+  IntersectAssign,
+  NoInfer,
+} from './utils'
 import type {
   AnySchema,
   AnyStandardSchemaValidator,
+  AnyValidator,
   AnyValidatorAdapter,
   AnyValidatorObj,
+  DefaultValidator,
   ResolveSearchValidatorInput,
   ResolveValidatorOutput,
   StandardSchemaValidator,
@@ -503,6 +519,517 @@ export type AnyRouteWithContext<TContext> = AnyRoute & {
   types: { allContext: TContext }
 }
 
+export type RouteOptions<
+  TParentRoute extends AnyRoute = AnyRoute,
+  TId extends string = string,
+  TCustomId extends string = string,
+  TFullPath extends string = string,
+  TPath extends string = string,
+  TSearchValidator = undefined,
+  TParams = AnyPathParams,
+  TLoaderDeps extends Record<string, any> = {},
+  TLoaderFn = undefined,
+  TRouterContext = {},
+  TRouteContextFn = AnyContext,
+  TBeforeLoadFn = AnyContext,
+> = BaseRouteOptions<
+  TParentRoute,
+  TId,
+  TCustomId,
+  TPath,
+  TSearchValidator,
+  TParams,
+  TLoaderDeps,
+  TLoaderFn,
+  TRouterContext,
+  TRouteContextFn,
+  TBeforeLoadFn
+> &
+  UpdatableRouteOptions<
+    NoInfer<TParentRoute>,
+    NoInfer<TCustomId>,
+    NoInfer<TFullPath>,
+    NoInfer<TParams>,
+    NoInfer<TSearchValidator>,
+    NoInfer<TLoaderFn>,
+    NoInfer<TLoaderDeps>,
+    NoInfer<TRouterContext>,
+    NoInfer<TRouteContextFn>,
+    NoInfer<TBeforeLoadFn>
+  >
+
+export type RouteContextFn<
+  in out TParentRoute extends AnyRoute,
+  in out TSearchValidator,
+  in out TParams,
+  in out TRouterContext,
+> = (
+  ctx: RouteContextOptions<
+    TParentRoute,
+    TSearchValidator,
+    TParams,
+    TRouterContext
+  >,
+) => any
+
+export type BeforeLoadFn<
+  in out TParentRoute extends AnyRoute,
+  in out TSearchValidator,
+  in out TParams,
+  in out TRouterContext,
+  in out TRouteContextFn,
+> = (
+  ctx: BeforeLoadContextOptions<
+    TParentRoute,
+    TSearchValidator,
+    TParams,
+    TRouterContext,
+    TRouteContextFn
+  >,
+) => any
+
+export type FileBaseRouteOptions<
+  TParentRoute extends AnyRoute = AnyRoute,
+  TId extends string = string,
+  TPath extends string = string,
+  TSearchValidator = undefined,
+  TParams = {},
+  TLoaderDeps extends Record<string, any> = {},
+  TLoaderFn = undefined,
+  TRouterContext = {},
+  TRouteContextFn = AnyContext,
+  TBeforeLoadFn = AnyContext,
+  TRemountDepsFn = AnyContext,
+> = ParamsOptions<TPath, TParams> & {
+  validateSearch?: Constrain<TSearchValidator, AnyValidator, DefaultValidator>
+
+  shouldReload?:
+    | boolean
+    | ((
+        match: LoaderFnContext<
+          TParentRoute,
+          TId,
+          TParams,
+          TLoaderDeps,
+          TRouterContext,
+          TRouteContextFn,
+          TBeforeLoadFn
+        >,
+      ) => any)
+
+  context?: Constrain<
+    TRouteContextFn,
+    (
+      ctx: RouteContextOptions<
+        TParentRoute,
+        TParams,
+        TRouterContext,
+        TLoaderDeps
+      >,
+    ) => any
+  >
+
+  // This async function is called before a route is loaded.
+  // If an error is thrown here, the route's loader will not be called.
+  // If thrown during a navigation, the navigation will be cancelled and the error will be passed to the `onError` function.
+  // If thrown during a preload event, the error will be logged to the console.
+  beforeLoad?: Constrain<
+    TBeforeLoadFn,
+    (
+      ctx: BeforeLoadContextOptions<
+        TParentRoute,
+        TSearchValidator,
+        TParams,
+        TRouterContext,
+        TRouteContextFn
+      >,
+    ) => any
+  >
+
+  loaderDeps?: (
+    opts: FullSearchSchemaOption<TParentRoute, TSearchValidator>,
+  ) => TLoaderDeps
+
+  remountDeps?: Constrain<
+    TRemountDepsFn,
+    (
+      opt: RemountDepsOptions<
+        TId,
+        FullSearchSchemaOption<TParentRoute, TSearchValidator>,
+        Expand<ResolveAllParamsFromParent<TParentRoute, TParams>>,
+        TLoaderDeps
+      >,
+    ) => any
+  >
+
+  loader?: Constrain<
+    TLoaderFn,
+    (
+      ctx: LoaderFnContext<
+        TParentRoute,
+        TId,
+        TParams,
+        TLoaderDeps,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn
+      >,
+    ) => any
+  >
+}
+
+export type BaseRouteOptions<
+  TParentRoute extends AnyRoute = AnyRoute,
+  TId extends string = string,
+  TCustomId extends string = string,
+  TPath extends string = string,
+  TSearchValidator = undefined,
+  TParams = {},
+  TLoaderDeps extends Record<string, any> = {},
+  TLoaderFn = undefined,
+  TRouterContext = {},
+  TRouteContextFn = AnyContext,
+  TBeforeLoadFn = AnyContext,
+> = RoutePathOptions<TCustomId, TPath> &
+  FileBaseRouteOptions<
+    TParentRoute,
+    TId,
+    TPath,
+    TSearchValidator,
+    TParams,
+    TLoaderDeps,
+    TLoaderFn,
+    TRouterContext,
+    TRouteContextFn,
+    TBeforeLoadFn
+  > & {
+    getParentRoute: () => TParentRoute
+  }
+
+export interface ContextOptions<
+  in out TParentRoute extends AnyRoute,
+  in out TParams,
+> {
+  abortController: AbortController
+  preload: boolean
+  params: Expand<ResolveAllParamsFromParent<TParentRoute, TParams>>
+  location: ParsedLocation
+  /**
+   * @deprecated Use `throw redirect({ to: '/somewhere' })` instead
+   **/
+  navigate: NavigateFn
+  buildLocation: BuildLocationFn
+  cause: 'preload' | 'enter' | 'stay'
+  matches: Array<MakeRouteMatchUnion>
+}
+
+export interface RouteContextOptions<
+  in out TParentRoute extends AnyRoute,
+  in out TParams,
+  in out TRouterContext,
+  in out TLoaderDeps,
+> extends ContextOptions<TParentRoute, TParams> {
+  deps: TLoaderDeps
+  context: Expand<RouteContextParameter<TParentRoute, TRouterContext>>
+}
+
+export interface BeforeLoadContextOptions<
+  in out TParentRoute extends AnyRoute,
+  in out TSearchValidator,
+  in out TParams,
+  in out TRouterContext,
+  in out TRouteContextFn,
+> extends ContextOptions<TParentRoute, TParams>,
+    FullSearchSchemaOption<TParentRoute, TSearchValidator> {
+  context: Expand<
+    BeforeLoadContextParameter<TParentRoute, TRouterContext, TRouteContextFn>
+  >
+}
+
+type AssetFnContextOptions<
+  in out TRouteId,
+  in out TFullPath,
+  in out TParentRoute extends AnyRoute,
+  in out TParams,
+  in out TSearchValidator,
+  in out TLoaderFn,
+  in out TRouterContext,
+  in out TRouteContextFn,
+  in out TBeforeLoadFn,
+  in out TLoaderDeps,
+> = {
+  matches: Array<
+    RouteMatch<
+      TRouteId,
+      TFullPath,
+      ResolveAllParamsFromParent<TParentRoute, TParams>,
+      ResolveFullSearchSchema<TParentRoute, TSearchValidator>,
+      ResolveLoaderData<TLoaderFn>,
+      ResolveAllContext<
+        TParentRoute,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn
+      >,
+      TLoaderDeps
+    >
+  >
+  match: RouteMatch<
+    TRouteId,
+    TFullPath,
+    ResolveAllParamsFromParent<TParentRoute, TParams>,
+    ResolveFullSearchSchema<TParentRoute, TSearchValidator>,
+    ResolveLoaderData<TLoaderFn>,
+    ResolveAllContext<
+      TParentRoute,
+      TRouterContext,
+      TRouteContextFn,
+      TBeforeLoadFn
+    >,
+    TLoaderDeps
+  >
+  params: ResolveAllParamsFromParent<TParentRoute, TParams>
+  loaderData: ResolveLoaderData<TLoaderFn>
+}
+
+export interface DefaultUpdatableRouteOptionsExtensions {
+  component?: unknown
+  errorComponent?: unknown
+  notFoundComponent?: unknown
+  pendingComponent?: unknown
+}
+
+export interface UpdatableRouteOptionsExtensions {}
+
+export interface UpdatableRouteOptions<
+  in out TParentRoute extends AnyRoute,
+  in out TRouteId,
+  in out TFullPath,
+  in out TParams,
+  in out TSearchValidator,
+  in out TLoaderFn,
+  in out TLoaderDeps,
+  in out TRouterContext,
+  in out TRouteContextFn,
+  in out TBeforeLoadFn,
+> extends UpdatableStaticRouteOption,
+    UpdatableRouteOptionsExtensions {
+  // If true, this route will be matched as case-sensitive
+  caseSensitive?: boolean
+  // If true, this route will be forcefully wrapped in a suspense boundary
+  wrapInSuspense?: boolean
+  // The content to be rendered when the route is matched. If no component is provided, defaults to `<Outlet />`
+
+  pendingMs?: number
+  pendingMinMs?: number
+  staleTime?: number
+  gcTime?: number
+  preload?: boolean
+  preloadStaleTime?: number
+  preloadGcTime?: number
+  search?: {
+    middlewares?: Array<
+      SearchMiddleware<
+        ResolveFullSearchSchemaInput<TParentRoute, TSearchValidator>
+      >
+    >
+  }
+  /** 
+  @deprecated Use search.middlewares instead
+  */
+  preSearchFilters?: Array<
+    SearchFilter<ResolveFullSearchSchema<TParentRoute, TSearchValidator>>
+  >
+  /** 
+  @deprecated Use search.middlewares instead
+  */
+  postSearchFilters?: Array<
+    SearchFilter<ResolveFullSearchSchema<TParentRoute, TSearchValidator>>
+  >
+  onCatch?: (error: Error) => void
+  onError?: (err: any) => void
+  // These functions are called as route matches are loaded, stick around and leave the active
+  // matches
+  onEnter?: (
+    match: RouteMatch<
+      TRouteId,
+      TFullPath,
+      ResolveAllParamsFromParent<TParentRoute, TParams>,
+      ResolveFullSearchSchema<TParentRoute, TSearchValidator>,
+      ResolveLoaderData<TLoaderFn>,
+      ResolveAllContext<
+        TParentRoute,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn
+      >,
+      TLoaderDeps
+    >,
+  ) => void
+  onStay?: (
+    match: RouteMatch<
+      TRouteId,
+      TFullPath,
+      ResolveAllParamsFromParent<TParentRoute, TParams>,
+      ResolveFullSearchSchema<TParentRoute, TSearchValidator>,
+      ResolveLoaderData<TLoaderFn>,
+      ResolveAllContext<
+        TParentRoute,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn
+      >,
+      TLoaderDeps
+    >,
+  ) => void
+  onLeave?: (
+    match: RouteMatch<
+      TRouteId,
+      TFullPath,
+      ResolveAllParamsFromParent<TParentRoute, TParams>,
+      ResolveFullSearchSchema<TParentRoute, TSearchValidator>,
+      ResolveLoaderData<TLoaderFn>,
+      ResolveAllContext<
+        TParentRoute,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn
+      >,
+      TLoaderDeps
+    >,
+  ) => void
+  headers?: (ctx: {
+    loaderData: ResolveLoaderData<TLoaderFn>
+  }) => Record<string, string>
+  head?: (
+    ctx: AssetFnContextOptions<
+      TRouteId,
+      TFullPath,
+      TParentRoute,
+      TParams,
+      TSearchValidator,
+      TLoaderFn,
+      TRouterContext,
+      TRouteContextFn,
+      TBeforeLoadFn,
+      TLoaderDeps
+    >,
+  ) => {
+    links?: AnyRouteMatch['links']
+    scripts?: AnyRouteMatch['headScripts']
+    meta?: AnyRouteMatch['meta']
+  }
+  scripts?: (
+    ctx: AssetFnContextOptions<
+      TRouteId,
+      TFullPath,
+      TParentRoute,
+      TParams,
+      TSearchValidator,
+      TLoaderFn,
+      TRouterContext,
+      TRouteContextFn,
+      TBeforeLoadFn,
+      TLoaderDeps
+    >,
+  ) => AnyRouteMatch['scripts']
+  ssr?: boolean
+  codeSplitGroupings?: Array<
+    Array<
+      | 'loader'
+      | 'component'
+      | 'pendingComponent'
+      | 'notFoundComponent'
+      | 'errorComponent'
+    >
+  >
+}
+
+export type RouteLoaderFn<
+  in out TParentRoute extends AnyRoute = AnyRoute,
+  in out TId extends string = string,
+  in out TParams = {},
+  in out TLoaderDeps = {},
+  in out TRouterContext = {},
+  in out TRouteContextFn = AnyContext,
+  in out TBeforeLoadFn = AnyContext,
+> = (
+  match: LoaderFnContext<
+    TParentRoute,
+    TId,
+    TParams,
+    TLoaderDeps,
+    TRouterContext,
+    TRouteContextFn,
+    TBeforeLoadFn
+  >,
+) => any
+
+export interface LoaderFnContext<
+  in out TParentRoute extends AnyRoute = AnyRoute,
+  in out TId extends string = string,
+  in out TParams = {},
+  in out TLoaderDeps = {},
+  in out TRouterContext = {},
+  in out TRouteContextFn = AnyContext,
+  in out TBeforeLoadFn = AnyContext,
+> {
+  abortController: AbortController
+  preload: boolean
+  params: Expand<ResolveAllParamsFromParent<TParentRoute, TParams>>
+  deps: TLoaderDeps
+  context: Expand<
+    ResolveAllContext<
+      TParentRoute,
+      TRouterContext,
+      TRouteContextFn,
+      TBeforeLoadFn
+    >
+  >
+  location: ParsedLocation // Do not supply search schema here so as to demotivate people from trying to shortcut loaderDeps
+  /**
+   * @deprecated Use `throw redirect({ to: '/somewhere' })` instead
+   **/
+  navigate: (opts: NavigateOptions<AnyRouter>) => Promise<void> | void
+  // root route does not have a parent match
+  parentMatchPromise: TId extends RootRouteId
+    ? never
+    : Promise<MakeRouteMatchFromRoute<TParentRoute>>
+  cause: 'preload' | 'enter' | 'stay'
+  route: AnyRoute
+}
+
+export type RootRouteOptions<
+  TSearchValidator = undefined,
+  TRouterContext = {},
+  TRouteContextFn = AnyContext,
+  TBeforeLoadFn = AnyContext,
+  TLoaderDeps extends Record<string, any> = {},
+  TLoaderFn = undefined,
+> = Omit<
+  RouteOptions<
+    any, // TParentRoute
+    RootRouteId, // TId
+    RootRouteId, // TCustomId
+    '', // TFullPath
+    '', // TPath
+    TSearchValidator,
+    {}, // TParams
+    TLoaderDeps,
+    TLoaderFn,
+    TRouterContext,
+    TRouteContextFn,
+    TBeforeLoadFn
+  >,
+  | 'path'
+  | 'id'
+  | 'getParentRoute'
+  | 'caseSensitive'
+  | 'parseParams'
+  | 'stringifyParams'
+  | 'params'
+>
+
 /**
  * @deprecated Use `ErrorComponentProps` instead.
  */

package/src/useLoaderData.ts

@@ -0,0 +1,20 @@
+import type { AllLoaderData, RouteById } from './routeInfo'
+import type { AnyRouter } from './router'
+import type { Expand } from './utils'
+
+export type ResolveUseLoaderData<
+  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
+  ? ResolveUseLoaderData<TRouter, TFrom, TStrict>
+  : TSelected

package/src/useLoaderDeps.ts

@@ -0,0 +1,13 @@
+import type { RouteById } from './routeInfo'
+import type { AnyRouter } from './router'
+import type { Expand } from './utils'
+
+export type ResolveUseLoaderDeps<TRouter extends AnyRouter, TFrom> = Expand<
+  RouteById<TRouter['routeTree'], TFrom>['types']['loaderDeps']
+>
+
+export type UseLoaderDepsResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TSelected,
+> = unknown extends TSelected ? ResolveUseLoaderDeps<TRouter, TFrom> : TSelected