Expand description
ยงMoonGraphQL Builder ๐
A high-performance, strictly typed GraphQL query and document generation framework
powered by the Type-State Pattern (compile-time field deduplication and auto-complete suppression),
proactive AST budget metric calculations (Complexity and Depth), automated GraphQL Variable
parametrization, and Project Fluent multi-locale diagnostics.
The framework is completely Transport Agnostic and can be seamlessly integrated
with any asynchronous or blocking HTTP client (moonclient,
reqwest, surf, ureq, etc.).
ยง๐ Quick Start
Here is a complete, copy-paste-ready example demonstrating typed selector definition, query builder generation with declarative validation, preemptive AST metric checks, and compilation into both inline queries and parameterized GraphQL variables:
use moongraphql_builder::prelude::*;
// 1. Declare a Type-State field selector with base complexity
define_selector! {
#[default_complexity = 1]
#[default = "id name"]
pub struct UserSelector {
#[complexity = 1]
id: id,
#[complexity = 1]
name: name,
#[complexity = 1]
email: email,
}
}
// 2. Declare a query builder with boundary constraints
define_query_builder! {
#[root = user]
#[selector = UserSelector]
pub struct UserQueryBuilder {
#[validate(required)]
id: u32 => id("ID!", scalar),
}
}
// 3. Assemble query with fluent syntax and compile-time deduplication
let query = UserQueryBuilder::new()
.id(42)
.select(|f| f.id().name().email());
// 4. Preemptive metric verification
assert_eq!(query.complexity(), 1 + 3); // 1 (root) + 3 (fields) = 4
assert_eq!(query.depth(), 1);
// 5. Preemptive client-side validation
let validator = MetricValidator::new(190, 5);
validator.validate(&query)?;
// 6. Compile to clean inline GraphQL string
println!("Compiled Query:\n{}", query._build_query());ยง๐๏ธ Architectural Pillars
- Compile-Time Field Deduplication: Utilizes generic
constbooleans and the Type-State pattern in generated field selectors. Physically removes already-selected fields from IDE code completion lists and prohibits redundant duplicate selections at compile time without runtime sets. - Deterministic Canonical AST: Fields are automatically deduplicated and alphabetically sorted
via
std::collections::BTreeSet, guaranteeing reproducible query hashes and optimal HTTP cache hits. - Proactive AST Complexity & Depth Budgeting: Calculates theoretical query weight and tree depth
before dispatching requests over the network, protecting applications against remote HTTP
422and429rejections from servers enforcing strict schema complexity limits. - Namespaced Variable Parametrization: Transparently extracts literal values into strongly typed
GraphQL Variables (
$animes_search: String,$mangas_limit: PositiveInt), avoiding variable name collisions when batching diverse multi-root queries into a single document. - Multi-Root Composite Documents: Assemble disparate root queries (
animes,mangas,users) into a single cohesive GraphQL document executed within a single network round-trip time (1 RTT). - Concurrent Request Batching: Native HTTP request batching (
BatchDocumentBuilder) with per-query isolated complexity budgets and parallel asynchronous execution. - Embedded Localization: Built-in multi-language diagnostic engine powered by
fluent, supporting dual-locale (en/ru) validation diagnostics.
ยง๐๏ธ Pipeline Execution Flow
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ define_selector! & define_query_builder! โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 1. Static Compile-Time Analysis: Type-State Deduplication (const field: bool)โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 2. Preemptive Metric Evaluation (GqlInspectable: Complexity & Depth) โ
โ โข Evaluates base weights + field weights locally in memory โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 3. Preemptive Argument Validation (GqlValidatable: min, max, range, custom) โ
โ โข Localized diagnostic errors rendered via Project Fluent (i18n) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 4. Dual Compilation Modes (BuildableQuery) โ
โ โโโบ Inline Query: query { animes(limit: 5) { id name } } โ
โ โโโบ Parameterized: query ($limit: Int) { ... } + JSON Variables โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 5. Network Dispatch (via MoonClient, reqwest, or BatchDocumentBuilder) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโยง๐งฉ Feature Flags
| Feature | Description | Dependencies | Default |
|---|---|---|---|
tokio | Enables Task-Local locale context storage via tokio::task_local. | tokio | Enabled |
Re-exportsยง
pub use prelude::*;
Modulesยง
- batch
- Generic HTTP request batching generator and concurrent executor for GraphQL operations.
- error
- Domain error models and result types for the MoonGraphQL Builder framework.
- i18n
- Dynamic internationalization (i18n) and localized diagnostic engine for GraphQL builders.
- macros
- Declarative macro generators for Type-State GraphQL selectors, query builders, and composite coordinators.
- metrics
- Pre-flight metric validation engine for AST tree complexity and selector depth.
- payload
- Standardized GraphQL network payload and transport models compliant with the GraphQL over HTTP specification.
- prelude
- Canonical crate prelude providing seamless access to public builders, macros, and traits.
- traits
- Fundamental trait contracts for compiled Type-State GraphQL selectors, query builders, and metrics.
- validation
- Context models and metadata descriptors for hybrid client-side GraphQL query validation.
Macrosยง
- define_
composite_ query - Declarative macro for generating composite multi-root GraphQL document coordinators.
- define_
query_ builder - Declarative macro for generating strongly typed GraphQL query builders with hybrid validation.
- define_
selector - Declarative macro for generating Type-State GraphQL field selectors with compile-time deduplication, full closure type inference, and an integrated AST complexity/depth calculator.
- tr
- Primary declarative macro for formatting and interpolating
moongraphql_buildermessages.