Trait Mutation 

pub trait Mutation<Input = ()>:
    Clone
    + PartialEq
    + 'static
where
    Input: Clone + PartialEq + 'static,
{
    type Output: Clone + PartialEq + Send + Sync + 'static;
    type Error: Clone + PartialEq + Send + Sync + 'static;

    // Required method
    fn mutate(
        &self,
        input: Input,
    ) -> impl Future<Output = Result<Self::Output, Self::Error>>;

    // Provided methods
    fn mutate_with_current(
        &self,
        input: Input,
        _current_data: Option<&Result<Self::Output, Self::Error>>,
    ) -> impl Future<Output = Result<Self::Output, Self::Error>> { ... }
    fn id(&self) -> String { ... }
    fn invalidates(&self) -> Vec<String> { ... }
    fn has_optimistic(&self) -> bool { ... }
    fn optimistic_updates(
        &self,
        _input: &Input,
    ) -> Vec<(String, Result<Self::Output, Self::Error>)> { ... }
    fn optimistic_updates_with_current(
        &self,
        _input: &Input,
        _current_data: Option<&Result<Self::Output, Self::Error>>,
    ) -> Vec<(String, Result<Self::Output, Self::Error>)> { ... }
}

Trait for defining mutations - operations that modify data

Mutations are similar to providers but are designed for data modification operations. They typically involve server requests to create, update, or delete data.

Usage

Prefer using the #[mutation] macro to define mutations. Manual trait implementations are for advanced use only.

Example

use dioxus_provider::prelude::*;

#[mutation(invalidates = [fetch_user, fetch_users])]
async fn update_user(user_id: u32, data: UserData) -> Result<User, String> {
    // Make API call to update user
    api_client.update_user(user_id, data).await
}

Required Associated Types

type Output: Clone + PartialEq + Send + Sync + 'static

The type of data returned on successful mutation

type Error: Clone + PartialEq + Send + Sync + 'static

The type of error returned on mutation failure

Required Methods

fn mutate( &self, input: Input, ) -> impl Future<Output = Result<Self::Output, Self::Error>>

Execute the mutation with the given input

Provided Methods

fn mutate_with_current( &self, input: Input, _current_data: Option<&Result<Self::Output, Self::Error>>, ) -> impl Future<Output = Result<Self::Output, Self::Error>>

Execute the mutation with access to current cached data This allows mutations to work with existing state instead of redefining data If not implemented, falls back to the simple mutate method

fn id(&self) -> String

Get a unique identifier for this mutation type

fn invalidates(&self) -> Vec<String>

Get list of provider cache keys that should be invalidated after successful mutation Override this to specify which providers should be refreshed after mutation

fn has_optimistic(&self) -> bool

Returns true if this mutation has optimistic updates configured Used by use_mutation to automatically detect and enable optimistic behavior

fn optimistic_updates( &self, _input: &Input, ) -> Vec<(String, Result<Self::Output, Self::Error>)>

Provide optimistic cache updates for immediate UI feedback Returns a list of (cache_key, optimistic_result) pairs to update the cache with This allows the UI to update immediately with the expected result The Result should contain the optimistic success value

fn optimistic_updates_with_current( &self, _input: &Input, _current_data: Option<&Result<Self::Output, Self::Error>>, ) -> Vec<(String, Result<Self::Output, Self::Error>)>

Compute optimistic updates with access to current cached data This is more efficient as it allows mutations to work with existing data instead of duplicating data structures

Return Value Usage

The mutation’s return value is used to update the cache directly on success, avoiding unnecessary provider refetches when using optimistic updates. When optimistic updates are defined, the actual server response replaces the optimistic value in the cache, keeping the UI in sync with the backend.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors