diff --git a/packages/query-core/src/types.ts b/packages/query-core/src/types.ts index 648fbaaeb5..82c4efc629 100644 --- a/packages/query-core/src/types.ts +++ b/packages/query-core/src/types.ts @@ -500,35 +500,124 @@ export interface QueryObserverBaseResult< TData = unknown, TError = DefaultError, > { + /** + * The last successfully resolved data for the query. + * - Defaults to `undefined`. + */ data: TData | undefined + /** + * The timestamp for when the query most recently returned the `status` as `"success"`. + */ dataUpdatedAt: number + /** + * The error object for the query, if an error was thrown. + * - Defaults to `null`. + */ error: TError | null + /** + * The timestamp for when the query most recently returned the `status` as `"error"`. + */ errorUpdatedAt: number + /** + * The failure count for the query. + * - Incremented every time the query fails. + * - Reset to `0` when the query succeeds. + */ failureCount: number + /** + * The failure reason for the query retry. + * - Reset to `null` when the query succeeds. + */ failureReason: TError | null + /** + * The sum of all errors. + */ errorUpdateCount: number + /** + * A derived boolean from the `status` variable, provided for convenience. + * - `true` if the query attempt resulted in an error. + */ isError: boolean + /** + * Will be `true` if the query has been fetched. + */ isFetched: 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. + */ isFetchedAfterMount: 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. + */ isFetching: boolean + /** + * Is `true` whenever the first fetch for a query is in-flight. + * - Is the same as `isFetching && isPending`. + */ isLoading: boolean + /** + * Will be `pending` if there's no cached data and no query attempt was finished yet. + */ isPending: boolean + /** + * Will be `true` if the query failed while fetching for the first time. + */ isLoadingError: boolean /** - * @deprecated isInitialLoading is being deprecated in favor of isLoading + * @deprecated `isInitialLoading` is being deprecated in favor of `isLoading` * and will be removed in the next major version. */ isInitialLoading: boolean + /** + * A derived boolean from the `fetchStatus` variable, provided for convenience. + * - The query wanted to fetch, but has been `paused`. + */ isPaused: boolean + /** + * Will be `true` if the data shown is the placeholder data. + */ isPlaceholderData: boolean + /** + * Will be `true` if the query failed while refetching. + */ isRefetchError: boolean + /** + * Is `true` whenever a background refetch is in-flight, which _does not_ include initial `pending`. + * - Is the same as `isFetching && !isPending`. + */ isRefetching: boolean + /** + * Will be `true` if the data in the cache is invalidated or if the data is older than the given `staleTime`. + */ isStale: 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. + */ isSuccess: boolean + /** + * A function to manually refetch the query. + */ refetch: ( options?: RefetchOptions, ) => Promise> + /** + * 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. + */ status: QueryStatus + /** + * 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. + */ fetchStatus: FetchStatus } @@ -826,11 +915,64 @@ export interface MutationObserverBaseResult< TVariables = void, TContext = unknown, > extends MutationState { + /** + * The last successfully resolved data for the mutation. + * - Defaults to `undefined`. + */ + data: TData | undefined + /** + * The variables object passed to the `mutationFn`. + * - Defaults to `undefined`. + */ + variables: TVariables | undefined + /** + * The error object for the mutation, if an error was encountered. + * - Defaults to `null`. + */ + error: TError | null + /** + * A boolean variable derived from `status`. + * - `true` if the last mutation attempt resulted in an error. + */ isError: boolean + /** + * A boolean variable derived from `status`. + * - `true` if the mutation is in its initial state prior to executing. + */ isIdle: boolean + /** + * A boolean variable derived from `status`. + * - `true` if the mutation is currently executing. + */ isPending: boolean + /** + * A boolean variable derived from `status`. + * - `true` if the last mutation attempt was successful. + */ isSuccess: boolean + /** + * The status of the mutation. + * - Will be: + * - `idle` initial status prior to the mutation function executing. + * - `pending` if the mutation is currently executing. + * - `error` if the last mutation attempt resulted in an error. + * - `success` if the last mutation attempt was successful. + */ + status: MutationStatus + /** + * The mutation function you can call with variables to trigger the mutation and optionally hooks on additional callback options. + * @param variables - The variables object to pass to the `mutationFn`. + * @param options.onSuccess - This function will fire when the mutation is successful and will be passed the mutation's result. + * @param options.onError - This function will fire if the mutation encounters an error and will be passed the error. + * @param options.onSettled - This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error. + * @remarks + * - If you make multiple requests, `onSuccess` will fire only after the latest call you've made. + * - All the callback functions (`onSuccess`, `onError`, `onSettled`) are void functions, and the returned value will be ignored. + */ mutate: MutateFunction + /** + * A function to clean the mutation internal state (i.e., it resets the mutation to its initial state). + */ reset: () => void }