MutationBuilder

The MutationBuilder handles data updates (CRUD) in your app. Unlike queries, mutations are not cached but can trigger cache invalidations or updates.

Usage


import 'package:fasq/fasq.dart';
 
MutationBuilder<Todo, String>(
  mutationFn: (text) => api.addTodo(text),
  options: MutationOptions(
    onSuccess: (newTodo) {
      // Invalidate the 'todos' query so it refetches
      QueryClient().invalidateQuery('todos'.toQueryKey());
    },
  ),
  builder: (context, state, mutate) {
    return Column(
      children: [
        if (state.hasError) Text('Error: ${state.error}'),
        
        ElevatedButton(
          // Pass data to the mutation
          onPressed: () => mutate('New Todo Item'),
          child: state.isLoading 
              ? const CircularProgressIndicator() 
              : const Text('Add Todo'),
        ),
      ],
    );
  },
)

API

Parameters

Name	Type	Required	Description
`mutationFn`	`Future<T> Function(V)`	Yes	function that performs the desired action.
`builder`	`Widget Function(BuildContext, MutationState<T>, MutateFunction<V>)`	Yes	Builds the UI. Provides the state and a function to trigger the mutation.
`options`	`MutationOptions<T, V>?`	No	Callbacks for success, error, and optimistic updates.

MutationState Properties

Property	Type	Description
`data`	`T?`	The result of the mutation.
`error`	`Object?`	The error if the mutation failed.
`status`	`MutationStatus`	`idle`, `loading`, `success`, or `error`.
`isLoading`	`bool`	True while the mutation is running.

Examples

Optimistic Updates

Update the UI before the server responds for a snappy experience.


MutationBuilder<Todo, Todo>(
  mutationFn: (todo) => api.updateTodo(todo),
  options: MutationOptions(
    // Runs before the mutation function
    onMutate: (newTodo, _) {
       final client = QueryClient();
       // 1. Cancel ongoing queries
       client.cancelQuery('todos'.toQueryKey());
       
       // 2. Snapshot previous value
       final prevTodos = client.getQueryData('todos'.toQueryKey());
       
       // 3. Optimistically update cache
       client.setQueryData(
         'todos'.toQueryKey(), 
         (old) => (old as List).map((t) => t.id == newTodo.id ? newTodo : t).toList()
       );
       
       // Return context to rollback if needed (optional)
       return {'prevTodos': prevTodos};
    },
    onError: (err, newTodo, context) {
       // Rollback on error
       if (context != null) {
         QueryClient().setQueryData('todos'.toQueryKey(), context['prevTodos']);
       }
    },
    onSettled: (_, __, ___, ____) {
       // Always refetch to ensure sync
       QueryClient().invalidateQuery('todos'.toQueryKey());
    }
  ),
  builder: (context, state, mutate) {
    // ...
  }
)

Form Submission with Side Effects


MutationBuilder<User, Map<String, dynamic>>(
  mutationFn: (data) => api.createUser(data),
  options: MutationOptions(
    onSuccess: (user) {
      Navigator.of(context).pop();
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Welcome ${user.name}!')),
      );
    },
  ),
  builder: (context, state, mutate) {
    return ElevatedButton(
      onPressed: () {
        if (formKey.currentState!.validate()) {
          mutate({'name': nameController.text});
        }
      },
      child: Text('Create Account'),
    );
  },
)