Expand description
The UNION face: what an enum whose variants CARRY their members expands into.
A union is not a node and not a value a column holds. It is a CHOICE — one of several member types, named by the variant that carries it — and the whole of what this half writes is the way Rust asks that choice: which member is held, and how to get at it.
§Which unions this derive is for
The DECLARED ones. A schema’s union SearchResult = Media | Video and its input-position twin
are both a payload-carrying enum somebody WROTE, and this derive equips it — the same direction
crate::enumeration takes with a vocabulary. The other payload enums in this framework are
the FAN-IN ones a node with several upstreams gets, and those are the node macros’ own emission:
nobody writes them, so there is nothing for a derive to be applied to.
§The shape, and the law it comes from
Every variant carries exactly ONE unnamed payload, and that payload’s type is the member. The
shape is not this crate’s taste — it is what a declared union renders as at both positions a
schema has for one, and the input position is the tighter of the two: an @oneOf input object
is an enum of single-value TUPLE variants and nothing else.
GraphQL’s own type validation is where the rest of the refusals come from, quoted rather than paraphrased: A Union type must include one or more unique member types. That one sentence is the empty union’s refusal and the duplicated member’s both.
§The face is a SEAM, because a union is not the only member set
[Equipped] is the emission, and UnionModel::emit is one caller of it. An INTERFACE is a
member set too — one with a contract over it — so it declares the same Rust shape and wants the
same question asked: which member is held, and how to get at it. Written once, the second caller
inherits the emission rather than a copy of it, and the two cannot come to spell one method
differently.
§The face is HAND-EMITTED, and it is the whole of what this half writes
is_<member>, unwrap_<member> and try_unwrap_<member>, the latter two in all three
receivers — owned, _ref, _mut. The suffix spelling is derive_more’s #[unwrap(ref, ref_mut)] semantics restated as OURS, and derive_more itself is not a dependency of THIS
emission: its TryUnwrapError would put a foreign path in every consumer’s expanded code and a
foreign type in the signatures a caller writes. (The framework crate does depend on it, for its
own Emission<Out> — an enum of this exact shape carrying those exact attributes. That is a
foreign path in ingraph’s own source, which is nobody else’s expansion.)
The two agree on the SUFFIXES and part company on the WORD, and the divergence is deliberate.
derive_more cases a variant through convert_case, whose default boundaries include
LOWER_DIGIT and UPPER_DIGIT, so a variant Vp9 reaches it as vp_9. This framework cases
through heck, where the same variant is vp9 — which is what the vocabulary derive already
emits and what its collision refusal already names. A variant spelled one way in Rust must
derive ONE word in this framework, whether it is a vocabulary’s member or a union’s, so the word
is the house’s and only the suffixes are borrowed.
Only is_<member> is const. The unwrap family cannot be: a receiver that takes self DROPS
the payload it did not match, and a const fn may not drop a value whose type could implement
Drop — so the owned pair is out on its own terms, and a family whose three receivers
differed in constness would read as an accident rather than a rule.
§The refusal carries the pair, and its construction is SEALED
<Union>UnwrapError holds the variant ASKED for and the variant HELD, as &'static str the
expansion mints. Not the empty payload a vocabulary’s parse refusal takes: there the caller
already holds the word that failed, and here the two names are the whole content of what went
wrong. The fields are private, so nothing outside the declaring module builds one; the pair is
read back through the emitted asked() and held(), and the
Display sentence is written from them once. The framework’s name shelf
offers nothing that fits: its five name types spell what ONE NAMESPACE calls a vocabulary’s
member — a stored word or a wire word — and a Rust variant’s own spelling is neither.
One refusal serves all three receivers, and that is what settles the question of handing the
held value back: a borrowing receiver has nothing owned to return, so an error carrying the
union would have to be a different type per receiver. The owned try_unwrap_<member> therefore
DROPS what it did not match, which is the trade written into the emitted # Errors note.
§The REFUSAL is the ONE name this expansion puts in the declaring scope
Everything else sits inside an anonymous const, where it collides with nothing anybody wrote.
The refusal cannot: it is named in signatures a caller writes. unwrap_error(rename = "…") is
the escape, read through the same shared block reader Record’s key(…) and the vocabulary’s
own error(…) go through — one grammar, so a third derive invents no wording for a rule the
first two already have. The word is unwrap_error and not error because error names the
CONVERSION CELLS, one per leg inside a database’s block: what a fallible crossing refuses with is
not what a wrong-variant unwrap answers with.
§The WIRE ROUND arrived, and it is what bought crate = "…"
The method face above is core and nothing else, and while it was the whole emission there was
nothing for a crate option to move. [wire] changed that: a declared union’s backend
implementations are HAND-EMITTED off UnionModel (their derive does not ride a model slot,
unlike the order-by’s — the ruling of 2026-08-05), every name in them is reached through
#krate::__private, and the gate they ride is reached the same way. So UnionModel::krate is
the path this expansion is rooted at, exactly as crate::enumeration’s is.
There is still no wire_derive, and now for a stronger reason than not yet: a DERIVE may only
append, so nothing here can put #[derive(async_graphql::Union)] on an enum somebody else wrote
— the same wall crate::index’s own union face states. Both faces are written out.
§The two faces are IMPLS ON THE DECLARED ENUM, and that decides the naming law
output is the schema’s union X = A | B; input is its @oneOf input object. Both are
written onto the type the declaration already named, so a union that declares both puts TWO
schema types on ONE Rust type — and a schema has one namespace for type names. Hence the law
UnionSkin::input_sdl carries: a single face takes the union’s own name, and where both are
rendered the output keeps it and the input derives <Union>Input.
Both faces are movable, and the rename-parity ruling is what made the pair symmetric:
input(rename = "…") names the twin, output(rename = "…") names the union itself and carries
the derived twin with it. The law above is untouched by either — it decides which face keeps the
DEFAULT, which is a different question from whether an author may name one.
§A union is not a column
No storage rows, at any backend. No scenario stores one: both declared positions are wire
shapes, and fan-in addresses its upstreams by (tag, id) rather than by a stored payload. Were
one ever to persist, the shape is already ruled — a discriminant column beside one side table
per member — and it is a design round that starts there rather than at a tagged blob.
Structs§
- Union
Input - The INPUT face’s declaration: that a backend renders one, and what a schema calls it.
- Union
Member - One member: the variant that names it and the type it is.
- Union
Model - One union’s declaration, validated.
- Union
Output - The OUTPUT face’s declaration: that a backend renders one, and what a schema calls it.
- Union
Skin - ONE GraphQL backend’s rendering of a declared union — which of the two schema positions it is dressed for.
Enums§
- Face
- One method the face declares for one member.
Functions§
- default_
input_ sdl_ name - What a SCHEMA calls a union’s input object where the output face already holds the union’s own
name:
<Union>Input. - default_
unwrap_ error_ name - What the refusal a wrong-variant unwrap answers with is called when nothing renamed it:
<Enum>UnwrapError. - input_
sdl_ name - The same convention over a base that is already a SCHEMA word — what a renamed face composes its input twin’s name from.
- seat
- The SEAT one member takes in the
@oneOfinput object —mediaforMedia,videoClipforVideoClip. - word
- The word a variant’s methods are built on —
mediaforMedia,typeforr#type.