sqry_core/query/builder/mod.rs
1//! Query Builder API for type-safe programmatic query construction
2//!
3//! This module provides a fluent builder API for constructing queries programmatically
4//! without parsing string queries. It offers compile-time safety for field names and
5//! operators, with runtime validation against the [`FieldRegistry`](crate::query::FieldRegistry).
6//!
7//! # Features
8//!
9//! - **Type-safe construction**: Methods for all core fields prevent typos
10//! - **Fluent API**: Method chaining for readable query construction
11//! - **Validation**: Field, operator, value type, and enum constraint validation
12//! - **Error accumulation**: All errors reported at `build()` time, not per-method
13//! - **Zero-copy optimization**: Uses `Cow<'static, str>` for static field names
14//!
15//! # Example
16//!
17//! ```ignore
18//! use sqry_core::query::builder::QueryBuilder;
19//!
20//! // Simple condition
21//! let query = QueryBuilder::kind("function")
22//! .build()?;
23//!
24//! // Combined conditions
25//! let query = QueryBuilder::kind("function")
26//! .and(QueryBuilder::lang("rust"))
27//! .and_not(QueryBuilder::name_matches("test.*"))
28//! .build()?;
29//!
30//! // OR conditions using static constructor
31//! let query = QueryBuilder::any(vec![
32//! QueryBuilder::kind("function"),
33//! QueryBuilder::kind("method"),
34//! ])
35//! .and(QueryBuilder::lang("rust"))
36//! .build()?;
37//!
38//! // Regex with custom flags
39//! let query = QueryBuilder::name_matches_with("Test.*", |rb| rb.case_insensitive())
40//! .build()?;
41//! ```
42//!
43//! # Architecture
44//!
45//! The builder is a thin layer over the existing Query AST types. It provides:
46//!
47//! 1. **Type-safe construction** of [`Expr`](crate::query::Expr) nodes
48//! 2. **Validation** against [`FieldRegistry`](crate::query::FieldRegistry)
49//! 3. **Conversion** to executable [`QueryAST`](crate::query::QueryAST) structures
50//!
51//! # Validation
52//!
53//! Validation is performed lazily at `build()` time:
54//!
55//! - Field existence (with alias resolution)
56//! - Operator compatibility with field type
57//! - Value type matching
58//! - Enum value validation (for `kind`, `scope`, `scope.type`)
59//! - Regex pattern syntax validation
60
61mod condition;
62mod error;
63mod query_builder;
64mod regex;
65
66pub use condition::ConditionBuilder;
67pub use error::BuildError;
68pub use query_builder::QueryBuilder;
69pub use regex::RegexBuilder;
70
71#[cfg(test)]
72mod tests;