Module core 

Available on crate feature core only.

Layer 0: Transport-agnostic query lifecycle primitives.

QueryResource owns the cache/request state for one resource. Callers start work with begin_request, then complete it with the returned RequestId. Completion methods reject stale request ids, so cancelled or replaced async work cannot overwrite newer state.

Request lifecycle

The typical lifecycle for a single query fetch is:

1. Begin: Call QueryResource::begin_request with a RequestSequencer. This returns a QueryBeginResult indicating whether a fetch is needed, the cache was hit, or the request was ignored.

2. Fetch: If the result is Started or StaleCacheHit, start an async fetch using the returned RequestId.

3. Accept: When the fetch completes, call QueryResource::accept_current_request with the RequestId. If the request is still active (not replaced or cancelled), this returns a RequestGuard — a single-use capability token.

4. Complete: Pass the RequestGuard (by value) to QueryResource::complete_success or QueryResource::complete_failure. The guard is consumed, preventing accidental double-completion.

Alternatively, use the convenience methods QueryResource::complete_current_success or QueryResource::complete_current_failure which combine steps 3 and 4.

This module depends only on serde — zero framework coupling.

Structs

Fetched

A fetcher success carrying an optional server-derived cache policy.

InfiniteQueryResource

An infinite query resource that manages paginated data.

MappedQueryResource

A mapped view over a QueryResource that applies a SelectTransform.

MutationResource

A mutation resource that tracks the state of a single mutation.

QueryError

An error produced by a query or mutation operation.

QueryKey

A structured, hierarchical cache key for query resources.

QueryResource

Core state machine for a single query resource.

QuerySignal

A cooperative cancellation signal for in-flight query requests.

QueryTimestamp

A timestamp for query operations, in milliseconds since UNIX epoch.

RequestGuard

A single-use capability token proving the holder owns the current request.

RequestId

A unique identifier for an in-flight request.

RequestSequencer

Monotonic request id generator scoped to a single resource.

RetryPolicy

Retry configuration for failed requests.

SelectTransform

A select transform that maps cached data of type T to output type U.

Enums

CachePolicy

How cached data is treated when a query is accessed.

FetchDirection

Direction mode for an infinite query.

MutationStatus

Status of a mutation operation.

NetworkMode

Controls fetch behavior based on network connectivity.

QueryBeginResult

The result of calling begin_request on a query resource.

QueryErrorKind

The kind of error that occurred during a query operation.

QueryFetchMode

Whether the fetch is a normal request or forced (ignoring cache).

QueryKeyFilter

A filter for matching query keys, used by bulk operations like invalidate_queries.

QueryStatus

The status of a query resource.

RefetchTrigger

Trigger configuration for automatic refetching.

RequestPolicy

How concurrent requests are handled.