query library

Cached server state, queries, mutations and hydration.

Classes

MutationContext
A mutation receives the actual transport deadline for this attempt.
MutationController<T, V>
Framework-independent mutation observer; each invocation runs exactly once. Concurrent calls are permitted. Only the latest call updates the snapshot.
MutationOptions<T, V>
Lifecycle callbacks run even after the initiating component unmounts, so cache invalidation completes. Keep UI-only effects outside these callbacks.
MutationSnapshot<T>
QueryClient
Shared query cache. Create one per SSR request and one per browser identity. Dispose on logout/identity changes; never share a server instance globally.
QueryClientProvider
Provides an explicitly owned cache. The caller disposes client on identity changes and, on the server, after response rendering. Hydrate it before mount.
QueryCodec<T>
Explicit wire codec for SSR. Do not serialize tokens or errors in query data.
QueryFunctionContext
Inputs supplied to a repository query, including its per-attempt deadline.
QueryKey
Immutable, canonical JSON key. Map order is ignored; list order is significant. Include all filters, pagination and identity-dependent inputs in the key.
QueryObserver<T>
Cache entry and framework-independent observer. Subscriptions own no server I/O.
QueryOptions<T>
Transport-neutral query definition. Retries are opt-in AND require readOnly. A repository must enforce timeout on its actual request, using the context.
QueryResult<T>
Query state plus an explicit refetch operation, which propagates failures.
QuerySignal
Cooperative cancellation. Transports should register their cancellation API.
QuerySnapshot<T>
Immutable observable query state. Data can coexist with a refetch error.

Enums

MutationStatus
State of the latest mutation invocation. Mutations never retry automatically.
QueryFetchStatus
QueryStatus

Functions

defaultQueryRetryDelay(int failureCount) → Duration
useMutation<T, V>(MutationOptions<T, V> options) → MutationController<T, V>
Owns mutation state until unmount. No mutation starts during SSR. Options update on rebuild; each invocation retains the callbacks it started with.
useQuery<T>(QueryOptions<T> options, {QueryClient? client}) → QueryResult<T>
Subscribes to a keyed query. SSR only reads prefetched cache data and starts no I/O, subscriptions or timers. Hydrate the cache before the first client render for matching HTML; subscriptions/fetching activate after that frame. Key changes unsubscribe the old query. The last observer cancels its fetch.
useQueryClient() → QueryClient
Reads the nearest cache without allocating one. Works during SSR.
useQueryLifecycle(QueryClient client) → void
Installs one browser focus/reconnect bridge per app cache. No work on SSR; removes listeners on unmount or client replacement. Call once in the shell.

Exceptions / Errors

QueryCancelled
A cancelled query must never publish a late result into the cache.