@tanstack/query-core 5.102.7 → 5.103.0

package/build/modern/query.cjs

@@ -5,6 +5,25 @@ const require_retryer = require("./retryer.cjs");
 const require_removable = require("./removable.cjs");
 const require_infiniteQueryBehavior = require("./infiniteQueryBehavior.cjs");
 //#region src/query.ts
+/**
+* Represents a single cached query. A `Query` holds the query's key, options,
+* state (data/error/status), and the observers currently subscribed to it.
+*
+* Instances are created and managed internally by `QueryCache`; application
+* code typically interacts with queries indirectly through `QueryClient` or
+* a framework hook like `useQuery`. Direct access to a `Query` instance is
+* possible via `queryCache.find()`/`findAll()` for inspecting cache state.
+*
+* @example
+* ```ts
+* const queryCache = queryClient.getQueryCache()
+* const query = queryCache.find({ queryKey: ['posts'] })
+*
+* if (query) {
+*   console.log(query.state.dataUpdatedAt)
+* }
+* ```
+*/
 var Query = class extends require_removable.Removable {
 	#queryType;
 	#initialState;
@@ -28,15 +47,24 @@ var Query = class extends require_removable.Removable {
 		this.state = config.state ?? this.#initialState;
 		this.scheduleGc();
 	}
+	/**
+	* The `meta` object passed in the query's options, if any.
+	*/
 	get meta() {
 		return this.options.meta;
 	}
+	/** @internal */
 	get queryType() {
 		return this.#queryType;
 	}
+	/**
+	* The promise for the currently in-flight fetch, if the query is fetching.
+	* `undefined` when the query is not fetching.
+	*/
 	get promise() {
 		return this.#retryer?.promise;
 	}
+	/** @internal */
 	setOptions(options) {
 		this.options = {
 			...this.#defaultOptions,
@@ -55,6 +83,7 @@ var Query = class extends require_removable.Removable {
 	optionalRemove() {
 		if (!this.observers.length && this.state.fetchStatus === "idle") this.#cache.remove(this);
 	}
+	/** @internal */
 	setData(newData, options) {
 		const data = require_utils.replaceData(this.state.data, newData, this.options);
 		this.#dispatch({
@@ -65,60 +94,141 @@ var Query = class extends require_removable.Removable {
 		});
 		return data;
 	}
+	/**
+	* Merges the given partial state directly into this query's state, notifying observers. Used
+	* by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a
+	* user manually trigger a loading/error state or edit the cached data.
+	*/
 	setState(state) {
 		this.#dispatch({
 			type: "setState",
 			state
 		});
 	}
+	/**
+	* Cancels the query's currently in-flight fetch, if any.
+	* - Returns a promise that resolves once the cancellation has settled.
+	* - If no fetch is in progress, resolves immediately.
+	*
+	* @example
+	* ```ts
+	* await query.cancel()
+	* ```
+	*/
 	cancel(options) {
 		const promise = this.#retryer?.promise;
 		this.#retryer?.cancel(options);
 		return promise ? promise.then(require_utils.noop).catch(require_utils.noop) : Promise.resolve();
 	}
+	/**
+	* Clears the query's garbage collection timeout and silently cancels any
+	* in-flight fetch. Called by `QueryCache` when the query is removed from
+	* the cache.
+	*
+	* @see {@link Query#cancel}
+	*/
 	destroy() {
 		super.destroy();
 		this.cancel({ silent: true });
 	}
+	/** @internal */
 	get resetState() {
 		return this.#initialState;
 	}
+	/**
+	* Resets the query back to its initial state (the state it had when it was
+	* first created, e.g. any `initialData`), destroying it first to cancel any
+	* in-flight fetch.
+	*/
 	reset() {
 		this.destroy();
 		this.setState(this.resetState);
 	}
+	/**
+	* Returns `true` if the query has at least one observer for which `enabled`
+	* does not resolve to `false`.
+	*/
 	isActive() {
 		return this.observers.some((observer) => require_utils.resolveQueryValue(observer.options.enabled, this) !== false);
 	}
+	/**
+	* Returns `true` if the query is disabled, meaning it will not fetch
+	* automatically.
+	* - If the query has observers, it is disabled when none of them are active
+	*   (see `isActive`).
+	* - If the query has no observers, it is disabled when its `queryFn` is
+	*   `skipToken` or it has never been fetched.
+	*/
 	isDisabled() {
 		if (this.getObserversCount() > 0) return !this.isActive();
 		return this.options.queryFn === require_utils.skipToken || !this.isFetched();
 	}
+	/**
+	* Returns `true` if the query has been fetched, i.e. it has resolved with
+	* either data or an error at least once.
+	*/
 	isFetched() {
 		return this.state.dataUpdateCount + this.state.errorUpdateCount > 0;
 	}
+	/**
+	* Returns `true` if the query has at least one observer configured with
+	* `staleTime: 'static'`, meaning it is treated as never stale.
+	*/
 	isStatic() {
 		if (this.getObserversCount() > 0) return this.observers.some((observer) => require_utils.resolveQueryValue(observer.options.staleTime, this) === "static");
 		return false;
 	}
+	/**
+	* Returns `true` if the query is stale.
+	* - If the query has observers, defers to whether any observer's current
+	*   result reports `isStale` (which accounts for each observer's own
+	*   `staleTime` and `enabled` state).
+	* - If the query has no observers, it is considered stale when it has no
+	*   data or has been invalidated.
+	*
+	* @see {@link Query#isStaleByTime}
+	* @example
+	* ```ts
+	* if (query.isStale()) {
+	*   // refetch or otherwise treat the cached data as outdated
+	* }
+	* ```
+	*/
 	isStale() {
 		if (this.getObserversCount() > 0) return this.observers.some((observer) => observer.getCurrentResult().isStale);
 		return this.state.data === void 0 || this.state.isInvalidated;
 	}
+	/**
+	* Returns `true` if the query's data is stale relative to the given
+	* `staleTime` (defaults to `0`).
+	* - A query with no data is always stale.
+	* - `staleTime: 'static'` is never stale.
+	* - An invalidated query is always stale.
+	* - Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.
+	*
+	* @see {@link Query#isStale}
+	* @example
+	* ```ts
+	* const isStale = query.isStaleByTime(1000 * 60)
+	* ```
+	*/
 	isStaleByTime(staleTime = 0) {
 		if (this.state.data === void 0) return true;
 		if (staleTime === "static") return false;
 		if (this.state.isInvalidated) return true;
 		return !require_utils.timeUntilStale(this.state.dataUpdatedAt, staleTime);
 	}
+	/** @internal */
 	onFocus() {
 		this.observers.find((x) => x.shouldFetchOnWindowFocus())?.refetch({ cancelRefetch: false });
 		this.#retryer?.continue();
 	}
+	/** @internal */
 	onOnline() {
 		this.observers.find((x) => x.shouldFetchOnReconnect())?.refetch({ cancelRefetch: false });
 		this.#retryer?.continue();
 	}
+	/** @internal */
 	addObserver(observer) {
 		if (!this.observers.includes(observer)) {
 			this.observers.push(observer);
@@ -130,6 +240,7 @@ var Query = class extends require_removable.Removable {
 			});
 		}
 	}
+	/** @internal */
 	removeObserver(observer) {
 		const index = this.observers.indexOf(observer);
 		if (index !== -1) {
@@ -148,12 +259,42 @@ var Query = class extends require_removable.Removable {
 			});
 		}
 	}
+	/**
+	* Returns the number of observers currently subscribed to this query.
+	*
+	* @example
+	* ```ts
+	* if (query.getObserversCount() === 0) {
+	*   // no component is currently watching this query
+	* }
+	* ```
+	*/
 	getObserversCount() {
 		return this.observers.length;
 	}
+	/**
+	* Marks the query as invalidated, unless it is already invalidated. This
+	* updates `state.isInvalidated` and notifies observers, but does not by
+	* itself trigger a refetch.
+	*
+	* @example
+	* ```ts
+	* query.invalidate()
+	* ```
+	*/
 	invalidate() {
 		if (!this.state.isInvalidated) this.#dispatch({ type: "invalidate" });
 	}
+	/**
+	* Fetches the query, i.e. runs its `queryFn` (through any configured
+	* retryer/behavior) and updates the query's state with the result.
+	* - If a fetch is already in flight, returns its promise instead of
+	*   starting a new one, unless `fetchOptions.cancelRefetch` is set and the
+	*   query already has data, in which case the current fetch is silently
+	*   cancelled first.
+	* - If `options` is passed, it replaces the query's current options
+	*   before fetching.
+	*/
 	async fetch(options, fetchOptions) {
 		if (this.state.fetchStatus !== "idle" && this.#retryer?.status() !== "rejected") {
 			if (this.state.data !== void 0 && fetchOptions?.cancelRefetch) this.cancel({ silent: true });

package/build/modern/query.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"query.cjs","names":["Removable","#abortSignalConsumed","#defaultOptions","#client","#cache","#initialState","#queryType","#retryer","replaceData","#dispatch","noop","resolveQueryValue","skipToken","timeUntilStale","ensureQueryFn","infiniteQueryBehavior","#revertState","createRetryer","CancelledError","canFetch"],"sources":["../../src/query.ts"],"sourcesContent":["import {\n  ensureQueryFn,\n  noop,\n  replaceData,\n  resolveQueryValue,\n  skipToken,\n  timeUntilStale,\n} from './utils'\nimport { notifyManager } from './notifyManager'\nimport { CancelledError, canFetch, createRetryer } from './retryer'\nimport { Removable } from './removable'\nimport { infiniteQueryBehavior } from './infiniteQueryBehavior'\nimport type { QueryCache } from './queryCache'\nimport type { QueryClient } from './queryClient'\nimport type {\n  CancelOptions,\n  DefaultError,\n  FetchStatus,\n  InitialDataFunction,\n  OmitKeyof,\n  QueryFunctionContext,\n  QueryKey,\n  QueryMeta,\n  QueryOptions,\n  QueryStatus,\n  SetDataOptions,\n  StaleTime,\n} from './types'\nimport type { QueryObserver } from './queryObserver'\nimport type { Retryer } from './retryer'\n\n// TYPES\n\ninterface QueryConfig<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  client: QueryClient\n  queryKey: TQueryKey\n  queryHash: string\n  options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  defaultOptions?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  state?: QueryState<TData, TError>\n}\n\nexport interface QueryState<TData = unknown, TError = DefaultError> {\n  data: TData | undefined\n  dataUpdateCount: number\n  dataUpdatedAt: number\n  error: TError | null\n  errorUpdateCount: number\n  errorUpdatedAt: number\n  fetchFailureCount: number\n  fetchFailureReason: TError | null\n  fetchMeta: FetchMeta | null\n  isInvalidated: boolean\n  status: QueryStatus\n  fetchStatus: FetchStatus\n}\n\nexport interface FetchContext<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  fetchFn: () => unknown | Promise<unknown>\n  fetchOptions?: FetchOptions\n  signal: AbortSignal\n  options: QueryOptions<TQueryFnData, TError, TData, any>\n  client: QueryClient\n  queryKey: TQueryKey\n  state: QueryState<TData, TError>\n}\n\nexport interface QueryBehavior<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  onFetch: (\n    context: FetchContext<TQueryFnData, TError, TData, TQueryKey>,\n    query: Query,\n  ) => void\n}\n\nexport type FetchDirection = 'forward' | 'backward'\n\nexport interface FetchMeta {\n  fetchMore?: { direction: FetchDirection }\n}\n\nexport interface FetchOptions<TData = unknown> {\n  cancelRefetch?: boolean\n  meta?: FetchMeta\n  initialPromise?: Promise<TData>\n}\n\ninterface FailedAction<TError> {\n  type: 'failed'\n  failureCount: number\n  error: TError\n}\n\ninterface FetchAction {\n  type: 'fetch'\n  meta?: FetchMeta\n}\n\ninterface SuccessAction<TData> {\n  data: TData | undefined\n  type: 'success'\n  dataUpdatedAt?: number\n  manual?: boolean\n}\n\ninterface ErrorAction<TError> {\n  type: 'error'\n  error: TError\n}\n\ninterface InvalidateAction {\n  type: 'invalidate'\n}\n\ninterface PauseAction {\n  type: 'pause'\n}\n\ninterface ContinueAction {\n  type: 'continue'\n}\n\ninterface SetStateAction<TData, TError> {\n  type: 'setState'\n  state: Partial<QueryState<TData, TError>>\n}\n\nexport type Action<TData, TError> =\n  | ContinueAction\n  | ErrorAction<TError>\n  | FailedAction<TError>\n  | FetchAction\n  | InvalidateAction\n  | PauseAction\n  | SetStateAction<TData, TError>\n  | SuccessAction<TData>\n\n// CLASS\n\nexport class Query<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> extends Removable {\n  queryKey: TQueryKey\n  queryHash: string\n  options!: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  state: QueryState<TData, TError>\n  #queryType?: 'infinite'\n\n  #initialState: QueryState<TData, TError>\n  #revertState?: QueryState<TData, TError>\n  #cache: QueryCache\n  #client: QueryClient\n  #retryer?: Retryer<TData>\n  observers: Array<QueryObserver<any, any, any, any, any>>\n  #defaultOptions?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  #abortSignalConsumed: boolean\n\n  constructor(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>) {\n    super()\n\n    this.#abortSignalConsumed = false\n    this.#defaultOptions = config.defaultOptions\n    this.setOptions(config.options)\n    this.observers = []\n    this.#client = config.client\n    this.#cache = this.#client.getQueryCache()\n    this.queryKey = config.queryKey\n    this.queryHash = config.queryHash\n    this.#initialState = getDefaultState(this.options)\n    this.state = config.state ?? this.#initialState\n    this.scheduleGc()\n  }\n  get meta(): QueryMeta | undefined {\n    return this.options.meta\n  }\n\n  get queryType() {\n    return this.#queryType\n  }\n\n  get promise(): Promise<TData> | undefined {\n    return this.#retryer?.promise\n  }\n\n  setOptions(\n    options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  ): void {\n    this.options = { ...this.#defaultOptions, ...options }\n\n    if (options?._type) {\n      this.#queryType = options._type\n    }\n\n    this.updateGcTime(this.options.gcTime)\n\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n    if (this.state && this.state.data === undefined) {\n      const defaultState = getDefaultState(this.options)\n      if (defaultState.data !== undefined) {\n        this.setState(\n          successState(defaultState.data, defaultState.dataUpdatedAt),\n        )\n        this.#initialState = defaultState\n      }\n    }\n  }\n\n  protected optionalRemove() {\n    if (!this.observers.length && this.state.fetchStatus === 'idle') {\n      this.#cache.remove(this)\n    }\n  }\n\n  setData(\n    newData: TData,\n    options?: SetDataOptions & { manual: boolean },\n  ): TData {\n    const data = replaceData(this.state.data, newData, this.options)\n\n    // Set data and mark it as cached\n    this.#dispatch({\n      data,\n      type: 'success',\n      dataUpdatedAt: options?.updatedAt,\n      manual: options?.manual,\n    })\n\n    return data\n  }\n\n  setState(state: Partial<QueryState<TData, TError>>): void {\n    this.#dispatch({ type: 'setState', state })\n  }\n\n  cancel(options?: CancelOptions): Promise<void> {\n    const promise = this.#retryer?.promise\n    this.#retryer?.cancel(options)\n    return promise ? promise.then(noop).catch(noop) : Promise.resolve()\n  }\n\n  destroy(): void {\n    super.destroy()\n\n    this.cancel({ silent: true })\n  }\n\n  get resetState(): QueryState<TData, TError> {\n    return this.#initialState\n  }\n\n  reset(): void {\n    this.destroy()\n    this.setState(this.resetState)\n  }\n\n  isActive(): boolean {\n    return this.observers.some(\n      (observer) => resolveQueryValue(observer.options.enabled, this) !== false,\n    )\n  }\n\n  isDisabled(): boolean {\n    if (this.getObserversCount() > 0) {\n      return !this.isActive()\n    }\n    // if a query has no observers, it should still be considered disabled if it never attempted a fetch\n    return this.options.queryFn === skipToken || !this.isFetched()\n  }\n\n  isFetched() {\n    return this.state.dataUpdateCount + this.state.errorUpdateCount > 0\n  }\n\n  isStatic(): boolean {\n    if (this.getObserversCount() > 0) {\n      return this.observers.some(\n        (observer) =>\n          resolveQueryValue(observer.options.staleTime, this) === 'static',\n      )\n    }\n\n    return false\n  }\n\n  isStale(): boolean {\n    // check observers first, their `isStale` has the source of truth\n    // calculated with `isStaleByTime` and it takes `enabled` into account\n    if (this.getObserversCount() > 0) {\n      return this.observers.some(\n        (observer) => observer.getCurrentResult().isStale,\n      )\n    }\n\n    return this.state.data === undefined || this.state.isInvalidated\n  }\n\n  isStaleByTime(staleTime: StaleTime = 0): boolean {\n    // no data is always stale\n    if (this.state.data === undefined) {\n      return true\n    }\n    // static is never stale\n    if (staleTime === 'static') {\n      return false\n    }\n    // if the query is invalidated, it is stale\n    if (this.state.isInvalidated) {\n      return true\n    }\n\n    return !timeUntilStale(this.state.dataUpdatedAt, staleTime)\n  }\n\n  onFocus(): void {\n    const observer = this.observers.find((x) => x.shouldFetchOnWindowFocus())\n\n    observer?.refetch({ cancelRefetch: false })\n\n    // Continue fetch if currently paused\n    this.#retryer?.continue()\n  }\n\n  onOnline(): void {\n    const observer = this.observers.find((x) => x.shouldFetchOnReconnect())\n\n    observer?.refetch({ cancelRefetch: false })\n\n    // Continue fetch if currently paused\n    this.#retryer?.continue()\n  }\n\n  addObserver(observer: QueryObserver<any, any, any, any, any>): void {\n    if (!this.observers.includes(observer)) {\n      this.observers.push(observer)\n\n      // Stop the query from being garbage collected\n      this.clearGcTimeout()\n\n      this.#cache.notify({ type: 'observerAdded', query: this, observer })\n    }\n  }\n\n  removeObserver(observer: QueryObserver<any, any, any, any, any>): void {\n    const index = this.observers.indexOf(observer)\n    if (index !== -1) {\n      this.observers.splice(index, 1)\n\n      if (!this.observers.length) {\n        // If the transport layer does not support cancellation\n        // we'll let the query continue so the result can be cached\n        if (this.#retryer) {\n          if (\n            this.#abortSignalConsumed ||\n            (this.state.fetchStatus === 'paused' &&\n              this.state.status === 'pending')\n          ) {\n            this.#retryer.cancel({ revert: true })\n          } else {\n            this.#retryer.cancelRetry()\n          }\n        }\n\n        this.scheduleGc()\n      }\n\n      this.#cache.notify({ type: 'observerRemoved', query: this, observer })\n    }\n  }\n\n  getObserversCount(): number {\n    return this.observers.length\n  }\n\n  invalidate(): void {\n    if (!this.state.isInvalidated) {\n      this.#dispatch({ type: 'invalidate' })\n    }\n  }\n\n  async fetch(\n    options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n    fetchOptions?: FetchOptions<TQueryFnData>,\n  ): Promise<TData> {\n    if (\n      this.state.fetchStatus !== 'idle' &&\n      // If the promise in the retryer is already rejected, we have to definitely\n      // re-start the fetch; there is a chance that the query is still in a\n      // pending state when that happens\n      this.#retryer?.status() !== 'rejected'\n    ) {\n      if (this.state.data !== undefined && fetchOptions?.cancelRefetch) {\n        // Silently cancel current fetch if the user wants to cancel refetch\n        this.cancel({ silent: true })\n      } else if (this.#retryer) {\n        // make sure that retries that were potentially cancelled due to unmounts can continue\n        this.#retryer.continueRetry()\n        // Return current promise if we are already fetching\n        return this.#retryer.promise\n      }\n    }\n\n    // Update config if passed, otherwise the config from the last execution is used\n    if (options) {\n      this.setOptions(options)\n    }\n\n    // Use the options from the first observer with a query function if no function is found.\n    // This can happen when the query is hydrated or created with setQueryData.\n    if (!this.options.queryFn) {\n      const observer = this.observers.find((x) => x.options.queryFn)\n      if (observer) {\n        this.setOptions(observer.options)\n      }\n    }\n\n    if (process.env.NODE_ENV !== 'production') {\n      if (!Array.isArray(this.options.queryKey)) {\n        console.error(\n          `As of v4, queryKey needs to be an Array. If you are using a string like 'repoData', please change it to an Array, e.g. ['repoData']`,\n        )\n      }\n    }\n\n    const abortController = new AbortController()\n\n    // Adds an enumerable signal property to the object that\n    // which sets abortSignalConsumed to true when the signal\n    // is read.\n    const addSignalProperty = (object: unknown) => {\n      Object.defineProperty(object, 'signal', {\n        enumerable: true,\n        get: () => {\n          this.#abortSignalConsumed = true\n          return abortController.signal\n        },\n      })\n    }\n\n    // Create fetch function\n    const fetchFn = () => {\n      const queryFn = ensureQueryFn(this.options, fetchOptions)\n\n      // Create query function context\n      const createQueryFnContext = (): QueryFunctionContext<TQueryKey> => {\n        const queryFnContext: OmitKeyof<\n          QueryFunctionContext<TQueryKey>,\n          'signal'\n        > = {\n          client: this.#client,\n          queryKey: this.queryKey,\n          meta: this.meta,\n        }\n        addSignalProperty(queryFnContext)\n        return queryFnContext as QueryFunctionContext<TQueryKey>\n      }\n\n      const queryFnContext = createQueryFnContext()\n\n      this.#abortSignalConsumed = false\n      if (this.options.persister) {\n        return this.options.persister(\n          queryFn,\n          queryFnContext,\n          this as unknown as Query,\n        )\n      }\n\n      return queryFn(queryFnContext)\n    }\n\n    // Trigger behavior hook\n    const createFetchContext = (): FetchContext<\n      TQueryFnData,\n      TError,\n      TData,\n      TQueryKey\n    > => {\n      const context: OmitKeyof<\n        FetchContext<TQueryFnData, TError, TData, TQueryKey>,\n        'signal'\n      > = {\n        fetchOptions,\n        options: this.options,\n        queryKey: this.queryKey,\n        client: this.#client,\n        state: this.state,\n        fetchFn,\n      }\n\n      addSignalProperty(context)\n      return context as FetchContext<TQueryFnData, TError, TData, TQueryKey>\n    }\n\n    const context = createFetchContext()\n\n    const behavior =\n      this.#queryType === 'infinite'\n        ? (infiniteQueryBehavior(\n            (this.options as { pages?: number }).pages,\n          ) as QueryBehavior<TQueryFnData, TError, TData, TQueryKey>)\n        : this.options.behavior\n    behavior?.onFetch(context, this as unknown as Query)\n\n    // Store state in case the current fetch needs to be reverted\n    this.#revertState = this.state\n\n    // Set to fetching state if not already in it\n    if (\n      this.state.fetchStatus === 'idle' ||\n      this.state.fetchMeta !== context.fetchOptions?.meta\n    ) {\n      this.#dispatch({ type: 'fetch', meta: context.fetchOptions?.meta })\n    }\n\n    // Try to fetch the data\n    const retryer = (this.#retryer = createRetryer({\n      initialPromise: fetchOptions?.initialPromise as\n        | Promise<TData>\n        | undefined,\n      fn: context.fetchFn as () => Promise<TData>,\n      onCancel: (error) => {\n        if (error instanceof CancelledError && error.revert) {\n          this.setState({\n            ...this.#revertState,\n            fetchStatus: 'idle' as const,\n          })\n        }\n        abortController.abort()\n      },\n      onFail: (failureCount, error) => {\n        this.#dispatch({ type: 'failed', failureCount, error })\n      },\n      onPause: () => {\n        this.#dispatch({ type: 'pause' })\n      },\n      onContinue: () => {\n        this.#dispatch({ type: 'continue' })\n      },\n      retry: context.options.retry,\n      retryDelay: context.options.retryDelay,\n      networkMode: context.options.networkMode,\n      canRun: () => true,\n    }))\n\n    try {\n      const data = await retryer.start()\n      // this is more of a runtime guard\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n      if (data === undefined) {\n        if (process.env.NODE_ENV !== 'production') {\n          console.error(\n            `Query data cannot be undefined. Please make sure to return a value other than undefined from your query function. Affected query key: ${this.queryHash}`,\n          )\n        }\n        throw new Error(`${this.queryHash} data is undefined`)\n      }\n\n      this.setData(data)\n\n      // Notify cache callback\n      this.#cache.config.onSuccess?.(data, this as Query<any, any, any, any>)\n      this.#cache.config.onSettled?.(\n        data,\n        this.state.error as any,\n        this as Query<any, any, any, any>,\n      )\n      return data\n    } catch (error) {\n      if (error instanceof CancelledError) {\n        if (error.silent) {\n          // silent cancellation implies a new fetch is going to be started,\n          // so we piggyback onto that promise\n          return this.#retryer.promise\n        } else if (error.revert) {\n          // transform error into reverted state data\n          // if the initial fetch was cancelled, we have no data, so we have\n          // to get reject with a CancelledError\n          if (this.state.data === undefined) {\n            throw error\n          }\n          return this.state.data\n        }\n      }\n      this.#dispatch({\n        type: 'error',\n        error: error as TError,\n      })\n\n      // Notify cache callback\n      this.#cache.config.onError?.(\n        error as any,\n        this as Query<any, any, any, any>,\n      )\n      this.#cache.config.onSettled?.(\n        this.state.data,\n        error as any,\n        this as Query<any, any, any, any>,\n      )\n\n      throw error // rethrow the error for further handling\n    } finally {\n      // The settled retryer's promise would otherwise pin this fetch's raw\n      // result (a second copy after structural sharing) for the query's lifetime\n      if (this.#retryer === retryer) {\n        this.#retryer = undefined\n      }\n      // Schedule query gc after fetching\n      this.scheduleGc()\n    }\n  }\n\n  #dispatch(action: Action<TData, TError>): void {\n    const reducer = (\n      state: QueryState<TData, TError>,\n    ): QueryState<TData, TError> => {\n      switch (action.type) {\n        case 'failed':\n          return {\n            ...state,\n            fetchFailureCount: action.failureCount,\n            fetchFailureReason: action.error,\n          }\n        case 'pause':\n          return {\n            ...state,\n            fetchStatus: 'paused',\n          }\n        case 'continue':\n          return {\n            ...state,\n            fetchStatus: 'fetching',\n          }\n        case 'fetch':\n          return {\n            ...state,\n            ...fetchState(state.data, this.options),\n            fetchMeta: action.meta ?? null,\n          }\n        case 'success':\n          const newState = {\n            ...state,\n            ...successState(action.data, action.dataUpdatedAt),\n            dataUpdateCount: state.dataUpdateCount + 1,\n            ...(!action.manual && {\n              fetchStatus: 'idle' as const,\n              fetchFailureCount: 0,\n              fetchFailureReason: null,\n            }),\n          }\n          // If fetching ends successfully, we don't need revertState as a fallback anymore.\n          // For manual updates, capture the state to revert to it in case of a cancellation.\n          this.#revertState = action.manual ? newState : undefined\n\n          return newState\n        case 'error':\n          const error = action.error\n          return {\n            ...state,\n            error,\n            errorUpdateCount: state.errorUpdateCount + 1,\n            errorUpdatedAt: Date.now(),\n            fetchFailureCount: state.fetchFailureCount + 1,\n            fetchFailureReason: error,\n            fetchStatus: 'idle',\n            status: 'error',\n            // flag existing data as invalidated if we get a background error\n            // note that \"no data\" always means stale so we can set unconditionally here\n            isInvalidated: true,\n          }\n        case 'invalidate':\n          return {\n            ...state,\n            isInvalidated: true,\n          }\n        case 'setState':\n          return {\n            ...state,\n            ...action.state,\n          }\n      }\n    }\n\n    this.state = reducer(this.state)\n\n    notifyManager.batch(() => {\n      // Keep the current iteration stable if an observer unsubscribes\n      // synchronously while it is being notified.\n      this.observers.slice().forEach((observer) => {\n        observer.onQueryUpdate()\n      })\n\n      this.#cache.notify({ query: this, type: 'updated', action })\n    })\n  }\n}\n\nexport function fetchState<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey,\n>(\n  data: TData | undefined,\n  options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n) {\n  return {\n    fetchFailureCount: 0,\n    fetchFailureReason: null,\n    fetchStatus: canFetch(options.networkMode) ? 'fetching' : 'paused',\n    ...(data === undefined &&\n      ({\n        error: null,\n        status: 'pending',\n      } as const)),\n  } as const\n}\n\nfunction successState<TData>(data: TData | undefined, dataUpdatedAt?: number) {\n  return {\n    data,\n    dataUpdatedAt: dataUpdatedAt ?? Date.now(),\n    error: null,\n    isInvalidated: false,\n    status: 'success' as const,\n  }\n}\n\nfunction getDefaultState<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey,\n>(\n  options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n): QueryState<TData, TError> {\n  const data =\n    typeof options.initialData === 'function'\n      ? (options.initialData as InitialDataFunction<TData>)()\n      : options.initialData\n\n  const hasData = data !== undefined\n\n  const initialDataUpdatedAt = hasData\n    ? typeof options.initialDataUpdatedAt === 'function'\n      ? options.initialDataUpdatedAt()\n      : options.initialDataUpdatedAt\n    : 0\n\n  return {\n    data,\n    dataUpdateCount: 0,\n    dataUpdatedAt: hasData ? (initialDataUpdatedAt ?? Date.now()) : 0,\n    error: null,\n    errorUpdateCount: 0,\n    errorUpdatedAt: 0,\n    fetchFailureCount: 0,\n    fetchFailureReason: null,\n    fetchMeta: null,\n    isInvalidated: false,\n    status: hasData ? 'success' : 'pending',\n    fetchStatus: 'idle',\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"query.cjs","names":["Removable","#abortSignalConsumed","#defaultOptions","#client","#cache","#initialState","#queryType","#retryer","replaceData","#dispatch","noop","resolveQueryValue","skipToken","timeUntilStale","ensureQueryFn","infiniteQueryBehavior","#revertState","createRetryer","CancelledError","canFetch"],"sources":["../../src/query.ts"],"sourcesContent":["import {\n  ensureQueryFn,\n  noop,\n  replaceData,\n  resolveQueryValue,\n  skipToken,\n  timeUntilStale,\n} from './utils'\nimport { notifyManager } from './notifyManager'\nimport { CancelledError, canFetch, createRetryer } from './retryer'\nimport { Removable } from './removable'\nimport { infiniteQueryBehavior } from './infiniteQueryBehavior'\nimport type { QueryCache } from './queryCache'\nimport type { QueryClient } from './queryClient'\nimport type {\n  CancelOptions,\n  DefaultError,\n  FetchStatus,\n  InitialDataFunction,\n  OmitKeyof,\n  QueryFunctionContext,\n  QueryKey,\n  QueryMeta,\n  QueryOptions,\n  QueryStatus,\n  SetDataOptions,\n  StaleTime,\n} from './types'\nimport type { QueryObserver } from './queryObserver'\nimport type { Retryer } from './retryer'\n\n// TYPES\n\ninterface QueryConfig<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  client: QueryClient\n  queryKey: TQueryKey\n  queryHash: string\n  options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  defaultOptions?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  state?: QueryState<TData, TError>\n}\n\n/**\n * The raw state stored on a `Query` instance. This is the underlying state\n * that observer results (e.g. `QueryObserverResult`) are derived from.\n */\nexport interface QueryState<TData = unknown, TError = DefaultError> {\n  /**\n   * The last successfully resolved data for the query.\n   */\n  data: TData | undefined\n  /**\n   * The number of times the query has successfully resolved.\n   */\n  dataUpdateCount: number\n  /**\n   * The timestamp for when the query most recently returned the `status` as `\"success\"`.\n   */\n  dataUpdatedAt: number\n  /**\n   * The error object for the query, if the last attempt resulted in an error.\n   * - Defaults to `null`.\n   */\n  error: TError | null\n  /**\n   * The sum of all errors, incremented every time the query resolves with an error.\n   */\n  errorUpdateCount: number\n  /**\n   * The timestamp for when the query most recently returned the `status` as `\"error\"`.\n   */\n  errorUpdatedAt: number\n  /**\n   * The failure count for the current fetch.\n   * - Incremented every time the fetch fails.\n   * - Reset to `0` when the fetch succeeds.\n   */\n  fetchFailureCount: number\n  /**\n   * The reason the current fetch failed, as reported by the retryer.\n   * - Reset to `null` when the fetch succeeds.\n   */\n  fetchFailureReason: TError | null\n  /**\n   * Metadata passed to the currently in-flight (or most recent) fetch, e.g. the\n   * `fetchMore` direction for infinite queries.\n   */\n  fetchMeta: FetchMeta | null\n  /**\n   * Whether the query has been marked as invalidated via `invalidate()`.\n   * - Reset to `false` whenever the query resolves successfully.\n   */\n  isInvalidated: boolean\n  /**\n   * The status of the query.\n   * - `pending` if there's no cached data and no attempt was finished yet.\n   * - `error` if the last attempt resulted in an error.\n   * - `success` if the query has data.\n   */\n  status: QueryStatus\n  /**\n   * The fetch status of the query.\n   * - `fetching`: the `queryFn` is currently executing.\n   * - `paused`: a fetch wanted to run but has been paused (see network mode).\n   * - `idle`: the query is not fetching.\n   */\n  fetchStatus: FetchStatus\n}\n\nexport interface FetchContext<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  fetchFn: () => unknown | Promise<unknown>\n  fetchOptions?: FetchOptions\n  signal: AbortSignal\n  options: QueryOptions<TQueryFnData, TError, TData, any>\n  client: QueryClient\n  queryKey: TQueryKey\n  state: QueryState<TData, TError>\n}\n\nexport interface QueryBehavior<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> {\n  onFetch: (\n    context: FetchContext<TQueryFnData, TError, TData, TQueryKey>,\n    query: Query,\n  ) => void\n}\n\nexport type FetchDirection = 'forward' | 'backward'\n\nexport interface FetchMeta {\n  fetchMore?: { direction: FetchDirection }\n}\n\nexport interface FetchOptions<TData = unknown> {\n  cancelRefetch?: boolean\n  meta?: FetchMeta\n  initialPromise?: Promise<TData>\n}\n\ninterface FailedAction<TError> {\n  type: 'failed'\n  failureCount: number\n  error: TError\n}\n\ninterface FetchAction {\n  type: 'fetch'\n  meta?: FetchMeta\n}\n\ninterface SuccessAction<TData> {\n  data: TData | undefined\n  type: 'success'\n  dataUpdatedAt?: number\n  manual?: boolean\n}\n\ninterface ErrorAction<TError> {\n  type: 'error'\n  error: TError\n}\n\ninterface InvalidateAction {\n  type: 'invalidate'\n}\n\ninterface PauseAction {\n  type: 'pause'\n}\n\ninterface ContinueAction {\n  type: 'continue'\n}\n\ninterface SetStateAction<TData, TError> {\n  type: 'setState'\n  state: Partial<QueryState<TData, TError>>\n}\n\nexport type Action<TData, TError> =\n  | ContinueAction\n  | ErrorAction<TError>\n  | FailedAction<TError>\n  | FetchAction\n  | InvalidateAction\n  | PauseAction\n  | SetStateAction<TData, TError>\n  | SuccessAction<TData>\n\n// CLASS\n\n/**\n * Represents a single cached query. A `Query` holds the query's key, options,\n * state (data/error/status), and the observers currently subscribed to it.\n *\n * Instances are created and managed internally by `QueryCache`; application\n * code typically interacts with queries indirectly through `QueryClient` or\n * a framework hook like `useQuery`. Direct access to a `Query` instance is\n * possible via `queryCache.find()`/`findAll()` for inspecting cache state.\n *\n * @example\n * ```ts\n * const queryCache = queryClient.getQueryCache()\n * const query = queryCache.find({ queryKey: ['posts'] })\n *\n * if (query) {\n *   console.log(query.state.dataUpdatedAt)\n * }\n * ```\n */\nexport class Query<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> extends Removable {\n  queryKey: TQueryKey\n  queryHash: string\n  options!: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  state: QueryState<TData, TError>\n  #queryType?: 'infinite'\n\n  #initialState: QueryState<TData, TError>\n  #revertState?: QueryState<TData, TError>\n  #cache: QueryCache\n  #client: QueryClient\n  #retryer?: Retryer<TData>\n  observers: Array<QueryObserver<any, any, any, any, any>>\n  #defaultOptions?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>\n  #abortSignalConsumed: boolean\n\n  constructor(config: QueryConfig<TQueryFnData, TError, TData, TQueryKey>) {\n    super()\n\n    this.#abortSignalConsumed = false\n    this.#defaultOptions = config.defaultOptions\n    this.setOptions(config.options)\n    this.observers = []\n    this.#client = config.client\n    this.#cache = this.#client.getQueryCache()\n    this.queryKey = config.queryKey\n    this.queryHash = config.queryHash\n    this.#initialState = getDefaultState(this.options)\n    this.state = config.state ?? this.#initialState\n    this.scheduleGc()\n  }\n  /**\n   * The `meta` object passed in the query's options, if any.\n   */\n  get meta(): QueryMeta | undefined {\n    return this.options.meta\n  }\n\n  /** @internal */\n  get queryType() {\n    return this.#queryType\n  }\n\n  /**\n   * The promise for the currently in-flight fetch, if the query is fetching.\n   * `undefined` when the query is not fetching.\n   */\n  get promise(): Promise<TData> | undefined {\n    return this.#retryer?.promise\n  }\n\n  /** @internal */\n  setOptions(\n    options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  ): void {\n    this.options = { ...this.#defaultOptions, ...options }\n\n    if (options?._type) {\n      this.#queryType = options._type\n    }\n\n    this.updateGcTime(this.options.gcTime)\n\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n    if (this.state && this.state.data === undefined) {\n      const defaultState = getDefaultState(this.options)\n      if (defaultState.data !== undefined) {\n        this.setState(\n          successState(defaultState.data, defaultState.dataUpdatedAt),\n        )\n        this.#initialState = defaultState\n      }\n    }\n  }\n\n  protected optionalRemove() {\n    if (!this.observers.length && this.state.fetchStatus === 'idle') {\n      this.#cache.remove(this)\n    }\n  }\n\n  /** @internal */\n  setData(\n    newData: TData,\n    options?: SetDataOptions & { manual: boolean },\n  ): TData {\n    const data = replaceData(this.state.data, newData, this.options)\n\n    // Set data and mark it as cached\n    this.#dispatch({\n      data,\n      type: 'success',\n      dataUpdatedAt: options?.updatedAt,\n      manual: options?.manual,\n    })\n\n    return data\n  }\n\n  /**\n   * Merges the given partial state directly into this query's state, notifying observers. Used\n   * by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a\n   * user manually trigger a loading/error state or edit the cached data.\n   */\n  setState(state: Partial<QueryState<TData, TError>>): void {\n    this.#dispatch({ type: 'setState', state })\n  }\n\n  /**\n   * Cancels the query's currently in-flight fetch, if any.\n   * - Returns a promise that resolves once the cancellation has settled.\n   * - If no fetch is in progress, resolves immediately.\n   *\n   * @example\n   * ```ts\n   * await query.cancel()\n   * ```\n   */\n  cancel(options?: CancelOptions): Promise<void> {\n    const promise = this.#retryer?.promise\n    this.#retryer?.cancel(options)\n    return promise ? promise.then(noop).catch(noop) : Promise.resolve()\n  }\n\n  /**\n   * Clears the query's garbage collection timeout and silently cancels any\n   * in-flight fetch. Called by `QueryCache` when the query is removed from\n   * the cache.\n   *\n   * @see {@link Query#cancel}\n   */\n  destroy(): void {\n    super.destroy()\n\n    this.cancel({ silent: true })\n  }\n\n  /** @internal */\n  get resetState(): QueryState<TData, TError> {\n    return this.#initialState\n  }\n\n  /**\n   * Resets the query back to its initial state (the state it had when it was\n   * first created, e.g. any `initialData`), destroying it first to cancel any\n   * in-flight fetch.\n   */\n  reset(): void {\n    this.destroy()\n    this.setState(this.resetState)\n  }\n\n  /**\n   * Returns `true` if the query has at least one observer for which `enabled`\n   * does not resolve to `false`.\n   */\n  isActive(): boolean {\n    return this.observers.some(\n      (observer) => resolveQueryValue(observer.options.enabled, this) !== false,\n    )\n  }\n\n  /**\n   * Returns `true` if the query is disabled, meaning it will not fetch\n   * automatically.\n   * - If the query has observers, it is disabled when none of them are active\n   *   (see `isActive`).\n   * - If the query has no observers, it is disabled when its `queryFn` is\n   *   `skipToken` or it has never been fetched.\n   */\n  isDisabled(): boolean {\n    if (this.getObserversCount() > 0) {\n      return !this.isActive()\n    }\n    // if a query has no observers, it should still be considered disabled if it never attempted a fetch\n    return this.options.queryFn === skipToken || !this.isFetched()\n  }\n\n  /**\n   * Returns `true` if the query has been fetched, i.e. it has resolved with\n   * either data or an error at least once.\n   */\n  isFetched() {\n    return this.state.dataUpdateCount + this.state.errorUpdateCount > 0\n  }\n\n  /**\n   * Returns `true` if the query has at least one observer configured with\n   * `staleTime: 'static'`, meaning it is treated as never stale.\n   */\n  isStatic(): boolean {\n    if (this.getObserversCount() > 0) {\n      return this.observers.some(\n        (observer) =>\n          resolveQueryValue(observer.options.staleTime, this) === 'static',\n      )\n    }\n\n    return false\n  }\n\n  /**\n   * Returns `true` if the query is stale.\n   * - If the query has observers, defers to whether any observer's current\n   *   result reports `isStale` (which accounts for each observer's own\n   *   `staleTime` and `enabled` state).\n   * - If the query has no observers, it is considered stale when it has no\n   *   data or has been invalidated.\n   *\n   * @see {@link Query#isStaleByTime}\n   * @example\n   * ```ts\n   * if (query.isStale()) {\n   *   // refetch or otherwise treat the cached data as outdated\n   * }\n   * ```\n   */\n  isStale(): boolean {\n    // check observers first, their `isStale` has the source of truth\n    // calculated with `isStaleByTime` and it takes `enabled` into account\n    if (this.getObserversCount() > 0) {\n      return this.observers.some(\n        (observer) => observer.getCurrentResult().isStale,\n      )\n    }\n\n    return this.state.data === undefined || this.state.isInvalidated\n  }\n\n  /**\n   * Returns `true` if the query's data is stale relative to the given\n   * `staleTime` (defaults to `0`).\n   * - A query with no data is always stale.\n   * - `staleTime: 'static'` is never stale.\n   * - An invalidated query is always stale.\n   * - Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.\n   *\n   * @see {@link Query#isStale}\n   * @example\n   * ```ts\n   * const isStale = query.isStaleByTime(1000 * 60)\n   * ```\n   */\n  isStaleByTime(staleTime: StaleTime = 0): boolean {\n    // no data is always stale\n    if (this.state.data === undefined) {\n      return true\n    }\n    // static is never stale\n    if (staleTime === 'static') {\n      return false\n    }\n    // if the query is invalidated, it is stale\n    if (this.state.isInvalidated) {\n      return true\n    }\n\n    return !timeUntilStale(this.state.dataUpdatedAt, staleTime)\n  }\n\n  /** @internal */\n  onFocus(): void {\n    const observer = this.observers.find((x) => x.shouldFetchOnWindowFocus())\n\n    observer?.refetch({ cancelRefetch: false })\n\n    // Continue fetch if currently paused\n    this.#retryer?.continue()\n  }\n\n  /** @internal */\n  onOnline(): void {\n    const observer = this.observers.find((x) => x.shouldFetchOnReconnect())\n\n    observer?.refetch({ cancelRefetch: false })\n\n    // Continue fetch if currently paused\n    this.#retryer?.continue()\n  }\n\n  /** @internal */\n  addObserver(observer: QueryObserver<any, any, any, any, any>): void {\n    if (!this.observers.includes(observer)) {\n      this.observers.push(observer)\n\n      // Stop the query from being garbage collected\n      this.clearGcTimeout()\n\n      this.#cache.notify({ type: 'observerAdded', query: this, observer })\n    }\n  }\n\n  /** @internal */\n  removeObserver(observer: QueryObserver<any, any, any, any, any>): void {\n    const index = this.observers.indexOf(observer)\n    if (index !== -1) {\n      this.observers.splice(index, 1)\n\n      if (!this.observers.length) {\n        // If the transport layer does not support cancellation\n        // we'll let the query continue so the result can be cached\n        if (this.#retryer) {\n          if (\n            this.#abortSignalConsumed ||\n            (this.state.fetchStatus === 'paused' &&\n              this.state.status === 'pending')\n          ) {\n            this.#retryer.cancel({ revert: true })\n          } else {\n            this.#retryer.cancelRetry()\n          }\n        }\n\n        this.scheduleGc()\n      }\n\n      this.#cache.notify({ type: 'observerRemoved', query: this, observer })\n    }\n  }\n\n  /**\n   * Returns the number of observers currently subscribed to this query.\n   *\n   * @example\n   * ```ts\n   * if (query.getObserversCount() === 0) {\n   *   // no component is currently watching this query\n   * }\n   * ```\n   */\n  getObserversCount(): number {\n    return this.observers.length\n  }\n\n  /**\n   * Marks the query as invalidated, unless it is already invalidated. This\n   * updates `state.isInvalidated` and notifies observers, but does not by\n   * itself trigger a refetch.\n   *\n   * @example\n   * ```ts\n   * query.invalidate()\n   * ```\n   */\n  invalidate(): void {\n    if (!this.state.isInvalidated) {\n      this.#dispatch({ type: 'invalidate' })\n    }\n  }\n\n  /**\n   * Fetches the query, i.e. runs its `queryFn` (through any configured\n   * retryer/behavior) and updates the query's state with the result.\n   * - If a fetch is already in flight, returns its promise instead of\n   *   starting a new one, unless `fetchOptions.cancelRefetch` is set and the\n   *   query already has data, in which case the current fetch is silently\n   *   cancelled first.\n   * - If `options` is passed, it replaces the query's current options\n   *   before fetching.\n   */\n  async fetch(\n    options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n    fetchOptions?: FetchOptions<TQueryFnData>,\n  ): Promise<TData> {\n    if (\n      this.state.fetchStatus !== 'idle' &&\n      // If the promise in the retryer is already rejected, we have to definitely\n      // re-start the fetch; there is a chance that the query is still in a\n      // pending state when that happens\n      this.#retryer?.status() !== 'rejected'\n    ) {\n      if (this.state.data !== undefined && fetchOptions?.cancelRefetch) {\n        // Silently cancel current fetch if the user wants to cancel refetch\n        this.cancel({ silent: true })\n      } else if (this.#retryer) {\n        // make sure that retries that were potentially cancelled due to unmounts can continue\n        this.#retryer.continueRetry()\n        // Return current promise if we are already fetching\n        return this.#retryer.promise\n      }\n    }\n\n    // Update config if passed, otherwise the config from the last execution is used\n    if (options) {\n      this.setOptions(options)\n    }\n\n    // Use the options from the first observer with a query function if no function is found.\n    // This can happen when the query is hydrated or created with setQueryData.\n    if (!this.options.queryFn) {\n      const observer = this.observers.find((x) => x.options.queryFn)\n      if (observer) {\n        this.setOptions(observer.options)\n      }\n    }\n\n    if (process.env.NODE_ENV !== 'production') {\n      if (!Array.isArray(this.options.queryKey)) {\n        console.error(\n          `As of v4, queryKey needs to be an Array. If you are using a string like 'repoData', please change it to an Array, e.g. ['repoData']`,\n        )\n      }\n    }\n\n    const abortController = new AbortController()\n\n    // Adds an enumerable signal property to the object that\n    // which sets abortSignalConsumed to true when the signal\n    // is read.\n    const addSignalProperty = (object: unknown) => {\n      Object.defineProperty(object, 'signal', {\n        enumerable: true,\n        get: () => {\n          this.#abortSignalConsumed = true\n          return abortController.signal\n        },\n      })\n    }\n\n    // Create fetch function\n    const fetchFn = () => {\n      const queryFn = ensureQueryFn(this.options, fetchOptions)\n\n      // Create query function context\n      const createQueryFnContext = (): QueryFunctionContext<TQueryKey> => {\n        const queryFnContext: OmitKeyof<\n          QueryFunctionContext<TQueryKey>,\n          'signal'\n        > = {\n          client: this.#client,\n          queryKey: this.queryKey,\n          meta: this.meta,\n        }\n        addSignalProperty(queryFnContext)\n        return queryFnContext as QueryFunctionContext<TQueryKey>\n      }\n\n      const queryFnContext = createQueryFnContext()\n\n      this.#abortSignalConsumed = false\n      if (this.options.persister) {\n        return this.options.persister(\n          queryFn,\n          queryFnContext,\n          this as unknown as Query,\n        )\n      }\n\n      return queryFn(queryFnContext)\n    }\n\n    // Trigger behavior hook\n    const createFetchContext = (): FetchContext<\n      TQueryFnData,\n      TError,\n      TData,\n      TQueryKey\n    > => {\n      const context: OmitKeyof<\n        FetchContext<TQueryFnData, TError, TData, TQueryKey>,\n        'signal'\n      > = {\n        fetchOptions,\n        options: this.options,\n        queryKey: this.queryKey,\n        client: this.#client,\n        state: this.state,\n        fetchFn,\n      }\n\n      addSignalProperty(context)\n      return context as FetchContext<TQueryFnData, TError, TData, TQueryKey>\n    }\n\n    const context = createFetchContext()\n\n    const behavior =\n      this.#queryType === 'infinite'\n        ? (infiniteQueryBehavior(\n            (this.options as { pages?: number }).pages,\n          ) as QueryBehavior<TQueryFnData, TError, TData, TQueryKey>)\n        : this.options.behavior\n    behavior?.onFetch(context, this as unknown as Query)\n\n    // Store state in case the current fetch needs to be reverted\n    this.#revertState = this.state\n\n    // Set to fetching state if not already in it\n    if (\n      this.state.fetchStatus === 'idle' ||\n      this.state.fetchMeta !== context.fetchOptions?.meta\n    ) {\n      this.#dispatch({ type: 'fetch', meta: context.fetchOptions?.meta })\n    }\n\n    // Try to fetch the data\n    const retryer = (this.#retryer = createRetryer({\n      initialPromise: fetchOptions?.initialPromise as\n        | Promise<TData>\n        | undefined,\n      fn: context.fetchFn as () => Promise<TData>,\n      onCancel: (error) => {\n        if (error instanceof CancelledError && error.revert) {\n          this.setState({\n            ...this.#revertState,\n            fetchStatus: 'idle' as const,\n          })\n        }\n        abortController.abort()\n      },\n      onFail: (failureCount, error) => {\n        this.#dispatch({ type: 'failed', failureCount, error })\n      },\n      onPause: () => {\n        this.#dispatch({ type: 'pause' })\n      },\n      onContinue: () => {\n        this.#dispatch({ type: 'continue' })\n      },\n      retry: context.options.retry,\n      retryDelay: context.options.retryDelay,\n      networkMode: context.options.networkMode,\n      canRun: () => true,\n    }))\n\n    try {\n      const data = await retryer.start()\n      // this is more of a runtime guard\n      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n      if (data === undefined) {\n        if (process.env.NODE_ENV !== 'production') {\n          console.error(\n            `Query data cannot be undefined. Please make sure to return a value other than undefined from your query function. Affected query key: ${this.queryHash}`,\n          )\n        }\n        throw new Error(`${this.queryHash} data is undefined`)\n      }\n\n      this.setData(data)\n\n      // Notify cache callback\n      this.#cache.config.onSuccess?.(data, this as Query<any, any, any, any>)\n      this.#cache.config.onSettled?.(\n        data,\n        this.state.error as any,\n        this as Query<any, any, any, any>,\n      )\n      return data\n    } catch (error) {\n      if (error instanceof CancelledError) {\n        if (error.silent) {\n          // silent cancellation implies a new fetch is going to be started,\n          // so we piggyback onto that promise\n          return this.#retryer.promise\n        } else if (error.revert) {\n          // transform error into reverted state data\n          // if the initial fetch was cancelled, we have no data, so we have\n          // to get reject with a CancelledError\n          if (this.state.data === undefined) {\n            throw error\n          }\n          return this.state.data\n        }\n      }\n      this.#dispatch({\n        type: 'error',\n        error: error as TError,\n      })\n\n      // Notify cache callback\n      this.#cache.config.onError?.(\n        error as any,\n        this as Query<any, any, any, any>,\n      )\n      this.#cache.config.onSettled?.(\n        this.state.data,\n        error as any,\n        this as Query<any, any, any, any>,\n      )\n\n      throw error // rethrow the error for further handling\n    } finally {\n      // The settled retryer's promise would otherwise pin this fetch's raw\n      // result (a second copy after structural sharing) for the query's lifetime\n      if (this.#retryer === retryer) {\n        this.#retryer = undefined\n      }\n      // Schedule query gc after fetching\n      this.scheduleGc()\n    }\n  }\n\n  #dispatch(action: Action<TData, TError>): void {\n    const reducer = (\n      state: QueryState<TData, TError>,\n    ): QueryState<TData, TError> => {\n      switch (action.type) {\n        case 'failed':\n          return {\n            ...state,\n            fetchFailureCount: action.failureCount,\n            fetchFailureReason: action.error,\n          }\n        case 'pause':\n          return {\n            ...state,\n            fetchStatus: 'paused',\n          }\n        case 'continue':\n          return {\n            ...state,\n            fetchStatus: 'fetching',\n          }\n        case 'fetch':\n          return {\n            ...state,\n            ...fetchState(state.data, this.options),\n            fetchMeta: action.meta ?? null,\n          }\n        case 'success':\n          const newState = {\n            ...state,\n            ...successState(action.data, action.dataUpdatedAt),\n            dataUpdateCount: state.dataUpdateCount + 1,\n            ...(!action.manual && {\n              fetchStatus: 'idle' as const,\n              fetchFailureCount: 0,\n              fetchFailureReason: null,\n            }),\n          }\n          // If fetching ends successfully, we don't need revertState as a fallback anymore.\n          // For manual updates, capture the state to revert to it in case of a cancellation.\n          this.#revertState = action.manual ? newState : undefined\n\n          return newState\n        case 'error':\n          const error = action.error\n          return {\n            ...state,\n            error,\n            errorUpdateCount: state.errorUpdateCount + 1,\n            errorUpdatedAt: Date.now(),\n            fetchFailureCount: state.fetchFailureCount + 1,\n            fetchFailureReason: error,\n            fetchStatus: 'idle',\n            status: 'error',\n            // flag existing data as invalidated if we get a background error\n            // note that \"no data\" always means stale so we can set unconditionally here\n            isInvalidated: true,\n          }\n        case 'invalidate':\n          return {\n            ...state,\n            isInvalidated: true,\n          }\n        case 'setState':\n          return {\n            ...state,\n            ...action.state,\n          }\n      }\n    }\n\n    this.state = reducer(this.state)\n\n    notifyManager.batch(() => {\n      // Keep the current iteration stable if an observer unsubscribes\n      // synchronously while it is being notified.\n      this.observers.slice().forEach((observer) => {\n        observer.onQueryUpdate()\n      })\n\n      this.#cache.notify({ query: this, type: 'updated', action })\n    })\n  }\n}\n\nexport function fetchState<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey,\n>(\n  data: TData | undefined,\n  options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n) {\n  return {\n    fetchFailureCount: 0,\n    fetchFailureReason: null,\n    fetchStatus: canFetch(options.networkMode) ? 'fetching' : 'paused',\n    ...(data === undefined &&\n      ({\n        error: null,\n        status: 'pending',\n      } as const)),\n  } as const\n}\n\nfunction successState<TData>(data: TData | undefined, dataUpdatedAt?: number) {\n  return {\n    data,\n    dataUpdatedAt: dataUpdatedAt ?? Date.now(),\n    error: null,\n    isInvalidated: false,\n    status: 'success' as const,\n  }\n}\n\nfunction getDefaultState<\n  TQueryFnData,\n  TError,\n  TData,\n  TQueryKey extends QueryKey,\n>(\n  options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n): QueryState<TData, TError> {\n  const data =\n    typeof options.initialData === 'function'\n      ? (options.initialData as InitialDataFunction<TData>)()\n      : options.initialData\n\n  const hasData = data !== undefined\n\n  const initialDataUpdatedAt = hasData\n    ? typeof options.initialDataUpdatedAt === 'function'\n      ? options.initialDataUpdatedAt()\n      : options.initialDataUpdatedAt\n    : 0\n\n  return {\n    data,\n    dataUpdateCount: 0,\n    dataUpdatedAt: hasData ? (initialDataUpdatedAt ?? Date.now()) : 0,\n    error: null,\n    errorUpdateCount: 0,\n    errorUpdatedAt: 0,\n    fetchFailureCount: 0,\n    fetchFailureReason: null,\n    fetchMeta: null,\n    isInvalidated: false,\n    status: hasData ? 'success' : 'pending',\n    fetchStatus: 'idle',\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAgOA,IAAa,QAAb,cAKUA,kBAAAA,UAAU;CAKlB;CAEA;CACA;CACA;CACA;CACA;CAEA;CACA;CAEA,YAAY,QAA6D;EACvE,MAAM;EAEN,KAAKC,uBAAuB;EAC5B,KAAKC,kBAAkB,OAAO;EAC9B,KAAK,WAAW,OAAO,OAAO;EAC9B,KAAK,YAAY,CAAC;EAClB,KAAKC,UAAU,OAAO;EACtB,KAAKC,SAAS,KAAKD,QAAQ,cAAc;EACzC,KAAK,WAAW,OAAO;EACvB,KAAK,YAAY,OAAO;EACxB,KAAKE,gBAAgB,gBAAgB,KAAK,OAAO;EACjD,KAAK,QAAQ,OAAO,SAAS,KAAKA;EAClC,KAAK,WAAW;CAClB;;;;CAIA,IAAI,OAA8B;EAChC,OAAO,KAAK,QAAQ;CACtB;;CAGA,IAAI,YAAY;EACd,OAAO,KAAKC;CACd;;;;;CAMA,IAAI,UAAsC;EACxC,OAAO,KAAKC,UAAU;CACxB;;CAGA,WACE,SACM;EACN,KAAK,UAAU;GAAE,GAAG,KAAKL;GAAiB,GAAG;EAAQ;EAErD,IAAI,SAAS,OACX,KAAKI,aAAa,QAAQ;EAG5B,KAAK,aAAa,KAAK,QAAQ,MAAM;EAGrC,IAAI,KAAK,SAAS,KAAK,MAAM,SAAS,KAAA,GAAW;GAC/C,MAAM,eAAe,gBAAgB,KAAK,OAAO;GACjD,IAAI,aAAa,SAAS,KAAA,GAAW;IACnC,KAAK,SACH,aAAa,aAAa,MAAM,aAAa,aAAa,CAC5D;IACA,KAAKD,gBAAgB;GACvB;EACF;CACF;CAEA,iBAA2B;EACzB,IAAI,CAAC,KAAK,UAAU,UAAU,KAAK,MAAM,gBAAgB,QACvD,KAAKD,OAAO,OAAO,IAAI;CAE3B;;CAGA,QACE,SACA,SACO;EACP,MAAM,OAAOI,cAAAA,YAAY,KAAK,MAAM,MAAM,SAAS,KAAK,OAAO;EAG/D,KAAKC,UAAU;GACb;GACA,MAAM;GACN,eAAe,SAAS;GACxB,QAAQ,SAAS;EACnB,CAAC;EAED,OAAO;CACT;;;;;;CAOA,SAAS,OAAiD;EACxD,KAAKA,UAAU;GAAE,MAAM;GAAY;EAAM,CAAC;CAC5C;;;;;;;;;;;CAYA,OAAO,SAAwC;EAC7C,MAAM,UAAU,KAAKF,UAAU;EAC/B,KAAKA,UAAU,OAAO,OAAO;EAC7B,OAAO,UAAU,QAAQ,KAAKG,cAAAA,IAAI,CAAC,CAAC,MAAMA,cAAAA,IAAI,IAAI,QAAQ,QAAQ;CACpE;;;;;;;;CASA,UAAgB;EACd,MAAM,QAAQ;EAEd,KAAK,OAAO,EAAE,QAAQ,KAAK,CAAC;CAC9B;;CAGA,IAAI,aAAwC;EAC1C,OAAO,KAAKL;CACd;;;;;;CAOA,QAAc;EACZ,KAAK,QAAQ;EACb,KAAK,SAAS,KAAK,UAAU;CAC/B;;;;;CAMA,WAAoB;EAClB,OAAO,KAAK,UAAU,MACnB,aAAaM,cAAAA,kBAAkB,SAAS,QAAQ,SAAS,IAAI,MAAM,KACtE;CACF;;;;;;;;;CAUA,aAAsB;EACpB,IAAI,KAAK,kBAAkB,IAAI,GAC7B,OAAO,CAAC,KAAK,SAAS;EAGxB,OAAO,KAAK,QAAQ,YAAYC,cAAAA,aAAa,CAAC,KAAK,UAAU;CAC/D;;;;;CAMA,YAAY;EACV,OAAO,KAAK,MAAM,kBAAkB,KAAK,MAAM,mBAAmB;CACpE;;;;;CAMA,WAAoB;EAClB,IAAI,KAAK,kBAAkB,IAAI,GAC7B,OAAO,KAAK,UAAU,MACnB,aACCD,cAAAA,kBAAkB,SAAS,QAAQ,WAAW,IAAI,MAAM,QAC5D;EAGF,OAAO;CACT;;;;;;;;;;;;;;;;;CAkBA,UAAmB;EAGjB,IAAI,KAAK,kBAAkB,IAAI,GAC7B,OAAO,KAAK,UAAU,MACnB,aAAa,SAAS,iBAAiB,CAAC,CAAC,OAC5C;EAGF,OAAO,KAAK,MAAM,SAAS,KAAA,KAAa,KAAK,MAAM;CACrD;;;;;;;;;;;;;;;CAgBA,cAAc,YAAuB,GAAY;EAE/C,IAAI,KAAK,MAAM,SAAS,KAAA,GACtB,OAAO;EAGT,IAAI,cAAc,UAChB,OAAO;EAGT,IAAI,KAAK,MAAM,eACb,OAAO;EAGT,OAAO,CAACE,cAAAA,eAAe,KAAK,MAAM,eAAe,SAAS;CAC5D;;CAGA,UAAgB;EAGd,KAFsB,UAAU,MAAM,MAAM,EAAE,yBAAyB,CAEhE,CAAC,EAAE,QAAQ,EAAE,eAAe,MAAM,CAAC;EAG1C,KAAKN,UAAU,SAAS;CAC1B;;CAGA,WAAiB;EAGf,KAFsB,UAAU,MAAM,MAAM,EAAE,uBAAuB,CAE9D,CAAC,EAAE,QAAQ,EAAE,eAAe,MAAM,CAAC;EAG1C,KAAKA,UAAU,SAAS;CAC1B;;CAGA,YAAY,UAAwD;EAClE,IAAI,CAAC,KAAK,UAAU,SAAS,QAAQ,GAAG;GACtC,KAAK,UAAU,KAAK,QAAQ;GAG5B,KAAK,eAAe;GAEpB,KAAKH,OAAO,OAAO;IAAE,MAAM;IAAiB,OAAO;IAAM;GAAS,CAAC;EACrE;CACF;;CAGA,eAAe,UAAwD;EACrE,MAAM,QAAQ,KAAK,UAAU,QAAQ,QAAQ;EAC7C,IAAI,UAAU,IAAI;GAChB,KAAK,UAAU,OAAO,OAAO,CAAC;GAE9B,IAAI,CAAC,KAAK,UAAU,QAAQ;IAG1B,IAAI,KAAKG,UAAU;KACjB,IACE,KAAKN,wBACJ,KAAK,MAAM,gBAAgB,YAC1B,KAAK,MAAM,WAAW,WAExB,KAAKM,SAAS,OAAO,EAAE,QAAQ,KAAK,CAAC;UAErC,KAAKA,SAAS,YAAY;IAE9B;IAEA,KAAK,WAAW;GAClB;GAEA,KAAKH,OAAO,OAAO;IAAE,MAAM;IAAmB,OAAO;IAAM;GAAS,CAAC;EACvE;CACF;;;;;;;;;;;CAYA,oBAA4B;EAC1B,OAAO,KAAK,UAAU;CACxB;;;;;;;;;;;CAYA,aAAmB;EACjB,IAAI,CAAC,KAAK,MAAM,eACd,KAAKK,UAAU,EAAE,MAAM,aAAa,CAAC;CAEzC;;;;;;;;;;;CAYA,MAAM,MACJ,SACA,cACgB;EAChB,IACE,KAAK,MAAM,gBAAgB,UAI3B,KAAKF,UAAU,OAAO,MAAM,YAC5B;GACA,IAAI,KAAK,MAAM,SAAS,KAAA,KAAa,cAAc,eAEjD,KAAK,OAAO,EAAE,QAAQ,KAAK,CAAC;QACvB,IAAI,KAAKA,UAAU;IAExB,KAAKA,SAAS,cAAc;IAE5B,OAAO,KAAKA,SAAS;GACvB;EACF;EAGA,IAAI,SACF,KAAK,WAAW,OAAO;EAKzB,IAAI,CAAC,KAAK,QAAQ,SAAS;GACzB,MAAM,WAAW,KAAK,UAAU,MAAM,MAAM,EAAE,QAAQ,OAAO;GAC7D,IAAI,UACF,KAAK,WAAW,SAAS,OAAO;EAEpC;EAEA,IAAI,QAAQ,IAAI,aAAa,cACvB;OAAA,CAAC,MAAM,QAAQ,KAAK,QAAQ,QAAQ,GACtC,QAAQ,MACN,qIACF;EAAA;EAIJ,MAAM,kBAAkB,IAAI,gBAAgB;EAK5C,MAAM,qBAAqB,WAAoB;GAC7C,OAAO,eAAe,QAAQ,UAAU;IACtC,YAAY;IACZ,WAAW;KACT,KAAKN,uBAAuB;KAC5B,OAAO,gBAAgB;IACzB;GACF,CAAC;EACH;EAGA,MAAM,gBAAgB;GACpB,MAAM,UAAUa,cAAAA,cAAc,KAAK,SAAS,YAAY;GAGxD,MAAM,6BAA8D;IAClE,MAAM,iBAGF;KACF,QAAQ,KAAKX;KACb,UAAU,KAAK;KACf,MAAM,KAAK;IACb;IACA,kBAAkB,cAAc;IAChC,OAAO;GACT;GAEA,MAAM,iBAAiB,qBAAqB;GAE5C,KAAKF,uBAAuB;GAC5B,IAAI,KAAK,QAAQ,WACf,OAAO,KAAK,QAAQ,UAClB,SACA,gBACA,IACF;GAGF,OAAO,QAAQ,cAAc;EAC/B;EAGA,MAAM,2BAKD;GACH,MAAM,UAGF;IACF;IACA,SAAS,KAAK;IACd,UAAU,KAAK;IACf,QAAQ,KAAKE;IACb,OAAO,KAAK;IACZ;GACF;GAEA,kBAAkB,OAAO;GACzB,OAAO;EACT;EAEA,MAAM,UAAU,mBAAmB;EAQnC,CALE,KAAKG,eAAe,aACfS,8BAAAA,sBACE,KAAK,QAA+B,KACvC,IACA,KAAK,QAAQ,SAAA,EACT,QAAQ,SAAS,IAAwB;EAGnD,KAAKC,eAAe,KAAK;EAGzB,IACE,KAAK,MAAM,gBAAgB,UAC3B,KAAK,MAAM,cAAc,QAAQ,cAAc,MAE/C,KAAKP,UAAU;GAAE,MAAM;GAAS,MAAM,QAAQ,cAAc;EAAK,CAAC;EAIpE,MAAM,UAAW,KAAKF,WAAWU,gBAAAA,cAAc;GAC7C,gBAAgB,cAAc;GAG9B,IAAI,QAAQ;GACZ,WAAW,UAAU;IACnB,IAAI,iBAAiBC,gBAAAA,kBAAkB,MAAM,QAC3C,KAAK,SAAS;KACZ,GAAG,KAAKF;KACR,aAAa;IACf,CAAC;IAEH,gBAAgB,MAAM;GACxB;GACA,SAAS,cAAc,UAAU;IAC/B,KAAKP,UAAU;KAAE,MAAM;KAAU;KAAc;IAAM,CAAC;GACxD;GACA,eAAe;IACb,KAAKA,UAAU,EAAE,MAAM,QAAQ,CAAC;GAClC;GACA,kBAAkB;IAChB,KAAKA,UAAU,EAAE,MAAM,WAAW,CAAC;GACrC;GACA,OAAO,QAAQ,QAAQ;GACvB,YAAY,QAAQ,QAAQ;GAC5B,aAAa,QAAQ,QAAQ;GAC7B,cAAc;EAChB,CAAC;EAED,IAAI;GACF,MAAM,OAAO,MAAM,QAAQ,MAAM;GAGjC,IAAI,SAAS,KAAA,GAAW;IACtB,IAAI,QAAQ,IAAI,aAAa,cAC3B,QAAQ,MACN,yIAAyI,KAAK,WAChJ;IAEF,MAAM,IAAI,MAAM,GAAG,KAAK,UAAU,mBAAmB;GACvD;GAEA,KAAK,QAAQ,IAAI;GAGjB,KAAKL,OAAO,OAAO,YAAY,MAAM,IAAiC;GACtE,KAAKA,OAAO,OAAO,YACjB,MACA,KAAK,MAAM,OACX,IACF;GACA,OAAO;EACT,SAAS,OAAO;GACd,IAAI,iBAAiBc,gBAAAA,gBAAgB;IACnC,IAAI,MAAM,QAGR,OAAO,KAAKX,SAAS;SAChB,IAAI,MAAM,QAAQ;KAIvB,IAAI,KAAK,MAAM,SAAS,KAAA,GACtB,MAAM;KAER,OAAO,KAAK,MAAM;IACpB;GACF;GACA,KAAKE,UAAU;IACb,MAAM;IACC;GACT,CAAC;GAGD,KAAKL,OAAO,OAAO,UACjB,OACA,IACF;GACA,KAAKA,OAAO,OAAO,YACjB,KAAK,MAAM,MACX,OACA,IACF;GAEA,MAAM;EACR,UAAU;GAGR,IAAI,KAAKG,aAAa,SACpB,KAAKA,WAAW,KAAA;GAGlB,KAAK,WAAW;EAClB;CACF;CAEA,UAAU,QAAqC;EAC7C,MAAM,WACJ,UAC8B;GAC9B,QAAQ,OAAO,MAAf;IACE,KAAK,UACH,OAAO;KACL,GAAG;KACH,mBAAmB,OAAO;KAC1B,oBAAoB,OAAO;IAC7B;IACF,KAAK,SACH,OAAO;KACL,GAAG;KACH,aAAa;IACf;IACF,KAAK,YACH,OAAO;KACL,GAAG;KACH,aAAa;IACf;IACF,KAAK,SACH,OAAO;KACL,GAAG;KACH,GAAG,WAAW,MAAM,MAAM,KAAK,OAAO;KACtC,WAAW,OAAO,QAAQ;IAC5B;IACF,KAAK;KACH,MAAM,WAAW;MACf,GAAG;MACH,GAAG,aAAa,OAAO,MAAM,OAAO,aAAa;MACjD,iBAAiB,MAAM,kBAAkB;MACzC,GAAI,CAAC,OAAO,UAAU;OACpB,aAAa;OACb,mBAAmB;OACnB,oBAAoB;MACtB;KACF;KAGA,KAAKS,eAAe,OAAO,SAAS,WAAW,KAAA;KAE/C,OAAO;IACT,KAAK;KACH,MAAM,QAAQ,OAAO;KACrB,OAAO;MACL,GAAG;MACH;MACA,kBAAkB,MAAM,mBAAmB;MAC3C,gBAAgB,KAAK,IAAI;MACzB,mBAAmB,MAAM,oBAAoB;MAC7C,oBAAoB;MACpB,aAAa;MACb,QAAQ;MAGR,eAAe;KACjB;IACF,KAAK,cACH,OAAO;KACL,GAAG;KACH,eAAe;IACjB;IACF,KAAK,YACH,OAAO;KACL,GAAG;KACH,GAAG,OAAO;IACZ;GACJ;EACF;EAEA,KAAK,QAAQ,QAAQ,KAAK,KAAK;EAE/B,sBAAA,cAAc,YAAY;GAGxB,KAAK,UAAU,MAAM,CAAC,CAAC,SAAS,aAAa;IAC3C,SAAS,cAAc;GACzB,CAAC;GAED,KAAKZ,OAAO,OAAO;IAAE,OAAO;IAAM,MAAM;IAAW;GAAO,CAAC;EAC7D,CAAC;CACH;AACF;AAEA,SAAgB,WAMd,MACA,SACA;CACA,OAAO;EACL,mBAAmB;EACnB,oBAAoB;EACpB,aAAae,gBAAAA,SAAS,QAAQ,WAAW,IAAI,aAAa;EAC1D,GAAI,SAAS,KAAA,KACV;GACC,OAAO;GACP,QAAQ;EACV;CACJ;AACF;AAEA,SAAS,aAAoB,MAAyB,eAAwB;CAC5E,OAAO;EACL;EACA,eAAe,iBAAiB,KAAK,IAAI;EACzC,OAAO;EACP,eAAe;EACf,QAAQ;CACV;AACF;AAEA,SAAS,gBAMP,SAC2B;CAC3B,MAAM,OACJ,OAAO,QAAQ,gBAAgB,aAC1B,QAAQ,YAA2C,IACpD,QAAQ;CAEd,MAAM,UAAU,SAAS,KAAA;CAEzB,MAAM,uBAAuB,UACzB,OAAO,QAAQ,yBAAyB,aACtC,QAAQ,qBAAqB,IAC7B,QAAQ,uBACV;CAEJ,OAAO;EACL;EACA,iBAAiB;EACjB,eAAe,UAAW,wBAAwB,KAAK,IAAI,IAAK;EAChE,OAAO;EACP,kBAAkB;EAClB,gBAAgB;EAChB,mBAAmB;EACnB,oBAAoB;EACpB,WAAW;EACX,eAAe;EACf,QAAQ,UAAU,YAAY;EAC9B,aAAa;CACf;AACF"}

package/build/modern/query.d.cts

@@ -1,2 +1,2 @@
-import { $n as Query, Jn as Action, Qn as FetchOptions, Xn as FetchDirection, Yn as FetchContext, Zn as FetchMeta, er as QueryBehavior, nr as fetchState, tr as QueryState } from "./hydration-DWGr3cFC.cjs";
+import { $n as Query, Jn as Action, Qn as FetchOptions, Xn as FetchDirection, Yn as FetchContext, Zn as FetchMeta, er as QueryBehavior, nr as fetchState, tr as QueryState } from "./hydration-DwR10Hi-.cjs";
 export { Action, FetchContext, FetchDirection, FetchMeta, FetchOptions, Query, QueryBehavior, QueryState, fetchState };

package/build/modern/query.d.ts

@@ -1,2 +1,2 @@
-import { $n as Query, Jn as Action, Qn as FetchOptions, Xn as FetchDirection, Yn as FetchContext, Zn as FetchMeta, er as QueryBehavior, nr as fetchState, tr as QueryState } from "./hydration-Bjs0MSgg.js";
+import { $n as Query, Jn as Action, Qn as FetchOptions, Xn as FetchDirection, Yn as FetchContext, Zn as FetchMeta, er as QueryBehavior, nr as fetchState, tr as QueryState } from "./hydration-Cq7QYAzB.js";
 export { Action, FetchContext, FetchDirection, FetchMeta, FetchOptions, Query, QueryBehavior, QueryState, fetchState };

package/build/modern/query.js

@@ -4,6 +4,25 @@ import { CancelledError, canFetch, createRetryer } from "./retryer.js";
 import { Removable } from "./removable.js";
 import { infiniteQueryBehavior } from "./infiniteQueryBehavior.js";
 //#region src/query.ts
+/**
+* Represents a single cached query. A `Query` holds the query's key, options,
+* state (data/error/status), and the observers currently subscribed to it.
+*
+* Instances are created and managed internally by `QueryCache`; application
+* code typically interacts with queries indirectly through `QueryClient` or
+* a framework hook like `useQuery`. Direct access to a `Query` instance is
+* possible via `queryCache.find()`/`findAll()` for inspecting cache state.
+*
+* @example
+* ```ts
+* const queryCache = queryClient.getQueryCache()
+* const query = queryCache.find({ queryKey: ['posts'] })
+*
+* if (query) {
+*   console.log(query.state.dataUpdatedAt)
+* }
+* ```
+*/
 var Query = class extends Removable {
 	#queryType;
 	#initialState;
@@ -27,15 +46,24 @@ var Query = class extends Removable {
 		this.state = config.state ?? this.#initialState;
 		this.scheduleGc();
 	}
+	/**
+	* The `meta` object passed in the query's options, if any.
+	*/
 	get meta() {
 		return this.options.meta;
 	}
+	/** @internal */
 	get queryType() {
 		return this.#queryType;
 	}
+	/**
+	* The promise for the currently in-flight fetch, if the query is fetching.
+	* `undefined` when the query is not fetching.
+	*/
 	get promise() {
 		return this.#retryer?.promise;
 	}
+	/** @internal */
 	setOptions(options) {
 		this.options = {
 			...this.#defaultOptions,
@@ -54,6 +82,7 @@ var Query = class extends Removable {
 	optionalRemove() {
 		if (!this.observers.length && this.state.fetchStatus === "idle") this.#cache.remove(this);
 	}
+	/** @internal */
 	setData(newData, options) {
 		const data = replaceData(this.state.data, newData, this.options);
 		this.#dispatch({
@@ -64,60 +93,141 @@ var Query = class extends Removable {
 		});
 		return data;
 	}
+	/**
+	* Merges the given partial state directly into this query's state, notifying observers. Used
+	* by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a
+	* user manually trigger a loading/error state or edit the cached data.
+	*/
 	setState(state) {
 		this.#dispatch({
 			type: "setState",
 			state
 		});
 	}
+	/**
+	* Cancels the query's currently in-flight fetch, if any.
+	* - Returns a promise that resolves once the cancellation has settled.
+	* - If no fetch is in progress, resolves immediately.
+	*
+	* @example
+	* ```ts
+	* await query.cancel()
+	* ```
+	*/
 	cancel(options) {
 		const promise = this.#retryer?.promise;
 		this.#retryer?.cancel(options);
 		return promise ? promise.then(noop).catch(noop) : Promise.resolve();
 	}
+	/**
+	* Clears the query's garbage collection timeout and silently cancels any
+	* in-flight fetch. Called by `QueryCache` when the query is removed from
+	* the cache.
+	*
+	* @see {@link Query#cancel}
+	*/
 	destroy() {
 		super.destroy();
 		this.cancel({ silent: true });
 	}
+	/** @internal */
 	get resetState() {
 		return this.#initialState;
 	}
+	/**
+	* Resets the query back to its initial state (the state it had when it was
+	* first created, e.g. any `initialData`), destroying it first to cancel any
+	* in-flight fetch.
+	*/
 	reset() {
 		this.destroy();
 		this.setState(this.resetState);
 	}
+	/**
+	* Returns `true` if the query has at least one observer for which `enabled`
+	* does not resolve to `false`.
+	*/
 	isActive() {
 		return this.observers.some((observer) => resolveQueryValue(observer.options.enabled, this) !== false);
 	}
+	/**
+	* Returns `true` if the query is disabled, meaning it will not fetch
+	* automatically.
+	* - If the query has observers, it is disabled when none of them are active
+	*   (see `isActive`).
+	* - If the query has no observers, it is disabled when its `queryFn` is
+	*   `skipToken` or it has never been fetched.
+	*/
 	isDisabled() {
 		if (this.getObserversCount() > 0) return !this.isActive();
 		return this.options.queryFn === skipToken || !this.isFetched();
 	}
+	/**
+	* Returns `true` if the query has been fetched, i.e. it has resolved with
+	* either data or an error at least once.
+	*/
 	isFetched() {
 		return this.state.dataUpdateCount + this.state.errorUpdateCount > 0;
 	}
+	/**
+	* Returns `true` if the query has at least one observer configured with
+	* `staleTime: 'static'`, meaning it is treated as never stale.
+	*/
 	isStatic() {
 		if (this.getObserversCount() > 0) return this.observers.some((observer) => resolveQueryValue(observer.options.staleTime, this) === "static");
 		return false;
 	}
+	/**
+	* Returns `true` if the query is stale.
+	* - If the query has observers, defers to whether any observer's current
+	*   result reports `isStale` (which accounts for each observer's own
+	*   `staleTime` and `enabled` state).
+	* - If the query has no observers, it is considered stale when it has no
+	*   data or has been invalidated.
+	*
+	* @see {@link Query#isStaleByTime}
+	* @example
+	* ```ts
+	* if (query.isStale()) {
+	*   // refetch or otherwise treat the cached data as outdated
+	* }
+	* ```
+	*/
 	isStale() {
 		if (this.getObserversCount() > 0) return this.observers.some((observer) => observer.getCurrentResult().isStale);
 		return this.state.data === void 0 || this.state.isInvalidated;
 	}
+	/**
+	* Returns `true` if the query's data is stale relative to the given
+	* `staleTime` (defaults to `0`).
+	* - A query with no data is always stale.
+	* - `staleTime: 'static'` is never stale.
+	* - An invalidated query is always stale.
+	* - Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.
+	*
+	* @see {@link Query#isStale}
+	* @example
+	* ```ts
+	* const isStale = query.isStaleByTime(1000 * 60)
+	* ```
+	*/
 	isStaleByTime(staleTime = 0) {
 		if (this.state.data === void 0) return true;
 		if (staleTime === "static") return false;
 		if (this.state.isInvalidated) return true;
 		return !timeUntilStale(this.state.dataUpdatedAt, staleTime);
 	}
+	/** @internal */
 	onFocus() {
 		this.observers.find((x) => x.shouldFetchOnWindowFocus())?.refetch({ cancelRefetch: false });
 		this.#retryer?.continue();
 	}
+	/** @internal */
 	onOnline() {
 		this.observers.find((x) => x.shouldFetchOnReconnect())?.refetch({ cancelRefetch: false });
 		this.#retryer?.continue();
 	}
+	/** @internal */
 	addObserver(observer) {
 		if (!this.observers.includes(observer)) {
 			this.observers.push(observer);
@@ -129,6 +239,7 @@ var Query = class extends Removable {
 			});
 		}
 	}
+	/** @internal */
 	removeObserver(observer) {
 		const index = this.observers.indexOf(observer);
 		if (index !== -1) {
@@ -147,12 +258,42 @@ var Query = class extends Removable {
 			});
 		}
 	}
+	/**
+	* Returns the number of observers currently subscribed to this query.
+	*
+	* @example
+	* ```ts
+	* if (query.getObserversCount() === 0) {
+	*   // no component is currently watching this query
+	* }
+	* ```
+	*/
 	getObserversCount() {
 		return this.observers.length;
 	}
+	/**
+	* Marks the query as invalidated, unless it is already invalidated. This
+	* updates `state.isInvalidated` and notifies observers, but does not by
+	* itself trigger a refetch.
+	*
+	* @example
+	* ```ts
+	* query.invalidate()
+	* ```
+	*/
 	invalidate() {
 		if (!this.state.isInvalidated) this.#dispatch({ type: "invalidate" });
 	}
+	/**
+	* Fetches the query, i.e. runs its `queryFn` (through any configured
+	* retryer/behavior) and updates the query's state with the result.
+	* - If a fetch is already in flight, returns its promise instead of
+	*   starting a new one, unless `fetchOptions.cancelRefetch` is set and the
+	*   query already has data, in which case the current fetch is silently
+	*   cancelled first.
+	* - If `options` is passed, it replaces the query's current options
+	*   before fetching.
+	*/
 	async fetch(options, fetchOptions) {
 		if (this.state.fetchStatus !== "idle" && this.#retryer?.status() !== "rejected") {
 			if (this.state.data !== void 0 && fetchOptions?.cancelRefetch) this.cancel({ silent: true });