@tanstack/router-core 1.133.13 → 1.133.18

package/dist/esm/searchMiddleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"searchMiddleware.js","sources":["../../src/searchMiddleware.ts"],"sourcesContent":["import { deepEqual } from './utils'\nimport type { NoInfer, PickOptional } from './utils'\nimport type { SearchMiddleware } from './route'\nimport type { IsRequiredParams } from './link'\n\nexport function retainSearchParams<TSearchSchema extends object>(\n  keys: Array<keyof TSearchSchema> | true,\n): SearchMiddleware<TSearchSchema> {\n  return ({ search, next }) => {\n    const result = next(search)\n    if (keys === true) {\n      return { ...search, ...result }\n    }\n    // add missing keys from search to result\n    keys.forEach((key) => {\n      if (!(key in result)) {\n        result[key] = search[key]\n      }\n    })\n    return result\n  }\n}\n\nexport function stripSearchParams<\n  TSearchSchema,\n  TOptionalProps = PickOptional<NoInfer<TSearchSchema>>,\n  const TValues =\n    | Partial<NoInfer<TOptionalProps>>\n    | Array<keyof TOptionalProps>,\n  const TInput = IsRequiredParams<TSearchSchema> extends never\n    ? TValues | true\n    : TValues,\n>(input: NoInfer<TInput>): SearchMiddleware<TSearchSchema> {\n  return ({ search, next }) => {\n    if (input === true) {\n      return {}\n    }\n    const result = next(search) as Record<string, unknown>\n    if (Array.isArray(input)) {\n      input.forEach((key) => {\n        delete result[key]\n      })\n    } else {\n      Object.entries(input as Record<string, unknown>).forEach(\n        ([key, value]) => {\n          if (deepEqual(result[key], value)) {\n            delete result[key]\n          }\n        },\n      )\n    }\n    return result as any\n  }\n}\n"],"names":[],"mappings":";AAKO,SAAS,mBACd,MACiC;AACjC,SAAO,CAAC,EAAE,QAAQ,WAAW;AAC3B,UAAM,SAAS,KAAK,MAAM;AAC1B,QAAI,SAAS,MAAM;AACjB,aAAO,EAAE,GAAG,QAAQ,GAAG,OAAA;AAAA,IACzB;AAEA,SAAK,QAAQ,CAAC,QAAQ;AACpB,UAAI,EAAE,OAAO,SAAS;AACpB,eAAO,GAAG,IAAI,OAAO,GAAG;AAAA,MAC1B;AAAA,IACF,CAAC;AACD,WAAO;AAAA,EACT;AACF;AAEO,SAAS,kBASd,OAAyD;AACzD,SAAO,CAAC,EAAE,QAAQ,WAAW;AAC3B,QAAI,UAAU,MAAM;AAClB,aAAO,CAAA;AAAA,IACT;AACA,UAAM,SAAS,KAAK,MAAM;AAC1B,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,YAAM,QAAQ,CAAC,QAAQ;AACrB,eAAO,OAAO,GAAG;AAAA,MACnB,CAAC;AAAA,IACH,OAAO;AACL,aAAO,QAAQ,KAAgC,EAAE;AAAA,QAC/C,CAAC,CAAC,KAAK,KAAK,MAAM;AAChB,cAAI,UAAU,OAAO,GAAG,GAAG,KAAK,GAAG;AACjC,mBAAO,OAAO,GAAG;AAAA,UACnB;AAAA,QACF;AAAA,MAAA;AAAA,IAEJ;AACA,WAAO;AAAA,EACT;AACF;"}
+{"version":3,"file":"searchMiddleware.js","sources":["../../src/searchMiddleware.ts"],"sourcesContent":["import { deepEqual } from './utils'\nimport type { NoInfer, PickOptional } from './utils'\nimport type { SearchMiddleware } from './route'\nimport type { IsRequiredParams } from './link'\n\n/**\n * Retain specified search params across navigations.\n *\n * If `keys` is `true`, retain all current params. Otherwise, copy only the\n * listed keys from the current search into the next search.\n *\n * @param keys `true` to retain all, or a list of keys to retain.\n * @returns A search middleware suitable for route `search.middlewares`.\n * @link https://tanstack.com/router/latest/docs/framework/react/api/router/retainSearchParamsFunction\n */\nexport function retainSearchParams<TSearchSchema extends object>(\n  keys: Array<keyof TSearchSchema> | true,\n): SearchMiddleware<TSearchSchema> {\n  return ({ search, next }) => {\n    const result = next(search)\n    if (keys === true) {\n      return { ...search, ...result }\n    }\n    // add missing keys from search to result\n    keys.forEach((key) => {\n      if (!(key in result)) {\n        result[key] = search[key]\n      }\n    })\n    return result\n  }\n}\n\n/**\n * Remove optional or default-valued search params from navigations.\n *\n * - Pass `true` (only if there are no required search params) to strip all.\n * - Pass an array to always remove those optional keys.\n * - Pass an object of default values; keys equal (deeply) to the defaults are removed.\n *\n * @returns A search middleware suitable for route `search.middlewares`.\n * @link https://tanstack.com/router/latest/docs/framework/react/api/router/stripSearchParamsFunction\n */\nexport function stripSearchParams<\n  TSearchSchema,\n  TOptionalProps = PickOptional<NoInfer<TSearchSchema>>,\n  const TValues =\n    | Partial<NoInfer<TOptionalProps>>\n    | Array<keyof TOptionalProps>,\n  const TInput = IsRequiredParams<TSearchSchema> extends never\n    ? TValues | true\n    : TValues,\n>(input: NoInfer<TInput>): SearchMiddleware<TSearchSchema> {\n  return ({ search, next }) => {\n    if (input === true) {\n      return {}\n    }\n    const result = next(search) as Record<string, unknown>\n    if (Array.isArray(input)) {\n      input.forEach((key) => {\n        delete result[key]\n      })\n    } else {\n      Object.entries(input as Record<string, unknown>).forEach(\n        ([key, value]) => {\n          if (deepEqual(result[key], value)) {\n            delete result[key]\n          }\n        },\n      )\n    }\n    return result as any\n  }\n}\n"],"names":[],"mappings":";AAeO,SAAS,mBACd,MACiC;AACjC,SAAO,CAAC,EAAE,QAAQ,WAAW;AAC3B,UAAM,SAAS,KAAK,MAAM;AAC1B,QAAI,SAAS,MAAM;AACjB,aAAO,EAAE,GAAG,QAAQ,GAAG,OAAA;AAAA,IACzB;AAEA,SAAK,QAAQ,CAAC,QAAQ;AACpB,UAAI,EAAE,OAAO,SAAS;AACpB,eAAO,GAAG,IAAI,OAAO,GAAG;AAAA,MAC1B;AAAA,IACF,CAAC;AACD,WAAO;AAAA,EACT;AACF;AAYO,SAAS,kBASd,OAAyD;AACzD,SAAO,CAAC,EAAE,QAAQ,WAAW;AAC3B,QAAI,UAAU,MAAM;AAClB,aAAO,CAAA;AAAA,IACT;AACA,UAAM,SAAS,KAAK,MAAM;AAC1B,QAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,YAAM,QAAQ,CAAC,QAAQ;AACrB,eAAO,OAAO,GAAG;AAAA,MACnB,CAAC;AAAA,IACH,OAAO;AACL,aAAO,QAAQ,KAAgC,EAAE;AAAA,QAC/C,CAAC,CAAC,KAAK,KAAK,MAAM;AAChB,cAAI,UAAU,OAAO,GAAG,GAAG,KAAK,GAAG;AACjC,mBAAO,OAAO,GAAG;AAAA,UACnB;AAAA,QACF;AAAA,MAAA;AAAA,IAEJ;AACA,WAAO;AAAA,EACT;AACF;"}

package/dist/esm/searchParams.d.ts

@@ -1,7 +1,29 @@
 import { AnySchema } from './validators.js';
 export declare const defaultParseSearch: (searchStr: string) => AnySchema;
 export declare const defaultStringifySearch: (search: Record<string, any>) => string;
+/**
+ * Build a `parseSearch` function using a provided JSON-like parser.
+ *
+ * The returned function strips a leading `?`, decodes values, and attempts to
+ * JSON-parse string values using the given `parser`.
+ *
+ * @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/framework/react/guide/custom-search-param-serialization
+ */
 export declare function parseSearchWith(parser: (str: string) => any): (searchStr: string) => AnySchema;
+/**
+ * Build a `stringifySearch` function using a provided serializer.
+ *
+ * Non-primitive values are serialized with `stringify`. If a `parser` is
+ * supplied, string values that are parseable are re-serialized to ensure
+ * symmetry with `parseSearch`.
+ *
+ * @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/framework/react/guide/custom-search-param-serialization
+ */
 export declare function stringifySearchWith(stringify: (search: any) => string, parser?: (str: string) => any): (search: Record<string, any>) => string;
 export type SearchSerializer = (searchObj: Record<string, any>) => string;
 export type SearchParser = (searchStr: string) => Record<string, any>;

package/dist/esm/searchParams.js.map

@@ -1 +1 @@
-{"version":3,"file":"searchParams.js","sources":["../../src/searchParams.ts"],"sourcesContent":["import { decode, encode } from './qss'\nimport type { AnySchema } from './validators'\n\nexport const defaultParseSearch = parseSearchWith(JSON.parse)\nexport const defaultStringifySearch = stringifySearchWith(\n  JSON.stringify,\n  JSON.parse,\n)\n\nexport function parseSearchWith(parser: (str: string) => any) {\n  return (searchStr: string): AnySchema => {\n    if (searchStr[0] === '?') {\n      searchStr = searchStr.substring(1)\n    }\n\n    const query: Record<string, unknown> = decode(searchStr)\n\n    // Try to parse any query params that might be json\n    for (const key in query) {\n      const value = query[key]\n      if (typeof value === 'string') {\n        try {\n          query[key] = parser(value)\n        } catch (_err) {\n          // silent\n        }\n      }\n    }\n\n    return query\n  }\n}\n\nexport function stringifySearchWith(\n  stringify: (search: any) => string,\n  parser?: (str: string) => any,\n) {\n  const hasParser = typeof parser === 'function'\n  function stringifyValue(val: any) {\n    if (typeof val === 'object' && val !== null) {\n      try {\n        return stringify(val)\n      } catch (_err) {\n        // silent\n      }\n    } else if (hasParser && typeof val === 'string') {\n      try {\n        // Check if it's a valid parseable string.\n        // If it is, then stringify it again.\n        parser(val)\n        return stringify(val)\n      } catch (_err) {\n        // silent\n      }\n    }\n    return val\n  }\n\n  return (search: Record<string, any>) => {\n    const searchStr = encode(search, stringifyValue)\n    return searchStr ? `?${searchStr}` : ''\n  }\n}\n\nexport type SearchSerializer = (searchObj: Record<string, any>) => string\nexport type SearchParser = (searchStr: string) => Record<string, any>\n"],"names":[],"mappings":";AAGO,MAAM,qBAAqB,gBAAgB,KAAK,KAAK;AACrD,MAAM,yBAAyB;AAAA,EACpC,KAAK;AAAA,EACL,KAAK;AACP;AAEO,SAAS,gBAAgB,QAA8B;AAC5D,SAAO,CAAC,cAAiC;AACvC,QAAI,UAAU,CAAC,MAAM,KAAK;AACxB,kBAAY,UAAU,UAAU,CAAC;AAAA,IACnC;AAEA,UAAM,QAAiC,OAAO,SAAS;AAGvD,eAAW,OAAO,OAAO;AACvB,YAAM,QAAQ,MAAM,GAAG;AACvB,UAAI,OAAO,UAAU,UAAU;AAC7B,YAAI;AACF,gBAAM,GAAG,IAAI,OAAO,KAAK;AAAA,QAC3B,SAAS,MAAM;AAAA,QAEf;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AACF;AAEO,SAAS,oBACd,WACA,QACA;AACA,QAAM,YAAY,OAAO,WAAW;AACpC,WAAS,eAAe,KAAU;AAChC,QAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM;AAC3C,UAAI;AACF,eAAO,UAAU,GAAG;AAAA,MACtB,SAAS,MAAM;AAAA,MAEf;AAAA,IACF,WAAW,aAAa,OAAO,QAAQ,UAAU;AAC/C,UAAI;AAGF,eAAO,GAAG;AACV,eAAO,UAAU,GAAG;AAAA,MACtB,SAAS,MAAM;AAAA,MAEf;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,SAAO,CAAC,WAAgC;AACtC,UAAM,YAAY,OAAO,QAAQ,cAAc;AAC/C,WAAO,YAAY,IAAI,SAAS,KAAK;AAAA,EACvC;AACF;"}
+{"version":3,"file":"searchParams.js","sources":["../../src/searchParams.ts"],"sourcesContent":["import { decode, encode } from './qss'\nimport type { AnySchema } from './validators'\n\nexport const defaultParseSearch = parseSearchWith(JSON.parse)\nexport const defaultStringifySearch = stringifySearchWith(\n  JSON.stringify,\n  JSON.parse,\n)\n\n/**\n * Build a `parseSearch` function using a provided JSON-like parser.\n *\n * The returned function strips a leading `?`, decodes values, and attempts to\n * JSON-parse string values using the given `parser`.\n *\n * @param parser Function to parse a string value (e.g. `JSON.parse`).\n * @returns A `parseSearch` function compatible with `Router` options.\n * @link https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization\n */\nexport function parseSearchWith(parser: (str: string) => any) {\n  return (searchStr: string): AnySchema => {\n    if (searchStr[0] === '?') {\n      searchStr = searchStr.substring(1)\n    }\n\n    const query: Record<string, unknown> = decode(searchStr)\n\n    // Try to parse any query params that might be json\n    for (const key in query) {\n      const value = query[key]\n      if (typeof value === 'string') {\n        try {\n          query[key] = parser(value)\n        } catch (_err) {\n          // silent\n        }\n      }\n    }\n\n    return query\n  }\n}\n\n/**\n * Build a `stringifySearch` function using a provided serializer.\n *\n * Non-primitive values are serialized with `stringify`. If a `parser` is\n * supplied, string values that are parseable are re-serialized to ensure\n * symmetry with `parseSearch`.\n *\n * @param stringify Function to serialize a value (e.g. `JSON.stringify`).\n * @param parser Optional parser to detect parseable strings.\n * @returns A `stringifySearch` function compatible with `Router` options.\n * @link https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization\n */\nexport function stringifySearchWith(\n  stringify: (search: any) => string,\n  parser?: (str: string) => any,\n) {\n  const hasParser = typeof parser === 'function'\n  function stringifyValue(val: any) {\n    if (typeof val === 'object' && val !== null) {\n      try {\n        return stringify(val)\n      } catch (_err) {\n        // silent\n      }\n    } else if (hasParser && typeof val === 'string') {\n      try {\n        // Check if it's a valid parseable string.\n        // If it is, then stringify it again.\n        parser(val)\n        return stringify(val)\n      } catch (_err) {\n        // silent\n      }\n    }\n    return val\n  }\n\n  return (search: Record<string, any>) => {\n    const searchStr = encode(search, stringifyValue)\n    return searchStr ? `?${searchStr}` : ''\n  }\n}\n\nexport type SearchSerializer = (searchObj: Record<string, any>) => string\nexport type SearchParser = (searchStr: string) => Record<string, any>\n"],"names":[],"mappings":";AAGO,MAAM,qBAAqB,gBAAgB,KAAK,KAAK;AACrD,MAAM,yBAAyB;AAAA,EACpC,KAAK;AAAA,EACL,KAAK;AACP;AAYO,SAAS,gBAAgB,QAA8B;AAC5D,SAAO,CAAC,cAAiC;AACvC,QAAI,UAAU,CAAC,MAAM,KAAK;AACxB,kBAAY,UAAU,UAAU,CAAC;AAAA,IACnC;AAEA,UAAM,QAAiC,OAAO,SAAS;AAGvD,eAAW,OAAO,OAAO;AACvB,YAAM,QAAQ,MAAM,GAAG;AACvB,UAAI,OAAO,UAAU,UAAU;AAC7B,YAAI;AACF,gBAAM,GAAG,IAAI,OAAO,KAAK;AAAA,QAC3B,SAAS,MAAM;AAAA,QAEf;AAAA,MACF;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AACF;AAcO,SAAS,oBACd,WACA,QACA;AACA,QAAM,YAAY,OAAO,WAAW;AACpC,WAAS,eAAe,KAAU;AAChC,QAAI,OAAO,QAAQ,YAAY,QAAQ,MAAM;AAC3C,UAAI;AACF,eAAO,UAAU,GAAG;AAAA,MACtB,SAAS,MAAM;AAAA,MAEf;AAAA,IACF,WAAW,aAAa,OAAO,QAAQ,UAAU;AAC/C,UAAI;AAGF,eAAO,GAAG;AACV,eAAO,UAAU,GAAG;AAAA,MACtB,SAAS,MAAM;AAAA,MAEf;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,SAAO,CAAC,WAAgC;AACtC,UAAM,YAAY,OAAO,QAAQ,cAAc;AAC/C,WAAO,YAAY,IAAI,SAAS,KAAK;AAAA,EACvC;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/router-core",
-  "version": "1.133.13",
+  "version": "1.133.18",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",

package/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?: {

package/src/load-matches.ts

@@ -673,6 +673,10 @@ const runLoader = async (
       const pendingPromise = match._nonReactive.minPendingPromise
       if (pendingPromise) await pendingPromise
 
+      if (isNotFound(e)) {
+        await (route.options.notFoundComponent as any)?.preload?.()
+      }
+
       handleRedirectAndNotFound(inner, inner.router.getMatch(matchId), e)
 
       try {

package/src/not-found.ts

@@ -18,12 +18,24 @@ export type NotFoundError = {
   headers?: HeadersInit
 }
 
+/**
+ * Create a not-found error object recognized by TanStack Router.
+ *
+ * Throw this from loaders/actions to trigger the nearest `notFoundComponent`.
+ * Use `routeId` to target a specific route's not-found boundary. If `throw`
+ * is true, the error is thrown instead of returned.
+ *
+ * @param options Optional settings including `routeId`, `headers`, and `throw`.
+ * @returns A not-found error object that can be thrown or returned.
+ * @link https://tanstack.com/router/latest/docs/router/framework/react/api/router/notFoundFunction
+ */
 export function notFound(options: NotFoundError = {}) {
   ;(options as any).isNotFound = true
   if (options.throw) throw options
   return options
 }
 
+/** Determine if a value is a TanStack Router not-found error. */
 export function isNotFound(obj: any): obj is NotFoundError {
   return !!obj?.isNotFound
 }

package/src/redirect.ts

@@ -54,6 +54,23 @@ export type ResolvedRedirect<
   TMaskTo extends string = '',
 > = Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>
 
+/**
+ * Create a redirect Response understood by TanStack Router.
+ *
+ * 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. 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
+ */
 export function redirect<
   TRouter extends AnyRouter = RegisteredRouter,
   const TTo extends string | undefined = '.',
@@ -92,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
 }

package/src/router.ts

@@ -2135,10 +2135,16 @@ export class RouterCore<
       await this.latestLoadPromise
     }
 
+    let newStatusCode: number | undefined = undefined
     if (this.hasNotFoundMatch()) {
+      newStatusCode = 404
+    } else if (this.__store.state.matches.some((d) => d.status === 'error')) {
+      newStatusCode = 500
+    }
+    if (newStatusCode !== undefined) {
       this.__store.setState((s) => ({
         ...s,
-        statusCode: 404,
+        statusCode: newStatusCode,
       }))
     }
   }

package/src/searchMiddleware.ts

@@ -3,6 +3,16 @@ import type { NoInfer, PickOptional } from './utils'
 import type { SearchMiddleware } from './route'
 import type { IsRequiredParams } from './link'
 
+/**
+ * Retain specified search params across navigations.
+ *
+ * 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,
 ): SearchMiddleware<TSearchSchema> {
@@ -21,6 +31,16 @@ export function retainSearchParams<TSearchSchema extends object>(
   }
 }
 
+/**
+ * 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.
+ *
+ * @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,
   TOptionalProps = PickOptional<NoInfer<TSearchSchema>>,

package/src/searchParams.ts

@@ -7,6 +7,16 @@ export const defaultStringifySearch = stringifySearchWith(
   JSON.parse,
 )
 
+/**
+ * Build a `parseSearch` function using a provided JSON-like parser.
+ *
+ * The returned function strips a leading `?`, decodes values, and attempts to
+ * JSON-parse string values using the given `parser`.
+ *
+ * @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/framework/react/guide/custom-search-param-serialization
+ */
 export function parseSearchWith(parser: (str: string) => any) {
   return (searchStr: string): AnySchema => {
     if (searchStr[0] === '?') {
@@ -31,6 +41,18 @@ export function parseSearchWith(parser: (str: string) => any) {
   }
 }
 
+/**
+ * Build a `stringifySearch` function using a provided serializer.
+ *
+ * Non-primitive values are serialized with `stringify`. If a `parser` is
+ * supplied, string values that are parseable are re-serialized to ensure
+ * symmetry with `parseSearch`.
+ *
+ * @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/framework/react/guide/custom-search-param-serialization
+ */
 export function stringifySearchWith(
   stringify: (search: any) => string,
   parser?: (str: string) => any,