smart_query library

Async server-state management for Flutter — caching, deduplication, background sync, optimistic updates, and pagination.

Inspired by TanStack Query (React Query), built idiomatically for Flutter.

Quick Start

// 1. Wrap your app
void main() {
  runApp(
    QueryClientProvider(
      client: QueryClient(),
      child: MyApp(),
    ),
  );
}

// 2. Use QueryBuilder
QueryBuilder<List<User>>(
  queryKey: ['users'],
  fetcher: () => api.getUsers(),
  builder: (context, result) {
    if (result.isLoading) return CircularProgressIndicator();
    if (result.isError) return Text('Error: ${result.error}');
    return ListView(
      children: result.data!.map((u) => Text(u.name)).toList(),
    );
  },
)

Classes

ConnectivityObserver

Abstract interface for monitoring network connectivity.

InfiniteQueryBuilder<TPage, TPageParam>

A widget that manages infinite scroll / "Load more" patterns.

InfiniteQueryData<TPage>

Holds the accumulated pages for an infinite query.

InfiniteQueryResult<TPage>

Result exposed to the builder of InfiniteQueryBuilder.

MutationBuilder<TData, TVariables>

A widget that manages mutation state and rebuilds when it changes.

MutationOptions<TData, TVariables>

Configuration options for a mutation.

MutationResult<TData, TVariables>

Immutable result of a mutation.

PaginatedQueryBuilder<T>

A convenience widget for classic page-based pagination.

QueryBuilder<T>

A widget that fetches and caches data, rebuilding when the query state changes.

QueryClient

The central entry point for all query and cache operations.

QueryClientInherited

InheritedWidget that holds the QueryClient.

QueryClientProvider

Provides a QueryClient to the widget subtree.

QueryDefaults

Global default options for all queries managed by a QueryClient.

QueryOptions<T>

Configuration options for a query.

QueryResult<T>

Immutable result of a query, containing data, error, and status information.

Enums

ConnectivityStatus

Network connectivity status.

MutationStatus

Status states for a mutation's lifecycle.

QueryStatus

Status states for a query's lifecycle.

Typedefs

MutatorFn<TData, TVariables> = Future<TData> Function(TVariables variables)

Type alias for a mutation function.

OnMutateFn<TVariables> = FutureOr Function(TVariables variables)

Type alias for the onMutate callback.

OnMutationErrorFn<TVariables> = FutureOr<void> Function(Object error, TVariables variables, dynamic context)

Type alias for the onError callback of a mutation.

OnMutationSettledFn<TData, TVariables> = FutureOr<void> Function(TData? data, Object? error, TVariables variables, dynamic context)

Type alias for the onSettled callback of a mutation.

OnMutationSuccessFn<TData, TVariables> = FutureOr<void> Function(TData data, TVariables variables, dynamic context)

Type alias for the onSuccess callback of a mutation.

PagedQueryFetcher<T, TPageParam> = Future<T> Function(TPageParam pageParam)

Type alias for a paginated query fetcher function.

QueryFetcher<T> = Future<T> Function()

Type alias for a query fetcher function.

RetryDelayFn = Duration Function(int attemptIndex)

Type alias for retry delay calculation.

RetryWhenFn = bool Function(Object error)

Type alias for conditional retry.