Skip to content

Commit 96caa27

Browse files
committed
Address PR feedback
1 parent df61253 commit 96caa27

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
@@ -1978,8 +1978,9 @@ either or both of these directives are provided, they must conform to the
19781978
requirements defined in this specification.
19791979

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

19841985
GraphQL implementations that support the type system definition language should
19851986
provide the `@specifiedBy` directive if representing custom scalar definitions.
@@ -2254,39 +2255,50 @@ directive @stream(
22542255
```
22552256

22562257
The `@stream` directive may be provided for a field whose type incorporates a
2257-
`List` type modifier; the directive enables the backend to leverage technology
2258-
such as asynchronous iterators to provide a partial list initially, and
2259-
additional list items in subsequent responses.
2258+
`List` type modifier. The directive enables returning a partial list initially,
2259+
followed by additional items in subsequent responses. Should the field type
2260+
incorporate multiple `List` type modifiers, only the outermost list is streamed.
2261+
2262+
Note: The mechanism through which items are streamed is implementation-defined
2263+
and may use technologies such as asynchronous iterators.
22602264

22612265
The `@include` and `@skip` directives take precedence over `@stream`.
22622266

22632267
```graphql example
22642268
query myQuery($shouldStream: Boolean! = true) {
22652269
user {
2266-
friends(first: 10) {
2267-
nodes
2268-
@stream(label: "friendsStream", initialCount: 5, if: $shouldStream) {
2269-
name
2270-
}
2270+
friends(first: 10)
2271+
@stream(label: "friendsStream", initialCount: 5, if: $shouldStream) {
2272+
name
22712273
}
22722274
}
22732275
}
22742276
```
22752277

22762278
#### @stream Arguments
22772279

2278-
- `initialCount: Int! = 0` - The number of list items the service should return
2279-
initially. If omitted, defaults to `0`. A field error will be raised if the
2280-
value of this argument is less than `0`.
2280+
- `initialCount: Int! = 0` - The number of list items to include initially. If
2281+
omitted, defaults to `0`. A field error will be raised if the value of this
2282+
argument is less than `0`. When the size of the list is greater than or equal
2283+
to the value of `initialCount`, the GraphQL service _must_ initially include
2284+
at least as many list items as the value of `initialCount` (see related note
2285+
below).
22812286
- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
2282-
note below). When `false`, the field must not be streamed and all list items
2283-
must be initially included. Defaults to `true` when omitted.
2287+
note below). When `false`, the field must behave as if the `@stream` directive
2288+
is not presentit must not be streamed and all of the list items must be
2289+
included. Defaults to `true` when omitted.
22842290
- `label: String` - An optional string literal (variables are disallowed) used
22852291
by GraphQL clients to identify data from responses and associate it with the
22862292
corresponding stream directive. If provided, the GraphQL service must include
2287-
this label in the corresponding pending object within the result. The `label`
2288-
argument must be unique across all `@defer` and `@stream` directives in the
2289-
document.
2293+
this label in the corresponding pending object within the response. The
2294+
`label` argument must be unique across all `@defer` and `@stream` directives
2295+
in the document.
2296+
2297+
Note: The
2298+
[Defer And Stream Directive Labels Are Unique](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
2299+
validation rule ensures uniqueness of the values passed to `label` on both the
2300+
`@defer` and `@stream` directives. Variables are disallowed in the `label`
2301+
because their values may not be known during validation.
22902302

22912303
Note: The ability to defer and/or stream parts of a response can have a
22922304
potentially significant impact on application performance. Developers generally
@@ -2295,7 +2307,7 @@ highly recommended that GraphQL services honor the `@defer` and `@stream`
22952307
directives on each execution. However, the specification allows advanced use
22962308
cases where the service can determine that it is more performant to not defer
22972309
and/or stream. Therefore, GraphQL clients _must_ be able to process a response
2298-
that ignores the `@defer` and/or `@stream` directives. This also applies to the
2299-
`initialCount` argument on the `@stream` directive. Clients _must_ be able to
2300-
process a streamed response that contains a different number of initial list
2301-
items than what was specified in the `initialCount` argument.
2310+
that ignores individual `@defer` and/or `@stream` directives. This also applies
2311+
to the `initialCount` argument on the `@stream` directive. Clients must be able
2312+
to process a streamed response that contains more initial list items than what
2313+
was specified in the `initialCount` argument.

0 commit comments

Comments
 (0)