API Reference

A compact index of the public surface, grouped by the crate’s four layers. Import hooks and common types from the crate root; import layer-specific items from gpui_query::core, gpui_query::client, or gpui_query::hook. Persistence types live under gpui_query::client behind the persist feature.

// Hooks and common types at the crate root:
use gpui_query::{
    use_query, use_mutation, use_infinite_query, use_query_select,
    QueryOptions, InfiniteQueryOptions, MutationOptions, MutationCallbacks,
    QueryKey, QueryKeyFilter, QueryError, QueryErrorKind, QueryStatus,
    CachePolicy, RequestPolicy, RetryPolicy, QueryClient,
};

core: Serde-only state machine

The core layer has no GPUI dependency. Everything here is Serialize + Deserialize (unless noted) and safe to persist.

Keys and filters

Item	Kind	Notes
QueryKey	struct	Hierarchical cache key, Arc<[Arc<str>]>-backed.
QueryKeyFilter	enum	Exact(&k) / Prefix(&k) / All. Used by bulk ops.

Policies and status

Item	Kind	Notes
CachePolicy	enum	NoCache / Ttl { ttl_ms } / StaleWhileRevalidate { ttl_ms, stale_ms }.
RequestPolicy	enum	LatestWins (default) / IgnoreWhileLoading.
RetryPolicy	struct	max_retries, retry_delay_ms, exponential_backoff, max_retry_delay_ms.
QueryStatus	enum	Idle / LoadingEmpty / LoadingWithData / Success / Failure / Cancelled.
MutationStatus	enum	Idle / Loading / Success / Failure.
QueryFetchMode	enum	Normal / Force.
QueryBeginResult	enum	Started / CacheHit / StaleCacheHit / IgnoredWhileLoading.
RequestId	struct	Monotonic per-resource request id.
QuerySignal	struct	Cooperative-cancellation signal handed to fetchers.

Errors

Item	Kind	Notes
QueryError	struct	Default error type. Display + Error, Arc<str> message. Constructors: response / transport / cancelled / unknown / sanitized.
QueryErrorKind	enum	Cancelled / Response / Transport / Unknown.

Resources

Item	Kind	Notes
QueryResource<T, E>	struct	The core cached resource. Accessors: data, error, status, key, cache_policy, retry_count, last_updated_at_ms, …
MutationResource<V,T,E>	struct	One mutation’s lifecycle.
InfiniteQueryResource<T,E>	struct	Pages + pagination state. pages, page_count, has_next_page, is_fetching_next_page, …
SelectTransform<T, U>	struct	Fn(&T) -> U wrapper for derived views.
MappedQueryResource<T,U,E>	struct	A derived view applying a SelectTransform.

client: GPUI registry

Item	Kind	Notes
QueryClient	struct	Global registry. resource, query, get_query_data, set_query_data, with_query_data, invalidate_queries, cancel_queries, reset_queries, remove_queries, prepare_fetch_query, prepare_prefetch_query, gc, gc_with_time, diagnostics. Persistence (persist): persist_with, collect_persist_snapshot, register_serializer, register_deserializer.
Observer<R>	struct	Generic status-deduplicating observer.
QueryObserver<T,E>	alias	Observer<QueryResource<T, E>>.
InfiniteQueryObserver<T,E>	alias	Observer<InfiniteQueryResource<T, E>>.
MutationObserver<V,T,E>	alias	Observer<MutationResource<V, T, E>>.
ObserverConfig	struct	notify_on_status_change_only (default true).
Persister (persist)	trait	Async backend: async load() -> Result<PersistSnapshot, PersistError>, async save(&PersistSnapshot) -> Result<(), PersistError>. Non-object-safe; consumed generically by persist_with.
PersistSnapshot / PersistedEntry (persist)	structs	Value-carrying snapshot: value (serde_json::Value), cached_at, cache_policy, meta.
PersistOptions / PersistFilter (persist)	struct / enum	persist_with tuning: filter (Exact / Prefix / All), max_age, debounce.
PersistHandle / NoopPersister (persist)	struct / struct	Drop-guard from persist_with (drop stops new saves) / no-op backend for tests.
SerializerRegistry (persist)	struct	Typed T -> serde_json::Value registry driving snapshot collection. Register serializers and deserializers via QueryClient::register_serializer / register_deserializer.
PersistError / PERSIST_VERSION (persist)	enum / const	Io / Serialize / Deserialize / VersionMismatch / BadPath / Permission; snapshot format version (1).
hydrate (persist)	free fn	async hydrate(client, &persister, &filter, max_age, cx) -> Result<PersistSnapshot, PersistError>; cold-start restore.
Fetched<T> (core; meta under persist)	struct	Fetcher return wrapper for server-derived cache policy: new, with_policy, with_meta.
PreparedFetch<T,E>	struct	Imperative fetch handle: entity, signal, request_id, now_ms.
QueryDiagnostic / MutationDiagnostic / ClientDiagnostic	structs	DevTools snapshot types.
DehydratedState / DehydratedEntry	structs	Legacy metadata-only snapshot (the dehydrate/restore skeleton). Prefer the value-carrying persist types above.
QueryPersister	trait	Legacy sync persister (load -> Vec<DehydratedEntry>, save(Vec<DehydratedEntry>)). Superseded by Persister.

hook: Ergonomic subscriptions

All hooks return (Entity<Resource>, Subscription) (or a triple for use_query_select). Store both.

Item	Returns	Notes
use_query	(Entity<QueryResource<T,E>>, Subscription)	Primary query hook, signal-always.
use_query_manual / _opts	same	Lower-level: explicit params.
use_query_unsignalled / _opts	same	Fetcher takes no signal (legacy).
use_query_select	(Entity<MappedQueryResource<T,U,E>>, Entity<QueryResource<T,E>>, (Subscription, Subscription))	select pattern.
use_infinite_query	(Entity<InfiniteQueryResource<T,E>>, Subscription)	Pagination / load-more.
fetch_next_page_infinite	()	Grow an infinite query forward.
fetch_previous_page_infinite	()	Grow an infinite query backward.
fetch_query / fetch_query_with_signal	()	Refetch on demand.
use_mutation	(Entity<MutationResource<V,T,E>>, Subscription)	Primary mutation hook.
use_mutation_state	Vec<Entity<MutationResource<V,T,E>>>	All mutations of a type triple.
mutate	()	Trigger with owned V.
mutate_with_callbacks	()	Trigger + lifecycle callbacks.
mutate_by_ref	()	Trigger, mutator borrows &V.
mutate_arc	()	Trigger with shared Arc<V>.

Companion crates

Two crates ship alongside gpui-query and publish independently:

Crate	Purpose
gpui-query-persist	Reference disk Persister: FilePersister (atomic write, tolerant load), PersistFormat::Json / Bincode, NoopPersister. See Persistence: reference adapter.
gpui-query-http	HTTP cache headers → CachePolicy: cache_policy_from_headers (RFC 9111), HttpCache<B> over an HttpBackend, CacheMeta (ETag / If-Modified-Since), optional ReqwestBackend. See HTTP cache headers.

Feature flags

The four layers are gated behind feature flags so you can compile only what you need:

Flag	Enables
core	The Serde-only state machine (no GPUI dep).
client	QueryClient, observers, devtools.
hook	use_query / use_mutation / use_infinite_query and friends.
persist	Async persistence: Persister, persist_with, hydrate, the (de)serializer registries. Adds serde_json + thiserror.

docsrs enables #[doc(cfg(...))] gating on docs.rs builds so the rendered API docs annotate each item with its feature gate.

Next steps

• The detailed pages in the sidebar cover each of these in depth. Start with Queries.
• For the full item-level documentation, build the Rust API docs with cargo doc -p gpui-query --open.