API Reference

A flat index of the public types, hooks, and functions gpui-query exports

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 (/docs/guides/persistence#reference-adapter-filepersister).
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 (/docs/guides/http-caching).

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 (/docs/api/queries).
- For the full item-level documentation, build the Rust API docs with cargo doc -p gpui-query --open.