Class Endpoint<TArg, TResult>

Namespace

Phetch.Core

Assembly

Phetch.Core.dll

Defines an "endpoint" that represents a single query function, usually for a specific HTTP endpoint.

public class Endpoint<TArg, TResult>

Type Parameters

TArg

The type of the argument passed to the query function. To use query functions with multiple arguments, wrap them in a tuple.

TResult

The return type from the query function

Inheritance

object

Endpoint<TArg, TResult>

Derived

ParameterlessEndpoint<TResult>

ResultlessEndpoint<TArg>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This is the recommended way to use queries in most cases, and serves as a convenient way to create Query<TArg, TResult> instances that share the same cache.

Constructors

Endpoint(Func<TArg, CancellationToken, Task<TResult>>, EndpointOptions<TArg, TResult>?)

Creates a new query endpoint with a given query function. In most cases, the query function will be a call to an HTTP endpoint, but it can be any async function.

public Endpoint(Func<TArg, CancellationToken, Task<TResult>> queryFn, EndpointOptions<TArg, TResult>? options = null)

Parameters

queryFn Func<TArg, CancellationToken, Task<TResult>>

options EndpointOptions<TArg, TResult>

Endpoint(Func<TArg, Task<TResult>>, EndpointOptions<TArg, TResult>?)

Creates a new query endpoint with a given query function. In most cases, the query function will be a call to an HTTP endpoint, but it can be any async function.

public Endpoint(Func<TArg, Task<TResult>> queryFn, EndpointOptions<TArg, TResult>? options = null)

Parameters

queryFn Func<TArg, Task<TResult>>

options EndpointOptions<TArg, TResult>

Properties

Options

Options for this endpoint.

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

Property Value

EndpointOptions<TArg, TResult>

Methods

GetCachedQuery(TArg)

Gets the cached query instance for the given argument if it exists in the cache, otherwise null.

public FixedQuery<TArg, TResult>? GetCachedQuery(TArg arg)

Parameters

arg TArg

Returns

FixedQuery<TArg, TResult>

Remarks

This does not return queries created by TriggerAsync(TArg).

GetCachedQueryByKey(object?)

Similar to GetCachedQuery(TArg), but looks up a query by its key directly. This is only useful when using KeySelector, because otherwise the key and arguments are equivalent.

public FixedQuery<TArg, TResult>? GetCachedQueryByKey(object? key)

Parameters

key object

Returns

FixedQuery<TArg, TResult>

Invalidate(TArg)

Invalidates a specific value in the cache, based on its query argument.

public void Invalidate(TArg arg)

Parameters

arg TArg

The query argument to invalidate

Remarks

If no queries are using the provided query argument, this does nothing.

InvalidateAll()

Invalidates all cached return values from this endpoint. Any components using them will automatically re-fetch their data.

public void InvalidateAll()

InvalidateWhere(Func<FixedQuery<TArg, TResult>, bool>)

Invalidates all cache entries that match the given predicate.

public void InvalidateWhere(Func<FixedQuery<TArg, TResult>, bool> predicate)

Parameters

predicate Func<FixedQuery<TArg, TResult>, bool>

The function to use when deciding which entries to invalidate, based on the cached query. This should return true for entries that should be invalidated, or false otherwise.

Invoke(TArg, CancellationToken)

Runs the original query function once, completely bypassing caching and other extra behavior

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

Prefetch(TArg)

Begins running the query in the background for the specified query argument, so that the result can be cached and used immediately when it is needed.

If the specified query argument already exists in the cache and was not an error, this does nothing.

public void Prefetch(TArg arg)

Parameters

arg TArg

PrefetchAsync(TArg)

Begins running the query in the background for the specified query argument, so that the result can be cached and used immediately when it is needed.

If the specified query argument already exists in the cache and was not an error, this does nothing.

public Task<TResult> PrefetchAsync(TArg arg)

Parameters

arg TArg

Returns

Task<TResult>

TryGetCachedResult(TArg, out TResult)

Attempts to retrieve a cached result for the given query argument.

public bool TryGetCachedResult(TArg arg, out TResult result)

Parameters

arg TArg

The query argument

result TResult

The cached data for the given query argument, or default if the data wasn't in the cache.

Returns

bool

True if the data existed in the cache.

UpdateQueryData(TArg, Func<FixedQuery<TArg, TResult>, TResult>, bool)

Updates the response data for a given query. If no cache entry exists for this arg and addIfNotExists is true, a new one will be created.

public void UpdateQueryData(TArg arg, Func<FixedQuery<TArg, TResult>, TResult> dataSelector, bool addIfNotExists = false)

Parameters

arg TArg

The query argument of the query to be updated.

dataSelector Func<FixedQuery<TArg, TResult>, TResult>

A function to select the new data for the query, based on the existing cached query.

addIfNotExists bool

If true and there is no cache entry for the given arg, a new query will be added to the cache.

Remarks

Note: It is not guaranteed that the the query object passed to dataSelector will have succeeded and/or have data available.

UpdateQueryData(TArg, TResult, bool)

Updates the response data for a given query. If no cache entry exists for this arg and addIfNotExists is true, a new one will be created.

public void UpdateQueryData(TArg arg, TResult resultData, bool addIfNotExists = false)

Parameters

arg TArg

The query argument of the query to be updated.

resultData TResult

The new data to set on the query.

addIfNotExists bool

Use(QueryOptions<TArg, TResult>?)

Creates a new Query<TArg, TResult> object, which can be used to make queries to this endpoint.

public Query<TArg, TResult> Use(QueryOptions<TArg, TResult>? options = null)

Parameters

options QueryOptions<TArg, TResult>

Additional options to use when querying

Returns

Query<TArg, TResult>

A new Query<TArg, TResult> object which shares the same cache as other queries from this endpoint.