Is a server required to honor the initialCount argument on @stream

[robrichard]

Context

At the time of this discussion creation the incremental delivery spec proposal states (emphasis added):

Therefore, GraphQL clients must be able to process a response
that ignores the @defer and/or @stream directives. This also applies to the
initialCount argument on the @stream directive. Clients must be able to
process a streamed response that contains a different number of initial list
items than what was specified in the initialCount argument.

Should servers be required to send at least as many items as the initialCount argument, or is it ok to send fewer items initially?

Option 1 - Update text to

Clients must be able to process a streamed response that contains more initial list items than what was specified in the initialCount argument.

• If a client receives fewer items than what was specified in the initialCount argument, it can assume that the list is complete. It would be a breaking change to switch to option 2 as this would break this client assumption.
• Developer experience - the developer does not have to account for fewer items being rendered, unless the list is shorter than the initial count.

Option 2 - Text remains as-is

• Guiding Principle: Preserve option value - We can change the spec to option 1, without breaking existing clients.
• Type system guarantees are the same as any list can be empty or have fewer items than expected.
• Advanced servers may have some knowledge that returning a lower initial count is more optimal than what was requested by the client.

Decision

This was discussed at the Feb 2025 primary WG and there was consensus to adopt Option 1. We would not want a product developer to forgo the use of @stream or write client side batching to work around a server sending fewer results than expected in the initial result. It is reasonable to allow a server to send more than the specified initialCount if, for example the server has them cached.

[BoD]

As the client can know whether more items are coming, it seems fine to allow fewer/more elements in the initial payload. Shouldn't be a big difference for the client (just something to know) and allows for more flexibility on the backend - so IMO Option 2: the current text looks fine.

[mjmahone]

the developer does not have to account for fewer items being rendered, unless the list is shorter than the initial count.

This to me is not a major developer experience advantage: you still always need to handle a list shorter than the initial count, because the list can always have less than the initial count.

[mjmahone]

On the other hand I cannot imagine the amount of product developer questions our team would get if initial_count was not honored (we returned more OR fewer, when the list is larger than initial_count). It certainly seems like always honoring initial_count, even if it's less performant, would reduce confusion.

[BoD]

call it preferredInitialCount :)

[benjie]

With: @stream(initialCount: 2)

Response: [1, 2]; then 🔄 streamed: 3, 4, 5, 6
👍 Fine - this is what's expected.

Response: [1, 2, 3, 4]; ❌ no stream
👍 Fine because the server chose not to stream

Response: [1, 2]; ❌ no stream
👍 Fine because there's two results

Response: []; ❌ no stream
👍 Fine because there's no results

Response: [1, 2, 3]; then 🔄 streamed: 4, 5, 6
👍 Fine because 3 results >= 2, and we may already have the `3` in memory.

Response: []; then 🔄 streamed: 1, 2, 3, 4, 5, 6
‼️ NOT FINE IMO

[JoviDeCroock]

This seems correct to me, from a UX point of view we don't want None unless there are really no items so case 4 being okay as we'd render an empty view while case 6 would be unacceptable as we'd flash an empty view to then populate the view.

I don't mind the initial results being more but less feels very counter-intuitive if we then get more afterwards.

[robrichard]

After discussing at the Feb 2025 primary WG there has been consensus around option 1. The parent post has been updated to reflect this.