Query<T>

Tracks a single asynchronous read and exposes its lifecycle as bindable state, notifying its attached listener as it advances so the owning component can re-render.

public class Query<T> : DejaObservable, IDisposable

A newer Execute supersedes (and cancels) an older in-flight one, and concurrent calls sharing a key join the same execution instead of fetching twice. Inherit DejaComponentBase in the owning component and attachment is handled for you.

Constructors#

Query()#

public Query()

Creates a query that resolves its cache client from the owning component (if any).

Query(DejaClient)#

public Query(DejaClient client)

Creates a query bound to client, for use outside a component. Throws ArgumentNullException when client is null.

State#

Member	Type	Description
IsLoading	`bool`	True while any execution is loading.
IsError	`bool`	True when the most recent execution failed. Cleared by a successful refetch.
ErrorMessage	`string?`	The failure message of the most recent execution, when `IsError` is true.
Data	`T?`	The most recently fetched data.
ReFetchCount	`int`	How many times the query has been executed.
IsReFetching	`bool`	True while an execution after the first is loading. Use for subtle refresh indicators.
UpdatedAt	`DateTimeOffset?`	When the current `Data` was fetched (cached path only); null on the uncached path or before the first result.
IsCachedData	`bool`	True while `Data` was served from the cache and no fresh fetch has completed during this query's subscription.
IsStale	`bool`	True when the observed cache entry is invalidated or older than the effective stale time (cached path only; always false uncached).

Methods#

Execute (keyed shorthand)#

public Task Execute(QueryKey? key, Func<CancellationToken, Task<T>> queryFunction, Action<QueryParameters<T>>? configure = null)

Runs a keyed query — the shorthand for the common case, equivalent to the full form with QueryKey and QueryFunction set and anything else configured by the hook. A string converts implicitly to a key; pass null for the uncached path. Throws ArgumentNullException when queryFunction is null.

_todos.Execute("todos", Api.GetTodosAsync);

Execute (unkeyed shorthand)#

public Task Execute(Func<CancellationToken, Task<T>> queryFunction, Action<QueryParameters<T>>? configure = null)

Runs an unkeyed query — a fetch that never touches the cache, where a newer call supersedes (and cancels) an older in-flight one.

Execute (full form)#

public Task Execute(QueryParameters<T> parameters)

Runs the query described by parameters. With a key and a DejaClient, the shared cache path runs: cached data renders instantly, staleness decides whether to refetch in the background, and concurrent same-key calls from any component join one in-flight fetch. With a key but no client, a concurrent same-key call on this instance joins the in-flight execution. Without a key, a newer call supersedes the older one. No-op when parameters is null or the query is disposed.

Refetch#

public Task Refetch(RefetchParameters<T>? parameters = null)

Re-runs the last Execute with a forced fresh fetch: staleness, RefetchOnMount and Enabled are bypassed — a manual refetch is an explicit request, not a mount policy. On the cached path the result updates the shared entry, so every component on the key re-renders. Overrides in RefetchParameters<T> apply to this call only. Does nothing before the first Execute or after disposal.

ClearData#

public void ClearData()

Resets the query's state (data, error, counters) without cancelling an in-flight execution. Resets only this query's view — a cache entry it observes is untouched, so the next keyed Execute serves the cached data again; use DejaClient.Remove to drop the entry itself.

ClearData(bool)#

public void ClearData(bool cancelCurrentRequest)

As above; when cancelCurrentRequest is true, the in-flight execution is also cancelled without disposing the query, so it can still be executed again.

Dispose#

public void Dispose()

Cancels any in-flight execution. DejaComponentBase calls this for the queries a component owns, so navigating away aborts the request (and the server query) instead of letting it run to completion.

Failure contract#

A failing execution publishes IsError/ErrorMessage and runs the error callbacks; an InvalidOperationException wrapping the original exception is thrown only when no error callback observed it. Cancellation (supersede or disposal) is not an error: no error state, no callbacks. See the error handling guide.