Connections and @stream

[benjie]

The GraphQL Cursor Connections Specification is awesome! For me, it's one of the best practices in GraphQL.

A common way of satisfying hasNextPage is to attempt to fetch an additional node, if it exists then we have a next page:

{ allUsers(first: 10) { pageInfo { hasNextPage } } }

# const rows = sql`select * from users limit 11`;
# const edges = rows.slice(0, 10);
# const hasNextPage = rows.length === 11;

Now consider we want to stream edges from our connection:

{
  allUsers(first: 10) {
    edges @stream {
      cursor
      node { id username avatar }
    }
    pageInfo { hasNextPage }
  }
}

Streaming these edges is not particularly useful, because in order to calculate hasNextPage we have to fetch all the rows up front anyway. (There is still some utility, but not as much as we would get with a plain list.)

I imagine this must have come up at Facebook, perhaps @Keweiqu can shed some light. My guess is instead of streaming like this you simply defer the entire allUsers field.

---

This issue I think actually surfaces a larger modelling problem. In resolver-land, it's the allUsers field that actually performs the fetch, and edges/pageInfo are calculated on the result. Ideally we'd have a way for the connection field itself (allUsers) to stream:

{
  allUsers(first: 10) @stream {
    edges {
      cursor
      node { id username avatar }
    }
    pageInfo { hasNextPage }
  }
}

we want its resolver to yield an async iterable, such that the edges come in one by one, and when done, the pageInfo populates.

However, that definitely doesn't mesh with what we've designed so far. A workaround would be to wrap the pageInfo in @defer:

{
  allUsers(first: 10) {
    edges @stream {
      cursor
      node { id username avatar }
    }
    ... @defer {
      pageInfo { hasNextPage }
    }
  }
}

If allUsers returns an async iterable as part of the result of its resolver, then edges can consume this iterable directly, and pageInfo can wait for the iterable to end and then populate. But I'm concerned it's not very ergonomic, and that people are going to fall in the "pit of failure" by streaming the edges but not deferring the other selections. Connections are such a common pattern, it feels like we should make sure it's well supported by @stream without requiring a lot of user education.

Would love to get your thoughts on this.

[robrichard]

@benjie I know that Relay supports a custom directive @stream_connection: https://relay.dev/docs/guided-tour/list-data/streaming-pagination/. The compiler transpiles it to a @stream on edges and an inline @defer fragment wrapping pageInfo just like in your example https://github.com/facebook/relay/blob/572a90f626a78e98758e76e0402e1151b0e50222/compiler/crates/relay-transforms/tests/transform_connections/fixtures/stream-connection.expected#L55-L68

[benjie]

I wonder if we should come up with a similar idea, because expecting people to know to write out the @stream / ... @defer { ... } themselves each time feels a bit "footgun-y". The simplest approach might be to allow @stream to be added to fields returning a composite type (or non-null thereof), in which case it effectively defers all their non-list children and streams all their list children?