ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! The storage side of a query: the COMPARISON types, and the crossing a filter makes to reach one.
//!
//! ```text
//! row     VideoTrack        ⇄ VideoTrackPostgres            ⇄ INSERT / SELECT
//! filter  VideoTrackFilter  → VideoTrackPostgresComparison  → WHERE "bitrate" = ?
//!         (domain values)      (storage values)
//! ```
//!
//! A filter is the client's vocabulary — one per entity, holding DOMAIN values, rendered as a
//! GraphQL input object. A comparison is the storage's — one per (entity × backend), holding
//! STORAGE values, lowered by binding. The crossing between them is where a value enters the
//! database, and it happens exactly once.
//!
//! # Why the two vocabularies are not one
//!
//! A filter is backend-NEUTRAL: `ScalarFilter<i64>` is the same type whichever database answers it,
//! which is why [`GraphqlFilter::is_empty`](crate::GraphqlFilter) can be asked without naming a
//! dialect. A comparison is backend-SPECIFIC by construction: `SqlScalarComparison<V, Db>` carries
//! its `Db` in its own type. That difference is structural rather than stylistic, and it is the
//! reason there is no neutral `DatabaseComparison` trait beside
//! [`GraphqlFilter`](crate::GraphqlFilter) — a comparison has no ambiguity for one to resolve.
//!
//! # The neutral pieces, and the family beside them
//!
//! - [`Backend`] — the storage backend a comparison renders for, owning the builder every
//!   comparison of that backend threads and the refusal they can return.
//! - [`ComplexComparison<B>`] — the lowering itself: the builder passes THROUGH a comparison rather
//!   than being written into, which is what lets one name two or more columns and nest without
//!   bound.
//! - [`At`] / [`RecordAddress`] — WHERE a comparison is being applied: the column, and the row it
//!   constrains. A leaf reads the column and ignores the row; a correlated predicate needs both,
//!   and neither is in a filter. Carrying it here rather than at the crossing is what keeps
//!   [`TryFromFilter`] taking a filter and nothing else.
//! - [`Path`] / [`Frame`] — the SEGMENTS naming that column, and the link a layer pushes to extend
//!   them. A comparison occupying several columns pushes one frame per part rather than being
//!   handed a name per column — so there is no pair to hand over in the wrong order, and the TOP
//!   level is the empty path rather than a name nobody can supply.
//! - [`CompositeComparison<B>`] — that a comparison occupies more than one column, which a scalar
//!   does not claim. It is what refuses `flatten` on a field whose name IS its column, and
//!   [`ToFlattenedComparison<V, Db>`] is the blanket-implemented form of that requirement an expansion
//!   can spell.
//! - [`CollapsibleComparison<B>`] — that a comparison over a ROW can hand back its constraint on
//!   that row's own id, and only when the id is all it constrains. A relation over a to-one
//!   reference renders that constraint on the FOREIGN KEY and skips its subquery entirely.
//! - [`ReferentialComparison<B>`] — that a comparison can SAY whether its constraint is a plain
//!   equality or membership. It is the half of the law above that a generic implementor cannot read
//!   for itself, and its absence is what refuses a collapse rather than silently declining one.
//! - [`ToDatabaseComparison<V, Db>`] — the type-level map from a filter KIND to the comparison it
//!   crosses into. Keyed on the filter rather than on the storage type, because the OPERATOR SET
//!   must survive the crossing: `TextFilter<String>` and `ScalarFilter<String>` share a storage type
//!   and are not the same question.
//! - [`ToRelatedComparison<C, Db>`] — the same map for a RELATION position, whose parameter is the
//!   far side's PREDICATE rather than a storage type. It carries no item bound — see its note for
//!   the mutual-relation cycle one closes — and [`ToLoweredRelatedComparison<C, Db>`] is the
//!   refinement a record's own lowering states and spends, carrying the rendering as METHODS so no
//!   projection has to be named at a generic dialect.
//! - [`FromFilter<F>`] / [`TryFromFilter<F>`] — the crossing itself, shaped like [`From`]/[`TryFrom`]
//!   and related by the same blanket.
//! - `RelationWidthError` / `RelationDepthError` — the two causes a relation predicate refuses for
//!   on EVERY backend: an address of more than one column, and a nesting past the aliases minted for
//!   it. The enums holding them are per family and the facts are not, so the payloads are here and
//!   each family re-exports them. Behind the two backend gates together, since a build with no
//!   backend has nothing that renders a relation.
//! - [`TextMatch`] — WHICH substring form a text match asks for, which is the question and not the
//!   rendering: the three members are the same three on every backend, and what a family builds from
//!   one is its own. It is here rather than inside a family for the reason the storage forms are in
//!   `storage` — a gate belonging to one of them was making the other declare a copy.
//! - `sql` — the first comparison family, behind the `sqlx` feature.
//! - `mongo` — the second, behind the `mongo` feature, entering through its own [`Backend`] row and
//!   changing nothing above it. Where the fit is loose rather than clean is recorded in that
//!   module's own note and at [`Backend`]'s two answers it measured.
//!
//! # A family is a MODULE, and its items keep its segment
//!
//! `sql`'s vocabulary is addressed through it — `sql::SqlScalarComparison`, not a name lifted to
//! sit beside the neutral pieces. What that separates is the two audiences: the traits above are
//! implemented and named by hand, while a comparison kind, a clause state and a rendering helper
//! are written by an expansion, and one namespace holding both makes `WhereClause` look like a name
//! this crate offers. The few family items a PERSON does write — the join surfaces — are
//! re-exported at the crate root, where a human is already looking.
//!
//! The storage types a declaration spells are re-exported there too and are NOT a family's: a
//! big-endian blob and a temporal wrapper name no database, and keeping them inside `sql` gated them
//! on `sqlx` — so a `u64` field was declarable on SQLite and undeclarable on MongoDB for a reason
//! belonging to neither. They live in the crate's `storage` module, and each family writes its own
//! carrier row for them.
//!
//! [`GraphqlFilter`]: crate::GraphqlFilter

mod backend;
mod complex;
mod convert;
mod lower;
#[cfg(feature = "mongo")]
pub mod mongo;
#[cfg(any(feature = "mongo", feature = "sqlx"))]
mod relation;
#[cfg(feature = "sqlx")]
pub mod sql;
#[cfg(all(feature = "jiff", feature = "time"))]
mod temporal;
mod text;

pub use backend::Backend;
pub use complex::{
  At, CollapsibleComparison, ComplexComparison, CompositeComparison, Frame, Path, RecordAddress,
  ReferentialComparison,
};
pub use convert::{FromFilter, TryFromFilter};
pub use lower::{
  ToCrossedComparison, ToDatabaseComparison, ToFlattenedComparison, ToLoweredRelatedComparison,
  ToRelatedComparison,
};
#[cfg(any(feature = "mongo", feature = "sqlx"))]
pub use relation::{RelationDepthError, RelationWidthError};
#[cfg(all(feature = "jiff", feature = "time"))]
pub use temporal::TemporalStorage;
pub use text::TextMatch;