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: [`FromFilter`] and [`TryFromFilter`].
//!
//! 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 identity crossing PROVABLY infallible, through an [`Infallible`](core::convert::Infallible)
//! error type, rather than merely always returning `Ok`.
//!
//! # Why not [`TryFrom`] itself
//!
//! Two reasons. Its `Into` blanket is in the way — `impl<T, U: Into<T>> TryFrom<U> for T` already
//! occupies the shape the comparison impls need. And this step has a NAME in the architecture: the
//! crossing, where a domain value becomes a storage value, 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 comparisons under either trait, because the self type is foreign to it; a downstream
//! kind brings both halves or neither.
//!
//! # The orphan rule reaches the crossing's BOUND too, and the answer is a local storage type
//!
//! The per-kind impls bound their crossing on `V: TryFrom<D>`, which is the one place a pair of
//! FOREIGN types cannot meet: `impl TryFrom<jiff::Timestamp> for time::OffsetDateTime` is `E0117`
//! here. Two ways around it were measured and both are `E0119` against the generic impl — a
//! concrete `TryFromFilter` row for the pair (*"upstream crates may add a new impl of trait
//! `TryFrom<jiff::Timestamp>` for type `time::OffsetDateTime` in future versions"*) and a blanket
//! keyed on a local trait, whose associated type unifies with the generic impl's `V`.
//!
//! So the temporal family joins with **no new impl of these traits at all**: it names a LOCAL
//! storage type, [`Temporal<T>`](crate::Temporal), whose `From` blanket std's own
//! reflexive `TryFrom` lifts. The crossing that reaches a temporal column is this module's,
//! unchanged, at [`Infallible`](core::convert::Infallible).
//!
//! That is the general shape rather than a special case: a foreign domain type reaches storage
//! through a local storage type, which is what [`BeU64`](crate::BeU64) already is for a `u64` on
//! SQLite.

/// The infallible crossing: build a comparison from a filter whose values need no conversion.
///
/// The shape [`From`] has, for the reason [`From`] has it — and the half a downstream comparison
/// implements when its crossing cannot fail. [`TryFromFilter`] follows from it through the blanket
/// below, so implementing this gives both.
pub trait FromFilter<F> {
  /// Cross `filter` into this comparison.
  fn from_filter(filter: F) -> Self;
}

/// The fallible crossing: build a comparison from a filter, converting each operand.
///
/// # What the error is, and is not
///
/// It is the conversion's own — whatever `V: TryFrom<D>` reports for the widths involved, or
/// whatever a declared converter returns. It is NOT a lowering failure: once a comparison holds
/// storage values, rendering it binds them and cannot fail, which is why every SQL dialect's
/// [`Backend::Error`](crate::Backend::Error) is [`Infallible`](core::convert::Infallible). The
/// crossing is where the fallibility of the whole path lives.
pub trait TryFromFilter<F>: Sized {
  /// Why a filter's operands did not become storage values.
  type Error;

  /// Cross `filter` into this comparison, or report why an operand could not follow.
  fn try_from_filter(filter: F) -> Result<Self, Self::Error>;
}

/// The identity crossing is infallible, and says so in its type.
///
/// # This blanket and a per-kind [`TryFromFilter`] impl are compatible — but only one way round
///
/// A per-kind `impl<D, S, Db> TryFromFilter<ScalarFilter<D>> for SqlScalarComparison<S, Db> where
/// S: TryFrom<D>` coexists with this blanket, because rustc can see that no
/// `SqlScalarComparison<S, Db>: FromFilter<ScalarFilter<D>>` impl exists and that no downstream may
/// add one (every type in it is local here). Writing that missing impl is what breaks it: with both
/// present the two overlap at `D == S` and rustc reports
///
/// ```text
/// error[E0119]: conflicting implementations of trait `TryFromFilter<ScalarFilter<_>>`
///               for type `SqlScalarComparison<_, _>`
/// ```
///
/// So the comparisons in this crate deliberately implement [`TryFromFilter`] and NOT [`FromFilter`],
/// and they lose nothing by it: `S: TryFrom<S>` holds reflexively through std's own
/// `From`/`Into` blankets with `Error = Infallible`, so the identity crossing keeps exactly the
/// property this blanket exists to give it. [`FromFilter`] remains the shorter half a DOWNSTREAM
/// comparison implements, where the overlap cannot arise.
impl<F, C: FromFilter<F>> TryFromFilter<F> for C {
  type Error = core::convert::Infallible;

  #[inline]
  fn try_from_filter(filter: F) -> Result<Self, Self::Error> {
    Ok(C::from_filter(filter))
  }
}

#[cfg(test)]
mod tests;