[RFC] List coercion algorithm

[benjie]

Fixes #1002.

Previously, list coercion does not detail what to do with variables at all, and that could lead to either a null pointer exception, or to double-coercion of the variable value if you're only following the spec.

Consider the following valid schema:

type Query {
  sum(numbers:[Int!]!): Int
}

and the query that is valid against this schema:

query Q ($number: Int = 3) {
  sum(numbers: [1, $number, 3])
}

NOTE: We're using the variable in a list item position!

If you issue this to the GraphQL server with variables {"number": null} then CoerceVariableValues will give you {"number": null} and when you fast-forward to CoerceArgumentValues you'll go in to 5.j.iii.1:

https://spec.graphql.org/draft/#sel-NANTHHCJFTDFBBCAACGB0yS

• Let {coercedValues} be an empty unordered Map. coercedValues = {}
• Let {argumentValues} be the argument values provided in {field}. argumentValues = { numbers: [1, $number, 3] }
• Let {fieldName} be the name of {field}. fieldName = 'sum'
• Let {argumentDefinitions} be the arguments defined by {objectType} for the
  field named {fieldName}. argumentDefinitions = { numbers: ... }
• For each {argumentDefinition} in {argumentDefinitions}:
  • Let {argumentName} be the name of {argumentDefinition}. argumentName = 'numbers'
  • Let {argumentType} be the expected type of {argumentDefinition}. argumentType = [Int!]!
  • Let {defaultValue} be the default value for {argumentDefinition}. defaultValue = undefined
  • Let {hasValue} be {true} if {argumentValues} provides a value for the name
    {argumentName}. hasValue = true
  • Let {argumentValue} be the value provided in {argumentValues} for the name
    {argumentName}. argumentValue = [1, $number, 3]
  • If {argumentValue} is a {Variable}: NOPE
    • Let {variableName} be the name of {argumentValue}.
    • Let {hasValue} be {true} if {variableValues} provides a value for the name
      {variableName}.
    • Let {value} be the value provided in {variableValues} for the name
      {variableName}.
  • Otherwise, let {value} be {argumentValue}. value = [1, $number, 3]
  • If {hasValue} is not {true} and {defaultValue} exists (including {null}): NOT TRIGGERED
    • Add an entry to {coercedValues} named {argumentName} with the value
      {defaultValue}.
  • Otherwise if {argumentType} is a Non-Nullable type, and either {hasValue} is
    not {true} or {value} is {null}, raise a field error. NOT TRIGGERED
  • Otherwise if {hasValue} is true: Yes, it is
    • If {value} is {null}: It is not, it is a list
      • Add an entry to {coercedValues} named {argumentName} with the value
        {null}.
    • Otherwise, if {argumentValue} is a {Variable}: It is not, it is a list
      • Add an entry to {coercedValues} named {argumentName} with the value
        {value}.
    • Otherwise: YES
      • If {value} cannot be coerced according to the input coercion rules of
        {argumentType}, raise a field error. TIME TO VISIT LIST COERCION
      • Let {coercedValue} be the result of coercing {value} according to the
        input coercion rules of {argumentType}.
      • Add an entry to {coercedValues} named {argumentName} with the value
        {coercedValue}.
• Return {coercedValues}.

Time to visit list coercion

We need to coerce the value [1, $number, 3] to the non-nullable type [Int!]!.

Step 1: handle the non-null. It's not null. Great!

Now we need to coerce the value [1, $number, 3] to the list type [Int!].

Here's what the spec says about input coercion for lists:

When expected as an input, list values are accepted only when each item in the list can be accepted by the list’s item type.

If the value passed as an input to a list type is not a list and not the null value, then the result of input coercion is a list of size one, where the single item value is the result of input coercion for the list’s item type on the provided value (note this may apply recursively for nested lists).

This allows inputs which accept one or many arguments (sometimes referred to as “var args”) to declare their input type as a list while for the common case of a single value, a client can just pass that value directly rather than constructing the list.

We have a list, so we only care about the bold line.

This line seems to miss a bunch of situations.

For example: if we were coercing to [Int] the value [1, $number, 3] with variables {} then is $number (which is undefined, since it wasn't provided in the variables) "accepted by the list's item type"? Really we must coerce this to null, but that doesn't seem to be detailed. In fact this entire section doesn't mention variables at all.

We're actually coercing to [Int!], so the question is: is $number accepted by the list's item type? $number itself is a variable, so...

---

I've attempted to solve this problem by being much more explicit about the input coercion for lists, inspired by the input coercion for input objects. I've also added a non-normative note highlighting the risk of a null variable being fed through into a non-nullable position, why that can occur (validation) and what we do about it (field error). I've also expanded the table with both variables and many more examples to cover many more edge cases.

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	76bec1c
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/6551ebc9eb3fb100084a0329
😎 Deploy Preview	https://deploy-preview-1058--graphql-spec-draft.netlify.app/draft
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[mjmahone]

This feels like it brings list coercion to the same (currently buggy due to nullable-with-default-values) state as all the other variable coercion so this feels right to me

[martinbonnin]

Is there a specific reason this doesn't use the "pre-coerced" variable values? (from CoerceVariableValues)

[benjie]

The reason was that this is essentially copied from the input coercion for input objects (but via an algorithm to make it clearer): https://spec.graphql.org/draft/#sec-Input-Objects.Input-Coercion

But it's a good question. I guess the reason is that coercedVariableValues is not explicitly made available in section 3 of the spec.

[martinbonnin]

I see... It may be an issue:

Ultra synthetic example:

type Query {
  a(b: [[Int]]): Int
}

Operation:

query Foo($c: [Int]) {
  a(b: [$c])
}

Runtime Variables:

{
  "c": 42
}

If we're saying the runtime value is the "value that is sent over the wire", we end up with b = [42] (incompatible) instead of b = [[42]] if we coerce the variable to a list first (I think?)
If we're saying the runtime value is the "pre-coerced" value, then there's no need to mention defaultValue