defer/stream: split incremental delivery into new entry point

This PR changes the `execute` and `graphql` APIs on the `defer-stream`
branch back to having the same API as on `main`: they can only produce a
single `ExecutionResult` and do not support incremental delivery.

Incremental delivery is now provided by the new entry point
`experimentalExecuteIncrementally`. (We will remove "experimental" once
the proposal has been merged into the GraphQL spec.) This function
always returns a Promise containing an object that is *either* a single
result *or* an initial result plus a generator for subsequent results.

This will make upgrading to graphql@17 easier, and increases the clarity
of return types.

Use distinct types for "the only result of a single-payload execution",
"the first payload of a multi-payload execution", and "subsequent
payloads of a multi-payload execution", since the data structures are
different. (Multi-payload executions *always* have at least one payload,
and the structure differs, which is why the new types separate the
initial result from subsequent results.)

Note that with the previous types, you actually had to use a function
with a type guard like `isAsyncIterable`: you couldn't just write `if
(Symbol.asyncIterator in result)`. I think both explicitly separating
the first (differently-typed) element from the rest of the elements
*and* making it possible to differentiate the types with a simple `in`
check are improvements. Additionally, somebody using the API in
JavaScript who doesn't realize that there is new functionality available
who is confused that the result no longer has `data`/`errors` fields can
just print out the result and see and search for the terms
`initialResult` and `subsequentResults` instead of only seeing iterator
internals.

Fix `Formatted*Result` types to use `GraphQLFormattedError` rather than
`GraphQLError` for `errors` nested inside `incremental`.

Author: glasser

src/execution/__tests__/defer-test.ts

@@ -1,10 +1,9 @@
 import { describe, it } from 'mocha';
 
 import { expectJSON } from '../../__testUtils__/expectJSON';
+import { expectPromise } from '../../__testUtils__/expectPromise';
 import { resolveOnNextTick } from '../../__testUtils__/resolveOnNextTick';
 
-import { isAsyncIterable } from '../../jsutils/isAsyncIterable';
-
 import type { DocumentNode } from '../../language/ast';
 import { parse } from '../../language/parser';
 
@@ -16,7 +15,11 @@ import {
 import { GraphQLID, GraphQLString } from '../../type/scalars';
 import { GraphQLSchema } from '../../type/schema';
 
-import { execute } from '../execute';
+import type {
+  InitialIncrementalExecutionResult,
+  SubsequentIncrementalExecutionResult,
+} from '../execute';
+import { execute, experimentalExecuteIncrementally } from '../execute';
 
 const friendType = new GraphQLObjectType({
   fields: {
@@ -77,23 +80,25 @@ const query = new GraphQLObjectType({
   name: 'Query',
 });
 
-async function complete(document: DocumentNode) {
-  const schema = new GraphQLSchema({ query });
+const schema = new GraphQLSchema({ query });
 
-  const result = await execute({
+async function complete(document: DocumentNode) {
+  const result = await experimentalExecuteIncrementally({
     schema,
     document,
     rootValue: {},
   });
 
-  if (isAsyncIterable(result)) {
-    const results = [];
-    for await (const patch of result) {
+  if ('initialResult' in result) {
+    const results: Array<
+      InitialIncrementalExecutionResult | SubsequentIncrementalExecutionResult
+    > = [result.initialResult];
+    for await (const patch of result.subsequentResults) {
       results.push(patch);
     }
     return results;
   }
-  return result;
+  return result.singleResult;
 }
 
 describe('Execute: defer directive', () => {
@@ -641,4 +646,21 @@ describe('Execute: defer directive', () => {
       },
     ]);
   });
+
+  it('original execute function errors if anything is deferred', async () => {
+    const doc = `
+    query Deferred {
+      ... @defer { hero { id } }
+    }
+  `;
+    await expectPromise(
+      execute({
+        schema,
+        document: parse(doc),
+        rootValue: {},
+      }),
+    ).toRejectWith(
+      'Executing this GraphQL operation would unexpectedly produce multiple payloads (due to @defer or @stream directive)',
+    );
+  });
 });

src/execution/__tests__/lists-test.ts

@@ -3,8 +3,6 @@ import { describe, it } from 'mocha';
 
 import { expectJSON } from '../../__testUtils__/expectJSON';
 
-import type { PromiseOrValue } from '../../jsutils/PromiseOrValue';
-
 import { parse } from '../../language/parser';
 
 import type { GraphQLFieldResolver } from '../../type/definition';
@@ -14,8 +12,12 @@ import { GraphQLSchema } from '../../type/schema';
 
 import { buildSchema } from '../../utilities/buildASTSchema';
 
-import type { AsyncExecutionResult, ExecutionResult } from '../execute';
-import { execute, executeSync } from '../execute';
+import type { ExperimentalExecuteIncrementallyResults } from '../execute';
+import {
+  execute,
+  executeSync,
+  experimentalExecuteIncrementally,
+} from '../execute';
 
 describe('Execute: Accepts any iterable as list value', () => {
   function complete(rootValue: unknown) {
@@ -85,9 +87,7 @@ describe('Execute: Accepts async iterables as list value', () => {
 
   function completeObjectList(
     resolve: GraphQLFieldResolver<{ index: number }, unknown>,
-  ): PromiseOrValue<
-    ExecutionResult | AsyncGenerator<AsyncExecutionResult, void, void>
-  > {
+  ): Promise<ExperimentalExecuteIncrementallyResults> {
     const schema = new GraphQLSchema({
       query: new GraphQLObjectType({
         name: 'Query',
@@ -113,7 +113,7 @@ describe('Execute: Accepts async iterables as list value', () => {
         },
       }),
     });
-    return execute({
+    return experimentalExecuteIncrementally({
       schema,
       document: parse('{ listField { index } }'),
     });
@@ -191,7 +191,9 @@ describe('Execute: Accepts async iterables as list value', () => {
     expectJSON(
       await completeObjectList(({ index }) => Promise.resolve(index)),
     ).toDeepEqual({
-      data: { listField: [{ index: '0' }, { index: '1' }, { index: '2' }] },
+      singleResult: {
+        data: { listField: [{ index: '0' }, { index: '1' }, { index: '2' }] },
+      },
     });
   });
 
@@ -204,14 +206,16 @@ describe('Execute: Accepts async iterables as list value', () => {
         return Promise.resolve(index);
       }),
     ).toDeepEqual({
-      data: { listField: [{ index: '0' }, { index: '1' }, { index: null }] },
-      errors: [
-        {
-          message: 'bad',
-          locations: [{ line: 1, column: 15 }],
-          path: ['listField', 2, 'index'],
-        },
-      ],
+      singleResult: {
+        data: { listField: [{ index: '0' }, { index: '1' }, { index: null }] },
+        errors: [
+          {
+            message: 'bad',
+            locations: [{ line: 1, column: 15 }],
+            path: ['listField', 2, 'index'],
+          },
+        ],
+      },
     });
   });
   it('Handles nulls yielded by async generator', async () => {

src/execution/__tests__/mutations-test.ts

@@ -4,15 +4,17 @@ import { describe, it } from 'mocha';
 import { expectJSON } from '../../__testUtils__/expectJSON';
 import { resolveOnNextTick } from '../../__testUtils__/resolveOnNextTick';
 
-import { isAsyncIterable } from '../../jsutils/isAsyncIterable';
-
 import { parse } from '../../language/parser';
 
 import { GraphQLObjectType } from '../../type/definition';
 import { GraphQLInt } from '../../type/scalars';
 import { GraphQLSchema } from '../../type/schema';
 
-import { execute, executeSync } from '../execute';
+import {
+  execute,
+  executeSync,
+  experimentalExecuteIncrementally,
+} from '../execute';
 
 class NumberHolder {
   theNumber: number;
@@ -216,15 +218,16 @@ describe('Execute: Handles mutation execution ordering', () => {
     `);
 
     const rootValue = new Root(6);
-    const mutationResult = await execute({
+    const mutationResult = await experimentalExecuteIncrementally({
       schema,
       document,
       rootValue,
     });
     const patches = [];
 
-    assert(isAsyncIterable(mutationResult));
-    for await (const patch of mutationResult) {
+    assert('initialResult' in mutationResult);
+    patches.push(mutationResult.initialResult);
+    for await (const patch of mutationResult.subsequentResults) {
       patches.push(patch);
     }
 
@@ -291,15 +294,16 @@ describe('Execute: Handles mutation execution ordering', () => {
     `);
 
     const rootValue = new Root(6);
-    const mutationResult = await execute({
+    const mutationResult = await experimentalExecuteIncrementally({
       schema,
       document,
       rootValue,
     });
     const patches = [];
 
-    assert(isAsyncIterable(mutationResult));
-    for await (const patch of mutationResult) {
+    assert('initialResult' in mutationResult);
+    patches.push(mutationResult.initialResult);
+    for await (const patch of mutationResult.subsequentResults) {
       patches.push(patch);
     }
 

src/execution/__tests__/nonnull-test.ts

@@ -13,7 +13,7 @@ import { GraphQLSchema } from '../../type/schema';
 
 import { buildSchema } from '../../utilities/buildASTSchema';
 
-import type { AsyncExecutionResult, ExecutionResult } from '../execute';
+import type { ExecutionResult } from '../execute';
 import { execute, executeSync } from '../execute';
 
 const syncError = new Error('sync');
@@ -111,9 +111,7 @@ const schema = buildSchema(`
 function executeQuery(
   query: string,
   rootValue: unknown,
-): PromiseOrValue<
-  ExecutionResult | AsyncGenerator<AsyncExecutionResult, void, void>
-> {
+): PromiseOrValue<ExecutionResult> {
   return execute({ schema, document: parse(query), rootValue });
 }
 

src/execution/__tests__/simplePubSub.ts

@@ -51,6 +51,7 @@ export class SimplePubSub<T> {
         emptyQueue();
         return Promise.resolve({ value: undefined, done: true });
       },
+      /* c8 ignore next 4 */
       throw(error: unknown) {
         emptyQueue();
         return Promise.reject(error);