query_flow/lib.rs
1//! Query-Flow: A high-level query framework for incremental computation.
2//!
3//! Built on top of [`whale`], this crate provides a user-friendly API for defining
4//! and executing queries with automatic caching and dependency tracking.
5//!
6//! # Key Features
7//!
8//! - **Async-agnostic queries**: Write sync query logic, run with sync or async runtime
9//! - **Automatic caching**: Query results are cached and invalidated based on dependencies
10//! - **Suspense pattern**: Handle async loading with `AssetLoadingState` without coloring functions
11//! - **Type-safe**: Per-query-type caching with compile-time guarantees
12//! - **Early cutoff**: Skip downstream recomputation when values don't change
13//! - **External GC support**: Build custom garbage collection strategies using the Tracer API
14//!
15//! # Example
16//!
17//! ```
18//! use query_flow::{query, Db, QueryError, QueryRuntime};
19//!
20//! #[query]
21//! fn add(db: &impl Db, a: i32, b: i32) -> Result<i32, QueryError> {
22//! let _ = db;
23//! Ok(a + b)
24//! }
25//!
26//! let runtime = QueryRuntime::new();
27//! let result = runtime.query(Add::new(1, 2)).unwrap();
28//! assert_eq!(*result, 3);
29//! ```
30//!
31//! # Garbage Collection
32//!
33//! Query-flow provides primitives for implementing custom GC strategies externally:
34//!
35//! - [`Tracer::on_query_key`] - Track query access for LRU/TTL algorithms
36//! - [`QueryRuntime::query_keys`] - Enumerate all cached queries
37//! - [`QueryRuntime::remove`] / [`QueryRuntime::remove_if_unused`] - Remove queries by [`FullCacheKey`]
38//! - [`QueryRuntime::remove_query`] / [`QueryRuntime::remove_query_if_unused`] - Remove queries by typed key
39//!
40//! See the [`tracer`] module and GC methods on [`QueryRuntime`] for details.
41
42// Allow the macro to reference query_flow types when used inside this crate
43extern crate self as query_flow;
44
45mod asset;
46mod db;
47mod error;
48mod key;
49mod loading;
50pub mod output_eq;
51mod query;
52mod runtime;
53mod storage;
54pub mod tracer;
55
56pub use asset::{AssetKey, AssetLocator, DurabilityLevel, LocateResult, PendingAsset};
57pub use db::Db;
58pub use error::{QueryError, QueryResultExt, TypedErr};
59pub use key::{
60 AssetCacheKey, AssetKeySetSentinelKey, Cachable, CacheKey, FullCacheKey, QueryCacheKey,
61 QuerySetSentinelKey,
62};
63pub use loading::AssetLoadingState;
64pub use query::{Query, QueryOutput};
65pub use query_flow_macros::{asset_key, asset_locator, query};
66pub use runtime::{ErrorComparator, Polled, QueryRuntime, QueryRuntimeBuilder};
67pub use tracer::{
68 ExecutionResult, InvalidationReason, NoopTracer, SpanContext, SpanId, TraceId, Tracer,
69 TracerAssetState,
70};
71
72// Re-export RevisionCounter from whale for use with poll() and changed_at()
73pub use whale::RevisionCounter;