MutationParameters<T>

Describes one execution of a Mutation<T>: what to run and which callbacks to invoke.

public class MutationParameters<T>

Mutation functions#

Set exactly one. Precedence when several are set: CancellableMutationFunction > MutationFunction > CancellableVoidMutationFunction > VoidMutationFunction. Only the value-returning shapes write Data. Supplying none throws an ArgumentException.

Property TypeDefaultDescription
MutationFunction Func<Task<T>>?<code>null</code>The mutation to run. Takes precedence over VoidMutationFunction.
VoidMutationFunction Func<Task>?<code>null</code>A mutation without a return value; used when MutationFunction is not set.
CancellableMutationFunction Func<CancellationToken, Task<T>>?<code>null</code>The mutation to run, receiving a cancellation token. Takes precedence over every other shape. The token is cancelled when the owning component is disposed.
CancellableVoidMutationFunction Func<CancellationToken, Task>?<code>null</code>A cancellation-aware mutation without a return value.

Callbacks and control#

Property TypeDefaultDescription
CancellationToken CancellationToken?<code>null</code>Caller-owned lifetime token; null means the owning component's lifetime token. A value set here replaces the ambient token rather than combining with it.
OnSuccessAsync / OnSuccess Func<T?, Task>? / Action<T?>?—Invoked when the mutation succeeds. The async form is awaited before InvalidateKeys runs and before Execute completes, so follow-up queries or mutations can be chained from it.
OnErrorAsync / OnError Func<Exception, Task>? / Action<Exception>?—Invoked when the mutation fails.
OnDisplayUserErrorAsync / OnDisplayUserError Func<DisplayUserException, Task>? / Action<DisplayUserException>?—Invoked when the mutation fails with a DisplayUserException.
OnSettledAsync / OnSettled Func<T?, Task>? / Action<T?>?—Invoked when the mutation settles (success or failure; not cancellation).
Client DejaClient?<code>null</code>Cache client override for this execution; usually left null.
InvalidateKeys IReadOnlyList<QueryKey>?<code>null</code>Keys to invalidate (prefix-matched) after the mutation succeeds and OnSuccess has run. Every mounted query under them refetches in the background. Ignored without a registered client.

Example#

await _addTodo.Execute(new MutationParameters<Todo>
{
    CancellableMutationFunction = token => Api.AddTodoAsync(title, token),
    InvalidateKeys = [QueryKey.Of("todos")],
    OnError = e => _error = e.Message,
});