Include an indication of upcoming payloads in response

[robrichard]

Context

Taken from #52 (comment)

Since we allow servers to ignore defer/stream (meaning the results are inlined) there needs to be a way for clients to understand if a payload is being prepared, or was included in a prior response.

Proposed solution

• Adding a pending list of objects to responses would allow clients to know they can expect an upcoming payload at the specified path. If a pending object is not sent, clients can assume the results were included in prior response.
• Update stream paths to point to the list, not a specific index
• Add an additional incremental payload when a stream is completed, with complete: true

**Example A: Defer inside of stream

Although the incremental payloads for defer and stream have the same path, they are not ambiguous because the defer payload contains data and the stream payload contains items.

query {
  friendList @stream {
    id
    ... @defer {
      name
    }
  }
}

// Responses
[
  {
    "data": {
      "friendList": []
    },
    "pending": [{ "path": ["friendList"] }], // stream is pending
    "hasNext": true
  },
  {
    "hasNext": true,
    "pending": [{ "path": ["friendList", 0] }], // defer on first list item is pending
    "incremental": [{ "path": ["friendList"], "items": [{ "id": "1" }] }]
  },
  {
    "hasNext": true,
    "pending": [{ "path": ["friendList", 1] }],
    "incremental": [{ "path": ["friendList", 0], "data": { "name": "Luke" } }]
  },
  {
    "hasNext": true,
    "incremental": [{ "path": ["friendList"], "items": [{ "id": "2" }, "completed": true] }] // stream is complete
  },
  {
    "hasNext": false,
    "incremental": [{ "path": ["friendList", 1], "data": { "name": "Han" } }]
  }
]

Example B: Stream inside of defer,

query {
  ... @defer {
    friendList @stream {
      id
    }
  }
}

// Responses
[
  {
    "data": {},
    "pending": [{ "path": [] }], // defer is pending
    "hasNext": true
  },
  {
    "hasNext": true,
    "pending": [{ "path": ["friendList"] }], // stream is pending
    "incremental": [{ "path": [], "data": { "friendList": [] } }]
  },
  {
    "hasNext": true,
    "incremental": [{ "path": ["friendList"], "items": [{ "id": "1" }] }]
  },
  {
    "hasNext": true,
    "incremental": [{ "path": ["friendList"], "items": [{ "id": "2" }] }]
  },
  {
    "hasNext": true,
    "incremental": [{ "path": ["friendList"], "items": [{ "id": "3" }] }]
  },
  {
    "hasNext": false,
    "incremental": [{ "path": ["friendList"], "completed": true }] // stream is completed
  }
]

[robrichard]

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

The new response format contains "pending" which clients can use to determine if a defer is ignored/inlined by the server.