ingraph_codegen/delegate.rs
1//! The DELEGATE SEAT's model — one restated signature, how it takes its receiver, and whether it is
2//! also PUBLISHED.
3//!
4//! Two declarations spend this grammar and neither owns it. A vocabulary MIRROR forwards onto the
5//! upstream value it materialises from a stored word; a wrapping FIELD FRAGMENT forwards onto the
6//! value it holds. What they share is the whole of the seat: Rust has no `typeof`, so a forwarding
7//! method's return type is written by the declaration that asks for it, and the emitted method's
8//! head is that signature verbatim.
9//!
10//! The tiers differ in the BODY and in the sentences their refusals carry, which is what the front
11//! end parameterises — see `ingraph_derive`'s own `delegate` module. Nothing about the model is one
12//! tier's, so nothing about it lives in one tier's file.
13
14use crate::model::GraphqlKind;
15
16/// ONE `delegate(fn …)` entry: the signature the declaration restated, how it takes its receiver,
17/// and whether it is also PUBLISHED.
18///
19/// The three are one entry rather than three lists because each answers a different question about
20/// the same method, and two of them fork the emission: an exclusive receiver changes the BODY, and a
21/// published entry changes the declaration's whole wire face.
22#[derive(Debug, Clone)]
23pub struct Delegate {
24 /// The signature, exactly as the declaration wrote it — the emitted method's head, verbatim.
25 pub signature: syn::Signature,
26 /// Whether the receiver is EXCLUSIVE (`&mut self`) rather than shared (`&self`).
27 ///
28 /// A shared receiver FORWARDS and hands the answer back. An exclusive one has to reach a place it
29 /// may mutate, which is a different body at every tier — a mirror materialises, mutates and
30 /// converts home, at two conversions a call; a wrapper mutates the value it already holds, at
31 /// none. This flag is what makes the fork, and the cost, visible.
32 pub exclusive: bool,
33 /// `#[graphql(<backend>)]` — the backends this method is published to, when it is published.
34 ///
35 /// EMPTY is the ordinary entry: a delegated method is Rust and reaches no schema. What ONE entry
36 /// carrying a backend does is the declaration's own — a vocabulary mirror's output seat is
37 /// PROMOTED from a scalar to an object face, and a field fragment already has an object face and
38 /// gains a field on it.
39 pub wire: Vec<DelegateSkin>,
40 /// `on = self` — the entry's method lives on the DECLARED type rather than on the wrapped one, so
41 /// no forwarding half is minted for it.
42 ///
43 /// [`None`] is the shorthand entry, which is every entry written before this word existed: the
44 /// emission mints its forwarding method exactly as it did. [`Some`] carries the `self` token that
45 /// named the target, kept for the span its refusals report at rather than for the word — `self` is
46 /// the whole of the roster today, and a second target is a door rather than a plan.
47 pub on_self: Option<syn::Ident>,
48}
49
50impl Delegate {
51 /// The word a client writes this method as, at one backend: the declared `rename`, else the
52 /// method's own name in lower camel case.
53 ///
54 /// The ONE authority on that word. A front end refusing a collision has to spell exactly the name
55 /// the emitter publishes, and a second spelling on that side is how the two come to disagree —
56 /// which is [`union::seat`](crate::union::seat)'s own argument, one declaration over.
57 #[must_use]
58 pub fn word(&self, kind: GraphqlKind) -> Option<String> {
59 self.wire.iter().find(|skin| skin.kind == kind).map(|skin| {
60 skin
61 .rename
62 .as_ref()
63 .map(syn::LitStr::value)
64 .unwrap_or_else(|| crate::emit::wire::wire_member(&self.signature.ident))
65 })
66 }
67}
68
69/// ONE backend's publication of one delegated method.
70///
71/// `rename` is the whole of v1's knob, and it moves a STRING and nothing else: what a rename touches
72/// is the word a client writes — a match arm and a registry entry where the face is hand-emitted, a
73/// `#[graphql(name = "…")]` where it rides `#[Object]` — with no derived helper anywhere for it to
74/// have to agree with.
75#[derive(Debug, Clone)]
76pub struct DelegateSkin {
77 /// Which backend publishes it.
78 pub kind: GraphqlKind,
79 /// `rename = "…"` — what a client calls this field, where the declaration moved it.
80 pub rename: Option<syn::LitStr>,
81}