Table of Contents

Class QueryOptions<TQueryFnData, TData>

Namespace
Velvet
Assembly
Velvet.Docs.dll

Options passed to UseQuery<TQueryFnData, TData>(QueryOptions<TQueryFnData, TData>, QueryClient?): TanStack Query's { queryKey, queryFn } with its enabled, select, placeholderData, staleTime, gcTime, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, retry, retryDelay, structuralSharing and notifyOnChangeProps. QueryOptions<T> is the form without a Select that changes the data's type.

public record QueryOptions<TQueryFnData, TData>

Type Parameters

TQueryFnData

What the query function returns and the entry holds.

TData

What the result's Data holds; the query function's data unless Select turns it into something else.

Inheritance
object
QueryOptions<TQueryFnData, TData>
Derived

Constructors

QueryOptions(QueryKey, Func<CancellationToken, VelvetTask<TQueryFnData>>)

Options passed to UseQuery<TQueryFnData, TData>(QueryOptions<TQueryFnData, TData>, QueryClient?): TanStack Query's { queryKey, queryFn } with its enabled, select, placeholderData, staleTime, gcTime, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, retry, retryDelay, structuralSharing and notifyOnChangeProps. QueryOptions<T> is the form without a Select that changes the data's type.

QueryOptions(QueryKey, Func<VelvetTask<TQueryFnData>>)

Options whose query function takes no token: its request is not cancelled when the last query reading the entry leaves, and lands in the entry for the next reader to find.

Properties

Enabled

TanStack Query's enabled. False fetches nothing on its own — not on mount, not on invalidation — and reports the result not stale; Refetch() still fetches. Turning it true over stale data fetches.

GcTime

Overrides DefaultGcTime for this query. An entry keeps the longest time any query subscribing to it asked for.

NotifyOnChangeProps

The result properties whose change re-renders the component, TanStack Query's notifyOnChangeProps. When null, a change re-renders it only if it is to a property the component has read from a result, as useQuery tracks them by default, or at any change to the result while none has been read; All re-renders at every change to the result.

PlaceholderData

TanStack Query's placeholderData given as a function: data the result shows while the entry has none and is pending, handed the data and the QueryInfo of the last entry this component read that had data and still has it — default and null when there is none. The result is then Success with IsPlaceholderData true, and the entry is left without data. KeepPreviousData<T>(T?, QueryInfo?) keeps the previous key's data; (_, _) => value is the value form.

QueryFn

Fetches the entry's data. The token is cancelled when a refetch starts over this request, when Clear() removes the entry, and when the last query reading the entry leaves while the request is in flight, which also puts the entry back as it stood before the request started: TanStack Query aborts the request of a query function that read its signal in the same case. A function taking the token counts as having read it. The constructor taking a function without a token is the one whose request runs on after the last reader leaves, as TanStack Query's does for a function that never reads its signal.

QueryKey

Names the cache entry. Queries presenting equal keys share one entry.

RefetchInterval

TanStack Query's refetchInterval given as a number: an enabled query fetches again each time this much has passed on the client's clock since its entry last changed — a request starting, landing or failing — or since the interval last came round, whether or not its data is stale, joining a request already in flight. The wait is checked once a frame. Null, zero or less, or System.TimeSpan.MaxValue fetches on no interval.

RefetchIntervalFn

TanStack Query's refetchInterval given as a function: the interval, handed the entry the query reads, with the meaning RefetchInterval gives a number and null for no interval. It replaces RefetchInterval when both are set. It is called whenever the entry changes and at every commit of the component, not once a frame; one that throws counts as no interval, and its failure is logged once for each function instance.

RefetchIntervalInBackground

TanStack Query's refetchIntervalInBackground: true lets RefetchInterval fetch while the application is not visible, as NetworkSignals reads it; by default it waits.

RefetchOnReconnect

Overrides DefaultRefetchOnReconnect for this query: whether an enabled query fetches again when the device comes back online, TanStack Query's refetchOnReconnect.

RefetchOnReconnectFn

RefetchOnReconnect given as a function, with the terms of RefetchOnWindowFocusFn for the device coming back online.

RefetchOnWindowFocus

Overrides DefaultRefetchOnWindowFocus for this query: whether an enabled query fetches again when the application becomes visible, TanStack Query's refetchOnWindowFocus.

RefetchOnWindowFocusFn

RefetchOnWindowFocus given as a function, TanStack Query's refetchOnWindowFocus as a function: handed the entry the query reads, and called each time the application becomes visible for an enabled query. It replaces RefetchOnWindowFocus when both are set, and one that throws is logged and counts as Never.

Retry

Overrides DefaultRetry for this query: how many times a failed request runs again before the failure is the entry's error, TanStack Query's retry given as a number. Zero or less retries nothing.

RetryDelay

Overrides DefaultRetryDelay for this query: the wait before the next request, from the number of failures before this one and this failure's exception, TanStack Query's retryDelay.

Select

TanStack Query's select: turns the entry's data, and placeholder data, into the result's. Over the entry's data it runs again only when that data's instance or this function's changes, so pass a stable instance, such as one held in a field, to keep from running it each render. One that throws makes the result an error. Required when TData is not TQueryFnData.

StaleTime

Overrides DefaultStaleTime for this query.

StructuralSharing

Chooses the data an entry holds when a request lands, from the data it held, null when it held none, and the data that arrived: TanStack Query's structuralSharing given as a function. When null, the data that arrived keeps the instance the entry held where the two are deeply equal and keeps the equal parts of it where they are not; (_, arrived) => arrived turns that off. The same choice is made between a result's data and what Select or PlaceholderData produces next. The values are boxed, as v5 hands its function unknown: a function is handed TQueryFnData values when it chooses the entry's data and TData values when it chooses the result's, and has to return the type it was handed. What counts as deeply equal is described in react-migration.md §1-2b.