Skip to content

Commit 7d82d44

Browse files
committed
Address PR feedback
1 parent 5892e12 commit 7d82d44

File tree

1 file changed

+34
-22
lines changed

1 file changed

+34
-22
lines changed

spec/Section 3 -- Type System.md

Lines changed: 34 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2089,8 +2089,9 @@ either or both of these directives are provided, they must conform to the
20892089
requirements defined in this specification.
20902090

20912091
Note: The [Directives Are Defined](#sec-Directives-Are-Defined) validation rule
2092-
ensures that GraphQL Operations containing the `@defer` or `@stream` directives
2093-
cannot be executed by a GraphQL service that does not support them.
2092+
ensures that GraphQL operations can only include directives available on the
2093+
schema; thus operations including `@defer` or `@stream` directives can only be
2094+
executed by a GraphQL service that supports them.
20942095

20952096
GraphQL implementations that support the type system definition language should
20962097
provide the `@specifiedBy` directive if representing custom scalar definitions.
@@ -2385,39 +2386,50 @@ directive @stream(
23852386
```
23862387

23872388
The `@stream` directive may be provided for a field whose type incorporates a
2388-
`List` type modifier; the directive enables the backend to leverage technology
2389-
such as asynchronous iterators to provide a partial list initially, and
2390-
additional list items in subsequent responses.
2389+
`List` type modifier. The directive enables returning a partial list initially,
2390+
followed by additional items in subsequent responses. Should the field type
2391+
incorporate multiple `List` type modifiers, only the outermost list is streamed.
2392+
2393+
Note: The mechanism through which items are streamed is implementation-defined
2394+
and may use technologies such as asynchronous iterators.
23912395

23922396
The `@include` and `@skip` directives take precedence over `@stream`.
23932397

23942398
```graphql example
23952399
query myQuery($shouldStream: Boolean! = true) {
23962400
user {
2397-
friends(first: 10) {
2398-
nodes
2399-
@stream(label: "friendsStream", initialCount: 5, if: $shouldStream) {
2400-
name
2401-
}
2401+
friends(first: 10)
2402+
@stream(label: "friendsStream", initialCount: 5, if: $shouldStream) {
2403+
name
24022404
}
24032405
}
24042406
}
24052407
```
24062408

24072409
#### @stream Arguments
24082410

2409-
- `initialCount: Int! = 0` - The number of list items the service should return
2410-
initially. If omitted, defaults to `0`. A field error will be raised if the
2411-
value of this argument is less than `0`.
2411+
- `initialCount: Int! = 0` - The number of list items to include initially. If
2412+
omitted, defaults to `0`. A field error will be raised if the value of this
2413+
argument is less than `0`. When the size of the list is greater than or equal
2414+
to the value of `initialCount`, the GraphQL service _must_ initially include
2415+
at least as many list items as the value of `initialCount` (see related note
2416+
below).
24122417
- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
2413-
note below). When `false`, the field must not be streamed and all list items
2414-
must be initially included. Defaults to `true` when omitted.
2418+
note below). When `false`, the field must behave as if the `@stream` directive
2419+
is not presentit must not be streamed and all of the list items must be
2420+
included. Defaults to `true` when omitted.
24152421
- `label: String` - An optional string literal (variables are disallowed) used
24162422
by GraphQL clients to identify data from responses and associate it with the
24172423
corresponding stream directive. If provided, the GraphQL service must include
2418-
this label in the corresponding pending object within the result. The `label`
2419-
argument must be unique across all `@defer` and `@stream` directives in the
2420-
document.
2424+
this label in the corresponding pending object within the response. The
2425+
`label` argument must be unique across all `@defer` and `@stream` directives
2426+
in the document.
2427+
2428+
Note: The
2429+
[Defer And Stream Directive Labels Are Unique](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
2430+
validation rule ensures uniqueness of the values passed to `label` on both the
2431+
`@defer` and `@stream` directives. Variables are disallowed in the `label`
2432+
because their values may not be known during validation.
24212433

24222434
Note: The ability to defer and/or stream parts of a response can have a
24232435
potentially significant impact on application performance. Developers generally
@@ -2426,7 +2438,7 @@ highly recommended that GraphQL services honor the `@defer` and `@stream`
24262438
directives on each execution. However, the specification allows advanced use
24272439
cases where the service can determine that it is more performant to not defer
24282440
and/or stream. Therefore, GraphQL clients _must_ be able to process a response
2429-
that ignores the `@defer` and/or `@stream` directives. This also applies to the
2430-
`initialCount` argument on the `@stream` directive. Clients _must_ be able to
2431-
process a streamed response that contains a different number of initial list
2432-
items than what was specified in the `initialCount` argument.
2441+
that ignores individual `@defer` and/or `@stream` directives. This also applies
2442+
to the `initialCount` argument on the `@stream` directive. Clients must be able
2443+
to process a streamed response that contains more initial list items than what
2444+
was specified in the `initialCount` argument.

0 commit comments

Comments
 (0)