BloomMutation<T, P> class

Asynchronous mutation manager with automated optimistic updates, automatic rollback, and cache invalidation.

BloomMutation orchestrates side-effecting operations (such as HTTP POST, PUT, DELETE):

• Optimistic Updates: Immediately writes anticipated state changes into the BloomData cache via optimisticData before the network response completes.
• Automated Rollback: If the network call fails or throws, BloomMutation automatically reverts the cache entry at optimisticKey to its exact pre-mutation snapshot.
• Cache Invalidation: Automatically calls BloomData.invalidateQueries for all keys in invalidateKeys upon successful completion, triggering background refetches in active BloomQuery instances.
• Reactive Signals: Exposes data, status, and error as ReadonlySignal instances, allowing UI components to track loading and error states reactively.

Execution Flow

1. status changes to MutationStatus.pending and error is cleared to null.
2. If optimisticKey and optimisticData are set, snapshot current cache data and apply optimistic update.
3. onMutate hook is executed; its returned value becomes the context.
4. mutateFn is executed with the supplied parameters.
5. On Success:
   • data is set to the resolved result, status becomes MutationStatus.success.
   • Cache queries in invalidateKeys are invalidated.
   • onSuccess and onSettled hooks are awaited.
6. On Error:
   • error is set to the thrown exception, status becomes MutationStatus.error.
   • If optimisticKey was modified, the cache is automatically rolled back to the pre-mutation snapshot.
   • onError and onSettled hooks are awaited.
   • mutateAsync rethrows the error, while mutate catches it and returns null.

Backend Behavior

• Browser (mount): Subscribed Live descriptors update reactively across pending, success, and error states.
• SSR (renderToHtml): Safe to instantiate. Initial state is MutationStatus.idle.

Example

final createTodo = mutation<Todo, String>(
  mutate: (title) => httpClient.post<Todo>('/todos', body: {'title': title}),
  optimisticKey: ['todos'],
  optimisticData: (title, oldTodos) => [
    ...?oldTodos as List<Todo>?,
    Todo(id: 'temp-id', title: title, done: false),
  ],
  invalidateKeys: [['todos']],
  onError: (err, title, context) => print('Failed to add todo: $err'),
);

BloomNode buildAddTodoForm() {
  return Div(
    children: [
      Button(
        text: 'Create',
        on: {'click': (e) => createTodo.mutate('Buy groceries')},
      ),
      Live(() => createTodo.isPending ? Span(text: ' Saving...') : Span(text: '')),
    ],
  );
}

See also:

• mutation, the convenience factory function for creating mutations.
• BloomQuery, for managing cached queries that this mutation invalidates.
• BloomData, the underlying cache manager.