query library

Platform-neutral asynchronous server-state for Dart and Flutter apps.

Classes

DehydratedMutation

A paused mutation that can be resumed after its keyed options are registered.

DehydratedQuery

One serializable query plus an optional in-memory pending channel.

DehydratedState

Transport-neutral Query snapshot shared by handoff and persistence.

InfiniteData<TPage, TPageParam>

Page data and the exact parameters that produced each page.

InfinitePageContext<TPage, TPageParam>

Input supplied while fetching one page.

InfiniteQueryObserver<TPage, TPageParam>

Observer for infinite-query controls; storage remains a normal Query entry.

InfiniteQueryOptions<TPage, TPageParam>

A typed infinite query definition backed by the ordinary Query runtime.

InfiniteQueryResult<TPage, TPageParam>

UI-facing result with pagination-specific transport flags.

Mutation<TData, TVariables, TOptimistic>

One concrete mutation execution.

MutationCache

Owns mutation executions, serial scopes, and persistence events.

MutationCacheEvent

One mutation cache change.

MutationContext

Input shared by mutation lifecycle callbacks.

MutationObserver<TData, TVariables, TOptimistic>

Reactive facade that tracks the latest execution of one mutation kind.

MutationOptions<TData, TVariables, TOptimistic>

Strongly typed definition for one mutation kind.

MutationState<TData, TVariables, TOptimistic>

Immutable state of one mutation execution.

PersistedQueryClient

Versioned persisted Query payload.

Query<T>

One asynchronous server-state machine stored by QueryCache.

QueryCache

Storage and event boundary for query state machines.

QueryCacheEvent

One query cache change.

QueryCancellationController

Creates and completes a cancellation token for one query fetch.

QueryCancelToken

A transport-neutral cancellation signal supplied to query functions.

QueryClient

Owns query and mutation caches for one app or one server request.

QueryClientModule

Installs a Query client into an application context.

QueryClientOptions

Options shared by every query and mutation client operation.

QueryContext<T>

Input supplied to a query function.

QueryEnvironment

Runtime classification used by retry and timer defaults.

QueryFetchMeta

Metadata describing a fetch beyond the query identity.

QueryFilter

Selects query cache entries for bulk operations.

QueryFocusManager

Mutable application-focus signal with no platform dependency.

QueryFreshness

Freshness semantics for cached data.

QueryInitialData<T>

Explicit initial data, including a valid null value.

QueryKey<T extends Object?>

A deterministic, serializable identity for one server-state resource.

QueryNeverStale

Data that only becomes stale through invalidation.

QueryObserver<T>

Reactive lifecycle around one Query cache entry.

QueryObserverHandle

Internal contract implemented by reactive query observers.

QueryOnlineManager

Mutable connectivity signal wired by an application or platform adapter.

QueryOptions<T>

A reusable, strongly typed query definition.

QueryPersistence

Restores a QueryClient and coalesces subsequent cache writes.

QueryPersister

Storage adapter implemented by files, preferences, databases, or memory.

QueryPolicy

Optional policy values layered by client defaults and a query definition.

QueryResult<T>

UI-facing projection of a query's two state axes.

QueryRetry

Retry decision independent from a particular transport.

QueryScheduler

Clock and timer seam used by tests, servers, and alternative runtimes.

QueryStaleAfter

Data that becomes stale after a duration.

QueryState<T>

Immutable state of one query cache entry.

QueryStaticData

Immutable data that cannot be invalidated.

ResolvedQueryOptions<T>

Fully resolved options owned by one query cache entry.

SystemQueryScheduler

Default wall-clock scheduler.

Enums

InfiniteDirection

Direction of one infinite-query page fetch.

MutationCacheEventType

Why mutation cache subscribers were notified.

MutationStatus

Lifecycle status of one mutation execution.

QueryActivity

Observer activity used when filtering queries.

QueryCacheEventType

Why a query cache subscription was notified.

QueryFetchStatus

Current transport activity.

QueryNetworkMode

Whether a fetch depends on network availability.

QueryRefetchPolicy

When an observer-driven lifecycle event may refetch.

QueryStatus

Data lifecycle independent from active transport state.

Properties

queryClientKey → ContextKey<QueryClient>

The application context key used to read the registered QueryClient.

final

Functions

defaultQueryRetryDelay(int failureCount, Object _) → Duration

Returns the default capped exponential retry delay.

dehydrate(QueryClient client, {QuerySerializeData serializeData = _identity, bool shouldDehydrateQuery(Query query)?, bool shouldDehydrateMutation(Mutation mutation)?, bool includePending = false, bool redactErrors = true}) → DehydratedState

Creates a snapshot suitable for server handoff or persistence.

hydrate(QueryClient client, DehydratedState dehydrated, {QueryDeserializeData deserializeData = _identity}) → void

Merges a snapshot without overwriting newer client data.

structurallyShare(Object? previous, Object? next, [int depth = 0]) → Object?

Deeply reuses unchanged JSON-like values from previous.

Typedefs

GlobalMutationError = FutureOr<void> Function(Object error, StackTrace stackTrace, Object? variables, Object? optimistic, Mutation mutation, MutationContext context)

Handles failed mutations across a cache.

GlobalMutationSuccess = FutureOr<void> Function(Object? data, Object? variables, Object? optimistic, Mutation mutation, MutationContext context)

Handles successful mutations across a cache.

InfiniteNextPage<TPage, TPageParam> = TPageParam? Function(TPage lastPage, List<TPage> pages, TPageParam lastPageParam, List<TPageParam> pageParams)

Selects the parameter for the page after the current last page.

InfinitePageFunction<TPage, TPageParam> = FutureOr<TPage> Function(InfinitePageContext<TPage, TPageParam> context)

Fetches one page of an infinite query.

InfinitePreviousPage<TPage, TPageParam> = TPageParam? Function(TPage firstPage, List<TPage> pages, TPageParam firstPageParam, List<TPageParam> pageParams)

Selects the parameter for the page before the current first page.

MutationFunction<TData, TVariables> = FutureOr<TData> Function(TVariables variables, MutationContext context)

Executes a mutation from typed variables.

MutationOnError<TVariables, TOptimistic> = FutureOr<void> Function(Object error, StackTrace stackTrace, TVariables variables, TOptimistic? optimistic, MutationContext context)

Runs after a mutation fails.

MutationOnMutate<TVariables, TOptimistic> = FutureOr<TOptimistic> Function(TVariables variables, MutationContext context)

Runs before a mutation and may return an optimistic value.

MutationOnSettled<TData, TVariables, TOptimistic> = FutureOr<void> Function(TData? data, Object? error, TVariables variables, TOptimistic? optimistic, MutationContext context)

Runs after a mutation settles with either data or an error.

MutationOnSuccess<TData, TVariables, TOptimistic> = FutureOr<void> Function(TData data, TVariables variables, TOptimistic? optimistic, MutationContext context)

Runs after a mutation succeeds.

QueryDataMerger<T> = T Function(T? previous, T next)

Custom reference-preserving data merger.

QueryDeserializeData = Object? Function(Object? data)

Restores query or mutation data from a transported value.

QueryDispose = void Function()

Unsubscribes a listener or background task.

QueryFunction<T> = FutureOr<T> Function(QueryContext<T> context)

Fetches one typed resource.

QuerySerializeData = Object? Function(Object? data)

Converts query or mutation data into a transport-safe value.

Exceptions / Errors

MutationCancelledException

Raised when a cached mutation is destroyed before its next attempt starts.

QueryCancelledException

Cancellation raised by Query without treating it as a request failure.