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.