Glossary #106
Replies: 2 comments 8 replies
-
|
This currently doesn't take into consideration subscriptions:
Perhaps:
(I've not pluralized "incremental results", because this allows the glossary feature to be used if we move this into the spec.) To help think about this, here's a rough shape of the things I see in TS syntax: /** A regular GraphQL response for a traditional GraphQL query/mutation */
interface Response {
data?: object
errors?: Error[]
}
/** A stream of responses returned from a GraphQL subscription - each event triggers a new response */
type ResponseStream = Response[];
/** A GraphQL operation that uses @stream/@defer may return an "incremental stream": an initial response followed by one more more incremental results */
type IncrementalStream = [InitialResponse, ...IncrementalResult[]];
interface InitialResponse extends Response {
pending: ...
hasNext: true;
}
type IncrementalResult =
| {
incremental: IncrementalSomething[]
pending?: ...
completed?: ...
hasNext?: boolean
}
| { hasNext: false }
interface IncrementalSomething {
...
}Not sure what to call |
Beta Was this translation helpful? Give feedback.
-
|
From 2025-02-20 wg discussion: /** A regular GraphQL response for a traditional GraphQL query/mutation */
interface Response {
data?: object
errors?: Error[]
}
/** A stream of responses returned from a GraphQL subscription - each event triggers a new response */
type ResponseStream = Response[];
/** A GraphQL operation that uses @stream/@defer may return an "incremental stream": an initial response followed by one more more incremental results */
type IncrementalStream = [InitialResponse, ...SubsequentPayload[]];
interface InitialResponse extends Response {
incremental: IncrementalResult[]
pending?: Pending[]
completed?: CompletedResult[],
hasNext?: boolean;
}
type SubsequentPayload =
{
incremental?: IncrementalResult[]
pending?: Pending[]
completed?: CompletedResult[],
hasNext?: boolean;
}
type IncrementalResult = IncrementalObjectResult | IncrementalListResult |
Beta Was this translation helpful? Give feedback.
-
|
In the June 2025 Secondary WG we merged: graphql/graphql-spec#1159 which defines "execution result" and "request error result". Based on this, I am updating the types to: /** 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 |
Beta Was this translation helpful? Give feedback.
-
|
Updated the top level comment to change Subsequent Execution Result > Execution Update Result based on the conversation here: graphql/graphql-spec#1132 (comment) |
Beta Was this translation helpful? Give feedback.
-
|
Updated the top level comment to change Initial Execution Result > Initial Incremental Stream Result, Execution Update Result > Incremental Stream Update Result based on the conversation in Feb 2026 Secondary WG group |
Beta Was this translation helpful? Give feedback.
-
|
Updated the top level comment to change Pending Result => Incremental Pending Notice as discussed in graphql/graphql-spec#1203 (review) |
Beta Was this translation helpful? Give feedback.
-
|
What about adding those to the general Glossary? |
Beta Was this translation helpful? Give feedback.
-
|
@martinbonnin i definitely think they should go in the glossary. However, I don't want to add it just yet as we might still iterate on them, but we can start by adding Response and Response Stream after this spec edit is accepted: graphql/graphql-spec#1135 |
Beta Was this translation helpful? Give feedback.
-
|
I've been discussing this with @benjie and I think we both agree that we don't want the Glossary to duplicate the spec. Ultimately, the spec definitions should be the source of truth. I see the glossary as mostly a working document to reach consensus and/or a place to add extra information that's only useful to the spec contributors. Reason I'm pushing for this is that outside perspective and broad consensus is often useful on naming beyond the scope of a single RFC so I'd like to make that Glossary a bit more of a working document. But if you're already on good track there, no obligation to put it there, all goot ✅ . |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
This discussion will be used to document terms related to incremental delivery being used in the GraphQL Spec text:
Response Format
The Response of a GraphQL request will contain a new union member called incremental stream. An incremental stream is made up of an Initial Incremental Stream Result, followed by one or more Incremental Stream Update Result.
Initial Incremental Stream Result:
ExecutionResult, with the addition of new fields required for incremental delivery,hasNext,pending,incremental,completed.Incremental Stream Update Result:
dataorerrorshasNextpending,incremental,completed.Incremental Pending Notice
pendingarray in an initial execution result or incremental stream update resultIncremental Result
incrementalarray in an initial execution result or incremental stream update resultIncremental Completion Notice
completedarray in an initial execution result or incremental stream update resultBeta Was this translation helpful? Give feedback.
All reactions