QueryResult<TData> class sealed

The result of observing one query: what it holds, and what it is doing.

Every observer — a QueryObserver, and each widget or controller of the Flutter binding — hands out one of these, and a new one whenever something it reports changes. Results are immutable values with ==, so an unchanged result compares equal to the previous one.

What the query holds is the variant. The class is sealed, with exactly three subclasses, so a switch over it is exhaustive and each arm gets the fields that exist in that state — no result.data!:

What the query is doing is separate from the variant: fetchStatus and the flags derived from it — isFetching, isPaused, isLoading, isRefetching. A QuerySuccess with isFetching true is the ordinary background refresh: the old data stays on screen while the new data loads. The retry progress of the fetch in flight is in failureCount and failureReason, again without changing the variant.

String describe(QueryResult<List<Task>> result) => switch (result) {
      QueryPending() => 'Loading',
      QuerySuccess(:final data) when result.isFetching =>
        '${data.length} tasks (refreshing)',
      QuerySuccess(:final data) => '${data.length} tasks',
      QueryError(:final error, :final staleData?) =>
        '${staleData.length} tasks (refresh failed: $error)',
      QueryError(:final error) => 'Failed: $error',
    };

For code that stores or compares the state rather than matching on it there are status, isPending, isSuccess and isError, and dataOrNull and errorOrNull for a plain nullable read.

TanStack Query reports the same information as one object with a status string and a set of booleans; the sealed variants replace that.

Available extensions
Annotations

Properties

consecutiveErrorCount → int
Fetches in a row that ended in an error — the query's QueryState.consecutiveErrorCount, here so the widget that renders a result can read it too. A successful fetch sets it back to zero; a manual write (setQueryData, an optimistic patch) does not, although it turns an error into a QuerySuccess. So a "gave up after five failures" is read here, not from the variant: after such a write the result is a success while polling that stopped on this count stays stopped.
final
dataOrNull → TData?
The data this result carries, if any. Prefer pattern matching; this exists for the cases where a nullable read is genuinely what you want.
no setter
dataUpdatedAt → DateTime?
When the data was last written, by a fetch or by hand — what staleTime counts from. null until something has been.
final
errorOrNull → Object?
The error this result carries: QueryError.error for a QueryError, null for the other variants.
no setter
errorUpdateCount → int
How many times this query has ended in an error over its whole life. It never goes down; see consecutiveErrorCount for failures in a row.
final
errorUpdatedAt → DateTime?
When the query last ended in an error. null until it has; not cleared by a later success, so "last failed at" stays readable.
final
failureCount → int
Failures within the current fetch. A query retrying in the background reports progress here while still showing its last good data.
final
failureReason → Object?
What the latest failed attempt threw. It is kept while retries continue and after the fetch finally fails. It is cleared when the next fetch starts or an attempt succeeds.
final
failureStackTrace → StackTrace?
The stack trace of the attempt that threw failureReason; null whenever failureReason is.
final
fetchStatus → FetchStatus
What the query is doing right now, independent of what it holds.
final
hashCode → int
The hash code for this object.
no setteroverride
isEnabled → bool
Whether this observer's enabled option currently allows the query to fetch on its own. refetch runs even when this is false.
final
isError → bool
Whether this is a QueryError: the last fetch failed after its retries. Earlier data may still be in QueryError.staleData.
no setter
isFetched → bool
Whether anything has ever been fetched, successfully or not.
final
isFetchedAfterMount → bool
Whether a fetch has completed since this observer was created, as opposed to data that was already in the cache when it attached.
final
isFetching → bool
Whether a fetch is in flight, first load and refetch alike, whatever the variant.
no setter
isLoading → bool
Whether this is the first load: pending and fetching. False for a pending query that is not fetching, such as a disabled one — the case where a spinner would spin forever.
no setter
isPaused → bool
Whether a fetch wants to run but is waiting: for the network, as the query's networkMode asks, or for the app to return to the foreground before its next retry.
no setter
isPending → bool
Whether this is a QueryPending: no data and no error. True during the first load, during a new fetch of a query without data whose last fetch failed, and for a disabled query that has never fetched.
no setter
isPlaceholderData → bool
Whether QuerySuccess.data is the observer's placeholderData rather than data from the cache. A placeholder is shown while the real fetch runs and is never written to the cache.
final
isRefetching → bool
Whether a fetch is running over a result that is not pending — a background refresh of data already shown, or a retry after an error.
no setter
isStale → bool
Whether the data is older than this observer's staleTime, or has been invalidated. A query with no data is stale; a disabled query never is, since nothing would refetch it. Stale data is still shown; it is only refetched at the next trigger (a new observer, focus, reconnect).
final
isSuccess → bool
Whether this is a QuerySuccess: the query holds data, whether or not a refresh is running.
no setter
refetch → QueryRefetch<TData>
Refetches this query regardless of enabled and staleTime, and completes with the result that follows. With cancelRefetch: true, the default, a fetch already in flight is cancelled and started over — once the query holds data; a first load is joined, not restarted. With false the in-flight one is awaited instead.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
status → QueryStatus
Which variant this is, as an enum, for callers that store or compare it rather than pattern-match.
no setter

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
optional() → QueryResult<T?>

Available on QueryResult<T>, provided by the OptionalQueryResult extension

This result for a combination that must neither wait for it nor fail with it: an optional feature's endpoint answers 404, and the rest of the screen is still the rest of the screen.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
override