Refactor: Improve documentation and types for defer, redirect, and search middleware

Co-authored-by: tannerlinsley <tannerlinsley@gmail.com>

Author: cursoragent

packages/router-core/src/defer.ts

@@ -22,6 +22,18 @@ export type DeferredPromise<T> = Promise<T> & {
   [TSR_DEFERRED_PROMISE]: DeferredPromiseState<T>
 }
 
+/**
+ * Wrap a promise with a deferred state for use with `<Await>` and `useAwaited`.
+ *
+ * The returned promise is augmented with internal state (status/data/error)
+ * so UI can read progress or suspend until it settles.
+ *
+ * @param _promise The promise to wrap.
+ * @param options Optional config. Provide `serializeError` to customize how
+ * errors are serialized for transfer.
+ * @returns The same promise with attached deferred metadata.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/deferFunction
+ */
 export function defer<T>(
   _promise: Promise<T>,
   options?: {

packages/router-core/src/redirect.ts

@@ -57,14 +57,17 @@ export type ResolvedRedirect<
 /**
  * Create a redirect Response understood by TanStack Router.
  *
- * Use inside loaders/actions/server functions. If `throw: true` is provided,
- * the redirect Response is thrown instead of returned. When an absolute `href`
- * is passed and `reloadDocument` is not set, a full-document navigation is
- * inferred.
+ * Use from route `loader`/`beforeLoad` or server functions to trigger a
+ * navigation. If `throw: true` is set, the redirect is thrown instead of
+ * returned. When an absolute `href` is supplied and `reloadDocument` is not
+ * set, a full-document navigation is inferred.
  *
- * @param opts Options for the redirect, including `href`, `statusCode`,
- * `headers`, and standard navigation options (e.g. `to`, `params`, `search`,
- * `reloadDocument`).
+ * @param opts Options for the redirect. Common fields:
+ * - `href`: absolute URL for external redirects; infers `reloadDocument`.
+ * - `statusCode`: HTTP status code to use (defaults to 307).
+ * - `headers`: additional headers to include on the Response.
+ * - Standard navigation options like `to`, `params`, `search`, `replace`,
+ *   and `reloadDocument` for internal redirects.
  * @returns A Response augmented with router navigation options.
  * @link https://tanstack.com/router/latest/docs/framework/react/api/router/redirectFunction
  */
@@ -106,6 +109,7 @@ export function redirect<
   return response as Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>
 }
 
+/** Check whether a value is a TanStack Router redirect Response. */
 export function isRedirect(obj: any): obj is AnyRedirect {
   return obj instanceof Response && !!(obj as any).options
 }

packages/router-core/src/searchMiddleware.ts

@@ -4,11 +4,14 @@ import type { SearchMiddleware } from './route'
 import type { IsRequiredParams } from './link'
 
 /**
- * Search middleware to retain specified search params across links.
+ * Retain specified search params across navigations.
  *
- * If `keys` is `true`, all existing params are retained. Otherwise, missing
- * keys from the current search are merged into the next value produced by
- * subsequent middlewares.
+ * If `keys` is `true`, retain all current params. Otherwise, copy only the
+ * listed keys from the current search into the next search.
+ *
+ * @param keys `true` to retain all, or a list of keys to retain.
+ * @returns A search middleware suitable for route `search.middlewares`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/retainSearchParamsFunction
  */
 export function retainSearchParams<TSearchSchema extends object>(
   keys: Array<keyof TSearchSchema> | true,
@@ -29,11 +32,14 @@ export function retainSearchParams<TSearchSchema extends object>(
 }
 
 /**
- * Search middleware to remove optional search params from links.
+ * Remove optional or default-valued search params from navigations.
+ *
+ * - Pass `true` (only if there are no required search params) to strip all.
+ * - Pass an array to always remove those optional keys.
+ * - Pass an object of default values; keys equal (deeply) to the defaults are removed.
  *
- * Accepts either a list of keys or an object map of default values. Keys with
- * values matching the provided defaults are removed from the final search.
- * Passing `true` removes all params.
+ * @returns A search middleware suitable for route `search.middlewares`.
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/stripSearchParamsFunction
  */
 export function stripSearchParams<
   TSearchSchema,

packages/router-core/src/searchParams.ts

@@ -15,7 +15,7 @@ export const defaultStringifySearch = stringifySearchWith(
  *
  * @param parser Function to parse a string value (e.g. `JSON.parse`).
  * @returns A `parseSearch` function compatible with `Router` options.
- * @link https://tanstack.com/router/latest/docs/router/framework/react/guide/custom-search-param-serialization
+ * @link https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization
  */
 export function parseSearchWith(parser: (str: string) => any) {
   return (searchStr: string): AnySchema => {
@@ -51,7 +51,7 @@ export function parseSearchWith(parser: (str: string) => any) {
  * @param stringify Function to serialize a value (e.g. `JSON.stringify`).
  * @param parser Optional parser to detect parseable strings.
  * @returns A `stringifySearch` function compatible with `Router` options.
- * @link https://tanstack.com/router/latest/docs/router/framework/react/guide/custom-search-param-serialization
+ * @link https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization
  */
 export function stringifySearchWith(
   stringify: (search: any) => string,