Class Query<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 class Query<TArg, TResult> : IQuery<TArg, TResult>, IQuery, IDisposable

Type Parameters

TArg

TResult

Inheritance

object

Query<TArg, TResult>

Implements

IQuery<TArg, TResult>

IQuery

IDisposable

Derived

Query<TResult>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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.

public 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.

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

Property Value

FixedQuery<TArg, TResult>

Data

The response data from the current query if it exists.

public TResult? Data { get; }

Property Value

TResult

Remarks

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

Error

The exception thrown the last time the query failed with this arg, or null if the query has never failed with this arg.

public Exception? Error { get; }

Property Value

Exception

HasData

True if the query has succeeded and returned a non-null response.

public bool HasData { get; }

Property Value

bool

Remarks

This is particularly useful in combination with nullable reference types, as it lets you safely access Data without a compiler warning.

IsError

True if the query threw an exception and has not been re-run.

public bool IsError { get; }

Property Value

bool

IsFetching

True if the query is currently running, either for the initial load or for subsequent fetches once the data is stale.

public bool IsFetching { get; }

Property Value

bool

Remarks

If you only need to know about the initial load, use IsLoading instead.

IsLoading

True if the query is currently loading and has not previously succeeded with the same argument.

public bool IsLoading { get; }

Property Value

bool

Remarks

This will return false if the query is currently re-fetching in the background, and already has data. Use IsFetching for these cases (e.g., to show a loading indicator).

IsSuccess

True if the query has succeeded.

public bool IsSuccess { get; }

Property Value

bool

Remarks

In many cases you should prefer to use HasData as it works better with nullable reference types.

IsUninitialized

True if no arguments have been provided to this query yet.

public bool IsUninitialized { get; }

Property Value

bool

LastData

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

public 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.

public QueryOptions<TArg, TResult> Options { get; }

Property Value

QueryOptions<TArg, TResult>

Status

The current status of this query.

public QueryStatus Status { get; }

Property Value

QueryStatus

Methods

Cancel()

Cancels the currently running query, along with the CancellationToken that was passed to it.

public void Cancel()

Remarks

If the query function does not use the CancellationToken, the query state will be reset, but the underlying operation will continue to run. You should not rely on this to cancel operations with side effects.

Detach()

Stop listening to changes of the current query. This allows the query data to be garbage collected after the CacheTime has passed (if there are no other observers for the same Arg).

public void Detach()

Dispose()

Stop listening to changes of the current query. This is equivalent to calling Detach().

public void Dispose()

Remarks

If you created this query with endpoint.Use(), call this when you've finished using the query. Most commonly, this should be called in the Dispose method of a component.

If this query was created by <UseEndpoint/>, this method will be called automatically.

Dispose(bool)

Stop listening to changes of the current query.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

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.

public 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>

public 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>

public 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>

public 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).

public event Action<TResult?>? DataChanged

Event Type

Action<TResult>

Failed

An event that fires whenever this query fails.

public event Action<QueryFailureEventArgs<TArg>>? Failed

Event Type

Action<QueryFailureEventArgs<TArg>>

StateChanged

An event that fires whenever the state of this query changes.

public event Action? StateChanged

Event Type

Action

Succeeded

An event that fires whenever this query succeeds.

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

Event Type

Action<QuerySuccessEventArgs<TArg, TResult>>