flutter_query_client

A TanStack Query-inspired server state management library for Flutter.

Handles fetching, caching, synchronizing, and updating server state with minimal boilerplate — automatic background refetching, stale-while-revalidate caching, infinite pagination, mutation support, and a rich widget layer out of the box.

Features

  • QueryController — fetch and cache server data automatically
  • MutationController — user-triggered mutations; emits QueryState so all Query* widgets work with it
  • InfiniteQueryController — paginated / infinite-scroll data with loadMore()
  • Stale-while-revalidate — serve cached data instantly, refetch in background
  • Configurable stale time & garbage collection — control cache lifetime precisely
  • Automatic retry with exponential backoff — resilient to transient failures
  • Network-aware fetching — pauses when offline, resumes on reconnect
  • keepPreviousData — show old results while fetching new ones after setParams()
  • Global defaults with per-controller overrides
  • BLoC-based state — integrates naturally with flutter_bloc; observe all controllers via QueryObserver set in QueryClientProvider
  • Freezed immutable state — safe pattern matching on QueryState

Installation

dependencies:
  flutter_query_client: ^2.0.0

Quick Start

1. Wrap your app

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return QueryClientProvider(
      defaults: const QueryDefaults(
        staleTime: Duration(minutes: 5),
        gcTime: Duration(minutes: 10),
        retryCount: 3,
      ),
      // Optional: attach a global observer (no flutter_bloc import needed).
      observer: AppQueryObserver(),
      child: const MaterialApp(home: HomeScreen()),
    );
  }
}

2. Define a controller

class PostsController extends QueryController<List<Post>, void> {
  PostsController() : super('posts');

  @override
  Future<List<Post>> queryFn(void params) => postService.getPosts();
}

3. Provide and build

QueryProvider<PostsController, List<Post>>(
  create: (_) => PostsController(),
  child: QueryBuilder<PostsController, List<Post>>(
    builder: (context, state) {
      if (state.isLoading) return const CircularProgressIndicator();
      if (state.isError)   return Text('Error: ${state.error}');
      return PostListView(posts: state.data!);
    },
  ),
),

Core Concepts

QueryState

Every controller emits QueryState<T>:

Property Type Description
data T? The cached data
error Object? The last error
status QueryStatus idle · loading · success · error
fetchStatus FetchStatus idle · fetching · refetching · paused
isStale bool Data is past its stale time
isPlaceholderData bool Showing previous data during a setParams() fetch
isLoadingMore bool Infinite query is fetching the next page
isLoading bool status == loading
isSuccess bool status == success
isError bool status == error
isIdle bool status == idle
isFetching bool Any active background fetch
isRefetching bool Background refetch with data already present
isPaused bool Fetch paused (offline)
hasData bool data != null
hasError bool error != null

Widget Reference

Provider Widgets

Widget Purpose
QueryProvider<C, T> Provides a QueryController or MutationController via BlocProvider; handles remount
InfiniteQueryProvider<C> Provides an InfiniteQueryController; handles remount
MultiQueryProvider Nest multiple providers without indentation
QueryClientProvider Inject QueryClient + global QueryDefaults into the tree

Builder / Listener Widgets

Widget Purpose
QueryBuilder<C, T> Rebuild on QueryState<T> changes
InfiniteQueryBuilder<C, T> Rebuild on QueryState<List<T>> changes
QueryListener<C, T> Side-effects on QueryState<T> changes — no rebuild
InfiniteQueryListener<C, T> Side-effects on QueryState<List<T>> — no List<T> in type arg
MultiQueryListener Multiple QueryListeners without extra widget layers

Consumer Widgets (builder + listener combined)

Widget Purpose
QueryConsumer<C, T> QueryBuilder + QueryListener in one widget
InfiniteQueryConsumer<C, T> Same for infinite queries; List<T> baked in

Selector Widgets (minimal rebuilds)

Widget Purpose
QuerySelector<C, T, S> Rebuilds only when a derived value S changes
InfiniteQuerySelector<C, T, S> Same for infinite queries; List<T> baked in

Tip — mutations use the same widgets. MutationController<T> emits QueryState<T>, so QueryBuilder, QueryListener, QueryConsumer, and QuerySelector all work with mutations out of the box.

Provider Widgets

QueryProvider

QueryProvider<PostsController, List<Post>>(
  create: (_) => PostsController(),
  child: const PostsListView(),
)

Automatically calls controller.handleRemount() when a widget transitions from hidden → visible (e.g. inside IndexedStack or Visibility).

InfiniteQueryProvider

InfiniteQueryProvider<ProductsController>(
  create: (_) => ProductsController(),
  child: const ProductsView(),
)

MultiQueryProvider

Provide multiple controllers without deep nesting — identical ergonomics to MultiBlocProvider. Pass each provider without a child; MultiQueryProvider injects it automatically. Providers are applied top-to-bottom (first entry = outermost ancestor).

MultiQueryProvider(
  providers: [
    QueryProvider<PostsController, List<Post>>(
      create: (_) => PostsController(),
    ),
    QueryProvider<CreatePostMutation, Post>(
      create: (_) => CreatePostMutation(),
    ),
    InfiniteQueryProvider<ProductsController>(
      create: (_) => ProductsController(),
    ),
  ],
  child: const HomeScreen(),
)

Builder Widgets

QueryBuilder

QueryBuilder<PostsController, List<Post>>(
  buildWhen: (prev, next) => prev.status != next.status,
  builder: (context, state) {
    if (state.isLoading)    return const CircularProgressIndicator();
    if (state.isError)      return ErrorView(error: state.error);
    if (state.isRefetching) return PostsView(posts: state.data!, loading: true);
    return PostsView(posts: state.data ?? []);
  },
)

InfiniteQueryBuilder

InfiniteQueryBuilder<ProductsController, Product>(
  builder: (context, state) {
    final products = state.data ?? [];
    return ListView.builder(
      itemCount: products.length + (state.isLoadingMore ? 1 : 0),
      itemBuilder: (_, i) {
        if (i >= products.length) return const LoadingTile();
        return ProductTile(products[i]);
      },
    );
  },
)

Listener Widgets

QueryListener

Side-effects only — no rebuild. Works with both query and mutation controllers.

QueryListener<PostsController, List<Post>>(
  listenWhen: (prev, next) => !prev.isError && next.isError,
  listener: (context, state) => showErrorSnackBar(state.error),
  child: const PostsView(),
)

// With a MutationController
QueryListener<CreatePostMutation, Post>(
  listenWhen: (_, next) => next.isSuccess || next.isError,
  listener: (context, state) {
    if (state.isSuccess) Navigator.pop(context, state.data);
    if (state.isError)   showErrorSnackBar(state.error);
  },
  child: const CreatePostForm(),
)

InfiniteQueryListener

Identical to QueryListener for infinite queries — the List<T> wrapper is baked into the type so you only specify the item type:

// Before (verbose)
QueryListener<ProductsController, List<Product>>(...)

// After
InfiniteQueryListener<ProductsController, Product>(
  listenWhen: (prev, next) => prev.isLoadingMore && !next.isLoadingMore,
  listener: (context, state) {
    if (state.isError) showErrorSnackBar('Failed to load more');
  },
  child: const ProductsView(),
)

MultiQueryListener

Attach multiple listeners without extra widget layers:

MultiQueryListener(
  listeners: [
    QueryListener<PostsController, List<Post>>(
      listenWhen: (_, next) => next.isError,
      listener: (context, state) => showErrorSnackBar(state.error),
    ),
    QueryListener<CreatePostMutation, Post>(
      listenWhen: (_, next) => next.isSuccess || next.isError,
      listener: (context, state) { /* handle mutation result */ },
    ),
  ],
  child: const HomeScreen(),
)

Consumer Widgets

Combine builder + listener without nesting — useful when you need both a reactive UI and a side-effect on the same controller.

QueryConsumer

QueryConsumer<PostsController, List<Post>>(
  listenWhen: (_, next) => next.isError,
  listener: (context, state) => showErrorSnackBar(state.error),
  buildWhen: (prev, next) => prev.data != next.data,
  builder: (context, state) {
    if (state.isLoading) return const CircularProgressIndicator();
    return PostsView(posts: state.data ?? []);
  },
)

// With a MutationController
QueryConsumer<CreatePostMutation, Post>(
  listenWhen: (_, next) => next.isSuccess,
  listener: (context, state) => Navigator.pop(context, state.data),
  builder: (context, state) => FilledButton(
    onPressed: state.isLoading ? null : _submit,
    child: state.isLoading
        ? const CircularProgressIndicator()
        : const Text('Submit'),
  ),
)

InfiniteQueryConsumer

InfiniteQueryConsumer<ProductsController, Product>(
  listenWhen: (prev, next) => prev.isLoadingMore && !next.isLoadingMore && next.isError,
  listener: (context, state) => showErrorSnackBar('Failed to load more'),
  builder: (context, state) {
    final products = state.data ?? [];
    if (state.isLoading) return const CircularProgressIndicator();
    return ProductsView(products: products, isLoadingMore: state.isLoadingMore);
  },
)

Selector Widgets

Rebuilds only when the selected value changes — use for badges, counters, or flags that don't need the full state.

QuerySelector

// Only rebuilds when post count changes — ignores refetch/stale events.
QuerySelector<PostsController, List<Post>, int>(
  selector: (state) => state.data?.length ?? 0,
  builder: (context, count) => Badge(label: Text('$count')),
)

// Only rebuilds when the mutation's loading flag toggles.
QuerySelector<CreatePostMutation, Post, bool>(
  selector: (state) => state.isLoading,
  builder: (context, isLoading) => FilledButton(
    onPressed: isLoading ? null : _submit,
    child: const Text('Submit'),
  ),
)

InfiniteQuerySelector

// Only rebuilds when total item count changes.
InfiniteQuerySelector<ProductsController, Product, int>(
  selector: (state) => state.data?.length ?? 0,
  builder: (context, count) => Text('$count items loaded'),
)

QueryController

Base class for any single-resource fetch.

class PostByIdController extends QueryController<Post, int> {
  PostByIdController() : super('post');

  // Optional overrides
  @override Duration? get staleTime => const Duration(seconds: 30);
  @override int get retryCount => 1;
  @override RefetchOnMount get refetchOnMount => RefetchOnMount.always;

  @override
  Future<Post> queryFn(int? id) => postService.getPostById(id!);

  // Lifecycle hooks
  @override void onSuccess(Post data) { /* analytics, logging */ }
  @override void onQueryError(Object error) { /* report error */ }
}

Key methods

// Trigger the query (or re-trigger with new params)
controller.setParams(postId);

// Manual refetch
controller.refetch();

// Get or fetch data imperatively (returns cached if fresh)
final post = await controller.ensureData(postId);

// Optimistic cache update
controller.updateCache((current) => current?.copyWith(title: 'New title'));

// Invalidate — marks stale and refetches if active
controller.invalidate();

Override contract

Override Default Purpose
queryFn(P? params) — Required. The fetch function
enabled auto false prevents execution (auto: false when P ≠ void and params == null)
staleTime null Duration until data is considered stale (null = never)
refetchInterval null Auto-poll interval (null = disabled)
refetchOnMount always always · stale · never
refetchOnReconnect ifStale always · ifStale · never
networkMode online online · always · offlineFirst
retryCount 3 Retry attempts on failure
retryDelay 1s Base delay; actual uses exponential backoff
keepPreviousData false Show old data during setParams() refetch
onSuccess(T data) no-op Called after successful fetch
onQueryError(Object e) no-op Called after all retries fail

InfiniteQueryController

For cursor- or page-based pagination. T = item type, PageParam = page parameter type, P = filter type (void if no filters).

initialPageParam and limit are optional — they inherit from QueryDefaults (0 and 20 by default) and only need to be overridden when a controller differs from the global setting.

// Minimal — initialPageParam and limit come from QueryDefaults.
class ProductsController extends InfiniteQueryController<Product, int, String> {
  ProductsController() : super('products');

  @override bool get keepPreviousData => true;

  @override
  int? getNextPageParam(List<Product> lastPage, List<List<Product>> allPages) =>
      lastPage.length < limit ? null : allPages.length;

  @override
  Future<List<Product>> queryFn(int pageParam, String? query) =>
      productService.getProducts(page: pageParam, search: query ?? '');
}

// Override only when this controller differs from the global default.
class CursorProductsController extends InfiniteQueryController<Product, String, void> {
  CursorProductsController() : super('cursor-products');

  @override String get initialPageParam => '';   // cursor, not an int
  @override int    get limit           => 10;    // smaller page size

  @override
  String? getNextPageParam(List<Product> last, List<List<Product>> all) =>
      last.isEmpty ? null : last.last.cursor;

  @override
  Future<List<Product>> queryFn(String cursor, void _) =>
      productService.getProductsAfter(cursor, limit: limit);
}

Key methods

// Trigger next page
await controller.loadMore();

// Apply new filter params — resets pagination and refetches
controller.setParams('running shoes');

// Refetch from page 0
controller.refetch();

// Invalidate and reset
controller.invalidateAndRefresh();

// Optimistic item updates across all pages
controller.updateItem((p) => p.id == updated.id, updated);
controller.removeItem((p) => p.id == deletedId);
controller.prependItem(newItem);
controller.appendItem(newItem);

Key getters

controller.hasMore      // bool — whether getNextPageParam returns non-null
controller.currentPage  // int — number of pages loaded
controller.totalItems   // int — flat item count across all pages
controller.filters      // P?  — current filter params

MutationController

For create / update / delete operations. Takes a typed params generic P matching QueryController<T, P>. Override mutationFn(P params) — no closures needed. Mutations emit QueryState<T>, so every Query* widget works with them out of the box.

// Define a record typedef for the params (Dart 3 named records work well).
typedef CreatePostParams = ({int userId, String title, String body});

class CreatePostMutation extends MutationController<Post, CreatePostParams> {
  @override
  Future<Post> mutationFn(CreatePostParams params) {
    return postService.createPost(
      userId: params.userId,
      title: params.title,
      body: params.body,
    );
  }

  @override
  void onSuccess(Post data) => QueryLogger.info('Created: ${data.id}');

  @override
  void onMutationError(Object error) => QueryLogger.warning('Failed: $error');

  @override
  void onSettled(Post? data, Object? error) { /* always called */ }
}

// For mutations that need no params, use void as the second type argument.
class DeletePostMutation extends MutationController<bool, int> {
  @override
  Future<bool> mutationFn(int id) async {
    await postService.deletePost(id);
    return true;
  }
}

// Provide like a QueryController
QueryProvider<CreatePostMutation, Post>(
  create: (_) => CreatePostMutation(),
  child: const CreatePostForm(),
)

// Trigger with typed named-record params
context.query<CreatePostMutation>().mutate((
  userId: 1,
  title: 'Hello',
  body: 'World',
));

// Reset state to idle
context.query<CreatePostMutation>().reset();

// Use standard query widgets — mutations emit QueryState<T>
QueryConsumer<CreatePostMutation, Post>(
  listenWhen: (_, next) => next.isSuccess || next.isError,
  listener: (context, state) { /* navigate / show toast */ },
  builder: (context, state) => FilledButton(
    onPressed: state.isLoading ? null : _submit,
    child: state.isLoading
        ? const CircularProgressIndicator()
        : const Text('Create'),
  ),
)

Override contract

Override Default Purpose
mutationFn(P params) — Required. The mutation function; receives typed params
retryCount 0 Global retryCount intentionally not applied to mutations
onSuccess(T data) no-op Called after mutation succeeds
onMutationError(Object e) no-op Called after mutation fails
onSettled(T? data, Object? error) no-op Always called after settle

QueryClient

Singleton cache manager. Access via QueryClient.instance or context.queryClient.

final client = QueryClient.instance;

// Invalidate a specific key + params (removes from cache)
client.invalidate('posts', serializedParams);

// Invalidate all param variants for a key and notify active controllers
client.invalidateQueries(['posts', 'products']);

// Update cached data for all param variants of a key
client.update<List<Post>>('posts', (posts) => [newPost, ...posts]);

// Update infinite query pages
client.updateInfiniteQuery<Product>('products', (pages) => pages);

// Direct cache access
final cached = client.get<List<Post>>('posts');

// Register a global observer (prefer QueryClientProvider(observer:) at startup)
client.setObserver(AppQueryObserver());

// Set global defaults
client.setDefaults(const QueryDefaults(staleTime: Duration(minutes: 5)));

BuildContext extensions

// Get a controller from the widget tree
final ctrl = context.query<PostsController>();

// Get the QueryClient
final client = context.queryClient;

// Read cached data directly
final posts = context.cachedQuery<List<Post>>('posts');
final post  = context.cachedQueryWithParams<Post>('post', serializedId);

QueryObserver

A BlocObserver subclass that filters events to query and mutation controllers only, exposing typed hooks. Pass it to QueryClientProvider alongside your other global defaults — no direct flutter_bloc import needed in your app.

QueryClientProvider(
  defaults: const QueryDefaults(...),
  observer: AppQueryObserver(),   // ← registered here, alongside defaults
  child: const MyApp(),
)

class AppQueryObserver extends QueryObserver {
  /// Called when any QueryController, InfiniteQueryController,
  /// or MutationController is created.
  @override
  void onQueryCreate(String cacheKey) =>
      debugPrint('created: $cacheKey');

  /// currentState + nextState — same semantics as BlocObserver.onChange.
  @override
  void onQueryChange(
    String cacheKey,
    QueryState<dynamic> currentState,
    QueryState<dynamic> nextState,
  ) {
    debugPrint(
      '[$cacheKey] ${currentState.status.name} → ${nextState.status.name}',
    );
  }

  @override
  void onQueryError(String cacheKey, Object error, StackTrace stackTrace) =>
      FirebaseCrashlytics.instance.recordError(error, stackTrace);

  @override
  void onQueryClose(String cacheKey) =>
      debugPrint('closed: $cacheKey');
}

To also observe non-query cubits, override the raw BlocObserver hooks and call super:

@override
void onChange(BlocBase<dynamic> bloc, Change<dynamic> change) {
  super.onChange(bloc, change); // ← fires onQueryChange for query controllers
  if (bloc is MyOtherCubit) { /* handle */ }
}

Global Configuration

All global setup lives in a single QueryClientProvider:

QueryClientProvider(
  client: QueryClient.instance,       // optional — defaults to singleton
  observer: AppQueryObserver(),       // optional — global lifecycle observer
  defaults: QueryDefaults(
    staleTime: const Duration(minutes: 5),
    gcTime: const Duration(minutes: 10),
    retryCount: 3,
    retryDelay: const Duration(seconds: 1),
    refetchOnMount: RefetchOnMount.stale,
    refetchOnReconnect: RefetchOnReconnect.ifStale,
    networkMode: NetworkMode.online,
    refetchInterval: null,
    // Infinite query defaults — applied to every InfiniteQueryController
    // that doesn't override them individually.
    initialPageParam: 0,              // first page param (default: 0)
    limit: 20,                        // items per page (default: 20)
    transformError: (error) => AppException.from(error),
    connectivityEndpoints: [
      InternetCheckOption(uri: Uri.parse('https://api.example.com/health')),
    ],
    enableLogging: true,
    logLevel: Level.INFO,
  ),
  child: const MyApp(),
)

All QueryDefaults values apply globally but are overridable on each controller.

Network Modes

Mode Behaviour
NetworkMode.online Pauses fetching when offline, resumes on reconnect
NetworkMode.always Fetches regardless of network status
NetworkMode.offlineFirst Executes once without network check, then requires connectivity

Logging

// Enable via QueryDefaults
QueryDefaults(enableLogging: true, logLevel: Level.FINE)

// Or directly
QueryLogger.enable(level: Level.INFO, onLog: (record) => Sentry.addBreadcrumb(...));
QueryLogger.disable();

Example

A full example app demonstrating all features is in the example/ directory:

  • Posts tab — QueryController, QueryBuilder, MutationController<T, P> typed params, QueryClient.instance.update cache patching from mutation listeners, background polling, offline support
  • Products tab — InfiniteQueryController, setParams() live search, loadMore() on scroll, keepPreviousData, updateInfiniteQuery + prependItem after create, optimistic item removal
  • Widgets tab — live showcase of every widget: MultiQueryProvider, QueryConsumer, QuerySelector, InfiniteQueryListener, InfiniteQueryConsumer, InfiniteQuerySelector, MultiQueryListener, QueryObserver, and using mutation controllers with all Query* widgets
  • Issues tab — interactive before/after benchmarks for all v2.0.0 performance and memory optimizations; detailed documentation in example/lib/features/inefficiency_demos/OPTIMIZATIONS.md

Libraries

flutter_query_client