From c7adf7ddb9ed028782217813d131bc219280fad3 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Wed, 30 Sep 2026 20:15:27 +0900 Subject: [PATCH 01/12] docs(*): add parameter and result property tables to reference function pages and an overview to overloaded ones --- .../angular/reference/functions/dehydrate.md | 20 + .../angular/reference/functions/hydrate.md | 11 + .../functions/infiniteQueryOptions.md | 37 ++ .../functions/injectInfiniteQuery.md | 89 ++++ .../reference/functions/injectIsFetching.md | 21 + .../reference/functions/injectIsMutating.md | 19 + .../reference/functions/injectMutation.md | 28 ++ .../functions/injectMutationState.md | 8 + .../reference/functions/injectQuery.md | 87 ++++ .../reference/functions/matchMutation.md | 11 + .../angular/reference/functions/matchQuery.md | 13 + .../reference/functions/mutationOptions.md | 35 ++ .../angular/reference/functions/noop.md | 22 + .../reference/functions/queryFeature.md | 9 + .../reference/functions/queryOptions.md | 36 ++ .../createInfiniteQueryController.md | 37 ++ .../functions/createMutationController.md | 20 + .../functions/createQueriesController.md | 9 + .../functions/createQueryController.md | 34 ++ .../lit/reference/functions/dehydrate.md | 20 + .../lit/reference/functions/hydrate.md | 11 + .../functions/infiniteQueryOptions.md | 37 ++ .../lit/reference/functions/matchMutation.md | 11 + .../lit/reference/functions/matchQuery.md | 13 + .../reference/functions/mutationOptions.md | 40 ++ .../framework/lit/reference/functions/noop.md | 22 + .../lit/reference/functions/queryOptions.md | 38 ++ .../lit/reference/functions/useIsFetching.md | 13 + .../lit/reference/functions/useIsMutating.md | 11 + .../reference/functions/useMutationState.md | 9 + .../reference/functions/HydrationBoundary.md | 11 + .../functions/QueryClientProvider.md | 9 + .../functions/QueryErrorResetBoundary.md | 8 + .../preact/reference/functions/dehydrate.md | 20 + .../preact/reference/functions/hydrate.md | 11 + .../functions/infiniteQueryOptions.md | 36 ++ .../reference/functions/matchMutation.md | 11 + .../preact/reference/functions/matchQuery.md | 13 + .../reference/functions/mutationOptions.md | 35 ++ .../preact/reference/functions/noop.md | 22 + .../reference/functions/queryOptions.md | 36 ++ .../reference/functions/useInfiniteQuery.md | 125 ++++++ .../reference/functions/useIsFetching.md | 13 + .../reference/functions/useIsMutating.md | 11 + .../preact/reference/functions/useMutation.md | 20 + .../preact/reference/functions/useQuery.md | 113 +++++ .../functions/useSuspenseInfiniteQuery.md | 34 ++ .../reference/functions/useSuspenseQueries.md | 58 +++ .../reference/functions/useSuspenseQuery.md | 31 ++ .../reference/functions/HydrationBoundary.md | 11 + .../functions/QueryClientProvider.md | 9 + .../functions/QueryErrorResetBoundary.md | 8 + .../react/reference/functions/dehydrate.md | 20 + .../react/reference/functions/hydrate.md | 11 + .../functions/infiniteQueryOptions.md | 36 ++ .../reference/functions/matchMutation.md | 11 + .../react/reference/functions/matchQuery.md | 13 + .../reference/functions/mutationOptions.md | 35 ++ .../react/reference/functions/noop.md | 22 + .../react/reference/functions/queryOptions.md | 36 ++ .../reference/functions/useInfiniteQuery.md | 125 ++++++ .../reference/functions/useIsFetching.md | 13 + .../reference/functions/useIsMutating.md | 11 + .../react/reference/functions/useMutation.md | 20 + .../react/reference/functions/useQuery.md | 113 +++++ .../functions/useSuspenseInfiniteQuery.md | 34 ++ .../reference/functions/useSuspenseQueries.md | 58 +++ .../reference/functions/useSuspenseQuery.md | 31 ++ .../functions/QueryClientProvider.md | 9 + .../solid/reference/functions/dehydrate.md | 20 + .../solid/reference/functions/hydrate.md | 11 + .../functions/infiniteQueryOptions.md | 34 ++ .../reference/functions/matchMutation.md | 11 + .../solid/reference/functions/matchQuery.md | 13 + .../reference/functions/mutationOptions.md | 35 ++ .../solid/reference/functions/noop.md | 22 + .../solid/reference/functions/queryOptions.md | 34 ++ .../reference/functions/useInfiniteQuery.md | 85 ++++ .../solid/reference/functions/useQuery.md | 77 ++++ .../functions/createInfiniteQuery.md | 124 +++++ .../svelte/reference/functions/createQuery.md | 114 +++++ .../svelte/reference/functions/dehydrate.md | 20 + .../svelte/reference/functions/hydrate.md | 11 + .../functions/infiniteQueryOptions.md | 35 ++ .../reference/functions/matchMutation.md | 11 + .../svelte/reference/functions/matchQuery.md | 13 + .../reference/functions/mutationOptions.md | 34 ++ .../svelte/reference/functions/noop.md | 22 + .../reference/functions/queryOptions.md | 34 ++ .../svelte/reference/functions/useHydrate.md | 11 + .../reference/functions/useIsFetching.md | 13 + .../reference/functions/useIsMutating.md | 11 + .../reference/functions/useMutationState.md | 9 + .../vue/reference/functions/dehydrate.md | 20 + .../vue/reference/functions/hydrate.md | 11 + .../functions/infiniteQueryOptions.md | 35 ++ .../vue/reference/functions/matchMutation.md | 11 + .../vue/reference/functions/matchQuery.md | 13 + .../reference/functions/mutationOptions.md | 49 ++ .../framework/vue/reference/functions/noop.md | 22 + .../vue/reference/functions/queryOptions.md | 50 +++ .../reference/functions/useInfiniteQuery.md | 47 ++ .../vue/reference/functions/useQuery.md | 45 ++ scripts/generate-docs.ts | 424 ++++++++++++++++++ 104 files changed, 3545 insertions(+) diff --git a/docs/framework/angular/reference/functions/dehydrate.md b/docs/framework/angular/reference/functions/dehydrate.md index 201200efdfa..2c4abfc7754 100644 --- a/docs/framework/angular/reference/functions/dehydrate.md +++ b/docs/framework/angular/reference/functions/dehydrate.md @@ -25,10 +25,30 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `mutations` | `DehydratedMutation`[] | +| `queries` | `DehydratedQuery`[] | + ## Example ```ts diff --git a/docs/framework/angular/reference/functions/hydrate.md b/docs/framework/angular/reference/functions/hydrate.md index 435603b3af4..e0f723266cc 100644 --- a/docs/framework/angular/reference/functions/hydrate.md +++ b/docs/framework/angular/reference/functions/hydrate.md @@ -34,6 +34,17 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`HydrateOptions`](../interfaces/HydrateOptions.md) + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/angular/reference/functions/infiniteQueryOptions.md b/docs/framework/angular/reference/functions/infiniteQueryOptions.md index 38986e086e8..6cd5705cb2b 100644 --- a/docs/framework/angular/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/angular/reference/functions/infiniteQueryOptions.md @@ -3,6 +3,22 @@ id: infiniteQueryOptions title: infiniteQueryOptions --- +## Overview + +```ts +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +``` + +- [`DefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -94,6 +110,8 @@ export class Projects { } ``` + + ## Call Signature ```ts @@ -189,6 +207,8 @@ export class Comments { [injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. + + ## Call Signature ```ts @@ -283,3 +303,20 @@ export class Comments { ### See [injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. + + + +## Parameters + +### options + +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to +`injectInfiniteQuery`. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/angular/reference/functions/injectInfiniteQuery.md b/docs/framework/angular/reference/functions/injectInfiniteQuery.md index 39aecc1d173..fe34782cb8b 100644 --- a/docs/framework/angular/reference/functions/injectInfiniteQuery.md +++ b/docs/framework/angular/reference/functions/injectInfiniteQuery.md @@ -3,6 +3,22 @@ id: injectInfiniteQuery title: injectInfiniteQuery --- +## Overview + +```ts +function injectInfiniteQuery(injectInfiniteQueryFn: () => DefinedInitialDataInfiniteOptions, options?: InjectInfiniteQueryOptions): DefinedCreateInfiniteQueryResult; +function injectInfiniteQuery(injectInfiniteQueryFn: () => UndefinedInitialDataInfiniteOptions, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult; +function injectInfiniteQuery(injectInfiniteQueryFn: () => CreateInfiniteQueryOptions, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult; +``` + +- [`DefinedInitialDataInfiniteOptions` → `DefinedCreateInfiniteQueryResult`](#call-signature-1): The options for `injectInfiniteQuery` are identical to `injectQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". +- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryResult`](#call-signature-2): Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". +- [`CreateInfiniteQueryOptions` → `CreateInfiniteQueryResult`](#call-signature-3): This overload accepts the general [CreateInfiniteQueryOptions](../interfaces/CreateInfiniteQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectInfiniteQuery` in your own helper function that forwards caller-provided options. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -104,6 +120,8 @@ export class Projects { } ``` + + ## Call Signature ```ts @@ -293,6 +311,8 @@ export class Comments { } ``` + + ## Call Signature ```ts @@ -348,3 +368,72 @@ Additional configuration. [`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> The infinite query result. + + + +## Parameters + +### injectInfiniteQueryFn + +() => [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +A function that returns infinite query options. Similar to `computed` from +Angular, this function runs in the reactive context, so signals read inside it drive the query. + + + +#### `injectInfiniteQueryFn` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### options? + +[`InjectInfiniteQueryOptions`](../interfaces/InjectInfiniteQueryOptions.md) + +Additional configuration. + + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the infinite query. If this is not provided, the current injection context will be used instead (via `inject`). | + + + +## Returns + +[`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> + +The infinite query result. diff --git a/docs/framework/angular/reference/functions/injectIsFetching.md b/docs/framework/angular/reference/functions/injectIsFetching.md index ce629a0cf3f..c84d3c9b5ff 100644 --- a/docs/framework/angular/reference/functions/injectIsFetching.md +++ b/docs/framework/angular/reference/functions/injectIsFetching.md @@ -20,12 +20,33 @@ background (useful for app-wide loading indicators). The [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched queries. + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### options? [`InjectIsFetchingOptions`](../interfaces/InjectIsFetchingOptions.md) Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the isFetching signal. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns `Signal`\<`number`\> diff --git a/docs/framework/angular/reference/functions/injectIsMutating.md b/docs/framework/angular/reference/functions/injectIsMutating.md index 409d7c1653f..a179eb33851 100644 --- a/docs/framework/angular/reference/functions/injectIsMutating.md +++ b/docs/framework/angular/reference/functions/injectIsMutating.md @@ -20,12 +20,31 @@ Injects a signal that tracks the number of mutations that your application curre The [MutationFilters](../interfaces/MutationFilters.md) to narrow down the matched mutations. + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### options? [`InjectIsMutatingOptions`](../interfaces/InjectIsMutatingOptions.md) Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the isMutating signal. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns `Signal`\<`number`\> diff --git a/docs/framework/angular/reference/functions/injectMutation.md b/docs/framework/angular/reference/functions/injectMutation.md index 2a31bca1e7d..262ab473b77 100644 --- a/docs/framework/angular/reference/functions/injectMutation.md +++ b/docs/framework/angular/reference/functions/injectMutation.md @@ -39,12 +39,40 @@ Unlike queries, mutations are typically used to create/update/delete data or per A function that returns mutation options. Similar to `computed` from Angular, this function runs in the reactive context, so signals read inside it drive the mutation's options. + + +#### `injectMutationFn` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | + ### options? [`InjectMutationOptions`](../interfaces/InjectMutationOptions.md) Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the mutation. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns [`CreateMutationResult`](../type-aliases/CreateMutationResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> diff --git a/docs/framework/angular/reference/functions/injectMutationState.md b/docs/framework/angular/reference/functions/injectMutationState.md index 2e43406cfee..2ba5ceb4e2f 100644 --- a/docs/framework/angular/reference/functions/injectMutationState.md +++ b/docs/framework/angular/reference/functions/injectMutationState.md @@ -34,6 +34,14 @@ in the reactive context, so signals read inside it re-narrow the matched mutatio Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the mutation state signal. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns `Signal`\<`TResult`[]\> diff --git a/docs/framework/angular/reference/functions/injectQuery.md b/docs/framework/angular/reference/functions/injectQuery.md index bf715335bf4..3f0da59d1a3 100644 --- a/docs/framework/angular/reference/functions/injectQuery.md +++ b/docs/framework/angular/reference/functions/injectQuery.md @@ -3,6 +3,22 @@ id: injectQuery title: injectQuery --- +## Overview + +```ts +function injectQuery(injectQueryFn: () => DefinedInitialDataOptions, options?: InjectQueryOptions): DefinedCreateQueryResult; +function injectQuery(injectQueryFn: () => UndefinedInitialDataOptions, options?: InjectQueryOptions): CreateQueryResult; +function injectQuery(injectQueryFn: () => CreateQueryOptions, options?: InjectQueryOptions): CreateQueryResult; +``` + +- [`DefinedInitialDataOptions` → `DefinedCreateQueryResult`](#call-signature-1): This overload is selected when `initialData` is set on the options returned by `injectQueryFn`, so the resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`). +- [`UndefinedInitialDataOptions` → `CreateQueryResult`](#call-signature-2): Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. +- [`CreateQueryOptions` → `CreateQueryResult`](#call-signature-3): This overload accepts the general [CreateQueryOptions](../interfaces/CreateQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectQuery` in your own helper function that forwards caller-provided options. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -88,6 +104,8 @@ export class Posts { } ``` + + ## Call Signature ```ts @@ -206,6 +224,8 @@ export class Posts { } ``` + + ## Call Signature ```ts @@ -261,3 +281,70 @@ The query result. ### See https://tanstack.com/query/latest/docs/framework/angular/guides/queries + + + +## Parameters + +### injectQueryFn + +() => [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +A function that returns query options. Similar to `computed` from Angular, this +function runs in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive +the query. + + + +#### `injectQueryFn` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### options? + +[`InjectQueryOptions`](../interfaces/InjectQueryOptions.md) + +Additional configuration + + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the query. If this is not provided, the current injection context will be used instead (via `inject`). | + + + +## Returns + +[`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> + +The query result. diff --git a/docs/framework/angular/reference/functions/matchMutation.md b/docs/framework/angular/reference/functions/matchMutation.md index 0bc16b361f7..7903e79a6b6 100644 --- a/docs/framework/angular/reference/functions/matchMutation.md +++ b/docs/framework/angular/reference/functions/matchMutation.md @@ -19,6 +19,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/angular/reference/functions/matchQuery.md b/docs/framework/angular/reference/functions/matchQuery.md index ce575fc2b69..961ff43c3d1 100644 --- a/docs/framework/angular/reference/functions/matchQuery.md +++ b/docs/framework/angular/reference/functions/matchQuery.md @@ -18,6 +18,19 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/angular/reference/functions/mutationOptions.md b/docs/framework/angular/reference/functions/mutationOptions.md index fd29abb7ac6..a3f24c585c5 100644 --- a/docs/framework/angular/reference/functions/mutationOptions.md +++ b/docs/framework/angular/reference/functions/mutationOptions.md @@ -3,6 +3,20 @@ id: mutationOptions title: mutationOptions --- +## Overview + +```ts +function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; +function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; +``` + +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `injectMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other filters, such as `status`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -79,6 +93,8 @@ export class SavingIndicator { } ``` + + ## Call Signature ```ts @@ -165,3 +181,22 @@ export class Post { } } ``` + + + +## Parameters + +### options + +`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The mutation options to use, identical to what you'd pass to `injectMutation`, without a +`mutationKey`. + + + +## Returns + +`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The same options object, unchanged. diff --git a/docs/framework/angular/reference/functions/noop.md b/docs/framework/angular/reference/functions/noop.md index 01fb409f4e9..12d0e1a36b0 100644 --- a/docs/framework/angular/reference/functions/noop.md +++ b/docs/framework/angular/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/angular/reference/functions/queryFeature.md b/docs/framework/angular/reference/functions/queryFeature.md index ac98f4c34f9..f43652084f2 100644 --- a/docs/framework/angular/reference/functions/queryFeature.md +++ b/docs/framework/angular/reference/functions/queryFeature.md @@ -36,3 +36,12 @@ The Angular providers this feature contributes to `provideTanStackQuery`. [`QueryFeature`](../interfaces/QueryFeature.md)\<`TFeatureKind`\> A Query feature. + + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `ɵkind` | `TFeatureKind` | +| `ɵproviders` | `Provider`[] | diff --git a/docs/framework/angular/reference/functions/queryOptions.md b/docs/framework/angular/reference/functions/queryOptions.md index 46df24c42db..a42d4a747c4 100644 --- a/docs/framework/angular/reference/functions/queryOptions.md +++ b/docs/framework/angular/reference/functions/queryOptions.md @@ -3,6 +3,22 @@ id: queryOptions title: queryOptions --- +## Overview + +```ts +function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +``` + +- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -85,6 +101,8 @@ export class Posts { } ``` + + ## Call Signature ```ts @@ -162,6 +180,8 @@ export class Post { } ``` + + ## Call Signature ```ts @@ -272,3 +292,19 @@ export class Post { readonly postQuery = injectQuery(() => postOptions(this.postId())) } ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `injectQuery`. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/lit/reference/functions/createInfiniteQueryController.md b/docs/framework/lit/reference/functions/createInfiniteQueryController.md index 1e4f0a64734..702782bb52e 100644 --- a/docs/framework/lit/reference/functions/createInfiniteQueryController.md +++ b/docs/framework/lit/reference/functions/createInfiniteQueryController.md @@ -61,6 +61,43 @@ subscription. Infinite query observer options, or a getter that returns options. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/lit/reference/functions/createMutationController.md b/docs/framework/lit/reference/functions/createMutationController.md index 8283b194c5f..ee92ffcf550 100644 --- a/docs/framework/lit/reference/functions/createMutationController.md +++ b/docs/framework/lit/reference/functions/createMutationController.md @@ -55,6 +55,26 @@ subscription. Mutation observer options, or a getter that returns options. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/lit/reference/functions/createQueriesController.md b/docs/framework/lit/reference/functions/createQueriesController.md index 19b833d42fe..62cd2307334 100644 --- a/docs/framework/lit/reference/functions/createQueriesController.md +++ b/docs/framework/lit/reference/functions/createQueriesController.md @@ -47,6 +47,15 @@ subscription. Queries controller options, or a getter that returns options. + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `combine?` | (`result`: `CreateQueriesResults`\<`TQueryOptions`\>) => `TCombinedResult` | Optional function that combines the query result array into one value. | +| `queries` | [`Accessor`](../type-aliases/Accessor.md)\< \| readonly \[`...CreateQueriesOptions`\] \| readonly \[`...{ [K in keyof TQueryOptions]: GetCreateQueriesInput }`\]\> | Query options to observe, or a getter that returns the current options. | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/lit/reference/functions/createQueryController.md b/docs/framework/lit/reference/functions/createQueryController.md index 57584377086..22483547cd1 100644 --- a/docs/framework/lit/reference/functions/createQueryController.md +++ b/docs/framework/lit/reference/functions/createQueryController.md @@ -58,6 +58,40 @@ subscription. Query observer options, or a getter that returns options. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryData` \| () => `TQueryData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryData`\>, `TError`, `NonFunctionGuard`\<`TQueryData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/lit/reference/functions/dehydrate.md b/docs/framework/lit/reference/functions/dehydrate.md index 201200efdfa..2c4abfc7754 100644 --- a/docs/framework/lit/reference/functions/dehydrate.md +++ b/docs/framework/lit/reference/functions/dehydrate.md @@ -25,10 +25,30 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `mutations` | `DehydratedMutation`[] | +| `queries` | `DehydratedQuery`[] | + ## Example ```ts diff --git a/docs/framework/lit/reference/functions/hydrate.md b/docs/framework/lit/reference/functions/hydrate.md index a8bbe36eded..14e109fc5e9 100644 --- a/docs/framework/lit/reference/functions/hydrate.md +++ b/docs/framework/lit/reference/functions/hydrate.md @@ -34,6 +34,17 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`HydrateOptions`](../interfaces/HydrateOptions.md) + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/lit/reference/functions/infiniteQueryOptions.md b/docs/framework/lit/reference/functions/infiniteQueryOptions.md index a7f93674f4a..e2b5b24ea07 100644 --- a/docs/framework/lit/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/lit/reference/functions/infiniteQueryOptions.md @@ -42,6 +42,43 @@ data and error types across TanStack Query APIs. Infinite query options to preserve and brand. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + ## Returns [`InfiniteQueryObserverOptions`](../interfaces/InfiniteQueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` diff --git a/docs/framework/lit/reference/functions/matchMutation.md b/docs/framework/lit/reference/functions/matchMutation.md index 0bc16b361f7..7903e79a6b6 100644 --- a/docs/framework/lit/reference/functions/matchMutation.md +++ b/docs/framework/lit/reference/functions/matchMutation.md @@ -19,6 +19,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/lit/reference/functions/matchQuery.md b/docs/framework/lit/reference/functions/matchQuery.md index ce575fc2b69..961ff43c3d1 100644 --- a/docs/framework/lit/reference/functions/matchQuery.md +++ b/docs/framework/lit/reference/functions/matchQuery.md @@ -18,6 +18,19 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/lit/reference/functions/mutationOptions.md b/docs/framework/lit/reference/functions/mutationOptions.md index 8bf7ba068ea..21e1ec7d620 100644 --- a/docs/framework/lit/reference/functions/mutationOptions.md +++ b/docs/framework/lit/reference/functions/mutationOptions.md @@ -37,12 +37,52 @@ Preserves and types mutation options for reuse across Lit Query APIs. Mutation options to preserve. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | + ## Returns [`MutationObserverOptions`](../interfaces/MutationObserverOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> The same options object. + + +### Result properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | + ## Example ```ts diff --git a/docs/framework/lit/reference/functions/noop.md b/docs/framework/lit/reference/functions/noop.md index 01fb409f4e9..12d0e1a36b0 100644 --- a/docs/framework/lit/reference/functions/noop.md +++ b/docs/framework/lit/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/lit/reference/functions/queryOptions.md b/docs/framework/lit/reference/functions/queryOptions.md index 809b86e7bdb..f138c125f5d 100644 --- a/docs/framework/lit/reference/functions/queryOptions.md +++ b/docs/framework/lit/reference/functions/queryOptions.md @@ -3,6 +3,22 @@ id: queryOptions title: queryOptions --- +## Overview + +```ts +function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & object; +function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & object; +function queryOptions(options: UndefinedInitialDataOptions): QueryObserverOptions & object & object; +``` + +- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. +- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. +- [`UndefinedInitialDataOptions` → `QueryObserverOptions`](#call-signature-3): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -58,6 +74,8 @@ const todosOptions = queryOptions({ }) ``` + + ## Call Signature ```ts @@ -101,6 +119,8 @@ Query options to preserve and brand. The same options object with a typed `queryKey`. + + ## Call Signature ```ts @@ -143,3 +163,21 @@ Query options to preserve and brand. [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`, `never`\> & `object` & `object` The same options object with a typed `queryKey`. + + + +## Parameters + +### options + +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +Query options to preserve and brand. + + + +## Returns + +[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`, `never`\> & `object` & `object` + +The same options object with a typed `queryKey`. diff --git a/docs/framework/lit/reference/functions/useIsFetching.md b/docs/framework/lit/reference/functions/useIsFetching.md index e8843de6028..8e5445f9821 100644 --- a/docs/framework/lit/reference/functions/useIsFetching.md +++ b/docs/framework/lit/reference/functions/useIsFetching.md @@ -34,6 +34,19 @@ subscription. Query filters, or a getter that returns query filters. + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/lit/reference/functions/useIsMutating.md b/docs/framework/lit/reference/functions/useIsMutating.md index 16df7287a70..a2a1660e2ef 100644 --- a/docs/framework/lit/reference/functions/useIsMutating.md +++ b/docs/framework/lit/reference/functions/useIsMutating.md @@ -34,6 +34,17 @@ subscription. Mutation filters, or a getter that returns mutation filters. + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/lit/reference/functions/useMutationState.md b/docs/framework/lit/reference/functions/useMutationState.md index c62bbb8d19e..c3d23fff949 100644 --- a/docs/framework/lit/reference/functions/useMutationState.md +++ b/docs/framework/lit/reference/functions/useMutationState.md @@ -41,6 +41,15 @@ subscription. Mutation state filters and optional selector. + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `filters?` | [`Accessor`](../type-aliases/Accessor.md)\<[`MutationFilters`](../interfaces/MutationFilters.md)\> | Filters used to select mutations from the mutation cache. | +| `select?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `TResult` | Maps each matching mutation to the value returned by the accessor. | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md index 1757643329f..97d22becfe7 100644 --- a/docs/framework/preact/reference/functions/HydrationBoundary.md +++ b/docs/framework/preact/reference/functions/HydrationBoundary.md @@ -21,6 +21,17 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`. [`HydrationBoundaryProps`](../interfaces/HydrationBoundaryProps.md) + + +#### `props` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `children?` | `ComponentChildren` | The components to render — always rendered unconditionally, not gated on hydration. New queries are hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it lands. | +| `options?` | [`OmitKeyof`](../type-aliases/OmitKeyof.md)\<[`HydrateOptions`](../interfaces/HydrateOptions.md), `"defaultOptions"`\> & `object` | Optional. Note: unlike `hydrate`, `mutations` cannot be set here. | +| `queryClient?` | [`QueryClient`](../classes/QueryClient.md) | Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will be used. | +| `state` | [`DehydratedState`](../interfaces/DehydratedState.md) \| `null` \| `undefined` | The state to hydrate. | + ## Returns `Element` diff --git a/docs/framework/preact/reference/functions/QueryClientProvider.md b/docs/framework/preact/reference/functions/QueryClientProvider.md index a8c7a117a67..ed408e1a827 100644 --- a/docs/framework/preact/reference/functions/QueryClientProvider.md +++ b/docs/framework/preact/reference/functions/QueryClientProvider.md @@ -20,6 +20,15 @@ comes back online). [`QueryClientProviderProps`](../type-aliases/QueryClientProviderProps.md) + + +#### `props` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `children?` | `ComponentChildren` | The components that get access to the provided `QueryClient`. | +| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | + ## Returns `VNode` diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md index d7421971412..a9d73f276b8 100644 --- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md +++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md @@ -19,6 +19,14 @@ reset any query errors within the boundaries of the component. [`QueryErrorResetBoundaryProps`](../interfaces/QueryErrorResetBoundaryProps.md) + + +#### `props` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `children` | \| `ComponentChildren` \| [`QueryErrorResetBoundaryFunction`](../type-aliases/QueryErrorResetBoundaryFunction.md) | Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and returns a node. | + ## Returns `Element` diff --git a/docs/framework/preact/reference/functions/dehydrate.md b/docs/framework/preact/reference/functions/dehydrate.md index 201200efdfa..2c4abfc7754 100644 --- a/docs/framework/preact/reference/functions/dehydrate.md +++ b/docs/framework/preact/reference/functions/dehydrate.md @@ -25,10 +25,30 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `mutations` | `DehydratedMutation`[] | +| `queries` | `DehydratedQuery`[] | + ## Example ```ts diff --git a/docs/framework/preact/reference/functions/hydrate.md b/docs/framework/preact/reference/functions/hydrate.md index 435603b3af4..e0f723266cc 100644 --- a/docs/framework/preact/reference/functions/hydrate.md +++ b/docs/framework/preact/reference/functions/hydrate.md @@ -34,6 +34,17 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`HydrateOptions`](../interfaces/HydrateOptions.md) + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md index 1a8e0ea3a34..cd81b8d58a8 100644 --- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md @@ -3,6 +3,22 @@ id: infiniteQueryOptions title: infiniteQueryOptions --- +## Overview + +```ts +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +``` + +- [`DefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -89,6 +105,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -172,6 +190,8 @@ function Comments({ postId }: { postId: string }) { [useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + + ## Call Signature ```ts @@ -254,3 +274,19 @@ function Comments({ postId }: { postId: string }) { ### See [useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + + + +## Parameters + +### options + +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/preact/reference/functions/matchMutation.md b/docs/framework/preact/reference/functions/matchMutation.md index 0bc16b361f7..7903e79a6b6 100644 --- a/docs/framework/preact/reference/functions/matchMutation.md +++ b/docs/framework/preact/reference/functions/matchMutation.md @@ -19,6 +19,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/preact/reference/functions/matchQuery.md b/docs/framework/preact/reference/functions/matchQuery.md index ce575fc2b69..961ff43c3d1 100644 --- a/docs/framework/preact/reference/functions/matchQuery.md +++ b/docs/framework/preact/reference/functions/matchQuery.md @@ -18,6 +18,19 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md index 4b856590ba9..0cd586d7ce7 100644 --- a/docs/framework/preact/reference/functions/mutationOptions.md +++ b/docs/framework/preact/reference/functions/mutationOptions.md @@ -3,6 +3,20 @@ id: mutationOptions title: mutationOptions --- +## Overview + +```ts +function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; +function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; +``` + +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -72,6 +86,8 @@ function SavingIndicator() { } ``` + + ## Call Signature ```ts @@ -140,3 +156,22 @@ function CreatePost() { return } ``` + + + +## Parameters + +### options + +`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The mutation options to use, identical to what you'd pass to `useMutation`, without a +`mutationKey`. + + + +## Returns + +`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The same options object, unchanged. diff --git a/docs/framework/preact/reference/functions/noop.md b/docs/framework/preact/reference/functions/noop.md index 01fb409f4e9..12d0e1a36b0 100644 --- a/docs/framework/preact/reference/functions/noop.md +++ b/docs/framework/preact/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md index 666f9fd42ff..05bf57843b1 100644 --- a/docs/framework/preact/reference/functions/queryOptions.md +++ b/docs/framework/preact/reference/functions/queryOptions.md @@ -3,6 +3,22 @@ id: queryOptions title: queryOptions --- +## Overview + +```ts +function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; +``` + +- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `UseQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -80,6 +96,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -149,6 +167,8 @@ function Post({ id }: { id: string }) { } ``` + + ## Call Signature ```ts @@ -242,3 +262,19 @@ function Post({ postId }: { postId: number | undefined }) { return

{data?.title}

} ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md index 9fe8de01195..5808a40527a 100644 --- a/docs/framework/preact/reference/functions/useInfiniteQuery.md +++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md @@ -3,6 +3,22 @@ id: useInfiniteQuery title: useInfiniteQuery --- +## Overview + +```ts +function useInfiniteQuery(options: DefinedInitialDataInfiniteOptions, queryClient?: QueryClient): DefinedUseInfiniteQueryResult; +function useInfiniteQuery(options: UndefinedInitialDataInfiniteOptions, queryClient?: QueryClient): UseInfiniteQueryResult; +function useInfiniteQuery(options: UseInfiniteQueryOptions, queryClient?: QueryClient): UseInfiniteQueryResult; +``` + +- [`DefinedInitialDataInfiniteOptions` → `DefinedUseInfiniteQueryResult`](#call-signature-1): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`UndefinedInitialDataInfiniteOptions` → `UseInfiniteQueryResult`](#call-signature-2): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`UseInfiniteQueryOptions` → `UseInfiniteQueryResult`](#call-signature-3): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -99,6 +115,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -259,6 +277,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -447,3 +467,108 @@ function Comments({ postId }: { postId: string | undefined }) { ) } ``` + + + +## Parameters + +### options + +[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [UseInfiniteQueryOptions](../interfaces/UseInfiniteQueryOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + + + +## Returns + +[`UseInfiniteQueryResult`](../type-aliases/UseInfiniteQueryResult.md)\<`TData`, `TError`\> + +The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`, +`hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and +`data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default +`InfiniteData` shape. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/preact/reference/functions/useIsFetching.md b/docs/framework/preact/reference/functions/useIsFetching.md index 5dd612f9f82..86276c6960f 100644 --- a/docs/framework/preact/reference/functions/useIsFetching.md +++ b/docs/framework/preact/reference/functions/useIsFetching.md @@ -20,6 +20,19 @@ the background (useful for app-wide loading indicators). The [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched queries. + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/preact/reference/functions/useIsMutating.md b/docs/framework/preact/reference/functions/useIsMutating.md index d7c44f067fc..62ce832f2c7 100644 --- a/docs/framework/preact/reference/functions/useIsMutating.md +++ b/docs/framework/preact/reference/functions/useIsMutating.md @@ -20,6 +20,17 @@ The `useIsMutating` hook returns the `number` of mutations that your application The [MutationFilters](../interfaces/MutationFilters.md) to narrow down the matched mutations. + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md index d45c7a14880..c8d841db68c 100644 --- a/docs/framework/preact/reference/functions/useMutation.md +++ b/docs/framework/preact/reference/functions/useMutation.md @@ -38,6 +38,26 @@ Unlike queries, mutations are typically used to create/update/delete data or per The [UseMutationOptions](../interfaces/UseMutationOptions.md) to use — everything you can pass to `useMutation`. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md index 5afc02f1006..b12b59df589 100644 --- a/docs/framework/preact/reference/functions/useQuery.md +++ b/docs/framework/preact/reference/functions/useQuery.md @@ -3,6 +3,22 @@ id: useQuery title: useQuery --- +## Overview + +```ts +function useQuery(options: DefinedInitialDataOptions, queryClient?: QueryClient): DefinedUseQueryResult; +function useQuery(options: UndefinedInitialDataOptions, queryClient?: QueryClient): UseQueryResult; +function useQuery(options: UseQueryOptions, queryClient?: QueryClient): UseQueryResult; +``` + +- [`DefinedInitialDataOptions` → `DefinedUseQueryResult`](#call-signature-1): This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). +- [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-2) +- [`UseQueryOptions` → `UseQueryResult`](#call-signature-3) + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -84,6 +100,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -185,6 +203,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -382,3 +402,96 @@ function Posts() { ) } ``` + + + +## Parameters + +### options + +[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +The [UseQueryOptions](../interfaces/UseQueryOptions.md) to use — everything you can pass to `useQuery`. + + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + + + +## Returns + +[`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> + +The current query result. `status` is `pending` if there is no cached data to display, `error` if +the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` +are derived booleans for convenience. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md index cb697b7bdbc..7125367e188 100644 --- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md +++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md @@ -44,6 +44,40 @@ Caveat: cancellation does not work. The [UseSuspenseInfiniteQueryOptions](../interfaces/UseSuspenseInfiniteQueryOptions.md) to use — the same options as `useInfiniteQuery`, minus the ones listed above. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md index c19d6bf748c..a63d3ac5161 100644 --- a/docs/framework/preact/reference/functions/useSuspenseQueries.md +++ b/docs/framework/preact/reference/functions/useSuspenseQueries.md @@ -3,6 +3,20 @@ id: useSuspenseQueries title: useSuspenseQueries --- +## Overview + +```ts +function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; +function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; +``` + +- [`object` → `TCombinedResult`](#call-signature-1): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. +- [`object` → `TCombinedResult`](#call-signature-2): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -273,6 +287,8 @@ function ErrorBoundary({ } ``` + + ## Call Signature ```ts @@ -476,3 +492,45 @@ function ErrorBoundary({ return children } ``` + + + +## Parameters + +### options + +The `queries` array to run in Suspense, and an optional `combine` function. + +#### combine? + +(`result`: `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>, `GetUseSuspenseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \{ \[K in string \| number \| symbol\]: GetUseSuspenseQueryResult\\]\> \}) => `TCombinedResult` + +Use this to combine the results of the queries into a single value. The result will be structurally +shared to be as referentially stable as possible. + +#### queries + +readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>, `GetUseSuspenseQueryOptions`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...(...)[]`\] *extends* \[...\] ? \[..., ..., ...\] : ... *extends* ... ? ... : ... : `unknown`[] *extends* \[`...Tails[]`\] ? \[`...Tails[]`\] : \[`...(...)[]`\] *extends* ...[] ? ...[] : ...[] : `unknown`[] *extends* `T` ? `T` : `T` *extends* [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] ? [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] : [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]\] + +An array with query option objects identical to `useSuspenseQuery`. + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context +will be used. + + + +## Returns + +`TCombinedResult` + +The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be +defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived +flags set accordingly). + +Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone +stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid +this, make sure to set a high enough `staleTime`. Cancellation does not work. diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md index 2b919a92c00..2c70e2c0d25 100644 --- a/docs/framework/preact/reference/functions/useSuspenseQuery.md +++ b/docs/framework/preact/reference/functions/useSuspenseQuery.md @@ -40,6 +40,37 @@ Caveat: cancellation does not work. The [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) to use — the same options as `useQuery`, minus the ones listed above. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/react/reference/functions/HydrationBoundary.md b/docs/framework/react/reference/functions/HydrationBoundary.md index 76a2b31e128..ccd5902c324 100644 --- a/docs/framework/react/reference/functions/HydrationBoundary.md +++ b/docs/framework/react/reference/functions/HydrationBoundary.md @@ -21,6 +21,17 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`. [`HydrationBoundaryProps`](../interfaces/HydrationBoundaryProps.md) + + +#### `props` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `children?` | `ReactNode` | The components to render — always rendered unconditionally, not gated on hydration. New queries are hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it lands. | +| `options?` | [`OmitKeyof`](../type-aliases/OmitKeyof.md)\<[`HydrateOptions`](../interfaces/HydrateOptions.md), `"defaultOptions"`\> & `object` | Optional. Note: unlike `hydrate`, `mutations` cannot be set here. | +| `queryClient?` | [`QueryClient`](../classes/QueryClient.md) | Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will be used. | +| `state` | [`DehydratedState`](../interfaces/DehydratedState.md) \| `null` \| `undefined` | The state to hydrate. | + ## Returns `ReactElement`\<`unknown`, `string` \| `JSXElementConstructor`\<`any`\>\> diff --git a/docs/framework/react/reference/functions/QueryClientProvider.md b/docs/framework/react/reference/functions/QueryClientProvider.md index 68d6e73f2e1..aef10f67bee 100644 --- a/docs/framework/react/reference/functions/QueryClientProvider.md +++ b/docs/framework/react/reference/functions/QueryClientProvider.md @@ -22,6 +22,15 @@ comes back online). [`QueryClientProviderProps`](../type-aliases/QueryClientProviderProps.md) + + +#### `props` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `children?` | `React.ReactNode` | The components that get access to the provided `QueryClient`. | +| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | + ## Returns `Element` diff --git a/docs/framework/react/reference/functions/QueryErrorResetBoundary.md b/docs/framework/react/reference/functions/QueryErrorResetBoundary.md index d2f56cc8735..701b7a6b02b 100644 --- a/docs/framework/react/reference/functions/QueryErrorResetBoundary.md +++ b/docs/framework/react/reference/functions/QueryErrorResetBoundary.md @@ -21,6 +21,14 @@ reset any query errors within the boundaries of the component. [`QueryErrorResetBoundaryProps`](../interfaces/QueryErrorResetBoundaryProps.md) + + +#### `props` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `children` | \| `ReactNode` \| [`QueryErrorResetBoundaryFunction`](../type-aliases/QueryErrorResetBoundaryFunction.md) | Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and returns a node. | + ## Returns `Element` diff --git a/docs/framework/react/reference/functions/dehydrate.md b/docs/framework/react/reference/functions/dehydrate.md index 201200efdfa..2c4abfc7754 100644 --- a/docs/framework/react/reference/functions/dehydrate.md +++ b/docs/framework/react/reference/functions/dehydrate.md @@ -25,10 +25,30 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `mutations` | `DehydratedMutation`[] | +| `queries` | `DehydratedQuery`[] | + ## Example ```ts diff --git a/docs/framework/react/reference/functions/hydrate.md b/docs/framework/react/reference/functions/hydrate.md index 435603b3af4..e0f723266cc 100644 --- a/docs/framework/react/reference/functions/hydrate.md +++ b/docs/framework/react/reference/functions/hydrate.md @@ -34,6 +34,17 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`HydrateOptions`](../interfaces/HydrateOptions.md) + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/react/reference/functions/infiniteQueryOptions.md b/docs/framework/react/reference/functions/infiniteQueryOptions.md index e1d3e1208c0..628310ce015 100644 --- a/docs/framework/react/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/react/reference/functions/infiniteQueryOptions.md @@ -5,6 +5,22 @@ redirect_from: - framework/react/reference/infiniteQueryOptions --- +## Overview + +```ts +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +``` + +- [`DefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -91,6 +107,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -174,6 +192,8 @@ function Comments({ postId }: { postId: string }) { [useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + + ## Call Signature ```ts @@ -256,3 +276,19 @@ function Comments({ postId }: { postId: string }) { ### See [useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + + + +## Parameters + +### options + +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/react/reference/functions/matchMutation.md b/docs/framework/react/reference/functions/matchMutation.md index 0bc16b361f7..7903e79a6b6 100644 --- a/docs/framework/react/reference/functions/matchMutation.md +++ b/docs/framework/react/reference/functions/matchMutation.md @@ -19,6 +19,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/react/reference/functions/matchQuery.md b/docs/framework/react/reference/functions/matchQuery.md index ce575fc2b69..961ff43c3d1 100644 --- a/docs/framework/react/reference/functions/matchQuery.md +++ b/docs/framework/react/reference/functions/matchQuery.md @@ -18,6 +18,19 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/react/reference/functions/mutationOptions.md b/docs/framework/react/reference/functions/mutationOptions.md index 28562060e84..f8e5477c4c0 100644 --- a/docs/framework/react/reference/functions/mutationOptions.md +++ b/docs/framework/react/reference/functions/mutationOptions.md @@ -5,6 +5,20 @@ redirect_from: - framework/react/reference/mutationOptions --- +## Overview + +```ts +function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; +function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; +``` + +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -74,6 +88,8 @@ function SavingIndicator() { } ``` + + ## Call Signature ```ts @@ -142,3 +158,22 @@ function CreatePost() { return } ``` + + + +## Parameters + +### options + +`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The mutation options to use, identical to what you'd pass to `useMutation`, without a +`mutationKey`. + + + +## Returns + +`Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The same options object, unchanged. diff --git a/docs/framework/react/reference/functions/noop.md b/docs/framework/react/reference/functions/noop.md index 01fb409f4e9..12d0e1a36b0 100644 --- a/docs/framework/react/reference/functions/noop.md +++ b/docs/framework/react/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/react/reference/functions/queryOptions.md b/docs/framework/react/reference/functions/queryOptions.md index cce05c912b7..16f33e108a9 100644 --- a/docs/framework/react/reference/functions/queryOptions.md +++ b/docs/framework/react/reference/functions/queryOptions.md @@ -5,6 +5,22 @@ redirect_from: - framework/react/reference/queryOptions --- +## Overview + +```ts +function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; +``` + +- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `UseQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -82,6 +98,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -151,6 +169,8 @@ function Post({ id }: { id: string }) { } ``` + + ## Call Signature ```ts @@ -244,3 +264,19 @@ function Post({ postId }: { postId: number | undefined }) { return

{data?.title}

} ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/react/reference/functions/useInfiniteQuery.md b/docs/framework/react/reference/functions/useInfiniteQuery.md index d22795064cf..d7541dd172f 100644 --- a/docs/framework/react/reference/functions/useInfiniteQuery.md +++ b/docs/framework/react/reference/functions/useInfiniteQuery.md @@ -5,6 +5,22 @@ redirect_from: - framework/react/reference/useInfiniteQuery --- +## Overview + +```ts +function useInfiniteQuery(options: DefinedInitialDataInfiniteOptions, queryClient?: QueryClient): DefinedUseInfiniteQueryResult; +function useInfiniteQuery(options: UndefinedInitialDataInfiniteOptions, queryClient?: QueryClient): UseInfiniteQueryResult; +function useInfiniteQuery(options: UseInfiniteQueryOptions, queryClient?: QueryClient): UseInfiniteQueryResult; +``` + +- [`DefinedInitialDataInfiniteOptions` → `DefinedUseInfiniteQueryResult`](#call-signature-1): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`UndefinedInitialDataInfiniteOptions` → `UseInfiniteQueryResult`](#call-signature-2): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`UseInfiniteQueryOptions` → `UseInfiniteQueryResult`](#call-signature-3): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -101,6 +117,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -261,6 +279,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -449,3 +469,108 @@ function Comments({ postId }: { postId: string | undefined }) { ) } ``` + + + +## Parameters + +### options + +[`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [UseInfiniteQueryOptions](../interfaces/UseInfiniteQueryOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + + + +## Returns + +[`UseInfiniteQueryResult`](../type-aliases/UseInfiniteQueryResult.md)\<`TData`, `TError`\> + +The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`, +`hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and +`data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default +`InfiniteData` shape. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/react/reference/functions/useIsFetching.md b/docs/framework/react/reference/functions/useIsFetching.md index 19843c9734b..8930649d3e9 100644 --- a/docs/framework/react/reference/functions/useIsFetching.md +++ b/docs/framework/react/reference/functions/useIsFetching.md @@ -22,6 +22,19 @@ the background (useful for app-wide loading indicators). The [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched queries. + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/react/reference/functions/useIsMutating.md b/docs/framework/react/reference/functions/useIsMutating.md index e99bbbd0030..04512f1503e 100644 --- a/docs/framework/react/reference/functions/useIsMutating.md +++ b/docs/framework/react/reference/functions/useIsMutating.md @@ -22,6 +22,17 @@ The `useIsMutating` hook returns the `number` of mutations that your application The [MutationFilters](../interfaces/MutationFilters.md) to narrow down the matched mutations. + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/react/reference/functions/useMutation.md b/docs/framework/react/reference/functions/useMutation.md index febbbba063b..bbf8cf01111 100644 --- a/docs/framework/react/reference/functions/useMutation.md +++ b/docs/framework/react/reference/functions/useMutation.md @@ -40,6 +40,26 @@ Unlike queries, mutations are typically used to create/update/delete data or per The [UseMutationOptions](../interfaces/UseMutationOptions.md) to use — everything you can pass to `useMutation`. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/react/reference/functions/useQuery.md b/docs/framework/react/reference/functions/useQuery.md index 94a4b35d05d..fea552110b9 100644 --- a/docs/framework/react/reference/functions/useQuery.md +++ b/docs/framework/react/reference/functions/useQuery.md @@ -5,6 +5,22 @@ redirect_from: - framework/react/reference/useQuery --- +## Overview + +```ts +function useQuery(options: DefinedInitialDataOptions, queryClient?: QueryClient): DefinedUseQueryResult; +function useQuery(options: UndefinedInitialDataOptions, queryClient?: QueryClient): UseQueryResult; +function useQuery(options: UseQueryOptions, queryClient?: QueryClient): UseQueryResult; +``` + +- [`DefinedInitialDataOptions` → `DefinedUseQueryResult`](#call-signature-1): This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). +- [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-2) +- [`UseQueryOptions` → `UseQueryResult`](#call-signature-3) + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -86,6 +102,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -187,6 +205,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -384,3 +404,96 @@ function Posts() { ) } ``` + + + +## Parameters + +### options + +[`UseQueryOptions`](../interfaces/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +The [UseQueryOptions](../interfaces/UseQueryOptions.md) to use — everything you can pass to `useQuery`. + + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + + + +## Returns + +[`UseQueryResult`](../type-aliases/UseQueryResult.md)\<`TData`, `TError`\> + +The current query result. `status` is `pending` if there is no cached data to display, `error` if +the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` +are derived booleans for convenience. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md index 41f9cf42375..08f0e617e51 100644 --- a/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md +++ b/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md @@ -46,6 +46,40 @@ Caveat: cancellation does not work. The [UseSuspenseInfiniteQueryOptions](../interfaces/UseSuspenseInfiniteQueryOptions.md) to use — the same options as `useInfiniteQuery`, minus the ones listed above. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/react/reference/functions/useSuspenseQueries.md b/docs/framework/react/reference/functions/useSuspenseQueries.md index ceee7bdf046..d159cb261b0 100644 --- a/docs/framework/react/reference/functions/useSuspenseQueries.md +++ b/docs/framework/react/reference/functions/useSuspenseQueries.md @@ -5,6 +5,20 @@ redirect_from: - framework/react/reference/useSuspenseQueries --- +## Overview + +```ts +function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; +function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; +``` + +- [`object` → `TCombinedResult`](#call-signature-1): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. +- [`object` → `TCombinedResult`](#call-signature-2): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -215,6 +229,8 @@ function App() { } ``` + + ## Call Signature ```ts @@ -378,3 +394,45 @@ function App() { ) } ``` + + + +## Parameters + +### options + +The `queries` array to run in Suspense, and an optional `combine` function. + +#### combine? + +(`result`: `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>, `GetUseSuspenseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \{ \[K in string \| number \| symbol\]: GetUseSuspenseQueryResult\\]\> \}) => `TCombinedResult` + +Use this to combine the results of the queries into a single value. The result will be structurally +shared to be as referentially stable as possible. + +#### queries + +readonly \[`T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryOptions`\<`Head`\>, `GetUseSuspenseQueryOptions`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...(...)[]`\] *extends* \[...\] ? \[..., ..., ...\] : ... *extends* ... ? ... : ... : `unknown`[] *extends* \[`...Tails[]`\] ? \[`...Tails[]`\] : \[`...(...)[]`\] *extends* ...[] ? ...[] : ...[] : `unknown`[] *extends* `T` ? `T` : `T` *extends* [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] ? [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>[] : [`UseSuspenseQueryOptions`](../interfaces/UseSuspenseQueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]\] + +An array with query option objects identical to `useSuspenseQuery`. + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context +will be used. + + + +## Returns + +`TCombinedResult` + +The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be +defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived +flags set accordingly). + +Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone +stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid +this, make sure to set a high enough `staleTime`. Cancellation does not work. diff --git a/docs/framework/react/reference/functions/useSuspenseQuery.md b/docs/framework/react/reference/functions/useSuspenseQuery.md index 40e5c4accd2..c8921fbb1da 100644 --- a/docs/framework/react/reference/functions/useSuspenseQuery.md +++ b/docs/framework/react/reference/functions/useSuspenseQuery.md @@ -42,6 +42,37 @@ Caveat: cancellation does not work. The [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) to use — the same options as `useQuery`, minus the ones listed above. + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/solid/reference/functions/QueryClientProvider.md b/docs/framework/solid/reference/functions/QueryClientProvider.md index 586c522dd63..fca0e621e48 100644 --- a/docs/framework/solid/reference/functions/QueryClientProvider.md +++ b/docs/framework/solid/reference/functions/QueryClientProvider.md @@ -20,6 +20,15 @@ comes back online). [`QueryClientProviderProps`](../type-aliases/QueryClientProviderProps.md) + + +#### `props` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `children?` | `JSX.Element` | The components that get access to the provided `QueryClient`. | +| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | + ## Returns `Element` diff --git a/docs/framework/solid/reference/functions/dehydrate.md b/docs/framework/solid/reference/functions/dehydrate.md index 782758a4380..50a55efe0c5 100644 --- a/docs/framework/solid/reference/functions/dehydrate.md +++ b/docs/framework/solid/reference/functions/dehydrate.md @@ -25,10 +25,30 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `mutations` | `DehydratedMutation`[] | +| `queries` | `DehydratedQuery`[] | + ## Example ```ts diff --git a/docs/framework/solid/reference/functions/hydrate.md b/docs/framework/solid/reference/functions/hydrate.md index 926f21b445c..aec6df48f7b 100644 --- a/docs/framework/solid/reference/functions/hydrate.md +++ b/docs/framework/solid/reference/functions/hydrate.md @@ -34,6 +34,17 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`HydrateOptions`](../interfaces/HydrateOptions.md) + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | `MutationOptions`\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | `QueryOptions`\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/solid/reference/functions/infiniteQueryOptions.md b/docs/framework/solid/reference/functions/infiniteQueryOptions.md index 73cba2889fe..c843aa34eed 100644 --- a/docs/framework/solid/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/solid/reference/functions/infiniteQueryOptions.md @@ -5,6 +5,20 @@ redirect_from: - framework/solid/reference/infiniteQueryOptions --- +## Overview + +```ts +function infiniteQueryOptions(options: InfiniteQueryOptions & object): InfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: InfiniteQueryOptions & object): InfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +``` + +- [`InfiniteQueryOptions` → `InfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`InfiniteQueryOptions` → `InfiniteQueryOptions`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -91,6 +105,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -176,3 +192,21 @@ function Comments(props: { postId: string }) { ) } ``` + + + +## Parameters + +### options + +[`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` + +The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + + +## Returns + +[`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/solid/reference/functions/matchMutation.md b/docs/framework/solid/reference/functions/matchMutation.md index 0bc16b361f7..7903e79a6b6 100644 --- a/docs/framework/solid/reference/functions/matchMutation.md +++ b/docs/framework/solid/reference/functions/matchMutation.md @@ -19,6 +19,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/solid/reference/functions/matchQuery.md b/docs/framework/solid/reference/functions/matchQuery.md index ce575fc2b69..961ff43c3d1 100644 --- a/docs/framework/solid/reference/functions/matchQuery.md +++ b/docs/framework/solid/reference/functions/matchQuery.md @@ -18,6 +18,19 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/solid/reference/functions/mutationOptions.md b/docs/framework/solid/reference/functions/mutationOptions.md index f30b791ac06..5da51027caf 100644 --- a/docs/framework/solid/reference/functions/mutationOptions.md +++ b/docs/framework/solid/reference/functions/mutationOptions.md @@ -5,6 +5,20 @@ redirect_from: - framework/solid/reference/mutationOptions --- +## Overview + +```ts +function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; +function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; +``` + +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -74,6 +88,8 @@ function SavingIndicator() { } ``` + + ## Call Signature ```ts @@ -142,3 +158,22 @@ function CreatePost() { return } ``` + + + +## Parameters + +### options + +`Omit`\<[`MutationOptions`](../interfaces/MutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The mutation options to use, identical to what you'd pass to `useMutation`, without a +`mutationKey`. + + + +## Returns + +`Omit`\<[`MutationOptions`](../interfaces/MutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The same options object, unchanged. diff --git a/docs/framework/solid/reference/functions/noop.md b/docs/framework/solid/reference/functions/noop.md index 01fb409f4e9..12d0e1a36b0 100644 --- a/docs/framework/solid/reference/functions/noop.md +++ b/docs/framework/solid/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/solid/reference/functions/queryOptions.md b/docs/framework/solid/reference/functions/queryOptions.md index c586f4d70b3..412c365cff6 100644 --- a/docs/framework/solid/reference/functions/queryOptions.md +++ b/docs/framework/solid/reference/functions/queryOptions.md @@ -5,6 +5,20 @@ redirect_from: - framework/solid/reference/queryOptions --- +## Overview + +```ts +function queryOptions(options: QueryOptions & object): QueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: QueryOptions & object): QueryOptions & object & QueryKeyWithDataTag; +``` + +- [`QueryOptions` → `QueryOptions`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`QueryOptions` → `QueryOptions`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -84,6 +98,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -159,3 +175,21 @@ function Post(props: { id: string }) { ) } ``` + + + +## Parameters + +### options + +[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` + +The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. + + + +## Returns + +[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/solid/reference/functions/useInfiniteQuery.md b/docs/framework/solid/reference/functions/useInfiniteQuery.md index 4cc42c06768..1bd24bd077f 100644 --- a/docs/framework/solid/reference/functions/useInfiniteQuery.md +++ b/docs/framework/solid/reference/functions/useInfiniteQuery.md @@ -5,6 +5,20 @@ redirect_from: - framework/solid/reference/useInfiniteQuery --- +## Overview + +```ts +function useInfiniteQuery(options: DefinedInitialDataInfiniteOptions, queryClient?: Accessor): DefinedUseInfiniteQueryResult; +function useInfiniteQuery(options: UndefinedInitialDataInfiniteOptions, queryClient?: Accessor): UseInfiniteQueryResult; +``` + +- [`DefinedInitialDataInfiniteOptions` → `DefinedUseInfiniteQueryResult`](#call-signature-1): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`UndefinedInitialDataInfiniteOptions` → `UseInfiniteQueryResult`](#call-signature-2): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -105,6 +119,8 @@ function Projects() { } ``` + + ## Call Signature ```ts @@ -257,3 +273,72 @@ function Projects() { ) } ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +An accessor returning the [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything +you can pass to `useInfiniteQuery`. + +### queryClient? + +`Accessor`\<[`QueryClient`](../classes/QueryClient.md)\> + +An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context +will be used. + + + +## Returns + +[`UseInfiniteQueryResult`](../type-aliases/UseInfiniteQueryResult.md)\<`TData`, `TError`\> + +The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`, +`hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. `data.pages` and +`data.pageParams` are also added, as long as a `select` doesn't change `TData` away from its default +`InfiniteData` shape. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/solid/reference/functions/useQuery.md b/docs/framework/solid/reference/functions/useQuery.md index 54b8c202c5e..a16c80d0241 100644 --- a/docs/framework/solid/reference/functions/useQuery.md +++ b/docs/framework/solid/reference/functions/useQuery.md @@ -5,6 +5,20 @@ redirect_from: - framework/solid/reference/useQuery --- +## Overview + +```ts +function useQuery(options: UndefinedInitialDataOptions, queryClient?: () => QueryClient): UseQueryResult; +function useQuery(options: DefinedInitialDataOptions, queryClient?: () => QueryClient): DefinedUseQueryResult; +``` + +- [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-1): Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — `enabled: false` skips the initial fetch. +- [`DefinedInitialDataOptions` → `DefinedUseQueryResult`](#call-signature-2): Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — `enabled: false` skips the initial fetch. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -213,6 +227,8 @@ function Posts() { } ``` + + ## Call Signature ```ts @@ -299,3 +315,64 @@ function Posts() { ) } ``` + + + +## Parameters + +### options + +[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +An accessor returning the [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use — everything you can +pass to `useQuery`, with `initialData` set. + +### queryClient? + +() => [`QueryClient`](../classes/QueryClient.md) + +An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context +will be used. + + + +## Returns + +[`DefinedUseQueryResult`](../type-aliases/DefinedUseQueryResult.md)\<`TData`, `TError`\> + +The current query result, as a Solid store, typed so that `status` is `success` — or `error` if a +fetch attempt fails while keeping the existing data (`status` never resolves to `pending` in this overload's +type, since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for +convenience. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/svelte/reference/functions/createInfiniteQuery.md b/docs/framework/svelte/reference/functions/createInfiniteQuery.md index 20ddcbff342..f50bdc70edc 100644 --- a/docs/framework/svelte/reference/functions/createInfiniteQuery.md +++ b/docs/framework/svelte/reference/functions/createInfiniteQuery.md @@ -3,6 +3,22 @@ id: createInfiniteQuery title: createInfiniteQuery --- +## Overview + +```ts +function createInfiniteQuery(options: Accessor>, queryClient?: Accessor): DefinedCreateInfiniteQueryResult; +function createInfiniteQuery(options: Accessor>, queryClient?: Accessor): CreateInfiniteQueryResult; +function createInfiniteQuery(options: Accessor>, queryClient?: Accessor): CreateInfiniteQueryResult; +``` + +- [`DefinedInitialDataInfiniteOptions` → `DefinedCreateInfiniteQueryResult`](#call-signature-1): The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryResult`](#call-signature-2): The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`CreateInfiniteQueryOptions` → `CreateInfiniteQueryResult`](#call-signature-3): The options for `createInfiniteQuery` are identical to `createQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -66,6 +82,8 @@ to page through the query. [infiniteQueryOptions](infiniteQueryOptions.md) to share these options between `createInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`. + + ## Call Signature ```ts @@ -129,6 +147,8 @@ to page through the query. [infiniteQueryOptions](infiniteQueryOptions.md) to share these options between `createInfiniteQuery` and imperative APIs like `queryClient.infiniteQuery`. + + ## Call Signature ```ts @@ -272,3 +292,107 @@ sentinel element after the list:
{/if} ``` + + + +## Parameters + +### options + +[`Accessor`](../type-aliases/Accessor.md)\<[`CreateInfiniteQueryOptions`](../type-aliases/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>\> + +The [CreateInfiniteQueryOptions](../type-aliases/CreateInfiniteQueryOptions.md) to use — everything you can pass to +`createInfiniteQuery`, wrapped in an [Accessor](../type-aliases/Accessor.md) so options can be reactive. + + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### queryClient? + +[`Accessor`](../type-aliases/Accessor.md)\<[`QueryClient`](../classes/QueryClient.md)\> + +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + + + +## Returns + +[`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> + +The current query result, plus `fetchNextPage`/`fetchPreviousPage`/`hasNextPage`/`hasPreviousPage` +to page through the query. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/svelte/reference/functions/createQuery.md b/docs/framework/svelte/reference/functions/createQuery.md index d6a503566f7..89b5848149a 100644 --- a/docs/framework/svelte/reference/functions/createQuery.md +++ b/docs/framework/svelte/reference/functions/createQuery.md @@ -3,6 +3,22 @@ id: createQuery title: createQuery --- +## Overview + +```ts +function createQuery(options: Accessor>, queryClient?: Accessor): DefinedCreateQueryResult; +function createQuery(options: Accessor>, queryClient?: Accessor): CreateQueryResult; +function createQuery(options: Accessor>, queryClient?: Accessor): CreateQueryResult; +``` + +- [`DefinedInitialDataOptions` → `DefinedCreateQueryResult`](#call-signature-1): Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — `enabled: false` skips the initial fetch. +- [`UndefinedInitialDataOptions` → `CreateQueryResult`](#call-signature-2): Subscribes to a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. The query runs when the options call for it — `enabled: false` skips the initial fetch. +- [`CreateQueryOptions` → `CreateQueryResult`](#call-signature-3) + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -88,6 +104,8 @@ since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived ``` + + ## Call Signature ```ts @@ -194,6 +212,8 @@ The same query, checking `isPending`/`isError` instead of `status` — pick whic {/if} ``` + + ## Call Signature ```ts @@ -349,3 +369,97 @@ Paginated data, keeping the previous page's data visible while the next page loa Next Page ``` + + + +## Parameters + +### options + +[`Accessor`](../type-aliases/Accessor.md)\<[`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>\> + +The [CreateQueryOptions](../type-aliases/CreateQueryOptions.md) to use — everything you can pass to `createQuery`, wrapped +in an [Accessor](../type-aliases/Accessor.md) so options can be reactive. + + + +#### `options` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryData` \| () => `TQueryData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryData`\>, `TError`, `NonFunctionGuard`\<`TQueryData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### queryClient? + +[`Accessor`](../type-aliases/Accessor.md)\<[`QueryClient`](../classes/QueryClient.md)\> + +Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will +be used. + + + +## Returns + +[`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> + +The current query result. `status` is `pending` if there is no cached data to display, `error` if +the last fetch attempt failed, or `success` if the query has data to display. `isPending`/`isSuccess`/`isError` +are derived booleans for convenience. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/svelte/reference/functions/dehydrate.md b/docs/framework/svelte/reference/functions/dehydrate.md index 201200efdfa..2c4abfc7754 100644 --- a/docs/framework/svelte/reference/functions/dehydrate.md +++ b/docs/framework/svelte/reference/functions/dehydrate.md @@ -25,10 +25,30 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `mutations` | `DehydratedMutation`[] | +| `queries` | `DehydratedQuery`[] | + ## Example ```ts diff --git a/docs/framework/svelte/reference/functions/hydrate.md b/docs/framework/svelte/reference/functions/hydrate.md index 435603b3af4..e0f723266cc 100644 --- a/docs/framework/svelte/reference/functions/hydrate.md +++ b/docs/framework/svelte/reference/functions/hydrate.md @@ -34,6 +34,17 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`HydrateOptions`](../interfaces/HydrateOptions.md) + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md index cbe59c6cdba..429d7d50e4a 100644 --- a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md @@ -3,6 +3,20 @@ id: infiniteQueryOptions title: infiniteQueryOptions --- +## Overview + +```ts +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +``` + +- [`DefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`. These options can be shared across `createInfiniteQuery` calls and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`. These options can be shared across `createInfiniteQuery` calls and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -89,6 +103,8 @@ visible alongside the error: ``` + + ## Call Signature ```ts @@ -176,3 +192,22 @@ A parameterized factory, so the same options object can be reused per `postId`: {/if} ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to +`createInfiniteQuery`. + + + +## Returns + +[`CreateInfiniteQueryOptions`](../type-aliases/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/svelte/reference/functions/matchMutation.md b/docs/framework/svelte/reference/functions/matchMutation.md index 0bc16b361f7..7903e79a6b6 100644 --- a/docs/framework/svelte/reference/functions/matchMutation.md +++ b/docs/framework/svelte/reference/functions/matchMutation.md @@ -19,6 +19,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/svelte/reference/functions/matchQuery.md b/docs/framework/svelte/reference/functions/matchQuery.md index ce575fc2b69..961ff43c3d1 100644 --- a/docs/framework/svelte/reference/functions/matchQuery.md +++ b/docs/framework/svelte/reference/functions/matchQuery.md @@ -18,6 +18,19 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/svelte/reference/functions/mutationOptions.md b/docs/framework/svelte/reference/functions/mutationOptions.md index d6d51f94415..14ae7f1940d 100644 --- a/docs/framework/svelte/reference/functions/mutationOptions.md +++ b/docs/framework/svelte/reference/functions/mutationOptions.md @@ -3,6 +3,20 @@ id: mutationOptions title: mutationOptions --- +## Overview + +```ts +function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; +function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; +``` + +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`. This overload requires `mutationKey`, so the resulting options can be looked up elsewhere (e.g. with `useMutationState`). +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -73,6 +87,8 @@ Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "savi {/if} ``` + + ## Call Signature ```ts @@ -134,3 +150,21 @@ The same options object. ``` + + + +## Parameters + +### options + +`Omit`\<[`CreateMutationOptions`](../type-aliases/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The options to use — everything you can pass to `createMutation`. + + + +## Returns + +`Omit`\<[`CreateMutationOptions`](../type-aliases/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The same options object. diff --git a/docs/framework/svelte/reference/functions/noop.md b/docs/framework/svelte/reference/functions/noop.md index 01fb409f4e9..12d0e1a36b0 100644 --- a/docs/framework/svelte/reference/functions/noop.md +++ b/docs/framework/svelte/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/svelte/reference/functions/queryOptions.md b/docs/framework/svelte/reference/functions/queryOptions.md index 348f3676cc8..8ddcde78fb5 100644 --- a/docs/framework/svelte/reference/functions/queryOptions.md +++ b/docs/framework/svelte/reference/functions/queryOptions.md @@ -3,6 +3,20 @@ id: queryOptions title: queryOptions --- +## Overview + +```ts +function queryOptions(options: DefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +``` + +- [`DefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -82,6 +96,8 @@ The same options object, typed so that `queryKey` carries the inferred data type ``` + + ## Call Signature ```ts @@ -156,3 +172,21 @@ A parameterized factory, so the same options object can be reused per `id`:

{query.data.title}

{/if} ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `createQuery`. + + + +## Returns + +[`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/svelte/reference/functions/useHydrate.md b/docs/framework/svelte/reference/functions/useHydrate.md index 9f54479fb66..59567930909 100644 --- a/docs/framework/svelte/reference/functions/useHydrate.md +++ b/docs/framework/svelte/reference/functions/useHydrate.md @@ -31,6 +31,17 @@ The dehydrated state to hydrate into the cache, as produced by `dehydrate`. [HydrateOptions](../interfaces/HydrateOptions.md) to control the hydration. + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/svelte/reference/functions/useIsFetching.md b/docs/framework/svelte/reference/functions/useIsFetching.md index 5d3bf0f8dde..0588d630b4d 100644 --- a/docs/framework/svelte/reference/functions/useIsFetching.md +++ b/docs/framework/svelte/reference/functions/useIsFetching.md @@ -21,6 +21,19 @@ fetching in the background (useful for app-wide loading indicators). [QueryFilters](../interfaces/QueryFilters.md) to narrow down which queries to count. Omit to count every fetching query. + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/svelte/reference/functions/useIsMutating.md b/docs/framework/svelte/reference/functions/useIsMutating.md index 1e733178ba3..77d7579ad58 100644 --- a/docs/framework/svelte/reference/functions/useIsMutating.md +++ b/docs/framework/svelte/reference/functions/useIsMutating.md @@ -20,6 +20,17 @@ running (useful for app-wide loading indicators). [MutationFilters](../interfaces/MutationFilters.md) to narrow down which mutations to count. + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/svelte/reference/functions/useMutationState.md b/docs/framework/svelte/reference/functions/useMutationState.md index 4eb83ce595a..85fb5499459 100644 --- a/docs/framework/svelte/reference/functions/useMutationState.md +++ b/docs/framework/svelte/reference/functions/useMutationState.md @@ -32,6 +32,15 @@ state. The `filters` to narrow down matched mutations, and an optional `select` to transform the mutation state. + + +#### `options` properties + +| Property | Type | +| ------ | ------ | +| `filters?` | [`MutationFilters`](../interfaces/MutationFilters.md) | +| `select?` | (`mutation`: `TMutation`) => `TResult` | + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/vue/reference/functions/dehydrate.md b/docs/framework/vue/reference/functions/dehydrate.md index 782758a4380..50a55efe0c5 100644 --- a/docs/framework/vue/reference/functions/dehydrate.md +++ b/docs/framework/vue/reference/functions/dehydrate.md @@ -25,10 +25,30 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) + + +### Result properties + +| Property | Type | +| ------ | ------ | +| `mutations` | `DehydratedMutation`[] | +| `queries` | `DehydratedQuery`[] | + ## Example ```ts diff --git a/docs/framework/vue/reference/functions/hydrate.md b/docs/framework/vue/reference/functions/hydrate.md index 926f21b445c..aec6df48f7b 100644 --- a/docs/framework/vue/reference/functions/hydrate.md +++ b/docs/framework/vue/reference/functions/hydrate.md @@ -34,6 +34,17 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`HydrateOptions`](../interfaces/HydrateOptions.md) + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | `MutationOptions`\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | `QueryOptions`\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/vue/reference/functions/infiniteQueryOptions.md b/docs/framework/vue/reference/functions/infiniteQueryOptions.md index 7f2e6c71e27..92e85703898 100644 --- a/docs/framework/vue/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/vue/reference/functions/infiniteQueryOptions.md @@ -5,6 +5,20 @@ redirect_from: - framework/vue/reference/infiniteQueryOptions --- +## Overview + +```ts +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +``` + +- [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -75,6 +89,8 @@ const { data, isError, error, fetchNextPage } = useInfiniteQuery(projectsOptions ``` + + ## Call Signature ```ts @@ -150,3 +166,22 @@ const projectsOptions = infiniteQueryOptions({ const { data, isError, error } = useInfiniteQuery(projectsOptions) ``` + + + +## Parameters + +### options + +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfiniteOptions.md) to use — everything you can pass to +`useInfiniteQuery`, with `initialData` set. + + + +## Returns + +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/vue/reference/functions/matchMutation.md b/docs/framework/vue/reference/functions/matchMutation.md index 0bc16b361f7..7903e79a6b6 100644 --- a/docs/framework/vue/reference/functions/matchMutation.md +++ b/docs/framework/vue/reference/functions/matchMutation.md @@ -19,6 +19,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/vue/reference/functions/matchQuery.md b/docs/framework/vue/reference/functions/matchQuery.md index ce575fc2b69..961ff43c3d1 100644 --- a/docs/framework/vue/reference/functions/matchQuery.md +++ b/docs/framework/vue/reference/functions/matchQuery.md @@ -18,6 +18,19 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/vue/reference/functions/mutationOptions.md b/docs/framework/vue/reference/functions/mutationOptions.md index 7d1081744cd..c32bd9a5dd1 100644 --- a/docs/framework/vue/reference/functions/mutationOptions.md +++ b/docs/framework/vue/reference/functions/mutationOptions.md @@ -5,6 +5,24 @@ redirect_from: - framework/vue/reference/mutationOptions --- +## Overview + +```ts +function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; +function mutationOptions(options: () => WithRequired, "mutationKey">): () => WithRequired, "mutationKey">; +function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; +function mutationOptions(options: () => Omit, "mutationKey">): () => Omit, "mutationKey">; +``` + +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`WithRequired` → `WithRequired`](#call-signature-2): Same as the plain-object overload with a required `mutationKey`, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `useMutation` and the other consumers always read the current values instead of the ones captured when the options were created. +- [`Omit` → `Omit`](#call-signature-3): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. +- [`Omit` → `Omit`](#call-signature-4): Same as the plain-object overload without a `mutationKey`, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `useMutation` and the other consumers always read the current values instead of the ones captured when the options were created. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -79,6 +97,8 @@ const isCreatingPost = computed(() => creatingPosts.value.length > 0) ``` + + ## Call Signature ```ts @@ -156,6 +176,8 @@ const mutation = useMutation(createPostOptions) ``` + + ## Call Signature ```ts @@ -228,6 +250,8 @@ const mutation = useMutation(createPostOptions) ``` + + ## Call Signature ```ts @@ -303,3 +327,28 @@ const mutation = useMutation(createPostOptions) ``` + + + +## Parameters + +### options + +() => `Omit`\<[`MutationOptions`](../type-aliases/MutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +A function returning the mutation options to use, without a `mutationKey`, re-evaluated on +demand. + + + +## Returns + +A function that returns the same options object, unchanged. + +```ts +(): Omit, "mutationKey">; +``` + +#### Returns + +`Omit`\<[`MutationOptions`](../type-aliases/MutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> diff --git a/docs/framework/vue/reference/functions/noop.md b/docs/framework/vue/reference/functions/noop.md index 01fb409f4e9..12d0e1a36b0 100644 --- a/docs/framework/vue/reference/functions/noop.md +++ b/docs/framework/vue/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/vue/reference/functions/queryOptions.md b/docs/framework/vue/reference/functions/queryOptions.md index af4ddcd4b01..a36324c2395 100644 --- a/docs/framework/vue/reference/functions/queryOptions.md +++ b/docs/framework/vue/reference/functions/queryOptions.md @@ -5,6 +5,24 @@ redirect_from: - framework/vue/reference/queryOptions --- +## Overview + +```ts +function queryOptions(options: DefinedInitialQueryOptions): DefinedInitialQueryOptionsWithDataTag; +function queryOptions(options: () => DefinedInitialQueryOptions): () => DefinedInitialQueryOptionsWithDataTag; +function queryOptions(options: UndefinedInitialQueryOptions): UndefinedInitialQueryOptionsWithDataTag; +function queryOptions(options: () => UndefinedInitialQueryOptions): () => UndefinedInitialQueryOptionsWithDataTag; +``` + +- [`DefinedInitialQueryOptions` → `DefinedInitialQueryOptionsWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialQueryOptions` → `DefinedInitialQueryOptionsWithDataTag`](#call-signature-2): Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `queryClient` methods like `invalidateQueries`/`fetchQuery` always read the current values instead of the ones captured when the options were created. +- [`UndefinedInitialQueryOptions` → `UndefinedInitialQueryOptionsWithDataTag`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialQueryOptions` → `UndefinedInitialQueryOptionsWithDataTag`](#call-signature-4): Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so the `queryKey` — and anything else derived from a `ref` — reacts to changes, and so `queryClient` methods like `invalidateQueries`/`fetchQuery` always read the current values instead of the ones captured when the options were created. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -75,6 +93,8 @@ const { data, isError, error } = useQuery(postsOptions) ``` + + ## Call Signature ```ts @@ -149,6 +169,8 @@ const { data } = useQuery(postOptions) ``` + + ## Call Signature ```ts @@ -215,6 +237,8 @@ const { data, isPending, isError, error } = useQuery(postOptions('1')) ``` + + ## Call Signature ```ts @@ -311,3 +335,29 @@ const props = defineProps<{ postId: number | undefined }>() const { data, isLoading, isError, error } = useQuery(postOptions(props.postId)) ``` + + + +## Parameters + +### options + +() => [`UndefinedInitialQueryOptions`](../type-aliases/UndefinedInitialQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +A function returning the [UndefinedInitialQueryOptions](../type-aliases/UndefinedInitialQueryOptions.md) to use, re-evaluated on +demand. + + + +## Returns + +A function that returns the same options object, typed so that `queryKey` carries the inferred +data type. + +```ts +(): UndefinedInitialQueryOptionsWithDataTag; +``` + +#### Returns + +[`UndefinedInitialQueryOptionsWithDataTag`](../type-aliases/UndefinedInitialQueryOptionsWithDataTag.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> diff --git a/docs/framework/vue/reference/functions/useInfiniteQuery.md b/docs/framework/vue/reference/functions/useInfiniteQuery.md index 486bdbca68d..fb12de6fedd 100644 --- a/docs/framework/vue/reference/functions/useInfiniteQuery.md +++ b/docs/framework/vue/reference/functions/useInfiniteQuery.md @@ -5,6 +5,22 @@ redirect_from: - framework/vue/reference/useInfiniteQuery --- +## Overview + +```ts +function useInfiniteQuery(options: MaybeRefOrGetter>, queryClient?: QueryClient): UseInfiniteQueryReturnType; +function useInfiniteQuery(options: MaybeRefOrGetter>, queryClient?: QueryClient): UseInfiniteQueryReturnType; +function useInfiniteQuery(options: MaybeRefOrGetter>, queryClient?: QueryClient): UseInfiniteQueryReturnType; +``` + +- [`MaybeRefOrGetter` → `UseInfiniteQueryReturnType`](#call-signature-1): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`MaybeRefOrGetter` → `UseInfiniteQueryReturnType`](#call-signature-2): The options for `useInfiniteQuery` are identical to `useQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. +- [`MaybeRefOrGetter` → `UseInfiniteQueryReturnType`](#call-signature-3): Fallback overload for options whose `initialData` presence isn't statically known — for example, a `ref`/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -103,6 +119,8 @@ const { data, isError, error } = useInfiniteQuery({ ``` + + ## Call Signature ```ts @@ -266,6 +284,8 @@ onUnmounted(() => observer?.disconnect()) ``` + + ## Call Signature ```ts @@ -387,3 +407,30 @@ const { data, isLoading, isError, error } = useInfiniteQuery(() => { ``` + + + +## Parameters + +### options + +`MaybeRefOrGetter`\<[`UseInfiniteQueryOptions`](../type-aliases/UseInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>\> + +A `ref`, plain value, or reactive getter resolving to the [UseInfiniteQueryOptions](../type-aliases/UseInfiniteQueryOptions.md) to +use. + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin` +will be used. + + + +## Returns + +[`UseInfiniteQueryReturnType`](../type-aliases/UseInfiniteQueryReturnType.md)\<`TData`, `TError`\> + +The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchPreviousPage`, +`hasNextPage`, `hasPreviousPage`, `isFetchingNextPage`, and `isFetchingPreviousPage`. diff --git a/docs/framework/vue/reference/functions/useQuery.md b/docs/framework/vue/reference/functions/useQuery.md index 2714eb2c52d..2af0bb0593b 100644 --- a/docs/framework/vue/reference/functions/useQuery.md +++ b/docs/framework/vue/reference/functions/useQuery.md @@ -5,6 +5,22 @@ redirect_from: - framework/vue/reference/useQuery --- +## Overview + +```ts +function useQuery(options: DefinedInitialQueryOptions, queryClient?: QueryClient): UseQueryDefinedReturnType; +function useQuery(options: UndefinedInitialQueryOptions, queryClient?: QueryClient): UseQueryReturnType; +function useQuery(options: MaybeRefOrGetter>, queryClient?: QueryClient): UseQueryReturnType; +``` + +- [`DefinedInitialQueryOptions` → `UseQueryDefinedReturnType`](#call-signature-1): This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). +- [`UndefinedInitialQueryOptions` → `UseQueryReturnType`](#call-signature-2): `enabled` tracks reactive dependencies automatically as a `ref`, a plain value, or a reactive getter (`() => ...`). `queryKey` reacts through a `ref` or a reactive getter for the array itself, or `ref`s and reactive getters as individual entries. Other options are read once when passed as a plain value, and stay reactive when passed as a `ref` or a `computed`. +- [`MaybeRefOrGetter` → `UseQueryReturnType`](#call-signature-3): Fallback overload for options whose `initialData` presence isn't statically known — for example, a `ref`/reactive object built up conditionally, rather than a plain object literal. Prefer one of the other overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -86,6 +102,8 @@ const { data, isError, error } = useQuery({ ``` + + ## Call Signature ```ts @@ -259,6 +277,8 @@ const { data, isPlaceholderData, isError, error } = useQuery({ ``` + + ## Call Signature ```ts @@ -365,3 +385,28 @@ const { data, isLoading, isError, error } = useQuery(() => {

{{ data?.title }}

``` + + + +## Parameters + +### options + +`MaybeRefOrGetter`\<[`UseQueryOptions`](../type-aliases/UseQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`\>\> + +A `ref`, plain value, or reactive getter resolving to the [UseQueryOptions](../type-aliases/UseQueryOptions.md) to use. + +### queryClient? + +[`QueryClient`](../classes/QueryClient.md) + +Use this to use a custom `QueryClient`. Otherwise, the one provided by `VueQueryPlugin` +will be used. + + + +## Returns + +[`UseQueryReturnType`](../type-aliases/UseQueryReturnType.md)\<`TData`, `TError`\> + +The current query result, with `data` typed as possibly `undefined`. diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index b111f5b7e7f..f0809140703 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -210,6 +210,430 @@ async function generatePackageReferenceDocs(pkg: PackageReferenceDocsConfig) { if (pkg.redirectFrom) { await addRedirectFromToFrontmatter(outputDir, pkg.redirectFrom) } + + await addReferenceDetails(outputDir) +} + +// Splits the escaped type arguments (`\\<…\\>`) that follow a type name from the rest of the line. +function splitTypeArguments(rest: string) { + if (!rest.startsWith('\\<')) { + return { typeArguments: undefined, after: rest } + } + let depth = 0 + for (let index = 0; index < rest.length; index++) { + if (rest.startsWith('\\<', index)) { + depth++ + } else if (rest.startsWith('\\>', index) && --depth === 0) { + return { + typeArguments: rest.slice(2, index), + after: rest.slice(index + 2), + } + } + } + return { typeArguments: undefined, after: rest } +} + +// The type page a `Parameters`/`Returns` type line refers to when the whole line is that one type +// (with an optional default value), looking through wrappers that only change how the value is +// passed, i.e. aliases like `Accessor = () => T` and inline `() => T`. +// Whether a type alias only changes how its single type argument is passed, e.g. `Accessor = () => T`. +async function isWrapperAlias(outputDir: string, from: string) { + const code = (await readPage(outputDir, from))?.match( + /```ts\ntype \w+<(\w+)> = ([^\n]*);\n```/, + ) + return ( + !!code && + code[2]! + .split(' | ') + .every((member) => member === code[1] || member === `() => ${code[1]}`) + ) +} + +// The type page a `Parameters`/`Returns` type line refers to when the whole line is that one type +// (with an optional default value), looking through wrappers that only change how the value is +// passed, i.e. aliases like `Accessor = () => T` and inline `() => T`. +async function linkedTypePage(outputDir: string, typeLine: string) { + let line = typeLine + for (;;) { + line = line.replace(/^\(\) => /, '') + const link = line.match( + /^\[`\w+`\]\(\.\.\/((?:interfaces|type-aliases)\/\w+)\.md\)/, + ) + if (!link) { + return undefined + } + const { typeArguments, after } = splitTypeArguments( + line.slice(link[0].length), + ) + if (typeArguments && (await isWrapperAlias(outputDir, link[1]!))) { + line = typeArguments + continue + } + return after === '' || after.startsWith(' = ') ? link[1] : undefined + } +} + +// The name of the type a signature's code starts with, looking through the same wrappers. +async function typeNameInCode(outputDir: string, code: string) { + let type = code + for (;;) { + type = type.replace(/^\(\) => /, '') + const name = type.match(/^\w+/)?.[0] + if ( + !name || + type[name.length] !== '<' || + !(await isWrapperAlias(outputDir, `type-aliases/${name}`)) + ) { + return name + } + let depth = 0 + for (let index = name.length; index < type.length; index++) { + if (type[index] === '<') { + depth++ + } else if ( + type[index] === '>' && + type[index - 1] !== '=' && + --depth === 0 + ) { + type = type.slice(name.length + 1, index) + break + } + } + } +} + +// The property table for the first type line that has one. +async function findPropertiesTable( + outputDir: string, + typeLines: Array, +) { + for (const typeLine of typeLines) { + const link = await linkedTypePage(outputDir, typeLine) + const from = link && (await propertiesPage(outputDir, link)) + const table = from && (await readPropertiesTable(outputDir, from)) + if (table) { + return table + } + } + return undefined +} + +// The type line of each parameter and of the return value in one call signature. +function signatureTypes(signature: string) { + const parametersHeading = signature.match(/\n#{2,3} Parameters\n/) + const returnsHeading = signature.match(/\n#{2,3} Returns\n/) + const parameters = parametersHeading + ? signature.slice( + parametersHeading.index! + parametersHeading[0].length - 1, + returnsHeading?.index, + ) + : '' + // Only the headings one level below `Parameters`, not the properties of an inline object argument. + const parameterHeading = '#'.repeat( + (parametersHeading?.[0].trim().indexOf(' ') ?? 0) + 1, + ) + return { + parameters: new Map( + [ + ...parameters.matchAll( + new RegExp(`\\n${parameterHeading} (\\S+)\\n\\n([^\\n]*)`, 'g'), + ), + ].map(([, name, typeLine]) => [name!, typeLine!]), + ), + returns: returnsHeading + ? signature + .slice(returnsHeading.index! + returnsHeading[0].length) + .trim() + .split('\n')[0]! + : undefined, + } +} + +function readPage(outputDir: string, from: string) { + return readFile(resolve(outputDir, `${from}.md`), 'utf8').then( + (source) => source, + () => undefined, + ) +} + +// Resolves a type page to the interface pages it stands for: itself when it has a `## Properties` +// table, or the members of a plain alias or union. Anything else (intersections, `Omit`, `Override`, …) +// resolves to nothing, since no generated table describes it as-is. +async function resolveInterfacePages( + outputDir: string, + from: string, +): Promise | undefined> { + const source = await readPage(outputDir, from) + if (source === undefined) { + return undefined + } + if (source.includes('\n## Properties\n')) { + return [from] + } + const code = source.match( + /```ts\ntype \w+(?:<[^\n=]*>)? = ([\s\S]*?);\n```/, + )?.[1] + if (!code) { + return undefined + } + let members = code + while (/<[^<>]*>/.test(members)) { + members = members.replace(/<[^<>]*>/g, '') + } + const names = members + .split('|') + .map((member) => member.trim()) + .filter(Boolean) + if (!names.every((name) => /^\w+$/.test(name))) { + return undefined + } + const pages: Array = [] + for (const name of names) { + const resolved = + (await resolveInterfacePages(outputDir, `interfaces/${name}`)) ?? + (await resolveInterfacePages(outputDir, `type-aliases/${name}`)) + if (!resolved) { + return undefined + } + pages.push(...resolved) + } + return pages +} + +// The page whose `## Properties` table describes the type: the type itself, or the interface every +// member of a union extends. +async function propertiesPage(outputDir: string, from: string) { + const pages = await resolveInterfacePages(outputDir, from) + if (!pages?.length) { + return undefined + } + if (pages.length === 1) { + return pages[0] + } + const bases = new Set() + for (const page of pages) { + const base = (await readPage(outputDir, page))?.match( + /\n## Extends\n\n- \[`\w+`\]\((\w+)\.md\)[^\n]*\n\n##/, + )?.[1] + if (!base) { + return undefined + } + bases.add(`${dirname(page)}/${base}`) + } + return bases.size === 1 ? [...bases][0] : undefined +} + +async function readPropertiesTable(outputDir: string, from: string) { + const source = await readPage(outputDir, from) + const start = source?.indexOf('\n## Properties\n') ?? -1 + if (source === undefined || start === -1) { + return undefined + } + const fromDir = dirname(from) + return source + .slice(start + '\n## Properties\n'.length) + .trim() + .replace( + /\]\((?!https?:|#)([^)]+)\)/g, + (_, link: string) => + `](../${link.startsWith('../') ? link.slice(3) : `${fromDir}/${link}`})`, + ) +} + +// Adds to every function page without changing what TypeDoc generated: the properties of each +// argument and of the result, and an `## Overview` of every call signature on overloaded pages. The +// properties come from the generated page of the type, following plain aliases and, for a union, +// the interface all of its members extend. Types that override or omit properties get no table. +async function addReferenceDetails(outputDir: string) { + const files = await readdir(resolve(outputDir, 'functions')).catch( + () => [] as Array, + ) + for (const file of files.filter((name) => name.endsWith('.md'))) { + const pagePath = `functions/${file.slice(0, -3)}` + const pageFile = resolve(outputDir, `${pagePath}.md`) + const page = await readFile(pageFile, 'utf8') + const [head, ...signatures] = page.split('\n## Call Signature\n') + const isOverloaded = signatures.length > 1 + const lastSignature = signatures.at(-1) ?? page + + // Property tables of the arguments whose type has a `## Properties` table, and of the result. + const tables: Array<{ + id: string + title: string + table: string + parameter?: string + }> = [] + const parametersHeading = lastSignature.match(/\n#{2,3} Parameters\n/) + const returnsHeading = lastSignature.match(/\n#{2,3} Returns\n/) + const parameters = parametersHeading + ? lastSignature.slice( + parametersHeading.index! + parametersHeading[0].length - 1, + returnsHeading?.index, + ) + : '' + // Overloads describe the same arguments with different types, so a table missing from the + // last (most general) signature is taken from the latest earlier one that has it. + const signatureTypeLines = (signatures.length ? signatures : [page]) + .map(signatureTypes) + .reverse() + for (const name of signatureTypeLines[0]!.parameters.keys()) { + const table = await findPropertiesTable( + outputDir, + signatureTypeLines.flatMap((types) => types.parameters.get(name) ?? []), + ) + if (!table) { + continue + } + const argument = name.replace(/\\/g, '').replace(/\?$/, '') + const key = argument === '__namedParameters' ? 'props' : argument + tables.push({ + id: `${key}-properties`, + title: `\`${key}\` properties`, + table, + parameter: name, + }) + } + const resultTable = await findPropertiesTable( + outputDir, + signatureTypeLines.flatMap((types) => types.returns ?? []), + ) + if (resultTable) { + tables.push({ + id: 'result-properties', + title: 'Result properties', + table: resultTable, + }) + } + + // Property anchors are prefixed with the table's name, so they stay unique when two tables on + // the same page list the same properties. + const section = ( + level: number, + { id, title, table }: (typeof tables)[number], + ) => + `\n\n${'#'.repeat(level)} ${title}\n\n${table.replace( + /<\/a>/g, + ``, + )}` + + if (!isOverloaded) { + // Put each table at the end of the section it describes, so nothing is repeated. + let updated = page.trimEnd() + for (const entry of tables) { + const heading = entry.parameter + ? `\n### ${entry.parameter}\n` + : '\n## Returns\n' + const level = entry.parameter ? 3 : 2 + const start = updated.indexOf(heading) + if (start === -1) { + continue + } + const next = updated + .slice(start + heading.length) + .search(new RegExp(`\\n#{1,${level}} `)) + const insertAt = + next === -1 ? updated.length : start + heading.length + next + updated = `${updated.slice(0, insertAt).trimEnd()}\n\n${section(level + 1, entry)}\n${updated.slice(insertAt)}` + } + await writeFile(pageFile, `${updated.trimEnd()}\n`) + continue + } + + const entries = await Promise.all( + signatures.map(async (signature, index) => { + const code = signature.match(/```ts\n([\s\S]*?)\n```/)?.[1] ?? '' + const summary = signature + .split('\n### ')[0]! + .split('\n\n') + .map((block) => block.trim()) + .find( + (block) => + block !== '' && + !block.startsWith('```') && + !block.startsWith('Defined in:'), + ) + const label = ( + await Promise.all( + [ + code.match(/\((?:\w+\??): ([\s\S]*)/)?.[1], + code.match(/\): ([\s\S]*)/)?.[1], + ].map((type) => type && typeNameInCode(outputDir, type)), + ) + ) + .filter(Boolean) + .map((type) => `\`${type}\``) + .join(' → ') + return { + code, + line: `- [${label || `Call signature ${index + 1}`}](#call-signature-${index + 1})${summary ? `: ${summary.replace(/\n/g, ' ')}` : ''}`, + } + }), + ) + // Repeat the last (most general) signature's `Parameters` and `Returns` once at the end, one + // heading level up, with the property tables, so every argument and the result are listed together. + const promote = (block: string) => block.replace(/^#(#+) /gm, '$1 ') + let parametersSummary = parametersHeading + ? `## Parameters\n\n${promote(parameters.trim())}` + : '' + for (const entry of tables.filter((table) => table.parameter)) { + const heading = `\n### ${entry.parameter}\n` + const start = parametersSummary.indexOf(heading) + const next = parametersSummary + .slice(start + heading.length) + .search(/\n#{1,3} /) + const insertAt = + next === -1 ? parametersSummary.length : start + heading.length + next + parametersSummary = `${parametersSummary.slice(0, insertAt).trimEnd()}\n\n${section(4, entry)}\n${parametersSummary.slice(insertAt)}` + } + const returnsBlock = returnsHeading + ? lastSignature + .slice(returnsHeading.index! + returnsHeading[0].length) + .split(/\n#{2,3} /)[0]! + .trim() + : '' + const resultEntry = tables.find((table) => !table.parameter) + const summaries = [ + parametersSummary + ? `\n\n${parametersSummary.trimEnd()}` + : '', + returnsBlock + ? [ + '', + '', + '## Returns', + '', + returnsBlock, + ...(resultEntry ? ['', section(3, resultEntry)] : []), + ].join('\n') + : '', + ].filter(Boolean) + const links = [ + ...(parametersSummary ? ['[Parameters](#parameters-summary)'] : []), + ...(returnsBlock ? ['[Returns](#returns-summary)'] : []), + ] + const overview = [ + '## Overview', + '', + '```ts', + ...entries.map((entry) => entry.code), + '```', + '', + ...entries.map((entry) => entry.line), + ...(links.length > 0 ? ['', `See also: ${links.join(' · ')}`] : []), + ].join('\n') + const body = signatures + .map( + (signature, index) => + `\n\n\n## Call Signature\n${signature}`, + ) + .join('') + .trimEnd() + const appended = summaries.join('\n\n') + await writeFile( + pageFile, + `${head!.trimEnd()}\n\n${overview}\n${body}${appended ? `\n\n${appended}` : ''}\n`, + ) + } } const packages: Array = [ From d45f683d95827ba3355bef52ea13a0bd7581d725 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Wed, 30 Sep 2026 20:29:27 +0900 Subject: [PATCH 02/12] docs(*): link to the base type's properties when a parameter or result type has no property table --- .../angular/reference/functions/hydrate.md | 6 + .../functions/infiniteQueryOptions.md | 6 + .../functions/injectInfiniteQuery.md | 6 + .../reference/functions/mutationOptions.md | 12 ++ .../reference/functions/queryOptions.md | 6 + .../lit/reference/functions/hydrate.md | 6 + .../functions/infiniteQueryOptions.md | 6 + .../lit/reference/functions/queryOptions.md | 12 ++ .../preact/reference/functions/hydrate.md | 6 + .../functions/infiniteQueryOptions.md | 6 + .../reference/functions/mutationOptions.md | 12 ++ .../reference/functions/queryOptions.md | 6 + .../preact/reference/functions/useMutation.md | 6 + .../reference/functions/usePrefetchQuery.md | 6 + .../functions/useSuspenseInfiniteQuery.md | 6 + .../reference/functions/useSuspenseQuery.md | 6 + .../react/reference/functions/hydrate.md | 6 + .../functions/infiniteQueryOptions.md | 6 + .../reference/functions/mutationOptions.md | 12 ++ .../react/reference/functions/queryOptions.md | 6 + .../react/reference/functions/useMutation.md | 6 + .../reference/functions/usePrefetchQuery.md | 6 + .../functions/useSuspenseInfiniteQuery.md | 6 + .../reference/functions/useSuspenseQuery.md | 6 + .../solid/reference/functions/hydrate.md | 6 + .../functions/infiniteQueryOptions.md | 12 ++ .../reference/functions/mutationOptions.md | 12 ++ .../solid/reference/functions/queryOptions.md | 12 ++ .../reference/functions/useInfiniteQuery.md | 6 + .../reference/functions/useIsFetching.md | 6 + .../reference/functions/useIsMutating.md | 6 + .../solid/reference/functions/useMutation.md | 12 ++ .../solid/reference/functions/useQuery.md | 6 + .../reference/functions/createMutation.md | 12 ++ .../svelte/reference/functions/hydrate.md | 6 + .../functions/infiniteQueryOptions.md | 12 ++ .../reference/functions/mutationOptions.md | 12 ++ .../reference/functions/queryOptions.md | 12 ++ .../vue/reference/functions/hydrate.md | 6 + .../reference/functions/usePrefetchQuery.md | 6 + scripts/generate-docs.ts | 121 ++++++++++++++++++ 41 files changed, 433 insertions(+) diff --git a/docs/framework/angular/reference/functions/hydrate.md b/docs/framework/angular/reference/functions/hydrate.md index e0f723266cc..65d204a296a 100644 --- a/docs/framework/angular/reference/functions/hydrate.md +++ b/docs/framework/angular/reference/functions/hydrate.md @@ -30,6 +30,12 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) diff --git a/docs/framework/angular/reference/functions/infiniteQueryOptions.md b/docs/framework/angular/reference/functions/infiniteQueryOptions.md index 6cd5705cb2b..5e781810da2 100644 --- a/docs/framework/angular/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/angular/reference/functions/infiniteQueryOptions.md @@ -315,6 +315,12 @@ export class Comments { The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `injectInfiniteQuery`. + + +#### `options` properties + +Built from [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptions.md#properties). See the type above for what it changes. + ## Returns diff --git a/docs/framework/angular/reference/functions/injectInfiniteQuery.md b/docs/framework/angular/reference/functions/injectInfiniteQuery.md index fe34782cb8b..c6170378a95 100644 --- a/docs/framework/angular/reference/functions/injectInfiniteQuery.md +++ b/docs/framework/angular/reference/functions/injectInfiniteQuery.md @@ -437,3 +437,9 @@ Additional configuration. [`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> The infinite query result. + + + +### Result properties + +Built from [`BaseQueryNarrowing`](../interfaces/BaseQueryNarrowing.md#properties), [`InfiniteQueryObserverBaseResult`](../interfaces/InfiniteQueryObserverBaseResult.md#properties). See the type above for what it changes. diff --git a/docs/framework/angular/reference/functions/mutationOptions.md b/docs/framework/angular/reference/functions/mutationOptions.md index a3f24c585c5..45ee3ff00f5 100644 --- a/docs/framework/angular/reference/functions/mutationOptions.md +++ b/docs/framework/angular/reference/functions/mutationOptions.md @@ -193,6 +193,12 @@ export class Post { The mutation options to use, identical to what you'd pass to `injectMutation`, without a `mutationKey`. + + +#### `options` properties + +Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes. + ## Returns @@ -200,3 +206,9 @@ The mutation options to use, identical to what you'd pass to `injectMutation`, w `Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> The same options object, unchanged. + + + +### Result properties + +Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/angular/reference/functions/queryOptions.md b/docs/framework/angular/reference/functions/queryOptions.md index a42d4a747c4..101fda4958f 100644 --- a/docs/framework/angular/reference/functions/queryOptions.md +++ b/docs/framework/angular/reference/functions/queryOptions.md @@ -303,6 +303,12 @@ export class Post { The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `injectQuery`. + + +#### `options` properties + +Built from [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md#properties). See the type above for what it changes. + ## Returns diff --git a/docs/framework/lit/reference/functions/hydrate.md b/docs/framework/lit/reference/functions/hydrate.md index 14e109fc5e9..28aef5f8328 100644 --- a/docs/framework/lit/reference/functions/hydrate.md +++ b/docs/framework/lit/reference/functions/hydrate.md @@ -30,6 +30,12 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) diff --git a/docs/framework/lit/reference/functions/infiniteQueryOptions.md b/docs/framework/lit/reference/functions/infiniteQueryOptions.md index e2b5b24ea07..d8df320e21c 100644 --- a/docs/framework/lit/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/lit/reference/functions/infiniteQueryOptions.md @@ -85,6 +85,12 @@ Infinite query options to preserve and brand. The same options object with a typed `queryKey`. + + +### Result properties + +Built from [`InfiniteQueryObserverOptions`](../interfaces/InfiniteQueryObserverOptions.md#properties). See the type above for what it changes. + ## Example ```ts diff --git a/docs/framework/lit/reference/functions/queryOptions.md b/docs/framework/lit/reference/functions/queryOptions.md index f138c125f5d..0175f71d545 100644 --- a/docs/framework/lit/reference/functions/queryOptions.md +++ b/docs/framework/lit/reference/functions/queryOptions.md @@ -174,6 +174,12 @@ The same options object with a typed `queryKey`. Query options to preserve and brand. + + +#### `options` properties + +Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#properties). See the type above for what it changes. + ## Returns @@ -181,3 +187,9 @@ Query options to preserve and brand. [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`, `never`\> & `object` & `object` The same options object with a typed `queryKey`. + + + +### Result properties + +Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/preact/reference/functions/hydrate.md b/docs/framework/preact/reference/functions/hydrate.md index e0f723266cc..65d204a296a 100644 --- a/docs/framework/preact/reference/functions/hydrate.md +++ b/docs/framework/preact/reference/functions/hydrate.md @@ -30,6 +30,12 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md index cd81b8d58a8..d58791e91f4 100644 --- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md @@ -285,6 +285,12 @@ function Comments({ postId }: { postId: string }) { The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + +#### `options` properties + +Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md#properties). See the type above for what it changes. + ## Returns diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md index 0cd586d7ce7..fe69aa228df 100644 --- a/docs/framework/preact/reference/functions/mutationOptions.md +++ b/docs/framework/preact/reference/functions/mutationOptions.md @@ -168,6 +168,12 @@ function CreatePost() { The mutation options to use, identical to what you'd pass to `useMutation`, without a `mutationKey`. + + +#### `options` properties + +Built from [`UseMutationOptions`](../interfaces/UseMutationOptions.md#properties). See the type above for what it changes. + ## Returns @@ -175,3 +181,9 @@ The mutation options to use, identical to what you'd pass to `useMutation`, with `Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> The same options object, unchanged. + + + +### Result properties + +Built from [`UseMutationOptions`](../interfaces/UseMutationOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md index 05bf57843b1..9cd59850c9b 100644 --- a/docs/framework/preact/reference/functions/queryOptions.md +++ b/docs/framework/preact/reference/functions/queryOptions.md @@ -273,6 +273,12 @@ function Post({ postId }: { postId: number | undefined }) { The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. + + +#### `options` properties + +Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties). See the type above for what it changes. + ## Returns diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md index c8d841db68c..2edc6082178 100644 --- a/docs/framework/preact/reference/functions/useMutation.md +++ b/docs/framework/preact/reference/functions/useMutation.md @@ -75,6 +75,12 @@ mutation definition. Hook-level callbacks (passed to `options`) fire for every m fire only for the latest call you've made, and only while the component is still mounted — unmounting before the mutation settles removes the subscription and prevents them from firing. + + +### Result properties + +Built from [`MutationObserverBaseResult`](../interfaces/MutationObserverBaseResult.md#properties). See the type above for what it changes. + ## See [mutationOptions](mutationOptions.md) to share these options across multiple `useMutation` call sites, or to look diff --git a/docs/framework/preact/reference/functions/usePrefetchQuery.md b/docs/framework/preact/reference/functions/usePrefetchQuery.md index 29d83a2f62e..5dec79fbf00 100644 --- a/docs/framework/preact/reference/functions/usePrefetchQuery.md +++ b/docs/framework/preact/reference/functions/usePrefetchQuery.md @@ -48,6 +48,12 @@ already there or already in flight. The [UsePrefetchQueryOptions](../type-aliases/UsePrefetchQueryOptions.md) to use — everything you can pass to `queryClient.query`. + + +#### `options` properties + +Built from [`QueryExecuteOptions`](../interfaces/QueryExecuteOptions.md#properties). See the type above for what it changes. + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md index 7125367e188..0f0cc5dc9de 100644 --- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md +++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md @@ -93,6 +93,12 @@ The same object as `useInfiniteQuery`, except that `data` is guaranteed to be de `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set accordingly). + + +### Result properties + +Built from [`InfiniteQueryObserverBaseResult`](../interfaces/InfiniteQueryObserverBaseResult.md#properties). See the type above for what it changes. + ## Remarks Multiple suspenseful query calls in the same component suspend serially, causing a request diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md index 2c70e2c0d25..b262be8e16c 100644 --- a/docs/framework/preact/reference/functions/useSuspenseQuery.md +++ b/docs/framework/preact/reference/functions/useSuspenseQuery.md @@ -85,6 +85,12 @@ be used. The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set accordingly). + + +### Result properties + +Built from [`QueryObserverBaseResult`](../interfaces/QueryObserverBaseResult.md#properties). See the type above for what it changes. + ## Remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request diff --git a/docs/framework/react/reference/functions/hydrate.md b/docs/framework/react/reference/functions/hydrate.md index e0f723266cc..65d204a296a 100644 --- a/docs/framework/react/reference/functions/hydrate.md +++ b/docs/framework/react/reference/functions/hydrate.md @@ -30,6 +30,12 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) diff --git a/docs/framework/react/reference/functions/infiniteQueryOptions.md b/docs/framework/react/reference/functions/infiniteQueryOptions.md index 628310ce015..c54fd5f2741 100644 --- a/docs/framework/react/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/react/reference/functions/infiniteQueryOptions.md @@ -287,6 +287,12 @@ function Comments({ postId }: { postId: string }) { The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + +#### `options` properties + +Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md#properties). See the type above for what it changes. + ## Returns diff --git a/docs/framework/react/reference/functions/mutationOptions.md b/docs/framework/react/reference/functions/mutationOptions.md index f8e5477c4c0..5f25b4b7604 100644 --- a/docs/framework/react/reference/functions/mutationOptions.md +++ b/docs/framework/react/reference/functions/mutationOptions.md @@ -170,6 +170,12 @@ function CreatePost() { The mutation options to use, identical to what you'd pass to `useMutation`, without a `mutationKey`. + + +#### `options` properties + +Built from [`UseMutationOptions`](../interfaces/UseMutationOptions.md#properties). See the type above for what it changes. + ## Returns @@ -177,3 +183,9 @@ The mutation options to use, identical to what you'd pass to `useMutation`, with `Omit`\<[`UseMutationOptions`](../interfaces/UseMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> The same options object, unchanged. + + + +### Result properties + +Built from [`UseMutationOptions`](../interfaces/UseMutationOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/react/reference/functions/queryOptions.md b/docs/framework/react/reference/functions/queryOptions.md index 16f33e108a9..ea8a43a2e7f 100644 --- a/docs/framework/react/reference/functions/queryOptions.md +++ b/docs/framework/react/reference/functions/queryOptions.md @@ -275,6 +275,12 @@ function Post({ postId }: { postId: number | undefined }) { The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. + + +#### `options` properties + +Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties). See the type above for what it changes. + ## Returns diff --git a/docs/framework/react/reference/functions/useMutation.md b/docs/framework/react/reference/functions/useMutation.md index bbf8cf01111..fd915a3ee5d 100644 --- a/docs/framework/react/reference/functions/useMutation.md +++ b/docs/framework/react/reference/functions/useMutation.md @@ -77,6 +77,12 @@ mutation definition. Hook-level callbacks (passed to `options`) fire for every m fire only for the latest call you've made, and only while the component is still mounted — unmounting before the mutation settles removes the subscription and prevents them from firing. + + +### Result properties + +Built from [`MutationObserverBaseResult`](../interfaces/MutationObserverBaseResult.md#properties). See the type above for what it changes. + ## See [mutationOptions](mutationOptions.md) to share these options across multiple `useMutation` call sites, or to look diff --git a/docs/framework/react/reference/functions/usePrefetchQuery.md b/docs/framework/react/reference/functions/usePrefetchQuery.md index 3e3246310ef..9a23bacd3ff 100644 --- a/docs/framework/react/reference/functions/usePrefetchQuery.md +++ b/docs/framework/react/reference/functions/usePrefetchQuery.md @@ -50,6 +50,12 @@ already there or already in flight. The [UsePrefetchQueryOptions](../type-aliases/UsePrefetchQueryOptions.md) to use — everything you can pass to `queryClient.query`. + + +#### `options` properties + +Built from [`QueryExecuteOptions`](../interfaces/QueryExecuteOptions.md#properties). See the type above for what it changes. + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md index 08f0e617e51..5c4661bd018 100644 --- a/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md +++ b/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md @@ -95,6 +95,12 @@ The same object as `useInfiniteQuery`, except that `data` is guaranteed to be de `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set accordingly). + + +### Result properties + +Built from [`InfiniteQueryObserverBaseResult`](../interfaces/InfiniteQueryObserverBaseResult.md#properties). See the type above for what it changes. + ## Remarks Multiple suspenseful query calls in the same component suspend serially, causing a request diff --git a/docs/framework/react/reference/functions/useSuspenseQuery.md b/docs/framework/react/reference/functions/useSuspenseQuery.md index c8921fbb1da..f78d8871499 100644 --- a/docs/framework/react/reference/functions/useSuspenseQuery.md +++ b/docs/framework/react/reference/functions/useSuspenseQuery.md @@ -87,6 +87,12 @@ be used. The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set accordingly). + + +### Result properties + +Built from [`QueryObserverBaseResult`](../interfaces/QueryObserverBaseResult.md#properties). See the type above for what it changes. + ## Remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request diff --git a/docs/framework/solid/reference/functions/hydrate.md b/docs/framework/solid/reference/functions/hydrate.md index aec6df48f7b..6c746514b09 100644 --- a/docs/framework/solid/reference/functions/hydrate.md +++ b/docs/framework/solid/reference/functions/hydrate.md @@ -30,6 +30,12 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) diff --git a/docs/framework/solid/reference/functions/infiniteQueryOptions.md b/docs/framework/solid/reference/functions/infiniteQueryOptions.md index c843aa34eed..54c3c0394f6 100644 --- a/docs/framework/solid/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/solid/reference/functions/infiniteQueryOptions.md @@ -203,6 +203,12 @@ function Comments(props: { postId: string }) { The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + +#### `options` properties + +Built from [`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md#properties). See the type above for what it changes. + ## Returns @@ -210,3 +216,9 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn [`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/solid/reference/functions/mutationOptions.md b/docs/framework/solid/reference/functions/mutationOptions.md index 5da51027caf..286c0eb992a 100644 --- a/docs/framework/solid/reference/functions/mutationOptions.md +++ b/docs/framework/solid/reference/functions/mutationOptions.md @@ -170,6 +170,12 @@ function CreatePost() { The mutation options to use, identical to what you'd pass to `useMutation`, without a `mutationKey`. + + +#### `options` properties + +Built from [`MutationOptions`](../interfaces/MutationOptions.md#properties). See the type above for what it changes. + ## Returns @@ -177,3 +183,9 @@ The mutation options to use, identical to what you'd pass to `useMutation`, with `Omit`\<[`MutationOptions`](../interfaces/MutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> The same options object, unchanged. + + + +### Result properties + +Built from [`MutationOptions`](../interfaces/MutationOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/solid/reference/functions/queryOptions.md b/docs/framework/solid/reference/functions/queryOptions.md index 412c365cff6..1f97c011846 100644 --- a/docs/framework/solid/reference/functions/queryOptions.md +++ b/docs/framework/solid/reference/functions/queryOptions.md @@ -186,6 +186,12 @@ function Post(props: { id: string }) { The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`. + + +#### `options` properties + +Built from [`QueryOptions`](../interfaces/QueryOptions.md#properties). See the type above for what it changes. + ## Returns @@ -193,3 +199,9 @@ The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md [`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`QueryOptions`](../interfaces/QueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/solid/reference/functions/useInfiniteQuery.md b/docs/framework/solid/reference/functions/useInfiniteQuery.md index 1bd24bd077f..e065df5e6ab 100644 --- a/docs/framework/solid/reference/functions/useInfiniteQuery.md +++ b/docs/framework/solid/reference/functions/useInfiniteQuery.md @@ -285,6 +285,12 @@ function Projects() { An accessor returning the [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `useInfiniteQuery`. + + +#### `options` properties + +Built from [`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md#properties). See the type above for what it changes. + ### queryClient? `Accessor`\<[`QueryClient`](../classes/QueryClient.md)\> diff --git a/docs/framework/solid/reference/functions/useIsFetching.md b/docs/framework/solid/reference/functions/useIsFetching.md index 19a86c4d985..6a0d6d204af 100644 --- a/docs/framework/solid/reference/functions/useIsFetching.md +++ b/docs/framework/solid/reference/functions/useIsFetching.md @@ -22,6 +22,12 @@ in the background (useful for app-wide loading indicators). An accessor returning the [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched queries. + + +#### `filters` properties + +Built from [`QueryFilters`](../interfaces/QueryFilters.md#properties). See the type above for what it changes. + ### queryClient? `Accessor`\<[`QueryClient`](../classes/QueryClient.md)\> diff --git a/docs/framework/solid/reference/functions/useIsMutating.md b/docs/framework/solid/reference/functions/useIsMutating.md index fe04b02534f..390e26b1137 100644 --- a/docs/framework/solid/reference/functions/useIsMutating.md +++ b/docs/framework/solid/reference/functions/useIsMutating.md @@ -22,6 +22,12 @@ The `useIsMutating` primitive returns the `number` of mutations that your applic An accessor returning the [MutationFilters](../interfaces/MutationFilters.md) to narrow down the matched mutations. + + +#### `filters` properties + +Built from [`MutationFilters`](../interfaces/MutationFilters.md#properties). See the type above for what it changes. + ### queryClient? `Accessor`\<[`QueryClient`](../classes/QueryClient.md)\> diff --git a/docs/framework/solid/reference/functions/useMutation.md b/docs/framework/solid/reference/functions/useMutation.md index 2b1eff9cef0..da2105e5f01 100644 --- a/docs/framework/solid/reference/functions/useMutation.md +++ b/docs/framework/solid/reference/functions/useMutation.md @@ -40,6 +40,12 @@ Unlike queries, mutations are typically used to create/update/delete data or per An accessor returning the [UseMutationOptions](../type-aliases/UseMutationOptions.md) to use. + + +#### `options` properties + +Built from [`MutationOptions`](../interfaces/MutationOptions.md#properties). See the type above for what it changes. + ### queryClient? `Accessor`\<[`QueryClient`](../classes/QueryClient.md)\> @@ -57,6 +63,12 @@ mutation definition. Hook-level callbacks (passed to `options`) fire for every m fire only for the latest call you've made, and only while the component is still mounted — unmounting before the mutation settles removes the subscription and prevents them from firing. + + +### Result properties + +Built from [`MutationObserverBaseResult`](../interfaces/MutationObserverBaseResult.md#properties). See the type above for what it changes. + ## Examples ```tsx diff --git a/docs/framework/solid/reference/functions/useQuery.md b/docs/framework/solid/reference/functions/useQuery.md index a16c80d0241..45373e60f7c 100644 --- a/docs/framework/solid/reference/functions/useQuery.md +++ b/docs/framework/solid/reference/functions/useQuery.md @@ -327,6 +327,12 @@ function Posts() { An accessor returning the [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use — everything you can pass to `useQuery`, with `initialData` set. + + +#### `options` properties + +Built from [`QueryOptions`](../interfaces/QueryOptions.md#properties). See the type above for what it changes. + ### queryClient? () => [`QueryClient`](../classes/QueryClient.md) diff --git a/docs/framework/svelte/reference/functions/createMutation.md b/docs/framework/svelte/reference/functions/createMutation.md index c06221075c8..28de135d1ff 100644 --- a/docs/framework/svelte/reference/functions/createMutation.md +++ b/docs/framework/svelte/reference/functions/createMutation.md @@ -39,6 +39,12 @@ Unlike queries, mutations are typically used to create/update/delete data or per The [CreateMutationOptions](../type-aliases/CreateMutationOptions.md) to use, wrapped in an [Accessor](../type-aliases/Accessor.md) so options can be reactive. + + +#### `options` properties + +Built from [`MutationObserverOptions`](../interfaces/MutationObserverOptions.md#properties). See the type above for what it changes. + ### queryClient? [`Accessor`](../type-aliases/Accessor.md)\<[`QueryClient`](../classes/QueryClient.md)\> @@ -55,6 +61,12 @@ argument, useful for triggering call-site side effects (e.g. navigation) without mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've made. + + +### Result properties + +Built from [`MutationObserverBaseResult`](../interfaces/MutationObserverBaseResult.md#properties). See the type above for what it changes. + ## See [mutationOptions](mutationOptions.md) to share these options across multiple `createMutation` call sites, or to look diff --git a/docs/framework/svelte/reference/functions/hydrate.md b/docs/framework/svelte/reference/functions/hydrate.md index e0f723266cc..65d204a296a 100644 --- a/docs/framework/svelte/reference/functions/hydrate.md +++ b/docs/framework/svelte/reference/functions/hydrate.md @@ -30,6 +30,12 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) diff --git a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md index 429d7d50e4a..8bcaa806957 100644 --- a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md @@ -204,6 +204,12 @@ A parameterized factory, so the same options object can be reused per `postId`: The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to `createInfiniteQuery`. + + +#### `options` properties + +Built from [`InfiniteQueryObserverOptions`](../interfaces/InfiniteQueryObserverOptions.md#properties). See the type above for what it changes. + ## Returns @@ -211,3 +217,9 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn [`CreateInfiniteQueryOptions`](../type-aliases/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`InfiniteQueryObserverOptions`](../interfaces/InfiniteQueryObserverOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/svelte/reference/functions/mutationOptions.md b/docs/framework/svelte/reference/functions/mutationOptions.md index 14ae7f1940d..4982bd27ca4 100644 --- a/docs/framework/svelte/reference/functions/mutationOptions.md +++ b/docs/framework/svelte/reference/functions/mutationOptions.md @@ -161,6 +161,12 @@ The same options object. The options to use — everything you can pass to `createMutation`. + + +#### `options` properties + +Built from [`MutationObserverOptions`](../interfaces/MutationObserverOptions.md#properties). See the type above for what it changes. + ## Returns @@ -168,3 +174,9 @@ The options to use — everything you can pass to `createMutation`. `Omit`\<[`CreateMutationOptions`](../type-aliases/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> The same options object. + + + +### Result properties + +Built from [`MutationObserverOptions`](../interfaces/MutationObserverOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/svelte/reference/functions/queryOptions.md b/docs/framework/svelte/reference/functions/queryOptions.md index 8ddcde78fb5..ea20ec435cd 100644 --- a/docs/framework/svelte/reference/functions/queryOptions.md +++ b/docs/framework/svelte/reference/functions/queryOptions.md @@ -183,6 +183,12 @@ A parameterized factory, so the same options object can be reused per `id`: The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `createQuery`. + + +#### `options` properties + +Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#properties). See the type above for what it changes. + ## Returns @@ -190,3 +196,9 @@ The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md [`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/vue/reference/functions/hydrate.md b/docs/framework/vue/reference/functions/hydrate.md index aec6df48f7b..6c746514b09 100644 --- a/docs/framework/vue/reference/functions/hydrate.md +++ b/docs/framework/vue/reference/functions/hydrate.md @@ -30,6 +30,12 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) diff --git a/docs/framework/vue/reference/functions/usePrefetchQuery.md b/docs/framework/vue/reference/functions/usePrefetchQuery.md index 2e58f483d76..b72306f80e3 100644 --- a/docs/framework/vue/reference/functions/usePrefetchQuery.md +++ b/docs/framework/vue/reference/functions/usePrefetchQuery.md @@ -54,6 +54,12 @@ Fire this during render, before a suspense boundary that wraps a component using A `ref`, plain value, or reactive getter resolving to the [UsePrefetchQueryOptions](../type-aliases/UsePrefetchQueryOptions.md) to use — everything you can pass to `queryClient.query`. + + +#### `options` properties + +Built from [`QueryExecuteOptions`](../interfaces/QueryExecuteOptions.md#properties). See the type above for what it changes. + ### queryClient? [`QueryClient`](../classes/QueryClient.md) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index f0809140703..485bfe8d156 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -315,9 +315,130 @@ async function findPropertiesTable( return table } } + const bases = await findBasePages(outputDir, typeLines) + if (bases.length) { + return `Built from ${bases + .map( + (base) => `[\`${base.split('/').at(-1)}\`](../${base}.md#properties)`, + ) + .join(', ')}. See the type above for what it changes.` + } + return undefined +} + +// Splits a type expression at a top-level separator, outside `<>`, `()`, `{}`, and `[]`. +function splitTopLevel(type: string, separator: string) { + const parts: Array = [] + let depth = 0 + let start = 0 + for (let index = 0; index < type.length; index++) { + const char = type[index]! + if ('<({['.includes(char)) { + depth++ + } else if ( + ')}]'.includes(char) || + (char === '>' && type[index - 1] !== '=') + ) { + depth-- + } else if (depth === 0 && type.startsWith(separator, index)) { + parts.push(type.slice(start, index)) + start = index + separator.length + index += separator.length - 1 + } + } + parts.push(type.slice(start)) + return parts.map((part) => part.trim()).filter(Boolean) +} + +async function typePage(outputDir: string, name: string) { + for (const from of [`interfaces/${name}`, `type-aliases/${name}`]) { + if ((await readPage(outputDir, from)) !== undefined) { + return from + } + } return undefined } +// The pages with a `## Properties` table that a type expression without one is built from: every +// member of an intersection (skipping object literals, which only add properties), and the first type +// argument of a utility that isn't built from one itself, like `Omit<…>`. Returns nothing unless every part is found. +async function basePagesOfType( + outputDir: string, + type: string, + seen: Set, +): Promise> { + const expression = splitTopLevel(type, ' = ')[0]! + .replace(/^[|&]\s*/, '') + .replace(/^\(\) => /, '') + .trim() + const members = splitTopLevel(expression, ' & ').filter( + (member) => member !== 'object' && !member.startsWith('{'), + ) + if (members.length > 1) { + const pages: Array = [] + for (const member of members) { + const memberPages = await basePagesOfType(outputDir, member, seen) + if (!memberPages.length) { + return [] + } + pages.push(...memberPages) + } + return [...new Set(pages)] + } + const reference = members[0]?.match(/^(\w+)(?:<([\s\S]*)>)?$/) + if (!reference) { + return [] + } + const [, name, typeArguments] = reference + const [firstTypeArgument] = typeArguments + ? splitTopLevel(typeArguments, ',') + : [] + const page = await typePage(outputDir, name!) + const pages = + page && !(await isWrapperAlias(outputDir, page)) + ? await basePages(outputDir, page, seen) + : [] + if (pages.length) { + return pages + } + return firstTypeArgument + ? basePagesOfType(outputDir, firstTypeArgument, seen) + : [] +} + +async function basePages( + outputDir: string, + from: string, + seen: Set, +): Promise> { + if (seen.has(from)) { + return [] + } + seen.add(from) + const page = await propertiesPage(outputDir, from) + if (page) { + return [page] + } + const code = (await readPage(outputDir, from))?.match( + /```ts\ntype \w+(?:<[^\n=]*>)? = ([\s\S]*?);\n```/, + )?.[1] + return code ? basePagesOfType(outputDir, code, seen) : [] +} + +// The base pages of the first type line that has any. +async function findBasePages(outputDir: string, typeLines: Array) { + for (const typeLine of typeLines) { + const type = typeLine + .replace(/\[`?(\w+)`?\]\([^)]*\)/g, '$1') + .replace(/[\\`]/g, '') + const pages = await basePagesOfType(outputDir, type, new Set()) + if (pages.length) { + return pages + } + } + return [] +} + // The type line of each parameter and of the return value in one call signature. function signatureTypes(signature: string) { const parametersHeading = signature.match(/\n#{2,3} Parameters\n/) From 3b3c28017784e972f10e0babb80a09f94b10acbe Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Mon, 5 Oct 2026 04:10:33 +0900 Subject: [PATCH 03/12] docs(framework/*/reference): regenerate reference docs --- .../angular/reference/functions/dehydrate.md | 17 +++++++---- .../angular/reference/functions/hydrate.md | 9 +++++- .../functions/infiniteQueryOptions.md | 30 +++++++++---------- .../reference/functions/matchMutation.md | 8 ++++- .../angular/reference/functions/matchQuery.md | 8 ++++- .../reference/functions/queryFeature.md | 8 ++--- .../lit/reference/functions/dehydrate.md | 17 +++++++---- .../lit/reference/functions/hydrate.md | 9 +++++- .../lit/reference/functions/matchMutation.md | 8 ++++- .../lit/reference/functions/matchQuery.md | 8 ++++- .../reference/functions/HydrationBoundary.md | 9 ++++-- .../functions/QueryClientProvider.md | 8 +++-- .../functions/QueryErrorResetBoundary.md | 8 +++-- .../preact/reference/functions/dehydrate.md | 17 +++++++---- .../preact/reference/functions/hydrate.md | 9 +++++- .../functions/infiniteQueryOptions.md | 30 +++++++++---------- .../reference/functions/matchMutation.md | 8 ++++- .../preact/reference/functions/matchQuery.md | 8 ++++- .../preact/reference/functions/useMutation.md | 7 ++++- .../preact/reference/functions/useQuery.md | 4 +-- .../reference/functions/HydrationBoundary.md | 9 ++++-- .../functions/QueryClientProvider.md | 8 +++-- .../functions/QueryErrorResetBoundary.md | 8 +++-- .../react/reference/functions/dehydrate.md | 17 +++++++---- .../react/reference/functions/hydrate.md | 9 +++++- .../functions/infiniteQueryOptions.md | 30 +++++++++---------- .../reference/functions/matchMutation.md | 8 ++++- .../react/reference/functions/matchQuery.md | 8 ++++- .../react/reference/functions/useMutation.md | 7 ++++- .../react/reference/functions/useQuery.md | 4 +-- .../functions/QueryClientProvider.md | 4 ++- .../solid/reference/functions/dehydrate.md | 17 +++++++---- .../solid/reference/functions/hydrate.md | 9 +++++- .../reference/functions/matchMutation.md | 8 ++++- .../solid/reference/functions/matchQuery.md | 8 ++++- .../svelte/reference/functions/createQuery.md | 2 +- .../svelte/reference/functions/dehydrate.md | 17 +++++++---- .../svelte/reference/functions/hydrate.md | 9 +++++- .../reference/functions/matchMutation.md | 8 ++++- .../svelte/reference/functions/matchQuery.md | 8 ++++- .../reference/functions/useMutationState.md | 8 ++--- .../vue/reference/functions/dehydrate.md | 17 +++++++---- .../vue/reference/functions/hydrate.md | 9 +++++- .../vue/reference/functions/matchMutation.md | 8 ++++- .../vue/reference/functions/matchQuery.md | 8 ++++- 45 files changed, 343 insertions(+), 135 deletions(-) diff --git a/docs/framework/angular/reference/functions/dehydrate.md b/docs/framework/angular/reference/functions/dehydrate.md index 2c4abfc7754..e01b3cf74ef 100644 --- a/docs/framework/angular/reference/functions/dehydrate.md +++ b/docs/framework/angular/reference/functions/dehydrate.md @@ -7,7 +7,7 @@ title: dehydrate function dehydrate(client: QueryClient, options: DehydrateOptions): DehydratedState; ``` -Defined in: [packages/query-core/src/hydration.ts:208](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L208) +Defined in: [packages/query-core/src/hydration.ts:245](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L245) Dehydrates a `QueryClient`'s cache (queries and mutations) into a plain, serializable `DehydratedState`, typically to embed in server-rendered markup and later restore into a client-side `QueryClient` via `hydrate`. @@ -21,10 +21,15 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`QueryClient`](../classes/QueryClient.md) +The client whose cache is dehydrated. + ### options [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` +Controls which queries and mutations are included and how their data and errors +are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. + #### `options` properties @@ -40,14 +45,16 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydratedState`](../interfaces/DehydratedState.md) +The dehydrated state, with the included `queries` and `mutations`. + ### Result properties -| Property | Type | -| ------ | ------ | -| `mutations` | `DehydratedMutation`[] | -| `queries` | `DehydratedQuery`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/angular/reference/functions/hydrate.md b/docs/framework/angular/reference/functions/hydrate.md index 65d204a296a..e160e90a332 100644 --- a/docs/framework/angular/reference/functions/hydrate.md +++ b/docs/framework/angular/reference/functions/hydrate.md @@ -10,7 +10,7 @@ function hydrate( options?: HydrateOptions): void; ``` -Defined in: [packages/query-core/src/hydration.ts:265](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L265) +Defined in: [packages/query-core/src/hydration.ts:306](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L306) Restores a `DehydratedState` (as produced by `dehydrate`) into a `QueryClient`'s cache, typically to seed the client with data already fetched on the server. `mutations` and `queries` are each optional on `dehydratedState`. @@ -26,10 +26,14 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`QueryClient`](../classes/QueryClient.md) +The client whose cache is restored into. + ### dehydratedState `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> +The dehydrated state, e.g. produced by `dehydrate` on the server. + #### `dehydratedState` properties @@ -40,6 +44,9 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See [`HydrateOptions`](../interfaces/HydrateOptions.md) +`defaultOptions` merged into every restored query and mutation (on top of the +client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + #### `options` properties diff --git a/docs/framework/angular/reference/functions/infiniteQueryOptions.md b/docs/framework/angular/reference/functions/infiniteQueryOptions.md index 5e781810da2..99b9c2a64fb 100644 --- a/docs/framework/angular/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/angular/reference/functions/infiniteQueryOptions.md @@ -25,7 +25,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:181](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L181) +Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:176](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L176) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as @@ -69,15 +69,15 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini The same options object, typed so that `queryKey` carries the inferred data type. -### See - -[injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. - ### Remarks See [injectInfiniteQuery](injectInfiniteQuery.md) for examples that fetch further pages, from a button click or automatically as the user scrolls. +### See + +[injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. + ### Example ```angular-ts @@ -118,7 +118,7 @@ export class Projects { function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:255](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L255) +Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:247](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L247) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as @@ -165,6 +165,10 @@ The same options object, typed so that `queryKey` carries the inferred data type See [injectInfiniteQuery](injectInfiniteQuery.md) for examples that fetch further pages, from a button click or automatically as the user scrolls. +### See + +[injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. + ### Example A parameterized factory, so the same options object can be reused per `postId`: @@ -203,10 +207,6 @@ export class Comments { } ``` -### See - -[injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. - ## Call Signature @@ -215,7 +215,7 @@ export class Comments { function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:329](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L329) +Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:318](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L318) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as @@ -262,6 +262,10 @@ The same options object, typed so that `queryKey` carries the inferred data type See [injectInfiniteQuery](injectInfiniteQuery.md) for examples that fetch further pages (from a button click or automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set. +### See + +[injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. + ### Example A parameterized factory, so the same options object can be reused per `postId`: @@ -300,10 +304,6 @@ export class Comments { } ``` -### See - -[injectInfiniteQuery](injectInfiniteQuery.md) to run an infinite query with these options. - ## Parameters diff --git a/docs/framework/angular/reference/functions/matchMutation.md b/docs/framework/angular/reference/functions/matchMutation.md index 7903e79a6b6..b12d3b9565c 100644 --- a/docs/framework/angular/reference/functions/matchMutation.md +++ b/docs/framework/angular/reference/functions/matchMutation.md @@ -7,7 +7,7 @@ title: matchMutation function matchMutation(filters: MutationFilters, mutation: Mutation): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:237](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L237) +Defined in: [packages/query-core/src/utils.ts:269](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L269) Checks whether a mutation matches the given [MutationFilters](../interfaces/MutationFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -19,6 +19,8 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) +The filters to check the mutation against. + #### `filters` properties @@ -34,10 +36,14 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> +The mutation to check. + ## Returns `boolean` +`true` if the mutation matches every specified filter. + ## Example ```ts diff --git a/docs/framework/angular/reference/functions/matchQuery.md b/docs/framework/angular/reference/functions/matchQuery.md index 961ff43c3d1..e1cdd4ee789 100644 --- a/docs/framework/angular/reference/functions/matchQuery.md +++ b/docs/framework/angular/reference/functions/matchQuery.md @@ -7,7 +7,7 @@ title: matchQuery function matchQuery(filters: QueryFilters, query: Query): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:175](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L175) +Defined in: [packages/query-core/src/utils.ts:205](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L205) Checks whether a query matches the given [QueryFilters](../interfaces/QueryFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -18,6 +18,8 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) +The filters to check the query against. + #### `filters` properties @@ -35,10 +37,14 @@ Every filter that is specified must match; filters that are left unspecified are [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> +The query to check. + ## Returns `boolean` +`true` if the query matches every specified filter. + ## Example ```ts diff --git a/docs/framework/angular/reference/functions/queryFeature.md b/docs/framework/angular/reference/functions/queryFeature.md index f43652084f2..ea8a90c9aae 100644 --- a/docs/framework/angular/reference/functions/queryFeature.md +++ b/docs/framework/angular/reference/functions/queryFeature.md @@ -41,7 +41,7 @@ A Query feature. ### Result properties -| Property | Type | -| ------ | ------ | -| `ɵkind` | `TFeatureKind` | -| `ɵproviders` | `Provider`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `ɵkind` | `TFeatureKind` | The kind of the feature, e.g. `'Devtools'` or `'PersistQueryClient'`. | +| `ɵproviders` | `Provider`[] | The providers that `provideTanStackQuery` registers for the feature. | diff --git a/docs/framework/lit/reference/functions/dehydrate.md b/docs/framework/lit/reference/functions/dehydrate.md index 2c4abfc7754..e01b3cf74ef 100644 --- a/docs/framework/lit/reference/functions/dehydrate.md +++ b/docs/framework/lit/reference/functions/dehydrate.md @@ -7,7 +7,7 @@ title: dehydrate function dehydrate(client: QueryClient, options: DehydrateOptions): DehydratedState; ``` -Defined in: [packages/query-core/src/hydration.ts:208](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L208) +Defined in: [packages/query-core/src/hydration.ts:245](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L245) Dehydrates a `QueryClient`'s cache (queries and mutations) into a plain, serializable `DehydratedState`, typically to embed in server-rendered markup and later restore into a client-side `QueryClient` via `hydrate`. @@ -21,10 +21,15 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`QueryClient`](../classes/QueryClient.md) +The client whose cache is dehydrated. + ### options [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` +Controls which queries and mutations are included and how their data and errors +are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. + #### `options` properties @@ -40,14 +45,16 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydratedState`](../interfaces/DehydratedState.md) +The dehydrated state, with the included `queries` and `mutations`. + ### Result properties -| Property | Type | -| ------ | ------ | -| `mutations` | `DehydratedMutation`[] | -| `queries` | `DehydratedQuery`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/lit/reference/functions/hydrate.md b/docs/framework/lit/reference/functions/hydrate.md index 28aef5f8328..9772d216cee 100644 --- a/docs/framework/lit/reference/functions/hydrate.md +++ b/docs/framework/lit/reference/functions/hydrate.md @@ -10,7 +10,7 @@ function hydrate( options?: HydrateOptions): void; ``` -Defined in: [packages/query-core/src/hydration.ts:265](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L265) +Defined in: [packages/query-core/src/hydration.ts:306](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L306) Restores a `DehydratedState` (as produced by `dehydrate`) into a `QueryClient`'s cache, typically to seed the client with data already fetched on the server. `mutations` and `queries` are each optional on `dehydratedState`. @@ -26,10 +26,14 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`QueryClient`](../classes/QueryClient.md) +The client whose cache is restored into. + ### dehydratedState `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> +The dehydrated state, e.g. produced by `dehydrate` on the server. + #### `dehydratedState` properties @@ -40,6 +44,9 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See [`HydrateOptions`](../interfaces/HydrateOptions.md) +`defaultOptions` merged into every restored query and mutation (on top of the +client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + #### `options` properties diff --git a/docs/framework/lit/reference/functions/matchMutation.md b/docs/framework/lit/reference/functions/matchMutation.md index 7903e79a6b6..b12d3b9565c 100644 --- a/docs/framework/lit/reference/functions/matchMutation.md +++ b/docs/framework/lit/reference/functions/matchMutation.md @@ -7,7 +7,7 @@ title: matchMutation function matchMutation(filters: MutationFilters, mutation: Mutation): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:237](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L237) +Defined in: [packages/query-core/src/utils.ts:269](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L269) Checks whether a mutation matches the given [MutationFilters](../interfaces/MutationFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -19,6 +19,8 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) +The filters to check the mutation against. + #### `filters` properties @@ -34,10 +36,14 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> +The mutation to check. + ## Returns `boolean` +`true` if the mutation matches every specified filter. + ## Example ```ts diff --git a/docs/framework/lit/reference/functions/matchQuery.md b/docs/framework/lit/reference/functions/matchQuery.md index 961ff43c3d1..e1cdd4ee789 100644 --- a/docs/framework/lit/reference/functions/matchQuery.md +++ b/docs/framework/lit/reference/functions/matchQuery.md @@ -7,7 +7,7 @@ title: matchQuery function matchQuery(filters: QueryFilters, query: Query): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:175](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L175) +Defined in: [packages/query-core/src/utils.ts:205](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L205) Checks whether a query matches the given [QueryFilters](../interfaces/QueryFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -18,6 +18,8 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) +The filters to check the query against. + #### `filters` properties @@ -35,10 +37,14 @@ Every filter that is specified must match; filters that are left unspecified are [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> +The query to check. + ## Returns `boolean` +`true` if the query matches every specified filter. + ## Example ```ts diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md index 97d22becfe7..4de7af659ad 100644 --- a/docs/framework/preact/reference/functions/HydrationBoundary.md +++ b/docs/framework/preact/reference/functions/HydrationBoundary.md @@ -4,10 +4,10 @@ title: HydrationBoundary --- ```ts -function HydrationBoundary(__namedParameters: HydrationBoundaryProps): Element; +function HydrationBoundary(props: HydrationBoundaryProps): Element; ``` -Defined in: [packages/preact-query/src/HydrationBoundary.tsx:87](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L87) +Defined in: [packages/preact-query/src/HydrationBoundary.tsx:86](https://github.com/TanStack/query/blob/main/packages/preact-query/src/HydrationBoundary.tsx#L86) `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on @@ -17,10 +17,13 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`. ## Parameters -### \_\_namedParameters +### props [`HydrationBoundaryProps`](../interfaces/HydrationBoundaryProps.md) +The dehydrated `state` to hydrate, the hydrate `options`, an optional custom +`queryClient`, and the `children` to render. + #### `props` properties diff --git a/docs/framework/preact/reference/functions/QueryClientProvider.md b/docs/framework/preact/reference/functions/QueryClientProvider.md index ed408e1a827..eb0f56ff2fd 100644 --- a/docs/framework/preact/reference/functions/QueryClientProvider.md +++ b/docs/framework/preact/reference/functions/QueryClientProvider.md @@ -4,10 +4,10 @@ title: QueryClientProvider --- ```ts -function QueryClientProvider(__namedParameters: QueryClientProviderProps): VNode; +function QueryClientProvider(props: QueryClientProviderProps): VNode; ``` -Defined in: [packages/preact-query/src/QueryClientProvider.tsx:70](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L70) +Defined in: [packages/preact-query/src/QueryClientProvider.tsx:69](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryClientProvider.tsx#L69) Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application. Also calls `client.mount()`/`client.unmount()` as this component mounts/unmounts, which subscribes the client to @@ -16,10 +16,12 @@ comes back online). ## Parameters -### \_\_namedParameters +### props [`QueryClientProviderProps`](../type-aliases/QueryClientProviderProps.md) +The `client` to provide, and the `children` that get access to it. + #### `props` properties diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md index a9d73f276b8..6531ae5d962 100644 --- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md +++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md @@ -4,10 +4,10 @@ title: QueryErrorResetBoundary --- ```ts -function QueryErrorResetBoundary(__namedParameters: QueryErrorResetBoundaryProps): Element; +function QueryErrorResetBoundary(props: QueryErrorResetBoundaryProps): Element; ``` -Defined in: [packages/preact-query/src/QueryErrorResetBoundary.tsx:159](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L159) +Defined in: [packages/preact-query/src/QueryErrorResetBoundary.tsx:164](https://github.com/TanStack/query/blob/main/packages/preact-query/src/QueryErrorResetBoundary.tsx#L164) When using `suspense` or `throwOnError` in your queries, you need a way to let queries know that you want to try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can @@ -15,10 +15,12 @@ reset any query errors within the boundaries of the component. ## Parameters -### \_\_namedParameters +### props [`QueryErrorResetBoundaryProps`](../interfaces/QueryErrorResetBoundaryProps.md) +The `children` to render. + #### `props` properties diff --git a/docs/framework/preact/reference/functions/dehydrate.md b/docs/framework/preact/reference/functions/dehydrate.md index 2c4abfc7754..e01b3cf74ef 100644 --- a/docs/framework/preact/reference/functions/dehydrate.md +++ b/docs/framework/preact/reference/functions/dehydrate.md @@ -7,7 +7,7 @@ title: dehydrate function dehydrate(client: QueryClient, options: DehydrateOptions): DehydratedState; ``` -Defined in: [packages/query-core/src/hydration.ts:208](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L208) +Defined in: [packages/query-core/src/hydration.ts:245](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L245) Dehydrates a `QueryClient`'s cache (queries and mutations) into a plain, serializable `DehydratedState`, typically to embed in server-rendered markup and later restore into a client-side `QueryClient` via `hydrate`. @@ -21,10 +21,15 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`QueryClient`](../classes/QueryClient.md) +The client whose cache is dehydrated. + ### options [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` +Controls which queries and mutations are included and how their data and errors +are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. + #### `options` properties @@ -40,14 +45,16 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydratedState`](../interfaces/DehydratedState.md) +The dehydrated state, with the included `queries` and `mutations`. + ### Result properties -| Property | Type | -| ------ | ------ | -| `mutations` | `DehydratedMutation`[] | -| `queries` | `DehydratedQuery`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/preact/reference/functions/hydrate.md b/docs/framework/preact/reference/functions/hydrate.md index 65d204a296a..e160e90a332 100644 --- a/docs/framework/preact/reference/functions/hydrate.md +++ b/docs/framework/preact/reference/functions/hydrate.md @@ -10,7 +10,7 @@ function hydrate( options?: HydrateOptions): void; ``` -Defined in: [packages/query-core/src/hydration.ts:265](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L265) +Defined in: [packages/query-core/src/hydration.ts:306](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L306) Restores a `DehydratedState` (as produced by `dehydrate`) into a `QueryClient`'s cache, typically to seed the client with data already fetched on the server. `mutations` and `queries` are each optional on `dehydratedState`. @@ -26,10 +26,14 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`QueryClient`](../classes/QueryClient.md) +The client whose cache is restored into. + ### dehydratedState `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> +The dehydrated state, e.g. produced by `dehydrate` on the server. + #### `dehydratedState` properties @@ -40,6 +44,9 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See [`HydrateOptions`](../interfaces/HydrateOptions.md) +`defaultOptions` merged into every restored query and mutation (on top of the +client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + #### `options` properties diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md index d58791e91f4..d52d022d642 100644 --- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md @@ -25,7 +25,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:171](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L171) +Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:166](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L166) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. @@ -67,15 +67,15 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini The same options object, typed so that `queryKey` carries the inferred data type. -### See - -[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. - ### Remarks See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or automatically as the user scrolls. +### See + +[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + ### Example ```tsx @@ -113,7 +113,7 @@ function Projects() { function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:233](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L233) +Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:225](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L225) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. @@ -158,6 +158,10 @@ The same options object, typed so that `queryKey` carries the inferred data type See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or automatically as the user scrolls. +### See + +[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + ### Example A parameterized factory, so the same options object can be reused per `postId`: @@ -186,10 +190,6 @@ function Comments({ postId }: { postId: string }) { } ``` -### See - -[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. - ## Call Signature @@ -198,7 +198,7 @@ function Comments({ postId }: { postId: string }) { function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:295](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L295) +Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:284](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L284) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. @@ -243,6 +243,10 @@ The same options object, typed so that `queryKey` carries the inferred data type See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages (from a button click or automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set. +### See + +[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + ### Example A parameterized factory, so the same options object can be reused per `postId`: @@ -271,10 +275,6 @@ function Comments({ postId }: { postId: string }) { } ``` -### See - -[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. - ## Parameters diff --git a/docs/framework/preact/reference/functions/matchMutation.md b/docs/framework/preact/reference/functions/matchMutation.md index 7903e79a6b6..b12d3b9565c 100644 --- a/docs/framework/preact/reference/functions/matchMutation.md +++ b/docs/framework/preact/reference/functions/matchMutation.md @@ -7,7 +7,7 @@ title: matchMutation function matchMutation(filters: MutationFilters, mutation: Mutation): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:237](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L237) +Defined in: [packages/query-core/src/utils.ts:269](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L269) Checks whether a mutation matches the given [MutationFilters](../interfaces/MutationFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -19,6 +19,8 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) +The filters to check the mutation against. + #### `filters` properties @@ -34,10 +36,14 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> +The mutation to check. + ## Returns `boolean` +`true` if the mutation matches every specified filter. + ## Example ```ts diff --git a/docs/framework/preact/reference/functions/matchQuery.md b/docs/framework/preact/reference/functions/matchQuery.md index 961ff43c3d1..e1cdd4ee789 100644 --- a/docs/framework/preact/reference/functions/matchQuery.md +++ b/docs/framework/preact/reference/functions/matchQuery.md @@ -7,7 +7,7 @@ title: matchQuery function matchQuery(filters: QueryFilters, query: Query): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:175](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L175) +Defined in: [packages/query-core/src/utils.ts:205](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L205) Checks whether a query matches the given [QueryFilters](../interfaces/QueryFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -18,6 +18,8 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) +The filters to check the query against. + #### `filters` properties @@ -35,10 +37,14 @@ Every filter that is specified must match; filters that are left unspecified are [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> +The query to check. + ## Returns `boolean` +`true` if the query matches every specified filter. + ## Example ```ts diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md index 2edc6082178..2fb4df9d71b 100644 --- a/docs/framework/preact/reference/functions/useMutation.md +++ b/docs/framework/preact/reference/functions/useMutation.md @@ -7,7 +7,7 @@ title: useMutation function useMutation(options: UseMutationOptions, queryClient?: QueryClient): UseMutationResult; ``` -Defined in: [packages/preact-query/src/useMutation.ts:192](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L192) +Defined in: [packages/preact-query/src/useMutation.ts:188](https://github.com/TanStack/query/blob/main/packages/preact-query/src/useMutation.ts#L188) Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. `useMutation` is the hook for that. @@ -81,6 +81,11 @@ the mutation settles removes the subscription and prevents them from firing. Built from [`MutationObserverBaseResult`](../interfaces/MutationObserverBaseResult.md#properties). See the type above for what it changes. +## Throws + +The mutation error, when `throwOnError` is `true` or returns `true` for it, so that it is +thrown to the nearest error boundary. + ## See [mutationOptions](mutationOptions.md) to share these options across multiple `useMutation` call sites, or to look diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md index fc1f312014e..5635ee7c5a4 100644 --- a/docs/framework/preact/reference/functions/useQuery.md +++ b/docs/framework/preact/reference/functions/useQuery.md @@ -12,8 +12,8 @@ function useQuery(options: UseQueryOptio ``` - [`DefinedInitialDataOptions` → `DefinedUseQueryResult`](#call-signature-1): This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). -- [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-2) -- [`UseQueryOptions` → `UseQueryResult`](#call-signature-3) +- [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-2): This overload is selected when `initialData` is omitted or may be `undefined`, so the resulting `data` can be `undefined`. +- [`UseQueryOptions` → `UseQueryResult`](#call-signature-3): Fallback overload for options whose `initialData` presence isn't statically known — for example, an object typed as [UseQueryOptions](../interfaces/UseQueryOptions.md) rather than an object literal. Prefer one of the other overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/react/reference/functions/HydrationBoundary.md b/docs/framework/react/reference/functions/HydrationBoundary.md index ccd5902c324..d34306f72db 100644 --- a/docs/framework/react/reference/functions/HydrationBoundary.md +++ b/docs/framework/react/reference/functions/HydrationBoundary.md @@ -4,10 +4,10 @@ title: HydrationBoundary --- ```ts -function HydrationBoundary(__namedParameters: HydrationBoundaryProps): ReactElement>; +function HydrationBoundary(props: HydrationBoundaryProps): ReactElement>; ``` -Defined in: [packages/react-query/src/HydrationBoundary.tsx:86](https://github.com/TanStack/query/blob/main/packages/react-query/src/HydrationBoundary.tsx#L86) +Defined in: [packages/react-query/src/HydrationBoundary.tsx:85](https://github.com/TanStack/query/blob/main/packages/react-query/src/HydrationBoundary.tsx#L85) `HydrationBoundary` adds a previously dehydrated state into the `queryClient` that would be returned by `useQueryClient()`. If the client already contains data, the new queries will be intelligently merged based on @@ -17,10 +17,13 @@ Note: Only `queries` can be dehydrated with an `HydrationBoundary`. ## Parameters -### \_\_namedParameters +### props [`HydrationBoundaryProps`](../interfaces/HydrationBoundaryProps.md) +The dehydrated `state` to hydrate, the hydrate `options`, an optional custom +`queryClient`, and the `children` to render. + #### `props` properties diff --git a/docs/framework/react/reference/functions/QueryClientProvider.md b/docs/framework/react/reference/functions/QueryClientProvider.md index aef10f67bee..5b0778b6b1c 100644 --- a/docs/framework/react/reference/functions/QueryClientProvider.md +++ b/docs/framework/react/reference/functions/QueryClientProvider.md @@ -6,10 +6,10 @@ redirect_from: --- ```ts -function QueryClientProvider(__namedParameters: QueryClientProviderProps): Element; +function QueryClientProvider(props: QueryClientProviderProps): Element; ``` -Defined in: [packages/react-query/src/QueryClientProvider.tsx:70](https://github.com/TanStack/query/blob/main/packages/react-query/src/QueryClientProvider.tsx#L70) +Defined in: [packages/react-query/src/QueryClientProvider.tsx:69](https://github.com/TanStack/query/blob/main/packages/react-query/src/QueryClientProvider.tsx#L69) Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application. Also calls `client.mount()`/`client.unmount()` as this component mounts/unmounts, which subscribes the client to @@ -18,10 +18,12 @@ comes back online). ## Parameters -### \_\_namedParameters +### props [`QueryClientProviderProps`](../type-aliases/QueryClientProviderProps.md) +The `client` to provide, and the `children` that get access to it. + #### `props` properties diff --git a/docs/framework/react/reference/functions/QueryErrorResetBoundary.md b/docs/framework/react/reference/functions/QueryErrorResetBoundary.md index 701b7a6b02b..1283aeba32e 100644 --- a/docs/framework/react/reference/functions/QueryErrorResetBoundary.md +++ b/docs/framework/react/reference/functions/QueryErrorResetBoundary.md @@ -6,10 +6,10 @@ redirect_from: --- ```ts -function QueryErrorResetBoundary(__namedParameters: QueryErrorResetBoundaryProps): Element; +function QueryErrorResetBoundary(props: QueryErrorResetBoundaryProps): Element; ``` -Defined in: [packages/react-query/src/QueryErrorResetBoundary.tsx:136](https://github.com/TanStack/query/blob/main/packages/react-query/src/QueryErrorResetBoundary.tsx#L136) +Defined in: [packages/react-query/src/QueryErrorResetBoundary.tsx:160](https://github.com/TanStack/query/blob/main/packages/react-query/src/QueryErrorResetBoundary.tsx#L160) When using `suspense` or `throwOnError` in your queries, you need a way to let queries know that you want to try again when re-rendering after some error occurred. With the `QueryErrorResetBoundary` component you can @@ -17,10 +17,12 @@ reset any query errors within the boundaries of the component. ## Parameters -### \_\_namedParameters +### props [`QueryErrorResetBoundaryProps`](../interfaces/QueryErrorResetBoundaryProps.md) +The `children` to render. + #### `props` properties diff --git a/docs/framework/react/reference/functions/dehydrate.md b/docs/framework/react/reference/functions/dehydrate.md index 2c4abfc7754..e01b3cf74ef 100644 --- a/docs/framework/react/reference/functions/dehydrate.md +++ b/docs/framework/react/reference/functions/dehydrate.md @@ -7,7 +7,7 @@ title: dehydrate function dehydrate(client: QueryClient, options: DehydrateOptions): DehydratedState; ``` -Defined in: [packages/query-core/src/hydration.ts:208](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L208) +Defined in: [packages/query-core/src/hydration.ts:245](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L245) Dehydrates a `QueryClient`'s cache (queries and mutations) into a plain, serializable `DehydratedState`, typically to embed in server-rendered markup and later restore into a client-side `QueryClient` via `hydrate`. @@ -21,10 +21,15 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`QueryClient`](../classes/QueryClient.md) +The client whose cache is dehydrated. + ### options [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` +Controls which queries and mutations are included and how their data and errors +are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. + #### `options` properties @@ -40,14 +45,16 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydratedState`](../interfaces/DehydratedState.md) +The dehydrated state, with the included `queries` and `mutations`. + ### Result properties -| Property | Type | -| ------ | ------ | -| `mutations` | `DehydratedMutation`[] | -| `queries` | `DehydratedQuery`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/react/reference/functions/hydrate.md b/docs/framework/react/reference/functions/hydrate.md index 65d204a296a..e160e90a332 100644 --- a/docs/framework/react/reference/functions/hydrate.md +++ b/docs/framework/react/reference/functions/hydrate.md @@ -10,7 +10,7 @@ function hydrate( options?: HydrateOptions): void; ``` -Defined in: [packages/query-core/src/hydration.ts:265](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L265) +Defined in: [packages/query-core/src/hydration.ts:306](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L306) Restores a `DehydratedState` (as produced by `dehydrate`) into a `QueryClient`'s cache, typically to seed the client with data already fetched on the server. `mutations` and `queries` are each optional on `dehydratedState`. @@ -26,10 +26,14 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`QueryClient`](../classes/QueryClient.md) +The client whose cache is restored into. + ### dehydratedState `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> +The dehydrated state, e.g. produced by `dehydrate` on the server. + #### `dehydratedState` properties @@ -40,6 +44,9 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See [`HydrateOptions`](../interfaces/HydrateOptions.md) +`defaultOptions` merged into every restored query and mutation (on top of the +client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + #### `options` properties diff --git a/docs/framework/react/reference/functions/infiniteQueryOptions.md b/docs/framework/react/reference/functions/infiniteQueryOptions.md index c54fd5f2741..4fe2117edfc 100644 --- a/docs/framework/react/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/react/reference/functions/infiniteQueryOptions.md @@ -27,7 +27,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/react-query/src/infiniteQueryOptions.ts:170](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L170) +Defined in: [packages/react-query/src/infiniteQueryOptions.ts:165](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L165) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. @@ -69,15 +69,15 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini The same options object, typed so that `queryKey` carries the inferred data type. -### See - -[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. - ### Remarks See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or automatically as the user scrolls. +### See + +[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + ### Example ```tsx @@ -115,7 +115,7 @@ function Projects() { function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/react-query/src/infiniteQueryOptions.ts:232](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L232) +Defined in: [packages/react-query/src/infiniteQueryOptions.ts:224](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L224) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. @@ -160,6 +160,10 @@ The same options object, typed so that `queryKey` carries the inferred data type See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages, from a button click or automatically as the user scrolls. +### See + +[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + ### Example A parameterized factory, so the same options object can be reused per `postId`: @@ -188,10 +192,6 @@ function Comments({ postId }: { postId: string }) { } ``` -### See - -[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. - ## Call Signature @@ -200,7 +200,7 @@ function Comments({ postId }: { postId: string }) { function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -Defined in: [packages/react-query/src/infiniteQueryOptions.ts:294](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L294) +Defined in: [packages/react-query/src/infiniteQueryOptions.ts:283](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L283) You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. @@ -245,6 +245,10 @@ The same options object, typed so that `queryKey` carries the inferred data type See [useInfiniteQuery](useInfiniteQuery.md) for examples that fetch further pages (from a button click or automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set. +### See + +[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. + ### Example A parameterized factory, so the same options object can be reused per `postId`: @@ -273,10 +277,6 @@ function Comments({ postId }: { postId: string }) { } ``` -### See - -[useInfiniteQuery](useInfiniteQuery.md) to run an infinite query with these options. - ## Parameters diff --git a/docs/framework/react/reference/functions/matchMutation.md b/docs/framework/react/reference/functions/matchMutation.md index 7903e79a6b6..b12d3b9565c 100644 --- a/docs/framework/react/reference/functions/matchMutation.md +++ b/docs/framework/react/reference/functions/matchMutation.md @@ -7,7 +7,7 @@ title: matchMutation function matchMutation(filters: MutationFilters, mutation: Mutation): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:237](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L237) +Defined in: [packages/query-core/src/utils.ts:269](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L269) Checks whether a mutation matches the given [MutationFilters](../interfaces/MutationFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -19,6 +19,8 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) +The filters to check the mutation against. + #### `filters` properties @@ -34,10 +36,14 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> +The mutation to check. + ## Returns `boolean` +`true` if the mutation matches every specified filter. + ## Example ```ts diff --git a/docs/framework/react/reference/functions/matchQuery.md b/docs/framework/react/reference/functions/matchQuery.md index 961ff43c3d1..e1cdd4ee789 100644 --- a/docs/framework/react/reference/functions/matchQuery.md +++ b/docs/framework/react/reference/functions/matchQuery.md @@ -7,7 +7,7 @@ title: matchQuery function matchQuery(filters: QueryFilters, query: Query): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:175](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L175) +Defined in: [packages/query-core/src/utils.ts:205](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L205) Checks whether a query matches the given [QueryFilters](../interfaces/QueryFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -18,6 +18,8 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) +The filters to check the query against. + #### `filters` properties @@ -35,10 +37,14 @@ Every filter that is specified must match; filters that are left unspecified are [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> +The query to check. + ## Returns `boolean` +`true` if the query matches every specified filter. + ## Example ```ts diff --git a/docs/framework/react/reference/functions/useMutation.md b/docs/framework/react/reference/functions/useMutation.md index fd915a3ee5d..db22ad35136 100644 --- a/docs/framework/react/reference/functions/useMutation.md +++ b/docs/framework/react/reference/functions/useMutation.md @@ -9,7 +9,7 @@ redirect_from: function useMutation(options: UseMutationOptions, queryClient?: QueryClient): UseMutationResult; ``` -Defined in: [packages/react-query/src/useMutation.ts:191](https://github.com/TanStack/query/blob/main/packages/react-query/src/useMutation.ts#L191) +Defined in: [packages/react-query/src/useMutation.ts:187](https://github.com/TanStack/query/blob/main/packages/react-query/src/useMutation.ts#L187) Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects. `useMutation` is the hook for that. @@ -83,6 +83,11 @@ the mutation settles removes the subscription and prevents them from firing. Built from [`MutationObserverBaseResult`](../interfaces/MutationObserverBaseResult.md#properties). See the type above for what it changes. +## Throws + +The mutation error, when `throwOnError` is `true` or returns `true` for it, so that it is +thrown to the nearest error boundary. + ## See [mutationOptions](mutationOptions.md) to share these options across multiple `useMutation` call sites, or to look diff --git a/docs/framework/react/reference/functions/useQuery.md b/docs/framework/react/reference/functions/useQuery.md index 4095d58fff3..a2fb1c7aa88 100644 --- a/docs/framework/react/reference/functions/useQuery.md +++ b/docs/framework/react/reference/functions/useQuery.md @@ -14,8 +14,8 @@ function useQuery(options: UseQueryOptio ``` - [`DefinedInitialDataOptions` → `DefinedUseQueryResult`](#call-signature-1): This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless a `select` changes `TData` to include `undefined`). -- [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-2) -- [`UseQueryOptions` → `UseQueryResult`](#call-signature-3) +- [`UndefinedInitialDataOptions` → `UseQueryResult`](#call-signature-2): This overload is selected when `initialData` is omitted or may be `undefined`, so the resulting `data` can be `undefined`. +- [`UseQueryOptions` → `UseQueryResult`](#call-signature-3): Fallback overload for options whose `initialData` presence isn't statically known — for example, an object typed as [UseQueryOptions](../interfaces/UseQueryOptions.md) rather than an object literal. Prefer one of the other overloads when possible, since they infer whether `data` can be `undefined` from `initialData` directly. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/solid/reference/functions/QueryClientProvider.md b/docs/framework/solid/reference/functions/QueryClientProvider.md index fca0e621e48..97429d9f6c0 100644 --- a/docs/framework/solid/reference/functions/QueryClientProvider.md +++ b/docs/framework/solid/reference/functions/QueryClientProvider.md @@ -7,7 +7,7 @@ title: QueryClientProvider function QueryClientProvider(props: QueryClientProviderProps): Element; ``` -Defined in: [packages/solid-query/src/QueryClientProvider.tsx:95](https://github.com/TanStack/query/blob/main/packages/solid-query/src/QueryClientProvider.tsx#L95) +Defined in: [packages/solid-query/src/QueryClientProvider.tsx:100](https://github.com/TanStack/query/blob/main/packages/solid-query/src/QueryClientProvider.tsx#L100) Use the `QueryClientProvider` component to connect and provide a `QueryClient` to your application. Also calls `client.mount()`/`client.unmount()` as this component mounts/unmounts, which subscribes the client to @@ -20,6 +20,8 @@ comes back online). [`QueryClientProviderProps`](../type-aliases/QueryClientProviderProps.md) +The `client` to provide, and the `children` that get access to it. + #### `props` properties diff --git a/docs/framework/solid/reference/functions/dehydrate.md b/docs/framework/solid/reference/functions/dehydrate.md index 50a55efe0c5..8653ce08798 100644 --- a/docs/framework/solid/reference/functions/dehydrate.md +++ b/docs/framework/solid/reference/functions/dehydrate.md @@ -7,7 +7,7 @@ title: dehydrate function dehydrate(client: QueryClient, options: DehydrateOptions): DehydratedState; ``` -Defined in: [packages/query-core/src/hydration.ts:208](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L208) +Defined in: [packages/query-core/src/hydration.ts:245](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L245) Dehydrates a `QueryClient`'s cache (queries and mutations) into a plain, serializable `DehydratedState`, typically to embed in server-rendered markup and later restore into a client-side `QueryClient` via `hydrate`. @@ -21,10 +21,15 @@ falling back to the client's `dehydrate` default options, and finally to `defaul `QueryClient` +The client whose cache is dehydrated. + ### options [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` +Controls which queries and mutations are included and how their data and errors +are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. + #### `options` properties @@ -40,14 +45,16 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydratedState`](../interfaces/DehydratedState.md) +The dehydrated state, with the included `queries` and `mutations`. + ### Result properties -| Property | Type | -| ------ | ------ | -| `mutations` | `DehydratedMutation`[] | -| `queries` | `DehydratedQuery`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/solid/reference/functions/hydrate.md b/docs/framework/solid/reference/functions/hydrate.md index 6c746514b09..17c0afeb896 100644 --- a/docs/framework/solid/reference/functions/hydrate.md +++ b/docs/framework/solid/reference/functions/hydrate.md @@ -10,7 +10,7 @@ function hydrate( options?: HydrateOptions): void; ``` -Defined in: [packages/query-core/src/hydration.ts:265](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L265) +Defined in: [packages/query-core/src/hydration.ts:306](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L306) Restores a `DehydratedState` (as produced by `dehydrate`) into a `QueryClient`'s cache, typically to seed the client with data already fetched on the server. `mutations` and `queries` are each optional on `dehydratedState`. @@ -26,10 +26,14 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `QueryClient` +The client whose cache is restored into. + ### dehydratedState `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> +The dehydrated state, e.g. produced by `dehydrate` on the server. + #### `dehydratedState` properties @@ -40,6 +44,9 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See [`HydrateOptions`](../interfaces/HydrateOptions.md) +`defaultOptions` merged into every restored query and mutation (on top of the +client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + #### `options` properties diff --git a/docs/framework/solid/reference/functions/matchMutation.md b/docs/framework/solid/reference/functions/matchMutation.md index 7903e79a6b6..b12d3b9565c 100644 --- a/docs/framework/solid/reference/functions/matchMutation.md +++ b/docs/framework/solid/reference/functions/matchMutation.md @@ -7,7 +7,7 @@ title: matchMutation function matchMutation(filters: MutationFilters, mutation: Mutation): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:237](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L237) +Defined in: [packages/query-core/src/utils.ts:269](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L269) Checks whether a mutation matches the given [MutationFilters](../interfaces/MutationFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -19,6 +19,8 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) +The filters to check the mutation against. + #### `filters` properties @@ -34,10 +36,14 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> +The mutation to check. + ## Returns `boolean` +`true` if the mutation matches every specified filter. + ## Example ```ts diff --git a/docs/framework/solid/reference/functions/matchQuery.md b/docs/framework/solid/reference/functions/matchQuery.md index 961ff43c3d1..e1cdd4ee789 100644 --- a/docs/framework/solid/reference/functions/matchQuery.md +++ b/docs/framework/solid/reference/functions/matchQuery.md @@ -7,7 +7,7 @@ title: matchQuery function matchQuery(filters: QueryFilters, query: Query): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:175](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L175) +Defined in: [packages/query-core/src/utils.ts:205](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L205) Checks whether a query matches the given [QueryFilters](../interfaces/QueryFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -18,6 +18,8 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) +The filters to check the query against. + #### `filters` properties @@ -35,10 +37,14 @@ Every filter that is specified must match; filters that are left unspecified are [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> +The query to check. + ## Returns `boolean` +`true` if the query matches every specified filter. + ## Example ```ts diff --git a/docs/framework/svelte/reference/functions/createQuery.md b/docs/framework/svelte/reference/functions/createQuery.md index e78bccd4521..d3c2148d67b 100644 --- a/docs/framework/svelte/reference/functions/createQuery.md +++ b/docs/framework/svelte/reference/functions/createQuery.md @@ -13,7 +13,7 @@ function createQuery(options: Accessor #### `options` properties @@ -40,14 +45,16 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydratedState`](../interfaces/DehydratedState.md) +The dehydrated state, with the included `queries` and `mutations`. + ### Result properties -| Property | Type | -| ------ | ------ | -| `mutations` | `DehydratedMutation`[] | -| `queries` | `DehydratedQuery`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/svelte/reference/functions/hydrate.md b/docs/framework/svelte/reference/functions/hydrate.md index 65d204a296a..e160e90a332 100644 --- a/docs/framework/svelte/reference/functions/hydrate.md +++ b/docs/framework/svelte/reference/functions/hydrate.md @@ -10,7 +10,7 @@ function hydrate( options?: HydrateOptions): void; ``` -Defined in: [packages/query-core/src/hydration.ts:265](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L265) +Defined in: [packages/query-core/src/hydration.ts:306](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L306) Restores a `DehydratedState` (as produced by `dehydrate`) into a `QueryClient`'s cache, typically to seed the client with data already fetched on the server. `mutations` and `queries` are each optional on `dehydratedState`. @@ -26,10 +26,14 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm [`QueryClient`](../classes/QueryClient.md) +The client whose cache is restored into. + ### dehydratedState `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> +The dehydrated state, e.g. produced by `dehydrate` on the server. + #### `dehydratedState` properties @@ -40,6 +44,9 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See [`HydrateOptions`](../interfaces/HydrateOptions.md) +`defaultOptions` merged into every restored query and mutation (on top of the +client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + #### `options` properties diff --git a/docs/framework/svelte/reference/functions/matchMutation.md b/docs/framework/svelte/reference/functions/matchMutation.md index 7903e79a6b6..b12d3b9565c 100644 --- a/docs/framework/svelte/reference/functions/matchMutation.md +++ b/docs/framework/svelte/reference/functions/matchMutation.md @@ -7,7 +7,7 @@ title: matchMutation function matchMutation(filters: MutationFilters, mutation: Mutation): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:237](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L237) +Defined in: [packages/query-core/src/utils.ts:269](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L269) Checks whether a mutation matches the given [MutationFilters](../interfaces/MutationFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -19,6 +19,8 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) +The filters to check the mutation against. + #### `filters` properties @@ -34,10 +36,14 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> +The mutation to check. + ## Returns `boolean` +`true` if the mutation matches every specified filter. + ## Example ```ts diff --git a/docs/framework/svelte/reference/functions/matchQuery.md b/docs/framework/svelte/reference/functions/matchQuery.md index 961ff43c3d1..e1cdd4ee789 100644 --- a/docs/framework/svelte/reference/functions/matchQuery.md +++ b/docs/framework/svelte/reference/functions/matchQuery.md @@ -7,7 +7,7 @@ title: matchQuery function matchQuery(filters: QueryFilters, query: Query): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:175](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L175) +Defined in: [packages/query-core/src/utils.ts:205](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L205) Checks whether a query matches the given [QueryFilters](../interfaces/QueryFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -18,6 +18,8 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) +The filters to check the query against. + #### `filters` properties @@ -35,10 +37,14 @@ Every filter that is specified must match; filters that are left unspecified are [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> +The query to check. + ## Returns `boolean` +`true` if the query matches every specified filter. + ## Example ```ts diff --git a/docs/framework/svelte/reference/functions/useMutationState.md b/docs/framework/svelte/reference/functions/useMutationState.md index af86b5aebc9..0bbde650c83 100644 --- a/docs/framework/svelte/reference/functions/useMutationState.md +++ b/docs/framework/svelte/reference/functions/useMutationState.md @@ -36,10 +36,10 @@ mutation state. #### `options` properties -| Property | Type | -| ------ | ------ | -| `filters?` | [`MutationFilters`](../interfaces/MutationFilters.md) | -| `select?` | (`mutation`: `TMutation`) => `TResult` | +| Property | Type | Description | +| ------ | ------ | ------ | +| `filters?` | [`MutationFilters`](../interfaces/MutationFilters.md) | The filters that select the mutations to return the state of. | +| `select?` | (`mutation`: `TMutation`) => `TResult` | Maps each matching mutation to the value returned for it. Defaults to the mutation's `state`. | ### queryClient? diff --git a/docs/framework/vue/reference/functions/dehydrate.md b/docs/framework/vue/reference/functions/dehydrate.md index 50a55efe0c5..8653ce08798 100644 --- a/docs/framework/vue/reference/functions/dehydrate.md +++ b/docs/framework/vue/reference/functions/dehydrate.md @@ -7,7 +7,7 @@ title: dehydrate function dehydrate(client: QueryClient, options: DehydrateOptions): DehydratedState; ``` -Defined in: [packages/query-core/src/hydration.ts:208](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L208) +Defined in: [packages/query-core/src/hydration.ts:245](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L245) Dehydrates a `QueryClient`'s cache (queries and mutations) into a plain, serializable `DehydratedState`, typically to embed in server-rendered markup and later restore into a client-side `QueryClient` via `hydrate`. @@ -21,10 +21,15 @@ falling back to the client's `dehydrate` default options, and finally to `defaul `QueryClient` +The client whose cache is dehydrated. + ### options [`DehydrateOptions`](../interfaces/DehydrateOptions.md) = `{}` +Controls which queries and mutations are included and how their data and errors +are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. + #### `options` properties @@ -40,14 +45,16 @@ falling back to the client's `dehydrate` default options, and finally to `defaul [`DehydratedState`](../interfaces/DehydratedState.md) +The dehydrated state, with the included `queries` and `mutations`. + ### Result properties -| Property | Type | -| ------ | ------ | -| `mutations` | `DehydratedMutation`[] | -| `queries` | `DehydratedQuery`[] | +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/vue/reference/functions/hydrate.md b/docs/framework/vue/reference/functions/hydrate.md index 6c746514b09..17c0afeb896 100644 --- a/docs/framework/vue/reference/functions/hydrate.md +++ b/docs/framework/vue/reference/functions/hydrate.md @@ -10,7 +10,7 @@ function hydrate( options?: HydrateOptions): void; ``` -Defined in: [packages/query-core/src/hydration.ts:265](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L265) +Defined in: [packages/query-core/src/hydration.ts:306](https://github.com/TanStack/query/blob/main/packages/query-core/src/hydration.ts#L306) Restores a `DehydratedState` (as produced by `dehydrate`) into a `QueryClient`'s cache, typically to seed the client with data already fetched on the server. `mutations` and `queries` are each optional on `dehydratedState`. @@ -26,10 +26,14 @@ promise, it is resumed via `query.fetch()` (reusing that promise as `initialProm `QueryClient` +The client whose cache is restored into. + ### dehydratedState `Partial`\<[`DehydratedState`](../interfaces/DehydratedState.md)\> +The dehydrated state, e.g. produced by `dehydrate` on the server. + #### `dehydratedState` properties @@ -40,6 +44,9 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See [`HydrateOptions`](../interfaces/HydrateOptions.md) +`defaultOptions` merged into every restored query and mutation (on top of the +client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + #### `options` properties diff --git a/docs/framework/vue/reference/functions/matchMutation.md b/docs/framework/vue/reference/functions/matchMutation.md index 7903e79a6b6..b12d3b9565c 100644 --- a/docs/framework/vue/reference/functions/matchMutation.md +++ b/docs/framework/vue/reference/functions/matchMutation.md @@ -7,7 +7,7 @@ title: matchMutation function matchMutation(filters: MutationFilters, mutation: Mutation): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:237](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L237) +Defined in: [packages/query-core/src/utils.ts:269](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L269) Checks whether a mutation matches the given [MutationFilters](../interfaces/MutationFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -19,6 +19,8 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`MutationFilters`](../interfaces/MutationFilters.md) +The filters to check the mutation against. + #### `filters` properties @@ -34,10 +36,14 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> +The mutation to check. + ## Returns `boolean` +`true` if the mutation matches every specified filter. + ## Example ```ts diff --git a/docs/framework/vue/reference/functions/matchQuery.md b/docs/framework/vue/reference/functions/matchQuery.md index 961ff43c3d1..e1cdd4ee789 100644 --- a/docs/framework/vue/reference/functions/matchQuery.md +++ b/docs/framework/vue/reference/functions/matchQuery.md @@ -7,7 +7,7 @@ title: matchQuery function matchQuery(filters: QueryFilters, query: Query): boolean; ``` -Defined in: [packages/query-core/src/utils.ts:175](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L175) +Defined in: [packages/query-core/src/utils.ts:205](https://github.com/TanStack/query/blob/main/packages/query-core/src/utils.ts#L205) Checks whether a query matches the given [QueryFilters](../interfaces/QueryFilters.md). Every filter that is specified must match; filters that are left unspecified are ignored. @@ -18,6 +18,8 @@ Every filter that is specified must match; filters that are left unspecified are [`QueryFilters`](../interfaces/QueryFilters.md) +The filters to check the query against. + #### `filters` properties @@ -35,10 +37,14 @@ Every filter that is specified must match; filters that are left unspecified are [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> +The query to check. + ## Returns `boolean` +`true` if the query matches every specified filter. + ## Example ```ts From 7651f7c6053ff4308166dc403eb7cece810a234b Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Mon, 5 Oct 2026 12:42:58 +0900 Subject: [PATCH 04/12] docs(framework/*/reference): regenerate reference docs --- .../angular/reference/functions/dehydrate.md | 20 ---- .../angular/reference/functions/hydrate.md | 17 ---- .../functions/infiniteQueryOptions.md | 43 --------- .../functions/injectInfiniteQuery.md | 95 ------------------- .../reference/functions/injectIsFetching.md | 21 ---- .../reference/functions/injectIsMutating.md | 19 ---- .../reference/functions/injectMutation.md | 28 ------ .../functions/injectMutationState.md | 8 -- .../reference/functions/injectQuery.md | 87 ----------------- .../reference/functions/matchMutation.md | 11 --- .../angular/reference/functions/matchQuery.md | 13 --- .../reference/functions/mutationOptions.md | 47 --------- .../angular/reference/functions/noop.md | 22 ----- .../reference/functions/queryFeature.md | 9 -- .../reference/functions/queryOptions.md | 42 -------- 15 files changed, 482 deletions(-) diff --git a/docs/framework/angular/reference/functions/dehydrate.md b/docs/framework/angular/reference/functions/dehydrate.md index 4fd7568ed13..40d47106c19 100644 --- a/docs/framework/angular/reference/functions/dehydrate.md +++ b/docs/framework/angular/reference/functions/dehydrate.md @@ -30,32 +30,12 @@ The client whose cache is dehydrated. Controls which queries and mutations are included and how their data and errors are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | -| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | -| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | -| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | - ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) The dehydrated state, with the included `queries` and `mutations`. - - -### Result properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | -| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | - ## Example ```ts diff --git a/docs/framework/angular/reference/functions/hydrate.md b/docs/framework/angular/reference/functions/hydrate.md index e160e90a332..5e250b9da2b 100644 --- a/docs/framework/angular/reference/functions/hydrate.md +++ b/docs/framework/angular/reference/functions/hydrate.md @@ -34,12 +34,6 @@ The client whose cache is restored into. The dehydrated state, e.g. produced by `dehydrate` on the server. - - -#### `dehydratedState` properties - -Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. - ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) @@ -47,17 +41,6 @@ Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See `defaultOptions` merged into every restored query and mutation (on top of the client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | -| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | -| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | -| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | - ## Returns `void` diff --git a/docs/framework/angular/reference/functions/infiniteQueryOptions.md b/docs/framework/angular/reference/functions/infiniteQueryOptions.md index 99b9c2a64fb..fea63614295 100644 --- a/docs/framework/angular/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/angular/reference/functions/infiniteQueryOptions.md @@ -3,22 +3,6 @@ id: infiniteQueryOptions title: infiniteQueryOptions --- -## Overview - -```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; -``` - -- [`DefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. - -See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) - - - ## Call Signature ```ts @@ -110,8 +94,6 @@ export class Projects { } ``` - - ## Call Signature ```ts @@ -207,8 +189,6 @@ export class Comments { } ``` - - ## Call Signature ```ts @@ -303,26 +283,3 @@ export class Comments { readonly commentsQuery = injectInfiniteQuery(() => commentsOptions(this.postId())) } ``` - - - -## Parameters - -### options - -[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> - -The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to -`injectInfiniteQuery`. - - - -#### `options` properties - -Built from [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptions.md#properties). See the type above for what it changes. - - - -## Returns - -The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/angular/reference/functions/injectInfiniteQuery.md b/docs/framework/angular/reference/functions/injectInfiniteQuery.md index 61e20feb353..25fc0c0f09f 100644 --- a/docs/framework/angular/reference/functions/injectInfiniteQuery.md +++ b/docs/framework/angular/reference/functions/injectInfiniteQuery.md @@ -3,22 +3,6 @@ id: injectInfiniteQuery title: injectInfiniteQuery --- -## Overview - -```ts -function injectInfiniteQuery(injectInfiniteQueryFn: () => DefinedInitialDataInfiniteOptions, options?: InjectInfiniteQueryOptions): DefinedCreateInfiniteQueryResult; -function injectInfiniteQuery(injectInfiniteQueryFn: () => UndefinedInitialDataInfiniteOptions, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult; -function injectInfiniteQuery(injectInfiniteQueryFn: () => CreateInfiniteQueryOptions, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult; -``` - -- [`DefinedInitialDataInfiniteOptions` → `DefinedCreateInfiniteQueryResult`](#call-signature-1): The options for `injectInfiniteQuery` are identical to `injectQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". -- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryResult`](#call-signature-2): Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". -- [`CreateInfiniteQueryOptions` → `CreateInfiniteQueryResult`](#call-signature-3): This overload accepts the general [CreateInfiniteQueryOptions](../interfaces/CreateInfiniteQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectInfiniteQuery` in your own helper function that forwards caller-provided options. - -See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) - - - ## Call Signature ```ts @@ -120,8 +104,6 @@ export class Projects { } ``` - - ## Call Signature ```ts @@ -311,8 +293,6 @@ export class Comments { } ``` - - ## Call Signature ```ts @@ -368,78 +348,3 @@ Additional configuration. [`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> The infinite query result. - - - -## Parameters - -### injectInfiniteQueryFn - -() => [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> - -A function that returns infinite query options. Similar to `computed` from -Angular, this function runs in the reactive context, so signals read inside it drive the query. - - - -#### `injectInfiniteQueryFn` properties - -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | - -### options? - -[`InjectInfiniteQueryOptions`](../interfaces/InjectInfiniteQueryOptions.md) - -Additional configuration. - - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `injector?` | `Injector` | The `Injector` in which to create the infinite query. If this is not provided, the current injection context will be used instead (via `inject`). | - - - -## Returns - -[`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> - -The infinite query result. - - - -### Result properties - -Built from [`BaseQueryNarrowing`](../interfaces/BaseQueryNarrowing.md#properties), [`InfiniteQueryObserverBaseResult`](../interfaces/InfiniteQueryObserverBaseResult.md#properties). See the type above for what it changes. diff --git a/docs/framework/angular/reference/functions/injectIsFetching.md b/docs/framework/angular/reference/functions/injectIsFetching.md index c84d3c9b5ff..ce629a0cf3f 100644 --- a/docs/framework/angular/reference/functions/injectIsFetching.md +++ b/docs/framework/angular/reference/functions/injectIsFetching.md @@ -20,33 +20,12 @@ background (useful for app-wide loading indicators). The [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched queries. - - -#### `filters` properties - -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | - ### options? [`InjectIsFetchingOptions`](../interfaces/InjectIsFetchingOptions.md) Additional configuration - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `injector?` | `Injector` | The `Injector` in which to create the isFetching signal. If this is not provided, the current injection context will be used instead (via `inject`). | - ## Returns `Signal`\<`number`\> diff --git a/docs/framework/angular/reference/functions/injectIsMutating.md b/docs/framework/angular/reference/functions/injectIsMutating.md index 9a6e6798f93..665038e25dd 100644 --- a/docs/framework/angular/reference/functions/injectIsMutating.md +++ b/docs/framework/angular/reference/functions/injectIsMutating.md @@ -20,31 +20,12 @@ Injects a signal that tracks the number of mutations that your application curre The [MutationFilters](../interfaces/MutationFilters.md) to narrow down the matched mutations. - - -#### `filters` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | - ### options? [`InjectIsMutatingOptions`](../interfaces/InjectIsMutatingOptions.md) Additional configuration - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `injector?` | `Injector` | The `Injector` in which to create the isMutating signal. If this is not provided, the current injection context will be used instead (via `inject`). | - ## Returns `Signal`\<`number`\> diff --git a/docs/framework/angular/reference/functions/injectMutation.md b/docs/framework/angular/reference/functions/injectMutation.md index f1c521966fc..6af11f4fa48 100644 --- a/docs/framework/angular/reference/functions/injectMutation.md +++ b/docs/framework/angular/reference/functions/injectMutation.md @@ -39,40 +39,12 @@ Unlike queries, mutations are typically used to create/update/delete data or per A function that returns mutation options. Similar to `computed` from Angular, this function runs in the reactive context, so signals read inside it drive the mutation's options. - - -#### `injectMutationFn` properties - -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | -| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | -| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | -| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | -| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | -| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | -| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | - ### options? [`InjectMutationOptions`](../interfaces/InjectMutationOptions.md) Additional configuration - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `injector?` | `Injector` | The `Injector` in which to create the mutation. If this is not provided, the current injection context will be used instead (via `inject`). | - ## Returns [`CreateMutationResult`](../type-aliases/CreateMutationResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> diff --git a/docs/framework/angular/reference/functions/injectMutationState.md b/docs/framework/angular/reference/functions/injectMutationState.md index fde85f87d7c..43f90b0fdd0 100644 --- a/docs/framework/angular/reference/functions/injectMutationState.md +++ b/docs/framework/angular/reference/functions/injectMutationState.md @@ -34,14 +34,6 @@ in the reactive context, so signals read inside it re-narrow the matched mutatio Additional configuration - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `injector?` | `Injector` | The `Injector` in which to create the mutation state signal. If this is not provided, the current injection context will be used instead (via `inject`). | - ## Returns `Signal`\<`TResult`[]\> diff --git a/docs/framework/angular/reference/functions/injectQuery.md b/docs/framework/angular/reference/functions/injectQuery.md index 9a558fce7a2..d4c64df0376 100644 --- a/docs/framework/angular/reference/functions/injectQuery.md +++ b/docs/framework/angular/reference/functions/injectQuery.md @@ -3,22 +3,6 @@ id: injectQuery title: injectQuery --- -## Overview - -```ts -function injectQuery(injectQueryFn: () => DefinedInitialDataOptions, options?: InjectQueryOptions): DefinedCreateQueryResult; -function injectQuery(injectQueryFn: () => UndefinedInitialDataOptions, options?: InjectQueryOptions): CreateQueryResult; -function injectQuery(injectQueryFn: () => CreateQueryOptions, options?: InjectQueryOptions): CreateQueryResult; -``` - -- [`DefinedInitialDataOptions` → `DefinedCreateQueryResult`](#call-signature-1): This overload is selected when `initialData` is set on the options returned by `injectQueryFn`, so the resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`). -- [`UndefinedInitialDataOptions` → `CreateQueryResult`](#call-signature-2): Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. -- [`CreateQueryOptions` → `CreateQueryResult`](#call-signature-3): This overload accepts the general [CreateQueryOptions](../interfaces/CreateQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectQuery` in your own helper function that forwards caller-provided options. - -See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) - - - ## Call Signature ```ts @@ -104,8 +88,6 @@ export class Posts { } ``` - - ## Call Signature ```ts @@ -224,8 +206,6 @@ export class Posts { } ``` - - ## Call Signature ```ts @@ -281,70 +261,3 @@ The query result. ### See https://tanstack.com/query/latest/docs/framework/angular/guides/queries - - - -## Parameters - -### injectQueryFn - -() => [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> - -A function that returns query options. Similar to `computed` from Angular, this -function runs in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive -the query. - - - -#### `injectQueryFn` properties - -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | - -### options? - -[`InjectQueryOptions`](../interfaces/InjectQueryOptions.md) - -Additional configuration - - - -#### `options` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `injector?` | `Injector` | The `Injector` in which to create the query. If this is not provided, the current injection context will be used instead (via `inject`). | - - - -## Returns - -[`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> - -The query result. diff --git a/docs/framework/angular/reference/functions/matchMutation.md b/docs/framework/angular/reference/functions/matchMutation.md index b12d3b9565c..af337cdbec0 100644 --- a/docs/framework/angular/reference/functions/matchMutation.md +++ b/docs/framework/angular/reference/functions/matchMutation.md @@ -21,17 +21,6 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i The filters to check the mutation against. - - -#### `filters` properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | - ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/angular/reference/functions/matchQuery.md b/docs/framework/angular/reference/functions/matchQuery.md index e1cdd4ee789..312065fa2f2 100644 --- a/docs/framework/angular/reference/functions/matchQuery.md +++ b/docs/framework/angular/reference/functions/matchQuery.md @@ -20,19 +20,6 @@ Every filter that is specified must match; filters that are left unspecified are The filters to check the query against. - - -#### `filters` properties - -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | - ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/angular/reference/functions/mutationOptions.md b/docs/framework/angular/reference/functions/mutationOptions.md index 8cefaa926a2..a68edb0aab2 100644 --- a/docs/framework/angular/reference/functions/mutationOptions.md +++ b/docs/framework/angular/reference/functions/mutationOptions.md @@ -3,20 +3,6 @@ id: mutationOptions title: mutationOptions --- -## Overview - -```ts -function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; -function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; -``` - -- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `injectMutationState`. -- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other filters, such as `status`. - -See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) - - - ## Call Signature ```ts @@ -93,8 +79,6 @@ export class SavingIndicator { } ``` - - ## Call Signature ```ts @@ -181,34 +165,3 @@ export class Post { } } ``` - - - -## Parameters - -### options - -`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> - -The mutation options to use, identical to what you'd pass to `injectMutation`, without a -`mutationKey`. - - - -#### `options` properties - -Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes. - - - -## Returns - -`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> - -The same options object, unchanged. - - - -### Result properties - -Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/angular/reference/functions/noop.md b/docs/framework/angular/reference/functions/noop.md index 02331d2a79f..5fe4fc5ba99 100644 --- a/docs/framework/angular/reference/functions/noop.md +++ b/docs/framework/angular/reference/functions/noop.md @@ -3,20 +3,6 @@ id: noop title: noop --- -## Overview - -```ts -function noop(): void; -function noop(): undefined; -``` - -- [`void`](#call-signature-1): A function that does nothing. -- [`undefined`](#call-signature-2): A function that does nothing. - -See also: [Returns](#returns-summary) - - - ## Call Signature ```ts @@ -31,8 +17,6 @@ A function that does nothing. `void` - - ## Call Signature ```ts @@ -46,9 +30,3 @@ A function that does nothing. ### Returns `undefined` - - - -## Returns - -`undefined` diff --git a/docs/framework/angular/reference/functions/queryFeature.md b/docs/framework/angular/reference/functions/queryFeature.md index ea8a90c9aae..ac98f4c34f9 100644 --- a/docs/framework/angular/reference/functions/queryFeature.md +++ b/docs/framework/angular/reference/functions/queryFeature.md @@ -36,12 +36,3 @@ The Angular providers this feature contributes to `provideTanStackQuery`. [`QueryFeature`](../interfaces/QueryFeature.md)\<`TFeatureKind`\> A Query feature. - - - -### Result properties - -| Property | Type | Description | -| ------ | ------ | ------ | -| `ɵkind` | `TFeatureKind` | The kind of the feature, e.g. `'Devtools'` or `'PersistQueryClient'`. | -| `ɵproviders` | `Provider`[] | The providers that `provideTanStackQuery` registers for the feature. | diff --git a/docs/framework/angular/reference/functions/queryOptions.md b/docs/framework/angular/reference/functions/queryOptions.md index 3b7fbe80fbf..4f8fc331648 100644 --- a/docs/framework/angular/reference/functions/queryOptions.md +++ b/docs/framework/angular/reference/functions/queryOptions.md @@ -3,22 +3,6 @@ id: queryOptions title: queryOptions --- -## Overview - -```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; -``` - -- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. - -See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) - - - ## Call Signature ```ts @@ -101,8 +85,6 @@ export class Posts { } ``` - - ## Call Signature ```ts @@ -180,8 +162,6 @@ export class Post { } ``` - - ## Call Signature ```ts @@ -292,25 +272,3 @@ export class Post { readonly postQuery = injectQuery(() => postOptions(this.postId())) } ``` - - - -## Parameters - -### options - -[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> - -The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `injectQuery`. - - - -#### `options` properties - -Built from [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md#properties). See the type above for what it changes. - - - -## Returns - -The same options object, typed so that `queryKey` carries the inferred data type. From 5b8eda16fcecd86dda8a8df1255d120369b73a00 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Mon, 5 Oct 2026 12:44:10 +0900 Subject: [PATCH 05/12] chore(scripts/generate-docs): restore the 'dirname' import that the merge dropped --- scripts/generate-docs.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index e35c83fa5cd..0e6f4abc67a 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -1,6 +1,6 @@ import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises' import { createRequire } from 'node:module' -import { resolve } from 'node:path' +import { dirname, resolve } from 'node:path' import { fileURLToPath } from 'node:url' const __dirname = fileURLToPath(new URL('.', import.meta.url)) From 824200733787acd3a42ea650180e1021c39e9a67 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Mon, 5 Oct 2026 12:44:36 +0900 Subject: [PATCH 06/12] docs(framework/*/reference): regenerate reference docs --- .../angular/reference/functions/dehydrate.md | 20 +++ .../angular/reference/functions/hydrate.md | 17 +++ .../functions/infiniteQueryOptions.md | 43 ++++++ .../functions/injectInfiniteQuery.md | 95 +++++++++++++ .../reference/functions/injectIsFetching.md | 21 +++ .../reference/functions/injectIsMutating.md | 19 +++ .../reference/functions/injectMutation.md | 28 ++++ .../functions/injectMutationState.md | 8 ++ .../reference/functions/injectQuery.md | 87 ++++++++++++ .../reference/functions/matchMutation.md | 11 ++ .../angular/reference/functions/matchQuery.md | 13 ++ .../reference/functions/mutationOptions.md | 47 +++++++ .../angular/reference/functions/noop.md | 22 +++ .../reference/functions/queryFeature.md | 9 ++ .../reference/functions/queryOptions.md | 42 ++++++ .../createInfiniteQueryController.md | 33 +---- .../functions/createMutationController.md | 16 +-- .../functions/createQueriesController.md | 5 +- .../functions/createQueryController.md | 30 +---- .../lit/reference/functions/dehydrate.md | 12 +- .../lit/reference/functions/hydrate.md | 2 +- .../functions/infiniteQueryOptions.md | 60 ++++----- .../lit/reference/functions/matchMutation.md | 8 +- .../lit/reference/functions/matchQuery.md | 12 +- .../reference/functions/mutationOptions.md | 52 ++++---- .../lit/reference/functions/useIsFetching.md | 9 +- .../lit/reference/functions/useIsMutating.md | 7 +- .../reference/functions/useMutationState.md | 4 +- .../reference/functions/HydrationBoundary.md | 8 +- .../functions/QueryClientProvider.md | 4 +- .../functions/QueryErrorResetBoundary.md | 2 +- .../preact/reference/functions/dehydrate.md | 12 +- .../preact/reference/functions/hydrate.md | 2 +- .../reference/functions/matchMutation.md | 8 +- .../preact/reference/functions/matchQuery.md | 12 +- .../reference/functions/useInfiniteQuery.md | 126 +++++++++--------- .../reference/functions/useIsFetching.md | 12 +- .../reference/functions/useIsMutating.md | 8 +- .../preact/reference/functions/useMutation.md | 26 ++-- .../preact/reference/functions/useQuery.md | 104 +++++++-------- .../functions/useSuspenseInfiniteQuery.md | 54 ++++---- .../reference/functions/useSuspenseQueries.md | 2 +- .../reference/functions/useSuspenseQuery.md | 48 +++---- .../reference/functions/HydrationBoundary.md | 8 +- .../functions/QueryClientProvider.md | 4 +- .../functions/QueryErrorResetBoundary.md | 2 +- .../react/reference/functions/dehydrate.md | 12 +- .../react/reference/functions/hydrate.md | 2 +- .../reference/functions/matchMutation.md | 8 +- .../react/reference/functions/matchQuery.md | 12 +- .../reference/functions/useInfiniteQuery.md | 126 +++++++++--------- .../reference/functions/useIsFetching.md | 12 +- .../reference/functions/useIsMutating.md | 8 +- .../react/reference/functions/useMutation.md | 26 ++-- .../react/reference/functions/useQuery.md | 104 +++++++-------- .../functions/useSuspenseInfiniteQuery.md | 54 ++++---- .../reference/functions/useSuspenseQueries.md | 2 +- .../reference/functions/useSuspenseQuery.md | 48 +++---- .../functions/QueryClientProvider.md | 4 +- .../solid/reference/functions/dehydrate.md | 12 +- .../solid/reference/functions/hydrate.md | 2 +- .../reference/functions/matchMutation.md | 8 +- .../solid/reference/functions/matchQuery.md | 12 +- .../reference/functions/useInfiniteQuery.md | 66 ++++----- .../solid/reference/functions/useQuery.md | 50 +++---- .../functions/createInfiniteQuery.md | 126 +++++++++--------- .../svelte/reference/functions/createQuery.md | 104 +++++++-------- .../svelte/reference/functions/dehydrate.md | 12 +- .../svelte/reference/functions/hydrate.md | 2 +- .../reference/functions/matchMutation.md | 8 +- .../svelte/reference/functions/matchQuery.md | 12 +- .../svelte/reference/functions/useHydrate.md | 2 +- .../reference/functions/useIsFetching.md | 12 +- .../reference/functions/useIsMutating.md | 8 +- .../reference/functions/useMutationState.md | 4 +- .../vue/reference/functions/dehydrate.md | 12 +- .../vue/reference/functions/hydrate.md | 2 +- .../vue/reference/functions/matchMutation.md | 8 +- .../vue/reference/functions/matchQuery.md | 12 +- .../reference/functions/mutationOptions.md | 8 +- .../vue/reference/functions/queryOptions.md | 8 +- .../reference/functions/useMutationState.md | 6 + 82 files changed, 1238 insertions(+), 850 deletions(-) diff --git a/docs/framework/angular/reference/functions/dehydrate.md b/docs/framework/angular/reference/functions/dehydrate.md index 40d47106c19..2bc0ac7a297 100644 --- a/docs/framework/angular/reference/functions/dehydrate.md +++ b/docs/framework/angular/reference/functions/dehydrate.md @@ -30,12 +30,32 @@ The client whose cache is dehydrated. Controls which queries and mutations are included and how their data and errors are transformed. Each option falls back to the client's `defaultOptions.dehydrate`. + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | + ## Returns [`DehydratedState`](../interfaces/DehydratedState.md) The dehydrated state, with the included `queries` and `mutations`. + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | + ## Example ```ts diff --git a/docs/framework/angular/reference/functions/hydrate.md b/docs/framework/angular/reference/functions/hydrate.md index 5e250b9da2b..51dc7e63493 100644 --- a/docs/framework/angular/reference/functions/hydrate.md +++ b/docs/framework/angular/reference/functions/hydrate.md @@ -34,6 +34,12 @@ The client whose cache is restored into. The dehydrated state, e.g. produced by `dehydrate` on the server. + + +#### `dehydratedState` properties + +Built from [`DehydratedState`](../interfaces/DehydratedState.md#properties). See the type above for what it changes. + ### options? [`HydrateOptions`](../interfaces/HydrateOptions.md) @@ -41,6 +47,17 @@ The dehydrated state, e.g. produced by `dehydrate` on the server. `defaultOptions` merged into every restored query and mutation (on top of the client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeData`. + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | +| `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | +| `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | + ## Returns `void` diff --git a/docs/framework/angular/reference/functions/infiniteQueryOptions.md b/docs/framework/angular/reference/functions/infiniteQueryOptions.md index fea63614295..99b9c2a64fb 100644 --- a/docs/framework/angular/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/angular/reference/functions/infiniteQueryOptions.md @@ -3,6 +3,22 @@ id: infiniteQueryOptions title: infiniteQueryOptions --- +## Overview + +```ts +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +``` + +- [`DefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -94,6 +110,8 @@ export class Projects { } ``` + + ## Call Signature ```ts @@ -189,6 +207,8 @@ export class Comments { } ``` + + ## Call Signature ```ts @@ -283,3 +303,26 @@ export class Comments { readonly commentsQuery = injectInfiniteQuery(() => commentsOptions(this.postId())) } ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataInfiniteOptions.md) to use — everything you can pass to +`injectInfiniteQuery`. + + + +#### `options` properties + +Built from [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptions.md#properties). See the type above for what it changes. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/angular/reference/functions/injectInfiniteQuery.md b/docs/framework/angular/reference/functions/injectInfiniteQuery.md index 25fc0c0f09f..4aa3bca2b9d 100644 --- a/docs/framework/angular/reference/functions/injectInfiniteQuery.md +++ b/docs/framework/angular/reference/functions/injectInfiniteQuery.md @@ -3,6 +3,22 @@ id: injectInfiniteQuery title: injectInfiniteQuery --- +## Overview + +```ts +function injectInfiniteQuery(injectInfiniteQueryFn: () => DefinedInitialDataInfiniteOptions, options?: InjectInfiniteQueryOptions): DefinedCreateInfiniteQueryResult; +function injectInfiniteQuery(injectInfiniteQueryFn: () => UndefinedInitialDataInfiniteOptions, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult; +function injectInfiniteQuery(injectInfiniteQueryFn: () => CreateInfiniteQueryOptions, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult; +``` + +- [`DefinedInitialDataInfiniteOptions` → `DefinedCreateInfiniteQueryResult`](#call-signature-1): The options for `injectInfiniteQuery` are identical to `injectQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". +- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryResult`](#call-signature-2): Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". +- [`CreateInfiniteQueryOptions` → `CreateInfiniteQueryResult`](#call-signature-3): This overload accepts the general [CreateInfiniteQueryOptions](../interfaces/CreateInfiniteQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectInfiniteQuery` in your own helper function that forwards caller-provided options. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -104,6 +120,8 @@ export class Projects { } ``` + + ## Call Signature ```ts @@ -293,6 +311,8 @@ export class Comments { } ``` + + ## Call Signature ```ts @@ -348,3 +368,78 @@ Additional configuration. [`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> The infinite query result. + + + +## Parameters + +### injectInfiniteQueryFn + +() => [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> + +A function that returns infinite query options. Similar to `computed` from +Angular, this function runs in the reactive context, so signals read inside it drive the query. + + + +#### `injectInfiniteQueryFn` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (() => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| ((`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### options? + +[`InjectInfiniteQueryOptions`](../interfaces/InjectInfiniteQueryOptions.md) + +Additional configuration. + + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the infinite query. If this is not provided, the current injection context will be used instead (via `inject`). | + + + +## Returns + +[`CreateInfiniteQueryResult`](../type-aliases/CreateInfiniteQueryResult.md)\<`TData`, `TError`\> + +The infinite query result. + + + +### Result properties + +Built from [`BaseQueryNarrowing`](../interfaces/BaseQueryNarrowing.md#properties), [`InfiniteQueryObserverBaseResult`](../interfaces/InfiniteQueryObserverBaseResult.md#properties). See the type above for what it changes. diff --git a/docs/framework/angular/reference/functions/injectIsFetching.md b/docs/framework/angular/reference/functions/injectIsFetching.md index ce629a0cf3f..5f13d6a4ae3 100644 --- a/docs/framework/angular/reference/functions/injectIsFetching.md +++ b/docs/framework/angular/reference/functions/injectIsFetching.md @@ -20,12 +20,33 @@ background (useful for app-wide loading indicators). The [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched queries. + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### options? [`InjectIsFetchingOptions`](../interfaces/InjectIsFetchingOptions.md) Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the isFetching signal. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns `Signal`\<`number`\> diff --git a/docs/framework/angular/reference/functions/injectIsMutating.md b/docs/framework/angular/reference/functions/injectIsMutating.md index 665038e25dd..119c3988b1c 100644 --- a/docs/framework/angular/reference/functions/injectIsMutating.md +++ b/docs/framework/angular/reference/functions/injectIsMutating.md @@ -20,12 +20,31 @@ Injects a signal that tracks the number of mutations that your application curre The [MutationFilters](../interfaces/MutationFilters.md) to narrow down the matched mutations. + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### options? [`InjectIsMutatingOptions`](../interfaces/InjectIsMutatingOptions.md) Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the isMutating signal. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns `Signal`\<`number`\> diff --git a/docs/framework/angular/reference/functions/injectMutation.md b/docs/framework/angular/reference/functions/injectMutation.md index 6af11f4fa48..f8591f3ce84 100644 --- a/docs/framework/angular/reference/functions/injectMutation.md +++ b/docs/framework/angular/reference/functions/injectMutation.md @@ -39,12 +39,40 @@ Unlike queries, mutations are typically used to create/update/delete data or per A function that returns mutation options. Similar to `computed` from Angular, this function runs in the reactive context, so signals read inside it drive the mutation's options. + + +#### `injectMutationFn` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| ((`error`: `TError`) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | + ### options? [`InjectMutationOptions`](../interfaces/InjectMutationOptions.md) Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the mutation. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns [`CreateMutationResult`](../type-aliases/CreateMutationResult.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\> diff --git a/docs/framework/angular/reference/functions/injectMutationState.md b/docs/framework/angular/reference/functions/injectMutationState.md index 43f90b0fdd0..183abbc7a46 100644 --- a/docs/framework/angular/reference/functions/injectMutationState.md +++ b/docs/framework/angular/reference/functions/injectMutationState.md @@ -34,6 +34,14 @@ in the reactive context, so signals read inside it re-narrow the matched mutatio Additional configuration + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the mutation state signal. If this is not provided, the current injection context will be used instead (via `inject`). | + ## Returns `Signal`\<`TResult`[]\> diff --git a/docs/framework/angular/reference/functions/injectQuery.md b/docs/framework/angular/reference/functions/injectQuery.md index d4c64df0376..c80f125fabd 100644 --- a/docs/framework/angular/reference/functions/injectQuery.md +++ b/docs/framework/angular/reference/functions/injectQuery.md @@ -3,6 +3,22 @@ id: injectQuery title: injectQuery --- +## Overview + +```ts +function injectQuery(injectQueryFn: () => DefinedInitialDataOptions, options?: InjectQueryOptions): DefinedCreateQueryResult; +function injectQuery(injectQueryFn: () => UndefinedInitialDataOptions, options?: InjectQueryOptions): CreateQueryResult; +function injectQuery(injectQueryFn: () => CreateQueryOptions, options?: InjectQueryOptions): CreateQueryResult; +``` + +- [`DefinedInitialDataOptions` → `DefinedCreateQueryResult`](#call-signature-1): This overload is selected when `initialData` is set on the options returned by `injectQueryFn`, so the resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`). +- [`UndefinedInitialDataOptions` → `CreateQueryResult`](#call-signature-2): Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. +- [`CreateQueryOptions` → `CreateQueryResult`](#call-signature-3): This overload accepts the general [CreateQueryOptions](../interfaces/CreateQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectQuery` in your own helper function that forwards caller-provided options. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -88,6 +104,8 @@ export class Posts { } ``` + + ## Call Signature ```ts @@ -206,6 +224,8 @@ export class Posts { } ``` + + ## Call Signature ```ts @@ -261,3 +281,70 @@ The query result. ### See https://tanstack.com/query/latest/docs/framework/angular/guides/queries + + + +## Parameters + +### injectQueryFn + +() => [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +A function that returns query options. Similar to `computed` from Angular, this +function runs in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive +the query. + + + +#### `injectQueryFn` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| (() => `TQueryFnData` \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| ((`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | + +### options? + +[`InjectQueryOptions`](../interfaces/InjectQueryOptions.md) + +Additional configuration + + + +#### `options` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `injector?` | `Injector` | The `Injector` in which to create the query. If this is not provided, the current injection context will be used instead (via `inject`). | + + + +## Returns + +[`CreateQueryResult`](../type-aliases/CreateQueryResult.md)\<`TData`, `TError`\> + +The query result. diff --git a/docs/framework/angular/reference/functions/matchMutation.md b/docs/framework/angular/reference/functions/matchMutation.md index af337cdbec0..dcd87d70157 100644 --- a/docs/framework/angular/reference/functions/matchMutation.md +++ b/docs/framework/angular/reference/functions/matchMutation.md @@ -21,6 +21,17 @@ If a `mutationKey` filter is provided but the mutation has no `mutationKey` of i The filters to check the mutation against. + + +#### `filters` properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | + ### mutation [`Mutation`](../classes/Mutation.md)\<`any`, `any`\> diff --git a/docs/framework/angular/reference/functions/matchQuery.md b/docs/framework/angular/reference/functions/matchQuery.md index 312065fa2f2..2cc0696220c 100644 --- a/docs/framework/angular/reference/functions/matchQuery.md +++ b/docs/framework/angular/reference/functions/matchQuery.md @@ -20,6 +20,19 @@ Every filter that is specified must match; filters that are left unspecified are The filters to check the query against. + + +#### `filters` properties + +| Property | Type | Default value | Description | +| ------ | ------ | ------ | ------ | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | + ### query [`Query`](../classes/Query.md)\<`any`, `any`, `any`, `any`\> diff --git a/docs/framework/angular/reference/functions/mutationOptions.md b/docs/framework/angular/reference/functions/mutationOptions.md index a68edb0aab2..8cefaa926a2 100644 --- a/docs/framework/angular/reference/functions/mutationOptions.md +++ b/docs/framework/angular/reference/functions/mutationOptions.md @@ -3,6 +3,20 @@ id: mutationOptions title: mutationOptions --- +## Overview + +```ts +function mutationOptions(options: WithRequired, "mutationKey">): WithRequired, "mutationKey">; +function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; +``` + +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `injectMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other filters, such as `status`. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -79,6 +93,8 @@ export class SavingIndicator { } ``` + + ## Call Signature ```ts @@ -165,3 +181,34 @@ export class Post { } } ``` + + + +## Parameters + +### options + +`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The mutation options to use, identical to what you'd pass to `injectMutation`, without a +`mutationKey`. + + + +#### `options` properties + +Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes. + + + +## Returns + +`Omit`\<[`CreateMutationOptions`](../interfaces/CreateMutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> + +The same options object, unchanged. + + + +### Result properties + +Built from [`CreateMutationOptions`](../interfaces/CreateMutationOptions.md#properties). See the type above for what it changes. diff --git a/docs/framework/angular/reference/functions/noop.md b/docs/framework/angular/reference/functions/noop.md index 5fe4fc5ba99..02331d2a79f 100644 --- a/docs/framework/angular/reference/functions/noop.md +++ b/docs/framework/angular/reference/functions/noop.md @@ -3,6 +3,20 @@ id: noop title: noop --- +## Overview + +```ts +function noop(): void; +function noop(): undefined; +``` + +- [`void`](#call-signature-1): A function that does nothing. +- [`undefined`](#call-signature-2): A function that does nothing. + +See also: [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -17,6 +31,8 @@ A function that does nothing. `void` + + ## Call Signature ```ts @@ -30,3 +46,9 @@ A function that does nothing. ### Returns `undefined` + + + +## Returns + +`undefined` diff --git a/docs/framework/angular/reference/functions/queryFeature.md b/docs/framework/angular/reference/functions/queryFeature.md index ac98f4c34f9..5c53d5a7a08 100644 --- a/docs/framework/angular/reference/functions/queryFeature.md +++ b/docs/framework/angular/reference/functions/queryFeature.md @@ -36,3 +36,12 @@ The Angular providers this feature contributes to `provideTanStackQuery`. [`QueryFeature`](../interfaces/QueryFeature.md)\<`TFeatureKind`\> A Query feature. + + + +### Result properties + +| Property | Type | Description | +| ------ | ------ | ------ | +| `ɵkind` | `TFeatureKind` | The kind of the feature, e.g. `'Devtools'` or `'PersistQueryClient'`. | +| `ɵproviders` | `Provider`[] | The providers that `provideTanStackQuery` registers for the feature. | diff --git a/docs/framework/angular/reference/functions/queryOptions.md b/docs/framework/angular/reference/functions/queryOptions.md index 4f8fc331648..3b7fbe80fbf 100644 --- a/docs/framework/angular/reference/functions/queryOptions.md +++ b/docs/framework/angular/reference/functions/queryOptions.md @@ -3,6 +3,22 @@ id: queryOptions title: queryOptions --- +## Overview + +```ts +function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +``` + +- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. + +See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) + + + ## Call Signature ```ts @@ -85,6 +101,8 @@ export class Posts { } ``` + + ## Call Signature ```ts @@ -162,6 +180,8 @@ export class Post { } ``` + + ## Call Signature ```ts @@ -272,3 +292,25 @@ export class Post { readonly postQuery = injectQuery(() => postOptions(this.postId())) } ``` + + + +## Parameters + +### options + +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> + +The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use — everything you can pass to `injectQuery`. + + + +#### `options` properties + +Built from [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md#properties). See the type above for what it changes. + + + +## Returns + +The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/lit/reference/functions/createInfiniteQueryController.md b/docs/framework/lit/reference/functions/createInfiniteQueryController.md index 4231dfd07b9..2c7daf93e7d 100644 --- a/docs/framework/lit/reference/functions/createInfiniteQueryController.md +++ b/docs/framework/lit/reference/functions/createInfiniteQueryController.md @@ -65,38 +65,7 @@ options. #### `options` properties -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +Built from [`InfiniteQueryObserverOptions`](../interfaces/InfiniteQueryObserverOptions.md#properties). See the type above for what it changes. ### queryClient? diff --git a/docs/framework/lit/reference/functions/createMutationController.md b/docs/framework/lit/reference/functions/createMutationController.md index 78ad304640c..f22a364051b 100644 --- a/docs/framework/lit/reference/functions/createMutationController.md +++ b/docs/framework/lit/reference/functions/createMutationController.md @@ -59,21 +59,7 @@ Mutation observer options, or a getter that returns options. #### `options` properties -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | -| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | -| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | -| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | -| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | -| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | -| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | +Built from [`MutationObserverOptions`](../interfaces/MutationObserverOptions.md#properties). See the type above for what it changes. ### queryClient? diff --git a/docs/framework/lit/reference/functions/createQueriesController.md b/docs/framework/lit/reference/functions/createQueriesController.md index b43f0043b2e..67c3bdde5e4 100644 --- a/docs/framework/lit/reference/functions/createQueriesController.md +++ b/docs/framework/lit/reference/functions/createQueriesController.md @@ -51,10 +51,7 @@ Queries controller options, or a getter that returns options. #### `options` properties -| Property | Type | Description | -| ------ | ------ | ------ | -| `combine?` | (`result`: `CreateQueriesResults`\<`TQueryOptions`\>) => `TCombinedResult` | Optional function that combines the query result array into one value. | -| `queries` | [`Accessor`](../type-aliases/Accessor.md)\< \| readonly \[`...CreateQueriesOptions`\] \| readonly \[`...{ [K in keyof TQueryOptions]: GetCreateQueriesInput }`\]\> | Query options to observe, or a getter that returns the current options. | +Built from [`CreateQueriesControllerOptions`](../type-aliases/CreateQueriesControllerOptions.md#properties). See the type above for what it changes. ### queryClient? diff --git a/docs/framework/lit/reference/functions/createQueryController.md b/docs/framework/lit/reference/functions/createQueryController.md index d011c0ff658..7f6d7bec7a4 100644 --- a/docs/framework/lit/reference/functions/createQueryController.md +++ b/docs/framework/lit/reference/functions/createQueryController.md @@ -62,35 +62,7 @@ Query observer options, or a getter that returns options. #### `options` properties -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `initialData?` | `TQueryData` \| () => `TQueryData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryData`\>, `TError`, `NonFunctionGuard`\<`TQueryData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: `TQueryData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#properties). See the type above for what it changes. ### queryClient? diff --git a/docs/framework/lit/reference/functions/dehydrate.md b/docs/framework/lit/reference/functions/dehydrate.md index 4fd7568ed13..2bc0ac7a297 100644 --- a/docs/framework/lit/reference/functions/dehydrate.md +++ b/docs/framework/lit/reference/functions/dehydrate.md @@ -36,10 +36,10 @@ are transformed. Each option falls back to the client's `defaultOptions.dehydrat | Property | Type | Description | | ------ | ------ | ------ | -| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | -| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | -| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | -| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | ## Returns @@ -53,8 +53,8 @@ The dehydrated state, with the included `queries` and `mutations`. | Property | Type | Description | | ------ | ------ | ------ | -| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | -| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/lit/reference/functions/hydrate.md b/docs/framework/lit/reference/functions/hydrate.md index 9772d216cee..7609806252b 100644 --- a/docs/framework/lit/reference/functions/hydrate.md +++ b/docs/framework/lit/reference/functions/hydrate.md @@ -53,7 +53,7 @@ client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeD | Property | Type | Description | | ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | | `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | | `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | | `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | diff --git a/docs/framework/lit/reference/functions/infiniteQueryOptions.md b/docs/framework/lit/reference/functions/infiniteQueryOptions.md index 25fe68159e1..6effa6b8174 100644 --- a/docs/framework/lit/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/lit/reference/functions/infiniteQueryOptions.md @@ -48,36 +48,36 @@ Infinite query options to preserve and brand. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (() => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| ((`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | ## Returns diff --git a/docs/framework/lit/reference/functions/matchMutation.md b/docs/framework/lit/reference/functions/matchMutation.md index b12d3b9565c..dcd87d70157 100644 --- a/docs/framework/lit/reference/functions/matchMutation.md +++ b/docs/framework/lit/reference/functions/matchMutation.md @@ -27,10 +27,10 @@ The filters to check the mutation against. | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### mutation diff --git a/docs/framework/lit/reference/functions/matchQuery.md b/docs/framework/lit/reference/functions/matchQuery.md index e1cdd4ee789..2cc0696220c 100644 --- a/docs/framework/lit/reference/functions/matchQuery.md +++ b/docs/framework/lit/reference/functions/matchQuery.md @@ -26,12 +26,12 @@ The filters to check the query against. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### query diff --git a/docs/framework/lit/reference/functions/mutationOptions.md b/docs/framework/lit/reference/functions/mutationOptions.md index a14d99eecc3..6941686bf43 100644 --- a/docs/framework/lit/reference/functions/mutationOptions.md +++ b/docs/framework/lit/reference/functions/mutationOptions.md @@ -43,19 +43,19 @@ Mutation options to preserve. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | -| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | -| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | -| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | -| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | -| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | -| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| ((`error`: `TError`) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | ## Returns @@ -69,19 +69,19 @@ The same options object. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | -| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | -| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | -| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | -| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | -| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | -| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| ((`error`: `TError`) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | ## Example diff --git a/docs/framework/lit/reference/functions/useIsFetching.md b/docs/framework/lit/reference/functions/useIsFetching.md index 661a47cba93..857ef16d18c 100644 --- a/docs/framework/lit/reference/functions/useIsFetching.md +++ b/docs/framework/lit/reference/functions/useIsFetching.md @@ -38,14 +38,7 @@ Query filters, or a getter that returns query filters. #### `filters` properties -| Property | Type | Default value | Description | -| ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +Built from [`QueryFilters`](../interfaces/QueryFilters.md#properties). See the type above for what it changes. ### queryClient? diff --git a/docs/framework/lit/reference/functions/useIsMutating.md b/docs/framework/lit/reference/functions/useIsMutating.md index 662abd4cd28..f9b8e9de699 100644 --- a/docs/framework/lit/reference/functions/useIsMutating.md +++ b/docs/framework/lit/reference/functions/useIsMutating.md @@ -38,12 +38,7 @@ Mutation filters, or a getter that returns mutation filters. #### `filters` properties -| Property | Type | Description | -| ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +Built from [`MutationFilters`](../interfaces/MutationFilters.md#properties). See the type above for what it changes. ### queryClient? diff --git a/docs/framework/lit/reference/functions/useMutationState.md b/docs/framework/lit/reference/functions/useMutationState.md index 213e6bf8f0a..b8423d77b71 100644 --- a/docs/framework/lit/reference/functions/useMutationState.md +++ b/docs/framework/lit/reference/functions/useMutationState.md @@ -47,8 +47,8 @@ Mutation state filters and optional selector. | Property | Type | Description | | ------ | ------ | ------ | -| `filters?` | [`Accessor`](../type-aliases/Accessor.md)\<[`MutationFilters`](../interfaces/MutationFilters.md)\> | Filters used to select mutations from the mutation cache. | -| `select?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `TResult` | Maps each matching mutation to the value returned by the accessor. | +| `filters?` | [`Accessor`](../type-aliases/Accessor.md)\<[`MutationFilters`](../interfaces/MutationFilters.md)\> | Filters used to select mutations from the mutation cache. | +| `select?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `TResult` | Maps each matching mutation to the value returned by the accessor. | ### queryClient? diff --git a/docs/framework/preact/reference/functions/HydrationBoundary.md b/docs/framework/preact/reference/functions/HydrationBoundary.md index 4de7af659ad..b5fddffb1bf 100644 --- a/docs/framework/preact/reference/functions/HydrationBoundary.md +++ b/docs/framework/preact/reference/functions/HydrationBoundary.md @@ -30,10 +30,10 @@ The dehydrated `state` to hydrate, the hydrate `options`, an optional custom | Property | Type | Description | | ------ | ------ | ------ | -| `children?` | `ComponentChildren` | The components to render — always rendered unconditionally, not gated on hydration. New queries are hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it lands. | -| `options?` | [`OmitKeyof`](../type-aliases/OmitKeyof.md)\<[`HydrateOptions`](../interfaces/HydrateOptions.md), `"defaultOptions"`\> & `object` | Optional. Note: unlike `hydrate`, `mutations` cannot be set here. | -| `queryClient?` | [`QueryClient`](../classes/QueryClient.md) | Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will be used. | -| `state` | [`DehydratedState`](../interfaces/DehydratedState.md) \| `null` \| `undefined` | The state to hydrate. | +| `children?` | `ComponentChildren` | The components to render — always rendered unconditionally, not gated on hydration. New queries are hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it lands. | +| `options?` | [`OmitKeyof`](../type-aliases/OmitKeyof.md)\<[`HydrateOptions`](../interfaces/HydrateOptions.md), `"defaultOptions"`\> & `object` | Optional. Note: unlike `hydrate`, `mutations` cannot be set here. | +| `queryClient?` | [`QueryClient`](../classes/QueryClient.md) | Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will be used. | +| `state` | [`DehydratedState`](../interfaces/DehydratedState.md) \| `null` \| `undefined` | The state to hydrate. | ## Returns diff --git a/docs/framework/preact/reference/functions/QueryClientProvider.md b/docs/framework/preact/reference/functions/QueryClientProvider.md index eb0f56ff2fd..2668267c4cf 100644 --- a/docs/framework/preact/reference/functions/QueryClientProvider.md +++ b/docs/framework/preact/reference/functions/QueryClientProvider.md @@ -28,8 +28,8 @@ The `client` to provide, and the `children` that get access to it. | Property | Type | Description | | ------ | ------ | ------ | -| `children?` | `ComponentChildren` | The components that get access to the provided `QueryClient`. | -| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | +| `children?` | `ComponentChildren` | The components that get access to the provided `QueryClient`. | +| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | ## Returns diff --git a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md index 6531ae5d962..b813cdc221c 100644 --- a/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md +++ b/docs/framework/preact/reference/functions/QueryErrorResetBoundary.md @@ -27,7 +27,7 @@ The `children` to render. | Property | Type | Description | | ------ | ------ | ------ | -| `children` | \| `ComponentChildren` \| [`QueryErrorResetBoundaryFunction`](../type-aliases/QueryErrorResetBoundaryFunction.md) | Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and returns a node. | +| `children` | \| `ComponentChildren` \| [`QueryErrorResetBoundaryFunction`](../type-aliases/QueryErrorResetBoundaryFunction.md) | Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and returns a node. | ## Returns diff --git a/docs/framework/preact/reference/functions/dehydrate.md b/docs/framework/preact/reference/functions/dehydrate.md index 4fd7568ed13..2bc0ac7a297 100644 --- a/docs/framework/preact/reference/functions/dehydrate.md +++ b/docs/framework/preact/reference/functions/dehydrate.md @@ -36,10 +36,10 @@ are transformed. Each option falls back to the client's `defaultOptions.dehydrat | Property | Type | Description | | ------ | ------ | ------ | -| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | -| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | -| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | -| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | ## Returns @@ -53,8 +53,8 @@ The dehydrated state, with the included `queries` and `mutations`. | Property | Type | Description | | ------ | ------ | ------ | -| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | -| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/preact/reference/functions/hydrate.md b/docs/framework/preact/reference/functions/hydrate.md index e160e90a332..51dc7e63493 100644 --- a/docs/framework/preact/reference/functions/hydrate.md +++ b/docs/framework/preact/reference/functions/hydrate.md @@ -53,7 +53,7 @@ client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeD | Property | Type | Description | | ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | | `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | | `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | | `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | diff --git a/docs/framework/preact/reference/functions/matchMutation.md b/docs/framework/preact/reference/functions/matchMutation.md index b12d3b9565c..dcd87d70157 100644 --- a/docs/framework/preact/reference/functions/matchMutation.md +++ b/docs/framework/preact/reference/functions/matchMutation.md @@ -27,10 +27,10 @@ The filters to check the mutation against. | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### mutation diff --git a/docs/framework/preact/reference/functions/matchQuery.md b/docs/framework/preact/reference/functions/matchQuery.md index e1cdd4ee789..2cc0696220c 100644 --- a/docs/framework/preact/reference/functions/matchQuery.md +++ b/docs/framework/preact/reference/functions/matchQuery.md @@ -26,12 +26,12 @@ The filters to check the query against. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### query diff --git a/docs/framework/preact/reference/functions/useInfiniteQuery.md b/docs/framework/preact/reference/functions/useInfiniteQuery.md index 7977db6f0ec..d705315d7f5 100644 --- a/docs/framework/preact/reference/functions/useInfiniteQuery.md +++ b/docs/framework/preact/reference/functions/useInfiniteQuery.md @@ -484,36 +484,36 @@ The [UseInfiniteQueryOptions](../interfaces/UseInfiniteQueryOptions.md) to use | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (() => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| ((`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | ### queryClient? @@ -539,36 +539,36 @@ The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchP | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | -| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | -| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | -| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | -| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | -| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/preact/reference/functions/useIsFetching.md b/docs/framework/preact/reference/functions/useIsFetching.md index e690fb5bf05..3faf5e624ff 100644 --- a/docs/framework/preact/reference/functions/useIsFetching.md +++ b/docs/framework/preact/reference/functions/useIsFetching.md @@ -26,12 +26,12 @@ The [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched que | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### queryClient? diff --git a/docs/framework/preact/reference/functions/useIsMutating.md b/docs/framework/preact/reference/functions/useIsMutating.md index b18e138abf9..19ea567ad85 100644 --- a/docs/framework/preact/reference/functions/useIsMutating.md +++ b/docs/framework/preact/reference/functions/useIsMutating.md @@ -26,10 +26,10 @@ The [MutationFilters](../interfaces/MutationFilters.md) to narrow down the match | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### queryClient? diff --git a/docs/framework/preact/reference/functions/useMutation.md b/docs/framework/preact/reference/functions/useMutation.md index 2fb4df9d71b..1e17e63ac51 100644 --- a/docs/framework/preact/reference/functions/useMutation.md +++ b/docs/framework/preact/reference/functions/useMutation.md @@ -44,19 +44,19 @@ The [UseMutationOptions](../interfaces/UseMutationOptions.md) to use — everyth | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | -| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | -| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | -| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | -| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | -| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | -| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| ((`error`: `TError`) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | ### queryClient? diff --git a/docs/framework/preact/reference/functions/useQuery.md b/docs/framework/preact/reference/functions/useQuery.md index 5635ee7c5a4..a922960d75b 100644 --- a/docs/framework/preact/reference/functions/useQuery.md +++ b/docs/framework/preact/reference/functions/useQuery.md @@ -426,33 +426,33 @@ The [UseQueryOptions](../interfaces/UseQueryOptions.md) to use — everything yo | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| (() => `TQueryFnData` \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| ((`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | ### queryClient? @@ -477,28 +477,28 @@ are derived booleans for convenience. | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md index 01a165c6d4e..190f069ca2d 100644 --- a/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md +++ b/docs/framework/preact/reference/functions/useSuspenseInfiniteQuery.md @@ -50,33 +50,33 @@ The [UseSuspenseInfiniteQueryOptions](../interfaces/UseSuspenseInfiniteQueryOpti | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `queryFn?` | (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (() => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | ### queryClient? diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md index d31625315ce..a6145098d9b 100644 --- a/docs/framework/preact/reference/functions/useSuspenseQueries.md +++ b/docs/framework/preact/reference/functions/useSuspenseQueries.md @@ -503,7 +503,7 @@ The `queries` array to run in Suspense, and an optional `combine` function. #### combine? -(`result`: `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>, `GetUseSuspenseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \{ \[K in string \| number \| symbol\]: GetUseSuspenseQueryResult\\]\> \}) => `TCombinedResult` +(`result`: `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>, `GetUseSuspenseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \{ \[K in string \| number \| symbol\]: GetUseSuspenseQueryResult\ \}) => `TCombinedResult` Use this to combine the results of the queries into a single value. The result will be structurally shared to be as referentially stable as possible. diff --git a/docs/framework/preact/reference/functions/useSuspenseQuery.md b/docs/framework/preact/reference/functions/useSuspenseQuery.md index c75c49333f4..b4fd9e58735 100644 --- a/docs/framework/preact/reference/functions/useSuspenseQuery.md +++ b/docs/framework/preact/reference/functions/useSuspenseQuery.md @@ -46,30 +46,30 @@ The [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) to use | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `queryFn?` | (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| (() => `TQueryFnData` \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | ### queryClient? diff --git a/docs/framework/react/reference/functions/HydrationBoundary.md b/docs/framework/react/reference/functions/HydrationBoundary.md index d34306f72db..e1f96605175 100644 --- a/docs/framework/react/reference/functions/HydrationBoundary.md +++ b/docs/framework/react/reference/functions/HydrationBoundary.md @@ -30,10 +30,10 @@ The dehydrated `state` to hydrate, the hydrate `options`, an optional custom | Property | Type | Description | | ------ | ------ | ------ | -| `children?` | `ReactNode` | The components to render — always rendered unconditionally, not gated on hydration. New queries are hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it lands. | -| `options?` | [`OmitKeyof`](../type-aliases/OmitKeyof.md)\<[`HydrateOptions`](../interfaces/HydrateOptions.md), `"defaultOptions"`\> & `object` | Optional. Note: unlike `hydrate`, `mutations` cannot be set here. | -| `queryClient?` | [`QueryClient`](../classes/QueryClient.md) | Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will be used. | -| `state` | [`DehydratedState`](../interfaces/DehydratedState.md) \| `null` \| `undefined` | The state to hydrate. | +| `children?` | `ReactNode` | The components to render — always rendered unconditionally, not gated on hydration. New queries are hydrated into the cache during render; for queries that already exist in the cache, only newer dehydrated data is hydrated, and that happens in an effect after commit, so `children` may render briefly before it lands. | +| `options?` | [`OmitKeyof`](../type-aliases/OmitKeyof.md)\<[`HydrateOptions`](../interfaces/HydrateOptions.md), `"defaultOptions"`\> & `object` | Optional. Note: unlike `hydrate`, `mutations` cannot be set here. | +| `queryClient?` | [`QueryClient`](../classes/QueryClient.md) | Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will be used. | +| `state` | [`DehydratedState`](../interfaces/DehydratedState.md) \| `null` \| `undefined` | The state to hydrate. | ## Returns diff --git a/docs/framework/react/reference/functions/QueryClientProvider.md b/docs/framework/react/reference/functions/QueryClientProvider.md index 5b0778b6b1c..58716564176 100644 --- a/docs/framework/react/reference/functions/QueryClientProvider.md +++ b/docs/framework/react/reference/functions/QueryClientProvider.md @@ -30,8 +30,8 @@ The `client` to provide, and the `children` that get access to it. | Property | Type | Description | | ------ | ------ | ------ | -| `children?` | `React.ReactNode` | The components that get access to the provided `QueryClient`. | -| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | +| `children?` | `React.ReactNode` | The components that get access to the provided `QueryClient`. | +| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | ## Returns diff --git a/docs/framework/react/reference/functions/QueryErrorResetBoundary.md b/docs/framework/react/reference/functions/QueryErrorResetBoundary.md index 1283aeba32e..739ad5e3889 100644 --- a/docs/framework/react/reference/functions/QueryErrorResetBoundary.md +++ b/docs/framework/react/reference/functions/QueryErrorResetBoundary.md @@ -29,7 +29,7 @@ The `children` to render. | Property | Type | Description | | ------ | ------ | ------ | -| `children` | \| `ReactNode` \| [`QueryErrorResetBoundaryFunction`](../type-aliases/QueryErrorResetBoundaryFunction.md) | Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and returns a node. | +| `children` | \| `ReactNode` \| [`QueryErrorResetBoundaryFunction`](../type-aliases/QueryErrorResetBoundaryFunction.md) | Either a plain node, or a function that receives the boundary's QueryErrorResetBoundaryValue and returns a node. | ## Returns diff --git a/docs/framework/react/reference/functions/dehydrate.md b/docs/framework/react/reference/functions/dehydrate.md index 4fd7568ed13..2bc0ac7a297 100644 --- a/docs/framework/react/reference/functions/dehydrate.md +++ b/docs/framework/react/reference/functions/dehydrate.md @@ -36,10 +36,10 @@ are transformed. Each option falls back to the client's `defaultOptions.dehydrat | Property | Type | Description | | ------ | ------ | ------ | -| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | -| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | -| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | -| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | ## Returns @@ -53,8 +53,8 @@ The dehydrated state, with the included `queries` and `mutations`. | Property | Type | Description | | ------ | ------ | ------ | -| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | -| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/react/reference/functions/hydrate.md b/docs/framework/react/reference/functions/hydrate.md index e160e90a332..51dc7e63493 100644 --- a/docs/framework/react/reference/functions/hydrate.md +++ b/docs/framework/react/reference/functions/hydrate.md @@ -53,7 +53,7 @@ client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeD | Property | Type | Description | | ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | | `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | | `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | | `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | diff --git a/docs/framework/react/reference/functions/matchMutation.md b/docs/framework/react/reference/functions/matchMutation.md index b12d3b9565c..dcd87d70157 100644 --- a/docs/framework/react/reference/functions/matchMutation.md +++ b/docs/framework/react/reference/functions/matchMutation.md @@ -27,10 +27,10 @@ The filters to check the mutation against. | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### mutation diff --git a/docs/framework/react/reference/functions/matchQuery.md b/docs/framework/react/reference/functions/matchQuery.md index e1cdd4ee789..2cc0696220c 100644 --- a/docs/framework/react/reference/functions/matchQuery.md +++ b/docs/framework/react/reference/functions/matchQuery.md @@ -26,12 +26,12 @@ The filters to check the query against. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### query diff --git a/docs/framework/react/reference/functions/useInfiniteQuery.md b/docs/framework/react/reference/functions/useInfiniteQuery.md index a82947d929d..e8f7376284b 100644 --- a/docs/framework/react/reference/functions/useInfiniteQuery.md +++ b/docs/framework/react/reference/functions/useInfiniteQuery.md @@ -486,36 +486,36 @@ The [UseInfiniteQueryOptions](../interfaces/UseInfiniteQueryOptions.md) to use | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (() => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| ((`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | ### queryClient? @@ -541,36 +541,36 @@ The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchP | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | -| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | -| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | -| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | -| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | -| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/react/reference/functions/useIsFetching.md b/docs/framework/react/reference/functions/useIsFetching.md index c6687b91131..3275a18694f 100644 --- a/docs/framework/react/reference/functions/useIsFetching.md +++ b/docs/framework/react/reference/functions/useIsFetching.md @@ -28,12 +28,12 @@ The [QueryFilters](../interfaces/QueryFilters.md) to narrow down the matched que | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### queryClient? diff --git a/docs/framework/react/reference/functions/useIsMutating.md b/docs/framework/react/reference/functions/useIsMutating.md index 8b1a40fbe5b..c8e8d139386 100644 --- a/docs/framework/react/reference/functions/useIsMutating.md +++ b/docs/framework/react/reference/functions/useIsMutating.md @@ -28,10 +28,10 @@ The [MutationFilters](../interfaces/MutationFilters.md) to narrow down the match | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### queryClient? diff --git a/docs/framework/react/reference/functions/useMutation.md b/docs/framework/react/reference/functions/useMutation.md index db22ad35136..0bc3f30ca3d 100644 --- a/docs/framework/react/reference/functions/useMutation.md +++ b/docs/framework/react/reference/functions/useMutation.md @@ -46,19 +46,19 @@ The [UseMutationOptions](../interfaces/UseMutationOptions.md) to use — everyth | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | -| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | -| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | -| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | -| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | -| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | -| `throwOnError?` | `boolean` \| (`error`: `TError`) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that an unused/inactive mutation remains in memory before it is garbage collected. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on the mutation cache entry. Use it to pass information that can be read wherever the `mutation` is available, such as the `onError` and `onSuccess` callbacks of the `MutationCache`. | +| `mutationFn?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `Promise`\<`TData`\> | `undefined` | The function that performs the asynchronous task this mutation runs. Required, unless a default mutation function has been set for the matching `mutationKey` via `queryClient.setMutationDefaults`. Receives the `variables` passed to `mutate`, and a [MutationFunctionContext](../type-aliases/MutationFunctionContext.md) holding the `QueryClient`, the `mutationKey` and `meta`. Must return a promise that resolves the mutation's data. | +| `mutationKey?` | readonly `unknown`[] | `undefined` | The key to use for this mutation. Optional, but required to inherit defaults registered with `queryClient.setMutationDefaults`, and to match this mutation with `useMutationState` or `queryClient.isMutating`. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a mutation is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `onError?` | (`error`: `TError`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation encounters an error, and is passed the error. If a promise is returned, it is awaited before `onSettled` runs. | +| `onMutate?` | (`variables`: `TVariables`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `TOnMutateResult` \| `Promise`\<`TOnMutateResult`\> | `undefined` | This function fires before the mutation function runs, and receives the same variables. Useful for optimistic updates applied in the hope that the mutation succeeds. The value it returns is passed to `onSuccess`, `onError` and `onSettled` as `onMutateResult`, which is where an optimistic update is usually rolled back. If a promise is returned, it is awaited before the mutation function runs. | +| `onSettled?` | (`data`: `TData` \| `undefined`, `error`: `TError` \| `null`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult` \| `undefined`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation either succeeds or errors, and is passed either the data or the error. If a promise is returned, it is awaited before the mutation settles. | +| `onSuccess?` | (`data`: `TData`, `variables`: `TVariables`, `onMutateResult`: `TOnMutateResult`, `context`: [`MutationFunctionContext`](../type-aliases/MutationFunctionContext.md)) => `unknown` | `undefined` | This function fires when the mutation succeeds, and is passed the mutation's result. If a promise is returned, it is awaited before `onSettled` runs. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `0` | If `false`, failed mutations will not retry by default. If `true`, failed mutations will retry infinitely. If set to an integer number, e.g. 3, failed mutations will retry until the failed mutation count meets that number. If set to a function `(failureCount, error) => boolean` failed mutations will retry until the function returns false. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `scope?` | [`MutationScope`](../type-aliases/MutationScope.md) | `undefined` | Controls whether this mutation runs alongside others or waits its turn. Mutations sharing the same `scope.id` run serially, in the order they were started. Without a scope, a mutation runs as soon as it is triggered. | +| `throwOnError?` | `boolean` \| ((`error`: `TError`) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true`, all errors will be thrown to the nearest error boundary. If set to a function, it will be passed the error and should return a boolean indicating whether to throw the error (`true`) or return it as state (`false`). | ### queryClient? diff --git a/docs/framework/react/reference/functions/useQuery.md b/docs/framework/react/reference/functions/useQuery.md index a2fb1c7aa88..573cf4fd94b 100644 --- a/docs/framework/react/reference/functions/useQuery.md +++ b/docs/framework/react/reference/functions/useQuery.md @@ -428,33 +428,33 @@ The [UseQueryOptions](../interfaces/UseQueryOptions.md) to use — everything yo | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| (() => `TQueryFnData` \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryFnData`\> \| ((`previousData`: `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryFnData`\>, `TError`, `NonFunctionGuard`\<`TQueryFnData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryFnData`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | ### queryClient? @@ -479,28 +479,28 @@ are derived booleans for convenience. | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md b/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md index b0d76cd4e6f..b307569fb8a 100644 --- a/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md +++ b/docs/framework/react/reference/functions/useSuspenseInfiniteQuery.md @@ -52,33 +52,33 @@ The [UseSuspenseInfiniteQueryOptions](../interfaces/UseSuspenseInfiniteQueryOpti | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `queryFn?` | (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (() => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | ### queryClient? diff --git a/docs/framework/react/reference/functions/useSuspenseQueries.md b/docs/framework/react/reference/functions/useSuspenseQueries.md index 327ff2f2f71..1eba82cbf21 100644 --- a/docs/framework/react/reference/functions/useSuspenseQueries.md +++ b/docs/framework/react/reference/functions/useSuspenseQueries.md @@ -405,7 +405,7 @@ The `queries` array to run in Suspense, and an optional `combine` function. #### combine? -(`result`: `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>, `GetUseSuspenseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \{ \[K in string \| number \| symbol\]: GetUseSuspenseQueryResult\\]\> \}) => `TCombinedResult` +(`result`: `T` *extends* \[\] ? \[\] : `T` *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>\] : `T` *extends* \[`Head`, `...Tails[]`\] ? \[`...Tails[]`\] *extends* \[\] ? \[\] : \[`...Tails[]`\] *extends* \[`Head`\] ? \[`GetUseSuspenseQueryResult`\<`Head`\>, `GetUseSuspenseQueryResult`\<`Head`\>\] : \[`...Tails[]`\] *extends* \[`Head`, `...Tails[]`\] ? \[`...(...)[]`\] *extends* \[\] ? \[\] : ... *extends* ... ? ... : ... : \[`...{ [K in (...)]: (...) }[]`\] : \{ \[K in string \| number \| symbol\]: GetUseSuspenseQueryResult\ \}) => `TCombinedResult` Use this to combine the results of the queries into a single value. The result will be structurally shared to be as referentially stable as possible. diff --git a/docs/framework/react/reference/functions/useSuspenseQuery.md b/docs/framework/react/reference/functions/useSuspenseQuery.md index 1dee6c13117..241a250fd13 100644 --- a/docs/framework/react/reference/functions/useSuspenseQuery.md +++ b/docs/framework/react/reference/functions/useSuspenseQuery.md @@ -48,30 +48,30 @@ The [UseSuspenseQueryOptions](../interfaces/UseSuspenseQueryOptions.md) to use | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `initialData?` | `TQueryFnData` \| () => `TQueryFnData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `queryFn?` | (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryFnData` \| (() => `TQueryFnData` \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `queryFn?` | (`context`: `object`) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | `skipToken` is not allowed here — Suspense hooks cannot render a "disabled" state, so a query function must always be provided, unless a default query function has been defined. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryFnData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryFnData`, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `subscribed?` | `boolean` | `true` | Set this to `false` to unsubscribe this observer from updates to the query cache. | ### queryClient? diff --git a/docs/framework/solid/reference/functions/QueryClientProvider.md b/docs/framework/solid/reference/functions/QueryClientProvider.md index 97429d9f6c0..745e70ad448 100644 --- a/docs/framework/solid/reference/functions/QueryClientProvider.md +++ b/docs/framework/solid/reference/functions/QueryClientProvider.md @@ -28,8 +28,8 @@ The `client` to provide, and the `children` that get access to it. | Property | Type | Description | | ------ | ------ | ------ | -| `children?` | `JSX.Element` | The components that get access to the provided `QueryClient`. | -| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | +| `children?` | `JSX.Element` | The components that get access to the provided `QueryClient`. | +| `client` | [`QueryClient`](../classes/QueryClient.md) | **Required** The `QueryClient` instance to provide. | ## Returns diff --git a/docs/framework/solid/reference/functions/dehydrate.md b/docs/framework/solid/reference/functions/dehydrate.md index 3b1b8fbe99f..788ac8cb2d0 100644 --- a/docs/framework/solid/reference/functions/dehydrate.md +++ b/docs/framework/solid/reference/functions/dehydrate.md @@ -36,10 +36,10 @@ are transformed. Each option falls back to the client's `defaultOptions.dehydrat | Property | Type | Description | | ------ | ------ | ------ | -| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | -| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | -| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | -| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | ## Returns @@ -53,8 +53,8 @@ The dehydrated state, with the included `queries` and `mutations`. | Property | Type | Description | | ------ | ------ | ------ | -| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | -| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/solid/reference/functions/hydrate.md b/docs/framework/solid/reference/functions/hydrate.md index 17c0afeb896..4c185dd2be1 100644 --- a/docs/framework/solid/reference/functions/hydrate.md +++ b/docs/framework/solid/reference/functions/hydrate.md @@ -53,7 +53,7 @@ client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeD | Property | Type | Description | | ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | | `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | | `defaultOptions.mutations?` | `MutationOptions`\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | | `defaultOptions.queries?` | `QueryOptions`\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | diff --git a/docs/framework/solid/reference/functions/matchMutation.md b/docs/framework/solid/reference/functions/matchMutation.md index b12d3b9565c..dcd87d70157 100644 --- a/docs/framework/solid/reference/functions/matchMutation.md +++ b/docs/framework/solid/reference/functions/matchMutation.md @@ -27,10 +27,10 @@ The filters to check the mutation against. | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### mutation diff --git a/docs/framework/solid/reference/functions/matchQuery.md b/docs/framework/solid/reference/functions/matchQuery.md index e1cdd4ee789..2cc0696220c 100644 --- a/docs/framework/solid/reference/functions/matchQuery.md +++ b/docs/framework/solid/reference/functions/matchQuery.md @@ -26,12 +26,12 @@ The filters to check the query against. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### query diff --git a/docs/framework/solid/reference/functions/useInfiniteQuery.md b/docs/framework/solid/reference/functions/useInfiniteQuery.md index a0626a8ce2e..0bc7809ae4e 100644 --- a/docs/framework/solid/reference/functions/useInfiniteQuery.md +++ b/docs/framework/solid/reference/functions/useInfiniteQuery.md @@ -315,36 +315,36 @@ The same properties as `useQuery`, with the addition of `fetchNextPage`, `fetchP | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | -| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | -| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | -| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | -| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | -| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/solid/reference/functions/useQuery.md b/docs/framework/solid/reference/functions/useQuery.md index e2640b60626..a283652cd92 100644 --- a/docs/framework/solid/reference/functions/useQuery.md +++ b/docs/framework/solid/reference/functions/useQuery.md @@ -357,28 +357,28 @@ convenience. | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/svelte/reference/functions/createInfiniteQuery.md b/docs/framework/svelte/reference/functions/createInfiniteQuery.md index eb46d70e8be..7414732412d 100644 --- a/docs/framework/svelte/reference/functions/createInfiniteQuery.md +++ b/docs/framework/svelte/reference/functions/createInfiniteQuery.md @@ -310,36 +310,36 @@ The [CreateInfiniteQueryOptions](../type-aliases/CreateInfiniteQueryOptions.md) | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | -| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | -| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| () => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `getNextPageParam` | (`lastPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `lastPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the next cursor for infinite queries. The result will also be used to determine the value of `hasNextPage`. | +| `getPreviousPageParam?` | (`firstPage`: `TQueryFnData`, `allPages`: `TQueryFnData`[], `firstPageParam`: `TPageParam`, `allPageParams`: `TPageParam`[]) => `TPageParam` \| `null` \| `undefined` | `undefined` | This function can be set to automatically get the previous cursor for infinite queries. The result will also be used to determine the value of `hasPreviousPage`. | +| `initialData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| (() => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `initialPageParam` | `TPageParam` | `undefined` | The page param to start from when an infinite query has no pages yet. It is passed to `queryFn` as `pageParam` for the first page; every page after that gets the value returned by `getNextPageParam` or `getPreviousPageParam`. It only applies while the query has no pages: once a first page exists, refetching starts from that page's own param instead. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| ((`previousData`: \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<[`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\> \| `undefined`) => \| [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: [`InfiniteData`](../interfaces/InfiniteData.md)) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `TPageParam`\>, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | ### queryClient? @@ -363,36 +363,36 @@ to page through the query. | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | -| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | -| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | -| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | -| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | -| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchNextPage` | (`options?`: [`FetchNextPageOptions`](../interfaces/FetchNextPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the next "page" of results. | +| `fetchPreviousPage` | (`options?`: [`FetchPreviousPageOptions`](../interfaces/FetchPreviousPageOptions.md)) => `Promise`\<[`InfiniteQueryObserverResult`](../type-aliases/InfiniteQueryObserverResult.md)\<`TData`, `TError`\>\> | This function allows you to fetch the previous "page" of results. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `hasNextPage` | `boolean` | Will be `true` if there is a next page to be fetched (known via the `getNextPageParam` option). | +| `hasPreviousPage` | `boolean` | Will be `true` if there is a previous page to be fetched (known via the `getPreviousPageParam` option). | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| `isFetchingNextPage` | `boolean` | Will be `true` while fetching the next page with `fetchNextPage`. | +| `isFetchingPreviousPage` | `boolean` | Will be `true` while fetching the previous page with `fetchPreviousPage`. | +| `isFetchNextPageError` | `boolean` | Will be `true` if the query failed while fetching the next page. | +| `isFetchPreviousPageError` | `boolean` | Will be `true` if the query failed while fetching the previous page. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/svelte/reference/functions/createQuery.md b/docs/framework/svelte/reference/functions/createQuery.md index d3c2148d67b..e703d69d6ce 100644 --- a/docs/framework/svelte/reference/functions/createQuery.md +++ b/docs/framework/svelte/reference/functions/createQuery.md @@ -391,33 +391,33 @@ in an [Accessor](../type-aliases/Accessor.md) so options can be reactive. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `enabled?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | -| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | -| `initialData?` | `TQueryData` \| () => `TQueryData` \| `undefined` | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | -| `initialDataUpdatedAt?` | `number` \| () => `number` \| `undefined` | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | -| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | -| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | -| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| () => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined` | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | -| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | -| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryData`\> \| (`previousData`: `NonFunctionGuard`\<`TQueryData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryData`\>, `TError`, `NonFunctionGuard`\<`TQueryData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryData`\> \| `undefined` | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | -| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | -| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | -| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | -| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | -| `refetchInterval?` | \| `number` \| `false` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `false` \| `undefined` | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | -| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | -| `refetchOnMount?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | -| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | -| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"` | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | -| `retry?` | \| `number` \| `false` \| `true` \| (`failureCount`: `number`, `error`: `TError`) => `boolean` | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | -| `retryDelay?` | `number` \| (`failureCount`: `number`, `error`: `TError`) => `number` | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | -| `retryOnMount?` | \| `false` \| `true` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | -| `select?` | (`data`: `TQueryData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | -| `staleTime?` | \| `number` \| `"static"` \| (`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `"static"` | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | -| `structuralSharing?` | `boolean` \| (`oldData`: `unknown`, `newData`: `unknown`) => `unknown` | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | -| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | -| `throwOnError?` | \| `false` \| `true` \| (`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | +| `enabled?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean`) | `true` | Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys. To refetch the query, use the `refetch` method returned from the `useQuery` instance. Accepts a boolean or function that returns a boolean. | +| `gcTime?` | `number` | `undefined` | The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different garbage collection times are specified, the longest one will be used. Setting it to `Infinity` will disable garbage collection. Defaults to `5 * 60 * 1000` (5 minutes), or `Infinity` during SSR. Note: the maximum allowed time is about 24 days, imposed by `setTimeout`'s 32-bit signed integer delay — see `timeoutManager.setTimeoutProvider` for a workaround. | +| `initialData?` | `TQueryData` \| (() => `TQueryData` \| `undefined`) | `undefined` | If set, this value will be used as the initial data for the query cache (as long as the query hasn't been created or cached yet). If set to a function, the function will be called **once** during the shared/root query initialization, and be expected to synchronously return the initial data. Initial data is considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the cache. | +| `initialDataUpdatedAt?` | `number` \| (() => `number` \| `undefined`) | `undefined` | If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated. | +| `maxPages?` | `number` | `undefined` | Maximum number of pages to store in the data of an infinite query. | +| `meta?` | `Record`\<`string`, `unknown`\> | `undefined` | Additional payload to be stored on each query. Use this property to pass information that can be used in other places. | +| `networkMode?` | `"online"` \| `"always"` \| `"offlineFirst"` | `'online'` | Controls whether a query is allowed to run based on the current network connectivity. **See** [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `notifyOnChangeProps?` | \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `"all"` \| (() => \| `"all"` \| ( \| `"error"` \| `"data"` \| `"isError"` \| `"isPending"` \| `"isLoading"` \| `"isLoadingError"` \| `"isRefetchError"` \| `"isSuccess"` \| `"isPlaceholderData"` \| `"status"` \| `"dataUpdatedAt"` \| `"errorUpdatedAt"` \| `"failureCount"` \| `"failureReason"` \| `"errorUpdateCount"` \| `"isFetched"` \| `"isFetchedAfterMount"` \| `"isFetching"` \| `"isInitialLoading"` \| `"isPaused"` \| `"isRefetching"` \| `"isStale"` \| `"isEnabled"` \| `"refetch"` \| `"fetchStatus"` \| `"fetchNextPage"` \| `"fetchPreviousPage"` \| `"hasNextPage"` \| `"hasPreviousPage"` \| `"isFetchNextPageError"` \| `"isFetchingNextPage"` \| `"isFetchPreviousPageError"` \| `"isFetchingPreviousPage"`)[] \| `undefined`) | `undefined` | If set, the component will only re-render if any of the listed properties change. When set to `['data', 'error']`, the component will only re-render when the `data` or `error` properties change. When set to `'all'`, the component will re-render whenever a query is updated. When set to a function, the function will be executed to compute the list of properties. Defaults to `undefined`, in which case property access is tracked automatically, and the component only re-renders when one of the tracked properties changes. | +| `persister?` | (`queryFn`: (`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`NoInfer`\<`TQueryKey`\>, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>, `context`: `object`, `query`: [`Query`](../classes/Query.md)) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\> | `undefined` | This option can be used to persist the result of a query to an external storage, bypassing the need to actually call the `queryFn`. Useful for persisting a query's data across e.g. server/client boundaries. | +| `placeholderData?` | \| `NonFunctionGuard`\<`TQueryData`\> \| ((`previousData`: `NonFunctionGuard`\<`TQueryData`\> \| `undefined`, `previousQuery`: \| [`Query`](../classes/Query.md)\<`NonFunctionGuard`\<`TQueryData`\>, `TError`, `NonFunctionGuard`\<`TQueryData`\>, `TQueryKey`\> \| `undefined`) => `NonFunctionGuard`\<`TQueryData`\> \| `undefined`) | `undefined` | If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `loading` data and no initialData has been provided. | +| `queryFn?` | \| *typeof* [`skipToken`](../variables/skipToken.md) \| ((`context`: [`QueryFunctionContext`](../type-aliases/QueryFunctionContext.md)\<`TQueryKey`, `TPageParam`\>) => `TQueryFnData` \| `Promise`\<`TQueryFnData`\>) | `undefined` | The function that the query will use to request data. Required, unless a default query function has been set via `queryClient.setQueryDefaults` or `queryClient.setDefaultOptions`. Receives a [QueryFunctionContext](../type-aliases/QueryFunctionContext.md). Must return a promise that will either resolve data or throw an error. The data cannot be `undefined`. | +| `queryHash?` | `string` | `undefined` | The hashed form of `queryKey`, computed with `queryKeyHashFn` (or the default hashing function otherwise). Used as the actual cache key internally. | +| `queryKey` | `TQueryKey` & `object` | `undefined` | The query key to use for this query. The query key will be hashed into a stable hash. See [Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) for more information. The query will automatically update when this key changes (as long as `enabled` is not set to `false`). | +| `queryKeyHashFn?` | (`queryKey`: `TQueryKey`) => `string` | `undefined` | If specified, this function is used to hash the `queryKey` to a string. | +| `refetchInterval?` | \| `number` \| `false` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `false` \| `undefined`) | `false` | If set to a number, the query will continuously refetch at this frequency in milliseconds. If set to a function, the function will be executed with the latest data and query to compute a frequency | +| `refetchIntervalInBackground?` | `boolean` | `false` | If set to `true`, the query will continue to refetch while their tab/window is in the background. | +| `refetchOnMount?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on mount if the data is stale. If set to `false`, will disable additional instances of a query to trigger background refetch. If set to `'always'`, the query will always refetch on mount (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value | +| `refetchOnReconnect?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `undefined` | If set to `true`, the query will refetch on reconnect if the data is stale. If set to `false`, the query will not refetch on reconnect. If set to `'always'`, the query will always refetch on reconnect (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. Defaults to `true` unless `networkMode` is `'always'`. | +| `refetchOnWindowFocus?` | \| `boolean` \| `"always"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean` \| `"always"`) | `true` | If set to `true`, the query will refetch on window focus if the data is stale. If set to `false`, the query will not refetch on window focus. If set to `'always'`, the query will always refetch on window focus (except when `staleTime: 'static'` is used). If set to a function, the function will be executed with the latest data and query to compute the value. | +| `retry?` | \| `number` \| `false` \| `true` \| ((`failureCount`: `number`, `error`: `TError`) => `boolean`) | `undefined` | If `false`, failed queries will not retry by default. If `true`, failed queries will retry infinitely. If set to an integer number, e.g. 3, failed queries will retry until the failed query count meets that number. If set to a function `(failureCount, error) => boolean` failed queries will retry until the function returns false. Defaults to `3` on the client and `0` on the server. | +| `retryDelay?` | `number` \| ((`failureCount`: `number`, `error`: `TError`) => `number`) | `undefined` | This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds. A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff. A function like `attempt => attempt * 1000` applies linear backoff. Defaults to a function that applies exponential backoff, capped at 30 seconds. | +| `retryOnMount?` | \| `false` \| `true` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean`) | `true` | If set to `false`, the query will not be retried on mount if it contains an error. If set to a function, the function will be executed with the query to compute the value. | +| `select?` | (`data`: `TQueryData`) => `TData` | `undefined` | This option can be used to transform or select a part of the data returned by the query function. It affects the returned `data` value, but does not affect what gets stored in the query cache. The `select` function will only run if `data` changed, or if the reference to the `select` function itself changes. To optimize, memoize the function so its reference stays stable across calls. | +| `staleTime?` | \| `number` \| `"static"` \| ((`query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `number` \| `"static"`) | `0` | The time in milliseconds after data is considered stale. If set to `Infinity`, the data will never be considered stale. If set to `'static'`, the data will never be considered stale. If set to a function, the function will be executed with the query to compute a `staleTime`. | +| `structuralSharing?` | `boolean` \| ((`oldData`: `unknown`, `newData`: `unknown`) => `unknown`) | `true` | Set this to `false` to disable structural sharing between query results. Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom structural sharing logic. | +| `suspense?` | `boolean` | `false` | If set to `true`, the query will suspend when `status === 'pending'` and throw errors when `status === 'error'`. | +| `throwOnError?` | \| `false` \| `true` \| ((`error`: `TError`, `query`: [`Query`](../classes/Query.md)\<`TQueryFnData`, `TError`, `TQueryData`, `TQueryKey`\>) => `boolean`) | `false` | Whether errors should be thrown instead of setting the `error` property. If set to `true` or `suspense` is `true`, all errors will be thrown to the error boundary. If set to `false` and `suspense` is `false`, errors are returned as state. If set to a function, it will be passed the error and the query, and it should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`). | ### queryClient? @@ -442,28 +442,28 @@ are derived booleans for convenience. | Property | Type | Description | | ------ | ------ | ------ | -| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | -| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | -| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | -| `errorUpdateCount` | `number` | The sum of all errors. | -| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | -| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | -| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | -| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | -| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | -| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | -| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | -| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | -| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | -| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | -| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | -| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | -| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | -| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | -| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | -| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | -| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | -| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | -| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | -| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | -| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | +| `data` | `TData` \| `undefined` | The last successfully resolved data for the query. | +| `dataUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"success"`. | +| `error` | `TError` \| `null` | The error object for the query, if an error was thrown. - Defaults to `null`. | +| `errorUpdateCount` | `number` | The sum of all errors. | +| `errorUpdatedAt` | `number` | The timestamp for when the query most recently returned the `status` as `"error"`. | +| `failureCount` | `number` | The failure count for the query. - Incremented every time the query fails. - Reset to `0` when the query succeeds. | +| `failureReason` | `TError` \| `null` | The failure reason for the query retry. - Reset to `null` when the query succeeds. | +| `fetchStatus` | `"fetching"` \| `"paused"` \| `"idle"` | The fetch status of the query. - `fetching`: Is `true` whenever the queryFn is executing, which includes initial `pending` as well as background refetch. - `paused`: The query wanted to fetch, but has been `paused`. - `idle`: The query is not fetching. - See [Network Mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode) for more information. | +| `isEnabled` | `boolean` | `true` if this observer is enabled, `false` otherwise. | +| `isError` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query attempt resulted in an error. | +| `isFetched` | `boolean` | Will be `true` if the query has been fetched. | +| `isFetchedAfterMount` | `boolean` | Will be `true` if the query has been fetched after the component mounted. - This property can be used to not show any previously cached data. | +| `isFetching` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - `true` whenever the `queryFn` is executing, which includes initial `pending` as well as background refetch. | +| ~~`isInitialLoading`~~ | `boolean` | **Deprecated** `isInitialLoading` is being deprecated in favor of `isLoading` and will be removed in the next major version. | +| `isLoading` | `boolean` | Is `true` whenever the first fetch for a query is in-flight. - Is the same as `isFetching && isPending`. | +| `isLoadingError` | `boolean` | Will be `true` if the query failed while fetching for the first time. | +| `isPaused` | `boolean` | A derived boolean from the `fetchStatus` variable, provided for convenience. - The query wanted to fetch, but has been `paused`. | +| `isPending` | `boolean` | Will be `pending` if there's no cached data and no query attempt was finished yet. | +| `isPlaceholderData` | `boolean` | Will be `true` if the data shown is the placeholder data. | +| `isRefetchError` | `boolean` | Will be `true` if the query failed while refetching. | +| `isRefetching` | `boolean` | Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. - Is the same as `isFetching && !isPending`. | +| `isStale` | `boolean` | Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. | +| `isSuccess` | `boolean` | A derived boolean from the `status` variable, provided for convenience. - `true` if the query has received a response with no errors and is ready to display its data. | +| `refetch` | (`options?`: [`RefetchOptions`](../interfaces/RefetchOptions.md)) => `Promise`\<[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)\<`TData`, `TError`\>\> | A function to manually refetch the query. | +| `status` | `"error"` \| `"pending"` \| `"success"` | The status of the query. - Will be: - `pending` if there's no cached data and no query attempt was finished yet. - `error` if the query attempt resulted in an error. - `success` if the query has received a response with no errors and is ready to display its data. | diff --git a/docs/framework/svelte/reference/functions/dehydrate.md b/docs/framework/svelte/reference/functions/dehydrate.md index 4fd7568ed13..2bc0ac7a297 100644 --- a/docs/framework/svelte/reference/functions/dehydrate.md +++ b/docs/framework/svelte/reference/functions/dehydrate.md @@ -36,10 +36,10 @@ are transformed. Each option falls back to the client's `defaultOptions.dehydrat | Property | Type | Description | | ------ | ------ | ------ | -| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | -| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | -| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | -| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | ## Returns @@ -53,8 +53,8 @@ The dehydrated state, with the included `queries` and `mutations`. | Property | Type | Description | | ------ | ------ | ------ | -| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | -| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/svelte/reference/functions/hydrate.md b/docs/framework/svelte/reference/functions/hydrate.md index e160e90a332..51dc7e63493 100644 --- a/docs/framework/svelte/reference/functions/hydrate.md +++ b/docs/framework/svelte/reference/functions/hydrate.md @@ -53,7 +53,7 @@ client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeD | Property | Type | Description | | ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | | `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | | `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | | `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | diff --git a/docs/framework/svelte/reference/functions/matchMutation.md b/docs/framework/svelte/reference/functions/matchMutation.md index b12d3b9565c..dcd87d70157 100644 --- a/docs/framework/svelte/reference/functions/matchMutation.md +++ b/docs/framework/svelte/reference/functions/matchMutation.md @@ -27,10 +27,10 @@ The filters to check the mutation against. | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### mutation diff --git a/docs/framework/svelte/reference/functions/matchQuery.md b/docs/framework/svelte/reference/functions/matchQuery.md index e1cdd4ee789..2cc0696220c 100644 --- a/docs/framework/svelte/reference/functions/matchQuery.md +++ b/docs/framework/svelte/reference/functions/matchQuery.md @@ -26,12 +26,12 @@ The filters to check the query against. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### query diff --git a/docs/framework/svelte/reference/functions/useHydrate.md b/docs/framework/svelte/reference/functions/useHydrate.md index 53d7c4a83cc..47f9f419ff4 100644 --- a/docs/framework/svelte/reference/functions/useHydrate.md +++ b/docs/framework/svelte/reference/functions/useHydrate.md @@ -37,7 +37,7 @@ The dehydrated state to hydrate into the cache, as produced by `dehydrate`. | Property | Type | Description | | ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | | `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | | `defaultOptions.mutations?` | [`MutationOptions`](../interfaces/MutationOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | | `defaultOptions.queries?` | [`QueryOptions`](../interfaces/QueryOptions.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | diff --git a/docs/framework/svelte/reference/functions/useIsFetching.md b/docs/framework/svelte/reference/functions/useIsFetching.md index e50faa200ee..87bc111a111 100644 --- a/docs/framework/svelte/reference/functions/useIsFetching.md +++ b/docs/framework/svelte/reference/functions/useIsFetching.md @@ -27,12 +27,12 @@ query. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### queryClient? diff --git a/docs/framework/svelte/reference/functions/useIsMutating.md b/docs/framework/svelte/reference/functions/useIsMutating.md index 3143a8b2dc2..f06099e0f67 100644 --- a/docs/framework/svelte/reference/functions/useIsMutating.md +++ b/docs/framework/svelte/reference/functions/useIsMutating.md @@ -26,10 +26,10 @@ running (useful for app-wide loading indicators). | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### queryClient? diff --git a/docs/framework/svelte/reference/functions/useMutationState.md b/docs/framework/svelte/reference/functions/useMutationState.md index 9c5bb2fd332..34ad2dfab61 100644 --- a/docs/framework/svelte/reference/functions/useMutationState.md +++ b/docs/framework/svelte/reference/functions/useMutationState.md @@ -38,8 +38,8 @@ mutation state. | Property | Type | Description | | ------ | ------ | ------ | -| `filters?` | [`MutationFilters`](../interfaces/MutationFilters.md) | The filters that select the mutations to return the state of. | -| `select?` | (`mutation`: `TMutation`) => `TResult` | Maps each matching mutation to the value returned for it. Defaults to the mutation's `state`. | +| `filters?` | [`MutationFilters`](../interfaces/MutationFilters.md) | The filters that select the mutations to return the state of. | +| `select?` | (`mutation`: `TMutation`) => `TResult` | Maps each matching mutation to the value returned for it. Defaults to the mutation's `state`. | ### queryClient? diff --git a/docs/framework/vue/reference/functions/dehydrate.md b/docs/framework/vue/reference/functions/dehydrate.md index 3b1b8fbe99f..788ac8cb2d0 100644 --- a/docs/framework/vue/reference/functions/dehydrate.md +++ b/docs/framework/vue/reference/functions/dehydrate.md @@ -36,10 +36,10 @@ are transformed. Each option falls back to the client's `defaultOptions.dehydrat | Property | Type | Description | | ------ | ------ | ------ | -| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | -| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | -| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | -| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | +| `serializeData?` | `TransformerFn` | Transforms a query's `data` before it is dehydrated. Useful for non-JSON-serializable data. | +| `shouldDehydrateMutation?` | (`mutation`: [`Mutation`](../classes/Mutation.md)) => `boolean` | Predicate to decide whether a given `Mutation` should be dehydrated. Defaults to `defaultShouldDehydrateMutation`. | +| `shouldDehydrateQuery?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | Predicate to decide whether a given `Query` should be dehydrated. Defaults to `defaultShouldDehydrateQuery`. | +| `shouldRedactErrors?` | (`error`: `unknown`) => `boolean` | Predicate to decide whether a query's error should be redacted before dehydration. Errors are redacted (replaced with a generic `Error('redacted')`) unless this function is provided and returns `false` for the given error, in which case the original error is kept. | ## Returns @@ -53,8 +53,8 @@ The dehydrated state, with the included `queries` and `mutations`. | Property | Type | Description | | ------ | ------ | ------ | -| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | -| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | +| `mutations` | `DehydratedMutation`[] | The dehydrated mutations, by default only the paused ones. | +| `queries` | `DehydratedQuery`[] | The dehydrated queries, by default only the successful ones. | ## Example diff --git a/docs/framework/vue/reference/functions/hydrate.md b/docs/framework/vue/reference/functions/hydrate.md index 17c0afeb896..4c185dd2be1 100644 --- a/docs/framework/vue/reference/functions/hydrate.md +++ b/docs/framework/vue/reference/functions/hydrate.md @@ -53,7 +53,7 @@ client's `defaultOptions.hydrate`), and `deserializeData` to reverse `serializeD | Property | Type | Description | | ------ | ------ | ------ | -| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | +| `defaultOptions?` | `object` | Options applied to the queries and mutations restored from the dehydrated state. | | `defaultOptions.deserializeData?` | `TransformerFn` | Transforms a query's `data` after it is read from the dehydrated state, reversing `serializeData`. | | `defaultOptions.mutations?` | `MutationOptions`\<`unknown`, `Error`, `unknown`, `unknown`\> | Default options merged into every mutation restored from the dehydrated state. | | `defaultOptions.queries?` | `QueryOptions`\<`unknown`, `Error`, `unknown`, readonly `unknown`[], `never`\> | Default options merged into every query restored from the dehydrated state. | diff --git a/docs/framework/vue/reference/functions/matchMutation.md b/docs/framework/vue/reference/functions/matchMutation.md index b12d3b9565c..dcd87d70157 100644 --- a/docs/framework/vue/reference/functions/matchMutation.md +++ b/docs/framework/vue/reference/functions/matchMutation.md @@ -27,10 +27,10 @@ The filters to check the mutation against. | Property | Type | Description | | ------ | ------ | ------ | -| `exact?` | `boolean` | Match mutation key exactly | -| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | -| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | -| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | +| `exact?` | `boolean` | Match mutation key exactly | +| `mutationKey?` | readonly `unknown`[] | Include mutations matching this mutation key | +| `predicate?` | (`mutation`: [`Mutation`](../classes/Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>) => `boolean` | Include mutations matching this predicate function | +| `status?` | `"error"` \| `"pending"` \| `"success"` \| `"idle"` | Filter by mutation status | ### mutation diff --git a/docs/framework/vue/reference/functions/matchQuery.md b/docs/framework/vue/reference/functions/matchQuery.md index e1cdd4ee789..2cc0696220c 100644 --- a/docs/framework/vue/reference/functions/matchQuery.md +++ b/docs/framework/vue/reference/functions/matchQuery.md @@ -26,12 +26,12 @@ The filters to check the query against. | Property | Type | Default value | Description | | ------ | ------ | ------ | ------ | -| `exact?` | `boolean` | `undefined` | Match query key exactly | -| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | -| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | -| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | -| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | -| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | +| `exact?` | `boolean` | `undefined` | Match query key exactly | +| `fetchStatus?` | `"fetching"` \| `"paused"` \| `"idle"` | `undefined` | Include queries matching their fetchStatus | +| `predicate?` | (`query`: [`Query`](../classes/Query.md)) => `boolean` | `undefined` | Include queries matching this predicate function | +| `queryKey?` | `TQueryKey` \| `TuplePrefixes`\<`TQueryKey`\> | `undefined` | Include queries matching this query key | +| `stale?` | `boolean` | `undefined` | Include or exclude stale queries | +| `type?` | `QueryTypeFilter` | `'all'` | Filter to active queries, inactive queries or all queries | ### query diff --git a/docs/framework/vue/reference/functions/mutationOptions.md b/docs/framework/vue/reference/functions/mutationOptions.md index 260418ab939..ef1810ff59e 100644 --- a/docs/framework/vue/reference/functions/mutationOptions.md +++ b/docs/framework/vue/reference/functions/mutationOptions.md @@ -333,10 +333,4 @@ demand. A function that returns the same options object, unchanged. -```ts -(): Omit, "mutationKey">; -``` - -#### Returns - -`Omit`\<[`MutationOptions`](../type-aliases/MutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> +() => `Omit`\<[`MutationOptions`](../type-aliases/MutationOptions.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>, `"mutationKey"`\> diff --git a/docs/framework/vue/reference/functions/queryOptions.md b/docs/framework/vue/reference/functions/queryOptions.md index 37e68a89cd7..e28fbd6c69d 100644 --- a/docs/framework/vue/reference/functions/queryOptions.md +++ b/docs/framework/vue/reference/functions/queryOptions.md @@ -342,10 +342,4 @@ demand. A function that returns the same options object, typed so that `queryKey` carries the inferred data type. -```ts -(): UndefinedInitialQueryOptionsWithDataTag; -``` - -#### Returns - -[`UndefinedInitialQueryOptionsWithDataTag`](../type-aliases/UndefinedInitialQueryOptionsWithDataTag.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> +() => [`UndefinedInitialQueryOptionsWithDataTag`](../type-aliases/UndefinedInitialQueryOptionsWithDataTag.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> diff --git a/docs/framework/vue/reference/functions/useMutationState.md b/docs/framework/vue/reference/functions/useMutationState.md index 261940ef8ce..09d8f0ceb47 100644 --- a/docs/framework/vue/reference/functions/useMutationState.md +++ b/docs/framework/vue/reference/functions/useMutationState.md @@ -40,6 +40,12 @@ themselves depend on other reactive state. The `filters` to narrow down matched mutations, and an optional `select` to transform the mutation state. + + +#### `options` properties + +Built from [`MutationStateOptions`](../type-aliases/MutationStateOptions.md#properties). See the type above for what it changes. + ### queryClient? [`QueryClient`](../classes/QueryClient.md) From b1728df1ccb45d5ad90798eef70e55aa3b8a3aad Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 6 Oct 2026 01:35:06 +0900 Subject: [PATCH 07/12] docs(scripts/generate-docs): label overloads in the overview with their declared parameter and return types --- scripts/generate-docs.ts | 110 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 107 insertions(+), 3 deletions(-) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index 0e6f4abc67a..cc27cb56cdf 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -2,6 +2,7 @@ import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises' import { createRequire } from 'node:module' import { dirname, resolve } from 'node:path' import { fileURLToPath } from 'node:url' +import ts from 'typescript' const __dirname = fileURLToPath(new URL('.', import.meta.url)) const require = createRequire(import.meta.url) @@ -302,6 +303,100 @@ async function typeNameInCode(outputDir: string, code: string) { } } +// The parameter and return types of the declaration a call signature's "Defined in" line points to, as +// written in the source. The rendered code loses aliases that TypeScript flattens into an intersection, +// e.g. `Options & QueryKeyWithDataTag` becomes the members of `Options` followed by the tag. +const sourceFiles = new Map() +async function declaredSignatureTypes(signature: string) { + const location = signature.match(/^Defined in: \[([^\]]+):(\d+)\]/m) + if (!location) { + return undefined + } + const [, file, line] = location + let source = sourceFiles.get(file!) + if (!source) { + const text = await readFile(resolve(__dirname, '..', file!), 'utf8').catch( + () => undefined, + ) + if (text === undefined) { + return undefined + } + source = ts.createSourceFile(file!, text, ts.ScriptTarget.Latest, true) + sourceFiles.set(file!, source) + } + let found: ts.SignatureDeclaration | undefined + const visit = (node: ts.Node) => { + if (found) { + return + } + if ( + ts.isFunctionLike(node) && + 'parameters' in node && + source.getLineAndCharacterOfPosition(node.getStart()).line === + Number(line) - 1 + ) { + found = node + return + } + ts.forEachChild(node, visit) + } + visit(source) + return found && { parameter: found.parameters[0]?.type, returns: found.type } +} + +// Types that only transform their first type argument, so a label keeps that argument to stay +// meaningful, e.g. `Omit` instead of `Omit`. +const typeTransforms = new Set([ + 'Awaited', + 'DistributiveOmit', + 'NonNullable', + 'Omit', + 'OmitKeyof', + 'Partial', + 'Readonly', + 'Required', + 'ReturnType', + 'WithRequired', +]) + +// The label of a declared type: the members of an intersection or union joined, a getter's result, the +// keys of an object type, or the name looked up through the same wrappers as `typeNameInCode`. +async function declaredTypeLabel( + outputDir: string, + node: ts.TypeNode, +): Promise { + if (ts.isParenthesizedTypeNode(node)) { + return declaredTypeLabel(outputDir, node.type) + } + if (ts.isIntersectionTypeNode(node) || ts.isUnionTypeNode(node)) { + const members = await Promise.all( + node.types.map((member) => declaredTypeLabel(outputDir, member)), + ) + return members.every(Boolean) + ? members.join(ts.isIntersectionTypeNode(node) ? ' & ' : ' | ') + : undefined + } + if (ts.isFunctionTypeNode(node) && node.parameters.length === 0) { + const result = await declaredTypeLabel(outputDir, node.type) + return result && `() => ${result}` + } + if (ts.isTypeLiteralNode(node)) { + const keys = node.members + .map((member) => member.name?.getText()) + .filter(Boolean) + return keys.length > 0 ? `{ ${keys.join(', ')} }` : undefined + } + if ( + ts.isTypeReferenceNode(node) && + typeTransforms.has(node.typeName.getText()) && + node.typeArguments?.[0] + ) { + const target = await declaredTypeLabel(outputDir, node.typeArguments[0]) + return target && `${node.typeName.getText()}<${target}>` + } + return typeNameInCode(outputDir, node.getText()) +} + // The property table for the first type line that has one. async function findPropertiesTable( outputDir: string, @@ -673,12 +768,21 @@ async function addReferenceDetails(outputDir: string) { !block.startsWith('```') && !block.startsWith('Defined in:'), ) + const declared = await declaredSignatureTypes(signature) const label = ( await Promise.all( [ - code.match(/\((?:\w+\??): ([\s\S]*)/)?.[1], - code.match(/\): ([\s\S]*)/)?.[1], - ].map((type) => type && typeNameInCode(outputDir, type)), + [ + declared?.parameter, + code.match(/\((?:\w+\??): ([\s\S]*)/)?.[1], + ] as const, + [declared?.returns, code.match(/\): ([\s\S]*)/)?.[1]] as const, + ].map(async ([node, type]) => + node + ? ((await declaredTypeLabel(outputDir, node)) ?? + (type && typeNameInCode(outputDir, type))) + : type && typeNameInCode(outputDir, type), + ), ) ) .filter(Boolean) From 3e6573da19d97d9c1e6d415ad885631d77784ce4 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 6 Oct 2026 01:35:06 +0900 Subject: [PATCH 08/12] docs(framework/*/reference): regenerate reference docs --- .../angular/reference/functions/infiniteQueryOptions.md | 6 +++--- .../angular/reference/functions/injectInfiniteQuery.md | 6 +++--- docs/framework/angular/reference/functions/injectQuery.md | 6 +++--- .../angular/reference/functions/mutationOptions.md | 4 ++-- .../framework/angular/reference/functions/queryOptions.md | 6 +++--- docs/framework/lit/reference/functions/queryOptions.md | 6 +++--- .../preact/reference/functions/infiniteQueryOptions.md | 6 +++--- .../preact/reference/functions/mutationOptions.md | 4 ++-- docs/framework/preact/reference/functions/queryOptions.md | 6 +++--- .../preact/reference/functions/useSuspenseQueries.md | 4 ++-- .../react/reference/functions/infiniteQueryOptions.md | 6 +++--- .../react/reference/functions/mutationOptions.md | 4 ++-- docs/framework/react/reference/functions/queryOptions.md | 6 +++--- .../react/reference/functions/useSuspenseQueries.md | 4 ++-- .../solid/reference/functions/infiniteQueryOptions.md | 4 ++-- .../solid/reference/functions/mutationOptions.md | 4 ++-- docs/framework/solid/reference/functions/queryOptions.md | 4 ++-- .../svelte/reference/functions/infiniteQueryOptions.md | 4 ++-- .../svelte/reference/functions/mutationOptions.md | 4 ++-- docs/framework/svelte/reference/functions/queryOptions.md | 4 ++-- .../vue/reference/functions/infiniteQueryOptions.md | 4 ++-- docs/framework/vue/reference/functions/mutationOptions.md | 8 ++++---- docs/framework/vue/reference/functions/queryOptions.md | 4 ++-- 23 files changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/framework/angular/reference/functions/infiniteQueryOptions.md b/docs/framework/angular/reference/functions/infiniteQueryOptions.md index 99b9c2a64fb..2957d13db51 100644 --- a/docs/framework/angular/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/angular/reference/functions/infiniteQueryOptions.md @@ -11,9 +11,9 @@ function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -- [`DefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenInfiniteOptions` → `UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/angular/reference/functions/injectInfiniteQuery.md b/docs/framework/angular/reference/functions/injectInfiniteQuery.md index 4aa3bca2b9d..9951afce592 100644 --- a/docs/framework/angular/reference/functions/injectInfiniteQuery.md +++ b/docs/framework/angular/reference/functions/injectInfiniteQuery.md @@ -11,9 +11,9 @@ function injectInfiniteQuery function injectInfiniteQuery(injectInfiniteQueryFn: () => CreateInfiniteQueryOptions, options?: InjectInfiniteQueryOptions): CreateInfiniteQueryResult; ``` -- [`DefinedInitialDataInfiniteOptions` → `DefinedCreateInfiniteQueryResult`](#call-signature-1): The options for `injectInfiniteQuery` are identical to `injectQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". -- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryResult`](#call-signature-2): Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". -- [`CreateInfiniteQueryOptions` → `CreateInfiniteQueryResult`](#call-signature-3): This overload accepts the general [CreateInfiniteQueryOptions](../interfaces/CreateInfiniteQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectInfiniteQuery` in your own helper function that forwards caller-provided options. +- [`() => DefinedInitialDataInfiniteOptions` → `DefinedCreateInfiniteQueryResult`](#call-signature-1): The options for `injectInfiniteQuery` are identical to `injectQuery`, with the addition of `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, and `maxPages`. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". +- [`() => UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryResult`](#call-signature-2): Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key. Infinite queries can additively "load more" data onto an existing set of data, or "infinite scroll". +- [`() => CreateInfiniteQueryOptions` → `CreateInfiniteQueryResult`](#call-signature-3): This overload accepts the general [CreateInfiniteQueryOptions](../interfaces/CreateInfiniteQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectInfiniteQuery` in your own helper function that forwards caller-provided options. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/angular/reference/functions/injectQuery.md b/docs/framework/angular/reference/functions/injectQuery.md index c80f125fabd..55523c01258 100644 --- a/docs/framework/angular/reference/functions/injectQuery.md +++ b/docs/framework/angular/reference/functions/injectQuery.md @@ -11,9 +11,9 @@ function injectQuery(injectQueryFn: () = function injectQuery(injectQueryFn: () => CreateQueryOptions, options?: InjectQueryOptions): CreateQueryResult; ``` -- [`DefinedInitialDataOptions` → `DefinedCreateQueryResult`](#call-signature-1): This overload is selected when `initialData` is set on the options returned by `injectQueryFn`, so the resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`). -- [`UndefinedInitialDataOptions` → `CreateQueryResult`](#call-signature-2): Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. -- [`CreateQueryOptions` → `CreateQueryResult`](#call-signature-3): This overload accepts the general [CreateQueryOptions](../interfaces/CreateQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectQuery` in your own helper function that forwards caller-provided options. +- [`() => DefinedInitialDataOptions` → `DefinedCreateQueryResult`](#call-signature-1): This overload is selected when `initialData` is set on the options returned by `injectQueryFn`, so the resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`). +- [`() => UndefinedInitialDataOptions` → `CreateQueryResult`](#call-signature-2): Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key. +- [`() => CreateQueryOptions` → `CreateQueryResult`](#call-signature-3): This overload accepts the general [CreateQueryOptions](../interfaces/CreateQueryOptions.md) shape rather than the `initialData`-aware overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping `injectQuery` in your own helper function that forwards caller-provided options. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/angular/reference/functions/mutationOptions.md b/docs/framework/angular/reference/functions/mutationOptions.md index 8cefaa926a2..f5a75e563ef 100644 --- a/docs/framework/angular/reference/functions/mutationOptions.md +++ b/docs/framework/angular/reference/functions/mutationOptions.md @@ -10,8 +10,8 @@ function mutationOptions(options: Wi function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; ``` -- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `injectMutationState`. -- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other filters, such as `status`. +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `injectMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other filters, such as `status`. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/angular/reference/functions/queryOptions.md b/docs/framework/angular/reference/functions/queryOptions.md index 3b7fbe80fbf..b201688e26b 100644 --- a/docs/framework/angular/reference/functions/queryOptions.md +++ b/docs/framework/angular/reference/functions/queryOptions.md @@ -11,9 +11,9 @@ function queryOptions(options: UnusedSki function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; ``` -- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenOptions` → `UnusedSkipTokenOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `UndefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/lit/reference/functions/queryOptions.md b/docs/framework/lit/reference/functions/queryOptions.md index 33766a7f5ad..1f2fba02eaa 100644 --- a/docs/framework/lit/reference/functions/queryOptions.md +++ b/docs/framework/lit/reference/functions/queryOptions.md @@ -11,9 +11,9 @@ function queryOptions(options: UnusedSki function queryOptions(options: UndefinedInitialDataOptions): QueryObserverOptions & object & object; ``` -- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. -- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. -- [`UndefinedInitialDataOptions` → `QueryObserverOptions`](#call-signature-3): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. +- [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & { queryKey }`](#call-signature-1): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. +- [`UnusedSkipTokenOptions` → `UnusedSkipTokenOptions & { queryKey }`](#call-signature-2): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. +- [`UndefinedInitialDataOptions` → `UndefinedInitialDataOptions & { queryKey }`](#call-signature-3): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md index d52d022d642..2b2289a1c0c 100644 --- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md @@ -11,9 +11,9 @@ function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -- [`DefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenInfiniteOptions` → `UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/preact/reference/functions/mutationOptions.md b/docs/framework/preact/reference/functions/mutationOptions.md index 879cacb7547..843a6e21098 100644 --- a/docs/framework/preact/reference/functions/mutationOptions.md +++ b/docs/framework/preact/reference/functions/mutationOptions.md @@ -10,8 +10,8 @@ function mutationOptions(options: Wi function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; ``` -- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. -- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md index 5614deb0347..27446afd7a6 100644 --- a/docs/framework/preact/reference/functions/queryOptions.md +++ b/docs/framework/preact/reference/functions/queryOptions.md @@ -11,9 +11,9 @@ function queryOptions(options: UnusedSki function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; ``` -- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataOptions` → `UseQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenOptions` → `UnusedSkipTokenOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `UndefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/preact/reference/functions/useSuspenseQueries.md b/docs/framework/preact/reference/functions/useSuspenseQueries.md index a6145098d9b..ecfb8b96537 100644 --- a/docs/framework/preact/reference/functions/useSuspenseQueries.md +++ b/docs/framework/preact/reference/functions/useSuspenseQueries.md @@ -10,8 +10,8 @@ function useSuspenseQueries(options: object, queryClient?: Q function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -- [`object` → `TCombinedResult`](#call-signature-1): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. -- [`object` → `TCombinedResult`](#call-signature-2): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. +- [`{ queries, combine }` → `TCombinedResult`](#call-signature-1): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. +- [`{ queries, combine }` → `TCombinedResult`](#call-signature-2): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/react/reference/functions/infiniteQueryOptions.md b/docs/framework/react/reference/functions/infiniteQueryOptions.md index 4fe2117edfc..417ba6f142f 100644 --- a/docs/framework/react/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/react/reference/functions/infiniteQueryOptions.md @@ -13,9 +13,9 @@ function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -- [`DefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenInfiniteOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataInfiniteOptions` → `UseInfiniteQueryOptions`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenInfiniteOptions` → `UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/react/reference/functions/mutationOptions.md b/docs/framework/react/reference/functions/mutationOptions.md index 431b3b78c5a..e10807d0b46 100644 --- a/docs/framework/react/reference/functions/mutationOptions.md +++ b/docs/framework/react/reference/functions/mutationOptions.md @@ -12,8 +12,8 @@ function mutationOptions(options: Wi function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; ``` -- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. -- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/react/reference/functions/queryOptions.md b/docs/framework/react/reference/functions/queryOptions.md index f6982db9d38..ebfc7fa40aa 100644 --- a/docs/framework/react/reference/functions/queryOptions.md +++ b/docs/framework/react/reference/functions/queryOptions.md @@ -13,9 +13,9 @@ function queryOptions(options: UnusedSki function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; ``` -- [`DefinedInitialDataOptions` → `Omit`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`UnusedSkipTokenOptions` → `OmitKeyof`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataOptions` → `UseQueryOptions`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UnusedSkipTokenOptions` → `UnusedSkipTokenOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `UndefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/react/reference/functions/useSuspenseQueries.md b/docs/framework/react/reference/functions/useSuspenseQueries.md index 1eba82cbf21..82b9e2488ab 100644 --- a/docs/framework/react/reference/functions/useSuspenseQueries.md +++ b/docs/framework/react/reference/functions/useSuspenseQueries.md @@ -12,8 +12,8 @@ function useSuspenseQueries(options: object, queryClient?: Q function useSuspenseQueries(options: object, queryClient?: QueryClient): TCombinedResult; ``` -- [`object` → `TCombinedResult`](#call-signature-1): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. -- [`object` → `TCombinedResult`](#call-signature-2): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. +- [`{ queries, combine }` → `TCombinedResult`](#call-signature-1): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. +- [`{ queries, combine }` → `TCombinedResult`](#call-signature-2): The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/solid/reference/functions/infiniteQueryOptions.md b/docs/framework/solid/reference/functions/infiniteQueryOptions.md index f111739cb66..00661d29055 100644 --- a/docs/framework/solid/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/solid/reference/functions/infiniteQueryOptions.md @@ -12,8 +12,8 @@ function infiniteQueryOptions(options: InfiniteQueryOptions & object): InfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -- [`InfiniteQueryOptions` → `InfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`InfiniteQueryOptions` → `InfiniteQueryOptions`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`ReturnType` → `ReturnType & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`ReturnType` → `ReturnType & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/solid/reference/functions/mutationOptions.md b/docs/framework/solid/reference/functions/mutationOptions.md index 55506522aaa..d8ec359ca7f 100644 --- a/docs/framework/solid/reference/functions/mutationOptions.md +++ b/docs/framework/solid/reference/functions/mutationOptions.md @@ -12,8 +12,8 @@ function mutationOptions(options: Wi function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; ``` -- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. -- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/solid/reference/functions/queryOptions.md b/docs/framework/solid/reference/functions/queryOptions.md index 6e69bc1e856..4154ca1eddf 100644 --- a/docs/framework/solid/reference/functions/queryOptions.md +++ b/docs/framework/solid/reference/functions/queryOptions.md @@ -12,8 +12,8 @@ function queryOptions(options: QueryOpti function queryOptions(options: QueryOptions & object): QueryOptions & object & QueryKeyWithDataTag; ``` -- [`QueryOptions` → `QueryOptions`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`QueryOptions` → `QueryOptions`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`ReturnType` → `ReturnType & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`ReturnType` → `ReturnType & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md index fc5bf1d348f..1d96abf8032 100644 --- a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md @@ -10,8 +10,8 @@ function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; ``` -- [`DefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`. These options can be shared across `createInfiniteQuery` calls and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataInfiniteOptions` → `CreateInfiniteQueryOptions`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`. These options can be shared across `createInfiniteQuery` calls and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`. These options can be shared across `createInfiniteQuery` calls and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`. These options can be shared across `createInfiniteQuery` calls and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/svelte/reference/functions/mutationOptions.md b/docs/framework/svelte/reference/functions/mutationOptions.md index e8ccc3b1a99..e98ef02e89a 100644 --- a/docs/framework/svelte/reference/functions/mutationOptions.md +++ b/docs/framework/svelte/reference/functions/mutationOptions.md @@ -10,8 +10,8 @@ function mutationOptions(options: Wi function mutationOptions(options: Omit, "mutationKey">): Omit, "mutationKey">; ``` -- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`. This overload requires `mutationKey`, so the resulting options can be looked up elsewhere (e.g. with `useMutationState`). -- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`. +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`. This overload requires `mutationKey`, so the resulting options can be looked up elsewhere (e.g. with `useMutationState`). +- [`Omit` → `Omit`](#call-signature-2): You can generally pass everything to `mutationOptions` that you can also pass to `createMutation`. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/svelte/reference/functions/queryOptions.md b/docs/framework/svelte/reference/functions/queryOptions.md index ad3b8a0cc07..ff48cb280eb 100644 --- a/docs/framework/svelte/reference/functions/queryOptions.md +++ b/docs/framework/svelte/reference/functions/queryOptions.md @@ -10,8 +10,8 @@ function queryOptions(options: DefinedIn function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; ``` -- [`DefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialDataOptions` → `CreateQueryOptions`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataOptions` → `UndefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/vue/reference/functions/infiniteQueryOptions.md b/docs/framework/vue/reference/functions/infiniteQueryOptions.md index 10808085a95..6e405570fe5 100644 --- a/docs/framework/vue/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/vue/reference/functions/infiniteQueryOptions.md @@ -12,8 +12,8 @@ function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` -- [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. -- [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. +- [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/vue/reference/functions/mutationOptions.md b/docs/framework/vue/reference/functions/mutationOptions.md index ef1810ff59e..a47564e0475 100644 --- a/docs/framework/vue/reference/functions/mutationOptions.md +++ b/docs/framework/vue/reference/functions/mutationOptions.md @@ -14,10 +14,10 @@ function mutationOptions(options: Om function mutationOptions(options: () => Omit, "mutationKey">): () => Omit, "mutationKey">; ``` -- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. -- [`WithRequired` → `WithRequired`](#call-signature-2): Same as the plain-object overload with a required `mutationKey`, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `useMutation` and the other consumers always read the current values instead of the ones captured when the options were created. -- [`Omit` → `Omit`](#call-signature-3): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. -- [`Omit` → `Omit`](#call-signature-4): Same as the plain-object overload without a `mutationKey`, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `useMutation` and the other consumers always read the current values instead of the ones captured when the options were created. +- [`WithRequired` → `WithRequired`](#call-signature-1): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. A `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with `useMutationState`. +- [`() => WithRequired` → `() => WithRequired`](#call-signature-2): Same as the plain-object overload with a required `mutationKey`, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `useMutation` and the other consumers always read the current values instead of the ones captured when the options were created. +- [`Omit` → `Omit`](#call-signature-3): You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No `mutationKey` is required on this overload — use this when you don't need to target the mutation via a `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters, such as `status`. +- [`() => Omit` → `() => Omit`](#call-signature-4): Same as the plain-object overload without a `mutationKey`, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `useMutation` and the other consumers always read the current values instead of the ones captured when the options were created. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) diff --git a/docs/framework/vue/reference/functions/queryOptions.md b/docs/framework/vue/reference/functions/queryOptions.md index e28fbd6c69d..4b32c2e726c 100644 --- a/docs/framework/vue/reference/functions/queryOptions.md +++ b/docs/framework/vue/reference/functions/queryOptions.md @@ -15,9 +15,9 @@ function queryOptions(options: () => Und ``` - [`DefinedInitialQueryOptions` → `DefinedInitialQueryOptionsWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`DefinedInitialQueryOptions` → `DefinedInitialQueryOptionsWithDataTag`](#call-signature-2): Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `queryClient` methods like `invalidateQueries`/`fetchQuery` always read the current values instead of the ones captured when the options were created. +- [`() => DefinedInitialQueryOptions` → `() => DefinedInitialQueryOptionsWithDataTag`](#call-signature-2): Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so `queryClient` methods like `invalidateQueries`/`fetchQuery` always read the current values instead of the ones captured when the options were created. - [`UndefinedInitialQueryOptions` → `UndefinedInitialQueryOptionsWithDataTag`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. -- [`UndefinedInitialQueryOptions` → `UndefinedInitialQueryOptionsWithDataTag`](#call-signature-4): Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so the `queryKey` — and anything else derived from a `ref` — reacts to changes, and so `queryClient` methods like `invalidateQueries`/`fetchQuery` always read the current values instead of the ones captured when the options were created. +- [`() => UndefinedInitialQueryOptions` → `() => UndefinedInitialQueryOptionsWithDataTag`](#call-signature-4): Same as the plain-object overload, but for options that close over reactive state (`ref`s read inside the function body). Wrap them in a getter so the `queryKey` — and anything else derived from a `ref` — reacts to changes, and so `queryClient` methods like `invalidateQueries`/`fetchQuery` always read the current values instead of the ones captured when the options were created. See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) From 8bda83aeade21d062f9938b1ec8d687c0f469127 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 6 Oct 2026 01:40:37 +0900 Subject: [PATCH 09/12] docs(scripts/generate-docs): convert declared intersection types from the source so signatures keep their alias names --- scripts/generate-docs.ts | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index cc27cb56cdf..da202f00af3 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -182,6 +182,36 @@ async function generatePackageReferenceDocs(pkg: PackageReferenceDocsConfig) { out: outputDir, }) + // TypeScript flattens an alias out of an intersection, so `Options & QueryKeyWithDataTag` + // would render as the members of `Options` followed by the tag. Convert declared intersections from + // the source instead, so signatures keep the alias names they were written with. + app.converter.on( + TypeDoc.Converter.EVENT_CREATE_SIGNATURE, + ( + context: InstanceType, + signature: InstanceType, + declaration?: ts.Node, + ) => { + if (!declaration || !ts.isFunctionLike(declaration)) { + return + } + const scope = context.withScope(signature) + if (declaration.type && ts.isIntersectionTypeNode(declaration.type)) { + signature.type = scope.converter.convertType(scope, declaration.type) + } + declaration.parameters.forEach((parameter, index) => { + const reflection = signature.parameters?.[index] + if ( + reflection && + parameter.type && + ts.isIntersectionTypeNode(parameter.type) + ) { + reflection.type = scope.converter.convertType(scope, parameter.type) + } + }) + }, + ) + const project = await app.convert() // `outputDir` was emptied above, so a failed conversion would otherwise leave it that way and From 20a74d9e314bbb6fa49102efeeee9d343707ab18 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 6 Oct 2026 01:40:37 +0900 Subject: [PATCH 10/12] docs(framework/*/reference): regenerate reference docs --- .../functions/infiniteQueryOptions.md | 26 ++++++++++++++----- .../reference/functions/queryOptions.md | 26 ++++++++++++++----- .../lit/reference/functions/queryOptions.md | 20 +++++++------- .../functions/infiniteQueryOptions.md | 26 ++++++++++++++----- .../reference/functions/queryOptions.md | 26 ++++++++++++++----- .../functions/infiniteQueryOptions.md | 26 ++++++++++++++----- .../react/reference/functions/queryOptions.md | 26 ++++++++++++++----- .../functions/infiniteQueryOptions.md | 14 +++++----- .../solid/reference/functions/queryOptions.md | 14 +++++----- .../functions/infiniteQueryOptions.md | 14 +++++----- .../reference/functions/queryOptions.md | 14 +++++----- .../functions/infiniteQueryOptions.md | 14 +++++----- 12 files changed, 165 insertions(+), 81 deletions(-) diff --git a/docs/framework/angular/reference/functions/infiniteQueryOptions.md b/docs/framework/angular/reference/functions/infiniteQueryOptions.md index 2957d13db51..465d11e1f2e 100644 --- a/docs/framework/angular/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/angular/reference/functions/infiniteQueryOptions.md @@ -6,9 +6,9 @@ title: infiniteQueryOptions ## Overview ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` - [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `injectInfiniteQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchInfiniteQuery`. `options.queryKey` is required and is the query key to generate options for. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:176](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L176) @@ -67,6 +67,8 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini ### Returns +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -115,7 +117,7 @@ export class Projects { ## Call Signature ```ts -function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:247](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L247) @@ -158,6 +160,8 @@ The [UnusedSkipTokenInfiniteOptions](../type-aliases/UnusedSkipTokenInfiniteOpti ### Returns +[`UnusedSkipTokenInfiniteOptions`](../type-aliases/UnusedSkipTokenInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -212,7 +216,7 @@ export class Comments { ## Call Signature ```ts -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/angular-query-experimental/src/infinite-query-options.ts:318](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/infinite-query-options.ts#L318) @@ -255,6 +259,8 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn ### Returns +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -325,4 +331,12 @@ Built from [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptio ## Returns +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`CreateInfiniteQueryOptions`](../interfaces/CreateInfiniteQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/angular/reference/functions/queryOptions.md b/docs/framework/angular/reference/functions/queryOptions.md index b201688e26b..203a629670a 100644 --- a/docs/framework/angular/reference/functions/queryOptions.md +++ b/docs/framework/angular/reference/functions/queryOptions.md @@ -6,9 +6,9 @@ title: queryOptions ## Overview ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` - [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/angular-query-experimental/src/query-options.ts:145](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/query-options.ts#L145) @@ -63,6 +63,8 @@ with `initialData` set. ### Returns +[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### See @@ -106,7 +108,7 @@ export class Posts { ## Call Signature ```ts -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; ``` Defined in: [packages/angular-query-experimental/src/query-options.ts:192](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/query-options.ts#L192) @@ -143,6 +145,8 @@ The [UnusedSkipTokenOptions](../type-aliases/UnusedSkipTokenOptions.md) to use ### Returns +[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### See @@ -185,7 +189,7 @@ export class Post { ## Call Signature ```ts -function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/angular-query-experimental/src/query-options.ts:270](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/query-options.ts#L270) @@ -222,6 +226,8 @@ The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md ### Returns +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -313,4 +319,12 @@ Built from [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md#properties ## Returns +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/lit/reference/functions/queryOptions.md b/docs/framework/lit/reference/functions/queryOptions.md index 1f2fba02eaa..0cd474924d8 100644 --- a/docs/framework/lit/reference/functions/queryOptions.md +++ b/docs/framework/lit/reference/functions/queryOptions.md @@ -6,9 +6,9 @@ title: queryOptions ## Overview ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & object; -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & object; -function queryOptions(options: UndefinedInitialDataOptions): QueryObserverOptions & object & object; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & object; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & object; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & object; ``` - [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & { queryKey }`](#call-signature-1): Brands query options so the `queryKey` carries the query function data and error types across TanStack Query APIs. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & object; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & object; ``` Defined in: [packages/lit-query/src/queryOptions.ts:91](https://github.com/TanStack/query/blob/main/packages/lit-query/src/queryOptions.ts#L91) @@ -58,7 +58,7 @@ Query options to preserve and brand. ### Returns -`Omit`\<[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`, `never`\>, `"queryFn"`\> & `object` & `object` +[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` The same options object with a typed `queryKey`. @@ -79,7 +79,7 @@ const todosOptions = queryOptions({ ## Call Signature ```ts -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & object; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & object; ``` Defined in: [packages/lit-query/src/queryOptions.ts:108](https://github.com/TanStack/query/blob/main/packages/lit-query/src/queryOptions.ts#L108) @@ -115,7 +115,7 @@ Query options to preserve and brand. ### Returns -[`OmitKeyof`](../type-aliases/OmitKeyof.md)\<[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`, `never`\>, `"queryFn"`\> & `object` & `object` +[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` The same options object with a typed `queryKey`. @@ -124,7 +124,7 @@ The same options object with a typed `queryKey`. ## Call Signature ```ts -function queryOptions(options: UndefinedInitialDataOptions): QueryObserverOptions & object & object; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & object; ``` Defined in: [packages/lit-query/src/queryOptions.ts:125](https://github.com/TanStack/query/blob/main/packages/lit-query/src/queryOptions.ts#L125) @@ -160,7 +160,7 @@ Query options to preserve and brand. ### Returns -[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`, `never`\> & `object` & `object` +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` The same options object with a typed `queryKey`. @@ -184,7 +184,7 @@ Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#proper ## Returns -[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryFnData`, `TQueryKey`, `never`\> & `object` & `object` +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` The same options object with a typed `queryKey`. diff --git a/docs/framework/preact/reference/functions/infiniteQueryOptions.md b/docs/framework/preact/reference/functions/infiniteQueryOptions.md index 2b2289a1c0c..4e6d70a579c 100644 --- a/docs/framework/preact/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/preact/reference/functions/infiniteQueryOptions.md @@ -6,9 +6,9 @@ title: infiniteQueryOptions ## Overview ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` - [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:166](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L166) @@ -65,6 +65,8 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini ### Returns +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -110,7 +112,7 @@ function Projects() { ## Call Signature ```ts -function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:225](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L225) @@ -151,6 +153,8 @@ The [UnusedSkipTokenInfiniteOptions](../type-aliases/UnusedSkipTokenInfiniteOpti ### Returns +[`UnusedSkipTokenInfiniteOptions`](../type-aliases/UnusedSkipTokenInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -195,7 +199,7 @@ function Comments({ postId }: { postId: string }) { ## Call Signature ```ts -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/preact-query/src/infiniteQueryOptions.ts:284](https://github.com/TanStack/query/blob/main/packages/preact-query/src/infiniteQueryOptions.ts#L284) @@ -236,6 +240,8 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn ### Returns +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -295,4 +301,12 @@ Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md# ## Returns +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/preact/reference/functions/queryOptions.md b/docs/framework/preact/reference/functions/queryOptions.md index 27446afd7a6..a6845bbc7b1 100644 --- a/docs/framework/preact/reference/functions/queryOptions.md +++ b/docs/framework/preact/reference/functions/queryOptions.md @@ -6,9 +6,9 @@ title: queryOptions ## Overview ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` - [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/preact-query/src/queryOptions.ts:138](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L138) @@ -62,6 +62,8 @@ The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to ### Returns +[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### See @@ -101,7 +103,7 @@ function Posts() { ## Call Signature ```ts -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; ``` Defined in: [packages/preact-query/src/queryOptions.ts:177](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L177) @@ -138,6 +140,8 @@ The [UnusedSkipTokenOptions](../type-aliases/UnusedSkipTokenOptions.md) to use ### Returns +[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### See @@ -172,7 +176,7 @@ function Post({ id }: { id: string }) { ## Call Signature ```ts -function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/preact-query/src/queryOptions.ts:238](https://github.com/TanStack/query/blob/main/packages/preact-query/src/queryOptions.ts#L238) @@ -209,6 +213,8 @@ The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md ### Returns +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -283,4 +289,12 @@ Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties). See ## Returns +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/react/reference/functions/infiniteQueryOptions.md b/docs/framework/react/reference/functions/infiniteQueryOptions.md index 417ba6f142f..5a3681ee287 100644 --- a/docs/framework/react/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/react/reference/functions/infiniteQueryOptions.md @@ -8,9 +8,9 @@ redirect_from: ## Overview ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` - [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. @@ -24,7 +24,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/react-query/src/infiniteQueryOptions.ts:165](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L165) @@ -67,6 +67,8 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini ### Returns +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -112,7 +114,7 @@ function Projects() { ## Call Signature ```ts -function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UnusedSkipTokenInfiniteOptions): UnusedSkipTokenInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/react-query/src/infiniteQueryOptions.ts:224](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L224) @@ -153,6 +155,8 @@ The [UnusedSkipTokenInfiniteOptions](../type-aliases/UnusedSkipTokenInfiniteOpti ### Returns +[`UnusedSkipTokenInfiniteOptions`](../type-aliases/UnusedSkipTokenInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -197,7 +201,7 @@ function Comments({ postId }: { postId: string }) { ## Call Signature ```ts -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UseInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/react-query/src/infiniteQueryOptions.ts:283](https://github.com/TanStack/query/blob/main/packages/react-query/src/infiniteQueryOptions.ts#L283) @@ -238,6 +242,8 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn ### Returns +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -297,4 +303,12 @@ Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md# ## Returns +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`UseInfiniteQueryOptions`](../interfaces/UseInfiniteQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/react/reference/functions/queryOptions.md b/docs/framework/react/reference/functions/queryOptions.md index ebfc7fa40aa..1630e4f4d32 100644 --- a/docs/framework/react/reference/functions/queryOptions.md +++ b/docs/framework/react/reference/functions/queryOptions.md @@ -8,9 +8,9 @@ redirect_from: ## Overview ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; -function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` - [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. @@ -24,7 +24,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function queryOptions(options: DefinedInitialDataOptions): Omit, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/react-query/src/queryOptions.ts:137](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L137) @@ -64,6 +64,8 @@ The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to ### Returns +[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### See @@ -103,7 +105,7 @@ function Posts() { ## Call Signature ```ts -function queryOptions(options: UnusedSkipTokenOptions): OmitKeyof, "queryFn"> & object & QueryKeyWithDataTag; +function queryOptions(options: UnusedSkipTokenOptions): UnusedSkipTokenOptions & QueryKeyWithDataTag; ``` Defined in: [packages/react-query/src/queryOptions.ts:176](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L176) @@ -140,6 +142,8 @@ The [UnusedSkipTokenOptions](../type-aliases/UnusedSkipTokenOptions.md) to use ### Returns +[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### See @@ -174,7 +178,7 @@ function Post({ id }: { id: string }) { ## Call Signature ```ts -function queryOptions(options: UndefinedInitialDataOptions): UseQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/react-query/src/queryOptions.ts:237](https://github.com/TanStack/query/blob/main/packages/react-query/src/queryOptions.ts#L237) @@ -211,6 +215,8 @@ The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md ### Returns +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. ### Remarks @@ -285,4 +291,12 @@ Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties). See ## Returns +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> + The same options object, typed so that `queryKey` carries the inferred data type. + + + +### Result properties + +Built from [`UseQueryOptions`](../interfaces/UseQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes. diff --git a/docs/framework/solid/reference/functions/infiniteQueryOptions.md b/docs/framework/solid/reference/functions/infiniteQueryOptions.md index 00661d29055..d43272ac85c 100644 --- a/docs/framework/solid/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/solid/reference/functions/infiniteQueryOptions.md @@ -8,8 +8,8 @@ redirect_from: ## Overview ```ts -function infiniteQueryOptions(options: InfiniteQueryOptions & object): InfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: InfiniteQueryOptions & object): InfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: InfiniteQueryOptions & object): ReturnType> & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: InfiniteQueryOptions & object): ReturnType> & QueryKeyWithDataTag, TError>; ``` - [`ReturnType` → `ReturnType & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function infiniteQueryOptions(options: InfiniteQueryOptions & object): InfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: InfiniteQueryOptions & object): ReturnType> & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/solid-query/src/infiniteQueryOptions.ts:101](https://github.com/TanStack/query/blob/main/packages/solid-query/src/infiniteQueryOptions.ts#L101) @@ -65,7 +65,7 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini ### Returns -[`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +`ReturnType`\<[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -110,7 +110,7 @@ function Projects() { ## Call Signature ```ts -function infiniteQueryOptions(options: InfiniteQueryOptions & object): InfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: InfiniteQueryOptions & object): ReturnType> & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/solid-query/src/infiniteQueryOptions.ts:168](https://github.com/TanStack/query/blob/main/packages/solid-query/src/infiniteQueryOptions.ts#L168) @@ -151,7 +151,7 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn ### Returns -[`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +`ReturnType`\<[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -213,7 +213,7 @@ Built from [`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md#proper ## Returns -[`InfiniteQueryOptions`](../interfaces/InfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +`ReturnType`\<[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\>\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/solid/reference/functions/queryOptions.md b/docs/framework/solid/reference/functions/queryOptions.md index 4154ca1eddf..841d1885a52 100644 --- a/docs/framework/solid/reference/functions/queryOptions.md +++ b/docs/framework/solid/reference/functions/queryOptions.md @@ -8,8 +8,8 @@ redirect_from: ## Overview ```ts -function queryOptions(options: QueryOptions & object): QueryOptions & object & QueryKeyWithDataTag; -function queryOptions(options: QueryOptions & object): QueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: QueryOptions & object): ReturnType> & QueryKeyWithDataTag; +function queryOptions(options: QueryOptions & object): ReturnType> & QueryKeyWithDataTag; ``` - [`ReturnType` → `ReturnType & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `useQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function queryOptions(options: QueryOptions & object): QueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: QueryOptions & object): ReturnType> & QueryKeyWithDataTag; ``` Defined in: [packages/solid-query/src/queryOptions.ts:86](https://github.com/TanStack/query/blob/main/packages/solid-query/src/queryOptions.ts#L86) @@ -62,7 +62,7 @@ The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to ### Returns -[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> +`ReturnType`\<[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -103,7 +103,7 @@ function Posts() { ## Call Signature ```ts -function queryOptions(options: QueryOptions & object): QueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: QueryOptions & object): ReturnType> & QueryKeyWithDataTag; ``` Defined in: [packages/solid-query/src/queryOptions.ts:134](https://github.com/TanStack/query/blob/main/packages/solid-query/src/queryOptions.ts#L134) @@ -140,7 +140,7 @@ The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md ### Returns -[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> +`ReturnType`\<[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -196,7 +196,7 @@ Built from [`QueryOptions`](../interfaces/QueryOptions.md#properties). See the t ## Returns -[`QueryOptions`](../interfaces/QueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> +`ReturnType`\<[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md index 1d96abf8032..4ab5f3a1ae3 100644 --- a/docs/framework/svelte/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/svelte/reference/functions/infiniteQueryOptions.md @@ -6,8 +6,8 @@ title: infiniteQueryOptions ## Overview ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` - [`DefinedInitialDataInfiniteOptions` → `DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `createInfiniteQuery`. These options can be shared across `createInfiniteQuery` calls and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. @@ -20,7 +20,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/svelte-query/src/infiniteQueryOptions.ts:98](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/infiniteQueryOptions.ts#L98) @@ -64,7 +64,7 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini ### Returns -[`CreateInfiniteQueryOptions`](../type-aliases/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -108,7 +108,7 @@ visible alongside the error: ## Call Signature ```ts -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): CreateInfiniteQueryOptions & object & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/svelte-query/src/infiniteQueryOptions.ts:163](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/infiniteQueryOptions.ts#L163) @@ -150,7 +150,7 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn ### Returns -[`CreateInfiniteQueryOptions`](../type-aliases/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -214,7 +214,7 @@ Built from [`InfiniteQueryObserverOptions`](../interfaces/InfiniteQueryObserverO ## Returns -[`CreateInfiniteQueryOptions`](../type-aliases/CreateInfiniteQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/svelte/reference/functions/queryOptions.md b/docs/framework/svelte/reference/functions/queryOptions.md index ff48cb280eb..66a4f7e1688 100644 --- a/docs/framework/svelte/reference/functions/queryOptions.md +++ b/docs/framework/svelte/reference/functions/queryOptions.md @@ -6,8 +6,8 @@ title: queryOptions ## Overview ```ts -function queryOptions(options: DefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; -function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` - [`DefinedInitialDataOptions` → `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `createQuery`. These options can be shared across `createQuery` calls and imperative APIs such as `queryClient.query`. `options.queryKey` is required and is the query key to generate options for. @@ -20,7 +20,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function queryOptions(options: DefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: DefinedInitialDataOptions): DefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/svelte-query/src/queryOptions.ts:77](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/queryOptions.ts#L77) @@ -61,7 +61,7 @@ with `initialData` set. ### Returns -[`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> +[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -101,7 +101,7 @@ The same options object, typed so that `queryKey` carries the inferred data type ## Call Signature ```ts -function queryOptions(options: UndefinedInitialDataOptions): CreateQueryOptions & object & QueryKeyWithDataTag; +function queryOptions(options: UndefinedInitialDataOptions): UndefinedInitialDataOptions & QueryKeyWithDataTag; ``` Defined in: [packages/svelte-query/src/queryOptions.ts:120](https://github.com/TanStack/query/blob/main/packages/svelte-query/src/queryOptions.ts#L120) @@ -138,7 +138,7 @@ The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md ### Returns -[`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -193,7 +193,7 @@ Built from [`QueryObserverOptions`](../interfaces/QueryObserverOptions.md#proper ## Returns -[`CreateQueryOptions`](../type-aliases/CreateQueryOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & `object` & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> +[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. diff --git a/docs/framework/vue/reference/functions/infiniteQueryOptions.md b/docs/framework/vue/reference/functions/infiniteQueryOptions.md index 6e405570fe5..0a1792f8a59 100644 --- a/docs/framework/vue/reference/functions/infiniteQueryOptions.md +++ b/docs/framework/vue/reference/functions/infiniteQueryOptions.md @@ -8,8 +8,8 @@ redirect_from: ## Overview ```ts -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` - [`UndefinedInitialDataInfiniteOptions` → `UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `infiniteQueryOptions` that you can also pass to `useInfiniteQuery`. These options can be shared across hooks and imperative APIs such as `queryClient.infiniteQuery`. `options.queryKey` is required and is the query key to generate options for. @@ -22,7 +22,7 @@ See also: [Parameters](#parameters-summary) · [Returns](#returns-summary) ## Call Signature ```ts -function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: UndefinedInitialDataInfiniteOptions): UndefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/vue-query/src/infiniteQueryOptions.ts:95](https://github.com/TanStack/query/blob/main/packages/vue-query/src/infiniteQueryOptions.ts#L95) @@ -64,7 +64,7 @@ The [UndefinedInitialDataInfiniteOptions](../type-aliases/UndefinedInitialDataIn ### Returns -[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +[`UndefinedInitialDataInfiniteOptions`](../type-aliases/UndefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -94,7 +94,7 @@ const { data, isError, error, fetchNextPage } = useInfiniteQuery(projectsOptions ## Call Signature ```ts -function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; +function infiniteQueryOptions(options: DefinedInitialDataInfiniteOptions): DefinedInitialDataInfiniteOptions & QueryKeyWithDataTag, TError>; ``` Defined in: [packages/vue-query/src/infiniteQueryOptions.ts:148](https://github.com/TanStack/query/blob/main/packages/vue-query/src/infiniteQueryOptions.ts#L148) @@ -139,7 +139,7 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini ### Returns -[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. @@ -182,6 +182,6 @@ The [DefinedInitialDataInfiniteOptions](../type-aliases/DefinedInitialDataInfini ## Returns -[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`, `unknown`\>, `TError`\> +[`DefinedInitialDataInfiniteOptions`](../type-aliases/DefinedInitialDataInfiniteOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `TPageParam`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, [`InfiniteData`](../interfaces/InfiniteData.md)\<`TQueryFnData`\>, `TError`\> The same options object, typed so that `queryKey` carries the inferred data type. From 11a16097726f8b0f81c3ff60e797d43ad11377f2 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 6 Oct 2026 01:46:28 +0900 Subject: [PATCH 11/12] docs(scripts/generate-docs): reword a comment to avoid the unknown word 'inlines' --- scripts/generate-docs.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index da202f00af3..fe4594b6ae6 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -156,7 +156,7 @@ async function generatePackageReferenceDocs(pkg: PackageReferenceDocsConfig) { hidePageTitle: true, useCodeBlocks: true, // `parametersFormat` and `typeDeclarationFormat` are deliberately left as lists: the first - // inlines the huge conditional types of `useQueries` into a single cell and drops `@default` + // puts the huge conditional types of `useQueries` into a single cell and drops `@default` // blocks, and the second collapses `@example` code blocks onto one line, which swallows the // following statement into a `//` comment. interfacePropertiesFormat: 'table', From 31407b2205508f87b312b3d888cefdd364776df9 Mon Sep 17 00:00:00 2001 From: Wonsuk Choi Date: Tue, 6 Oct 2026 01:46:28 +0900 Subject: [PATCH 12/12] docs(scripts/generate-docs): skip a parameter table on overloaded pages when its heading is missing --- scripts/generate-docs.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts index fe4594b6ae6..a785356adf5 100644 --- a/scripts/generate-docs.ts +++ b/scripts/generate-docs.ts @@ -833,6 +833,9 @@ async function addReferenceDetails(outputDir: string) { for (const entry of tables.filter((table) => table.parameter)) { const heading = `\n### ${entry.parameter}\n` const start = parametersSummary.indexOf(heading) + if (start === -1) { + continue + } const next = parametersSummary .slice(start + heading.length) .search(/\n#{1,3} /)