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 SLOT SEAM — what one field of a COMPOSED filter is, resolved by the compiler rather than by
//! the derive reading tokens.
//!
//! `#[derive(ingraph::Filter)]`'s composed identity takes a hand-written filter struct and emits its
//! wire face from the fields themselves: the struct IS the vocabulary. To do that the emitter has to
//! know, per field, WHICH of four shapes it is — and it cannot know from the tokens. `Option<Rate>`
//! and `Option<ScalarFilter<i32>>` are one shape to a proc macro and two shapes on the wire: the
//! first crosses through the element's own carrier and the second is a whole nested filter. So the
//! question is asked of the TYPE SYSTEM, at the emitted call, and the answer is a trait row.
//!
//! # The four shapes, and the three rows that carry them
//!
//! | a field written… | is | what it registers |
//! |---|---|---|
//! | `Option<T>` where `T: ToGraphqlInput` | ONE operand | `Option<T::Input>` — the element's own carrier |
//! | `Option<Box<[T]>>` where `T: ToGraphqlInput` | a LIST of operands | `Option<Box<[T::Input]>>` |
//! | `Option<Utf8Bytes>` | one TEXT operand | `Option<String>` — the row above, at the UTF-8 household |
//! | `Option<F>` where `F: GraphqlFilter` | a NESTED filter | `Option<F>`, whole |
//!
//! **The text shape is the operand row and not a fourth impl**, which is arithmetic rather than a
//! simplification: `smol_bytes::Utf8Bytes` already carries [`ToGraphqlInput`] with `Input = String`,
//! crossing IN through `From<String>` and OUT through `as_str().to_owned()` — a COPY rather than a
//! conversion, which is exactly what a hand-written render facet writes for it and exactly what the
//! reading in [`carrier`](super::super::carrier) publishes. A row of its own beside the operand row
//! would be `E0119` against it and would buy nothing: same registration, same bytes on the wire.
//!
//! # `K` is a MARKER and it is what keeps the rows apart
//!
//! Two of the three rows are over `Option<_>` and would overlap as one trait — coherence cannot rule
//! out a downstream type that is both `ToGraphqlInput` and [`GraphqlFilter`], and negative reasoning
//! is not available on stable. Parameterising by a KIND makes them `FilterSlot<OneOperand>` and
//! `FilterSlot<NestedFilter>`, which are different traits as far as coherence is concerned, and the
//! emitter never spells the marker: it writes `FilterSlot<_>` and inference picks the one row that
//! applies. A type answering TWO of them is an ambiguity at the declaration rather than a silent
//! choice, which is the honest failure for a field whose meaning is genuinely two things.
//!
//! # TWO traits, because emptiness is not a wire question
//!
//! [`FilterSlot`] is UNGATED and answers one thing: does this slot ask anything. That is what
//! [`GraphqlFilter`] wants, it is the same answer on every backend, and a build with no binding at
//! all still has lowerings that ask it.
//!
//! [`SlotFace`] is the WIRE half — what the slot registers, how it is read off a parsed object and
//! how it is written back — and it rides the binding gate, because every one of those three names an
//! async-graphql type. The supertrait is what makes a slot one thing said twice rather than two
//! things that could disagree.
//!
//! # The EMPTINESS law, which is `ListFilter`'s and is restated here rather than re-decided
//!
//! An absent operand asks nothing, so `None` is empty at the first three shapes. A NESTED filter
//! folds in: `Some(f)` is empty exactly while `f` is, because asking no question about a component
//! excludes no row. That is [`Nullable`](crate::Nullable)'s fold-in and this crate's rule for a
//! nested filter — see [`ListFilter`](crate::ListFilter)'s own note, where the one EXCEPTION is
//! written down: a QUANTIFIED slot (`any`) is not empty when it holds an empty filter, because
//! `∃x ∈ S. true` is `S ≠ ∅`, which is a predicate. A composed filter has no quantifier — its slots
//! are operators over one subject rather than over a collection — so the exception has nothing to
//! attach to here, and the fold-in is the whole law.

use super::GraphqlFilter;
use crate::ToGraphqlInput;

#[cfg(test)]
mod tests;

/// The kind marker for ONE OPERAND — a slot holding a single value of the subject's own element
/// type, crossing on that element's carrier.
///
/// Uninhabited, for the reason every marker in this crate is: it is a name a row is filed under and
/// never a value anybody holds.
///
/// # The three names are LONGER than the words they stand for, and that is measured
///
/// `Operand`, `Operands` and `Nested` are what these are about, and the first of them is a name this
/// crate already uses: four SQL and Mongo crossing errors carry an `Operand` VARIANT, and with a
/// dialect feature on, rustc prints the marker as `ingraph::Operand` where it prints the bare word
/// without one. That difference lands inside `tests/composed_slot_shape`'s golden, which would then
/// be a pinned diagnostic that depends on the feature set it was blessed under — a lane red on the
/// obvious minimal command for no reason at all.
///
/// So the trio is spelled with the word that disambiguates it, and the pin is feature-independent.
pub enum OneOperand {}

/// The kind marker for a LIST OF OPERANDS — the `in` / `notIn` shape, crossing as a list of the
/// element's carrier. See [`OneOperand`] for why the name is not `Operands`.
pub enum ManyOperands {}

/// The kind marker for a NESTED FILTER — a slot holding a whole filter over a component of the
/// subject, crossing as that filter's own input object. See [`OneOperand`] for why the name is not
/// `Nested`.
pub enum NestedFilter {}

/// Which SHAPE one slot of a composed filter is, and whether it asks anything.
///
/// The half that is not about the wire, so a build with no binding still has it — see the module
/// note for why the trait is split and for the emptiness law this method states.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a shape a composed filter's slot may take",
  label = "no slot shape",
  note = "a composed filter's fields ARE its vocabulary, so every one of them has to be a slot the \
          wire face knows how to register, read and render. Four shapes, and each is `Option` \
          because a slot that is not set is an operator a client did not write: `Option<T>` where \
          `T: ingraph::ToGraphqlInput` is ONE operand; `Option<Box<[T]>>` is a LIST of them; \
          `Option<smol_bytes::Utf8Bytes>` is the text operand, which is the first shape at the \
          UTF-8 household; and `Option<F>` where `F: ingraph::GraphqlFilter` is a whole NESTED \
          filter over a component. A type inside the `Option` that has none of those rows reaches \
          one by declaring a crossing for ITSELF — `impl ingraph::ToGraphqlInput for <that type>`, \
          or the element mode `#[ingraph(operator(<family>))]`, which mints one."
)]
pub trait FilterSlot<K>: Sized {
  /// True while this slot asks NOTHING — so a lowering would emit no predicate for it.
  fn is_empty(&self) -> bool;
}

/// ONE operand. `None` asks nothing.
impl<T: ToGraphqlInput> FilterSlot<OneOperand> for Option<T> {
  #[inline]
  fn is_empty(&self) -> bool {
    self.is_none()
  }
}

/// A LIST of operands. `None` asks nothing — and an EMPTY list does not: `in: []` is a membership
/// test against no value, which is a predicate that excludes every row rather than the absence of
/// one.
impl<T: ToGraphqlInput> FilterSlot<ManyOperands> for Option<Box<[T]>> {
  #[inline]
  fn is_empty(&self) -> bool {
    self.is_none()
  }
}

/// A NESTED filter, which FOLDS IN: a present component filter that asks nothing leaves this slot
/// asking nothing. The module note is where the law is, and where `ListFilter`'s one exception to it
/// is named.
impl<F: GraphqlFilter> FilterSlot<NestedFilter> for Option<F> {
  #[inline]
  fn is_empty(&self) -> bool {
    self.as_ref().is_none_or(GraphqlFilter::is_empty)
  }
}

/// The WIRE half of a slot: what it registers, how it is read off a parsed object, and how it is
/// written back.
///
/// Behind the binding gate, all three methods naming an async-graphql type. The supertrait is what
/// keeps a slot ONE decision — a shape that crosses one way and empties another would be two rulings
/// filed under one name.
#[cfg(feature = "async-graphql")]
// The SUPERTRAIT already carries the whole sentence, and it fails first — so this note says where
// to read rather than restating it. A bound with no note at all is what a reader would otherwise
// get twice from one field.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a shape a composed filter's slot may cross on",
  label = "no slot shape",
  note = "the shapes are `ingraph::FilterSlot`'s, and its own note lists them — this is the WIRE \
          half of the same seam, so a field answering one answers both."
)]
pub trait SlotFace<K>: FilterSlot<K> {
  /// The type this slot CROSSES AS — what a client's document is checked against and what the SDL
  /// prints.
  ///
  /// Not always the slot's own type: an operand slot crosses on its element's carrier, so a
  /// `Option<Rate>` field publishes `RateOperand` and a `Option<Utf8Bytes>` field publishes
  /// `String`.
  type Wire: async_graphql::InputType;

  /// This slot's entry in the registry, as the type name a field's `MetaInputValue` carries.
  ///
  /// Provided, and every row takes it: the wire type is the only thing that differs, and it is
  /// already named above. A row that overrode this would be a slot whose registration and whose
  /// parse could disagree.
  #[inline]
  fn slot_type(registry: &mut async_graphql::registry::Registry) -> ::std::string::String {
    <Self::Wire as async_graphql::InputType>::create_type_info(registry)
  }

  /// One slot, read off the parsed object under `name`.
  ///
  /// `F` is the OWNER — the composed filter being parsed — because an `InputValueError` carries the
  /// type it is about, so a slot's refusal has to be re-pointed at the face a client was writing.
  ///
  /// # Errors
  ///
  /// Whatever the crossing refuses: a wrong wire form is async-graphql's own refusal, PROPAGATED,
  /// and an operand the element's crossing declines becomes that crossing's own sentence.
  fn read<F>(
    object: &async_graphql::indexmap::IndexMap<async_graphql::Name, async_graphql::Value>,
    name: &str,
  ) -> Result<Self, async_graphql::InputValueError<F>>
  where
    F: async_graphql::InputType;

  /// One slot, written back onto the wire.
  fn write(&self) -> async_graphql::Value;
}

#[cfg(feature = "async-graphql")]
impl<T> SlotFace<OneOperand> for Option<T>
where
  T: ToGraphqlInput,
  T::Input: async_graphql::InputType,
{
  type Wire = Option<T::Input>;

  #[inline]
  fn read<F>(
    object: &async_graphql::indexmap::IndexMap<async_graphql::Name, async_graphql::Value>,
    name: &str,
  ) -> Result<Self, async_graphql::InputValueError<F>>
  where
    F: async_graphql::InputType,
  {
    super::via::cross::<T, F>(object, name)
  }

  #[inline]
  fn write(&self) -> async_graphql::Value {
    super::via::carry(self)
  }
}

#[cfg(feature = "async-graphql")]
impl<T> SlotFace<ManyOperands> for Option<Box<[T]>>
where
  T: ToGraphqlInput,
  T::Input: async_graphql::InputType,
{
  type Wire = Option<Box<[T::Input]>>;

  #[inline]
  fn read<F>(
    object: &async_graphql::indexmap::IndexMap<async_graphql::Name, async_graphql::Value>,
    name: &str,
  ) -> Result<Self, async_graphql::InputValueError<F>>
  where
    F: async_graphql::InputType,
  {
    super::via::cross_list::<T, F>(object, name)
  }

  #[inline]
  fn write(&self) -> async_graphql::Value {
    super::via::carry_list(self)
  }
}

/// The NESTED row's read is the component face's OWN parse, handed the value under this name — so a
/// composed filter reading a composed filter spends exactly one parser per face however deep the
/// nesting runs.
#[cfg(feature = "async-graphql")]
impl<F> SlotFace<NestedFilter> for Option<F>
where
  F: GraphqlFilter + async_graphql::InputType,
{
  type Wire = Self;

  #[inline]
  fn read<O>(
    object: &async_graphql::indexmap::IndexMap<async_graphql::Name, async_graphql::Value>,
    name: &str,
  ) -> Result<Self, async_graphql::InputValueError<O>>
  where
    O: async_graphql::InputType,
  {
    super::via::nested(object, name)
  }

  #[inline]
  fn write(&self) -> async_graphql::Value {
    async_graphql::InputType::to_value(self)
  }
}