Examples

Case Study: Optimistic Mutations & Rollback

A complete optimistic update implementation: setQueryData for immediate UI feedback, restoreQueryData for automatic rollback on failure, and invalidateWhere for server reconciliation.

Objective

Context: Write operations introduce a latency problem. A round-trip to the server takes 1–3 seconds. Blocking the UI until the server responds produces sluggish interactions and breaks the perceived responsiveness of the application.

Optimistic updates resolve this by applying the expected result to the local cache immediately, before the server responds. If the server confirms the operation, the optimistic data is replaced by the authoritative server response. If the server rejects it, the cache is restored to its pre-mutation state.

This example implements the full optimistic update protocol using QoraMutationBuilder, setQueryData, and restoreQueryData. The simulated API fails ~30 % of the time to make rollback observable.

Key Features Demonstrated

QoraMutationBuilder<TData, TVariables, TContext>: manages MutationController lifecycle (create on mount, dispose on unmount), wires offline queue automatically
MutationOptions.onMutate: captures a pre-mutation cache snapshot (TContext) and applies setQueryData before the server call
MutationOptions.onError: calls restoreQueryData with the TContext snapshot to revert both affected cache entries simultaneously
MutationOptions.onSuccess: calls invalidateWhere to trigger background refetch and reconcile the cache with the server-confirmed state
Cross-cache optimistic update: a single mutation updates two independent cache entries (['users', id] and ['users']) atomically via TContext
MutationState pattern matching: four states (MutationIdle, MutationPending, MutationSuccess, MutationFailure) handled exhaustively with Dart 3 switch expressions
QoraBuilder + QoraMutationBuilder composition: read and write operations coexist on the same screen without shared mutable state

Architecture Highlights

The mutation lifecycle is entirely managed by QoraMutationBuilder. The widget tree declares intent; Qora coordinates cache, network, and state transitions:

ex_02_mutations_optimistic/lib/
├── main.dart                      ← QoraClient + QoraScope at root
├── models/
│   └── user.dart                  ← pure data class with copyWith
├── services/
│   └── fake_api.dart              ← async API (2 s latency, ~30 % failure on updateUser)
└── screens/
    ├── user_list_screen.dart      ← QoraBuilder<List<User>>, key: ['users']
    └── rename_user_sheet.dart     ← QoraMutationBuilder + three-step optimistic protocol

QoraClient is configured once at the root. UserListScreen reads the user list via QoraBuilder. The edit action captures context.qora and passes it explicitly to RenameUserSheet, since modal routes run in a separate navigator overlay:

lib/screens/user_list_screen.dart

Future<void> _showRenameSheet(BuildContext context, User user) {
  // Capture the client before the sheet opens: modal routes run in a
  // separate navigator overlay and may not resolve QoraScope on their own.
  final client = context.qora;
  return showModalBottomSheet<void>(
    context: context,
    isScrollControlled: true,
    useSafeArea: true,
    builder: (_) => RenameUserSheet(user: user, client: client),
  );
}

Implementation Details

The three-step optimistic update protocol

Every optimistic mutation follows three sequential hooks defined in MutationOptions. The type parameters encode the domain types precisely:

TData = User: value returned by the server on success
TVariables = ({String id, String name}): input to the mutator
TContext = ({User? user, List<User>? list}): pre-mutation snapshot for rollback