Interface IQuery<TArg, TResult>

Namespace

Phetch.Core

Assembly

Phetch.Core.dll

An asynchronous query taking one parameter of type TArg and returning a result of type TResult

public interface IQuery<TArg, TResult> : IQuery, IDisposable

Type Parameters

TArg

TResult

Inherited Members

IQuery.StateChanged

IQuery.Status

IQuery.Error

IQuery.IsLoading

IQuery.IsError

IQuery.IsSuccess

IQuery.HasData

IQuery.IsUninitialized

IQuery.IsFetching

IQuery.Detach()

IQuery.Cancel()

IDisposable.Dispose()

Extension Methods

QueryExtensions.Refetch<TArg, TResult>(IQuery<TArg, TResult>)

QueryExtensions.SetArg<TArg, TResult>(IQuery<TArg, TResult>, TArg)

QueryExtensions.TriggerAsync<TArg, TResult>(IQuery<TArg, TResult>, TArg, Action<QuerySuccessEventArgs<TArg, TResult>>?, Action<QueryFailureEventArgs<TArg>>?)

QueryExtensions.Trigger<TArg, TResult>(IQuery<TArg, TResult>, TArg, Action<QuerySuccessEventArgs<TArg, TResult>>?, Action<QueryFailureEventArgs<TArg>>?)

Remarks

For queries with no parameters, you can use the Query<TResult> class.

For queries with multiple parameters, you can use a tuple or record in place of TArg:

Query<(int, string), string>

Properties

Arg

The current argument passed to this query, or default if the query is uninitialized.

TArg? Arg { get; }

Property Value

TArg

CurrentQuery

The instance of FixedQuery<TArg, TResult> that this query is currently observing. This changes every time the Arg for this query changes.

FixedQuery<TArg, TResult>? CurrentQuery { get; }

Property Value

FixedQuery<TArg, TResult>

Data

The response data from the current query if it exists.

TResult? Data { get; }

Property Value

TResult

Remarks

To also keep data from previous args while a new query is loading, use LastData instead.

LastData

The response data from the current query if it exists, otherwise the response data from the last successful query.

TResult? LastData { get; }

Property Value

TResult

Remarks

This is useful for pagination, if you want to keep the data of the previous page visible while the next page loads. May return data from a different query argument if the argument has changed.

Options

Options for this query.

QueryOptions<TArg, TResult> Options { get; }

Property Value

QueryOptions<TArg, TResult>

Methods

Invoke(TArg, CancellationToken)

Runs the original query function once, completely bypassing caching and other extra behavior. Re-throws any exception thrown by the query function.

Task<TResult> Invoke(TArg arg, CancellationToken ct = default)

Parameters

arg TArg

The argument passed to the query function

ct CancellationToken

An optional cancellation token

Returns

Task<TResult>

The value returned by the query function

RefetchAsync()

Re-runs the query using the most recent argument and returns the result. This does not throw if the query fails, and instead returns the error via a QueryResult<TResult>

Task<QueryResult<TResult>> RefetchAsync()

Returns

Task<QueryResult<TResult>>

A QueryResult<TResult> containing the outcome of the query (data or error).

Remarks

If you do not need to await the completion of the query, use Refetch instead.

Exceptions

InvalidOperationException

Thrown if no argument has been provided to the query

SetArgAsync(TArg)

Updates the argument for this query, and re-run the query if the argument has changed. This does not throw if the query fails, and instead returns the error via a QueryResult<TResult>

Task<QueryResult<TResult>> SetArgAsync(TArg arg)

Parameters

arg TArg

Returns

Task<QueryResult<TResult>>

A QueryResult<TResult> containing the outcome of the query (data or error).

Remarks

If you do not need to await the completion of the query, use SetArg<TArg, TResult>(IQuery<TArg, TResult>, TArg) instead.

TriggerAsync(TArg)

Run the query function without sharing state or cache with other queries. This does not throw if the query fails, and instead returns the error via a QueryResult<TResult>

Task<QueryResult<TResult>> TriggerAsync(TArg arg)

Parameters

arg TArg

The argument to pass to the query function

Returns

Task<QueryResult<TResult>>

A QueryResult<TResult> containing the outcome of the query (data or error).

Remarks

If you do not need to await the completion of the query, use Trigger instead.

This is typically used for queries that have side effects (e.g., POST requests). This has the following differences from SetArgAsync(TArg):

• This will always run the query function, even if it was previously run with the same query argument.
• The state of this query (including the cached return value) will not be shared with other queries that use the same query argument.

Events

DataChanged

An event that fires whenever the data of this query changes (including when loading is started).

event Action<TResult?>? DataChanged

Event Type

Action<TResult>

Failed

An event that fires whenever this query fails.

event Action<QueryFailureEventArgs<TArg>>? Failed

Event Type

Action<QueryFailureEventArgs<TArg>>

Succeeded

An event that fires whenever this query succeeds.

event Action<QuerySuccessEventArgs<TArg, TResult>>? Succeeded

Event Type

Action<QuerySuccessEventArgs<TArg, TResult>>