incrementalDelivery: use single execute function with flag being directives themselves

The use of new experimental functionality triggered by directives does not need a separate runtime flag. The directives themselves are the flags and all operations passed to `execute` are assumed to be valid.

Using TS conditional types, when new generic `TMaybeIncremental` parameter is set to true, return type of `execute` will be either an ExecutionResult or an IncrementalExecutionResultMap containing an `initialResult` and a generator of `subsequentResults`. While incremental delivery is designated as experimental, `TMaybeIncremental` will default to `false`. When incremental delivery is merged into the spec, it may be useful to adjust the default to `true`.

Note that this PR removes the `ExperimentalExecuteIncrementallyResults`, instead favoring a union of ExecutionResults and IncrementalExecutionResultsMap as above, avoiding the unnecessary runtime wrapping of single results.

Author: yaacovCR

src/execution/__tests__/defer-test.ts

@@ -1,8 +1,6 @@
-import { expect } from 'chai';
 import { describe, it } from 'mocha';
 
 import { expectJSON } from '../../__testUtils__/expectJSON.js';
-import { expectPromise } from '../../__testUtils__/expectPromise.js';
 import { resolveOnNextTick } from '../../__testUtils__/resolveOnNextTick.js';
 
 import type { DocumentNode } from '../../language/ast.js';
@@ -20,7 +18,7 @@ import type {
   InitialIncrementalExecutionResult,
   SubsequentIncrementalExecutionResult,
 } from '../execute.js';
-import { execute, experimentalExecuteIncrementally } from '../execute.js';
+import { execute } from '../execute.js';
 
 const friendType = new GraphQLObjectType({
   fields: {
@@ -84,7 +82,7 @@ const query = new GraphQLObjectType({
 const schema = new GraphQLSchema({ query });
 
 async function complete(document: DocumentNode) {
-  const result = await experimentalExecuteIncrementally({
+  const result = await execute<true>({
     schema,
     document,
     rootValue: {},
@@ -656,46 +654,4 @@ describe('Execute: defer directive', () => {
       },
     ]);
   });
-
-  it('original execute function throws error if anything is deferred and everything else is sync', () => {
-    const doc = `
-    query Deferred {
-      ... @defer { hero { id } }
-    }
-  `;
-    expect(() =>
-      execute({
-        schema,
-        document: parse(doc),
-        rootValue: {},
-      }),
-    ).to.throw(
-      'Executing this GraphQL operation would unexpectedly produce multiple payloads (due to @defer or @stream directive)',
-    );
-  });
-
-  it('original execute function resolves to error if anything is deferred and something else is async', async () => {
-    const doc = `
-    query Deferred {
-      hero { slowField }
-      ... @defer { hero { id } }
-    }
-  `;
-    expectJSON(
-      await expectPromise(
-        execute({
-          schema,
-          document: parse(doc),
-          rootValue: {},
-        }),
-      ).toResolve(),
-    ).toDeepEqual({
-      errors: [
-        {
-          message:
-            'Executing this GraphQL operation would unexpectedly produce multiple payloads (due to @defer or @stream directive)',
-        },
-      ],
-    });
-  });
 });

src/execution/__tests__/executor-test.ts

@@ -807,7 +807,12 @@ describe('Execute: Handles basic execution tasks', () => {
     const rootValue = { a: 'b', c: 'd' };
     const operationName = 'Q';
 
-    const result = executeSync({ schema, document, rootValue, operationName });
+    const result = executeSync({
+      schema,
+      document,
+      rootValue,
+      operationName,
+    });
     expect(result).to.deep.equal({ data: { a: 'b' } });
   });
 

src/execution/__tests__/mutations-test.ts

@@ -10,11 +10,7 @@ import { GraphQLObjectType } from '../../type/definition.js';
 import { GraphQLInt } from '../../type/scalars.js';
 import { GraphQLSchema } from '../../type/schema.js';
 
-import {
-  execute,
-  executeSync,
-  experimentalExecuteIncrementally,
-} from '../execute.js';
+import { execute, executeSync } from '../execute.js';
 
 class NumberHolder {
   theNumber: number;
@@ -218,7 +214,7 @@ describe('Execute: Handles mutation execution ordering', () => {
     `);
 
     const rootValue = new Root(6);
-    const mutationResult = await experimentalExecuteIncrementally({
+    const mutationResult = await execute<true>({
       schema,
       document,
       rootValue,
@@ -294,7 +290,7 @@ describe('Execute: Handles mutation execution ordering', () => {
     `);
 
     const rootValue = new Root(6);
-    const mutationResult = await experimentalExecuteIncrementally({
+    const mutationResult = await execute<true>({
       schema,
       document,
       rootValue,

src/execution/__tests__/stream-test.ts

@@ -20,7 +20,7 @@ import type {
   InitialIncrementalExecutionResult,
   SubsequentIncrementalExecutionResult,
 } from '../execute.js';
-import { experimentalExecuteIncrementally } from '../execute.js';
+import { execute } from '../execute.js';
 
 const friendType = new GraphQLObjectType({
   fields: {
@@ -69,7 +69,7 @@ const query = new GraphQLObjectType({
 const schema = new GraphQLSchema({ query });
 
 async function complete(document: DocumentNode, rootValue: unknown = {}) {
-  const result = await experimentalExecuteIncrementally({
+  const result = await execute<true>({
     schema,
     document,
     rootValue,
@@ -92,7 +92,7 @@ async function completeAsync(
   numCalls: number,
   rootValue: unknown = {},
 ) {
-  const result = await experimentalExecuteIncrementally({
+  const result = await execute<true>({
     schema,
     document,
     rootValue,
@@ -1017,7 +1017,7 @@ describe('Execute: stream directive', () => {
         }
       }
     `);
-    const executeResult = await experimentalExecuteIncrementally({
+    const executeResult = await execute<true>({
       schema,
       document,
       rootValue: {
@@ -1110,7 +1110,7 @@ describe('Execute: stream directive', () => {
     }
   `);
 
-    const executeResult = await experimentalExecuteIncrementally({
+    const executeResult = await execute<true>({
       schema,
       document,
       rootValue: {
@@ -1196,7 +1196,7 @@ describe('Execute: stream directive', () => {
     }
   `);
 
-    const executeResult = await experimentalExecuteIncrementally({
+    const executeResult = await execute<true>({
       schema,
       document,
       rootValue: {
@@ -1300,7 +1300,7 @@ describe('Execute: stream directive', () => {
       }
     `);
 
-    const executeResult = await experimentalExecuteIncrementally({
+    const executeResult = await execute<true>({
       schema,
       document,
       rootValue: {
@@ -1354,7 +1354,7 @@ describe('Execute: stream directive', () => {
       }
     `);
 
-    const executeResult = await experimentalExecuteIncrementally({
+    const executeResult = await execute<true>({
       schema,
       document,
       rootValue: {
@@ -1414,7 +1414,7 @@ describe('Execute: stream directive', () => {
       }
     `);
 
-    const executeResult = await experimentalExecuteIncrementally({
+    const executeResult = await execute<true>({
       schema,
       document,
       rootValue: {

src/execution/__tests__/subscribe-test.ts

@@ -21,11 +21,7 @@ import {
 import { GraphQLSchema } from '../../type/schema.js';
 
 import type { ExecutionArgs, ExecutionResult } from '../execute.js';
-import {
-  createSourceEventStream,
-  experimentalSubscribeIncrementally,
-  subscribe,
-} from '../execute.js';
+import { createSourceEventStream, subscribe } from '../execute.js';
 
 import { SimplePubSub } from './simplePubSub.js';
 
@@ -99,7 +95,6 @@ const emailSchema = new GraphQLSchema({
 function createSubscription(
   pubsub: SimplePubSub<Email>,
   variableValues?: { readonly [variable: string]: unknown },
-  originalSubscribe: boolean = false,
 ) {
   const document = parse(`
     subscription ($priority: Int = 0, $shouldDefer: Boolean = false, $asyncResolver: Boolean = false) {
@@ -145,7 +140,7 @@ function createSubscription(
     }),
   };
 
-  return (originalSubscribe ? subscribe : experimentalSubscribeIncrementally)({
+  return subscribe({
     schema: emailSchema,
     document,
     rootValue: data,
@@ -841,75 +836,6 @@ describe('Subscription Publish Phase', () => {
     });
   });
 
-  it('original subscribe function returns errors with @defer', async () => {
-    const pubsub = new SimplePubSub<Email>();
-    const subscription = await createSubscription(
-      pubsub,
-      {
-        shouldDefer: true,
-      },
-      true,
-    );
-    assert(isAsyncIterable(subscription));
-    // Wait for the next subscription payload.
-    const payload = subscription.next();
-
-    // A new email arrives!
-    expect(
-      pubsub.emit({
-        from: 'yuzhi@graphql.org',
-        subject: 'Alright',
-        message: 'Tests are good',
-        unread: true,
-      }),
-    ).to.equal(true);
-
-    const errorPayload = {
-      done: false,
-      value: {
-        errors: [
-          {
-            message:
-              'Executing this GraphQL operation would unexpectedly produce multiple payloads (due to @defer or @stream directive)',
-          },
-        ],
-      },
-    };
-
-    // The previously waited on payload now has a value.
-    expectJSON(await payload).toDeepEqual(errorPayload);
-
-    // Wait for the next payload from @defer
-    expectJSON(await subscription.next()).toDeepEqual(errorPayload);
-
-    // Another new email arrives, after all incrementally delivered payloads are received.
-    expect(
-      pubsub.emit({
-        from: 'hyo@graphql.org',
-        subject: 'Tools',
-        message: 'I <3 making things',
-        unread: true,
-      }),
-    ).to.equal(true);
-
-    // The next waited on payload will have a value.
-    expectJSON(await subscription.next()).toDeepEqual(errorPayload);
-    // The next waited on payload will have a value.
-    expectJSON(await subscription.next()).toDeepEqual(errorPayload);
-
-    // The client disconnects before the deferred payload is consumed.
-    expectJSON(await subscription.return()).toDeepEqual({
-      done: true,
-      value: undefined,
-    });
-
-    // Awaiting a subscription after closing it results in completed results.
-    expectJSON(await subscription.next()).toDeepEqual({
-      done: true,
-      value: undefined,
-    });
-  });
-
   it('produces a payload when there are multiple events', async () => {
     const pubsub = new SimplePubSub<Email>();
     const subscription = createSubscription(pubsub);

src/execution/__tests__/sync-test.ts

@@ -114,6 +114,16 @@ describe('Execute: synchronously when possible', () => {
       }).to.throw('GraphQL execution failed to complete synchronously.');
     });
 
+    it('return successfully if incremental delivery is enabled but async iterable is not returned', () => {
+      const doc = 'query Example { syncField }';
+      const result = executeSync({
+        schema,
+        document: parse(doc),
+        rootValue: 'rootValue',
+      });
+      expect(result).to.deep.equal({ data: { syncField: 'rootValue' } });
+    });
+
     it('throws if encountering async iterable execution', () => {
       const doc = `
         query Example {