BloomQuery<T> class

A reactive asynchronous query manager with automatic caching, request deduplication, background revalidation, and invalidation listening.

BloomQuery integrates asynchronous data fetching into Bloom's signal-based reactivity:

Stale-While-Revalidate: If cached data exists in BloomData, it is returned immediately with status set to QueryStatus.success, while an asynchronous background revalidation runs if the entry QueryCacheEntry.shouldRevalidate.
Reactive Signals: Exposes data, status, error, isFetching, and isStale as ReadonlySignal instances that automatically trigger re-renders in Live or Show widgets.
Deduplication: Automatically deduplicates concurrent calls to the same key via BloomData.deduplicate.
Auto Invalidation: Listens to BloomData.invalidateQueries events matching key to automatically refetch.

Backend Behavior

Browser (mount): Initiates network fetching on creation (if enabled), listens for invalidations, and updates reactive signals as results arrive.
SSR (renderToHtml): Synchronously evaluates current signal values. If data was preloaded into BloomData before rendering, SSR renders the success state immediately.

Example

final userQuery = query<User>(
  key: ['users', 123],
  fetch: () => httpClient.get<User>('/users/123'),
  staleTime: Duration(minutes: 2),
);

BloomNode buildUserProfile() {
  return Live(() => switch (userQuery.status.value) {
    QueryStatus.loading => P(text: 'Loading user...'),
    QueryStatus.error => P(text: 'Error: ${userQuery.error.value}'),
    QueryStatus.success => Div(children: [
        H1(text: userQuery.data.value?.name ?? 'Unknown'),
        if (userQuery.isFetching.value) Span(text: 'Updating...'),
      ]),
    QueryStatus.idle => P(text: 'Idle'),
  });
}

Constructors

BloomQuery({required List key, required Future<T> fetch(), Duration staleTime = const Duration(minutes: 5), Duration cacheTime = const Duration(minutes: 30), bool enabled = true, T? initialData}): Creates a BloomQuery and immediately checks cache freshness or initiates a fetch if enabled.

Properties

cacheTime → Duration: Duration after a fetch after which cached data is evicted from the cache.
final
data → ReadonlySignal<T?>: Reactive signal holding the resolved query data, or null if uninitialized/loading.
no setter
enabled → bool: Whether this query should automatically fetch on instantiation and upon invalidation.
final
error → ReadonlySignal<Object?>: Reactive signal holding any unhandled exception thrown during fetch, or null on success.
no setter
fetch → Future<T> Function(): The asynchronous fetch function executed to retrieve data.
final
hasData → bool: Whether the query has non-null data available (either fresh or stale).
no setter
hashCode → int: The hash code for this object.
no setterinherited
isError → bool: Whether the query failed with an error.
no setter
isFetching → ReadonlySignal<bool>: Reactive signal indicating whether a network fetch is actively in-flight (including background revalidations).
no setter
isLoading → bool: Whether the query is currently performing its initial fetch with no data available.
no setter
isStale → ReadonlySignal<bool>: Reactive signal indicating whether the current data is stale and awaiting background revalidation.
no setter
isSuccess → bool: Whether the query resolved successfully and contains valid data.
no setter
key → List: The structured query cache key identifying this query.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
staleTime → Duration: Duration after a successful fetch during which data is considered fresh before revalidation.
final
status → ReadonlySignal<QueryStatus>: Reactive signal holding the current lifecycle QueryStatus (idle, loading, success, error).
no setter

Methods

dispose() → void: Cancels the query's invalidation stream subscription and prevents future state updates.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
refetch() → Future<T?>: Manually triggers a network re-fetch for this query, returning the resolved result.
setData(T newData) → void: Manually updates the cached and signal data for this query without triggering a network fetch.
toString() → String: A string representation of this object.
inherited

Operators

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