Question 1

How is gpui-query different from TanStack Query?

Accepted Answer

gpui-query adapts TanStack Query's proven patterns to Rust and the GPUI framework. It uses Rust's type system for compile-time guarantees, Arc<AtomicBool> for cooperative cancellation, and integrates directly with GPUI's render loop.

Question 2

Can I use gpui-query outside of Zed?

Accepted Answer

gpui-query is designed for the GPUI framework, which powers the Zed editor. While architecturally the Core layer is framework-agnostic, the Hook layer depends on GPUI's reactive primitives.

Question 3

How do I set up QueryClient in my app?

Accepted Answer

Create a QueryClient instance and register it in your GPUI application. The client manages all query resources, caching, and garbage collection. See the Getting Started guide for a complete walkthrough.

Question 4

Why does use_query return a tuple instead of an object?

Accepted Answer

Following Rust convention, use_query returns a tuple (data, status) for ergonomic destructuring. The status enum provides complete lifecycle information.

Question 5

What happens if my component unmounts during a fetch?

Accepted Answer

gpui-query uses cooperative cancellation via QuerySignal (Arc<AtomicBool>). When a component unmounts, the signal is set and the query checks it between retry attempts, enabling clean teardown.

Question 6

What is QuerySignal and when do I check it?

Accepted Answer

QuerySignal is an Arc<AtomicBool> that enables cooperative cancellation. Long-running queries should check the signal periodically (especially between retry attempts) and abort early if cancelled.

Question 7

Why does LatestWins cancel my in-flight request?

Accepted Answer

LatestWins is a RequestPolicy that ensures only the most recent request's result is used. When a new request arrives, previous in-flight requests are cancelled via their signals, preventing stale data from overwriting fresh results.

Question 8

How do I persist my query cache?

Accepted Answer

Implement the QueryPersister trait to serialize and restore query state. gpui-query supports custom persistence backends — you can use files, databases, or any storage mechanism.

Question 9

How do I handle pagination?

Accepted Answer

Use use_infinite_query for paginated data. It supports bidirectional fetching (fetch_next_page_infinite / fetch_previous_page_infinite) and configurable max_pages to limit cached pages.

Question 10

Is there a devtools experience?

Accepted Answer

gpui-query provides ClientDiagnostic types and dehydrate/hydrate methods for inspecting cache state, query status, and resource lifecycle — a developer toolkit for debugging async state.

Frequently Asked Questions

Getting Started

Architecture

Advanced

Still have questions?