queryx_riverpod library

Riverpod bindings for queryx.

Classes

AlwaysOnlineNetworkMonitor

Default no-op monitor: always reports online. Use this in tests or until a real connectivity adapter is wired up.

CacheEntry<T>

A single cached resource plus everything needed to decide freshness and eviction. One CacheEntry is shared by every observer of the same query key — this is what makes deduplication and cross-widget cache sharing work.

CachePersistenceConfig

CacheStorage

Storage abstraction for persisting cache entries to disk. The core package ships no implementation — plug in queryx_persistence (Hive, Isar, SQLite) or your own, so core stays dependency-free.

HttpClientAdapter

Transport-agnostic request/response contract. queryx never hard-codes to Dio — queryx_dio is the default adapter, but http, dart:io, or a fully custom client can implement this instead.

InfinitePage<T, P>

One fetched page: the items, plus whatever cursor/page-info the caller needs to request the next page. P is your own lightweight page-param type (an int page number, a cursor string, an offset, etc.) — queryx doesn't assume page-number vs cursor pagination (spec §21).

InfiniteQuery<T, P>

A query that accumulates pages as the user scrolls, rather than replacing data on each fetch (spec §22).

InfiniteQueryNotifier<T, P>

Bridges a queryx InfiniteQuery into Riverpod's StateNotifier.

InfiniteQueryxSnapshot<T, P>

Immutable snapshot of an InfiniteQuery's state.

Mutation<T, V, C>

A single write operation (POST/PUT/PATCH/DELETE). Unlike Query, mutations are not cached or deduplicated by key — each mutate call is a distinct, explicit action.

MutationNotifier<T, V, C>

Bridges a queryx Mutation into Riverpod's StateNotifier. Unlike queries, mutations don't auto-run — the widget calls mutate/mutateAsync explicitly (a button press, form submit, etc.).

MutationOptions<T, V, C>

Lifecycle callbacks for a Mutation, mirroring TanStack Query's well-tested optimistic-update contract:

MutationSnapshot<T>

Immutable snapshot of a Mutation's state.

NetworkMonitor

Reports connectivity so the engine can skip unnecessary requests while offline and resume (refetch/poll) when the connection returns. The core package ships a permanently-online default; plug a real adapter (connectivity_plus, platform channels, etc.) via NetworkMonitor.

Query<T>

The public, per-consumer handle to a query. Multiple Query instances for the same key all read/write through one shared QueryCore — this is what implements request deduplication and cross-widget cache sharing.

QueryClient

The single object that coordinates cache, queries, mutations, network state, and (optionally) auth token refresh for an app — or a portion of one; large apps can run multiple clients, one per backend.

QueryDebugInfo

QueryKey

A structured, deterministic identity for a query.

QueryNotifier<T>

Bridges a queryx Query (mutable, listener-based) into Riverpod's StateNotifier (immutable snapshots). This is the entire adapter — the core engine already does dedup/caching/retry/etc., so this class's only job is "when the query changes, emit a new snapshot."

QueryOptions<T>

Configuration for a single Query. Any field left null falls back to the QueryClient's default. Nothing here is "magic" — every behavior that affects network traffic (retry, polling, background refetch) is an explicit, documented option (spec §91: No Magic).

QueryxCancelToken

Cooperative cancellation handle. Adapters translate this into their own native cancellation (e.g. Dio's CancelToken) where the transport supports it.

QueryxLogger

Development-mode logger. Disabled by default in production — enable explicitly via QueryClient(logger: QueryxLogger(enabled: true)).

QueryxRequest

QueryxResponse

QueryxSnapshot<T>

Immutable snapshot of a Query's state at a point in time. This is what queryProvider actually emits — Riverpod diffs/rebuilds on this, not on the mutable Query handle itself.

RetryPolicy

Decides whether a failed attempt should be retried, and how long to wait before the next attempt. Sensible defaults only retry errors that are plausibly transient (network, timeout, 5xx) — never 4xx/validation, and never a cancelled request.

Serializer<T>

Per-type encode/decode so the persistence layer never needs generated code or reflection.

Enums

HttpMethod

NetworkStatus

QueryErrorType

Category of a normalized QueryError. Kept intentionally small and UI-actionable rather than mirroring every possible transport exception.

QueryStatus

Constants

sensitiveFieldNames → const List<String>

Fields that must never appear in debug logs, regardless of where they show up in a request/response (headers, body, etc.).

Properties

queryxClientProvider → Provider<QueryClient>

The QueryClient every queryProvider/mutationProvider in this app reads from. Override this once, near the root of your app:

final

Functions

defaultErrorMapper(Object error, StackTrace stackTrace) → QueryError

infiniteQueryProvider<T, P>(QueryKey key, {required PageFetcher<T, P> fetchPageBuilder(Ref<Object?> ref), P? initialPageParam}) → AutoDisposeStateNotifierProvider<InfiniteQueryNotifier<T, P>, InfiniteQueryxSnapshot<T, P>>

Creates an autoDispose StateNotifierProvider backed by a queryx InfiniteQuery.

mutationProvider<T, V, C>(MutationFn<T, V> fnBuilder(Ref<Object?> ref), {MutationOptions<T, V, C> optionsBuilder(Ref<Object?> ref)?}) → AutoDisposeStateNotifierProvider<MutationNotifier<T, V, C>, MutationSnapshot<T>>

Creates an autoDispose StateNotifierProvider backed by a queryx Mutation. The provider itself does nothing until a widget calls ref.read(myMutationProvider.notifier).mutate(variables) (typically from a button's onPressed).

queryProvider<T>(QueryKey key, Fetcher<T> fetcherBuilder(Ref<Object?> ref), {QueryOptions<T>? options}) → AutoDisposeStateNotifierProvider<QueryNotifier<T>, QueryxSnapshot<T>>

Creates an autoDispose StateNotifierProvider backed by a queryx Query.

Typedefs

ErrorMapper = QueryError Function(Object error, StackTrace stackTrace)

Converts a raw transport-layer exception (Dio, http, custom) into a normalized QueryError. Supply a custom mapper to QueryClient to support backend-specific error envelopes, e.g.:

Fetcher<T> = Future<T> Function()

MutationFn<T, V> = Future<T> Function(V variables)

PageFetcher<T, P> = Future<InfinitePage<T, P>> Function(P? pageParam)

QueryxLogSink = void Function(String message)

ShouldRetry = bool Function(QueryError error, int attempt)

Exceptions / Errors

QueryError

The single error shape that ever reaches application code. Adapters (Dio, http, custom) are responsible for translating their own exceptions into a QueryError via an ErrorMapper — the engine never leaks raw transport exceptions to the UI layer.