flusso_query/handles/
mod.rs

1//! Field handles. Each handle carries a field path **and a scope** `S`, and
2//! exposes only the operators its mapping type supports; every operator builds a
3//! [`Query`]`<S>`.
4//!
5//! Root fields and flattened object / to-one-join sub-fields are scope
6//! [`Root`](crate::Root); a `nested` array's element handles carry the element type as their
7//! scope, so their queries must be lifted with [`Nested::any`]/[`Nested::all`]
8//! before joining a parent query. (The derive picks the right scope; hand-written
9//! handles default to `Root`.)
10//!
11//! The handles are grouped by field family:
12//!
13//! - `string` — [`Keyword`], [`Text`], and the cross-field [`multi_match`].
14//! - `scalar` — [`Bool`], [`Number`], [`Date`] (exact/range value fields).
15//! - `nested` — [`Nested`] arrays and their [`NestedProjection`].
16//! - `object` — [`Object`] sub-documents and the opaque [`Binary`]/[`Json`] fields.
17//! - `geo` — [`Geo`] points and [`GeoPoint`].
18//! - `sort` — [`Sort`]/[`SortOrder`].
19//!
20//! This module holds the pieces they share: the leaf-query builders and the
21//! [`trait@FlussoValue`] type-kind machinery.
22
23use serde_json::{Map, Value};
24
25use crate::query::Query;
26
27mod geo;
28mod nested;
29mod object;
30mod scalar;
31mod sort;
32mod string;
33
34pub use geo::{Geo, GeoPoint};
35pub use nested::{Nested, NestedProjection};
36pub use object::{Binary, Json, Object};
37pub use scalar::{Bool, Date, Number};
38pub use sort::{Sort, SortOrder};
39pub use string::{Keyword, Text, multi_match};
40
41/// `{ "<wrapper>": { "<path>": <value> } }`.
42fn single<S>(wrapper: &str, path: &str, value: Value) -> Query<S> {
43    let mut inner = Map::new();
44    inner.insert(path.to_string(), value);
45    let mut outer = Map::new();
46    outer.insert(wrapper.to_string(), Value::Object(inner));
47    Query::leaf(Value::Object(outer))
48}
49
50/// `{ "exists": { "field": "<path>" } }`.
51fn exists_q<S>(path: &str) -> Query<S> {
52    let mut inner = Map::new();
53    inner.insert("field".to_string(), Value::String(path.to_string()));
54    let mut outer = Map::new();
55    outer.insert("exists".to_string(), Value::Object(inner));
56    Query::leaf(Value::Object(outer))
57}
58
59/// `{ "range": { "<path>": { <bounds…> } } }`.
60fn range_q<S>(path: &str, bounds: Vec<(&str, Value)>) -> Query<S> {
61    let mut body = Map::new();
62    for (key, value) in bounds {
63        body.insert(key.to_string(), value);
64    }
65    single("range", path, Value::Object(body))
66}
67
68/// `{ "match_all": {} }`.
69pub(crate) fn match_all_value() -> Value {
70    let mut outer = Map::new();
71    outer.insert("match_all".to_string(), Value::Object(Map::new()));
72    Value::Object(outer)
73}
74
75/// Field-category markers for [`trait@FlussoValue`]. Zero-size and uninhabited — they
76/// exist only as the `K` type parameter, so one type can be a valid value for
77/// several kinds (e.g. `String` is a [`kind::Keyword`], [`kind::Text`], and
78/// [`kind::Date`] value).
79pub mod kind {
80    /// A `keyword` field — an exact string.
81    #[derive(Debug)]
82    pub enum Keyword {}
83    /// A `text` field — an analyzed string.
84    #[derive(Debug)]
85    pub enum Text {}
86    /// A numeric field (`byte`…`double`, `scaled_float`).
87    #[derive(Debug)]
88    pub enum Number {}
89    /// A `date`/`timestamp` field — an ISO-8601 string.
90    #[derive(Debug)]
91    pub enum Date {}
92}
93
94/// A Rust type usable where a field of kind `K` is expected: as the field type
95/// in a `#[derive(FlussoDocument)]` struct, and (for [`kind::Keyword`]) as a
96/// query value on [`Keyword::eq`]/[`Keyword::in_`].
97///
98/// Built-in leaf types are pre-implemented (`String`/`&str` for keyword, the
99/// numeric primitives for number, …). Custom enums and newtype wrappers opt in
100/// with `#[derive(FlussoValue)]` (e.g. a `Pro`/`Enterprise`/`Free` tier enum →
101/// `Account::tier().eq(AccountTier::Pro)`, matched against its serde string).
102/// `FlussoDocument` emits a deferred bound on this trait for any non-primitive
103/// field type, so a document only compiles when the type genuinely fits.
104#[diagnostic::on_unimplemented(
105    message = "`{Self}` is not a valid value for a `{K}` field",
106    label = "unsupported field type",
107    note = "use a built-in leaf type, or add `#[derive(FlussoValue)]` (with the matching kind) to `{Self}`"
108)]
109pub trait FlussoValue<K> {}
110
111impl FlussoValue<kind::Keyword> for String {}
112impl FlussoValue<kind::Keyword> for &str {}
113
114impl FlussoValue<kind::Text> for String {}
115impl FlussoValue<kind::Text> for &str {}
116
117impl FlussoValue<kind::Number> for i8 {}
118impl FlussoValue<kind::Number> for i16 {}
119impl FlussoValue<kind::Number> for i32 {}
120impl FlussoValue<kind::Number> for i64 {}
121impl FlussoValue<kind::Number> for f32 {}
122impl FlussoValue<kind::Number> for f64 {}
123#[cfg(feature = "decimal")]
124impl FlussoValue<kind::Number> for crate::Decimal {}
125
126impl FlussoValue<kind::Date> for String {}
flusso_query/handles/mod.rs

flusso_query/handles/
mod.rs
