@graphql-tools/executor 1.2.6 → 2.0.0-alpha-20240606144658-8963c8b8f661638eaee0e101a55f3b6e46cc03ff

package/esm/execution/execute.js

@@ -1,8 +1,10 @@
 import { assertValidSchema, getDirectiveValues, GraphQLError, isAbstractType, isLeafType, isListType, isNonNullType, isObjectType, Kind, locatedError, SchemaMetaFieldDef, TypeMetaFieldDef, TypeNameMetaFieldDef, } from 'graphql';
-import { ValueOrPromise } from 'value-or-promise';
-import { collectSubFields as _collectSubfields, addPath, collectFields, createGraphQLError, getArgumentValues, getDefinedRootType, GraphQLStreamDirective, inspect, isAsyncIterable, isIterableObject, isObjectLike, isPromise, mapAsyncIterator, memoize1, memoize3, pathToArray, promiseReduce, } from '@graphql-tools/utils';
+import { addPath, createGraphQLError, getArgumentValues, getDefinedRootType, GraphQLStreamDirective, inspect, isAsyncIterable, isIterableObject, isObjectLike, isPromise, mapAsyncIterator, memoize1, memoize3, pathToArray, promiseReduce, } from '@graphql-tools/utils';
+import { BoxedPromiseOrValue } from './BoxedPromiseOrValue.js';
+import { buildFieldPlan } from './buildFieldPlan.js';
 import { coerceError } from './coerceError.js';
-import { flattenAsyncIterable } from './flattenAsyncIterable.js';
+import { collectSubfields as _collectSubfields, collectFields, } from './collectFields.js';
+import { buildIncrementalResponse } from './IncrementalPublisher.js';
 import { invariant } from './invariant.js';
 import { promiseForObject } from './promiseForObject.js';
 import { getVariableValues } from './values.js';
@@ -11,7 +13,7 @@ import { getVariableValues } from './values.js';
  * type. Memoizing ensures the subfields are not repeatedly calculated, which
  * saves overhead when resolving lists of values.
  */
-const collectSubfields = memoize3((exeContext, returnType, fieldNodes) => _collectSubfields(exeContext.schema, exeContext.fragments, exeContext.variableValues, returnType, fieldNodes));
+const collectSubfields = memoize3((exeContext, returnType, fieldGroup) => _collectSubfields(exeContext.schema, exeContext.fragments, exeContext.variableValues, exeContext.operation, returnType, fieldGroup));
 /**
  * Implements the "Executing requests" section of the GraphQL specification,
  * including `@defer` and `@stream` as proposed in
@@ -45,45 +47,7 @@ export function execute(args) {
             }),
         };
     }
-    return executeImpl(exeContext);
-}
-function executeImpl(exeContext) {
-    if (exeContext.signal?.aborted) {
-        throw exeContext.signal.reason;
-    }
-    // Return a Promise that will eventually resolve to the data described by
-    // The "Response" section of the GraphQL specification.
-    //
-    // If errors are encountered while executing a GraphQL field, only that
-    // field and its descendants will be omitted, and sibling fields will still
-    // be executed. An execution which encounters errors will still result in a
-    // resolved Promise.
-    //
-    // Errors from sub-fields of a NonNull type may propagate to the top level,
-    // at which point we still log the error and null the parent field, which
-    // in this case is the entire response.
-    const result = new ValueOrPromise(() => executeOperation(exeContext))
-        .then(data => {
-        const initialResult = buildResponse(data, exeContext.errors);
-        if (exeContext.subsequentPayloads.size > 0) {
-            return {
-                initialResult: {
-                    ...initialResult,
-                    hasNext: true,
-                },
-                subsequentResults: yieldSubsequentPayloads(exeContext),
-            };
-        }
-        return initialResult;
-    }, (error) => {
-        if (exeContext.signal?.aborted) {
-            throw exeContext.signal.reason;
-        }
-        exeContext.errors.push(error);
-        return buildResponse(null, exeContext.errors);
-    })
-        .resolve();
-    return result;
+    return executeOperation(exeContext);
 }
 /**
  * Also implements the "Executing requests" section of the GraphQL specification.
@@ -102,8 +66,49 @@ export function executeSync(args) {
  * Given a completed execution context and data, build the `{ errors, data }`
  * response defined by the "Response" section of the GraphQL specification.
  */
-function buildResponse(data, errors) {
-    return errors.length === 0 ? { data } : { errors, data };
+function buildDataResponse(exeContext, data) {
+    const { errors, incrementalDataRecords } = exeContext;
+    if (incrementalDataRecords === undefined) {
+        return buildSingleResult(data, errors);
+    }
+    if (errors === undefined) {
+        return buildIncrementalResponse(exeContext, data, undefined, incrementalDataRecords);
+    }
+    const filteredIncrementalDataRecords = filterIncrementalDataRecords(undefined, errors, incrementalDataRecords);
+    if (filteredIncrementalDataRecords.length === 0) {
+        return buildSingleResult(data, errors);
+    }
+    return buildIncrementalResponse(exeContext, data, Array.from(errors.values()), filteredIncrementalDataRecords);
+}
+function buildSingleResult(data, errors) {
+    return errors !== undefined ? { errors: Array.from(errors.values()), data } : { data };
+}
+function filterIncrementalDataRecords(initialPath, errors, incrementalDataRecords) {
+    const filteredIncrementalDataRecords = [];
+    for (const incrementalDataRecord of incrementalDataRecords) {
+        let currentPath = incrementalDataRecord.path;
+        if (errors.has(currentPath)) {
+            continue;
+        }
+        const paths = [currentPath];
+        let filtered = false;
+        while (currentPath !== initialPath) {
+            // Because currentPath leads to initialPath or is undefined, and the
+            // loop will exit if initialPath is undefined, currentPath must be
+            // defined.
+            // TODO: Consider, however, adding an invariant.
+            currentPath = currentPath.prev;
+            if (errors.has(currentPath)) {
+                filtered = true;
+                break;
+            }
+            paths.push(currentPath);
+        }
+        if (!filtered) {
+            filteredIncrementalDataRecords.push(incrementalDataRecord);
+        }
+    }
+    return filteredIncrementalDataRecords;
 }
 /**
  * Essential assertions before executing to provide developer feedback for
@@ -137,7 +142,7 @@ export const getFragmentsFromDocument = memoize1(function getFragmentsFromDocume
  * @internal
  */
 export function buildExecutionContext(args) {
-    const { schema, document, rootValue, contextValue, variableValues: rawVariableValues, operationName, fieldResolver, typeResolver, subscribeFieldResolver, signal, } = args;
+    const { schema, document, rootValue, contextValue, variableValues: rawVariableValues, operationName, fieldResolver, typeResolver, subscribeFieldResolver, enableEarlyExecution, signal, } = args;
     // If the schema used for execution is invalid, throw an error.
     assertValidSchema(schema);
     const fragments = getFragmentsFromDocument(document);
@@ -186,78 +191,132 @@ export function buildExecutionContext(args) {
         fieldResolver: fieldResolver ?? defaultFieldResolver,
         typeResolver: typeResolver ?? defaultTypeResolver,
         subscribeFieldResolver: subscribeFieldResolver ?? defaultFieldResolver,
-        subsequentPayloads: new Set(),
-        errors: [],
+        enableEarlyExecution: enableEarlyExecution !== false,
         signal,
+        errors: undefined,
+        cancellableStreams: undefined,
+        incrementalDataRecords: undefined,
     };
 }
 function buildPerEventExecutionContext(exeContext, payload) {
     return {
         ...exeContext,
         rootValue: payload,
-        subsequentPayloads: new Set(),
-        errors: [],
+        errors: undefined,
     };
 }
 /**
  * Implements the "Executing operations" section of the spec.
  */
 function executeOperation(exeContext) {
-    const { operation, schema, fragments, variableValues, rootValue } = exeContext;
-    const rootType = getDefinedRootType(schema, operation.operation, [operation]);
-    if (rootType == null) {
-        createGraphQLError(`Schema is not configured to execute ${operation.operation} operation.`, {
-            nodes: operation,
-        });
+    if (exeContext.signal?.aborted) {
+        throw exeContext.signal.reason;
+    }
+    try {
+        const { operation, schema, fragments, variableValues, rootValue } = exeContext;
+        const rootType = getDefinedRootType(schema, operation.operation, [operation]);
+        if (rootType == null) {
+            createGraphQLError(`Schema is not configured to execute ${operation.operation} operation.`, {
+                nodes: operation,
+            });
+        }
+        const collectedFields = collectFields(schema, fragments, variableValues, rootType, operation);
+        let groupedFieldSet = collectedFields.groupedFieldSet;
+        const newDeferUsages = collectedFields.newDeferUsages;
+        let data;
+        if (newDeferUsages.length === 0) {
+            data = executeRootGroupedFieldSet(exeContext, operation.operation, rootType, rootValue, groupedFieldSet, undefined);
+        }
+        else {
+            const fieldPLan = buildFieldPlan(groupedFieldSet);
+            groupedFieldSet = fieldPLan.groupedFieldSet;
+            const newGroupedFieldSets = fieldPLan.newGroupedFieldSets;
+            const newDeferMap = addNewDeferredFragments(newDeferUsages, new Map());
+            data = executeRootGroupedFieldSet(exeContext, operation.operation, rootType, rootValue, groupedFieldSet, newDeferMap);
+            if (newGroupedFieldSets.size > 0) {
+                const newDeferredGroupedFieldSetRecords = executeDeferredGroupedFieldSets(exeContext, rootType, rootValue, undefined, undefined, newGroupedFieldSets, newDeferMap);
+                addIncrementalDataRecords(exeContext, newDeferredGroupedFieldSetRecords);
+            }
+        }
+        if (isPromise(data)) {
+            return data.then(resolved => buildDataResponse(exeContext, resolved), error => {
+                if (exeContext.signal?.aborted) {
+                    throw exeContext.signal.reason;
+                }
+                return {
+                    data: null,
+                    errors: withError(exeContext.errors, error),
+                };
+            });
+        }
+        return buildDataResponse(exeContext, data);
     }
-    const { fields: rootFields, patches } = collectFields(schema, fragments, variableValues, rootType, operation.selectionSet);
-    const path = undefined;
+    catch (error) {
+        if (exeContext.signal?.aborted) {
+            throw exeContext.signal.reason;
+        }
+        return { data: null, errors: withError(exeContext.errors, error) };
+    }
+}
+function executeRootGroupedFieldSet(exeContext, operation, rootType, rootValue, groupedFieldSet, deferMap) {
     let result;
-    if (operation.operation === 'mutation') {
-        result = executeFieldsSerially(exeContext, rootType, rootValue, path, rootFields);
+    if (operation === 'mutation') {
+        result = executeFieldsSerially(exeContext, rootType, rootValue, undefined, groupedFieldSet, undefined, deferMap);
     }
     else {
-        result = executeFields(exeContext, rootType, rootValue, path, rootFields);
-    }
-    for (const patch of patches) {
-        const { label, fields: patchFields } = patch;
-        executeDeferredFragment(exeContext, rootType, rootValue, patchFields, label, path);
+        result = executeFields(exeContext, rootType, rootValue, undefined, groupedFieldSet, undefined, deferMap);
     }
     return result;
 }
+function addIncrementalDataRecords(context, newIncrementalDataRecords) {
+    const incrementalDataRecords = context.incrementalDataRecords;
+    if (incrementalDataRecords === undefined) {
+        context.incrementalDataRecords = [...newIncrementalDataRecords];
+        return;
+    }
+    incrementalDataRecords.push(...newIncrementalDataRecords);
+}
+function withError(errors, error) {
+    return errors === undefined ? [error] : [...errors.values(), error];
+}
 /**
  * Implements the "Executing selection sets" section of the spec
  * for fields that must be executed serially.
  */
-function executeFieldsSerially(exeContext, parentType, sourceValue, path, fields) {
-    return promiseReduce(fields, (results, [responseName, fieldNodes]) => {
+function executeFieldsSerially(exeContext, parentType, sourceValue, path, groupedFieldSet, incrementalContext, deferMap) {
+    return promiseReduce(groupedFieldSet, (results, [responseName, fieldGroup]) => {
         const fieldPath = addPath(path, responseName, parentType.name);
         if (exeContext.signal?.aborted) {
             throw exeContext.signal.reason;
         }
-        return new ValueOrPromise(() => executeField(exeContext, parentType, sourceValue, fieldNodes, fieldPath)).then(result => {
-            if (result === undefined) {
-                return results;
-            }
-            results[responseName] = result;
+        const result = executeField(exeContext, parentType, sourceValue, fieldGroup, fieldPath, incrementalContext, deferMap);
+        if (result === undefined) {
             return results;
-        });
-    }, Object.create(null)).resolve();
+        }
+        if (isPromise(result)) {
+            return result.then(resolved => {
+                results[responseName] = resolved;
+                return results;
+            });
+        }
+        results[responseName] = result;
+        return results;
+    }, Object.create(null));
 }
 /**
  * Implements the "Executing selection sets" section of the spec
  * for fields that may be executed in parallel.
  */
-function executeFields(exeContext, parentType, sourceValue, path, fields, asyncPayloadRecord) {
+function executeFields(exeContext, parentType, sourceValue, path, groupedFieldSet, incrementalContext, deferMap) {
     const results = Object.create(null);
     let containsPromise = false;
     try {
-        for (const [responseName, fieldNodes] of fields) {
+        for (const [responseName, fieldGroup] of groupedFieldSet) {
             if (exeContext.signal?.aborted) {
                 throw exeContext.signal.reason;
             }
             const fieldPath = addPath(path, responseName, parentType.name);
-            const result = executeField(exeContext, parentType, sourceValue, fieldNodes, fieldPath, asyncPayloadRecord);
+            const result = executeField(exeContext, parentType, sourceValue, fieldGroup, fieldPath, incrementalContext, deferMap);
             if (result !== undefined) {
                 results[responseName] = result;
                 if (isPromise(result)) {
@@ -275,7 +334,7 @@ function executeFields(exeContext, parentType, sourceValue, path, fields, asyncP
         }
         throw error;
     }
-    // If there are no promises, we can just return the object
+    // If there are no promises, we can just return the object and any incrementalDataRecords
     if (!containsPromise) {
         return results;
     }
@@ -284,58 +343,51 @@ function executeFields(exeContext, parentType, sourceValue, path, fields, asyncP
     // same map, but with any promises replaced with the values they resolved to.
     return promiseForObject(results, exeContext.signal);
 }
+function toNodes(fieldGroup) {
+    return fieldGroup.map(fieldDetails => fieldDetails.node);
+}
 /**
  * Implements the "Executing fields" section of the spec
  * In particular, this function figures out the value that the field returns by
  * calling its resolve function, then calls completeValue to complete promises,
  * serialize scalars, or execute the sub-selection-set for objects.
  */
-function executeField(exeContext, parentType, source, fieldNodes, path, asyncPayloadRecord) {
-    const errors = asyncPayloadRecord?.errors ?? exeContext.errors;
-    const fieldDef = getFieldDef(exeContext.schema, parentType, fieldNodes[0]);
+function executeField(exeContext, parentType, source, fieldGroup, path, incrementalContext, deferMap) {
+    const fieldDef = getFieldDef(exeContext.schema, parentType, fieldGroup[0].node);
     if (!fieldDef) {
         return;
     }
     const returnType = fieldDef.type;
     const resolveFn = fieldDef.resolve ?? exeContext.fieldResolver;
-    const info = buildResolveInfo(exeContext, fieldDef, fieldNodes, parentType, path);
+    const info = buildResolveInfo(exeContext, fieldDef, toNodes(fieldGroup), parentType, path);
     // Get the resolve function, regardless of if its result is normal or abrupt (error).
     try {
         // Build a JS object of arguments from the field.arguments AST, using the
         // variables scope to fulfill any variable references.
         // TODO: find a way to memoize, in case this field is within a List type.
-        const args = getArgumentValues(fieldDef, fieldNodes[0], exeContext.variableValues);
+        const args = getArgumentValues(fieldDef, fieldGroup[0].node, exeContext.variableValues);
         // The resolve function's optional third argument is a context value that
         // is provided to every resolve function within an execution. It is commonly
         // used to represent an authenticated user, or request-specific caches.
         const contextValue = exeContext.contextValue;
         const result = resolveFn(source, args, contextValue, info);
-        let completed;
         if (isPromise(result)) {
-            completed = result.then(resolved => completeValue(exeContext, returnType, fieldNodes, info, path, resolved, asyncPayloadRecord));
-        }
-        else {
-            completed = completeValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord);
+            return completePromisedValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap);
         }
+        const completed = completeValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap);
         if (isPromise(completed)) {
             // Note: we don't rely on a `catch` method, but we do expect "thenable"
             // to take a second callback for the error case.
             return completed.then(undefined, rawError => {
-                rawError = coerceError(rawError);
-                const error = locatedError(rawError, fieldNodes, pathToArray(path));
-                const handledError = handleFieldError(error, returnType, errors);
-                filterSubsequentPayloads(exeContext, path, asyncPayloadRecord);
-                return handledError;
+                handleFieldError(rawError, exeContext, returnType, fieldGroup, path, incrementalContext);
+                return null;
             });
         }
         return completed;
     }
     catch (rawError) {
-        const coercedError = coerceError(rawError);
-        const error = locatedError(coercedError, fieldNodes, pathToArray(path));
-        const handledError = handleFieldError(error, returnType, errors);
-        filterSubsequentPayloads(exeContext, path, asyncPayloadRecord);
-        return handledError;
+        handleFieldError(rawError, exeContext, returnType, fieldGroup, path, incrementalContext);
+        return null;
     }
 }
 /**
@@ -358,7 +410,8 @@ export function buildResolveInfo(exeContext, fieldDef, fieldNodes, parentType, p
         variableValues: exeContext.variableValues,
     };
 }
-function handleFieldError(error, returnType, errors) {
+function handleFieldError(rawError, exeContext, returnType, fieldGroup, path, incrementalContext) {
+    const error = locatedError(coerceError(rawError), toNodes(fieldGroup), pathToArray(path));
     // If the field type is non-nullable, then it is resolved without any
     // protection from errors, however it still properly locates the error.
     if (isNonNullType(returnType)) {
@@ -366,8 +419,13 @@ function handleFieldError(error, returnType, errors) {
     }
     // Otherwise, error protection is applied, logging the error and resolving
     // a null value for this field if one is encountered.
-    errors.push(error);
-    return null;
+    const context = incrementalContext ?? exeContext;
+    let errors = context.errors;
+    if (errors === undefined) {
+        errors = new Map();
+        context.errors = errors;
+    }
+    errors.set(path, error);
 }
 /**
  * Implements the instructions for completeValue as defined in the
@@ -390,7 +448,7 @@ function handleFieldError(error, returnType, errors) {
  * Otherwise, the field type expects a sub-selection set, and will complete the
  * value by executing all sub-selections.
  */
-function completeValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord) {
+function completeValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap) {
     // If result is an Error, throw a located error.
     if (result instanceof Error) {
         throw result;
@@ -398,8 +456,8 @@ function completeValue(exeContext, returnType, fieldNodes, info, path, result, a
     // If field type is NonNull, complete for inner type, and throw field error
     // if result is null.
     if (isNonNullType(returnType)) {
-        const completed = completeValue(exeContext, returnType.ofType, fieldNodes, info, path, result, asyncPayloadRecord);
-        if (completed === null) {
+        const completed = completeValue(exeContext, returnType.ofType, fieldGroup, info, path, result, incrementalContext, deferMap);
+        if (completed == null) {
             throw new Error(`Cannot return null for non-nullable field ${info.parentType.name}.${info.fieldName}.`);
         }
         return completed;
@@ -410,7 +468,7 @@ function completeValue(exeContext, returnType, fieldNodes, info, path, result, a
     }
     // If field type is List, complete each item in the list with the inner type
     if (isListType(returnType)) {
-        return completeListValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord);
+        return completeListValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap);
     }
     // If field type is a leaf type, Scalar or Enum, serialize to a valid value,
     // returning null if serialization is not possible.
@@ -420,29 +478,48 @@ function completeValue(exeContext, returnType, fieldNodes, info, path, result, a
     // If field type is an abstract type, Interface or Union, determine the
     // runtime Object type and complete for that type.
     if (isAbstractType(returnType)) {
-        return completeAbstractValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord);
+        return completeAbstractValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap);
     }
     // If field type is Object, execute and complete all sub-selections.
     if (isObjectType(returnType)) {
-        return completeObjectValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord);
+        return completeObjectValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap);
     }
     /* c8 ignore next 6 */
     // Not reachable, all possible output types have been considered.
-    console.assert(false, 'Cannot complete value of unexpected output type: ' + inspect(returnType));
+    invariant(false, 'Cannot complete value of unexpected output type: ' + inspect(returnType));
+}
+async function completePromisedValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap) {
+    try {
+        const resolved = await result;
+        let completed = completeValue(exeContext, returnType, fieldGroup, info, path, resolved, incrementalContext, deferMap);
+        if (isPromise(completed)) {
+            completed = await completed;
+        }
+        return completed;
+    }
+    catch (rawError) {
+        handleFieldError(rawError, exeContext, returnType, fieldGroup, path, incrementalContext);
+        return null;
+    }
 }
 /**
- * Returns an object containing the `@stream` arguments if a field should be
+ * Returns an object containing info for streaming if a field should be
  * streamed based on the experimental flag, stream directive present and
  * not disabled by the "if" argument.
  */
-function getStreamValues(exeContext, fieldNodes, path) {
+function getStreamUsage(exeContext, fieldGroup, path) {
     // do not stream inner lists of multi-dimensional lists
     if (typeof path.key === 'number') {
         return;
     }
+    // TODO: add test for this case (a streamed list nested under a list).
+    /* c8 ignore next 7 */
+    if (fieldGroup._streamUsage !== undefined) {
+        return fieldGroup._streamUsage;
+    }
     // validation only allows equivalent streams on multiple fields, so it is
     // safe to only check the first fieldNode for the stream directive
-    const stream = getDirectiveValues(GraphQLStreamDirective, fieldNodes[0], exeContext.variableValues);
+    const stream = getDirectiveValues(GraphQLStreamDirective, fieldGroup[0].node, exeContext.variableValues);
     if (!stream) {
         return;
     }
@@ -451,84 +528,142 @@ function getStreamValues(exeContext, fieldNodes, path) {
     }
     invariant(typeof stream['initialCount'] === 'number', 'initialCount must be a number');
     invariant(stream['initialCount'] >= 0, 'initialCount must be a positive integer');
-    return {
+    invariant(exeContext.operation.operation !== 'subscription', '`@stream` directive not supported on subscription operations. Disable `@stream` by setting the `if` argument to `false`.');
+    const streamedFieldGroup = fieldGroup.map(fieldDetails => ({
+        node: fieldDetails.node,
+        deferUsage: undefined,
+    }));
+    const streamUsage = {
         initialCount: stream['initialCount'],
         label: typeof stream['label'] === 'string' ? stream['label'] : undefined,
+        fieldGroup: streamedFieldGroup,
     };
+    fieldGroup._streamUsage = streamUsage;
+    return streamUsage;
 }
 /**
  * Complete a async iterator value by completing the result and calling
  * recursively until all the results are completed.
  */
-async function completeAsyncIteratorValue(exeContext, itemType, fieldNodes, info, path, iterator, asyncPayloadRecord) {
+async function completeAsyncIteratorValue(exeContext, itemType, fieldGroup, info, path, asyncIterator, incrementalContext, deferMap) {
     exeContext.signal?.addEventListener('abort', () => {
-        iterator.return?.();
+        asyncIterator.return?.();
     });
-    const errors = asyncPayloadRecord?.errors ?? exeContext.errors;
-    const stream = getStreamValues(exeContext, fieldNodes, path);
     let containsPromise = false;
     const completedResults = [];
     let index = 0;
+    const streamUsage = getStreamUsage(exeContext, fieldGroup, path);
     while (true) {
-        if (stream && typeof stream.initialCount === 'number' && index >= stream.initialCount) {
-            executeStreamIterator(index, iterator, exeContext, fieldNodes, info, itemType, path, stream.label, asyncPayloadRecord);
+        if (streamUsage && index >= streamUsage.initialCount) {
+            const streamItemQueue = buildAsyncStreamItemQueue(index, path, asyncIterator, exeContext, streamUsage.fieldGroup, info, itemType);
+            const returnFn = asyncIterator.return;
+            let streamRecord;
+            if (returnFn === undefined) {
+                streamRecord = {
+                    label: streamUsage.label,
+                    path,
+                    streamItemQueue,
+                };
+            }
+            else {
+                streamRecord = {
+                    label: streamUsage.label,
+                    path,
+                    streamItemQueue,
+                    earlyReturn: returnFn.bind(asyncIterator),
+                };
+                if (exeContext.cancellableStreams === undefined) {
+                    exeContext.cancellableStreams = new Set();
+                }
+                exeContext.cancellableStreams.add(streamRecord);
+            }
+            const context = incrementalContext ?? exeContext;
+            addIncrementalDataRecords(context, [streamRecord]);
             break;
         }
         const itemPath = addPath(path, index, undefined);
         let iteration;
         try {
-            iteration = await iterator.next();
-            if (iteration.done) {
-                break;
-            }
+            iteration = await asyncIterator.next();
         }
         catch (rawError) {
-            const coercedError = coerceError(rawError);
-            const error = locatedError(coercedError, fieldNodes, pathToArray(itemPath));
-            completedResults.push(handleFieldError(error, itemType, errors));
+            throw locatedError(coerceError(rawError), toNodes(fieldGroup), pathToArray(path));
+        }
+        // TODO: add test case for stream returning done before initialCount
+        /* c8 ignore next 3 */
+        if (iteration.done) {
             break;
         }
-        if (completeListItemValue(iteration.value, completedResults, errors, exeContext, itemType, fieldNodes, info, itemPath, asyncPayloadRecord)) {
+        const item = iteration.value;
+        // TODO: add tests for stream backed by asyncIterator that returns a promise
+        /* c8 ignore start */
+        if (isPromise(item)) {
+            completedResults.push(completePromisedListItemValue(item, exeContext, itemType, fieldGroup, info, itemPath, incrementalContext, deferMap));
+            containsPromise = true;
+        }
+        else if (
+        /* c8 ignore stop */
+        completeListItemValue(item, completedResults, exeContext, itemType, fieldGroup, info, itemPath, incrementalContext, deferMap)
+        // TODO: add tests for stream backed by asyncIterator that completes to a promise
+        /* c8 ignore start */
+        ) {
             containsPromise = true;
         }
-        index += 1;
+        /* c8 ignore stop */
+        index++;
     }
-    return containsPromise ? Promise.all(completedResults) : completedResults;
+    return containsPromise
+        ? /* c8 ignore start */ Promise.all(completedResults)
+        : /* c8 ignore stop */ completedResults;
 }
 /**
  * Complete a list value by completing each item in the list with the
  * inner type
  */
-function completeListValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord) {
+function completeListValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap) {
     const itemType = returnType.ofType;
-    const errors = asyncPayloadRecord?.errors ?? exeContext.errors;
     if (isAsyncIterable(result)) {
-        const iterator = result[Symbol.asyncIterator]();
-        return completeAsyncIteratorValue(exeContext, itemType, fieldNodes, info, path, iterator, asyncPayloadRecord);
+        const asyncIterator = result[Symbol.asyncIterator]();
+        return completeAsyncIteratorValue(exeContext, itemType, fieldGroup, info, path, asyncIterator, incrementalContext, deferMap);
     }
     if (!isIterableObject(result)) {
         throw createGraphQLError(`Expected Iterable, but did not find one for field "${info.parentType.name}.${info.fieldName}".`);
     }
-    const stream = getStreamValues(exeContext, fieldNodes, path);
+    return completeIterableValue(exeContext, itemType, fieldGroup, info, path, result, incrementalContext, deferMap);
+}
+function completeIterableValue(exeContext, itemType, fieldGroup, info, path, items, incrementalContext, deferMap) {
     // This is specified as a simple map, however we're optimizing the path
     // where the list contains no Promises by avoiding creating another Promise.
     let containsPromise = false;
-    let previousAsyncPayloadRecord = asyncPayloadRecord;
     const completedResults = [];
     let index = 0;
-    for (const item of result) {
+    const streamUsage = getStreamUsage(exeContext, fieldGroup, path);
+    const iterator = items[Symbol.iterator]();
+    let iteration = iterator.next();
+    while (!iteration.done) {
+        const item = iteration.value;
+        if (streamUsage && index >= streamUsage.initialCount) {
+            const streamRecord = {
+                label: streamUsage.label,
+                path,
+                streamItemQueue: buildSyncStreamItemQueue(item, index, path, iterator, exeContext, streamUsage.fieldGroup, info, itemType),
+            };
+            const context = incrementalContext ?? exeContext;
+            addIncrementalDataRecords(context, [streamRecord]);
+            break;
+        }
         // No need to modify the info object containing the path,
         // since from here on it is not ever accessed by resolver functions.
         const itemPath = addPath(path, index, undefined);
-        if (stream && typeof stream.initialCount === 'number' && index >= stream.initialCount) {
-            previousAsyncPayloadRecord = executeStreamField(path, itemPath, item, exeContext, fieldNodes, info, itemType, stream.label, previousAsyncPayloadRecord);
-            index++;
-            continue;
+        if (isPromise(item)) {
+            completedResults.push(completePromisedListItemValue(item, exeContext, itemType, fieldGroup, info, itemPath, incrementalContext, deferMap));
+            containsPromise = true;
         }
-        if (completeListItemValue(item, completedResults, errors, exeContext, itemType, fieldNodes, info, itemPath, asyncPayloadRecord)) {
+        else if (completeListItemValue(item, completedResults, exeContext, itemType, fieldGroup, info, itemPath, incrementalContext, deferMap)) {
             containsPromise = true;
         }
         index++;
+        iteration = iterator.next();
     }
     return containsPromise ? Promise.all(completedResults) : completedResults;
 }
@@ -537,38 +672,40 @@ function completeListValue(exeContext, returnType, fieldNodes, info, path, resul
  *
  * Returns true if the value is a Promise.
  */
-function completeListItemValue(item, completedResults, errors, exeContext, itemType, fieldNodes, info, itemPath, asyncPayloadRecord) {
+function completeListItemValue(item, completedResults, exeContext, itemType, fieldGroup, info, itemPath, incrementalContext, deferMap) {
     try {
-        let completedItem;
-        if (isPromise(item)) {
-            completedItem = item.then(resolved => completeValue(exeContext, itemType, fieldNodes, info, itemPath, resolved, asyncPayloadRecord));
-        }
-        else {
-            completedItem = completeValue(exeContext, itemType, fieldNodes, info, itemPath, item, asyncPayloadRecord);
-        }
+        const completedItem = completeValue(exeContext, itemType, fieldGroup, info, itemPath, item, incrementalContext, deferMap);
         if (isPromise(completedItem)) {
             // Note: we don't rely on a `catch` method, but we do expect "thenable"
             // to take a second callback for the error case.
             completedResults.push(completedItem.then(undefined, rawError => {
-                rawError = coerceError(rawError);
-                const error = locatedError(rawError, fieldNodes, pathToArray(itemPath));
-                const handledError = handleFieldError(error, itemType, errors);
-                filterSubsequentPayloads(exeContext, itemPath, asyncPayloadRecord);
-                return handledError;
+                handleFieldError(rawError, exeContext, itemType, fieldGroup, itemPath, incrementalContext);
+                return null;
             }));
             return true;
         }
         completedResults.push(completedItem);
     }
     catch (rawError) {
-        const coercedError = coerceError(rawError);
-        const error = locatedError(coercedError, fieldNodes, pathToArray(itemPath));
-        const handledError = handleFieldError(error, itemType, errors);
-        filterSubsequentPayloads(exeContext, itemPath, asyncPayloadRecord);
-        completedResults.push(handledError);
+        handleFieldError(rawError, exeContext, itemType, fieldGroup, itemPath, incrementalContext);
+        completedResults.push(null);
     }
     return false;
 }
+async function completePromisedListItemValue(item, exeContext, itemType, fieldGroup, info, itemPath, incrementalContext, deferMap) {
+    try {
+        const resolved = await item;
+        let completed = completeValue(exeContext, itemType, fieldGroup, info, itemPath, resolved, incrementalContext, deferMap);
+        if (isPromise(completed)) {
+            completed = await completed;
+        }
+        return completed;
+    }
+    catch (rawError) {
+        handleFieldError(rawError, exeContext, itemType, fieldGroup, itemPath, incrementalContext);
+        return null;
+    }
+}
 /**
  * Complete a Scalar or Enum by serializing to a valid value, returning
  * null if serialization is not possible.
@@ -598,18 +735,18 @@ function completeLeafValue(returnType, result) {
  * Complete a value of an abstract type by determining the runtime object type
  * of that value, then complete the value for that type.
  */
-function completeAbstractValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord) {
+function completeAbstractValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap) {
     const resolveTypeFn = returnType.resolveType ?? exeContext.typeResolver;
     const contextValue = exeContext.contextValue;
     const runtimeType = resolveTypeFn(result, contextValue, info, returnType);
     if (isPromise(runtimeType)) {
-        return runtimeType.then(resolvedRuntimeType => completeObjectValue(exeContext, ensureValidRuntimeType(resolvedRuntimeType, exeContext, returnType, fieldNodes, info, result), fieldNodes, info, path, result, asyncPayloadRecord));
+        return runtimeType.then(resolvedRuntimeType => completeObjectValue(exeContext, ensureValidRuntimeType(resolvedRuntimeType, exeContext, returnType, fieldGroup, info, result), fieldGroup, info, path, result, incrementalContext, deferMap));
     }
-    return completeObjectValue(exeContext, ensureValidRuntimeType(runtimeType, exeContext, returnType, fieldNodes, info, result), fieldNodes, info, path, result, asyncPayloadRecord);
+    return completeObjectValue(exeContext, ensureValidRuntimeType(runtimeType, exeContext, returnType, fieldGroup, info, result), fieldGroup, info, path, result, incrementalContext, deferMap);
 }
-function ensureValidRuntimeType(runtimeTypeName, exeContext, returnType, fieldNodes, info, result) {
+function ensureValidRuntimeType(runtimeTypeName, exeContext, returnType, fieldGroup, info, result) {
     if (runtimeTypeName == null) {
-        throw createGraphQLError(`Abstract type "${returnType.name}" must resolve to an Object type at runtime for field "${info.parentType.name}.${info.fieldName}". Either the "${returnType.name}" type should provide a "resolveType" function or each possible type should provide an "isTypeOf" function.`, { nodes: fieldNodes });
+        throw createGraphQLError(`Abstract type "${returnType.name}" must resolve to an Object type at runtime for field "${info.parentType.name}.${info.fieldName}". Either the "${returnType.name}" type should provide a "resolveType" function or each possible type should provide an "isTypeOf" function.`, { nodes: toNodes(fieldGroup) });
     }
     // releases before 16.0.0 supported returning `GraphQLObjectType` from `resolveType`
     // TODO: remove in 17.0.0 release
@@ -622,20 +759,20 @@ function ensureValidRuntimeType(runtimeTypeName, exeContext, returnType, fieldNo
     }
     const runtimeType = exeContext.schema.getType(runtimeTypeName);
     if (runtimeType == null) {
-        throw createGraphQLError(`Abstract type "${returnType.name}" was resolved to a type "${runtimeTypeName}" that does not exist inside the schema.`, { nodes: fieldNodes });
+        throw createGraphQLError(`Abstract type "${returnType.name}" was resolved to a type "${runtimeTypeName}" that does not exist inside the schema.`, { nodes: toNodes(fieldGroup) });
     }
     if (!isObjectType(runtimeType)) {
-        throw createGraphQLError(`Abstract type "${returnType.name}" was resolved to a non-object type "${runtimeTypeName}".`, { nodes: fieldNodes });
+        throw createGraphQLError(`Abstract type "${returnType.name}" was resolved to a non-object type "${runtimeTypeName}".`, { nodes: toNodes(fieldGroup) });
     }
     if (!exeContext.schema.isSubType(returnType, runtimeType)) {
-        throw createGraphQLError(`Runtime Object type "${runtimeType.name}" is not a possible type for "${returnType.name}".`, { nodes: fieldNodes });
+        throw createGraphQLError(`Runtime Object type "${runtimeType.name}" is not a possible type for "${returnType.name}".`, { nodes: toNodes(fieldGroup) });
     }
     return runtimeType;
 }
 /**
  * Complete an Object value by executing all sub-selections.
  */
-function completeObjectValue(exeContext, returnType, fieldNodes, info, path, result, asyncPayloadRecord) {
+function completeObjectValue(exeContext, returnType, fieldGroup, info, path, result, incrementalContext, deferMap) {
     // If there is an isTypeOf predicate function, call it with the
     // current result. If isTypeOf returns false, then raise an error rather
     // than continuing execution.
@@ -644,32 +781,70 @@ function completeObjectValue(exeContext, returnType, fieldNodes, info, path, res
         if (isPromise(isTypeOf)) {
             return isTypeOf.then(resolvedIsTypeOf => {
                 if (!resolvedIsTypeOf) {
-                    throw invalidReturnTypeError(returnType, result, fieldNodes);
+                    throw invalidReturnTypeError(returnType, result, fieldGroup);
                 }
-                return collectAndExecuteSubfields(exeContext, returnType, fieldNodes, path, result, asyncPayloadRecord);
+                return collectAndExecuteSubfields(exeContext, returnType, fieldGroup, path, result, incrementalContext, deferMap);
             });
         }
         if (!isTypeOf) {
-            throw invalidReturnTypeError(returnType, result, fieldNodes);
+            throw invalidReturnTypeError(returnType, result, fieldGroup);
         }
     }
-    return collectAndExecuteSubfields(exeContext, returnType, fieldNodes, path, result, asyncPayloadRecord);
+    return collectAndExecuteSubfields(exeContext, returnType, fieldGroup, path, result, incrementalContext, deferMap);
 }
-function invalidReturnTypeError(returnType, result, fieldNodes) {
-    return createGraphQLError(`Expected value of type "${returnType.name}" but got: ${inspect(result)}.`, {
-        nodes: fieldNodes,
-    });
+function invalidReturnTypeError(returnType, result, fieldGroup) {
+    return createGraphQLError(`Expected value of type "${returnType.name}" but got: ${inspect(result)}.`, { nodes: toNodes(fieldGroup) });
+}
+function addNewDeferredFragments(newDeferUsages, newDeferMap, path) {
+    // For each new deferUsage object:
+    for (const newDeferUsage of newDeferUsages) {
+        const parentDeferUsage = newDeferUsage.parentDeferUsage;
+        const parent = parentDeferUsage === undefined
+            ? undefined
+            : deferredFragmentRecordFromDeferUsage(parentDeferUsage, newDeferMap);
+        // Instantiate the new record.
+        const deferredFragmentRecord = {
+            path,
+            label: newDeferUsage.label,
+            parent,
+        };
+        // Update the map.
+        newDeferMap.set(newDeferUsage, deferredFragmentRecord);
+    }
+    return newDeferMap;
 }
-function collectAndExecuteSubfields(exeContext, returnType, fieldNodes, path, result, asyncPayloadRecord) {
+function deferredFragmentRecordFromDeferUsage(deferUsage, deferMap) {
+    return deferMap.get(deferUsage);
+}
+function collectAndExecuteSubfields(exeContext, returnType, fieldGroup, path, result, incrementalContext, deferMap) {
     // Collect sub-fields to execute to complete this value.
-    const { fields: subFieldNodes, patches: subPatches } = collectSubfields(exeContext, returnType, fieldNodes);
-    const subFields = executeFields(exeContext, returnType, result, path, subFieldNodes, asyncPayloadRecord);
-    for (const subPatch of subPatches) {
-        const { label, fields: subPatchFieldNodes } = subPatch;
-        executeDeferredFragment(exeContext, returnType, result, subPatchFieldNodes, label, path, asyncPayloadRecord);
+    const collectedSubfields = collectSubfields(exeContext, returnType, fieldGroup);
+    let groupedFieldSet = collectedSubfields.groupedFieldSet;
+    const newDeferUsages = collectedSubfields.newDeferUsages;
+    if (deferMap === undefined && newDeferUsages.length === 0) {
+        return executeFields(exeContext, returnType, result, path, groupedFieldSet, incrementalContext, undefined);
+    }
+    const subFieldPlan = buildSubFieldPlan(groupedFieldSet, incrementalContext?.deferUsageSet);
+    groupedFieldSet = subFieldPlan.groupedFieldSet;
+    const newGroupedFieldSets = subFieldPlan.newGroupedFieldSets;
+    const newDeferMap = addNewDeferredFragments(newDeferUsages, new Map(deferMap), path);
+    const subFields = executeFields(exeContext, returnType, result, path, groupedFieldSet, incrementalContext, newDeferMap);
+    if (newGroupedFieldSets.size > 0) {
+        const newDeferredGroupedFieldSetRecords = executeDeferredGroupedFieldSets(exeContext, returnType, result, path, incrementalContext?.deferUsageSet, newGroupedFieldSets, newDeferMap);
+        const context = incrementalContext ?? exeContext;
+        addIncrementalDataRecords(context, newDeferredGroupedFieldSetRecords);
     }
     return subFields;
 }
+function buildSubFieldPlan(originalGroupedFieldSet, deferUsageSet) {
+    let fieldPlan = originalGroupedFieldSet._fieldPlan;
+    if (fieldPlan !== undefined) {
+        return fieldPlan;
+    }
+    fieldPlan = buildFieldPlan(originalGroupedFieldSet, deferUsageSet);
+    originalGroupedFieldSet._fieldPlan = fieldPlan;
+    return fieldPlan;
+}
 /**
  * If a resolveType function is not given, then a default resolve behavior is
  * used which attempts two strategies:
@@ -820,14 +995,6 @@ export function flattenIncrementalResults(incrementalResults) {
         },
     };
 }
-async function* ensureAsyncIterable(someExecutionResult) {
-    if ('initialResult' in someExecutionResult) {
-        yield* flattenIncrementalResults(someExecutionResult);
-    }
-    else {
-        yield someExecutionResult;
-    }
-}
 function mapSourceToResponse(exeContext, resultOrStream) {
     if (!isAsyncIterable(resultOrStream)) {
         return resultOrStream;
@@ -838,13 +1005,13 @@ function mapSourceToResponse(exeContext, resultOrStream) {
     // the GraphQL specification. The `execute` function provides the
     // "ExecuteSubscriptionEvent" algorithm, as it is nearly identical to the
     // "ExecuteQuery" algorithm, for which `execute` is also used.
-    return flattenAsyncIterable(mapAsyncIterator(resultOrStream[Symbol.asyncIterator](), async (payload) => ensureAsyncIterable(await executeImpl(buildPerEventExecutionContext(exeContext, payload))), (error) => {
+    return mapAsyncIterator(resultOrStream[Symbol.asyncIterator](), (payload) => executeOperation(buildPerEventExecutionContext(exeContext, payload)), (error) => {
         const wrappedError = createGraphQLError(error.message, {
             originalError: error,
             nodes: [exeContext.operation],
         });
         throw wrappedError;
-    }));
+    });
 }
 function createSourceEventStreamImpl(exeContext) {
     try {
@@ -866,23 +1033,24 @@ function executeSubscription(exeContext) {
             nodes: operation,
         });
     }
-    const { fields: rootFields } = collectFields(schema, fragments, variableValues, rootType, operation.selectionSet);
-    const [responseName, fieldNodes] = [...rootFields.entries()][0];
-    const fieldName = fieldNodes[0].name.value;
-    const fieldDef = getFieldDef(schema, rootType, fieldNodes[0]);
+    const { groupedFieldSet } = collectFields(schema, fragments, variableValues, rootType, operation);
+    const firstRootField = [...groupedFieldSet.entries()][0];
+    const [responseName, fieldGroup] = firstRootField;
+    const fieldName = fieldGroup[0].node.name.value;
+    const fieldDef = getFieldDef(schema, rootType, fieldGroup[0].node);
     if (!fieldDef) {
         throw createGraphQLError(`The subscription field "${fieldName}" is not defined.`, {
-            nodes: fieldNodes,
+            nodes: toNodes(fieldGroup),
         });
     }
     const path = addPath(undefined, responseName, rootType.name);
-    const info = buildResolveInfo(exeContext, fieldDef, fieldNodes, rootType, path);
+    const info = buildResolveInfo(exeContext, fieldDef, toNodes(fieldGroup), rootType, path);
     try {
         // Implements the "ResolveFieldEventStream" algorithm from GraphQL specification.
         // It differs from "ResolveFieldValue" due to providing a different `resolveFn`.
         // Build a JS object of arguments from the field.arguments AST, using the
         // variables scope to fulfill any variable references.
-        const args = getArgumentValues(fieldDef, fieldNodes[0], variableValues);
+        const args = getArgumentValues(fieldDef, fieldGroup[0].node, variableValues);
         // The resolve function's optional third argument is a context value that
         // is provided to every resolve function within an execution. It is commonly
         // used to represent an authenticated user, or request-specific caches.
@@ -893,13 +1061,13 @@ function executeSubscription(exeContext) {
         const result = resolveFn(rootValue, args, contextValue, info);
         if (isPromise(result)) {
             return result.then(assertEventStream).then(undefined, error => {
-                throw locatedError(error, fieldNodes, pathToArray(path));
+                throw locatedError(error, toNodes(fieldGroup), pathToArray(path));
             });
         }
         return assertEventStream(result, exeContext.signal);
     }
     catch (error) {
-        throw locatedError(error, fieldNodes, pathToArray(path));
+        throw locatedError(error, toNodes(fieldGroup), pathToArray(path));
     }
 }
 function assertEventStream(result, signal) {
@@ -920,346 +1088,213 @@ function assertEventStream(result, signal) {
         },
     };
 }
-function executeDeferredFragment(exeContext, parentType, sourceValue, fields, label, path, parentContext) {
-    const asyncPayloadRecord = new DeferredFragmentRecord({
-        label,
-        path,
-        parentContext,
-        exeContext,
-    });
-    let promiseOrData;
-    try {
-        promiseOrData = executeFields(exeContext, parentType, sourceValue, path, fields, asyncPayloadRecord);
-        if (isPromise(promiseOrData)) {
-            promiseOrData = promiseOrData.then(null, e => {
-                asyncPayloadRecord.errors.push(e);
-                return null;
-            });
-        }
-    }
-    catch (e) {
-        asyncPayloadRecord.errors.push(e);
-        promiseOrData = null;
-    }
-    asyncPayloadRecord.addData(promiseOrData);
+function executeDeferredGroupedFieldSets(exeContext, parentType, sourceValue, path, parentDeferUsages, newGroupedFieldSets, deferMap) {
+    const newDeferredGroupedFieldSetRecords = [];
+    for (const [deferUsageSet, groupedFieldSet] of newGroupedFieldSets) {
+        const deferredFragmentRecords = getDeferredFragmentRecords(deferUsageSet, deferMap);
+        const deferredGroupedFieldSetRecord = {
+            path,
+            deferredFragmentRecords,
+            result: undefined,
+        };
+        const executor = () => executeDeferredGroupedFieldSet(deferredGroupedFieldSetRecord, exeContext, parentType, sourceValue, path, groupedFieldSet, {
+            errors: undefined,
+            deferUsageSet,
+            incrementalDataRecords: undefined,
+        }, deferMap);
+        const shouldDeferThisDeferUsageSet = shouldDefer(parentDeferUsages, deferUsageSet);
+        deferredGroupedFieldSetRecord.result = shouldDeferThisDeferUsageSet
+            ? exeContext.enableEarlyExecution
+                ? new BoxedPromiseOrValue(Promise.resolve().then(executor))
+                : () => new BoxedPromiseOrValue(executor())
+            : new BoxedPromiseOrValue(executor());
+        newDeferredGroupedFieldSetRecords.push(deferredGroupedFieldSetRecord);
+    }
+    return newDeferredGroupedFieldSetRecords;
 }
-function executeStreamField(path, itemPath, item, exeContext, fieldNodes, info, itemType, label, parentContext) {
-    const asyncPayloadRecord = new StreamRecord({
-        label,
-        path: itemPath,
-        parentContext,
-        exeContext,
-    });
-    let completedItem;
+function shouldDefer(parentDeferUsages, deferUsages) {
+    // If we have a new child defer usage, defer.
+    // Otherwise, this defer usage was already deferred when it was initially
+    // encountered, and is now in the midst of executing early, so the new
+    // deferred grouped fields set can be executed immediately.
+    return (parentDeferUsages === undefined ||
+        !Array.from(deferUsages).every(deferUsage => parentDeferUsages.has(deferUsage)));
+}
+function executeDeferredGroupedFieldSet(deferredGroupedFieldSetRecord, exeContext, parentType, sourceValue, path, groupedFieldSet, incrementalContext, deferMap) {
+    let result;
     try {
-        try {
-            if (isPromise(item)) {
-                completedItem = item.then(resolved => completeValue(exeContext, itemType, fieldNodes, info, itemPath, resolved, asyncPayloadRecord));
-            }
-            else {
-                completedItem = completeValue(exeContext, itemType, fieldNodes, info, itemPath, item, asyncPayloadRecord);
-            }
-            if (isPromise(completedItem)) {
-                // Note: we don't rely on a `catch` method, but we do expect "thenable"
-                // to take a second callback for the error case.
-                completedItem = completedItem.then(undefined, rawError => {
-                    rawError = coerceError(rawError);
-                    const error = locatedError(rawError, fieldNodes, pathToArray(itemPath));
-                    const handledError = handleFieldError(error, itemType, asyncPayloadRecord.errors);
-                    filterSubsequentPayloads(exeContext, itemPath, asyncPayloadRecord);
-                    return handledError;
-                });
-            }
-        }
-        catch (rawError) {
-            const coercedError = coerceError(rawError);
-            const error = locatedError(coercedError, fieldNodes, pathToArray(itemPath));
-            completedItem = handleFieldError(error, itemType, asyncPayloadRecord.errors);
-            filterSubsequentPayloads(exeContext, itemPath, asyncPayloadRecord);
-        }
+        result = executeFields(exeContext, parentType, sourceValue, path, groupedFieldSet, incrementalContext, deferMap);
     }
     catch (error) {
-        asyncPayloadRecord.errors.push(error);
-        filterSubsequentPayloads(exeContext, path, asyncPayloadRecord);
-        asyncPayloadRecord.addItems(null);
-        return asyncPayloadRecord;
-    }
-    let completedItems;
-    if (isPromise(completedItem)) {
-        completedItems = completedItem.then(value => [value], error => {
-            asyncPayloadRecord.errors.push(error);
-            filterSubsequentPayloads(exeContext, path, asyncPayloadRecord);
-            return null;
-        });
+        return {
+            deferredGroupedFieldSetRecord,
+            path: pathToArray(path),
+            errors: withError(incrementalContext.errors, error),
+        };
     }
-    else {
-        completedItems = [completedItem];
+    if (isPromise(result)) {
+        return result.then(resolved => buildDeferredGroupedFieldSetResult(incrementalContext, deferredGroupedFieldSetRecord, path, resolved), error => ({
+            deferredGroupedFieldSetRecord,
+            path: pathToArray(path),
+            errors: withError(incrementalContext.errors, error),
+        }));
     }
-    asyncPayloadRecord.addItems(completedItems);
-    return asyncPayloadRecord;
+    return buildDeferredGroupedFieldSetResult(incrementalContext, deferredGroupedFieldSetRecord, path, result);
 }
-async function executeStreamIteratorItem(iterator, exeContext, fieldNodes, info, itemType, asyncPayloadRecord, itemPath) {
-    let item;
-    try {
-        const { value, done } = await iterator.next();
-        if (done) {
-            asyncPayloadRecord.setIsCompletedIterator();
-            return { done, value: undefined };
-        }
-        item = value;
-    }
-    catch (rawError) {
-        const coercedError = coerceError(rawError);
-        const error = locatedError(coercedError, fieldNodes, pathToArray(itemPath));
-        const value = handleFieldError(error, itemType, asyncPayloadRecord.errors);
-        // don't continue if iterator throws
-        return { done: true, value };
-    }
-    let completedItem;
-    try {
-        completedItem = completeValue(exeContext, itemType, fieldNodes, info, itemPath, item, asyncPayloadRecord);
-        if (isPromise(completedItem)) {
-            completedItem = completedItem.then(undefined, rawError => {
-                const error = locatedError(rawError, fieldNodes, pathToArray(itemPath));
-                const handledError = handleFieldError(error, itemType, asyncPayloadRecord.errors);
-                filterSubsequentPayloads(exeContext, itemPath, asyncPayloadRecord);
-                return handledError;
-            });
-        }
-        return { done: false, value: completedItem };
+function buildDeferredGroupedFieldSetResult(incrementalContext, deferredGroupedFieldSetRecord, path, data) {
+    const { errors, incrementalDataRecords } = incrementalContext;
+    if (incrementalDataRecords === undefined) {
+        return {
+            deferredGroupedFieldSetRecord,
+            path: pathToArray(path),
+            result: errors === undefined ? { data } : { data, errors: [...errors.values()] },
+            incrementalDataRecords,
+        };
     }
-    catch (rawError) {
-        const error = locatedError(rawError, fieldNodes, pathToArray(itemPath));
-        const value = handleFieldError(error, itemType, asyncPayloadRecord.errors);
-        filterSubsequentPayloads(exeContext, itemPath, asyncPayloadRecord);
-        return { done: false, value };
+    if (errors === undefined) {
+        return {
+            deferredGroupedFieldSetRecord,
+            path: pathToArray(path),
+            result: { data },
+            incrementalDataRecords,
+        };
     }
+    return {
+        deferredGroupedFieldSetRecord,
+        path: pathToArray(path),
+        result: { data, errors: [...errors.values()] },
+        incrementalDataRecords: filterIncrementalDataRecords(path, errors, incrementalDataRecords),
+    };
 }
-async function executeStreamIterator(initialIndex, iterator, exeContext, fieldNodes, info, itemType, path, label, parentContext) {
-    let index = initialIndex;
-    let previousAsyncPayloadRecord = parentContext ?? undefined;
-    while (true) {
-        const itemPath = addPath(path, index, undefined);
-        const asyncPayloadRecord = new StreamRecord({
-            label,
-            path: itemPath,
-            parentContext: previousAsyncPayloadRecord,
-            iterator,
-            exeContext,
-        });
-        let iteration;
-        try {
-            iteration = await executeStreamIteratorItem(iterator, exeContext, fieldNodes, info, itemType, asyncPayloadRecord, itemPath);
-        }
-        catch (error) {
-            asyncPayloadRecord.errors.push(error);
-            filterSubsequentPayloads(exeContext, path, asyncPayloadRecord);
-            asyncPayloadRecord.addItems(null);
-            // entire stream has errored and bubbled upwards
-            if (iterator?.return) {
-                iterator.return().catch(() => {
-                    // ignore errors
-                });
-            }
-            return;
-        }
-        const { done, value: completedItem } = iteration;
-        let completedItems;
-        if (isPromise(completedItem)) {
-            completedItems = completedItem.then(value => [value], error => {
-                asyncPayloadRecord.errors.push(error);
-                filterSubsequentPayloads(exeContext, path, asyncPayloadRecord);
-                return null;
-            });
-        }
-        else {
-            completedItems = [completedItem];
-        }
-        asyncPayloadRecord.addItems(completedItems);
-        if (done) {
-            break;
-        }
-        previousAsyncPayloadRecord = asyncPayloadRecord;
-        index++;
-    }
+function getDeferredFragmentRecords(deferUsages, deferMap) {
+    return Array.from(deferUsages).map(deferUsage => deferredFragmentRecordFromDeferUsage(deferUsage, deferMap));
 }
-function filterSubsequentPayloads(exeContext, nullPath, currentAsyncRecord) {
-    const nullPathArray = pathToArray(nullPath);
-    exeContext.subsequentPayloads.forEach(asyncRecord => {
-        if (asyncRecord === currentAsyncRecord) {
-            // don't remove payload from where error originates
-            return;
-        }
-        for (let i = 0; i < nullPathArray.length; i++) {
-            if (asyncRecord.path[i] !== nullPathArray[i]) {
-                // asyncRecord points to a path unaffected by this payload
-                return;
+function buildSyncStreamItemQueue(initialItem, initialIndex, streamPath, iterator, exeContext, fieldGroup, info, itemType) {
+    const streamItemQueue = [];
+    const enableEarlyExecution = exeContext.enableEarlyExecution;
+    const firstExecutor = () => {
+        const initialPath = addPath(streamPath, initialIndex, undefined);
+        const firstStreamItem = new BoxedPromiseOrValue(completeStreamItem(streamPath, initialPath, initialItem, exeContext, { errors: undefined, incrementalDataRecords: undefined }, fieldGroup, info, itemType));
+        let iteration = iterator.next();
+        let currentIndex = initialIndex + 1;
+        let currentStreamItem = firstStreamItem;
+        while (!iteration.done) {
+            // TODO: add test case for early sync termination
+            /* c8 ignore next 6 */
+            if (currentStreamItem instanceof BoxedPromiseOrValue) {
+                const result = currentStreamItem.value;
+                if (!isPromise(result) && result.errors !== undefined) {
+                    break;
+                }
             }
+            const itemPath = addPath(streamPath, currentIndex, undefined);
+            const value = iteration.value;
+            const currentExecutor = () => completeStreamItem(streamPath, itemPath, value, exeContext, { errors: undefined, incrementalDataRecords: undefined }, fieldGroup, info, itemType);
+            currentStreamItem = enableEarlyExecution
+                ? new BoxedPromiseOrValue(currentExecutor())
+                : () => new BoxedPromiseOrValue(currentExecutor());
+            streamItemQueue.push(currentStreamItem);
+            iteration = iterator.next();
+            currentIndex = initialIndex + 1;
         }
-        // asyncRecord path points to nulled error field
-        if (isStreamPayload(asyncRecord) && asyncRecord.iterator?.return) {
-            asyncRecord.iterator.return().catch(() => {
-                // ignore error
-            });
-        }
-        exeContext.subsequentPayloads.delete(asyncRecord);
-    });
+        streamItemQueue.push(new BoxedPromiseOrValue({ path: streamPath }));
+        return firstStreamItem.value;
+    };
+    streamItemQueue.push(enableEarlyExecution
+        ? new BoxedPromiseOrValue(Promise.resolve().then(firstExecutor))
+        : () => new BoxedPromiseOrValue(firstExecutor()));
+    return streamItemQueue;
 }
-function getCompletedIncrementalResults(exeContext) {
-    const incrementalResults = [];
-    for (const asyncPayloadRecord of exeContext.subsequentPayloads) {
-        const incrementalResult = {};
-        if (!asyncPayloadRecord.isCompleted) {
-            continue;
-        }
-        exeContext.subsequentPayloads.delete(asyncPayloadRecord);
-        if (isStreamPayload(asyncPayloadRecord)) {
-            const items = asyncPayloadRecord.items;
-            if (asyncPayloadRecord.isCompletedIterator) {
-                // async iterable resolver just finished but there may be pending payloads
-                continue;
-            }
-            incrementalResult.items = items;
-        }
-        else {
-            const data = asyncPayloadRecord.data;
-            incrementalResult.data = data ?? null;
-        }
-        incrementalResult.path = asyncPayloadRecord.path;
-        if (asyncPayloadRecord.label) {
-            incrementalResult.label = asyncPayloadRecord.label;
-        }
-        if (asyncPayloadRecord.errors.length > 0) {
-            incrementalResult.errors = asyncPayloadRecord.errors;
-        }
-        incrementalResults.push(incrementalResult);
-    }
-    return incrementalResults;
+function buildAsyncStreamItemQueue(initialIndex, streamPath, asyncIterator, exeContext, fieldGroup, info, itemType) {
+    const streamItemQueue = [];
+    const executor = () => getNextAsyncStreamItemResult(streamItemQueue, streamPath, initialIndex, asyncIterator, exeContext, fieldGroup, info, itemType);
+    streamItemQueue.push(exeContext.enableEarlyExecution
+        ? new BoxedPromiseOrValue(executor())
+        : () => new BoxedPromiseOrValue(executor()));
+    return streamItemQueue;
 }
-function yieldSubsequentPayloads(exeContext) {
-    let isDone = false;
-    const abortPromise = new Promise((_, reject) => {
-        exeContext.signal?.addEventListener('abort', () => {
-            isDone = true;
-            reject(exeContext.signal?.reason);
-        });
-    });
-    async function next() {
-        if (isDone) {
-            return { value: undefined, done: true };
-        }
-        await Promise.race([
-            abortPromise,
-            ...Array.from(exeContext.subsequentPayloads).map(p => p.promise),
-        ]);
-        if (isDone) {
-            // a different call to next has exhausted all payloads
-            return { value: undefined, done: true };
-        }
-        const incremental = getCompletedIncrementalResults(exeContext);
-        const hasNext = exeContext.subsequentPayloads.size > 0;
-        if (!incremental.length && hasNext) {
-            return next();
-        }
-        if (!hasNext) {
-            isDone = true;
-        }
+async function getNextAsyncStreamItemResult(streamItemQueue, streamPath, index, asyncIterator, exeContext, fieldGroup, info, itemType) {
+    let iteration;
+    try {
+        iteration = await asyncIterator.next();
+    }
+    catch (error) {
         return {
-            value: incremental.length ? { incremental, hasNext } : { hasNext },
-            done: false,
+            path: streamPath,
+            errors: [locatedError(error, toNodes(fieldGroup), pathToArray(streamPath))],
         };
     }
-    function returnStreamIterators() {
-        const promises = [];
-        exeContext.subsequentPayloads.forEach(asyncPayloadRecord => {
-            if (isStreamPayload(asyncPayloadRecord) && asyncPayloadRecord.iterator?.return) {
-                promises.push(asyncPayloadRecord.iterator.return());
-            }
-        });
-        return Promise.all(promises);
+    if (iteration.done) {
+        return { path: streamPath };
     }
-    return {
-        [Symbol.asyncIterator]() {
-            return this;
-        },
-        next,
-        async return() {
-            await returnStreamIterators();
-            isDone = true;
-            return { value: undefined, done: true };
-        },
-        async throw(error) {
-            await returnStreamIterators();
-            isDone = true;
-            return Promise.reject(error);
-        },
-    };
+    const itemPath = addPath(streamPath, index, undefined);
+    const result = completeStreamItem(streamPath, itemPath, iteration.value, exeContext, { errors: undefined, incrementalDataRecords: undefined }, fieldGroup, info, itemType);
+    const executor = () => getNextAsyncStreamItemResult(streamItemQueue, streamPath, index, asyncIterator, exeContext, fieldGroup, info, itemType);
+    streamItemQueue.push(exeContext.enableEarlyExecution
+        ? new BoxedPromiseOrValue(executor())
+        : () => new BoxedPromiseOrValue(executor()));
+    return result;
 }
-class DeferredFragmentRecord {
-    constructor(opts) {
-        this.type = 'defer';
-        this.label = opts.label;
-        this.path = pathToArray(opts.path);
-        this.parentContext = opts.parentContext;
-        this.errors = [];
-        this._exeContext = opts.exeContext;
-        this._exeContext.subsequentPayloads.add(this);
-        this.isCompleted = false;
-        this.data = null;
-        this.promise = new Promise(resolve => {
-            this._resolve = MaybePromise => {
-                resolve(MaybePromise);
-            };
-        }).then(data => {
-            this.data = data;
-            this.isCompleted = true;
-        });
+function completeStreamItem(streamPath, itemPath, item, exeContext, incrementalContext, fieldGroup, info, itemType) {
+    if (isPromise(item)) {
+        return completePromisedValue(exeContext, itemType, fieldGroup, info, itemPath, item, incrementalContext, new Map()).then(resolvedItem => buildStreamItemResult(incrementalContext, streamPath, resolvedItem), error => ({
+            path: streamPath,
+            errors: withError(incrementalContext.errors, error),
+        }));
     }
-    addData(data) {
-        const parentData = this.parentContext?.promise;
-        if (parentData) {
-            this._resolve?.(parentData.then(() => data));
-            return;
+    let result;
+    try {
+        try {
+            result = completeValue(exeContext, itemType, fieldGroup, info, itemPath, item, incrementalContext, new Map());
         }
-        this._resolve?.(data);
-    }
-}
-class StreamRecord {
-    constructor(opts) {
-        this.type = 'stream';
-        this.items = null;
-        this.label = opts.label;
-        this.path = pathToArray(opts.path);
-        this.parentContext = opts.parentContext;
-        this.iterator = opts.iterator;
-        this.errors = [];
-        this._exeContext = opts.exeContext;
-        this._exeContext.subsequentPayloads.add(this);
-        this.isCompleted = false;
-        this.items = null;
-        this.promise = new Promise(resolve => {
-            this._resolve = MaybePromise => {
-                resolve(MaybePromise);
-            };
-        }).then(items => {
-            this.items = items;
-            this.isCompleted = true;
-        });
-    }
-    addItems(items) {
-        const parentData = this.parentContext?.promise;
-        if (parentData) {
-            this._resolve?.(parentData.then(() => items));
-            return;
+        catch (rawError) {
+            handleFieldError(rawError, exeContext, itemType, fieldGroup, itemPath, incrementalContext);
+            result = null;
         }
-        this._resolve?.(items);
     }
-    setIsCompletedIterator() {
-        this.isCompletedIterator = true;
+    catch (error) {
+        return {
+            path: streamPath,
+            errors: withError(incrementalContext.errors, error),
+        };
+    }
+    if (isPromise(result)) {
+        return result
+            .then(undefined, rawError => {
+            handleFieldError(rawError, exeContext, itemType, fieldGroup, itemPath, incrementalContext);
+            return null;
+        })
+            .then(resolvedItem => buildStreamItemResult(incrementalContext, streamPath, resolvedItem), error => ({
+            path: streamPath,
+            errors: withError(incrementalContext.errors, error),
+        }));
     }
+    return buildStreamItemResult(incrementalContext, streamPath, result);
 }
-function isStreamPayload(asyncPayload) {
-    return asyncPayload.type === 'stream';
+function buildStreamItemResult(incrementalContext, streamPath, item) {
+    const { errors, incrementalDataRecords } = incrementalContext;
+    if (incrementalDataRecords === undefined) {
+        return {
+            path: streamPath,
+            item,
+            errors: errors === undefined ? undefined : [...errors.values()],
+            incrementalDataRecords,
+        };
+    }
+    if (errors === undefined) {
+        return {
+            path: streamPath,
+            item,
+            errors,
+            incrementalDataRecords,
+        };
+    }
+    return {
+        path: streamPath,
+        item,
+        errors: [...errors.values()],
+        incrementalDataRecords: filterIncrementalDataRecords(streamPath, errors, incrementalDataRecords),
+    };
 }
 /**
  * This method looks up the field on the given type definition.