watchQuery<TData> method

QueryResult<TData> watchQuery<TData>(QueryObserverOptions<TData> options, { Object? id, BuildWhen<QueryResult<TData>>? buildWhen, })

Subscribes this State to options's query and returns its current result.

final task = watchQuery(taskQuery(widget.id));

The first call for a key creates the observer; later calls with the same key reuse it and apply the new options. Options built inline are re-applied on every build, so an Enabled.when over outside state is re-evaluated; the observer compares them by value and only a real difference reaches the query. A different key is a different observer, and the one for the key no longer read is released after the frame — unless the read carries an id: then the id is the read's identity and the observer follows the key, which is what PlaceholderData.compute((previous, _) => previous) needs to show the previous key's data while the next loads. id also tells apart two reads of one key in the same State.

buildWhen narrows when this State rebuilds, the same predicate a builder takes (QueryBuilder.buildWhen): given the result the last build showed and the one that just arrived, it says whether the change is worth a frame. A result equal to the one last built is skipped before the predicate is asked, so it only ever sees a real change. It is the tool for the change select cannot narrow away — a background refetch moves fetchStatus and dataUpdatedAt, and both are part of a QueryResult's ==. Each read has its own predicate, and any one of them letting a change through rebuilds the whole State.

Implementation

QueryResult<TData> watchQuery<TData>(
  QueryObserverOptions<TData> options, {
  Object? id,
  BuildWhen<QueryResult<TData>>? buildWhen,
}) =>
    _watch<TData, TData>(options, id, buildWhen);