qora library

Qora — async state management for Dart, inspired by TanStack Query.

Quick start

import 'package:qora/qora.dart';

// 1. Create a client (one per app / DI scope)
final client = QoraClient(
  config: QoraClientConfig(
    defaultOptions: QoraOptions(staleTime: Duration(minutes: 5)),
    debugMode: true,
  ),
);

// 2a. One-shot fetch (with caching, deduplication, and retry)
final user = await client.fetchQuery<User>(
  key: ['users', userId],
  fetcher: () => api.getUser(userId),
);

// 2b. Reactive stream (auto-fetches, polls, emits all state transitions)
client.watchQuery<List<Post>>(
  key: ['posts'],
  fetcher: api.getPosts,
  options: QoraOptions(refetchInterval: Duration(seconds: 30)),
).listen((state) {
  switch (state) {
    case Success(:final data):  render(data);
    case Failure(:final error): showError(error);
    default: {}
  }
});

// 3. Optimistic update
final snapshot = client.getQueryData<User>(['users', userId]);
client.setQueryData(['users', userId], updated);
try {
  await api.updateUser(userId, payload);
} catch (_) {
  client.restoreQueryData(['users', userId], snapshot);
}

// 4. Invalidate after mutation
await api.createPost(payload);
client.invalidate(['posts']);

Classes

CacheEntry<T>: An entry in the query cache.
CancelToken: A cooperative cancellation signal for QoraClient.fetchQuery, QoraClient.watchQuery, and QoraClient.prefetch.
ConnectivityManager: Abstract interface for network connectivity observation.
Failure<T>: Failure state - fetch operation failed.
InfiniteData<TData, TPageParam>: Immutable container holding all fetched pages and their corresponding page parameters for an infinite query.
InfiniteFailure<TData, TPageParam>: A fetch failure, with optional previousData for graceful degradation.
InfiniteInitial<TData, TPageParam>: The query has not been executed yet.
InfiniteLoading<TData, TPageParam>: The initial page fetch is in progress (no pages loaded yet).
InfiniteQueryObserver<TData, TPageParam>: Manages the pagination lifecycle for a single infinite query.
InfiniteQueryOptions<TData, TPageParam>: Configuration for an infinite (paginated) query.
InfiniteQueryState<TData, TPageParam>: The state machine for an infinite (paginated) query.
InfiniteSuccess<TData, TPageParam>: All currently loaded pages, with pagination status flags.
Initial<T>: Initial state - query hasn't started yet.
InMemoryPersistence<T>: In-memory persistence (for testing).
InMemoryStorageAdapter: In-memory StorageAdapter backed by a plain Map.
LifecycleManager
Loading<T>: Loading state - actively fetching data.
MutationController<TData, TVariables, TContext>: Controls and tracks the lifecycle of a single mutation.
MutationEvent: An event emitted by QoraClient whenever a tracked MutationController changes state.
MutationFailure<TData, TVariables>: Failure state — mutation failed.
MutationIdle<TData, TVariables>: Idle state — no mutation has been run yet (or after MutationController.reset).
MutationOptions<TData, TVariables, TContext>: Configuration and lifecycle callbacks for a MutationController.
MutationPending<TData, TVariables>: Pending state — mutation is actively running.
MutationState<TData, TVariables>: Represents the state of a mutation operation.
MutationSuccess<TData, TVariables>: Success state — mutation completed successfully.
MutationTracker: Interface that receives mutation lifecycle notifications from a MutationController.
OfflineMutationQueue: A FIFO queue of PendingMutations accumulated while the device is offline.
OfflineReplayResult: Result of an OfflineMutationQueue.replay call.
PendingMutation: A mutation enqueued while the device was offline.
PersistQoraClient: A QoraClient that automatically persists query results to a StorageAdapter and restores them on startup (offline-first).
QoraClient
QoraClientConfig: Global configuration for QoraClient.
QoraKey: Immutable query key with validation and type safety.
QoraOptions: Per-query configuration that overrides global QoraClientConfig defaults.
QoraSerializer<T>: A pair of functions that convert a value of type T to and from a JSON-compatible representation.
QoraState<T>: Represents the state of a query operation.
QoraStateCodec<T>: Codec for encoding/decoding states with a specific data type.
QoraStatePersistence<T>: Persistence adapter for storing states.
QoraStateSerialization: Mixin for serializing and deserializing QoraState.
QoraStateUtils: Utility for handling multiple states.
QoraTracker: Observability interface injected into QoraClient to report cache and mutation lifecycle events.
QueryCache: Internal LRU cache that stores CacheEntry instances keyed by normalised query keys.
ReconnectStrategy: Controls how QoraClient replays paused queries when the device reconnects.
SharedPreferencesPersistence<T>: SharedPreferences persistence adapter.
SsrHydrator: No-op SsrHydrator for non-web platforms.
StorageAdapter: Low-level key/value storage contract for Qora persistence.
Success<T>: Success state - data fetched successfully.

Enums

FetchStatus: Indicates whether a query is currently executing a network request.
LifecycleState
MutationStatus: Coarse-grained status of a MutationState.
NetworkMode: Controls how a query or mutation behaves with respect to network status.
NetworkStatus: The network reachability status reported by a ConnectivityManager.
ReqryStatus: Simple status enum for cases where you don't need full state.

Extensions

MutationStateExtensions on MutationState<TData, TVariables>: Additional utility extensions on MutationState.
MutationStateStreamExtensions on Stream<MutationState<TData, TVariables>>: Stream extensions for MutationState.
QoraStateExtensions on QoraState<T>: Additional utility extensions for QoraState.
QoraStateFutureExtensions on Future<QoraState<T>>: Extension for working with Future<QoraState<T>>.
QoraStateSerializationX on QoraState<T>: Extension for easier serialization access.
QoraStateStreamExtensions on Stream<QoraState<T>>: Extension for working with Stream<QoraState<T>>.

Functions

normalizeKey(Object key) → List: Normalizes a polymorphic key input to parts.

Typedefs

InfiniteQueryFunction<TData, TPageParam> = Future<TData> Function(TPageParam pageParam): Fonction qui retourne une page de données pour une infinite query.
MutatorFunction<TData, TVariables> = Future<TData> Function(TVariables variables): Fonction de mutation
QoraKeyParts = List: Type alias for raw key parts (backwards compatibility).
QueryFilter = bool Function(String key, QoraState state, QoraOptions? lastOptions): The central engine of Qora — manages queries, cache, deduplication, retries, reactive state, and network-aware pausing / reconnect replay.
QueryFunction<T> = Future<T> Function(): Fonction qui retourne les données de la query

Exceptions / Errors

QoraCancelException: Thrown by QoraClient.fetchQuery or QoraClient.watchQuery when the associated CancelToken is cancelled before or during the fetch.
QoraException
QoraOfflineException: Thrown by QoraClient.fetchQuery when the device is offline, the query's NetworkMode is NetworkMode.online, and there is no cached data to return.

qora library

Quick start

Classes

Enums

Extensions

Functions

Typedefs

Exceptions / Errors

qora package

qora library