gpui_query/lib.rs
1//! gpui-query — Zero-boilerplate async state management for GPUI.
2//!
3//! Inspired by [TanStack Query v5](https://tanstack.com/query), redesigned for
4//! GPUI's synchronous rendering model and Rust's ownership semantics.
5//!
6//! # v2 Improvements over v1
7//!
8//! - **Options-first API** with sensible defaults — `use_query("users", fetcher, cx)`
9//! - **Tuple return types** — hooks return `(Entity<QueryResource<T,E>>, Subscription)` for explicit control
10//! - **Signal-always** — fetchers always receive `QuerySignal` for cooperative cancellation
11//! - **Fixed signal lifecycle** — signals are cancelled on LatestWins replacement
12//! - **Fixed retry loops** — single counter, signal checked between attempts
13//! - **Efficient re-renders** — `cx.notify()` only on terminal state changes
14//! - **`QueryError: Display + Error`** — ecosystem interop with `?` and `anyhow`
15//! - **`AHashMap`** for trusted cache keys — ~2x faster lookups
16//! - **Bounded `max_pages`** default — prevents unbounded memory growth
17//! - **Actual mutation GC** — no more memory leaks
18//!
19//! # Layers
20//!
21//! - **`core`** — Serde-only state machine (`QueryResource`, `CachePolicy`, etc.)
22//! - **`client`** — GPUI `QueryClient` registry with type-partitioned buckets
23//! - **`hook`** — `use_query()` / `use_mutation()` / `use_infinite_query()` hooks
24//!
25//! # Quick Start
26//!
27//! Hooks are re-exported at the crate root for ergonomic imports:
28//!
29//! ```ignore
30//! use gpui_query::{use_query, use_mutation, use_infinite_query, QueryClient};
31//! ```
32
33// T5: enable `#[doc(cfg(...))]` attribute gating on docs.rs builds so the
34// rendered API docs annotate items with the feature gate that enables them
35// (`core`, `client`, `hook`). `doc_cfg` is a nightly-only intradoc feature,
36// so it is only turned on under the `docsrs` config attribute.
37#![cfg_attr(docsrs, feature(doc_cfg))]
38
39#[cfg(feature = "core")]
40#[cfg_attr(docsrs, doc(cfg(feature = "core")))]
41pub mod core;
42
43#[cfg(feature = "client")]
44#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
45pub mod client;
46
47#[cfg(feature = "hook")]
48#[cfg_attr(docsrs, doc(cfg(feature = "hook")))]
49pub mod hook;
50
51// Convenience re-exports (star-export each enabled layer at crate root).
52//
53// `current_time_ms` is defined in both `client` and `hook` modules with
54// identical implementations. Both glob re-exports are intentional so that
55// users can import from either layer. Suppress the ambiguous_glob_reexports
56// lint since the duplicate is harmless and both are public API.
57#[cfg(feature = "core")]
58#[cfg_attr(docsrs, doc(cfg(feature = "core")))]
59pub use core::*;
60
61#[cfg(feature = "client")]
62#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
63#[allow(ambiguous_glob_reexports)]
64pub use client::*;
65
66#[cfg(feature = "hook")]
67#[cfg_attr(docsrs, doc(cfg(feature = "hook")))]
68pub use hook::*;
69
70// ── Tests ──────────────────────────────────────────────────────────────
71
72#[cfg(test)]
73mod tests;