BloomInfiniteQuery<TPage, TParam> class

A reactive asynchronous paginated/infinite query coordinator with caching, cursor/offset pagination, background revalidation, and invalidation tracking.

BloomInfiniteQuery extends Bloom's query system to support paginated datasets:

Page Accumulation: Sequentially loads and appends pages into data / pages as fetchNextPage is invoked.
Next Page Determination: Derives the next page parameter via getNextPageParam, signaling end-of-list when it returns null.
Granular Spinners: Distinguishes initial page loading (isLoading) from incremental page loading (isFetchingNextPage) to support clean bottom loading spinners.
Concurrency Guard: Prevents duplicate in-flight requests when fetchNextPage is triggered multiple times concurrently.
Automatic Reset on Refetch: refetch restarts from initialPageParam and replaces stale accumulated pages rather than appending duplicates.
Cache & Invalidation: Automatically persists pages to BloomData cache and revalidates when matching query keys are invalidated via BloomData.invalidateQueries.

SSR & Browser Behavior

SSR (renderToHtml): Synchronously evaluates current pages signal. If preloaded or hydrated, renders initial pages in HTML.
Browser (mount): Initiates initial fetch if enabled, subscribes to invalidations, and updates reactive signals as subsequent pages are fetched.

Example

final feedQuery = infiniteQuery<List<String>, int>(
  key: ['feed'],
  initialPageParam: 0,
  fetch: (page) => api.fetchFeed(offset: page, limit: 10),
  getNextPageParam: (lastPage, allPages) =>
      lastPage.length == 10 ? allPages.length * 10 : null,
);

BloomNode buildFeed() {
  return Div(
    children: [
      Live(() => switch (feedQuery.status.value) {
        QueryStatus.loading => P(text: 'Loading initial feed...'),
        QueryStatus.error => P(text: 'Error: ${feedQuery.error.value}'),
        QueryStatus.success || QueryStatus.idle => Div(
          children: [
            for (final item in feedQuery.items) Div(text: item.toString()),
            if (feedQuery.hasNextPage.value)
              Button(
                text: feedQuery.isFetchingNextPage.value ? 'Loading more...' : 'Load More',
                on: {'click': (e) => feedQuery.fetchNextPage()},
              ),
          ],
        ),
      }),
    ],
  );
}

Constructors

BloomInfiniteQuery({required List key, required InfiniteQueryFn<TPage, TParam> fetch, required TParam initialPageParam, required GetNextPageParamFn<TPage, TParam> getNextPageParam, Duration staleTime = const Duration(minutes: 5), Duration cacheTime = const Duration(minutes: 30), bool enabled = true, List getItems(TPage page)?, List<TPage>? initialData}): Creates a BloomInfiniteQuery and checks cache freshness or initiates an initial fetch.

Properties

cacheTime → Duration: Duration after a fetch after which cached data is evicted from the cache.
final
data → ReadonlySignal<List<TPage>?>: Reactive signal holding the accumulated list of resolved pages, or null if uninitialized.
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 fetching, or null on success.
no setter
fetch → InfiniteQueryFn<TPage, TParam>: The asynchronous fetch function executed to retrieve a single page.
final
getItems → List Function(TPage page)?: Optional function extracting a list of items from a page for the items convenience getter.
final
getNextPageParam → GetNextPageParamFn<TPage, TParam>: Function deriving the parameter for the next page from the most recent page and all loaded pages.
final
hasData → bool: Whether the query currently holds any non-empty page data.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasNextPage → ReadonlySignal<bool>: Reactive signal indicating whether there is a subsequent page available to fetch.
no setter
initialPageParam → TParam: The parameter value used to request the first page.
final
isError → bool: Whether the query failed with an error.
no setter
isFetching → ReadonlySignal<bool>: Reactive signal indicating whether any network fetch is in-flight (initial, refetch, or next page).
no setter
isFetchingNextPage → ReadonlySignal<bool>: Reactive signal indicating whether a request for the next page is actively in-flight.
no setter
isLoading → bool: Whether the query is performing its initial fetch with no pages loaded.
no setter
isStale → ReadonlySignal<bool>: Reactive signal indicating whether the current cached page data is stale.
no setter
isSuccess → bool: Whether the query has successfully resolved at least one page.
no setter
items → List: Convenience getter returning all individual items across all loaded pages flattened into a single list.
no setter
key → List: The structured query cache key identifying this query.
final
nextPageParam → TParam?: The next parameter value that will be passed to fetch on fetchNextPage, or null if no more pages.
no setter
pageList → List<TPage>: Synchronous non-null snapshot of the current loaded pages.
no setter
pageParams → List<TParam>: The parameter values that were used to fetch each loaded page in order.
no setter
pages → ReadonlySignal<List<TPage>?>: Reactive signal holding the accumulated list of resolved pages (alias for data).
no setter
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.
no setter

Methods

dispose() → void: Cancels the invalidation subscription and halts future reactive updates.
fetchNextPage() → Future<List<TPage>?>: Fetches the subsequent page using nextPageParam and appends it to pages.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
refetch() → Future<List<TPage>?>: Manually re-fetches the first page from scratch and replaces all accumulated pages.
setData(List<TPage> newPages) → void: Manually updates the accumulated pages without triggering a network fetch.
toString() → String: A string representation of this object.
inherited

Operators

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