Remove labels and merge deferred fragments under the same object

[robrichard]

Context

Taken from #52 (comment).

There has been discussion around the necessity of labels and how merging deferred fragments would be more inline with the user expectations of GraphQL.

Proposal:

• Remove label from both defer and stream
• All deferred fragments on the same object are merged into a single selection set that is deferred together.
  • Server can choose to inline deferred fragments, but if it does inline, it must inline all of the deferred fragments on this object.
• The algorithm we implement would guarantee that only one payload is sent per path.

This change should remove the need for clients to use labels or hacks like an aliased __typename to identity payloads.

Caveats

• It's no longer possible to have separate deferred fragments to arrive at different times. For simplicity of this spec proposal, we are not attempting to solve that problem at this time.
• The Fragment Modularity (Fragment aliases)
  RFC is one possible way to solve for this problem
• We could explore other options (new defer argument, adding back label, etc) if fragment modularity isn't pursued or evolves in a way that doesn't address this.
• Aliasing the parent field of the deferred fragments is a workaround that could be used to enable this behavior, (but that's not possible if the deferred fragments are directly under the query type).

Example A: Multiple defers on the same object are merged

query {
  friendList {
    ... @defer {
      ...FriendFrag
      ... @defer {
        ...OtherFriendFrag
        ... @defer {
          ...FriendFrag
          ... @defer {
            ...OtherFriendFrag
          }
        }
      }
    }
  }
}
fragment FriendFrag on Friend {
  id
  name
}

}
fragment OtherFriendFrag on Friend {
  name
  birthYear
}

// Responses
[
  {
    "data": { "friendList": [{}, {}, {}] },
    "hasNext": true
  },
  {
    "hasNext": false,
    "incremental": [
      { "data": { "id": "1", "name": "Luke", "birthYear": "19BBY" }, "path": ["friendList", 0] },
      { "data": { "id": "2", "name": "Han", "birthYear": "29BBY" }, "path": ["friendList", 1] },
      { "data": { "id": "3", "name": "Leia", "birthYear": "19BBY" }, "path": ["friendList", 2] }
    ]
  }
]

Example B: Spec guarantees that only one payload is sent per path:

query { 
  nestedObject {
    ... @defer {
      foo
    }
  }
  ... @defer {
    nestedObject {
      ... @defer {
        bar
      }
    }
  }
}

An improved merging algorithm, as proposed in graphql/graphql-js#3820 can give a result that does not do any deduplication, but guarantees all payloads have unique paths:

[
  {
    "data": { "nestedObject": {} },
    "hasNext": true,
  },
  {
    "incremental": [
      {
        "data": { "nestedObject": {} },
        "path": []
      },
      {
        "data": { "foo": "foo", "bar": "foo" },
        "path": ["nestedObject"]
      }
    ],
    "hasNext": false
  }
]

Related

• Deduplication of deferred fields #65

[robrichard]

This has been addressed by the new response format described in #69

We decided against merging defers at the same level or label, but deferred fields are no longer duplicated in this response format which addresses the underlying reason this was suggested