Class MutationOptions<TArgs, TData>

Namespace

DotNetQuery.Core

Assembly

DotNetQuery.Core.dll

Configuration options for a single mutation created via CreateMutation<TArgs, TData>(MutationOptions<TArgs, TData>).

public sealed record MutationOptions<TArgs, TData> : IEquatable<MutationOptions<TArgs, TData>>

Type Parameters

TArgs

The type of the arguments passed to the mutator.

TData

The type of the data returned on success.

Inheritance

object

MutationOptions<TArgs, TData>

Implements

IEquatable<MutationOptions<TArgs, TData>>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

InvalidateKeys

A list of QueryKey values to invalidate automatically after a successful execution. null skips automatic invalidation.

public IReadOnlyList<QueryKey>? InvalidateKeys { get; init; }

Property Value

IReadOnlyList<QueryKey>

Remarks

Invalidation fires immediately when the Mutator task resolves. For eventually-consistent backends — read replicas, CQRS read models, async side-effects — the re-fetch may arrive before the write is visible and return stale data. In those cases use OnSuccess instead, where you control when to call QueryClient.Invalidate(...).

IsEnabled

Whether the mutation is initially enabled. Defaults to true. When false, calls to Execute(TArgs) are silently ignored.

public bool IsEnabled { get; init; }

Property Value

bool

Mutator

The async function that performs the mutation for the given args. Receives a CancellationToken that is cancelled when the mutation is cancelled or disposed.

public required Func<TArgs, CancellationToken, Task<TData>> Mutator { get; init; }

Property Value

Func<TArgs, CancellationToken, Task<TData>>

OnFailure

Invoked after each failed execution with the thrown exception. Called before OnSettled.

public Action<Exception>? OnFailure { get; init; }

Property Value

Action<Exception>

OnMutate

Invoked synchronously with the mutation args immediately before the mutator runs. Use this to snapshot the current cache state and apply an optimistic update via SetData(TData). On failure, restore the snapshot in OnFailure.

public Action<TArgs>? OnMutate { get; init; }

Property Value

Action<TArgs>

OnSettled

Invoked after every execution that reaches a terminal state: success, failure, or cancellation. Called after OnSuccess or OnFailure when applicable.

public Action? OnSettled { get; init; }

Property Value

Action

OnSuccess

Invoked after each successful execution with the original args and the returned data. Called before OnSettled.

public Action<TArgs, TData>? OnSuccess { get; init; }

Property Value

Action<TArgs, TData>

RetryHandler

Overrides the global RetryHandler. null uses the global default.

public IRetryHandler? RetryHandler { get; init; }

Property Value

IRetryHandler