Skip to content

v1.4.0

Choose a tag to compare

@donfreddy donfreddy released this 17 Nov 18:39
· 27 commits to main since this release

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 scope are 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 retry or discard. A discarded call settles with MutationDiscardedException, 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.mutationRegistry and MutationMeta (#71)
  • QoraClient.mutationQueue, QoraClientConfig.mutationQueue, registerMutation(scope:, isPermanent:) and MutationDiscardedException (#72)
  • Persistence of the queue in PersistQoraClient (#72)
  • MutationQueue.entries and entriesStream, MutationQueueBuilder, useMutationQueue() (#72)
  • QueryCache(canEvict:), a predicate that keeps an entry from LRU eviction (#64)

Fixed

  • A query's own QoraOptions.gcTime was ignored; it now applies per query (#70)
  • Per-query QoraOptions now inherit QoraClientConfig.defaultOptions: a global retryCount: 0 no longer becomes 3 when a query passes QoraOptions(staleTime: ...) (#65)
  • Infinite queries now apply retryCondition, stop retrying after dispose(), and useInfiniteQuery retries next pages like the first one, drops late pages and clears error after a success (#63, #69)
  • A paused query whose fetch failed on reconnect no longer crashes the current Zone or 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 throwing transformError, errorMapper or model ==, no longer leaves the query stuck in Loading (#64)
  • FetchStatus no longer reports idle while 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 to onBackgroundFetchError. If you awaited prefetch to catch its error, use fetchQuery.
  • onBackgroundFetchError fires once per failed background fetch, and no longer for cancellations or offline pauses.
  • PersistQoraClient.clearStorage() and clear() delete only the keys Qora wrote (#60). To wipe a shared adapter, call clear() on the adapter.
  • The QoraOptions constructor 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 example QoraOptions(staleTime: Duration.zero).
  • QoraMutationBuilder.mutator is nullable, and optional when mutationKey names a registered mutation.
  • OfflineMutationQueue.stopOnFirstError is deprecated: it never had an effect. Use a registered mutation with a scope.
dependencies:
  qora_flutter: ^1.4.0
  # qora_hooks: ^1.4.0

Full changelogs: qora, qora_flutter, qora_hooks.