flutter_query 0.9.0

Fetch, cache, and sync server data with automatic state management and background updates, inspired by TanStack Query.

0.9.0 - 2026-06-24

• Expanded the experimental, pattern-matchable snapshot API (opt in via import 'package:flutter_query/experiments.dart';) to cover mutations and infinite queries alongside useQuery:

  • useMutation now returns a sealed MutationSnapshot with four variants matching MutationStatus (MutationIdle, MutationPending, MutationSuccess, MutationError), exposing non-null variables on every variant except idle.
  • useInfiniteQuery now returns a sealed InfiniteQuerySnapshot with InfiniteQueryPending, InfiniteQuerySuccess, and InfiniteQueryError variants, with page-level fetch flags on the base class.

  Because the experimental library reuses the canonical hook names, hide them when importing it alongside the main library:

  import 'package:flutter_query/flutter_query.dart'
      hide
          useQuery,
          useMutation,
          useInfiniteQuery;
  import 'package:flutter_query/experiments.dart';
  

  As part of this work, QuerySnapshot now exposes the activity axis via a single fetchStatus enum, with isFetching/isPaused/isIdle retained as derived conveniences. These types remain experimental and may change in a future minor release.

0.8.0 - 2026-06-23

• Added an experimental, Dart-idiomatic query API, opt in via import 'package:flutter_query/experiments.dart';. It exposes a useQuery that returns a QuerySnapshot: a sealed hierarchy (QueryPending, QuerySuccess, QueryError) supporting exhaustive switch matching, with non-nullable data/error on the success/error variants and the activity axis exposed via isFetching/isPaused/isIdle.

  import 'package:flutter_query/flutter_query.dart' hide useQuery;
  import 'package:flutter_query/experiments.dart';
  
  final snapshot = useQuery(['user', id], () => fetchUser(id));
  final widget = switch (snapshot) {
    QueryPending() => const CircularProgressIndicator(),
    QuerySuccess(:final data) => Text(data.name),
    QueryError(:final error) => Text('$error'),
  };
  

  This API is annotated @experimental and may change in a future minor release.

0.7.0 - 2026-03-08

• Fixed crashes when multiple screens share the same query key (#40).

• Added ensureQueryData method to QueryClient. This method returns cached data if available (even if stale) or fetches it if missing. It also supports a revalidateIfStale option to trigger a background refetch if the cached data is stale.

• Exposed MutateFn typedef.

• BREAKING: Restored RefetchType enum. invalidateQueries() is now async again and accepts a refetchType parameter (defaults to RefetchType.active) to control which queries are automatically refetched after invalidation.

  // Invalidate and refetch active queries (default)
  await client.invalidateQueries(queryKey: ['users']);
  
  // Invalidate without refetching
  client.invalidateQueries(
    queryKey: ['users'],
    refetchType: RefetchType.none,
  );
  

0.6.0 - 2026-02-03

This release contains breaking changes to improve API consistency and usability.

• Added useMutationState hook that returns mutation states from the mutation cache. Useful for tracking mutation progress across your application.

  // Get all mutation states
  final states = useMutationState();
  
  // Filter by mutation key
  final todoMutations = useMutationState(mutationKey: ['todos']);
  
  // Filter with predicate (e.g., pending mutations)
  final pending = useMutationState(
    predicate: (key, state) => state.status == MutationStatus.pending,
  );
  

• Added networkMode option to useQuery, useInfiniteQuery, and useMutation for controlling behavior based on network connectivity. Requires passing a connectivityChanges stream to QueryClient.

  • NetworkMode.online (default): Pauses when offline, resumes when online
  • NetworkMode.always: Never pauses, ignores network state
  • NetworkMode.offlineFirst: First execution runs regardless of network, retries pause when offline

• Added useIsFetching hook that returns the count of queries currently fetching.

• Added useIsMutating hook that returns the count of mutations currently pending.

• BREAKING: The mutate function returned by useMutation is now fire-and-forget. It returns void and does not throw errors. Use mutateAsync to await the result or handle errors directly.

  // Before
  final result = useMutation(...);
  try {
    final data = await result.mutate(variables);
  } catch (e) {
    // handle error
  }
  
  // After (fire-and-forget)
  result.mutate(variables); // returns void, errors handled via onError callback
  
  // After (async with error handling)
  try {
    final data = await result.mutateAsync(variables);
  } catch (e) {
    // handle error
  }
  

• Added refetchOnReconnect option to useQuery and useInfiniteQuery for controlling refetch behavior when network connectivity is restored. Requires passing a connectivityChanges stream to QueryClient.

• Added meta property to DefaultQueryOptions and DefaultMutationOptions for setting default metadata across all queries and mutations. This metadata is deep-merged with query/mutation-specific meta and observer meta.

• BREAKING: Simplified getQueryData<TData>() and getInfiniteQueryData<TData, TPageParam>() signatures by removing the TError generic type parameter. The error type is not needed when retrieving cached data.

  // Before
  final data = client.getQueryData<String, Error>(const ['key']);
  final infiniteData = client.getInfiniteQueryData<String, Error, int>(const ['key']);
  
  // After
  final data = client.getQueryData<String>(const ['key']);
  final infiniteData = client.getInfiniteQueryData<String, int>(const ['key']);
  

• BREAKING: QueryCache and MutationCache are no longer part of the public API. The cache and mutationCache constructor parameters have been removed from QueryClient. The caches are now created and managed internally.

• BREAKING: Query, Mutation, QueryObserver, and MutationObserver are no longer part of the public API.

• BREAKING: Renamed InfiniteQueryObserverOptions to InfiniteQueryOptions.

• Fixed gc timer to start after fetch completes rather than at query creation time.

• Added resetQueries method on QueryClient for resetting queries to their initial state. Unlike invalidateQueries (which marks queries as stale), resetQueries completely resets the query state - queries with seed data are reset to that seed, while queries without seed have their data cleared. Active queries are automatically refetched after reset.

• Added removeQueries method on QueryClient for removing queries from the cache. Unlike invalidateQueries, removed queries are completely discarded and must be fetched from scratch when accessed again.

• Added getQueryState method on QueryClient for retrieving the full query state (status, error, dataUpdatedAt, etc.) instead of just the data.

• Added setQueryData method on QueryClient for imperatively setting or updating cached query data. Useful for optimistic updates in mutation callbacks.

• BREAKING: fetchQuery, prefetchQuery, fetchInfiniteQuery, and prefetchInfiniteQuery now take queryKey and queryFn as positional parameters instead of named parameters.

  // Before
  await client.fetchQuery<String, Object>(
    queryKey: const ['users', id],
    queryFn: (context) async => fetchUser(id),
  );
  
  // After
  await client.fetchQuery<String, Object>(
    const ['users', id],
    (context) async => fetchUser(id),
  );
  

• BREAKING: Predicate callbacks now receive immutable QueryState and MutationState objects instead of Query and Mutation instances, with the key passed as a separate first parameter.

  // Before
  client.invalidateQueries(predicate: (query) => query.key.first == 'users');
  
  // After
  client.invalidateQueries(predicate: (key, state) => key.first == 'users');
  

• BREAKING: MutationFunctionContext.meta is now a non-nullable Map<String, dynamic> (defaults to an empty map when not provided in options).

• BREAKING: The queryClient parameter on useQuery, useMutation, and useInfiniteQuery hooks has been renamed to client for simplicity.

• BREAKING: QueryClientProvider API changed. The client parameter has been replaced with a create factory function. Use QueryClientProvider.value() for existing clients.

  // Before
  QueryClientProvider(
    client: queryClient,
    child: MyApp(),
  )
  
  // After (managed lifecycle)
  QueryClientProvider(
    create: (context) => QueryClient(),
    child: MyApp(),
  )
  
  // After (existing client)
  QueryClientProvider.value(
    queryClient,
    child: MyApp(),
  )
  

• QueryClientProvider now supports lazy initialization via the lazy parameter

• QueryClientProvider now automatically clears the QueryClient when removed from the widget tree (when using the default constructor)

0.5.1 - 2026-01-14

This release adds support for infinite/paginated queries.

• useInfiniteQuery hook for paginated data fetching with automatic page accumulation
• fetchNextPage and fetchPreviousPage for bidirectional pagination
• hasNextPage and hasPreviousPage state for pagination controls
• maxPages option to limit the number of accumulated pages
• Full support for all standard query options (caching, refetching, retry, etc.)

0.4.0 - 2026-01-08

This release aligns the API with TanStack Query v5.

• useQuery hook for data fetching with caching, refetching, and cancellation
• useMutation hook for mutations with optimistic updates
• useQueryClient hook for imperative cache operations
• Client-level default options for queries and mutations

0.3.7 and earlier

Legacy codebase. Not maintained.