Class MutationOptions<TArgs, TData, TProgress>

Namespace

Fetchling.Core

Assembly

Fetchling.Core.dll

Configuration options for a progress-reporting mutation created via CreateMutation<TArgs, TData, TProgress>(MutationOptions<TArgs, TData, TProgress>). Identical to MutationOptions<TArgs, TData> except that the Mutator also receives an IProgress<T>, whose latest value surfaces as Progress.

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

Type Parameters

TArgs

The type of the arguments passed to the mutator.

TData

The type of the data returned on success.

TProgress

The type of the progress values the mutator reports (e.g. bytes sent).

Inheritance

object

MutationOptions<TArgs, TData, TProgress>

Implements

IEquatable<MutationOptions<TArgs, TData, TProgress>>

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 an IProgress<T> to report progress through, and a CancellationToken that is cancelled when the mutation is cancelled or disposed.

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

Property Value

Func<TArgs, IProgress<TProgress>, CancellationToken, Task<TData>>

Remarks

Each Report(T) emits a new Running state on State synchronously, on the reporting thread — it may be called from any thread. Reports are not throttled: a mutator that reports thousands of times per second emits that many states, so either report at a sensible granularity or sample the state stream in the UI.

Reports made after the attempt has ended — after it returned, threw, was cancelled, or was superseded by a retry or a newer execution — are ignored.

A retry calls the mutator again from the start, and progress resets accordingly. A mutator that consumes a one-shot input (a non-seekable Stream, say) cannot be retried unless it can re-open that input; set RetryHandler to a non-retrying handler if it can't.

Name

A short name used to tag metrics, traces, and log messages for this mutation (e.g. "uploadFile"). When null, typeof(TArgs).Name is used instead.

public string? Name { get; init; }

Property Value

string

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