Interface IQuery<TArgs, TData>

Namespace

DotNetQuery.Core

Assembly

DotNetQuery.Core.dll

A query that fetches data using the provided TArgs. Inherits all lifecycle members from IQuery.

public interface IQuery<TArgs, TData> : IQuery, IDisposable

Type Parameters

TArgs

The type of the parameters passed to the fetcher.

TData

The type of the data returned by the fetcher.

Inherited Members

IQuery.Key

IQuery.CacheTime

IQuery.Refetch()

IQuery.Cancel()

IQuery.Invalidate()

IDisposable.Dispose()

Properties

CurrentState

The current state snapshot. Can be read synchronously without subscribing.

QueryState<TData> CurrentState { get; }

Property Value

QueryState<TData>

Failure

Emits the Exception on each failed fetch.

IObservable<Exception> Failure { get; }

Property Value

IObservable<Exception>

Settled

Emits the final QueryState<TData> after each fetch completes, regardless of whether it succeeded or failed. Useful for hiding loading indicators.

IObservable<QueryState<TData>> Settled { get; }

Property Value

IObservable<QueryState<TData>>

State

Emits on every state transition (e.g. Idle → Fetching → Success/Failed). Replays the latest state to new subscribers.

IObservable<QueryState<TData>> State { get; }

Property Value

IObservable<QueryState<TData>>

Success

Emits the unwrapped TData on each successful fetch.

IObservable<TData> Success { get; }

Property Value

IObservable<TData>

Methods

Detach()

Removes this query from the client cache while keeping active subscriptions alive. Use Dispose() to also tear down all subscriptions and release resources.

void Detach()

PrefetchAsync(TArgs, CancellationToken)

Warms the cache for args by fetching data immediately, before any observer subscribes via SetArgs(TArgs). If the cache already holds fresh data for the derived key, the fetch is skipped. Returns a Task that completes when the fetch settles (success or failure).

Task PrefetchAsync(TArgs args, CancellationToken cancellationToken = default)

Parameters

args TArgs

cancellationToken CancellationToken

Returns

Task

Select<TResult>(Func<TData, TResult>, IEqualityComparer<TResult>?)

Returns a derived observable that applies selector to each successfully fetched value and suppresses re-emissions when the selected result is equal according to comparer (defaults to Default). The underlying fetch and cache are unaffected — no additional fetches are triggered.

IObservable<TResult> Select<TResult>(Func<TData, TResult> selector, IEqualityComparer<TResult>? comparer = null)

Parameters

selector Func<TData, TResult>

A transform applied to each successful TData value.

comparer IEqualityComparer<TResult>

Equality comparer for TResult. When null, Default is used.

Returns

IObservable<TResult>

Type Parameters

TResult

The type produced by the selector.

SetArgs(TArgs)

Sets the args that drive the next fetch. When args change, the query switches to the cache entry for the newly derived key and triggers a fetch if the query is enabled.

void SetArgs(TArgs args)

Parameters

args TArgs

SetData(TData)

Directly writes data into the active cache entry as a success state, bypassing any in-flight fetch. Stamps the entry as fresh so stale-time is respected and an immediate re-fetch is not triggered. Useful for applying optimistic updates before a mutation completes.

void SetData(TData data)

Parameters

data TData

SetEnabled(bool)

Enables or disables the query. When false, fetching is suspended even if the query is invalidated or new args are pushed. Pass true to resume; the query will immediately re-evaluate its active key and trigger a fetch if one is pending.

void SetEnabled(bool enabled)

Parameters

enabled bool