Skip to main content

Module union

Module union 

Source
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§

UnionInput
The INPUT face’s declaration: that a backend renders one, and what a schema calls it.
UnionMember
One member: the variant that names it and the type it is.
UnionModel
One union’s declaration, validated.
UnionOutput
The OUTPUT face’s declaration: that a backend renders one, and what a schema calls it.
UnionSkin
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 @oneOf input object — media for Media, videoClip for VideoClip.
word
The word a variant’s methods are built on — media for Media, type for r#type.