Spec edits for incremental delivery, Section 3 only

[robrichard]

Extracted from the full PR (#1110) and targeting an integration branch to aid in review.

Helpful reference material:

Response format examples: graphql/defer-stream-wg#69
Glossary: graphql/defer-stream-wg#106
GraphQL Conf talk: https://www.youtube.com/watch?v=LEyDeNoobT0

Response types

/** Currently defined types */
type RequestErrorResult = {
  errors: Error[] // request errors only
  extensions?: object
}
type ExecutionResult = {
  data: {} | null
  errors?: Error[] // execution errors only
  extensions?: object
}
type ResponseStream = ExecutionResult[]

/** New types that are yielded by an Incremental Stream */
interface InitialExecutionResult extends ExecutionResult {
  incremental: IncrementalResult[]
  pending?: Pending[]
  completed?: CompletedResult[],
  hasNext?: boolean;
}

type SubsequentExecutionResult = {
  incremental?: IncrementalResult[]
  pending?: Pending[]
  completed?: CompletedResult[],
  hasNext?: boolean;
}

type IncrementalStream = [InitialExecutionResult, ...SubsequentExecutionResult[]];

/** Response is updated to include IncrementalStream as a new member */
type Response = RequestErrorResult | ExecutionResult | ResponseStream | IncrementalStream;

type IncrementalResult = IncrementalObjectResult | IncrementalListResult

[benjie]

Lots of nit-picky comments but I think we're pretty close! Do we have a glossary somewhere? I think we need to be really crisp on terms like "result", "response", "payload" and the like.

[benjie]

I believe that we've refined the terminology around this: there's one response. The response for stream/defer is a stream consisting of an initial result payload followed by a number of incremental payloads. I couldn't find where we discussed this, so please correct as appropriate.

Suggested change

	responses: the initial response containing all non-deferred data, while
	subsequent responses include deferred data.
	payloads: the initial payload containing all non-deferred data, while subsequent
	payloads include deferred data.

[robrichard]

@benjie after the last discussion we had, I decided to drop payload. The response section now says:

The result of a GraphQL request must be either a single initial response or an
incremental stream. The response will be an incremental stream when the GraphQL
service has deferred or streamed data as a result of the @defer or @stream
directives. When the result of the GraphQL operation is an incremental stream,
the first value will be an initial response, followed by one or more subsequent
responses.

[benjie]

The "and" here implies this is an additional behaviour

Suggested change

	- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
	note below). When `false`, the field must not be streamed and all list items
	must be initially included. Defaults to `true` when omitted.
	- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
	note below). When `false`, the field must behave as if the `@stream` directive
	is not present—it must not be streamed and all of the list items must be
	included. Defaults to `true` when omitted.

[robrichard]

@benjie I added a rough glossary here: graphql/defer-stream-wg#106, I'll keep refining it as we go

[mjmahone]

These changes look correct to me, I don't think the definition of the @stream/@defer directives have changed in a very long time, so this feels good.

[leebyron]

keep if consistently as the first arg

[leebyron]

should this arg be last? to match if/label/* order from defer