useMutationState function

List<MutationState> useMutationState({ List<Object?>? mutationKey, bool exact = false, bool predicate(List<Object?>? mutationKey, MutationState state)?, QueryClient? client, })

A hook that returns mutation states from the mutation cache.

This hook subscribes to the mutation cache and updates whenever any mutation is added, removed, or updated. Use it to track mutation state across your application.

The mutationKey filters which mutations to include. When exact is false (default), all mutations whose keys start with mutationKey are included. When true, only mutations with an exactly matching key are included.

The predicate function provides additional filtering based on mutation key and state. Only mutations for which it returns true are included.

The optional client parameter specifies which QueryClient to use. If not provided, the nearest QueryClientProvider ancestor is used.

Example:

Widget build(BuildContext context) {
  final mutations = useMutationState();

  return ListView(
    children: [
      for (final state in mutations)
        ListTile(
          title: Text('Status: ${state.status}'),
          subtitle: Text('Variables: ${state.variables}'),
        ),
    ],
  );
}

With filtering:

// Get mutations for a specific key
final todoMutations = useMutationState(mutationKey: ['todos']);

// Get pending mutations
final pending = useMutationState(
  predicate: (key, state) => state.status == MutationStatus.pending,
);

// Combine filters
final pendingTodos = useMutationState(
  mutationKey: ['todos'],
  predicate: (key, state) => state.status == MutationStatus.pending,
);

Implementation

List<MutationState> useMutationState({
  List<Object?>? mutationKey,
  bool exact = false,
  bool Function(List<Object?>? mutationKey, MutationState state)? predicate,
  QueryClient? client,
}) {
  final effectiveClient = useQueryClient(client);

  final getStates = useEffectEvent(() {
    return effectiveClient.mutationCache
        .findAll(
          mutationKey: mutationKey,
          exact: exact,
          predicate: predicate,
        )
        .map((mutation) => mutation.state)
        .toList();
  });

  final states = useState(getStates.call());

  // Recompute synchronously during build when filters change, so the updated
  // value is visible to the caller in the same frame (mirrors use_query.dart).
  final currentStates = getStates.call();
  if (!deepEq.equals(states.value, currentStates)) {
    states.value = currentStates;
  }

  useEffect(() {
    final unsubscribe = effectiveClient.mutationCache.subscribe((event) {
      if (event is MutationAddedEvent || event is MutationRemovedEvent || event is MutationUpdatedEvent) {
        final newStates = getStates.call();
        if (!deepEq.equals(states.value, newStates)) {
          states.value = newStates;
        }
      }
    });
    return unsubscribe;
  }, [effectiveClient]);

  return states.value;
}