ZenMutation<TData, TVariables> class

A reactive mutation that manages async data updates (creates/updates/deletes)

Example:

final loginMutation = ZenMutation<User, LoginArgs>(
  mutationFn: (args) => api.login(args),
  onSuccess: (user, args) => print('Logged in as ${user.name}'),
  onError: (error, args) => print('Login failed: $error'),
);

// Trigger
loginMutation.mutate(LoginArgs('user', 'pass'));
Inheritance
Available extensions

Constructors

ZenMutation({required Future<TData> mutationFn(TVariables variables), String? mutationKey, FutureOr<Object?> onMutate(TVariables variables)?, void onSuccess(TData data, TVariables variables, Object? context)?, void onError(Object error, TVariables variables, Object? context)?, void onSettled(TData? data, Object? error, TVariables variables, Object? context)?, int retryCount = 0, Duration retryDelay = const Duration(milliseconds: 200), RetryDelayFn? retryDelayFn, Duration maxRetryDelay = const Duration(seconds: 30), double retryBackoffMultiplier = 2.0, bool exponentialBackoff = true, bool retryWithJitter = true})

Properties

activeWatcherCount → int
Get count of active watchers (useful for debugging)
no setterinherited
childControllerCount → int
Get count of tracked child controllers for debugging
no setterinherited
childControllerStats → Map<String, int>
Get stats about child controllers
no setterinherited
createdAt → DateTime
no setterinherited
data → Rx<TData?>
Result data (null if not successful yet)
final
error → Rx<Object?>
Current error (null if no error)
final
exponentialBackoff → bool
Whether to use exponential backoff
final
hashCode → int
The hash code for this object.
no setterinherited
isDisposed → bool
no setterinherited
isError → bool
Whether the mutation failed
no setter
isInitialized → bool
no setterinherited
isLoading → RxBool
Whether the mutation is currently running
no setter
isReady → bool
no setterinherited
isSuccess → bool
Whether the mutation was successful
no setter
maxRetryDelay → Duration
Maximum delay for retries
final
mutationFn → Future<TData> Function(TVariables variables)
Function that performs the mutation
final
mutationKey → String?
Unique key for this mutation.
final
onError → void Function(Object error, TVariables variables, Object? context)?
Callback on error
final
onMutate → FutureOr<Object?> Function(TVariables variables)?
Callback before mutation executes (useful for optimistic updates). Returns a context object that is passed to onError and onSettled.
final
onSettled → void Function(TData? data, Object? error, TVariables variables, Object? context)?
Callback when mutation is finished (success or error) Useful for invalidating queries
final
onSuccess → void Function(TData data, TVariables variables, Object? context)?
Callback on success
final
reactiveObjectCount → int
Get count of tracked reactive objects for debugging
no setterinherited
reactiveStats → Map<String, int>
Get stats about reactive objects
no setterinherited
retryBackoffMultiplier → double
Multiplier for exponential backoff
final
retryCount → int
Number of retry attempts (default 0 for mutations)
final
retryDelay → Duration
Base delay between retries
final
retryDelayFn → RetryDelayFn?
Custom function to calculate retry delay
final
retryWithJitter → bool
Whether to add random jitter to retry delays
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
status → Rx<ZenMutationStatus>
Current status of the mutation
final

Methods

addDisposer(void disposer()) → void
Add a disposer function that will be called when the controller is disposed
inherited
addUpdateListener(String updateId, VoidCallback listener) → void
Register a listener for a specific update ID
inherited
condition<T>(ValueNotifier<T> obs, bool condition(T), void callback(T)) → ZenWorker
inherited
createEffect<T>({required String name}) → ZenEffect<T>
Create an effect that will be auto-disposed with this controller
inherited
createWorkerGroup() → ZenWorkerGroup
Create a managed worker group
inherited
createWorkers(List<ZenWorker Function()> creators) → List<ZenWorker>

Available on ZenController, provided by the ZenControllerWorkerExtension extension

Create multiple workers in one call
debounce<T>(ValueNotifier<T> obs, void callback(T), Duration duration) → ZenWorker
inherited
didChangeAppLifecycleState(AppLifecycleState state) → void
Override from WidgetsBindingObserver to handle app lifecycle
inherited
dispose() → void
Dispose the controller and clean up ALL resources - PREVENTS MEMORY LEAKS
inherited
disposeWorkers(List<ZenWorker> workers) → void

Available on ZenController, provided by the ZenControllerWorkerExtension extension

Dispose specific workers
ever<T>(ValueNotifier<T> obs, void callback(T)) → ZenWorker
Type-safe convenience worker methods
inherited
getResourceStats() → Map<String, dynamic>
Get comprehensive resource usage statistics
inherited
getWorkerStats() → Map<String, dynamic>
Get worker statistics for debugging/monitoring
inherited
interval<T>(ValueNotifier<T> obs, void callback(T), Duration duration) → ZenWorker
inherited
mutate(TVariables variables, {void onSuccess(TData data, TVariables variables)?, void onError(Object error, TVariables variables)?, void onSettled(TData? data, Object? error, TVariables variables)?}) → Future<TData?>
Execute the mutation.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
obs<T>(T initialValue) → Rx<T>
Create and auto-track a reactive variable - PREVENTS MEMORY LEAKS
inherited
obsList<T>([List<T>? initialValue]) → RxList<T>
Create and auto-track a reactive list - PREVENTS MEMORY LEAKS
inherited
obsMap<K, V>([Map<K, V>? initialValue]) → RxMap<K, V>
Create and auto-track a reactive map - PREVENTS MEMORY LEAKS
inherited
obsSet<T>([Set<T>? initialValue]) → RxSet<T>
Create and auto-track a reactive set - PREVENTS MEMORY LEAKS
inherited
once<T>(ValueNotifier<T> obs, void callback(T)) → ZenWorker
inherited
onClose() → void
User-defined cleanup hook - called before internal disposal
override
onDetached() → void
Called when the app is detached
inherited
onHidden() → void
Called when the app is hidden
inherited
onInactive() → void
Called when the app is inactive
inherited
onInit() → void
Internal method called by child controllers to auto-register with parent This is called automatically during child controller construction if a parent exists
inherited
onPause() → void
Called when the app is paused (goes to background)
inherited
onReady() → void
inherited
onResume() → void
Called when the app is resumed (comes back to foreground)
inherited
pauseAllWorkers() → void
Pause all workers managed by this controller
inherited
pauseSpecificWorkers(List<ZenWorker> workers) → void

Available on ZenController, provided by the ZenControllerWorkerExtension extension

Pause specific workers
removeUpdateListener(String updateId, VoidCallback listener) → void
Remove a listener for a specific update ID
inherited
reset() → void
Reset the mutation state to idle.
resumeAllWorkers() → void
Resume all workers managed by this controller
inherited
resumeSpecificWorkers(List<ZenWorker> workers) → void

Available on ZenController, provided by the ZenControllerWorkerExtension extension

Resume specific workers
throttle<T>(ValueNotifier<T> obs, void callback(T), Duration duration) → ZenWorker
inherited
toString() → String
A string representation of this object.
inherited
trackController<T extends ZenController>(T controller) → T
Track a child controller (like ZenQuery, ZenStreamQuery) for automatic disposal
inherited
trackReactive(Rx reactive) → void
Manually track a reactive object (for external reactive objects)
inherited
update([List<String>? updateIds]) → void
Optimized update method that can notify specific listeners or all listeners
inherited
watch<T>(ValueNotifier<T> observable, void callback(T), {WorkerType type = WorkerType.ever, Duration? duration, bool condition(T)?}) → ZenWorker
Create workers that auto-dispose with controller
inherited
when({required Widget idle(), Widget loading()?, Widget success(TData data)?, Widget error(Object error)?}) → Widget

Available on ZenMutation<TData, TVariables>, provided by the ZenMutationWhenExtension extension

Builds UI based on the current mutation state.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

activeMutations → RxInt
Number of currently running mutations globally.
final
anyMutating → bool
Returns true if ANY mutation is currently running.
no setter

Static Methods

activeMutationsForKey(String mutationKey) → int
Returns the number of currently running mutations with the given mutationKey.
isMutatingKey(String mutationKey) → bool
Returns true if a mutation with the given mutationKey is currently running.
listPut<TData>({required Object queryKey, String? mutationKey, required Future<TData> mutationFn(TData item), bool addToStart = true, void onSuccess(TData data, TData item, Object? context)?, void onError(Object error, TData item)?}) → ZenMutation<TData, TData>
Create a mutation that optimistically adds an item to a list.
listRemove<TData>({required Object queryKey, String? mutationKey, required Future<void> mutationFn(TData item), required bool where(TData item, TData toRemove), void onSuccess(TData item, Object? context)?, void onError(Object error, TData item)?}) → ZenMutation<void, TData>
Create a mutation that optimistically removes an item from a list.
listSet<TData>({required Object queryKey, String? mutationKey, required Future<TData> mutationFn(TData item), required bool where(TData item, TData updated), void onSuccess(TData data, TData item, Object? context)?, void onError(Object error, TData item)?}) → ZenMutation<TData, TData>
Create a mutation that optimistically updates an item in a list.
put<TData>({required Object queryKey, String? mutationKey, required Future<TData> mutationFn(TData value), void onSuccess(TData data, TData value, Object? context)?, void onError(Object error, TData value)?}) → ZenMutation<TData, TData>
Create a mutation that optimistically creates/adds a single value.
remove({required Object queryKey, String? mutationKey, required Future<void> mutationFn(), void onSuccess(Object? context)?, void onError(Object error)?}) → ZenMutation<void, void>
Create a mutation that optimistically removes/deletes a single value.
resetActiveCounters() → void
Reset all active mutation counters (primarily for testing and full reset).
set<TData>({required Object queryKey, String? mutationKey, required Future<TData> mutationFn(TData value), void onSuccess(TData data, TData value, Object? context)?, void onError(Object error, TData value)?}) → ZenMutation<TData, TData>
Create a mutation that optimistically updates a single value.