@tanstack/query-core 5.102.7 → 5.103.0

package/build/modern/streamedQuery.d.cts

@@ -1,7 +1,14 @@
-import { Ct as QueryKey, St as QueryFunctionContext, xt as QueryFunction } from "./hydration-DWGr3cFC.cjs";
+import { Ct as QueryKey, St as QueryFunctionContext, xt as QueryFunction } from "./hydration-DwR10Hi-.cjs";
 //#region src/streamedQuery.d.ts
 type BaseStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = {
+  /** The function that returns an `AsyncIterable` to stream data from. */
   streamFn: (context: QueryFunctionContext<TQueryKey>) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>;
+  /**
+   * Defines how refetches are handled.
+   * - `'reset'` (default): erases all data and puts the query back into `pending` state.
+   * - `'append'`: appends new data to the existing data.
+   * - `'replace'`: writes all data to the cache once the stream ends.
+   */
   refetchMode?: 'append' | 'reset' | 'replace';
 };
 type SimpleStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
@@ -9,7 +16,15 @@ type SimpleStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = BaseS
   initialValue?: never;
 };
 type ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
+  /**
+   * Reduces streamed chunks into the final data shape. Required whenever `TData` is not an
+   * array, since there is no default way to accumulate non-array chunks.
+   */
   reducer: (acc: TData, chunk: TQueryFnData) => TData;
+  /**
+   * The value used while the first chunk is being fetched, and returned if the stream yields no
+   * values. Required together with a custom `reducer`.
+   */
   initialValue: TData;
 };
 type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = SimpleStreamedQueryParams<TQueryFnData, TQueryKey> | ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey>;
@@ -18,7 +33,7 @@ type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = Simp
  * Data will be an Array of all the chunks received.
  * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.
  * The query will stay in fetchStatus 'fetching' until the stream ends.
- * @param queryFn - The function that returns an AsyncIterable to stream data from.
+ * @param streamFn - The function that returns an AsyncIterable to stream data from.
  * @param refetchMode - Defines how re-fetches are handled.
  * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.
  * Set to `'append'` to append new data to the existing data.
@@ -26,6 +41,15 @@ type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = Simp
  * @param reducer - A function to reduce the streamed chunks into the final data.
  * Defaults to a function that appends chunks to the end of the array.
  * @param initialValue - Initial value to be used while the first chunk is being fetched, and returned if the stream yields no values.
+ * @example
+ * ```ts
+ * await queryClient.query({
+ *   queryKey: ['data'],
+ *   queryFn: streamedQuery({
+ *     streamFn: fetchDataInChunks,
+ *   }),
+ * })
+ * ```
  */
 declare function streamedQuery<TQueryFnData = unknown, TData = Array<TQueryFnData>, TQueryKey extends QueryKey = QueryKey>({ streamFn, refetchMode, reducer, initialValue }: StreamedQueryParams<TQueryFnData, TData, TQueryKey>): QueryFunction<TData, TQueryKey>;
 //#endregion

package/build/modern/streamedQuery.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"streamedQuery.d.cts","names":[],"sources":["../../src/streamedQuery.ts"],"mappings":";;KAQK,wBAAwB,cAAc,kBAAkB;EAC3D,WACE,SAAS,qBAAqB,eAC3B,cAAc,gBAAgB,QAAQ,cAAc;EACzD;;KAGG,0BACH,cACA,kBAAkB,YAChB,wBAAwB,cAAc;EACxC;EACA;;KAGG,6BACH,cACA,OACA,kBAAkB,YAChB,wBAAwB,cAAc;EACxC,UAAU,KAAK,OAAO,OAAO,iBAAiB;EAC9C,cAAc;;KAGX,oBAAoB,cAAc,OAAO,kBAAkB,YAC5D,0BAA0B,cAAc,aACxC,6BAA6B,cAAc,OAAO;;;;;;;;;;;;;;;iBAgBtC,cACd,wBACA,QAAQ,MAAM,eACd,kBAAkB,WAAW,YAE7B,UACA,aACA,SAEA,gBACC,oBAAoB,cAAc,OAAO,aAAa,cACvD,OACA"}
+{"version":3,"file":"streamedQuery.d.cts","names":[],"sources":["../../src/streamedQuery.ts"],"mappings":";;KAQK,wBAAwB,cAAc,kBAAkB;;EAE3D,WACE,SAAS,qBAAqB,eAC3B,cAAc,gBAAgB,QAAQ,cAAc;;;;;;;EAOzD;;KAGG,0BACH,cACA,kBAAkB,YAChB,wBAAwB,cAAc;EACxC;EACA;;KAGG,6BACH,cACA,OACA,kBAAkB,YAChB,wBAAwB,cAAc;;;;;EAKxC,UAAU,KAAK,OAAO,OAAO,iBAAiB;;;;;EAK9C,cAAc;;KAGX,oBAAoB,cAAc,OAAO,kBAAkB,YAC5D,0BAA0B,cAAc,aACxC,6BAA6B,cAAc,OAAO;;;;;;;;;;;;;;;;;;;;;;;;iBAyBtC,cACd,wBACA,QAAQ,MAAM,eACd,kBAAkB,WAAW,YAE7B,UACA,aACA,SAEA,gBACC,oBAAoB,cAAc,OAAO,aAAa,cACvD,OACA"}

package/build/modern/streamedQuery.d.ts

@@ -1,7 +1,14 @@
-import { Ct as QueryKey, St as QueryFunctionContext, xt as QueryFunction } from "./hydration-Bjs0MSgg.js";
+import { Ct as QueryKey, St as QueryFunctionContext, xt as QueryFunction } from "./hydration-Cq7QYAzB.js";
 //#region src/streamedQuery.d.ts
 type BaseStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = {
+  /** The function that returns an `AsyncIterable` to stream data from. */
   streamFn: (context: QueryFunctionContext<TQueryKey>) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>;
+  /**
+   * Defines how refetches are handled.
+   * - `'reset'` (default): erases all data and puts the query back into `pending` state.
+   * - `'append'`: appends new data to the existing data.
+   * - `'replace'`: writes all data to the cache once the stream ends.
+   */
   refetchMode?: 'append' | 'reset' | 'replace';
 };
 type SimpleStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
@@ -9,7 +16,15 @@ type SimpleStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = BaseS
   initialValue?: never;
 };
 type ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
+  /**
+   * Reduces streamed chunks into the final data shape. Required whenever `TData` is not an
+   * array, since there is no default way to accumulate non-array chunks.
+   */
   reducer: (acc: TData, chunk: TQueryFnData) => TData;
+  /**
+   * The value used while the first chunk is being fetched, and returned if the stream yields no
+   * values. Required together with a custom `reducer`.
+   */
   initialValue: TData;
 };
 type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = SimpleStreamedQueryParams<TQueryFnData, TQueryKey> | ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey>;
@@ -18,7 +33,7 @@ type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = Simp
  * Data will be an Array of all the chunks received.
  * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.
  * The query will stay in fetchStatus 'fetching' until the stream ends.
- * @param queryFn - The function that returns an AsyncIterable to stream data from.
+ * @param streamFn - The function that returns an AsyncIterable to stream data from.
  * @param refetchMode - Defines how re-fetches are handled.
  * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.
  * Set to `'append'` to append new data to the existing data.
@@ -26,6 +41,15 @@ type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> = Simp
  * @param reducer - A function to reduce the streamed chunks into the final data.
  * Defaults to a function that appends chunks to the end of the array.
  * @param initialValue - Initial value to be used while the first chunk is being fetched, and returned if the stream yields no values.
+ * @example
+ * ```ts
+ * await queryClient.query({
+ *   queryKey: ['data'],
+ *   queryFn: streamedQuery({
+ *     streamFn: fetchDataInChunks,
+ *   }),
+ * })
+ * ```
  */
 declare function streamedQuery<TQueryFnData = unknown, TData = Array<TQueryFnData>, TQueryKey extends QueryKey = QueryKey>({ streamFn, refetchMode, reducer, initialValue }: StreamedQueryParams<TQueryFnData, TData, TQueryKey>): QueryFunction<TData, TQueryKey>;
 //#endregion

package/build/modern/streamedQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streamedQuery.d.ts","names":[],"sources":["../../src/streamedQuery.ts"],"mappings":";;KAQK,wBAAwB,cAAc,kBAAkB;EAC3D,WACE,SAAS,qBAAqB,eAC3B,cAAc,gBAAgB,QAAQ,cAAc;EACzD;;KAGG,0BACH,cACA,kBAAkB,YAChB,wBAAwB,cAAc;EACxC;EACA;;KAGG,6BACH,cACA,OACA,kBAAkB,YAChB,wBAAwB,cAAc;EACxC,UAAU,KAAK,OAAO,OAAO,iBAAiB;EAC9C,cAAc;;KAGX,oBAAoB,cAAc,OAAO,kBAAkB,YAC5D,0BAA0B,cAAc,aACxC,6BAA6B,cAAc,OAAO;;;;;;;;;;;;;;;iBAgBtC,cACd,wBACA,QAAQ,MAAM,eACd,kBAAkB,WAAW,YAE7B,UACA,aACA,SAEA,gBACC,oBAAoB,cAAc,OAAO,aAAa,cACvD,OACA"}
+{"version":3,"file":"streamedQuery.d.ts","names":[],"sources":["../../src/streamedQuery.ts"],"mappings":";;KAQK,wBAAwB,cAAc,kBAAkB;;EAE3D,WACE,SAAS,qBAAqB,eAC3B,cAAc,gBAAgB,QAAQ,cAAc;;;;;;;EAOzD;;KAGG,0BACH,cACA,kBAAkB,YAChB,wBAAwB,cAAc;EACxC;EACA;;KAGG,6BACH,cACA,OACA,kBAAkB,YAChB,wBAAwB,cAAc;;;;;EAKxC,UAAU,KAAK,OAAO,OAAO,iBAAiB;;;;;EAK9C,cAAc;;KAGX,oBAAoB,cAAc,OAAO,kBAAkB,YAC5D,0BAA0B,cAAc,aACxC,6BAA6B,cAAc,OAAO;;;;;;;;;;;;;;;;;;;;;;;;iBAyBtC,cACd,wBACA,QAAQ,MAAM,eACd,kBAAkB,WAAW,YAE7B,UACA,aACA,SAEA,gBACC,oBAAoB,cAAc,OAAO,aAAa,cACvD,OACA"}

package/build/modern/streamedQuery.js

@@ -5,7 +5,7 @@ import { addConsumeAwareSignal, addToEnd } from "./utils.js";
 * Data will be an Array of all the chunks received.
 * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.
 * The query will stay in fetchStatus 'fetching' until the stream ends.
-* @param queryFn - The function that returns an AsyncIterable to stream data from.
+* @param streamFn - The function that returns an AsyncIterable to stream data from.
 * @param refetchMode - Defines how re-fetches are handled.
 * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.
 * Set to `'append'` to append new data to the existing data.
@@ -13,6 +13,15 @@ import { addConsumeAwareSignal, addToEnd } from "./utils.js";
 * @param reducer - A function to reduce the streamed chunks into the final data.
 * Defaults to a function that appends chunks to the end of the array.
 * @param initialValue - Initial value to be used while the first chunk is being fetched, and returned if the stream yields no values.
+* @example
+* ```ts
+* await queryClient.query({
+*   queryKey: ['data'],
+*   queryFn: streamedQuery({
+*     streamFn: fetchDataInChunks,
+*   }),
+* })
+* ```
 */
 function streamedQuery({ streamFn, refetchMode = "reset", reducer = (items, chunk) => addToEnd(items, chunk), initialValue = [] }) {
 	return async (context) => {

package/build/modern/streamedQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"streamedQuery.js","names":[],"sources":["../../src/streamedQuery.ts"],"sourcesContent":["import { addConsumeAwareSignal, addToEnd } from './utils'\nimport type {\n  OmitKeyof,\n  QueryFunction,\n  QueryFunctionContext,\n  QueryKey,\n} from './types'\n\ntype BaseStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = {\n  streamFn: (\n    context: QueryFunctionContext<TQueryKey>,\n  ) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>\n  refetchMode?: 'append' | 'reset' | 'replace'\n}\n\ntype SimpleStreamedQueryParams<\n  TQueryFnData,\n  TQueryKey extends QueryKey,\n> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {\n  reducer?: never\n  initialValue?: never\n}\n\ntype ReducibleStreamedQueryParams<\n  TQueryFnData,\n  TData,\n  TQueryKey extends QueryKey,\n> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {\n  reducer: (acc: TData, chunk: TQueryFnData) => TData\n  initialValue: TData\n}\n\ntype StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> =\n  | SimpleStreamedQueryParams<TQueryFnData, TQueryKey>\n  | ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey>\n\n/**\n * This is a helper function to create a query function that streams data from an AsyncIterable.\n * Data will be an Array of all the chunks received.\n * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.\n * The query will stay in fetchStatus 'fetching' until the stream ends.\n * @param queryFn - The function that returns an AsyncIterable to stream data from.\n * @param refetchMode - Defines how re-fetches are handled.\n * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.\n * Set to `'append'` to append new data to the existing data.\n * Set to `'replace'` to write all data to the cache once the stream ends.\n * @param reducer - A function to reduce the streamed chunks into the final data.\n * Defaults to a function that appends chunks to the end of the array.\n * @param initialValue - Initial value to be used while the first chunk is being fetched, and returned if the stream yields no values.\n */\nexport function streamedQuery<\n  TQueryFnData = unknown,\n  TData = Array<TQueryFnData>,\n  TQueryKey extends QueryKey = QueryKey,\n>({\n  streamFn,\n  refetchMode = 'reset',\n  reducer = (items, chunk) =>\n    addToEnd(items as Array<TQueryFnData>, chunk) as TData,\n  initialValue = [] as TData,\n}: StreamedQueryParams<TQueryFnData, TData, TQueryKey>): QueryFunction<\n  TData,\n  TQueryKey\n> {\n  return async (context) => {\n    const query = context.client\n      .getQueryCache()\n      .find({ queryKey: context.queryKey, exact: true })\n    const isRefetch = !!query && query.isFetched()\n    if (isRefetch && refetchMode === 'reset') {\n      query.setState({\n        ...query.resetState,\n        fetchStatus: 'fetching',\n      })\n    }\n\n    let result = initialValue\n\n    let cancelled: boolean = false as boolean\n    const streamFnContext = addConsumeAwareSignal<\n      OmitKeyof<typeof context, 'signal'>\n    >(\n      {\n        client: context.client,\n        meta: context.meta,\n        queryKey: context.queryKey,\n        pageParam: context.pageParam,\n        direction: context.direction,\n      },\n      () => context.signal,\n      () => (cancelled = true),\n    )\n\n    const stream = await streamFn(streamFnContext)\n\n    const isReplaceRefetch = isRefetch && refetchMode === 'replace'\n\n    for await (const chunk of stream) {\n      if (cancelled) {\n        break\n      }\n\n      if (isReplaceRefetch) {\n        // don't append to the cache directly when replace-refetching\n        result = reducer(result, chunk)\n      } else {\n        context.client.setQueryData<TData>(context.queryKey, (prev) =>\n          reducer(prev === undefined ? initialValue : prev, chunk),\n        )\n      }\n    }\n\n    // finalize result: replace-refetching needs to write to the cache\n    if (isReplaceRefetch && !cancelled) {\n      context.client.setQueryData<TData>(context.queryKey, result)\n    }\n\n    return context.client.getQueryData(context.queryKey) ?? initialValue\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkDA,SAAgB,cAId,EACA,UACA,cAAc,SACd,WAAW,OAAO,UAChB,SAAS,OAA8B,KAAK,GAC9C,eAAe,CAAC,KAIhB;CACA,OAAO,OAAO,YAAY;EACxB,MAAM,QAAQ,QAAQ,OACnB,cAAc,CAAC,CACf,KAAK;GAAE,UAAU,QAAQ;GAAU,OAAO;EAAK,CAAC;EACnD,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,UAAU;EAC7C,IAAI,aAAa,gBAAgB,SAC/B,MAAM,SAAS;GACb,GAAG,MAAM;GACT,aAAa;EACf,CAAC;EAGH,IAAI,SAAS;EAEb,IAAI,YAAqB;EAezB,MAAM,SAAS,MAAM,SAdG,sBAGtB;GACE,QAAQ,QAAQ;GAChB,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,WAAW,QAAQ;GACnB,WAAW,QAAQ;EACrB,SACM,QAAQ,cACP,YAAY,IAGuB,CAAC;EAE7C,MAAM,mBAAmB,aAAa,gBAAgB;EAEtD,WAAW,MAAM,SAAS,QAAQ;GAChC,IAAI,WACF;GAGF,IAAI,kBAEF,SAAS,QAAQ,QAAQ,KAAK;QAE9B,QAAQ,OAAO,aAAoB,QAAQ,WAAW,SACpD,QAAQ,SAAS,KAAA,IAAY,eAAe,MAAM,KAAK,CACzD;EAEJ;EAGA,IAAI,oBAAoB,CAAC,WACvB,QAAQ,OAAO,aAAoB,QAAQ,UAAU,MAAM;EAG7D,OAAO,QAAQ,OAAO,aAAa,QAAQ,QAAQ,KAAK;CAC1D;AACF"}
+{"version":3,"file":"streamedQuery.js","names":[],"sources":["../../src/streamedQuery.ts"],"sourcesContent":["import { addConsumeAwareSignal, addToEnd } from './utils'\nimport type {\n  OmitKeyof,\n  QueryFunction,\n  QueryFunctionContext,\n  QueryKey,\n} from './types'\n\ntype BaseStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = {\n  /** The function that returns an `AsyncIterable` to stream data from. */\n  streamFn: (\n    context: QueryFunctionContext<TQueryKey>,\n  ) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>\n  /**\n   * Defines how refetches are handled.\n   * - `'reset'` (default): erases all data and puts the query back into `pending` state.\n   * - `'append'`: appends new data to the existing data.\n   * - `'replace'`: writes all data to the cache once the stream ends.\n   */\n  refetchMode?: 'append' | 'reset' | 'replace'\n}\n\ntype SimpleStreamedQueryParams<\n  TQueryFnData,\n  TQueryKey extends QueryKey,\n> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {\n  reducer?: never\n  initialValue?: never\n}\n\ntype ReducibleStreamedQueryParams<\n  TQueryFnData,\n  TData,\n  TQueryKey extends QueryKey,\n> = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {\n  /**\n   * Reduces streamed chunks into the final data shape. Required whenever `TData` is not an\n   * array, since there is no default way to accumulate non-array chunks.\n   */\n  reducer: (acc: TData, chunk: TQueryFnData) => TData\n  /**\n   * The value used while the first chunk is being fetched, and returned if the stream yields no\n   * values. Required together with a custom `reducer`.\n   */\n  initialValue: TData\n}\n\ntype StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> =\n  | SimpleStreamedQueryParams<TQueryFnData, TQueryKey>\n  | ReducibleStreamedQueryParams<TQueryFnData, TData, TQueryKey>\n\n/**\n * This is a helper function to create a query function that streams data from an AsyncIterable.\n * Data will be an Array of all the chunks received.\n * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.\n * The query will stay in fetchStatus 'fetching' until the stream ends.\n * @param streamFn - The function that returns an AsyncIterable to stream data from.\n * @param refetchMode - Defines how re-fetches are handled.\n * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.\n * Set to `'append'` to append new data to the existing data.\n * Set to `'replace'` to write all data to the cache once the stream ends.\n * @param reducer - A function to reduce the streamed chunks into the final data.\n * Defaults to a function that appends chunks to the end of the array.\n * @param initialValue - Initial value to be used while the first chunk is being fetched, and returned if the stream yields no values.\n * @example\n * ```ts\n * await queryClient.query({\n *   queryKey: ['data'],\n *   queryFn: streamedQuery({\n *     streamFn: fetchDataInChunks,\n *   }),\n * })\n * ```\n */\nexport function streamedQuery<\n  TQueryFnData = unknown,\n  TData = Array<TQueryFnData>,\n  TQueryKey extends QueryKey = QueryKey,\n>({\n  streamFn,\n  refetchMode = 'reset',\n  reducer = (items, chunk) =>\n    addToEnd(items as Array<TQueryFnData>, chunk) as TData,\n  initialValue = [] as TData,\n}: StreamedQueryParams<TQueryFnData, TData, TQueryKey>): QueryFunction<\n  TData,\n  TQueryKey\n> {\n  return async (context) => {\n    const query = context.client\n      .getQueryCache()\n      .find({ queryKey: context.queryKey, exact: true })\n    const isRefetch = !!query && query.isFetched()\n    if (isRefetch && refetchMode === 'reset') {\n      query.setState({\n        ...query.resetState,\n        fetchStatus: 'fetching',\n      })\n    }\n\n    let result = initialValue\n\n    let cancelled: boolean = false as boolean\n    const streamFnContext = addConsumeAwareSignal<\n      OmitKeyof<typeof context, 'signal'>\n    >(\n      {\n        client: context.client,\n        meta: context.meta,\n        queryKey: context.queryKey,\n        pageParam: context.pageParam,\n        direction: context.direction,\n      },\n      () => context.signal,\n      () => (cancelled = true),\n    )\n\n    const stream = await streamFn(streamFnContext)\n\n    const isReplaceRefetch = isRefetch && refetchMode === 'replace'\n\n    for await (const chunk of stream) {\n      if (cancelled) {\n        break\n      }\n\n      if (isReplaceRefetch) {\n        // don't append to the cache directly when replace-refetching\n        result = reducer(result, chunk)\n      } else {\n        context.client.setQueryData<TData>(context.queryKey, (prev) =>\n          reducer(prev === undefined ? initialValue : prev, chunk),\n        )\n      }\n    }\n\n    // finalize result: replace-refetching needs to write to the cache\n    if (isReplaceRefetch && !cancelled) {\n      context.client.setQueryData<TData>(context.queryKey, result)\n    }\n\n    return context.client.getQueryData(context.queryKey) ?? initialValue\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,cAId,EACA,UACA,cAAc,SACd,WAAW,OAAO,UAChB,SAAS,OAA8B,KAAK,GAC9C,eAAe,CAAC,KAIhB;CACA,OAAO,OAAO,YAAY;EACxB,MAAM,QAAQ,QAAQ,OACnB,cAAc,CAAC,CACf,KAAK;GAAE,UAAU,QAAQ;GAAU,OAAO;EAAK,CAAC;EACnD,MAAM,YAAY,CAAC,CAAC,SAAS,MAAM,UAAU;EAC7C,IAAI,aAAa,gBAAgB,SAC/B,MAAM,SAAS;GACb,GAAG,MAAM;GACT,aAAa;EACf,CAAC;EAGH,IAAI,SAAS;EAEb,IAAI,YAAqB;EAezB,MAAM,SAAS,MAAM,SAdG,sBAGtB;GACE,QAAQ,QAAQ;GAChB,MAAM,QAAQ;GACd,UAAU,QAAQ;GAClB,WAAW,QAAQ;GACnB,WAAW,QAAQ;EACrB,SACM,QAAQ,cACP,YAAY,IAGuB,CAAC;EAE7C,MAAM,mBAAmB,aAAa,gBAAgB;EAEtD,WAAW,MAAM,SAAS,QAAQ;GAChC,IAAI,WACF;GAGF,IAAI,kBAEF,SAAS,QAAQ,QAAQ,KAAK;QAE9B,QAAQ,OAAO,aAAoB,QAAQ,WAAW,SACpD,QAAQ,SAAS,KAAA,IAAY,eAAe,MAAM,KAAK,CACzD;EAEJ;EAGA,IAAI,oBAAoB,CAAC,WACvB,QAAQ,OAAO,aAAoB,QAAQ,UAAU,MAAM;EAG7D,OAAO,QAAQ,OAAO,aAAa,QAAQ,QAAQ,KAAK;CAC1D;AACF"}

package/build/modern/timeoutManager.cjs

@@ -20,6 +20,31 @@ const defaultTimeoutProvider = {
 var TimeoutManager = class {
 	#provider = defaultTimeoutProvider;
 	#providerCalled = false;
+	/**
+	* `setTimeoutProvider` can be used to set a custom implementation of the
+	* `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` functions,
+	* called a `TimeoutProvider`.
+	*
+	* This may be useful if you notice event loop performance issues with
+	* thousands of queries. A custom TimeoutProvider could also support timer
+	* delays longer than the global `setTimeout` maximum delay value of about
+	* 24 days.
+	*
+	* It is important to call `setTimeoutProvider` before creating a
+	* QueryClient or queries, so that the same provider is used consistently
+	* for all timers in the application, since different TimeoutProviders
+	* cannot cancel each others' timers.
+	*
+	* @example
+	* ```ts
+	* import { timeoutManager, QueryClient } from '@tanstack/query-core'
+	* import { CustomTimeoutProvider } from './CustomTimeoutProvider'
+	*
+	* timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())
+	*
+	* export const queryClient = new QueryClient()
+	* ```
+	*/
 	setTimeoutProvider(provider) {
 		if (process.env.NODE_ENV !== "production") {
 			if (this.#providerCalled && provider !== this.#provider) console.error(`[timeoutManager]: Switching provider after calls to previous provider might result in unexpected behavior.`, {
@@ -30,21 +55,95 @@ var TimeoutManager = class {
 		this.#provider = provider;
 		if (process.env.NODE_ENV !== "production") this.#providerCalled = false;
 	}
+	/**
+	* `setTimeout` schedules a callback to run after approximately `delay`
+	* milliseconds, like the global `setTimeout` function. The callback can be
+	* canceled with `clearTimeout`.
+	*
+	* It returns a timer ID, which may be a number or an object that can be
+	* coerced to a number via `Symbol.toPrimitive`.
+	*
+	* @example
+	* ```ts
+	* import { timeoutManager } from '@tanstack/query-core'
+	*
+	* const timeoutId = timeoutManager.setTimeout(
+	*   () => console.log('ran at:', new Date()),
+	*   1000,
+	* )
+	*
+	* const timeoutIdNumber: number = Number(timeoutId)
+	* ```
+	*/
 	setTimeout(callback, delay) {
 		if (process.env.NODE_ENV !== "production") this.#providerCalled = true;
 		return this.#provider.setTimeout(callback, delay);
 	}
+	/**
+	* `clearTimeout` cancels a timeout callback scheduled with `setTimeout`,
+	* like the global `clearTimeout` function. It should be called with a
+	* timer ID returned by `setTimeout`.
+	*
+	* @example
+	* ```ts
+	* import { timeoutManager } from '@tanstack/query-core'
+	*
+	* const timeoutId = timeoutManager.setTimeout(
+	*   () => console.log('ran at:', new Date()),
+	*   1000,
+	* )
+	*
+	* timeoutManager.clearTimeout(timeoutId)
+	* ```
+	*/
 	clearTimeout(timeoutId) {
 		this.#provider.clearTimeout(timeoutId);
 	}
+	/**
+	* `setInterval` schedules a callback to be called approximately every
+	* `delay` milliseconds, like the global `setInterval` function.
+	*
+	* Like `setTimeout`, it returns a timer ID, which may be a number or an
+	* object that can be coerced to a number via `Symbol.toPrimitive`.
+	*
+	* @example
+	* ```ts
+	* import { timeoutManager } from '@tanstack/query-core'
+	*
+	* const intervalId = timeoutManager.setInterval(
+	*   () => console.log('ran at:', new Date()),
+	*   1000,
+	* )
+	* ```
+	*/
 	setInterval(callback, delay) {
 		if (process.env.NODE_ENV !== "production") this.#providerCalled = true;
 		return this.#provider.setInterval(callback, delay);
 	}
+	/**
+	* `clearInterval` can be used to cancel an interval, like the global
+	* `clearInterval` function. It should be called with an interval ID
+	* returned by `setInterval`.
+	*
+	* @example
+	* ```ts
+	* import { timeoutManager } from '@tanstack/query-core'
+	*
+	* const intervalId = timeoutManager.setInterval(
+	*   () => console.log('ran at:', new Date()),
+	*   1000,
+	* )
+	*
+	* timeoutManager.clearInterval(intervalId)
+	* ```
+	*/
 	clearInterval(intervalId) {
 		this.#provider.clearInterval(intervalId);
 	}
 };
+/**
+* Singleton instance of {@link TimeoutManager}, used throughout TanStack Query to schedule and cancel timers.
+*/
 const timeoutManager = new TimeoutManager();
 /**
 * In many cases code wants to delay to the next event loop tick; this is not

package/build/modern/timeoutManager.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"timeoutManager.cjs","names":["#providerCalled","#provider"],"sources":["../../src/timeoutManager.ts"],"sourcesContent":["/**\n * {@link TimeoutManager} does not support passing arguments to the callback.\n *\n * `(_: void)` is the argument type inferred by TypeScript's default typings for\n * `setTimeout(cb, number)`.\n * If we don't accept a single void argument, then\n * `new Promise(resolve => timeoutManager.setTimeout(resolve, N))` is a type error.\n */\nexport type TimeoutCallback = (_: void) => void\n\n/**\n * Wrapping `setTimeout` is awkward from a typing perspective because platform\n * typings may extend the return type of `setTimeout`. For example, NodeJS\n * typings add `NodeJS.Timeout`; but a non-default `timeoutManager` may not be\n * able to return such a type.\n */\nexport type ManagedTimerId = number | { [Symbol.toPrimitive]: () => number }\n\n/**\n * Backend for timer functions.\n */\nexport type TimeoutProvider<TTimerId extends ManagedTimerId = ManagedTimerId> =\n  {\n    readonly setTimeout: (callback: TimeoutCallback, delay: number) => TTimerId\n    readonly clearTimeout: (timeoutId: TTimerId | undefined) => void\n\n    readonly setInterval: (callback: TimeoutCallback, delay: number) => TTimerId\n    readonly clearInterval: (intervalId: TTimerId | undefined) => void\n  }\n\ntype SystemTimerId = ReturnType<typeof setTimeout>\n\nexport const defaultTimeoutProvider: TimeoutProvider = {\n  // We need the wrapper function syntax below instead of direct references to\n  // global setTimeout etc.\n  //\n  // BAD: `setTimeout: setTimeout`\n  // GOOD: `setTimeout: (cb, delay) => setTimeout(cb, delay)`\n  //\n  // If we use direct references here, then anything that wants to spy on or\n  // replace the global setTimeout (like tests) won't work since we'll already\n  // have a hard reference to the original implementation at the time when this\n  // file was imported.\n  setTimeout: (callback, delay) => setTimeout(callback, delay),\n  clearTimeout: (timeoutId) =>\n    clearTimeout(timeoutId as SystemTimerId | undefined),\n\n  setInterval: (callback, delay) => setInterval(callback, delay),\n  clearInterval: (intervalId) =>\n    clearInterval(intervalId as SystemTimerId | undefined),\n}\n\n/**\n * Allows customization of how timeouts are created.\n *\n * @tanstack/query-core makes liberal use of timeouts to implement `staleTime`\n * and `gcTime`. The default TimeoutManager provider uses the platform's global\n * `setTimeout` implementation, which is known to have scalability issues with\n * thousands of timeouts on the event loop.\n *\n * If you hit this limitation, consider providing a custom TimeoutProvider that\n * coalesces timeouts.\n */\nexport class TimeoutManager implements Omit<TimeoutProvider, 'name'> {\n  // We cannot have TimeoutManager<T> as we must instantiate it with a concrete\n  // type at app boot; and if we leave that type, then any new timer provider\n  // would need to support the default provider's concrete timer ID, which is\n  // infeasible across environments.\n  //\n  // We settle for type safety for the TimeoutProvider type, and accept that\n  // this class is unsafe internally to allow for extension.\n  #provider: TimeoutProvider<any> = defaultTimeoutProvider\n  #providerCalled = false\n\n  setTimeoutProvider<TTimerId extends ManagedTimerId>(\n    provider: TimeoutProvider<TTimerId>,\n  ): void {\n    if (process.env.NODE_ENV !== 'production') {\n      if (this.#providerCalled && provider !== this.#provider) {\n        // After changing providers, `clearTimeout` will not work as expected for\n        // timeouts from the previous provider.\n        //\n        // Since they may allocate the same timeout ID, clearTimeout may cancel an\n        // arbitrary different timeout, or unexpected no-op.\n        //\n        // We could protect against this by mixing the timeout ID bits\n        // deterministically with some per-provider bits.\n        //\n        // We could internally queue `setTimeout` calls to `TimeoutManager` until\n        // some API call to set the initial provider.\n        console.error(\n          `[timeoutManager]: Switching provider after calls to previous provider might result in unexpected behavior.`,\n          { previous: this.#provider, provider },\n        )\n      }\n    }\n\n    this.#provider = provider\n    if (process.env.NODE_ENV !== 'production') {\n      this.#providerCalled = false\n    }\n  }\n\n  setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId {\n    if (process.env.NODE_ENV !== 'production') {\n      this.#providerCalled = true\n    }\n    return this.#provider.setTimeout(callback, delay)\n  }\n\n  clearTimeout(timeoutId: ManagedTimerId | undefined): void {\n    this.#provider.clearTimeout(timeoutId)\n  }\n\n  setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId {\n    if (process.env.NODE_ENV !== 'production') {\n      this.#providerCalled = true\n    }\n    return this.#provider.setInterval(callback, delay)\n  }\n\n  clearInterval(intervalId: ManagedTimerId | undefined): void {\n    this.#provider.clearInterval(intervalId)\n  }\n}\n\nexport const timeoutManager = new TimeoutManager()\n\n/**\n * In many cases code wants to delay to the next event loop tick; this is not\n * mediated by {@link timeoutManager}.\n *\n * This function is provided to make auditing the `tanstack/query-core` for\n * incorrect use of system `setTimeout` easier.\n */\nexport function systemSetTimeoutZero(callback: TimeoutCallback): void {\n  setTimeout(callback, 0)\n}\n"],"mappings":";;AAgCA,MAAa,yBAA0C;CAWrD,aAAa,UAAU,UAAU,WAAW,UAAU,KAAK;CAC3D,eAAe,cACb,aAAa,SAAsC;CAErD,cAAc,UAAU,UAAU,YAAY,UAAU,KAAK;CAC7D,gBAAgB,eACd,cAAc,UAAuC;AACzD;;;;;;;;;;;;AAaA,IAAa,iBAAb,MAAqE;CAQnE,YAAkC;CAClC,kBAAkB;CAElB,mBACE,UACM;EACN,IAAI,QAAQ,IAAI,aAAa,cACvB;OAAA,KAAKA,mBAAmB,aAAa,KAAKC,WAY5C,QAAQ,MACN,8GACA;IAAE,UAAU,KAAKA;IAAW;GAAS,CACvC;EAAA;EAIJ,KAAKA,YAAY;EACjB,IAAI,QAAQ,IAAI,aAAa,cAC3B,KAAKD,kBAAkB;CAE3B;CAEA,WAAW,UAA2B,OAA+B;EACnE,IAAI,QAAQ,IAAI,aAAa,cAC3B,KAAKA,kBAAkB;EAEzB,OAAO,KAAKC,UAAU,WAAW,UAAU,KAAK;CAClD;CAEA,aAAa,WAA6C;EACxD,KAAKA,UAAU,aAAa,SAAS;CACvC;CAEA,YAAY,UAA2B,OAA+B;EACpE,IAAI,QAAQ,IAAI,aAAa,cAC3B,KAAKD,kBAAkB;EAEzB,OAAO,KAAKC,UAAU,YAAY,UAAU,KAAK;CACnD;CAEA,cAAc,YAA8C;EAC1D,KAAKA,UAAU,cAAc,UAAU;CACzC;AACF;AAEA,MAAa,iBAAiB,IAAI,eAAe;;;;;;;;AASjD,SAAgB,qBAAqB,UAAiC;CACpE,WAAW,UAAU,CAAC;AACxB"}
+{"version":3,"file":"timeoutManager.cjs","names":["#providerCalled","#provider"],"sources":["../../src/timeoutManager.ts"],"sourcesContent":["/**\n * {@link TimeoutManager} does not support passing arguments to the callback.\n *\n * `(_: void)` is the argument type inferred by TypeScript's default typings for\n * `setTimeout(cb, number)`.\n * If we don't accept a single void argument, then\n * `new Promise(resolve => timeoutManager.setTimeout(resolve, N))` is a type error.\n */\nexport type TimeoutCallback = (_: void) => void\n\n/**\n * Wrapping `setTimeout` is awkward from a typing perspective because platform\n * typings may extend the return type of `setTimeout`. For example, NodeJS\n * typings add `NodeJS.Timeout`; but a non-default `timeoutManager` may not be\n * able to return such a type.\n */\nexport type ManagedTimerId = number | { [Symbol.toPrimitive]: () => number }\n\n/**\n * Backend for timer functions.\n *\n * Timers are performance-sensitive: short-lived timers (delays under a few seconds) tend to be\n * latency-sensitive, while long-lived ones may benefit more from coalescing — batching timers\n * with similar deadlines together — which the default provider (backed by the platform's global\n * `setTimeout`/`setInterval`) does not do. A custom provider can implement coalescing, and can\n * also support delays longer than the ~24-day maximum of the global `setTimeout`.\n */\nexport type TimeoutProvider<TTimerId extends ManagedTimerId = ManagedTimerId> =\n  {\n    readonly setTimeout: (callback: TimeoutCallback, delay: number) => TTimerId\n    readonly clearTimeout: (timeoutId: TTimerId | undefined) => void\n\n    readonly setInterval: (callback: TimeoutCallback, delay: number) => TTimerId\n    readonly clearInterval: (intervalId: TTimerId | undefined) => void\n  }\n\ntype SystemTimerId = ReturnType<typeof setTimeout>\n\nexport const defaultTimeoutProvider: TimeoutProvider = {\n  // We need the wrapper function syntax below instead of direct references to\n  // global setTimeout etc.\n  //\n  // BAD: `setTimeout: setTimeout`\n  // GOOD: `setTimeout: (cb, delay) => setTimeout(cb, delay)`\n  //\n  // If we use direct references here, then anything that wants to spy on or\n  // replace the global setTimeout (like tests) won't work since we'll already\n  // have a hard reference to the original implementation at the time when this\n  // file was imported.\n  setTimeout: (callback, delay) => setTimeout(callback, delay),\n  clearTimeout: (timeoutId) =>\n    clearTimeout(timeoutId as SystemTimerId | undefined),\n\n  setInterval: (callback, delay) => setInterval(callback, delay),\n  clearInterval: (intervalId) =>\n    clearInterval(intervalId as SystemTimerId | undefined),\n}\n\n/**\n * Allows customization of how timeouts are created.\n *\n * @tanstack/query-core makes liberal use of timeouts to implement `staleTime`\n * and `gcTime`. The default TimeoutManager provider uses the platform's global\n * `setTimeout` implementation, which is known to have scalability issues with\n * thousands of timeouts on the event loop.\n *\n * If you hit this limitation, consider providing a custom TimeoutProvider that\n * coalesces timeouts.\n */\nexport class TimeoutManager implements Omit<TimeoutProvider, 'name'> {\n  // We cannot have TimeoutManager<T> as we must instantiate it with a concrete\n  // type at app boot; and if we leave that type, then any new timer provider\n  // would need to support the default provider's concrete timer ID, which is\n  // infeasible across environments.\n  //\n  // We settle for type safety for the TimeoutProvider type, and accept that\n  // this class is unsafe internally to allow for extension.\n  #provider: TimeoutProvider<any> = defaultTimeoutProvider\n  #providerCalled = false\n\n  /**\n   * `setTimeoutProvider` can be used to set a custom implementation of the\n   * `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` functions,\n   * called a `TimeoutProvider`.\n   *\n   * This may be useful if you notice event loop performance issues with\n   * thousands of queries. A custom TimeoutProvider could also support timer\n   * delays longer than the global `setTimeout` maximum delay value of about\n   * 24 days.\n   *\n   * It is important to call `setTimeoutProvider` before creating a\n   * QueryClient or queries, so that the same provider is used consistently\n   * for all timers in the application, since different TimeoutProviders\n   * cannot cancel each others' timers.\n   *\n   * @example\n   * ```ts\n   * import { timeoutManager, QueryClient } from '@tanstack/query-core'\n   * import { CustomTimeoutProvider } from './CustomTimeoutProvider'\n   *\n   * timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())\n   *\n   * export const queryClient = new QueryClient()\n   * ```\n   */\n  setTimeoutProvider<TTimerId extends ManagedTimerId>(\n    provider: TimeoutProvider<TTimerId>,\n  ): void {\n    if (process.env.NODE_ENV !== 'production') {\n      if (this.#providerCalled && provider !== this.#provider) {\n        // After changing providers, `clearTimeout` will not work as expected for\n        // timeouts from the previous provider.\n        //\n        // Since they may allocate the same timeout ID, clearTimeout may cancel an\n        // arbitrary different timeout, or unexpected no-op.\n        //\n        // We could protect against this by mixing the timeout ID bits\n        // deterministically with some per-provider bits.\n        //\n        // We could internally queue `setTimeout` calls to `TimeoutManager` until\n        // some API call to set the initial provider.\n        console.error(\n          `[timeoutManager]: Switching provider after calls to previous provider might result in unexpected behavior.`,\n          { previous: this.#provider, provider },\n        )\n      }\n    }\n\n    this.#provider = provider\n    if (process.env.NODE_ENV !== 'production') {\n      this.#providerCalled = false\n    }\n  }\n\n  /**\n   * `setTimeout` schedules a callback to run after approximately `delay`\n   * milliseconds, like the global `setTimeout` function. The callback can be\n   * canceled with `clearTimeout`.\n   *\n   * It returns a timer ID, which may be a number or an object that can be\n   * coerced to a number via `Symbol.toPrimitive`.\n   *\n   * @example\n   * ```ts\n   * import { timeoutManager } from '@tanstack/query-core'\n   *\n   * const timeoutId = timeoutManager.setTimeout(\n   *   () => console.log('ran at:', new Date()),\n   *   1000,\n   * )\n   *\n   * const timeoutIdNumber: number = Number(timeoutId)\n   * ```\n   */\n  setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId {\n    if (process.env.NODE_ENV !== 'production') {\n      this.#providerCalled = true\n    }\n    return this.#provider.setTimeout(callback, delay)\n  }\n\n  /**\n   * `clearTimeout` cancels a timeout callback scheduled with `setTimeout`,\n   * like the global `clearTimeout` function. It should be called with a\n   * timer ID returned by `setTimeout`.\n   *\n   * @example\n   * ```ts\n   * import { timeoutManager } from '@tanstack/query-core'\n   *\n   * const timeoutId = timeoutManager.setTimeout(\n   *   () => console.log('ran at:', new Date()),\n   *   1000,\n   * )\n   *\n   * timeoutManager.clearTimeout(timeoutId)\n   * ```\n   */\n  clearTimeout(timeoutId: ManagedTimerId | undefined): void {\n    this.#provider.clearTimeout(timeoutId)\n  }\n\n  /**\n   * `setInterval` schedules a callback to be called approximately every\n   * `delay` milliseconds, like the global `setInterval` function.\n   *\n   * Like `setTimeout`, it returns a timer ID, which may be a number or an\n   * object that can be coerced to a number via `Symbol.toPrimitive`.\n   *\n   * @example\n   * ```ts\n   * import { timeoutManager } from '@tanstack/query-core'\n   *\n   * const intervalId = timeoutManager.setInterval(\n   *   () => console.log('ran at:', new Date()),\n   *   1000,\n   * )\n   * ```\n   */\n  setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId {\n    if (process.env.NODE_ENV !== 'production') {\n      this.#providerCalled = true\n    }\n    return this.#provider.setInterval(callback, delay)\n  }\n\n  /**\n   * `clearInterval` can be used to cancel an interval, like the global\n   * `clearInterval` function. It should be called with an interval ID\n   * returned by `setInterval`.\n   *\n   * @example\n   * ```ts\n   * import { timeoutManager } from '@tanstack/query-core'\n   *\n   * const intervalId = timeoutManager.setInterval(\n   *   () => console.log('ran at:', new Date()),\n   *   1000,\n   * )\n   *\n   * timeoutManager.clearInterval(intervalId)\n   * ```\n   */\n  clearInterval(intervalId: ManagedTimerId | undefined): void {\n    this.#provider.clearInterval(intervalId)\n  }\n}\n\n/**\n * Singleton instance of {@link TimeoutManager}, used throughout TanStack Query to schedule and cancel timers.\n */\nexport const timeoutManager = new TimeoutManager()\n\n/**\n * In many cases code wants to delay to the next event loop tick; this is not\n * mediated by {@link timeoutManager}.\n *\n * This function is provided to make auditing the `tanstack/query-core` for\n * incorrect use of system `setTimeout` easier.\n */\nexport function systemSetTimeoutZero(callback: TimeoutCallback): void {\n  setTimeout(callback, 0)\n}\n"],"mappings":";;AAsCA,MAAa,yBAA0C;CAWrD,aAAa,UAAU,UAAU,WAAW,UAAU,KAAK;CAC3D,eAAe,cACb,aAAa,SAAsC;CAErD,cAAc,UAAU,UAAU,YAAY,UAAU,KAAK;CAC7D,gBAAgB,eACd,cAAc,UAAuC;AACzD;;;;;;;;;;;;AAaA,IAAa,iBAAb,MAAqE;CAQnE,YAAkC;CAClC,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BlB,mBACE,UACM;EACN,IAAI,QAAQ,IAAI,aAAa,cACvB;OAAA,KAAKA,mBAAmB,aAAa,KAAKC,WAY5C,QAAQ,MACN,8GACA;IAAE,UAAU,KAAKA;IAAW;GAAS,CACvC;EAAA;EAIJ,KAAKA,YAAY;EACjB,IAAI,QAAQ,IAAI,aAAa,cAC3B,KAAKD,kBAAkB;CAE3B;;;;;;;;;;;;;;;;;;;;;CAsBA,WAAW,UAA2B,OAA+B;EACnE,IAAI,QAAQ,IAAI,aAAa,cAC3B,KAAKA,kBAAkB;EAEzB,OAAO,KAAKC,UAAU,WAAW,UAAU,KAAK;CAClD;;;;;;;;;;;;;;;;;;CAmBA,aAAa,WAA6C;EACxD,KAAKA,UAAU,aAAa,SAAS;CACvC;;;;;;;;;;;;;;;;;;CAmBA,YAAY,UAA2B,OAA+B;EACpE,IAAI,QAAQ,IAAI,aAAa,cAC3B,KAAKD,kBAAkB;EAEzB,OAAO,KAAKC,UAAU,YAAY,UAAU,KAAK;CACnD;;;;;;;;;;;;;;;;;;CAmBA,cAAc,YAA8C;EAC1D,KAAKA,UAAU,cAAc,UAAU;CACzC;AACF;;;;AAKA,MAAa,iBAAiB,IAAI,eAAe;;;;;;;;AASjD,SAAgB,qBAAqB,UAAiC;CACpE,WAAW,UAAU,CAAC;AACxB"}

package/build/modern/timeoutManager.d.cts

@@ -19,6 +19,12 @@ type ManagedTimerId = number | {
 };
 /**
  * Backend for timer functions.
+ *
+ * Timers are performance-sensitive: short-lived timers (delays under a few seconds) tend to be
+ * latency-sensitive, while long-lived ones may benefit more from coalescing — batching timers
+ * with similar deadlines together — which the default provider (backed by the platform's global
+ * `setTimeout`/`setInterval`) does not do. A custom provider can implement coalescing, and can
+ * also support delays longer than the ~24-day maximum of the global `setTimeout`.
  */
 type TimeoutProvider<TTimerId extends ManagedTimerId = ManagedTimerId> = {
   readonly setTimeout: (callback: TimeoutCallback, delay: number) => TTimerId;
@@ -40,12 +46,111 @@ declare const defaultTimeoutProvider: TimeoutProvider;
  */
 declare class TimeoutManager implements Omit<TimeoutProvider, 'name'> {
   #private;
+  /**
+   * `setTimeoutProvider` can be used to set a custom implementation of the
+   * `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` functions,
+   * called a `TimeoutProvider`.
+   *
+   * This may be useful if you notice event loop performance issues with
+   * thousands of queries. A custom TimeoutProvider could also support timer
+   * delays longer than the global `setTimeout` maximum delay value of about
+   * 24 days.
+   *
+   * It is important to call `setTimeoutProvider` before creating a
+   * QueryClient or queries, so that the same provider is used consistently
+   * for all timers in the application, since different TimeoutProviders
+   * cannot cancel each others' timers.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager, QueryClient } from '@tanstack/query-core'
+   * import { CustomTimeoutProvider } from './CustomTimeoutProvider'
+   *
+   * timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())
+   *
+   * export const queryClient = new QueryClient()
+   * ```
+   */
   setTimeoutProvider<TTimerId extends ManagedTimerId>(provider: TimeoutProvider<TTimerId>): void;
+  /**
+   * `setTimeout` schedules a callback to run after approximately `delay`
+   * milliseconds, like the global `setTimeout` function. The callback can be
+   * canceled with `clearTimeout`.
+   *
+   * It returns a timer ID, which may be a number or an object that can be
+   * coerced to a number via `Symbol.toPrimitive`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const timeoutId = timeoutManager.setTimeout(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * const timeoutIdNumber: number = Number(timeoutId)
+   * ```
+   */
   setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId;
+  /**
+   * `clearTimeout` cancels a timeout callback scheduled with `setTimeout`,
+   * like the global `clearTimeout` function. It should be called with a
+   * timer ID returned by `setTimeout`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const timeoutId = timeoutManager.setTimeout(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * timeoutManager.clearTimeout(timeoutId)
+   * ```
+   */
   clearTimeout(timeoutId: ManagedTimerId | undefined): void;
+  /**
+   * `setInterval` schedules a callback to be called approximately every
+   * `delay` milliseconds, like the global `setInterval` function.
+   *
+   * Like `setTimeout`, it returns a timer ID, which may be a number or an
+   * object that can be coerced to a number via `Symbol.toPrimitive`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const intervalId = timeoutManager.setInterval(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   * ```
+   */
   setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId;
+  /**
+   * `clearInterval` can be used to cancel an interval, like the global
+   * `clearInterval` function. It should be called with an interval ID
+   * returned by `setInterval`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const intervalId = timeoutManager.setInterval(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * timeoutManager.clearInterval(intervalId)
+   * ```
+   */
   clearInterval(intervalId: ManagedTimerId | undefined): void;
 }
+/**
+ * Singleton instance of {@link TimeoutManager}, used throughout TanStack Query to schedule and cancel timers.
+ */
 declare const timeoutManager: TimeoutManager;
 /**
  * In many cases code wants to delay to the next event loop tick; this is not

package/build/modern/timeoutManager.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"timeoutManager.d.cts","names":[],"sources":["../../src/timeoutManager.ts"],"mappings":";;;;;;;;;KAQY,mBAAmB;;;;;;;KAQnB;GAA6B,OAAO;;;;;KAKpC,gBAAgB,iBAAiB,iBAAiB;WAEjD,aAAa,UAAU,iBAAiB,kBAAkB;WAC1D,eAAe,WAAW;WAE1B,cAAc,UAAU,iBAAiB,kBAAkB;WAC3D,gBAAgB,YAAY;;cAK5B,wBAAwB;;;;;;;;;;;;cA+BxB,0BAA0B,KAAK;;EAW1C,mBAAmB,iBAAiB,gBAClC,UAAU,gBAAgB;EA4B5B,WAAW,UAAU,iBAAiB,gBAAgB;EAOtD,aAAa,WAAW;EAIxB,YAAY,UAAU,iBAAiB,gBAAgB;EAOvD,cAAc,YAAY;;cAKf,gBAAc;;;;;;;;iBASX,qBAAqB,UAAU"}
+{"version":3,"file":"timeoutManager.d.cts","names":[],"sources":["../../src/timeoutManager.ts"],"mappings":";;;;;;;;;KAQY,mBAAmB;;;;;;;KAQnB;GAA6B,OAAO;;;;;;;;;;;KAWpC,gBAAgB,iBAAiB,iBAAiB;WAEjD,aAAa,UAAU,iBAAiB,kBAAkB;WAC1D,eAAe,WAAW;WAE1B,cAAc,UAAU,iBAAiB,kBAAkB;WAC3D,gBAAgB,YAAY;;cAK5B,wBAAwB;;;;;;;;;;;;cA+BxB,0BAA0B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoC1C,mBAAmB,iBAAiB,gBAClC,UAAU,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAgD5B,WAAW,UAAU,iBAAiB,gBAAgB;;;;;;;;;;;;;;;;;;EAwBtD,aAAa,WAAW;;;;;;;;;;;;;;;;;;EAqBxB,YAAY,UAAU,iBAAiB,gBAAgB;;;;;;;;;;;;;;;;;;EAwBvD,cAAc,YAAY;;;;;cAQf,gBAAc;;;;;;;;iBASX,qBAAqB,UAAU"}

package/build/modern/timeoutManager.d.ts

@@ -19,6 +19,12 @@ type ManagedTimerId = number | {
 };
 /**
  * Backend for timer functions.
+ *
+ * Timers are performance-sensitive: short-lived timers (delays under a few seconds) tend to be
+ * latency-sensitive, while long-lived ones may benefit more from coalescing — batching timers
+ * with similar deadlines together — which the default provider (backed by the platform's global
+ * `setTimeout`/`setInterval`) does not do. A custom provider can implement coalescing, and can
+ * also support delays longer than the ~24-day maximum of the global `setTimeout`.
  */
 type TimeoutProvider<TTimerId extends ManagedTimerId = ManagedTimerId> = {
   readonly setTimeout: (callback: TimeoutCallback, delay: number) => TTimerId;
@@ -40,12 +46,111 @@ declare const defaultTimeoutProvider: TimeoutProvider;
  */
 declare class TimeoutManager implements Omit<TimeoutProvider, 'name'> {
   #private;
+  /**
+   * `setTimeoutProvider` can be used to set a custom implementation of the
+   * `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` functions,
+   * called a `TimeoutProvider`.
+   *
+   * This may be useful if you notice event loop performance issues with
+   * thousands of queries. A custom TimeoutProvider could also support timer
+   * delays longer than the global `setTimeout` maximum delay value of about
+   * 24 days.
+   *
+   * It is important to call `setTimeoutProvider` before creating a
+   * QueryClient or queries, so that the same provider is used consistently
+   * for all timers in the application, since different TimeoutProviders
+   * cannot cancel each others' timers.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager, QueryClient } from '@tanstack/query-core'
+   * import { CustomTimeoutProvider } from './CustomTimeoutProvider'
+   *
+   * timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())
+   *
+   * export const queryClient = new QueryClient()
+   * ```
+   */
   setTimeoutProvider<TTimerId extends ManagedTimerId>(provider: TimeoutProvider<TTimerId>): void;
+  /**
+   * `setTimeout` schedules a callback to run after approximately `delay`
+   * milliseconds, like the global `setTimeout` function. The callback can be
+   * canceled with `clearTimeout`.
+   *
+   * It returns a timer ID, which may be a number or an object that can be
+   * coerced to a number via `Symbol.toPrimitive`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const timeoutId = timeoutManager.setTimeout(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * const timeoutIdNumber: number = Number(timeoutId)
+   * ```
+   */
   setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId;
+  /**
+   * `clearTimeout` cancels a timeout callback scheduled with `setTimeout`,
+   * like the global `clearTimeout` function. It should be called with a
+   * timer ID returned by `setTimeout`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const timeoutId = timeoutManager.setTimeout(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * timeoutManager.clearTimeout(timeoutId)
+   * ```
+   */
   clearTimeout(timeoutId: ManagedTimerId | undefined): void;
+  /**
+   * `setInterval` schedules a callback to be called approximately every
+   * `delay` milliseconds, like the global `setInterval` function.
+   *
+   * Like `setTimeout`, it returns a timer ID, which may be a number or an
+   * object that can be coerced to a number via `Symbol.toPrimitive`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const intervalId = timeoutManager.setInterval(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   * ```
+   */
   setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId;
+  /**
+   * `clearInterval` can be used to cancel an interval, like the global
+   * `clearInterval` function. It should be called with an interval ID
+   * returned by `setInterval`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const intervalId = timeoutManager.setInterval(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * timeoutManager.clearInterval(intervalId)
+   * ```
+   */
   clearInterval(intervalId: ManagedTimerId | undefined): void;
 }
+/**
+ * Singleton instance of {@link TimeoutManager}, used throughout TanStack Query to schedule and cancel timers.
+ */
 declare const timeoutManager: TimeoutManager;
 /**
  * In many cases code wants to delay to the next event loop tick; this is not

package/build/modern/timeoutManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeoutManager.d.ts","names":[],"sources":["../../src/timeoutManager.ts"],"mappings":";;;;;;;;;KAQY,mBAAmB;;;;;;;KAQnB;GAA6B,OAAO;;;;;KAKpC,gBAAgB,iBAAiB,iBAAiB;WAEjD,aAAa,UAAU,iBAAiB,kBAAkB;WAC1D,eAAe,WAAW;WAE1B,cAAc,UAAU,iBAAiB,kBAAkB;WAC3D,gBAAgB,YAAY;;cAK5B,wBAAwB;;;;;;;;;;;;cA+BxB,0BAA0B,KAAK;;EAW1C,mBAAmB,iBAAiB,gBAClC,UAAU,gBAAgB;EA4B5B,WAAW,UAAU,iBAAiB,gBAAgB;EAOtD,aAAa,WAAW;EAIxB,YAAY,UAAU,iBAAiB,gBAAgB;EAOvD,cAAc,YAAY;;cAKf,gBAAc;;;;;;;;iBASX,qBAAqB,UAAU"}
+{"version":3,"file":"timeoutManager.d.ts","names":[],"sources":["../../src/timeoutManager.ts"],"mappings":";;;;;;;;;KAQY,mBAAmB;;;;;;;KAQnB;GAA6B,OAAO;;;;;;;;;;;KAWpC,gBAAgB,iBAAiB,iBAAiB;WAEjD,aAAa,UAAU,iBAAiB,kBAAkB;WAC1D,eAAe,WAAW;WAE1B,cAAc,UAAU,iBAAiB,kBAAkB;WAC3D,gBAAgB,YAAY;;cAK5B,wBAAwB;;;;;;;;;;;;cA+BxB,0BAA0B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoC1C,mBAAmB,iBAAiB,gBAClC,UAAU,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAgD5B,WAAW,UAAU,iBAAiB,gBAAgB;;;;;;;;;;;;;;;;;;EAwBtD,aAAa,WAAW;;;;;;;;;;;;;;;;;;EAqBxB,YAAY,UAAU,iBAAiB,gBAAgB;;;;;;;;;;;;;;;;;;EAwBvD,cAAc,YAAY;;;;;cAQf,gBAAc;;;;;;;;iBASX,qBAAqB,UAAU"}