Incremental Delivery Suggestions

[yaacovCR]

Some of these were discussed during the Feb 2022 WG, some are new, possibly to be discussed in March :)

Execution:
= resolver functions for list fields should return AsyncIterables of Iterables, rather than just AsyncIterables to allow chunking
= change AsyncGenerator returned by execute to return an iterable of all available payloads instead of just the next payload

@stream:
= change stream payload to return an array for data, new atIndex property to specify the initial index for the array
= stream payloads currently act as error boundaries (as opposed to borking the entire stream/future payloads)
= add maxChunkSize Int argument for streaming in chunks
= add 'maxInterval' Int argument to send chunks before maxChunkSize if maxInterval ms have elapsed
= add 'inParallel' Boolean argument to allow sending items whenever ready, uses 'atIndices' instead of 'atIndex' to specify the indices of what is being returned

Related:
graphql/defer-stream-wg#32
graphql/defer-stream-wg#23
graphql/defer-stream-wg#17

[yaacovCR]

Defer with fragments

Operation:

query HeroNameQuery {
  hero {
    id
    ...TopFragment @defer(label: "DeferTop")
  }
}
fragment TopFragment on Hero {
  name
  ...NestedFragment @defer(label: "DeferNested")
}
fragment NestedFragment on Hero {
  friends {
    name
  }
}

Response:

[
  {
    data: {
    hero: {
      id: '1',
    },
  },
    hasNext: true,
  },
  {
    data: {
      friends: [{ name: 'Han' }, { name: 'Leia' }, { name: 'C-3PO' }],
    },
    path: ['hero'],
    label: 'DeferNested',
    hasNext: true,
  },
  {
    data: {
      name: 'Luke',
    },
    path: ['hero'],
    label: 'DeferTop',
    hasNext: false,
  },
]

[yaacovCR]

Defer with slow field in initial payload

Operation:

query HeroNameQuery {
  hero {
    id
    ...NameFragment @defer
  }
}
fragment NameFragment on Hero {
  slowField
  friends {
    ...NestedFragment @defer
  }
}
fragment NestedFragment on Friend {
  name
}

Response:

Results in two sets of payloads.

[
  {
    data: {
      hero: { id: '1' },
    },
    hasNext: true,
  },
],
[
  {
    data: {
      slowField: 'slow',
      friends: [{}, {}, {}],
    },
    path: ['hero'],
    hasNext: true,
  },
  {
    data: { name: 'Han' },
    path: ['hero', 'friends', 0],
    hasNext: true,
  },
  {
    data: { name: 'Leia' },
    path: ['hero', 'friends', 1],
    hasNext: true,
  },
  {
    data: { name: 'C-3PO' },
    path: ['hero', 'friends', 2],
    hasNext: false,
  },
]

[yaacovCR]

Stream

Operation:

{
  scalarList @stream
}

OR

{
  scalarList @stream(initialCount: 1)
}

Response:

[
  {
    data: {
    scalarList: ['apple'],
  },
    hasNext: true,
  },
  {
    data: ['banana'],
    path: ['scalarList'],
    atIndex: 1,
    hasNext: true,
  },
  {
    data: ['coconut'],
    path: ['scalarList'],
    atIndex: 2,
    hasNext: false,
  },
]

[yaacovCR]

Stream with chunks of greater than 1

Operation:

{
  scalarList @stream(maxChunkSize: 2)
}

Response:

The first stream chunk hits its max.

[
  {
    data: {
      scalarList: [],
    },
    hasNext: true,
    },
  {
    data: ['apple', 'banana'],
    path: ['scalarList'],
    atIndex: 0,
    hasNext: true,
  },
  {
    data: ['coconut'],
    path: ['scalarList'],
    atIndex: 2,
    hasNext: false,
  },
]

[yaacovCR]

Stream in correct order even when the first item is slow

Operation:

query { 
  asyncSlowList @stream(initialCount: 0) {
    name
    id
  }
}

Response:

Note that a slow item 1 will move all the items to the second set of payloads.

[
  {
    data: {
      asyncSlowList: [],
    },
    hasNext: true,
  },
],
[
  {
    data: [
      {
        name: 'Luke',
        id: '1',
      },
    ],
    path: ['asyncSlowList'],
    atIndex: 0,
    hasNext: true,
  },
  {
    data: [
      {
        name: 'Han',
        id: '2',
      },
    ],
    path: ['asyncSlowList'],
    atIndex: 1,
    hasNext: true,
  },
  {
    data: [
      {
        name: 'Leia',
        id: '3',
      },
    ],
    path: ['asyncSlowList'],
    atIndex: 2,
    hasNext: false,
  },
]

[yaacovCR]

Stream in parallel

Operation:

query { 
  asyncSlowList @stream(initialCount: 0, maxChunkSize: 1, inParallel: true) {
    name
    id
  }
}

Response:

When streaming in parallel, the first set of payloads includes everything except the slow item 1.

[
  {
    data: {
      asyncSlowList: [],
    },
    hasNext: true,
  },
  {
    data: [
      {
        name: 'Han',
        id: '2',
      },
      {
        name: 'Leia',
        id: '3',
      },
    ],
    path: ['asyncSlowList'],
    atIndices: [1, 2],
    hasNext: true,
  },
],
[
  {
    data: [
      {
        name: 'Luke',
        id: '1',
      },
    ],
    path: ['asyncSlowList'],
    atIndices: [0],
    hasNext: false,
  },
]

[yaacovCR]

Stream with asyncIterableList

Operation:

query { 
  asyncIterableList @stream {
    name
    id
  }
}

OR

query { 
  asyncIterableList @stream(maxChunkSize: 1) {
    name
    id
  }
}

OR

query { 
  asyncIterableList @stream(maxChunkSize: 2, maxInterval: 1) {
    name
    id
  }
}

Response:

With AsyncIterables, each item will have to be in its own set of payloads, unless chunked. (The default maxChunkSize is 1.) But, even if chunked, if the interval elapses, it is sent separately before the chunk maxes out. So, a maxChunkSize greater than 1 could still end up sending smaller payloads if the maxInterval is exceeded.

[
  {
    data: {
      asyncIterableList: [],
    },
    hasNext: true,
  },
  {
    data: [
      {
        name: 'Luke',
        id: '1',
      },
    ],
    path: ['asyncIterableList'],
    atIndex: 0,
    hasNext: true,
  },
],
[
  {
    data: [
      {
        name: 'Han',
        id: '2',
      },
    ],
    path: ['asyncIterableList'],
    atIndex: 1,
    hasNext: true,
  },
],
[
  {
    data: [
    {
        name: 'Leia',
        id: '3',
    },
    ],
    path: ['asyncIterableList'],
    atIndex: 2,
    hasNext: true,
  },
  {
    hasNext: false,
  },
]

[yaacovCR]

Stream with asyncIterableList with chunk size > 1

Operation:

query { 
  asyncIterableList @stream(maxChunkSize: 2) {
    name
    id
  }
}

Response:

[
  {
    data: {
      asyncIterableList: [],
    },
    hasNext: true,
  },
  {
    data: [
      {
        name: 'Luke',
        id: '1',
      },
      {
        name: 'Han',
        id: '2',
      },
    ],
    path: ['asyncIterableList'],
    atIndex: 0,
    hasNext: true,
  },
],
[
  {
    data: [
    {
        name: 'Leia',
        id: '3',
    },
    ],
    path: ['asyncIterableList'],
    atIndex: 2,
    hasNext: true,
  },
  {
    hasNext: false,
  },
]

[yaacovCR]

Stream where a non-nullable item returns null

Operation:

query { 
  asyncIterableNonNullError @stream(initialCount: 1) {
    name
  }
}

Response:

[
  {
    data: {
      asyncIterableNonNullError: [
        {
          name: 'Luke',
        },
      ],
    },
    hasNext: true,
  },
  {
    data: null,
    path: ['asyncIterableNonNullError'],
    atIndex: 1,
    errors: [
      {
        message:
        'Cannot return null for non-nullable field Query.asyncIterableNonNullError.',
        locations: [
          {
            line: 3,
            column: 9,
          },
        ],
        path: ['asyncIterableNonNullError', 1],
      },
    ],
    hasNext: true,
  },
],
[
  {
    data: [
      {
        name: 'Han',
      },
    ],
    path: ['asyncIterableNonNullError'],
    atIndex: 2,
    hasNext: true,
  },
  {
    hasNext: false,
  },
]

[yaacovCR]

Examples:

Defer with fragments
Defer with slow field in initial payload
Stream
Stream with chunks of greater than 1
Stream in correct order even when the first item is slow
Stream in parallel
Stream with asyncIterableList
Stream with asyncIterableList with chunk size > 1
Stream where a non-nullable item returns null

[yaacovCR]

Returning to simple fork.