diff --git a/packages/router-core/src/defer.ts b/packages/router-core/src/defer.ts index 5cbb5823b72..1b3eb5b0f86 100644 --- a/packages/router-core/src/defer.ts +++ b/packages/router-core/src/defer.ts @@ -22,6 +22,18 @@ export type DeferredPromise = Promise & { [TSR_DEFERRED_PROMISE]: DeferredPromiseState } +/** + * Wrap a promise with a deferred state for use with `` 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( _promise: Promise, options?: { diff --git a/packages/router-core/src/redirect.ts b/packages/router-core/src/redirect.ts index 8088546268a..277d184b4b2 100644 --- a/packages/router-core/src/redirect.ts +++ b/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 } +/** 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 } diff --git a/packages/router-core/src/searchMiddleware.ts b/packages/router-core/src/searchMiddleware.ts index 91175604bf3..e90d453350f 100644 --- a/packages/router-core/src/searchMiddleware.ts +++ b/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( keys: Array | true, @@ -29,11 +32,14 @@ export function retainSearchParams( } /** - * 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, diff --git a/packages/router-core/src/searchParams.ts b/packages/router-core/src/searchParams.ts index c008b743266..f36d8e490a6 100644 --- a/packages/router-core/src/searchParams.ts +++ b/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,