tanstack_query library

Flutter implementation of TanStack Query patterns: fetching, caching, invalidation, and background updates. Exports hooks and core types used by Flutter widgets.

Classes

DefaultOptions
Container for default query and mutation options.
FetchContext<T>
A mutable context object passed to QueryBehavior.onFetch.
FetchMeta
Metadata passed to a fetch to indicate pagination behavior.
FetchMore
Metadata for fetching more pages.
FocusManager
FocusManager mirrors the JS focusManager behavior: it is subscribable and allows registering a platform-specific event listener which calls setFocused to notify subscribers of focus changes.
InfiniteQueryBehavior<T>
Flutter port of React's infiniteQueryBehavior().
InfiniteQueryOptions<T>
Options specific to infinite queries.
InfiniteQueryResult<T>
Result type returned by useInfiniteQuery, with helper fetchNextPage and isFetchingNextPage flag.
MutateOptions<T>
Per-mutation call options passed to mutate.
Mutation<T, P>
A single mutation instance that holds its state and notifies observers on lifecycle events.
MutationAction<T>
MutationCache
Mutation cache that stores mutation instances and allows subscribing to mutation lifecycle events. It mirrors the JS MutationCache API.
MutationCacheConfig
Configuration callbacks for mutation lifecycle events such as onMutate, onSuccess, and onError.
MutationCacheNotifyEvent
Notification event emitted by MutationCache.subscribe.
MutationDefaultOptions
Default options placeholder for mutations.
MutationFunctionContext
Context object provided to mutation callbacks. Contains the client and an optional mutationKey which is the serialized cache-key produced by queryKeyToCacheKey when a mutationKey list is supplied to useMutation.
MutationObserver<T, P>
Observer that mirrors the JS MutationObserver. It can be subscribed to by multiple listeners and will reflect the state of the underlying active Mutation instance.
MutationObserverResult<T, P>
The shape returned by an observer to listeners.
MutationOptions<T, P>
Options used to create a Mutation/Observer.
MutationResult<T, P>
MutationState<T>
Represents the current state of a mutation operation.
OnlineManager
OnlineManager mirrors the JS onlineManager behavior: subscribable with custom event listener and setOnline / isOnline helpers.
Query<T>
Minimal Query implementation to centralize fetch and observer logic.
QueryBehavior<T>
QueryCache
Query cache that stores cache entries and provides utilities to find/subscribe/clear entries. It is intended to be owned by a QueryClient instance.
QueryCacheConfig
Configuration callbacks for query cache events like onError, onSuccess and onSettled.
QueryCacheEntry<T>
A cache entry storing the last query result, a timestamp and optionally a running queryFnRunning future.
QueryCacheNotifyEvent
A notification event emitted by QueryCache.
QueryClient
Core client that owns the cache and provides utilities to invalidate, set, and notify query data. Prefer obtaining the active client via useQueryClient() (with QueryClientProvider) in hooks and widgets; a
QueryClientContext
A lightweight holder used to provide a QueryClient instance to the widget subtree via Provider<QueryClientContext>.
QueryClientProvider
Provides a QueryClient to its descendants.
QueryDefaultOptions
Default options applied to queries (enabled, staleTime, refetch policy).
QueryObserver<TQueryFnData, TError, TData>
A simplified QueryObserver that mirrors the behavior of the JS implementation insofar as it maintains a current result based on a Query, can be subscribed to by multiple listeners, and can trigger refetch.
QueryOptions<T>
QueryResult<T>
Represents the current state of a query, including status, optional data, error and whether a fetch is ongoing.
Retryer<T>
TrackedFuture<T>
Simple wrapper to track whether a Future has completed or failed. Used by the cache to detect running or errored fetches.

Enums

FetchDirection
Direction for infinite pagination fetches.
MutationActionType
Action emitted by a Mutation to observers.
MutationStatus
Status values for mutations.
NotifyEventType
Types of events emitted by the cache.
QueryCacheEventType
The kinds of events emitted by the query cache.
QueryStatus
Status values for queries.

Properties

focusManager → FocusManager
final
onlineManager → OnlineManager
final

Functions

customEncode(dynamic item) → dynamic
Converts enum values and other items into a string form suitable for JSON encoding by queryKeyToCacheKey.
hasNextPage<T>(InfiniteQueryOptions<T> options, List<T>? data) → bool
hasPreviousPage<T>(InfiniteQueryOptions<T> options, List<T>? data) → bool
queryKeyToCacheKey(List<Object> queryKey) → String
Serializes a queryKey into a deterministic string usable as a cache key.
resetValues<T>(ObjectRef<int> currentPage, int initialPageParam, ValueNotifier<InfiniteQueryResult<T>> result, {bool isLoading = false}) → void
Resets the pagination and result state for an infinite query. Parameters:
useInfiniteQuery<T>({required List<Object> queryKey, required Future<T?> queryFn(int pageParam), bool? enabled, required int initialPageParam, int? getNextPageParam(T lastResult)?, double? staleTime, bool? refetchOnWindowFocus, bool? refetchOnReconnect, bool? refetchOnMount, int? gcTime, dynamic retry, bool? retryOnMount, dynamic retryDelay, Object? initialData, Object? initialDataUpdatedAt, Object? placeholderData, int? getPreviousPageParam(T firstResult)?}) → InfiniteQueryResult<T>
Hook for paginated/infinite queries.
useMutation<T, P>({required Future<T> mutationFn(P), List<Object>? mutationKey, void onSuccess(T?, [MutationFunctionContext? context])?, void onError(Object?, [MutationFunctionContext? context])?, void onSettled(T?, Object?, [MutationFunctionContext? context])?, dynamic retry, dynamic retryDelay, int? gcTime}) → MutationResult<T, P>
Hook to perform mutations (writes) and track mutation state.
useQuery<T>({required List<Object> queryKey, required Future<T> queryFn(), int? gcTime, bool? enabled, Object? initialData, Object? initialDataUpdatedAt, Object? placeholderData, bool? refetchOnMount, bool? refetchOnReconnect, bool? refetchOnWindowFocus, dynamic retry, bool? retryOnMount, dynamic retryDelay, double? staleTime}) → QueryResult<T>
Subscribe to a query identified by queryKey and manage its lifecycle.
useQueryClient() → QueryClient
Returns the nearest QueryClient provided by QueryClientProvider.

Typedefs

FocusListener = void Function(bool focused)
InitialDataFn<T> = T? Function()
Typedef for a function that returns initial data (used by initialData).
InitialDataUpdatedAtFn = int? Function()
Typedef for a function that returns the initialDataUpdatedAt timestamp.
MutationCacheListener = void Function(MutationCacheNotifyEvent event)
Listener signature for cache-level notifications.
MutationObserverListener<T, P> = void Function(MutationObserverResult<T, P>)
Listener type for mutation observers.
OnlineListener = void Function(bool online)
PlaceholderDataFn<T> = T? Function(T? previousValue, dynamic previousQuery)
Typedef for placeholder data function: takes previous value and previous query (observer-only) and returns a value.
QueryCacheListener = void Function(QueryCacheNotifyEvent event)
Listener signature for cache-level notifications.
QueryObserverListener<T, E> = void Function(QueryResult<T>)
Listener typedef used by QueryObserver.

Exceptions / Errors

CancelledError
Exception thrown when a query or mutation is cancelled.