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 crossing: [`FromGraphqlOrderBy`] and [`TryFromGraphqlOrderBy`].
//!
//! One step, two spellings, related exactly as [`From`] and [`TryFrom`] are — including the blanket
//! that lifts the infallible one into the fallible one. That shape is not decoration: it is what
//! makes an emitted crossing PROVABLY infallible, through an
//! [`Infallible`](core::convert::Infallible) error type, rather than merely always returning `Ok`.
//!
//! It is [`comparison::convert`](crate::comparison::convert)'s file one axis over, and the mirror is
//! deliberate. A filter crosses into a comparison; an ORDER crosses into a level sequence. Both
//! crossings are the single place storage enters, both are named steps in the architecture rather
//! than anonymous conversions, and both have exactly one fallible seat — so the two read alike and a
//! reader who has learnt one has learnt the other.
//!
//! # Why not [`TryFrom`] itself
//!
//! Two reasons, and they are the comparison crossing's own. Its `Into` blanket is in the way —
//! `impl<T, U: Into<T>> TryFrom<U> for T` already occupies the shape the emitted orders need. And
//! this step has a NAME in the architecture: the crossing, where a WIRE order becomes a DATABASE's
//! level sequence, once. A local trait keeps that greppable.
//!
//! The orphan situation is identical either way. A downstream cannot write a conversion INTO one of
//! this crate's orders under either trait, because the self type is foreign to it; a downstream
//! order brings both halves or neither.
//!
//! # What crosses, and what has already happened when it does
//!
//! `O` is the COMPLETED wire order — the client's terms, in the sequence it wrote them, with the
//! record's key tail appended by the emitted `<T>OrderBy::complete`. Everything the WIRE can refuse
//! has been refused before this point: [`Orderings`](crate::Orderings)' decode turned away a
//! repeated subject at the door, and `complete` MOVED the key rather than repeating it. So a
//! crossing never sees a malformed order and has no wire-shaped refusal to carry.
//!
//! `Self` is the per-database storage order — [`Record::OrderBy`](crate::Record::OrderBy) — which is
//! the LEVEL SEQUENCE a dialect really sorts by. A citizen's one wire word becomes its levels here
//! and nowhere else, which is what keeps the expansion out of every emitter that renders an order.
//!
//! # Fallibility lives AT the crossing, and the sentence is the comparison crossing's
//!
//! Once levels exist, rendering them binds and cannot fail — the same statement every SQL dialect's
//! [`Backend::Error`](crate::Backend::Error) being [`Infallible`](core::convert::Infallible) already
//! makes about a comparison. So the fallible half is not there for today's orders; it is the NAMED
//! ARRIVAL POINT for the words that will need it: a collation a dialect cannot express, a wire-only
//! variant crossed into a storage term, a MongoDB sort a document family refuses. Each of those is a
//! reason a crossing could say no, and each would otherwise have to invent a seat for itself.

/// The infallible crossing: build a database's level sequence from a completed wire order that
/// needs no conversion.
///
/// The shape [`From`] has, for the reason [`From`] has it — and the half an emitted crossing
/// implements, because the expansion is TOTAL over the admitted variants: every variant of a
/// `<T>OrderBy` is one this record's own emission wrote, and each one's levels are that column
/// type's own answer. [`TryFromGraphqlOrderBy`] follows from it through the blanket below, so
/// implementing this gives both.
pub trait FromGraphqlOrderBy<O> {
  /// Cross `order` into this database's level sequence.
  fn from_graphql_order_by(order: O) -> Self;
}

/// The fallible crossing: build a database's level sequence from a completed wire order, expanding
/// each term.
///
/// # What the error is, and is not
///
/// It is the EXPANSION's own — whatever a level sequence this dialect cannot express reports. It is
/// NOT a rendering failure: once levels exist, the `ORDER BY` and the keyset bind them and cannot
/// fail, which is why every SQL dialect's [`Backend::Error`](crate::Backend::Error) is
/// [`Infallible`](core::convert::Infallible). And it is not a WIRE failure either — a repeated
/// subject was refused at the decode, one layer out, so nothing malformed reaches here.
///
/// # Nothing implements it by hand today, and the seat is still the design
///
/// Every emitted crossing arrives through the blanket at [`Infallible`](core::convert::Infallible),
/// which is a compile-time proof rather than a habit of returning `Ok`. What the seat buys is that
/// the first word which CAN refuse — a collation, a document family's sort — has a place to be
/// refused from that no caller has to grow a new shape for.
pub trait TryFromGraphqlOrderBy<O>: Sized {
  /// Why a wire order did not become a level sequence.
  type Error;

  /// Cross `order` into this database's level sequence, or report why a term could not follow.
  fn try_from_graphql_order_by(order: O) -> Result<Self, Self::Error>;
}

/// The total crossing is infallible, and says so in its type.
///
/// # This blanket and a per-order [`TryFromGraphqlOrderBy`] impl are compatible — but only one way
/// round
///
/// [`comparison::convert`](crate::comparison::convert)'s own note carries the measurement, and the
/// shape here is identical: a hand-written `TryFromGraphqlOrderBy` row coexists with this blanket
/// only while no `FromGraphqlOrderBy` row exists for the same pair, because rustc can see that none
/// exists and that no downstream may add one. Writing both is
///
/// ```text
/// error[E0119]: conflicting implementations of trait `TryFromGraphqlOrderBy<_>`
/// ```
///
/// The two families therefore take OPPOSITE halves, and the difference is which side owns the type.
/// A comparison is this crate's, so the comparisons implement the fallible half and reach the
/// infallible one reflexively. An emitted ORDER is the DECLARING crate's, so its expansion implements
/// the infallible half — where no overlap can arise, every type in the impl being local to the
/// declaration — and gains the fallible one here, provably at
/// [`Infallible`](core::convert::Infallible).
impl<O, S: FromGraphqlOrderBy<O>> TryFromGraphqlOrderBy<O> for S {
  type Error = core::convert::Infallible;

  #[inline]
  fn try_from_graphql_order_by(order: O) -> Result<Self, Self::Error> {
    Ok(S::from_graphql_order_by(order))
  }
}

#[cfg(test)]
mod tests;