@tanstack/router-core 1.133.19 → 1.133.25

package/src/router.ts

@@ -778,6 +778,10 @@ export interface ViewTransitionOptions {
 }
 
 // TODO where is this used? can we remove this?
+/**
+ * Convert an unknown error into a minimal, serializable object.
+ * Includes name and message (and stack in development).
+ */
 export function defaultSerializeError(err: unknown) {
   if (err instanceof Error) {
     const obj = {
@@ -797,8 +801,20 @@ export function defaultSerializeError(err: unknown) {
   }
 }
 
-export type TrailingSlashOption = 'always' | 'never' | 'preserve'
+/** Options for configuring trailing-slash behavior. */
+export const trailingSlashOptions = {
+  always: 'always',
+  never: 'never',
+  preserve: 'preserve',
+} as const
 
+export type TrailingSlashOption =
+  (typeof trailingSlashOptions)[keyof typeof trailingSlashOptions]
+
+/**
+ * Compute whether path, href or hash changed between previous and current
+ * resolved locations in router state.
+ */
 export function getLocationChangeInfo(routerState: {
   resolvedLocation?: ParsedLocation
   location: ParsedLocation
@@ -835,6 +851,15 @@ export type CreateRouterFn = <
   TDehydrated
 >
 
+/**
+ * Core, framework-agnostic router engine that powers TanStack Router.
+ *
+ * Provides navigation, matching, loading, preloading, caching and event APIs
+ * used by framework adapters (React/Solid). Prefer framework helpers like
+ * `createRouter` in app code.
+ *
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/RouterType
+ */
 export class RouterCore<
   in out TRouteTree extends AnyRoute,
   in out TTrailingSlashOption extends TrailingSlashOption,
@@ -1089,6 +1114,12 @@ export class RouterCore<
     }
   }
 
+  /**
+   * Subscribe to router lifecycle events like `onBeforeNavigate`, `onLoad`,
+   * `onResolved`, etc. Returns an unsubscribe function.
+   *
+   * @link https://tanstack.com/router/latest/docs/framework/react/api/router/RouterEventsType
+   */
   subscribe: SubscribeFn = (eventType, fn) => {
     const listener: RouterListener<any> = {
       eventType,
@@ -1110,6 +1141,10 @@ export class RouterCore<
     })
   }
 
+  /**
+   * Parse a HistoryLocation into a strongly-typed ParsedLocation using the
+   * current router options, rewrite rules and search parser/stringifier.
+   */
   parseLocation: ParseLocationFn<TRouteTree> = (
     locationToParse,
     previousLocation,
@@ -1165,6 +1200,7 @@ export class RouterCore<
     return location
   }
 
+  /** Resolve a path against the router basepath and trailing-slash policy. */
   resolvePathWithBase = (from: string, path: string) => {
     const resolvedPath = resolvePath({
       base: from,
@@ -1531,6 +1567,13 @@ export class RouterCore<
     })
   }
 
+  /**
+   * Build the next ParsedLocation from navigation options without committing.
+   * Resolves `to`/`from`, params/search/hash/state, applies search validation
+   * and middlewares, and returns a stable, stringified location object.
+   *
+   * @link https://tanstack.com/router/latest/docs/framework/react/api/router/RouterType#buildlocation-method
+   */
   buildLocation: BuildLocationFn = (opts) => {
     const build = (
       dest: BuildNextOptions & {
@@ -1778,6 +1821,10 @@ export class RouterCore<
 
   commitLocationPromise: undefined | ControlledPromise<void>
 
+  /**
+   * Commit a previously built location to history (push/replace), optionally
+   * using view transitions and scroll restoration options.
+   */
   commitLocation: CommitLocationFn = ({
     viewTransition,
     ignoreBlocker,
@@ -1868,6 +1915,7 @@ export class RouterCore<
     return this.commitLocationPromise
   }
 
+  /** Convenience helper: build a location from options, then commit it. */
   buildAndCommitLocation = ({
     replace,
     resetScroll,
@@ -1904,6 +1952,13 @@ export class RouterCore<
     })
   }
 
+  /**
+   * Imperatively navigate using standard `NavigateOptions`. When `reloadDocument`
+   * or an absolute `href` is provided, performs a full document navigation.
+   * Otherwise, builds and commits a client-side location.
+   *
+   * @link https://tanstack.com/router/latest/docs/framework/react/api/router/NavigateOptionsType
+   */
   navigate: NavigateFn = ({ to, reloadDocument, href, ...rest }) => {
     if (!reloadDocument && href) {
       try {
@@ -2471,8 +2526,10 @@ export class RouterCore<
   }
 }
 
+/** Error thrown when search parameter validation fails. */
 export class SearchParamError extends Error {}
 
+/** Error thrown when path parameter parsing/validation fails. */
 export class PathParamError extends Error {}
 
 const normalize = (str: string) =>
@@ -2481,9 +2538,10 @@ function comparePaths(a: string, b: string) {
   return normalize(a) === normalize(b)
 }
 
-// A function that takes an import() argument which is a function and returns a new function that will
-// proxy arguments from the caller to the imported function, retaining all type
-// information along the way
+/**
+ * Lazily import a module function and forward arguments to it, retaining
+ * parameter and return types for the selected export key.
+ */
 export function lazyFn<
   T extends Record<string, (...args: Array<any>) => any>,
   TKey extends keyof T = 'default',
@@ -2496,6 +2554,7 @@ export function lazyFn<
   }
 }
 
+/** Create an initial RouterState from a parsed location. */
 export function getInitialRouterState(
   location: ParsedLocation,
 ): RouterState<any> {
@@ -2541,6 +2600,10 @@ function validateSearch(validateSearch: AnyValidator, input: unknown): unknown {
   return {}
 }
 
+/**
+ * Build the matched route chain and extract params for a pathname.
+ * Falls back to the root route if no specific route is found.
+ */
 export function getMatchedRoutes<TRouteLike extends RouteLike>({
   pathname,
   routePathname,

package/src/scroll-restoration.ts

@@ -33,6 +33,8 @@ function getSafeSessionStorage() {
   return undefined
 }
 
+/** SessionStorage key used to persist scroll restoration state. */
+/** SessionStorage key used to store scroll positions across navigations. */
 export const storageKey = 'tsr-scroll-restoration-v1_3'
 
 const throttle = (fn: (...args: Array<any>) => void, wait: number) => {
@@ -70,6 +72,8 @@ function createScrollRestorationCache(): ScrollRestorationCache | null {
   }
 }
 
+/** In-memory handle to the persisted scroll restoration cache. */
+/** In-memory handle to the persisted scroll restoration cache. */
 export const scrollRestorationCache = createScrollRestorationCache()
 
 /**
@@ -79,10 +83,17 @@ export const scrollRestorationCache = createScrollRestorationCache()
  * The `location.href` is used as a fallback to support the use case where the location state is not available like the initial render.
  */
 
+/**
+ * Default scroll restoration cache key: location state key or full href.
+ */
+/**
+ * Default scroll restoration cache key: location state key or full href.
+ */
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
   return location.state.__TSR_key! || location.href
 }
 
+/** Best-effort nth-child CSS selector for a given element. */
 export function getCssSelector(el: any): string {
   const path = []
   let parent: HTMLElement
@@ -101,6 +112,9 @@ let ignoreScroll = false
 // unless they are passed in as arguments. Why? Because we need to be able to
 // toString() it into a script tag to execute as early as possible in the browser
 // during SSR. Additionally, we also call it from within the router lifecycle
+/**
+ * Restore scroll positions for window/elements based on cached entries.
+ */
 export function restoreScroll({
   storageKey,
   key,
@@ -200,6 +214,7 @@ export function restoreScroll({
   ignoreScroll = false
 }
 
+/** Setup global listeners and hooks to support scroll restoration. */
 export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
   if (!scrollRestorationCache && !router.isServer) {
     return
@@ -357,6 +372,14 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
   })
 }
 
+/**
+ * @private
+ * Handles hash-based scrolling after navigation completes.
+ * To be used in framework-specific <Transitioner> components during the onResolved event.
+ *
+ * Provides hash scrolling for programmatic navigation when default browser handling is prevented.
+ * @param router The router instance containing current location and state
+ */
 /**
  * @private
  * Handles hash-based scrolling after navigation completes.

package/src/searchMiddleware.ts

@@ -13,6 +13,9 @@ import type { IsRequiredParams } from './link'
  * @returns A search middleware suitable for route `search.middlewares`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/retainSearchParamsFunction
  */
+/**
+ * Retain specified search params across navigations by merging prior values.
+ */
 export function retainSearchParams<TSearchSchema extends object>(
   keys: Array<keyof TSearchSchema> | true,
 ): SearchMiddleware<TSearchSchema> {
@@ -41,6 +44,9 @@ export function retainSearchParams<TSearchSchema extends object>(
  * @returns A search middleware suitable for route `search.middlewares`.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/stripSearchParamsFunction
  */
+/**
+ * Remove optional/default-valued search params from navigations.
+ */
 export function stripSearchParams<
   TSearchSchema,
   TOptionalProps = PickOptional<NoInfer<TSearchSchema>>,

package/src/searchParams.ts

@@ -1,6 +1,8 @@
 import { decode, encode } from './qss'
 import type { AnySchema } from './validators'
 
+/** Default `parseSearch` that strips leading '?' and JSON-parses values. */
+/** Default `parseSearch` that strips leading '?' and JSON-parses values. */
 export const defaultParseSearch = parseSearchWith(JSON.parse)
 export const defaultStringifySearch = stringifySearchWith(
   JSON.stringify,
@@ -17,6 +19,7 @@ export const defaultStringifySearch = stringifySearchWith(
  * @returns A `parseSearch` function compatible with `Router` options.
  * @link https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization
  */
+/** Build a parseSearch function using a provided JSON-like parser. */
 export function parseSearchWith(parser: (str: string) => any) {
   return (searchStr: string): AnySchema => {
     if (searchStr[0] === '?') {
@@ -53,6 +56,7 @@ export function parseSearchWith(parser: (str: string) => any) {
  * @returns A `stringifySearch` function compatible with `Router` options.
  * @link https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization
  */
+/** Build a stringifySearch function using a provided serializer/parser. */
 export function stringifySearchWith(
   stringify: (search: any) => string,
   parser?: (str: string) => any,

package/src/ssr/serializer/transformer.ts

@@ -32,6 +32,10 @@ export type UnionizeSerializationAdaptersInput<
   TAdapters extends ReadonlyArray<AnySerializationAdapter>,
 > = TAdapters[number]['~types']['input']
 
+/**
+ * Create a strongly-typed serialization adapter for SSR hydration.
+ * Use to register custom types with the router serializer.
+ */
 export function createSerializationAdapter<
   TInput = unknown,
   TOutput = unknown,
@@ -154,6 +158,7 @@ export interface SerializationAdapterTypes<
 
 export type AnySerializationAdapter = SerializationAdapter<any, any, any>
 
+/** Create a Seroval plugin for server-side serialization only. */
 export function makeSsrSerovalPlugin(
   serializationAdapter: AnySerializationAdapter,
   options: { didRun: boolean },
@@ -182,6 +187,7 @@ export function makeSsrSerovalPlugin(
   })
 }
 
+/** Create a Seroval plugin for client/server symmetric (de)serialization. */
 export function makeSerovalPlugin(
   serializationAdapter: AnySerializationAdapter,
 ): Plugin<any, SerovalNode> {