Class StreamedQueryOptions<TArgs, TData, TChunk>

Namespace

Fetchling.Core

Assembly

Fetchling.Core.dll

Configuration for a streamed query created via CreateStreamedQuery<TArgs, TData, TChunk>(StreamedQueryOptions<TArgs, TData, TChunk>): the fetcher yields chunks, and Reducer folds each one into the data, starting from InitialValue. Use it for responses that arrive in pieces and should be shown as they grow — server-streaming gRPC calls, LLM token output, and the like.

public sealed record StreamedQueryOptions<TArgs, TData, TChunk> : IEquatable<StreamedQueryOptions<TArgs, TData, TChunk>> where TData : class

Type Parameters

TArgs

The type of the arguments that identify which stream to fetch.

TData

The type of the folded data. Constrained to reference types because the library uses null to represent "no data yet".

TChunk

The type of a single chunk the stream yields.

Inheritance

object

StreamedQueryOptions<TArgs, TData, TChunk>

Implements

IEquatable<StreamedQueryOptions<TArgs, TData, TChunk>>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The query is Fetching until the first chunk arrives, then Success with IsStreaming set while more chunks come in. State emits once per chunk with the data folded so far; Success and Settled emit once, when the stream completes.

Caching, deduplication, stale time, cancellation and retries work exactly as for a regular query, applied to the folded data. A retry restarts the stream from InitialValue. Unlike a regular query, Invalidate() does not restart a stream that is still running — it only marks the data stale; Refetch() does restart it.

Properties

CacheTime

Overrides the global CacheTime. null uses the global default.

public TimeSpan? CacheTime { get; init; }

Property Value

TimeSpan?

DataComparer

Compares the completed data against the previous completed data. When equal, the previous reference is kept and Success does not re-emit. Not applied to the intermediate values published while streaming. Defaults to Default.

public IEqualityComparer<TData>? DataComparer { get; init; }

Property Value

IEqualityComparer<TData>

Fetcher

Opens the stream for the given args. Receives a CancellationToken that is cancelled when the query is cancelled, disposed, or superseded by a refetch; enumeration stops as soon as it is. Called again from the start on every refetch and retry.

public required Func<TArgs, CancellationToken, IAsyncEnumerable<TChunk>> Fetcher { get; init; }

Property Value

Func<TArgs, CancellationToken, IAsyncEnumerable<TChunk>>

InitialValue

The value every fetch starts folding from — e.g. "" for text, or an empty immutable list. This is the seed of the fold, not pre-populated cache data: a stream that yields no chunks completes with this value as its data.

public required TData InitialValue { get; init; }

Property Value

TData

IsEnabled

Whether the query is initially enabled. Defaults to true.

public bool IsEnabled { get; init; }

Property Value

bool

KeyFactory

Derives the cache key from the args. Queries with the same key share one running stream.

public required Func<TArgs, QueryKey> KeyFactory { get; init; }

Property Value

Func<TArgs, QueryKey>

Name

A short, low-cardinality name used to tag metrics for this query. When null, the first part of the derived QueryKey is used instead. See Name.

public string? Name { get; init; }

Property Value

string

Reducer

Folds one chunk into the data so far and returns the new data, e.g. (text, token) => text + token. Must not mutate its input: every intermediate value is published as a state, and a state is an immutable snapshot.

public required Func<TData, TChunk, TData> Reducer { get; init; }

Property Value

Func<TData, TChunk, TData>

RefetchInterval

Refetches on this interval. Unlike other query options, null does not fall back to RefetchInterval: re-opening a stream is rarely cheap (think of an LLM call), so a streamed query only polls when it asks to.

public TimeSpan? RefetchInterval { get; init; }

Property Value

TimeSpan?

RefetchMode

What to show while refetching data the query already has. Defaults to Reset. The very first fetch always shows chunks as they arrive, since there is nothing to keep.

public StreamRefetchMode RefetchMode { get; init; }

Property Value

StreamRefetchMode

RetryHandler

Overrides the global RetryHandler. null uses the global default. Each attempt restarts the stream from InitialValue.

public IRetryHandler? RetryHandler { get; init; }

Property Value

IRetryHandler

StaleTime

Overrides the global StaleTime. null uses the global default.

public TimeSpan? StaleTime { get; init; }

Property Value

TimeSpan?