Value Completion

## A field is executed in two steps Executing one field of a GraphQL document is two distinct operations, and an interviewer is usually listening for both names. First the executor **resolves** the field: it calls whatever function the type system supplies for that field on that object type, handing it the parent value and the already coerced arguments, and gets back a value in the server's own language - a row object, a string, a collection, a pending future, whatever the host language has. Then the executor **completes** that value: it forces the raw value through the field's *declared* type until what is left is a legal piece of the response. Resolution is where your code runs. Completion is where the schema runs. A resolver never has to ask whether its field was declared nullable, whether it was declared as a list, or whether the client selected three sub-fields or thirty. Completion applies all of that afterwards, uniformly, for every field in the document. ## The ladder, in order Completion is defined recursively over the *type wrappers*, and the order is fixed: 1. **Non-Null.** If the declared type is `T!`, complete the value against the inner `T` first. If that comes back null, raise a field error instead of writing null into the response. 2. **Null.** If the value is null - or the host language's equivalent, such as an absent property - the completed value is null and nothing below this step runs. In particular the sub-selection of a null object field is never executed, so those child resolvers are never called. 3. **List.** If the declared type is `[T]`, the value must be a collection. Every item is completed against `T`, each one under a path that ends in that item's index. 4. **Leaf** - a scalar or an enum. The value is handed to the result-coercion routine the type system provides for that type and the coerced value goes into the response. A value that routine cannot turn into a legal value of the type raises a field error at that position. 5. **Composite** - an object, interface or union type. If the type is abstract the concrete object type is determined first; then this field's sub-selection is executed with the resolved value as the new parent, producing a map of response keys. Because Non-Null is unwrapped *before* the null check, `Artwork!` and `Artwork` differ for exactly one input - null - and behave identically for every other value. ## On a real graph ```graphql type Query { gallery(id: ID!): Gallery } type Gallery { name: String! artworks: [Artwork!]! } type Artwork { accessionNumber: String! title: String medium: MediumCategory! } ``` A resolver for `gallery` may return a domain object, a map, or null. If it returns null, completion stops at step 2: `"gallery": null` is written and the resolvers for `name` and `artworks` never run, even though the document selected them. If it returns a gallery, completion reaches step 5, executes the sub-selection against it, and inside that the `artworks` field goes through step 3, walking the collection item by item; each `title` goes through step 4 and each `medium` through step 4 as an enum. A `title` that comes back null is simply null, because `title` is nullable. An `accessionNumber` that comes back null is a field error, because step 1 refuses it. ## Why the split matters in practice The separation is what keeps resolvers small and the response predictable. A resolver returns a domain value; it does not build a response fragment, does not decide the response keys, and does not decide what a missing value means. That is why two different documents over the same object can get two differently shaped responses from one unchanged resolver, and why the shape of the response is a function of the document and the schema alone. It is also where field errors are born and where their location is known. Completion is walking a path as it descends - a chain of response keys and list indices - so when it raises, it can say precisely which position failed. A resolver throwing an exception cannot describe its own address in the response; the executor can. ## Three things candidates get wrong **"The resolver returns the JSON."** It does not. It returns whatever is natural in the host language, and completion turns that into response values. A scalar field's serialized form is produced by the type, not by the resolver. **"A null object field still runs its children."** It does not. Step 2 short-circuits, and every resolver below that point is skipped. This is a real performance property, not a footnote: nulling a subtree at its root removes all the work under it. **"Whatever extra keys my object carries will appear in the response."** They will not. For a composite type, completion builds the response map from the fields the document selected; unselected properties of the resolved value are simply never asked for.