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 SPLICE SEAM — what a COMPOSED filter's `#[ingraph(flatten)]` field contributes to its host,
//! and the one door the host's registration table is folded through.
//!
//! A composed filter's ordinary field is one SLOT: one name, one wire type, one key in the parsed
//! object. A flattened field is not a slot at all — it is a whole component face whose OWN fields
//! become the host's, so `SoundEventDetectionFilter` publishes the eight operators of the code
//! filter it holds beside the five it declares itself, and a client writes `eq` at the top level
//! rather than `code: { eq: … }`.
//!
//! # The four faces splice TOGETHER, which is the whole of the word
//!
//! | face | what the splice does |
//! |---|---|
//! | registration | the component's `bare_fields`, spliced into the host's table at the field's position |
//! | parse | the HOST's whole object handed to the component's own parser, which reads its keys and ignores the rest |
//! | render | the component's `bare_values`, spliced into the host's map in that same position |
//! | [`NullableFace`] | both of the above, since that row IS the host's field list and rendered slots |
//!
//! So there is still one table with one author. What the splice adds is that part of the table is
//! the COMPONENT's, read from the component at each of the three walks rather than restated here —
//! which is why a component that renamed one of its own operators cannot leave this face reading a
//! word the roster moved.
//!
//! # A flattened field is written BARE, and that is arithmetic rather than a relaxation
//!
//! Every SLOT is an `Option` because the absence is the meaning: a slot that is not set is an
//! operator the client did not write. A spliced component has no such absence to carry — its fields
//! are the host's fields, and each of THOSE is an operator that carries its own. An `Option` around
//! the component would be a presence bit for a thing with no absent state, which is exactly the
//! reading [`OptionalMarker`](crate::OptionalMarker) exists to refuse one level up.
//!
//! The emptiness answer follows from the same fact: a flattened field folds in through
//! [`GraphqlFilter`](crate::GraphqlFilter) directly, where a nested SLOT reaches the same law
//! through [`FilterSlot`](crate::FilterSlot)'s `Option` row.
//!
//! # What a component has to BE
//!
//! [`NullableFace`] and nothing more, which is the honest floor: that row is exactly *this face
//! publishes a bare field list and can render it back*, and it is what both a nullable twin and a
//! splice ask of a face. Every filter kind this crate publishes carries it, and so does every
//! composed declaration — so a composed filter can splice another composed filter, and the framework
//! kinds are spliceable without a word of their own.

use async_graphql::{
  InputType, InputValueError, Name, Value,
  indexmap::IndexMap,
  registry::{MetaInputValue, Registry},
};

use super::NullableFace;

/// A component face a composed filter may SPLICE into its own, through
/// `#[ingraph(flatten)]` on the field that holds it.
///
/// Blanket over [`NullableFace`], so the row is never written by hand — what a declarer supplies is
/// the face, and this is the reading of it the splice spends.
#[diagnostic::on_unimplemented(
  message = "`{Self}` cannot be flattened into a composed filter",
  label = "no field table to splice",
  note = "`#[ingraph(flatten)]` puts a COMPONENT FACE's own fields into this filter, so the field \
          it sits on holds a whole filter face and is written BARE — `code: SoundEventCodeFilter`, \
          not `Option<…>`, because the component's fields carry their own absence and the component \
          has none of its own. What a face has to publish is `ingraph::NullableFace`: every filter \
          kind in this crate carries it, and so does every `#[ingraph(composed)]` declaration. An \
          operand, a list of operands or a text slot is a SLOT rather than a component — drop the \
          `flatten` and let it be one."
)]
pub trait FlattenFace: Sized {
  /// The fields this component contributes to its host's registration.
  fn flat_fields(registry: &mut Registry) -> IndexMap<String, MetaInputValue>;

  /// The component, read from the HOST's whole parsed object.
  ///
  /// `F` is the owner — the composed filter being parsed — because an `InputValueError` carries the
  /// type it is about, so the component's refusal has to be re-pointed at the face a client was
  /// writing. [`SlotFace::read`](crate::SlotFace::read)'s own shape, one field kind over.
  ///
  /// # Errors
  ///
  /// Whatever the component refuses the object with, PROPAGATED.
  fn flat_read<F>(object: &IndexMap<Name, Value>) -> Result<Self, InputValueError<F>>
  where
    F: InputType;

  /// The rendered slots this component contributes to its host's render, in the order it publishes
  /// them.
  fn flat_values(&self) -> IndexMap<Name, Value>;
}

/// `do_not_recommend`, and it is the SENTENCE above that it protects. Unmarked, a field that is not
/// a face reports the nested `NullableFace` obligation first and the note here second, so a reader
/// meets a trait they never wrote before the paragraph that says what to do — and the impl list
/// rustc prints beside it is over every filter kind compiled in, which makes a pinned diagnostic
/// depend on the feature set it was blessed under. Marked, the refusal is the root bound and its own
/// note. The pair in `comparison::sql::collection` carries the attribute for the same reason.
#[diagnostic::do_not_recommend]
impl<C: NullableFace> FlattenFace for C {
  #[inline]
  fn flat_fields(registry: &mut Registry) -> IndexMap<String, MetaInputValue> {
    Self::bare_fields(registry)
  }

  /// The object is CLONED, and the clone is the honest cost of splicing: the component's parser
  /// takes an owned value, and the host's other fields are read off the same object either side of
  /// this call. Handing the last splice the owned map would save one clone in the one-splice case
  /// and make the emission depend on which field came last.
  #[inline]
  fn flat_read<F>(object: &IndexMap<Name, Value>) -> Result<Self, InputValueError<F>>
  where
    F: InputType,
  {
    <Self as InputType>::parse(Some(Value::Object(object.clone())))
      .map_err(InputValueError::propagate)
  }

  #[inline]
  fn flat_values(&self) -> IndexMap<Name, Value> {
    Self::bare_values(self)
  }
}

/// A composed face's registration table, folded from its entries IN ORDER — the plain slots it
/// declared and the fields its splices contributed, each at the position its field was written.
///
/// # Two fields on one name PANIC here, and the panic is the refusal
///
/// The derive already refuses two SLOTS folding onto one wire name, at the tokens, where a refusal
/// can point at the second field. A splice's names cannot be seen there at all — a component's field
/// list is a function of a registry, not a fact about the declaration — so the collision between a
/// spliced name and one the host declared is answerable only here.
///
/// It fires once, at `Schema::build`, before any document is served, which is where async-graphql
/// puts its own name conflicts too. The alternative is what an unchecked `insert` does: the second
/// entry silently replaces the first, and the face publishes one field where its author wrote two.
///
/// # Every composed face is built through it, not only the ones that splice
///
/// One door means one sentence. For a face with no splice the derive's own refusal has already made
/// this one unreachable, and what it costs is a lookup per field at schema build.
///
/// # Panics
///
/// When two entries carry one name, naming the face and the name.
#[must_use]
pub fn table(
  face: &str,
  entries: std::vec::Vec<(String, MetaInputValue)>,
) -> IndexMap<String, MetaInputValue> {
  let mut fields = IndexMap::with_capacity(entries.len());
  for (name, field) in entries {
    assert!(
      !fields.contains_key(&name),
      "`{face}` publishes the field `{name}` twice — a `#[ingraph(flatten)]` component's own \
       fields become this filter's, so one of them has landed on a name the filter already \
       declares. Rename the declared slot with `#[ingraph(rename = \"…\")]`, or hold the component \
       in a nested slot instead of splicing it."
    );
    fields.insert(name, field);
  }
  fields
}