ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! The DELEGATE SEAT's model — one restated signature, how it takes its receiver, and whether it is
//! also PUBLISHED.
//!
//! Two declarations spend this grammar and neither owns it. A vocabulary MIRROR forwards onto the
//! upstream value it materialises from a stored word; a wrapping FIELD FRAGMENT forwards onto the
//! value it holds. What they share is the whole of the seat: Rust has no `typeof`, so a forwarding
//! method's return type is written by the declaration that asks for it, and the emitted method's
//! head is that signature verbatim.
//!
//! The tiers differ in the BODY and in the sentences their refusals carry, which is what the front
//! end parameterises — see `ingraph_derive`'s own `delegate` module. Nothing about the model is one
//! tier's, so nothing about it lives in one tier's file.

use crate::model::GraphqlKind;

/// ONE `delegate(fn …)` entry: the signature the declaration restated, how it takes its receiver,
/// and whether it is also PUBLISHED.
///
/// The three are one entry rather than three lists because each answers a different question about
/// the same method, and two of them fork the emission: an exclusive receiver changes the BODY, and a
/// published entry changes the declaration's whole wire face.
#[derive(Debug, Clone)]
pub struct Delegate {
  /// The signature, exactly as the declaration wrote it — the emitted method's head, verbatim.
  pub signature: syn::Signature,
  /// Whether the receiver is EXCLUSIVE (`&mut self`) rather than shared (`&self`).
  ///
  /// A shared receiver FORWARDS and hands the answer back. An exclusive one has to reach a place it
  /// may mutate, which is a different body at every tier — a mirror materialises, mutates and
  /// converts home, at two conversions a call; a wrapper mutates the value it already holds, at
  /// none. This flag is what makes the fork, and the cost, visible.
  pub exclusive: bool,
  /// `#[graphql(<backend>)]` — the backends this method is published to, when it is published.
  ///
  /// EMPTY is the ordinary entry: a delegated method is Rust and reaches no schema. What ONE entry
  /// carrying a backend does is the declaration's own — a vocabulary mirror's output seat is
  /// PROMOTED from a scalar to an object face, and a field fragment already has an object face and
  /// gains a field on it.
  pub wire: Vec<DelegateSkin>,
  /// `on = self` — the entry's method lives on the DECLARED type rather than on the wrapped one, so
  /// no forwarding half is minted for it.
  ///
  /// [`None`] is the shorthand entry, which is every entry written before this word existed: the
  /// emission mints its forwarding method exactly as it did. [`Some`] carries the `self` token that
  /// named the target, kept for the span its refusals report at rather than for the word — `self` is
  /// the whole of the roster today, and a second target is a door rather than a plan.
  pub on_self: Option<syn::Ident>,
}

impl Delegate {
  /// The word a client writes this method as, at one backend: the declared `rename`, else the
  /// method's own name in lower camel case.
  ///
  /// The ONE authority on that word. A front end refusing a collision has to spell exactly the name
  /// the emitter publishes, and a second spelling on that side is how the two come to disagree —
  /// which is [`union::seat`](crate::union::seat)'s own argument, one declaration over.
  #[must_use]
  pub fn word(&self, kind: GraphqlKind) -> Option<String> {
    self.wire.iter().find(|skin| skin.kind == kind).map(|skin| {
      skin
        .rename
        .as_ref()
        .map(syn::LitStr::value)
        .unwrap_or_else(|| crate::emit::wire::wire_member(&self.signature.ident))
    })
  }
}

/// ONE backend's publication of one delegated method.
///
/// `rename` is the whole of v1's knob, and it moves a STRING and nothing else: what a rename touches
/// is the word a client writes — a match arm and a registry entry where the face is hand-emitted, a
/// `#[graphql(name = "…")]` where it rides `#[Object]` — with no derived helper anywhere for it to
/// have to agree with.
#[derive(Debug, Clone)]
pub struct DelegateSkin {
  /// Which backend publishes it.
  pub kind: GraphqlKind,
  /// `rename = "…"` — what a client calls this field, where the declaration moved it.
  pub rename: Option<syn::LitStr>,
}