Repository navigation
v1.4.0
Qora 1.4.0 adds a persisted mutation queue: writes made offline are stored, survive an app restart, and are sent in order when the network returns (RFC #59). It also fixes a series of fetch, prefetch and options bugs. No API is removed; a few behaviour changes are listed under Upgrade notes.
| Package | Version |
|---|---|
qora |
1.4.0 |
qora_flutter |
1.4.0 |
qora_hooks |
1.4.0 |
Highlights
Registered mutations. Declare a write once, by key, with a serializer for its variables. Its mutator receives a mutationId that stays the same across retries and restarts: send it as an idempotency key.
client.registerMutation<Todo, TodoInput>(
'todos.save',
mutator: (input, meta) => api.saveTodo(
input,
idempotencyKey: meta.mutationId,
),
variables: todoInputSerializer,
scope: (input) => 'todo:${input.id}',
isPermanent: (error) => error is ApiException && error.statusCode < 500,
);Call sites name the key and pass no mutator:
MutationOptions<Todo, TodoInput, void>(
mutationKey: 'todos.save',
offlineQueue: true,
)The mutation queue. Registered calls with offlineQueue: true go through client.mutationQueue, online or not:
- calls with the same
scopeare sent one at a time, in order; calls without one share a global lane; - transient failures are retried with backoff; losing the network mid-request does not count as an attempt;
- a permanent failure blocks its scope and holds the calls behind it, until the app calls
retryordiscard. A discarded call settles withMutationDiscardedException, so its rollback runs.
Persisted across restarts. PersistQoraClient stores each call before it counts as queued, and hydrate() restores the queue in stored order. clear() empties the queue before the cache, so logging out does not send or roll back the previous user's writes. Qora still touches only the storage keys it wrote.
Sync status in the UI. MutationQueueBuilder in qora_flutter and useMutationQueue() in qora_hooks rebuild with the queue's entries:
MutationQueueBuilder(
builder: (context, entries, child) => entries.isEmpty
? const SizedBox.shrink()
: Text('${entries.length} change(s) to sync'),
)A call with no caller left, restored after a restart or retried after its call site settled, reports to mutationEvents as queue:<mutationId>.
The offline-first example is rebuilt on the queue: client-generated ids, one scope per todo, a sync panel and a simulated restart. Guide: Offline & Network, case study: Offline-First Todo App.
Added
QoraClient.registerMutation,MutationOptions.mutationKey,QoraClient.mutationRegistryandMutationMeta(#71)QoraClient.mutationQueue,QoraClientConfig.mutationQueue,registerMutation(scope:, isPermanent:)andMutationDiscardedException(#72)- Persistence of the queue in
PersistQoraClient(#72) MutationQueue.entriesandentriesStream,MutationQueueBuilder,useMutationQueue()(#72)QueryCache(canEvict:), a predicate that keeps an entry from LRU eviction (#64)
Fixed
- A query's own
QoraOptions.gcTimewas ignored; it now applies per query (#70) - Per-query
QoraOptionsnow inheritQoraClientConfig.defaultOptions: a globalretryCount: 0no longer becomes 3 when a query passesQoraOptions(staleTime: ...)(#65) - Infinite queries now apply
retryCondition, stop retrying afterdispose(), anduseInfiniteQueryretries next pages like the first one, drops late pages and clearserrorafter a success (#63, #69) - A paused query whose fetch failed on reconnect no longer crashes the current
Zoneor skips the remaining replays (#63) - Fetches superseded by
invalidate(), evicted or removed while in flight no longer overwrite newer data or lose their result (#64) - A fetcher throwing
QoraCancelException, or a throwingtransformError,errorMapperor model==, no longer leaves the query stuck inLoading(#64) FetchStatusno longer reportsidlewhile a fetch for the key is paused offline (#64)
Upgrade notes
prefetch()no longer throws for a fetch failure: the failure is recorded in the query state and passed toonBackgroundFetchError. If you awaitedprefetchto catch its error, usefetchQuery.onBackgroundFetchErrorfires once per failed background fetch, and no longer for cancellations or offline pauses.PersistQoraClient.clearStorage()andclear()delete only the keys Qora wrote (#60). To wipe a shared adapter, callclear()on the adapter.- The
QoraOptionsconstructor parameters are nullable: a field left out falls back to the global value. If a query relied on the old reset, pass the default explicitly, for exampleQoraOptions(staleTime: Duration.zero). QoraMutationBuilder.mutatoris nullable, and optional whenmutationKeynames a registered mutation.OfflineMutationQueue.stopOnFirstErroris deprecated: it never had an effect. Use a registered mutation with ascope.
dependencies:
qora_flutter: ^1.4.0
# qora_hooks: ^1.4.0Full changelogs: qora, qora_flutter, qora_hooks.