Struct QueryClient 

pub struct QueryClient { /* private fields */ }

Available on crate feature client only.

Global registry for query and mutation resources.

Implements Global so it can be set once with cx.set_global(QueryClient::default()) and accessed from any component via cx.global::<QueryClient>().

v2 Improvements

• Default impl (no required params)
• AHashMap for ~2x faster lookups on trusted keys
• Actual mutation GC (not a no-op)
• Collect-then-update pattern to avoid nested entity borrows

Implementations

impl QueryClient

pub fn infinite_resource<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: impl Into<QueryKey>, cx: &mut App, ) -> Entity<InfiniteQueryResource<T, E>>

Get or create an infinite query resource for the given key and type pair.

pub fn infinite_resource_with_policies<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: impl Into<QueryKey>, cache_policy: CachePolicy, request_policy: RequestPolicy, cx: &mut App, ) -> Entity<InfiniteQueryResource<T, E>>

Get or create an infinite query resource with explicit policies.

Audit 3 fix (findings 3, 4): Graceful downcast recovery.

pub fn infinite_query<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &self, key: &QueryKey, ) -> Option<Entity<InfiniteQueryResource<T, E>>>

Get a specific infinite query entity by key.

pub fn next_request_id_for_infinite_key<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: &QueryKey, ) -> Option<RequestId>

Use the infinite query bucket’s co-located sequencer to generate a RequestId for an infinite query key.

Returns None if no bucket entry exists for the key. The sequencer is advanced in-place so subsequent calls produce monotonically increasing IDs. This is the infinite query equivalent of next_request_id_for_key.

Audit 3 fix (findings 3, 4): Graceful downcast recovery.

pub fn all_infinite_queries<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &self, ) -> Vec<Entity<InfiniteQueryResource<T, E>>>

Get all infinite query entities of a given type pair.

pub fn register_mutation<V: Clone + Send + Sync + 'static, T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, entity: &Entity<MutationResource<V, T, E>>, cx: &App, )

Register a mutation entity.

Audit 3 fix (findings 3, 4): Graceful downcast recovery.

pub fn all_mutations<V: Clone + Send + Sync + 'static, T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &self, ) -> Vec<Entity<MutationResource<V, T, E>>>

Get all mutation entities of a given type triple.

pub fn invalidate_queries(&mut self, filter: &QueryKeyFilter<'_>, cx: &mut App)

Invalidate queries matching the filter.

Uses collect-then-update pattern to avoid nested entity borrows.

pub fn reset_queries(&mut self, filter: &QueryKeyFilter<'_>, cx: &mut App)

Reset queries matching the filter.

pub fn remove_queries(&mut self, filter: &QueryKeyFilter<'_>)

Remove queries matching the filter.

pub fn cancel_queries(&mut self, filter: &QueryKeyFilter<'_>, cx: &mut App)

Cancel in-flight requests matching the filter (Audit 3, Finding 5).

Iterates all query and infinite query buckets, finds resources with active requests, and cancels them with a [QueryError::cancelled] error. This is essential for cleanup when navigating away from a page or when bulk cancellation is needed.

Equivalent to TanStack Query’s queryClient.cancelQueries(). Individual QueryResource::cancel() exists but this is the bulk cancellation method on the client.

impl QueryClient

pub fn gc(&mut self, cx: &App)

Run garbage collection on all buckets.

Calls current_time_ms() internally to get the current time. If you already have a cached time value, use [gc_with_time] to avoid the syscall overhead (Audit 3, Finding 2).

pub fn gc_with_time(&mut self, now_ms: u64, cx: &App)

Run garbage collection with a pre-computed time value (Audit 3, Finding 2).

Use this when you call GC frequently and want to amortize the cost of SystemTime::now() across multiple calls. The now_ms parameter should be milliseconds since the UNIX epoch (as returned by current_time_ms).

L5: sets self.last_gc_ms = now_ms at the top so a manual GC call debounces the next opportunistic GC sweep (otherwise the caller’s explicit gc() would not push back the MIN_GC_TIME_MS window and the next op could immediately re-trigger GC).

pub fn diagnostics(&self, cx: &App) -> ClientDiagnostic

Get diagnostics for all queries and mutations.

Returns aggregate counts and per-resource diagnostic details. The queries and mutations vectors are populated by iterating all bucket entries, upgrading weak references, and reading entity state. Dead entries (collected entities) are skipped.

Audit 3 fix: Previously returned empty queries: Vec::new() and mutations: Vec::new() vectors. Now fully populates per-resource diagnostics via collect_diagnostics on each erased bucket.

pub fn dehydrate(&self, cx: &App) -> DehydratedState

Available on crate feature persist only.

Serialize all cached query state into a portable format.

Extracts all live query resources, recording their keys, status, and type information. The resulting DehydratedState can be persisted to disk or stored for later restoration via [hydrate].

Only resources with Success status are included. Resources in Idle, Loading, Failure, or Cancelled states are skipped.

Note: Full data serialization requires type-specific code at the call site. Use get_query_data::<T, E>(key, cx) to extract typed data and serialize it externally. The DehydratedState provides the metadata (keys, type IDs) needed for typed restoration.

pub fn hydrate(&mut self, _state: DehydratedState, _cx: &mut App)

Available on crate feature persist only.

Restore query state from a previously dehydrated snapshot.

Full hydration requires type-specific deserialization. The DehydratedState contains type_id keys but downcasting requires knowing the concrete types at the call site. Callers should iterate state.entries and call set_query_data::<T, E>() for each entry where they know the types.

This method is provided as a hook point for typed hydration and to document the intended API shape matching TanStack Query’s queryClient.hydrate().

pub fn persist(&self, persister: &dyn QueryPersister, cx: &App)

Available on crate feature persist only.

Persist all cached data using the provided persister.

Dehydrates the current state and saves it via the persister. This can be called periodically (e.g., during GC) or on app shutdown to ensure cached data survives across app restarts.

pub fn restore(persister: &dyn QueryPersister) -> Vec<DehydratedEntry>

Available on crate feature persist only.

Restore cached data from a persister.

Loads entries from the persister. Since type information is erased in the persister, callers must iterate and restore typed data themselves using set_query_data. This method loads the raw entries and returns them for inspection and typed restoration.

L4: this is an associated function rather than a method — it does not read any &self state, so callers invoke it as QueryClient::restore(&persister) instead of client.restore(...), avoiding the need for a borrow on the client.

pub fn prepare_fetch_query<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: impl Into<QueryKey>, cx: &mut App, ) -> Option<PreparedFetch<T, E>>

Prepare an imperative fetch for a query key, creating the resource if needed.

This creates (or reuses) the resource entity and begins a forced request, returning a PreparedFetch containing the entity, request ID, and signal. The caller is responsible for calling the fetcher and completing the request using complete_fetch or by directly calling complete_current_success / complete_current_failure on the entity.

This is the equivalent of TanStack Query’s queryClient.fetchQuery(). Unlike use_query, this does not subscribe or create an observer.

Returns None if the cache is fresh (cache hit) and no fetch is needed. In that case, use get_query_data to read the cached data.

Example

use gpui_query::client::QueryClient;
use gpui_query::core::QueryKey;

if let Some(prepared) = client.prepare_fetch_query::<UserData, QueryError>(
    QueryKey::from("user/42"),
    cx,
) {
    // prepared.entity, prepared.signal, and prepared.request_id are now available.
    // Use cx.spawn() to run your async fetcher, then call
    // prepared.complete_success(data, cx) or prepared.complete_failure(e, cx).
}

pub fn prepare_prefetch_query<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: impl Into<QueryKey>, cache_policy: CachePolicy, request_policy: RequestPolicy, cx: &mut App, ) -> Option<PreparedFetch<T, E>>

Prepare a prefetch for a key that will be needed soon.

Creates the resource entity (or reuses an existing one) and begins a request if the cache is stale or empty. The resource is NOT subscribed – no observer is attached. When a component later calls use_query with the same key, it will find the prefetched data in the cache.

This is the equivalent of TanStack Query’s queryClient.prefetchQuery().

If the resource already has fresh data (cache hit), returns None. Use prepare_fetch_query with forced mode to override this behavior.

Returns a PreparedFetch containing the entity, request ID, and signal. The caller is responsible for calling the fetcher and completing the request.

impl QueryClient

pub fn register_serializer<T, E>(&mut self, f: fn(&T) -> JsonValue)

where T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static,

Register a serializer for resources of type (T, E).

Only resources whose T has a registered serializer are emitted by the value-carrying collect_persistable_into path; unregistered types fall back to metadata-only (skipped), matching the legacy dehydrate.

f is a fn(&T) -> serde_json::Value (a plain function pointer, not a closure) so it is Send + Sync + 'static withoutboxing overhead.

pub fn register_deserializer<T, E>( &mut self, deserialize: fn(&JsonValue) -> Option<T>, )

where T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static,

Register a deserializer for resources of type (T, E), enabling hydrate to re-prime on-disk values of this type.

Strict-deserializer contract. hydrate offers every on-disk entry to every registered deserializer (there is no type discriminator on PersistedEntry, so routing is by trial). A deserializer MUST return None for any JSON shape it does not recognize as its own T; only return Some for values that genuinely decode to T. A lax deserializer that accepts a foreign shape would mis-prime the wrong bucket. (Each (T, E) writes to its own bucket, so typed data is not clobbered, but a permissive decoder wastes work and can prime a stale value.) Keep deserializers strict and cheap.

pub fn collect_persist_snapshot( &self, filter: &PersistFilter, max_age: Duration, cx: &App, ) -> PersistSnapshot

Collect a value-carrying snapshot from the live cache, honoring filter and max_age. Only resources with a registered serializer (and in Success status) are included.

pub fn persist_with<P: Persister>( &self, persister: P, opts: PersistOptions, cx: &mut App, ) -> PersistHandle

Drive a Persister from the live cache, debounced on the CacheMutation dirty signal.

On every CacheMutation bump, the callback:

1. collects a fresh PersistSnapshot (cheap; main thread, has &App),
2. stashes it in a shared slot, replacing any pending snapshot,
3. spawns a debounced task that, after opts.debounce, takes the latest snapshot from the slot and runs persister.save(&snapshot) on the background executor.

Rapid bursts coalesce: only the most recently collected snapshot is saved when the debounce timer elapses. Returning the PersistHandle keeps the observation alive; dropping it stops further saves.

impl QueryClient

pub fn new() -> Self

Create a new client with default policies.

pub fn with_policies( default_cache_policy: CachePolicy, default_request_policy: RequestPolicy, ) -> Self

Create with custom default policies.

pub fn with_gc_time(self, gc_time_ms: u64) -> Self

Set the garbage collection time (in milliseconds).

Values below 1000ms are clamped to 1000ms during GC to prevent aggressive eviction of all Idle/Failure resources on every GC pass.

pub fn resource<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: impl Into<QueryKey>, cx: &mut App, ) -> Entity<QueryResource<T, E>>

Get or create a query resource for the given key and type pair.

pub fn resource_with_policies<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: impl Into<QueryKey>, cache_policy: CachePolicy, request_policy: RequestPolicy, cx: &mut App, ) -> Entity<QueryResource<T, E>>

Get or create a query resource with explicit policies.

Audit 3 fix (findings 3, 4): Uses graceful downcast recovery instead of expect(). On type mismatch, logs the type name and creates a fresh bucket, preventing application crashes from hypothetical TypeId collisions.

pub fn all_queries<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &self, ) -> Vec<Entity<QueryResource<T, E>>>

Get all query entities of a given type pair.

pub fn query<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &self, key: &QueryKey, ) -> Option<Entity<QueryResource<T, E>>>

Get a specific query entity by key.

pub fn next_request_id_for_key<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: &QueryKey, ) -> Option<RequestId>

Use the bucket’s co-located sequencer to generate a RequestId for a key.

Returns None if no bucket entry exists for the key. The sequencer is advanced in-place (mutated) so subsequent calls produce monotonically increasing IDs. This is the fix for audit findings #1/#5/#15/#18: using the bucket’s persistent sequencer instead of a transient one prevents every request from getting the same RequestId(1, 1).

Audit 3 fix (findings 3, 4): Graceful downcast recovery.

pub fn get_query_data<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &self, key: &QueryKey, cx: &App, ) -> Option<T>

Read the cached data for a query key directly, without going through a hook.

Returns None if no resource exists for the key, the entity was collected, or the resource has no data (has not completed a fetch).

This is the ergonomic equivalent of TanStack Query’s queryClient.getQueryData(key).

pub fn with_query_data<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static, R>( &self, key: &QueryKey, cx: &App, f: impl FnOnce(&T) -> R, ) -> Option<R>

Read the cached data for a query key via a borrow callback, with NO clone of T (audit fix #L12).

This is the zero-clone counterpart to get_query_data: instead of returning Option<T> (which clones the value out of the resource), it hands f a &T for the duration of the call. Use this when the caller only needs to inspect the cached data (e.g. compute a derived value, render a summary) and would otherwise pay for a full T::clone() it discards immediately.

Returns None if no resource exists for the key, the entity was collected, or the resource has no data. Returns Some(R) (the value produced by f) otherwise. T and E are unchanged from get_query_data; R is the closure’s return type and is independent of T, so it does not shadow the crate’s T/E conventions.

pub fn set_query_data<T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + 'static>( &mut self, key: impl Into<QueryKey>, data: T, cx: &mut App, )

Write data directly into the cache for a query key, creating the resource if it does not already exist.

This is the ergonomic equivalent of TanStack Query’s queryClient.setQueryData(key, data). The resource’s previous data is saved for rollback via rollback_to_previous(). The data is set via set_data() which saves previous data but does not change the resource’s status or timestamp. Use this for optimistic updates and manual cache manipulation where you control the lifecycle.

Trait Implementations

impl Default for QueryClient

fn default() -> Self

Audit fix #21: Explicit Default impl that sets gc_time_ms to 300_000 (5 minutes), matching with_policies. The previous derive produced gc_time_ms: 0, which silently disabled GC — every non-loading Idle/Failure resource would be evicted on every pass. All other field defaults are identical to what the derive produced.

impl Global for QueryClient