query_flow/
query.rs

1//! Query trait definition.
2
3use std::sync::Arc;
4
5use crate::db::Db;
6use crate::key::CacheKey;
7use crate::QueryError;
8
9/// A query that can be executed and cached.
10///
11/// Queries are the fundamental unit of computation in query-flow. Each query:
12/// - Is itself the cache key (implements `Hash + Eq`)
13/// - Produces an output value
14/// - Can depend on other queries via `db.query()`
15///
16/// # Sync by Design
17///
18/// The `query` method is intentionally synchronous. This avoids the "function
19/// coloring" problem where async infects the entire call stack. For async
20/// operations, use the suspense pattern with `AssetLoadingState`.
21///
22/// # Error Handling
23///
24/// The `query` method returns `Result<Output, QueryError>` where:
25/// - `QueryError` represents system errors (Suspend, Cycle, Cancelled)
26/// - User domain errors should be wrapped in `Output`, e.g., `type Output = Result<T, MyError>`
27///
28/// This means fallible queries return `Ok(Ok(value))` on success and `Ok(Err(error))` on user error.
29///
30/// # Example
31///
32/// ```ignore
33/// use query_flow::{Query, Db, QueryError};
34///
35/// // Simple infallible query
36/// #[derive(Clone, Debug, Hash, PartialEq, Eq)]
37/// struct Add { a: i32, b: i32 }
38///
39/// impl Query for Add {
40///     type Output = i32;
41///
42///     fn query(self, _db: &impl Db) -> Result<Arc<Self::Output>, QueryError> {
43///         Ok(Arc::new(self.a + self.b))
44///     }
45///
46///     fn output_eq(old: &Self::Output, new: &Self::Output) -> bool {
47///         old == new
48///     }
49/// }
50///
51/// // Fallible query with user errors
52/// #[derive(Clone, Debug, Hash, PartialEq, Eq)]
53/// struct ParseInt { input: String }
54///
55/// impl Query for ParseInt {
56///     type Output = Result<i32, std::num::ParseIntError>;
57///
58///     fn query(self, _db: &impl Db) -> Result<Arc<Self::Output>, QueryError> {
59///         Ok(Arc::new(self.input.parse()))  // Ok(Arc(Ok(n))) or Ok(Arc(Err(parse_error)))
60///     }
61///
62///     fn output_eq(old: &Self::Output, new: &Self::Output) -> bool {
63///         old == new
64///     }
65/// }
66/// ```
67pub trait Query: CacheKey + Clone + Send + Sync + 'static {
68    /// The output type of this query.
69    ///
70    /// For fallible queries, use `Result<T, E>` here.
71    type Output: Send + Sync + 'static;
72
73    /// Execute the query, returning the output wrapped in Arc or a system error.
74    ///
75    /// The result is wrapped in `Arc` for efficient sharing in the cache.
76    /// Use the `#[query]` macro to automatically handle Arc wrapping.
77    ///
78    /// # Arguments
79    ///
80    /// * `db` - The database for accessing dependencies
81    ///
82    /// # Returns
83    ///
84    /// * `Ok(arc_output)` - Query completed successfully
85    /// * `Err(QueryError::Suspend)` - Query is waiting for async loading
86    /// * `Err(QueryError::Cycle)` - Dependency cycle detected
87    fn query(self, db: &impl Db) -> Result<Arc<Self::Output>, QueryError>;
88
89    /// Compare two outputs for equality (for early cutoff optimization).
90    ///
91    /// When a query is recomputed and the output is equal to the previous
92    /// output, downstream queries can skip recomputation (early cutoff).
93    ///
94    /// The `#[query]` macro generates this using `PartialEq` by default.
95    /// Use `output_eq = custom_fn` for types without `PartialEq`.
96    fn output_eq(old: &Self::Output, new: &Self::Output) -> bool;
97}
98
99/// Convenience trait for query output types.
100///
101/// This trait combines the bounds needed for a type to be used as a query output:
102/// `PartialEq + Send + Sync + 'static`.
103///
104/// - `PartialEq` is required for the default `output_eq` comparison (early cutoff optimization)
105/// - `Send + Sync + 'static` allows the output to be cached and shared across threads
106///
107/// # When to Use
108///
109/// Use `QueryOutput` for generic type parameters that appear only in query output:
110///
111/// ```ignore
112/// #[query]
113/// fn parse<T: QueryOutput + FromStr>(db: &impl Db, text: String) -> Result<T, QueryError>
114/// where
115///     T::Err: Display,
116/// {
117///     text.parse().map_err(|e| anyhow!("{}", e).into())
118/// }
119/// ```
120///
121/// # When Not to Use
122///
123/// If you're using `#[query(output_eq = none)]` or a custom `output_eq` function,
124/// you don't need `PartialEq`. In that case, use raw bounds instead:
125///
126/// ```ignore
127/// #[query(output_eq = none)]
128/// fn create<T: Send + Sync + 'static>(db: &impl Db) -> Result<T, QueryError> { ... }
129/// ```
130pub trait QueryOutput: PartialEq + Send + Sync + 'static {}
131impl<T: PartialEq + Send + Sync + 'static> QueryOutput for T {}
query_flow/query.rs

query_flow/
query.rs
