QueryObserverOptions<TData> class final Options

Observer options for a plain query: no select, so the observer reports the query's data as its own, and one type argument names both.

The type comes from queryFn's return type or an explicit argument — QueryObserverOptions<Task>(…). Written inline with neither, TData has nothing to infer from; the binding's controllers refuse that in debug mode, and the analyzer's strict-inference reports it at the literal.

QueryObserverOptions<List<Todo>> todosQuery() => QueryObserverOptions(
      queryKey: QueryKey(['todos']),
      queryFn: (context) => api.fetchTodos(),
      refetchInterval: const RefetchInterval.every(Duration(seconds: 30)),
    );

// Imperatively: fetch once, if stale, and read the data.
final todos = await client.query(todosQuery());

// Or watch it: the observer fetches on its first subscriber.
final observer = QueryObserver(client, todosQuery());
final unsubscribe = observer.subscribe((result) => print(result));

Every field is described on QueryOptions and QueryObserverOptionsBase, with its default. For a query whose observers see a projection of the cached data, use QuerySelectOptions, or withSelect on existing options.

Inheritance
Annotations
  • @immutable

Constructors

QueryObserverOptions({required QueryKey queryKey, QueryFn<TData>? queryFn, Enabled? enabled, StaleTime? staleTime, GcTime? gcTime, RetryPolicy? retry, RetryDelay? retryDelay, NetworkMode? networkMode, InitialData<TData>? initialData, DateTime? initialDataUpdatedAt, DateTime? initialDataUpdatedAtCompute()?, StructuralSharing<TData>? structuralSharing, Object? meta, @internal FetchBehavior<TData>? behavior, PlaceholderData<TData>? placeholderData, RefetchOn? refetchOnMount, RefetchOn? refetchOnWindowFocus, RefetchOn? refetchOnReconnect, RefetchInterval? refetchInterval, bool? refetchIntervalInBackground, bool? retryOnMount})
The cache-layer fields plus the observer's own. Every field but queryKey is optional and takes the client's default.
const

Properties

enabled → Enabled?
Whether the query may fetch on its own. The default: Enabled.yes. A disabled query still serves whatever the cache holds and can still be refetched by hand.
finalinherited
gcTime → GcTime?
How long the query stays cached after its last observer leaves. The default: GcTime.defaultValue, five minutes.
finalinherited
hashCode → int
The hash code for this object.
no setterinherited
initialData → InitialData<TData>?
Data the cache starts with, as if it had been fetched — see InitialData. No default: unset, the query starts without data. Unlike placeholderData it is written to the cache, and it goes stale by staleTime from initialDataUpdatedAt on.
finalinherited
initialDataUpdatedAt → DateTime?
When initialData was fetched, for the staleness clock. No default: unset, the seed counts as fetched the moment it is written.
finalinherited
initialDataUpdatedAtCompute → DateTime? Function()?
Computes the seed timestamp only when data is actually seeded. No default. Mutually exclusive with initialDataUpdatedAt; a null result means now.
finalinherited
meta → Object?
Arbitrary data carried along for logging, devtools or a query function, which receives it as QueryFunctionContext.meta. No default: unset, the key's registered default applies, if any.
finalinherited
networkMode → NetworkMode?
How connectivity gates the fetch. The default: NetworkMode.online, an offline device pauses the fetch until it is back.
finalinherited
placeholderData → PlaceholderData<TData>?
Data shown while the query has none of its own — see PlaceholderData. No default: unset, an observer without data reports a pending result. Never written to the cache: a result built from it reports isPlaceholderData, and it gives way the moment real data arrives.
finalinherited
queryFn → QueryFn<TData>?
Fetches the data. Unset, the query uses the function registered for its key with QueryClient.setQueryDefaults; with none there either, a fetch fails with MissingQueryFunctionError.
finalinherited
queryKey → QueryKey
The key this query is cached under. Required. Bound to exactly one data type: a key read as another type — a supertype included — throws QueryDataTypeError.
finalinherited
refetchInterval → RefetchInterval?
Polls the query on a timer while this observer is subscribed. The default: RefetchInterval.off.
finalinherited
refetchIntervalInBackground → bool?
Whether refetchInterval keeps polling while the app is not focused. The default: false, the timer skips its turns until focus returns.
finalinherited
refetchOnMount → RefetchOn?
Whether this observer subscribing triggers a refetch. The default: RefetchOn.ifStale, only when the data is older than staleTime.
finalinherited
refetchOnReconnect → RefetchOn?
Whether the device coming back online triggers a refetch. The default: RefetchOn.ifStale — except under NetworkMode.always, where it is RefetchOn.never: a fetch that ignores connectivity has nothing to catch up on.
finalinherited
refetchOnWindowFocus → RefetchOn?
Whether the app regaining focus triggers a refetch. The default: RefetchOn.ifStale.
finalinherited
retry → RetryPolicy?
Whether a failed fetch is retried. The default: RetryPolicy.times(3), three retries after the first failure (TanStack Query: retry: 3). QueryClient.query is the exception: when neither these options nor the client's defaults set retry, its fetch is not retried.
finalinherited
retryDelay → RetryDelay?
How long to wait between attempts. The default: RetryDelay.defaultValue, exponential back-off from one second — one, two, four, … — capped at thirty.
finalinherited
retryOnMount → bool?
Whether a query that ended in an error retries when an observer mounts. The default: true, the mount refetches, and only retryOnMount: false leaves the error standing until something else asks.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
select → SelectFn<TData, TData>?
Always null: a plain query has no projection.
no setteroverride
staleTime → StaleTime?
How long fetched data counts as fresh. The default: StaleTime.zero, stale the moment it arrives, so every mount, focus and reconnect refetches.
finalinherited
structuralSharing → StructuralSharing<TData>?
How new data is reconciled with what the cache already holds — see StructuralSharing. The default: replaceEqualDeep, which keeps every deep-equal part of the previous data. noStructuralSharing turns it off.
finalinherited
toStringFields → Map<String, Object?>
What toString shows after the key: every field, in declaration order, with the unset (null) ones skipped — so a test failure or a debug print reads QueryOptions<int>(QueryKey(["a"]), staleTime: …) rather than Instance of 'QueryOptions<int>'. A subclass adds its own fields after these.
no setterinherited

Methods

copyWith({QueryKey? queryKey, QueryFn<TData>? queryFn, Enabled? enabled, StaleTime? staleTime, GcTime? gcTime, RetryPolicy? retry, RetryDelay? retryDelay, NetworkMode? networkMode, InitialData<TData>? initialData, DateTime? initialDataUpdatedAt, DateTime? initialDataUpdatedAtCompute()?, StructuralSharing<TData>? structuralSharing, Object? meta, PlaceholderData<TData>? placeholderData, RefetchOn? refetchOnMount, RefetchOn? refetchOnWindowFocus, RefetchOn? refetchOnReconnect, RefetchInterval? refetchInterval, bool? refetchIntervalInBackground, bool? retryOnMount}) → QueryObserverOptions<TData>
This, with the given fields replaced; each shape returns its own type. select is not a field here — it is what tells the two shapes apart — so only QuerySelectOptions.copyWith accepts one.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited
withSelect<R>(SelectFn<TData, R> select) → QuerySelectOptions<TData, R>
These options with a select added: every field carried over, so a shared options helper can serve a projecting reader without being written out again field by field. The result is a QuerySelectOptions on the same key, so it shares the cache entry with every other reader.

Operators

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