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//! ```ignore
18//! use query_flow::{query, QueryContext, QueryError, QueryRuntime};
19//!
20//! #[query]
21//! fn add(ctx: &mut QueryContext, a: i32, b: i32) -> Result<i32, QueryError> {
22//! Ok(a + b)
23//! }
24//!
25//! let runtime = QueryRuntime::new();
26//! let result = runtime.query(Add::new(1, 2)).unwrap();
27//! assert_eq!(*result, 3);
28//! ```
29//!
30//! # Garbage Collection
31//!
32//! Query-flow provides primitives for implementing custom GC strategies externally:
33//!
34//! - [`Tracer::on_query_key`] - Track query access for LRU/TTL algorithms
35//! - [`QueryRuntime::query_keys`] - Enumerate all cached queries
36//! - [`QueryRuntime::remove`] / [`QueryRuntime::remove_if_unused`] - Remove queries by [`FullCacheKey`]
37//! - [`QueryRuntime::remove_query`] / [`QueryRuntime::remove_query_if_unused`] - Remove queries by typed key
38//!
39//! See the [`tracer`] module and GC methods on [`QueryRuntime`] for details.
40
41// Allow the macro to reference query_flow types when used inside this crate
42extern crate self as query_flow;
43
44mod asset;
45mod db;
46mod error;
47mod key;
48mod loading;
49pub mod output_eq;
50mod query;
51mod runtime;
52mod storage;
53pub mod tracer;
54
55pub use asset::{AssetKey, AssetLocator, DurabilityLevel, LocateResult, PendingAsset};
56pub use db::Db;
57pub use error::{QueryError, QueryResultExt, TypedErr};
58pub use key::{FullCacheKey, Key};
59pub use loading::AssetLoadingState;
60pub use query::Query;
61pub use query_flow_macros::{asset_key, query};
62pub use runtime::{ErrorComparator, Polled, QueryContext, QueryRuntime, QueryRuntimeBuilder};
63pub use tracer::{
64 ExecutionResult, InvalidationReason, NoopTracer, SpanId, Tracer, TracerAssetKey,
65 TracerAssetState, TracerQueryKey,
66};
67
68// Re-export RevisionCounter from whale for use with poll() and changed_at()
69pub use whale::RevisionCounter;