@graphql-tools/executor 2.0.0-alpha-20240702193427-1ce4b1efdef732d2635b657df6273a975a19d217 → 2.0.0-alpha-20240708182941-ed27153e85ecdb79083b1d124d470573a65893fd

package/cjs/execution/IncrementalGraph.js

@@ -33,6 +33,20 @@ class IncrementalGraph {
             this._addIncrementalDataRecords(incrementalDataRecords, reconcilableResult.deferredGroupedFieldSetRecord.deferredFragmentRecords);
         }
     }
+    currentCompletedIncrementalData() {
+        return {
+            [Symbol.iterator]() {
+                return this;
+            },
+            next: () => {
+                const value = this._completedQueue.shift();
+                if (value !== undefined) {
+                    return { value, done: false };
+                }
+                return { value: undefined, done: true };
+            },
+        };
+    }
     completedIncrementalData() {
         return {
             [Symbol.asyncIterator]() {

package/cjs/execution/IncrementalPublisher.js

@@ -70,13 +70,11 @@ class IncrementalPublisher {
                 incremental: [],
                 completed: [],
             };
+            let currentCompletedIncrementalData = this._incrementalGraph.currentCompletedIncrementalData();
             const completedIncrementalData = this._incrementalGraph.completedIncrementalData();
-            // use the raw iterator rather than 'for await ... of' so as not to trigger the
-            // '.return()' method on the iterator when exiting the loop with the next value
             const asyncIterator = completedIncrementalData[Symbol.asyncIterator]();
-            let iteration = await asyncIterator.next();
-            while (!iteration.done) {
-                for (const completedResult of iteration.value) {
+            do {
+                for (const completedResult of currentCompletedIncrementalData) {
                     this._handleCompletedIncrementalData(completedResult, context);
                 }
                 const { incremental, completed } = context;
@@ -100,8 +98,9 @@ class IncrementalPublisher {
                     }
                     return { value: subsequentIncrementalExecutionResult, done: false };
                 }
-                iteration = await asyncIterator.next();
-            }
+                const iteration = await asyncIterator.next();
+                currentCompletedIncrementalData = iteration.value;
+            } while (currentCompletedIncrementalData !== undefined);
             if (this._context.signal?.aborted) {
                 throw this._context.signal.reason;
             }
@@ -145,10 +144,28 @@ class IncrementalPublisher {
                     continue;
                 }
                 (0, invariant_js_1.invariant)(id !== undefined);
-                context.completed.push({
-                    id,
-                    errors: deferredGroupedFieldSetResult.errors,
-                });
+                if (this._context.sendIncrementalErrorsAsNull) {
+                    const incrementalEntry = {
+                        id,
+                        data: null,
+                        errors: deferredGroupedFieldSetResult.errors,
+                    };
+                    if (this._context.sendPathAndLabelOnIncremental) {
+                        const { path, label } = deferredFragmentRecord;
+                        incrementalEntry.path = (0, utils_1.pathToArray)(path);
+                        if (label !== undefined) {
+                            incrementalEntry.label = label;
+                        }
+                    }
+                    context.incremental.push(incrementalEntry);
+                    context.completed.push({ id });
+                }
+                else {
+                    context.completed.push({
+                        id,
+                        errors: deferredGroupedFieldSetResult.errors,
+                    });
+                }
             }
             return;
         }
@@ -170,6 +187,13 @@ class IncrementalPublisher {
                     ...reconcilableResult.result,
                     id: bestId,
                 };
+                if (this._context.sendPathAndLabelOnIncremental) {
+                    const { path, label } = deferredFragmentRecord;
+                    incrementalEntry.path = (0, utils_1.pathToArray)(path);
+                    if (label !== undefined) {
+                        incrementalEntry.label = label;
+                    }
+                }
                 if (subPath !== undefined) {
                     incrementalEntry.subPath = subPath;
                 }
@@ -183,10 +207,28 @@ class IncrementalPublisher {
         const id = streamRecord.id;
         (0, invariant_js_1.invariant)(id !== undefined);
         if (streamItemsResult.errors !== undefined) {
-            context.completed.push({
-                id,
-                errors: streamItemsResult.errors,
-            });
+            if (this._context.sendIncrementalErrorsAsNull) {
+                const incrementalEntry = {
+                    items: null,
+                    id,
+                    errors: streamItemsResult.errors,
+                };
+                if (this._context.sendPathAndLabelOnIncremental) {
+                    const { path, label, index } = streamRecord;
+                    incrementalEntry.path = (0, utils_1.pathToArray)((0, utils_1.addPath)(path, index, undefined));
+                    if (label !== undefined) {
+                        incrementalEntry.label = label;
+                    }
+                }
+                context.incremental.push(incrementalEntry);
+                context.completed.push({ id });
+            }
+            else {
+                context.completed.push({
+                    id,
+                    errors: streamItemsResult.errors,
+                });
+            }
             this._incrementalGraph.removeStream(streamRecord);
             if ((0, types_js_1.isCancellableStreamRecord)(streamRecord)) {
                 (0, invariant_js_1.invariant)(this._context.cancellableStreams !== undefined);
@@ -206,10 +248,19 @@ class IncrementalPublisher {
             }
         }
         else {
+            const bareResult = streamItemsResult.result;
             const incrementalEntry = {
                 id,
-                ...streamItemsResult.result,
+                ...bareResult,
             };
+            if (this._context.sendPathAndLabelOnIncremental) {
+                const { path, label, index } = streamRecord;
+                incrementalEntry.path = (0, utils_1.pathToArray)((0, utils_1.addPath)(path, index, undefined));
+                streamRecord.index += bareResult.items.length;
+                if (label !== undefined) {
+                    incrementalEntry.label = label;
+                }
+            }
             context.incremental.push(incrementalEntry);
             const incrementalDataRecords = streamItemsResult.incrementalDataRecords;
             if (incrementalDataRecords !== undefined) {

package/cjs/execution/buildFieldPlan.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildFieldPlan = void 0;
+exports.buildBranchingFieldPlan = exports.buildFieldPlan = void 0;
+const AccumulatorMap_js_1 = require("./AccumulatorMap.js");
 const getBySet_js_1 = require("./getBySet.js");
 const isSameSet_js_1 = require("./isSameSet.js");
 function buildFieldPlan(originalGroupedFieldSet, parentDeferUsages = new Set()) {
@@ -60,3 +61,29 @@ function getAncestors(deferUsage) {
     }
     return ancestors;
 }
+function buildBranchingFieldPlan(originalGroupedFieldSet, parentDeferUsages = new Set()) {
+    const groupedFieldSet = new AccumulatorMap_js_1.AccumulatorMap();
+    const newGroupedFieldSets = new Map();
+    for (const [responseKey, fieldGroup] of originalGroupedFieldSet) {
+        for (const fieldDetails of fieldGroup) {
+            const deferUsage = fieldDetails.deferUsage;
+            const deferUsageSet = deferUsage === undefined ? new Set() : new Set([deferUsage]);
+            if ((0, isSameSet_js_1.isSameSet)(parentDeferUsages, deferUsageSet)) {
+                groupedFieldSet.add(responseKey, fieldDetails);
+            }
+            else {
+                let newGroupedFieldSet = (0, getBySet_js_1.getBySet)(newGroupedFieldSets, deferUsageSet);
+                if (newGroupedFieldSet === undefined) {
+                    newGroupedFieldSet = new AccumulatorMap_js_1.AccumulatorMap();
+                    newGroupedFieldSets.set(deferUsageSet, newGroupedFieldSet);
+                }
+                newGroupedFieldSet.add(responseKey, fieldDetails);
+            }
+        }
+    }
+    return {
+        groupedFieldSet,
+        newGroupedFieldSets,
+    };
+}
+exports.buildBranchingFieldPlan = buildBranchingFieldPlan;

package/cjs/execution/execute.js

@@ -150,7 +150,7 @@ exports.getFragmentsFromDocument = (0, utils_1.memoize1)(function getFragmentsFr
  * @internal
  */
 function buildExecutionContext(args) {
-    const { schema, document, rootValue, contextValue, variableValues: rawVariableValues, operationName, fieldResolver, typeResolver, subscribeFieldResolver, enableEarlyExecution, errorWithIncrementalSubscription, signal, } = args;
+    const { schema, document, rootValue, contextValue, variableValues: rawVariableValues, operationName, fieldResolver, typeResolver, subscribeFieldResolver, enableEarlyExecution, deduplicateDefers, sendIncrementalErrorsAsNull, sendPathAndLabelOnIncremental, errorWithIncrementalSubscription, signal, } = args;
     // If the schema used for execution is invalid, throw an error.
     (0, graphql_1.assertValidSchema)(schema);
     const fragments = (0, exports.getFragmentsFromDocument)(document);
@@ -200,6 +200,9 @@ function buildExecutionContext(args) {
         typeResolver: typeResolver ?? exports.defaultTypeResolver,
         subscribeFieldResolver: subscribeFieldResolver ?? exports.defaultFieldResolver,
         enableEarlyExecution: enableEarlyExecution !== false,
+        deduplicateDefers: deduplicateDefers !== false,
+        sendIncrementalErrorsAsNull: sendIncrementalErrorsAsNull === true,
+        sendPathAndLabelOnIncremental: sendPathAndLabelOnIncremental === true,
         errorWithIncrementalSubscription: operation.operation === 'subscription' && errorWithIncrementalSubscription !== false,
         signal,
         errors: undefined,
@@ -223,7 +226,7 @@ function executeOperation(exeContext) {
         throw exeContext.signal.reason;
     }
     try {
-        const { operation, schema, fragments, variableValues, rootValue, errorWithIncrementalSubscription, } = exeContext;
+        const { operation, schema, fragments, variableValues, rootValue, deduplicateDefers, errorWithIncrementalSubscription, } = exeContext;
         const rootType = (0, utils_1.getDefinedRootType)(schema, operation.operation, [operation]);
         if (rootType == null) {
             (0, utils_1.createGraphQLError)(`Schema is not configured to execute ${operation.operation} operation.`, {
@@ -238,7 +241,9 @@ function executeOperation(exeContext) {
             data = executeRootGroupedFieldSet(exeContext, operation.operation, rootType, rootValue, groupedFieldSet, undefined);
         }
         else {
-            const fieldPLan = (0, buildFieldPlan_js_1.buildFieldPlan)(groupedFieldSet);
+            const fieldPLan = deduplicateDefers
+                ? (0, buildFieldPlan_js_1.buildFieldPlan)(groupedFieldSet)
+                : (0, buildFieldPlan_js_1.buildBranchingFieldPlan)(groupedFieldSet);
             groupedFieldSet = fieldPLan.groupedFieldSet;
             const newGroupedFieldSets = fieldPLan.newGroupedFieldSets;
             const newDeferMap = addNewDeferredFragments(newDeferUsages, new Map());
@@ -573,6 +578,7 @@ async function completeAsyncIteratorValue(exeContext, itemType, fieldGroup, info
                 streamRecord = {
                     label: streamUsage.label,
                     path,
+                    index,
                     streamItemQueue,
                 };
             }
@@ -580,6 +586,7 @@ async function completeAsyncIteratorValue(exeContext, itemType, fieldGroup, info
                 streamRecord = {
                     label: streamUsage.label,
                     path,
+                    index,
                     streamItemQueue,
                     earlyReturn: returnFn.bind(asyncIterator),
                 };
@@ -657,6 +664,7 @@ function completeIterableValue(exeContext, itemType, fieldGroup, info, path, ite
             const streamRecord = {
                 label: streamUsage.label,
                 path,
+                index,
                 streamItemQueue: buildSyncStreamItemQueue(item, index, path, iterator, exeContext, streamUsage.fieldGroup, info, itemType),
             };
             const context = incrementalContext ?? exeContext;
@@ -834,7 +842,7 @@ function collectAndExecuteSubfields(exeContext, returnType, fieldGroup, path, re
     if (deferMap === undefined && newDeferUsages.length === 0) {
         return executeFields(exeContext, returnType, result, path, groupedFieldSet, incrementalContext, undefined);
     }
-    const subFieldPlan = buildSubFieldPlan(groupedFieldSet, incrementalContext?.deferUsageSet);
+    const subFieldPlan = buildSubFieldPlan(groupedFieldSet, incrementalContext?.deferUsageSet, exeContext.deduplicateDefers);
     groupedFieldSet = subFieldPlan.groupedFieldSet;
     const newGroupedFieldSets = subFieldPlan.newGroupedFieldSets;
     const newDeferMap = addNewDeferredFragments(newDeferUsages, new Map(deferMap), path);
@@ -846,12 +854,14 @@ function collectAndExecuteSubfields(exeContext, returnType, fieldGroup, path, re
     }
     return subFields;
 }
-function buildSubFieldPlan(originalGroupedFieldSet, deferUsageSet) {
+function buildSubFieldPlan(originalGroupedFieldSet, deferUsageSet, deduplicateDefers) {
     let fieldPlan = originalGroupedFieldSet._fieldPlan;
     if (fieldPlan !== undefined) {
         return fieldPlan;
     }
-    fieldPlan = (0, buildFieldPlan_js_1.buildFieldPlan)(originalGroupedFieldSet, deferUsageSet);
+    fieldPlan = deduplicateDefers
+        ? (0, buildFieldPlan_js_1.buildFieldPlan)(originalGroupedFieldSet, deferUsageSet)
+        : (0, buildFieldPlan_js_1.buildBranchingFieldPlan)(originalGroupedFieldSet, deferUsageSet);
     originalGroupedFieldSet._fieldPlan = fieldPlan;
     return fieldPlan;
 }

package/esm/execution/IncrementalGraph.js

@@ -30,6 +30,20 @@ export class IncrementalGraph {
             this._addIncrementalDataRecords(incrementalDataRecords, reconcilableResult.deferredGroupedFieldSetRecord.deferredFragmentRecords);
         }
     }
+    currentCompletedIncrementalData() {
+        return {
+            [Symbol.iterator]() {
+                return this;
+            },
+            next: () => {
+                const value = this._completedQueue.shift();
+                if (value !== undefined) {
+                    return { value, done: false };
+                }
+                return { value: undefined, done: true };
+            },
+        };
+    }
     completedIncrementalData() {
         return {
             [Symbol.asyncIterator]() {

package/esm/execution/IncrementalPublisher.js

@@ -1,4 +1,4 @@
-import { pathToArray } from '@graphql-tools/utils';
+import { addPath, pathToArray } from '@graphql-tools/utils';
 import { IncrementalGraph } from './IncrementalGraph.js';
 import { invariant } from './invariant.js';
 import { isCancellableStreamRecord, isDeferredGroupedFieldSetResult, isNonReconcilableDeferredGroupedFieldSetResult, } from './types.js';
@@ -66,13 +66,11 @@ class IncrementalPublisher {
                 incremental: [],
                 completed: [],
             };
+            let currentCompletedIncrementalData = this._incrementalGraph.currentCompletedIncrementalData();
             const completedIncrementalData = this._incrementalGraph.completedIncrementalData();
-            // use the raw iterator rather than 'for await ... of' so as not to trigger the
-            // '.return()' method on the iterator when exiting the loop with the next value
             const asyncIterator = completedIncrementalData[Symbol.asyncIterator]();
-            let iteration = await asyncIterator.next();
-            while (!iteration.done) {
-                for (const completedResult of iteration.value) {
+            do {
+                for (const completedResult of currentCompletedIncrementalData) {
                     this._handleCompletedIncrementalData(completedResult, context);
                 }
                 const { incremental, completed } = context;
@@ -96,8 +94,9 @@ class IncrementalPublisher {
                     }
                     return { value: subsequentIncrementalExecutionResult, done: false };
                 }
-                iteration = await asyncIterator.next();
-            }
+                const iteration = await asyncIterator.next();
+                currentCompletedIncrementalData = iteration.value;
+            } while (currentCompletedIncrementalData !== undefined);
             if (this._context.signal?.aborted) {
                 throw this._context.signal.reason;
             }
@@ -141,10 +140,28 @@ class IncrementalPublisher {
                     continue;
                 }
                 invariant(id !== undefined);
-                context.completed.push({
-                    id,
-                    errors: deferredGroupedFieldSetResult.errors,
-                });
+                if (this._context.sendIncrementalErrorsAsNull) {
+                    const incrementalEntry = {
+                        id,
+                        data: null,
+                        errors: deferredGroupedFieldSetResult.errors,
+                    };
+                    if (this._context.sendPathAndLabelOnIncremental) {
+                        const { path, label } = deferredFragmentRecord;
+                        incrementalEntry.path = pathToArray(path);
+                        if (label !== undefined) {
+                            incrementalEntry.label = label;
+                        }
+                    }
+                    context.incremental.push(incrementalEntry);
+                    context.completed.push({ id });
+                }
+                else {
+                    context.completed.push({
+                        id,
+                        errors: deferredGroupedFieldSetResult.errors,
+                    });
+                }
             }
             return;
         }
@@ -166,6 +183,13 @@ class IncrementalPublisher {
                     ...reconcilableResult.result,
                     id: bestId,
                 };
+                if (this._context.sendPathAndLabelOnIncremental) {
+                    const { path, label } = deferredFragmentRecord;
+                    incrementalEntry.path = pathToArray(path);
+                    if (label !== undefined) {
+                        incrementalEntry.label = label;
+                    }
+                }
                 if (subPath !== undefined) {
                     incrementalEntry.subPath = subPath;
                 }
@@ -179,10 +203,28 @@ class IncrementalPublisher {
         const id = streamRecord.id;
         invariant(id !== undefined);
         if (streamItemsResult.errors !== undefined) {
-            context.completed.push({
-                id,
-                errors: streamItemsResult.errors,
-            });
+            if (this._context.sendIncrementalErrorsAsNull) {
+                const incrementalEntry = {
+                    items: null,
+                    id,
+                    errors: streamItemsResult.errors,
+                };
+                if (this._context.sendPathAndLabelOnIncremental) {
+                    const { path, label, index } = streamRecord;
+                    incrementalEntry.path = pathToArray(addPath(path, index, undefined));
+                    if (label !== undefined) {
+                        incrementalEntry.label = label;
+                    }
+                }
+                context.incremental.push(incrementalEntry);
+                context.completed.push({ id });
+            }
+            else {
+                context.completed.push({
+                    id,
+                    errors: streamItemsResult.errors,
+                });
+            }
             this._incrementalGraph.removeStream(streamRecord);
             if (isCancellableStreamRecord(streamRecord)) {
                 invariant(this._context.cancellableStreams !== undefined);
@@ -202,10 +244,19 @@ class IncrementalPublisher {
             }
         }
         else {
+            const bareResult = streamItemsResult.result;
             const incrementalEntry = {
                 id,
-                ...streamItemsResult.result,
+                ...bareResult,
             };
+            if (this._context.sendPathAndLabelOnIncremental) {
+                const { path, label, index } = streamRecord;
+                incrementalEntry.path = pathToArray(addPath(path, index, undefined));
+                streamRecord.index += bareResult.items.length;
+                if (label !== undefined) {
+                    incrementalEntry.label = label;
+                }
+            }
             context.incremental.push(incrementalEntry);
             const incrementalDataRecords = streamItemsResult.incrementalDataRecords;
             if (incrementalDataRecords !== undefined) {

package/esm/execution/buildFieldPlan.js

@@ -1,3 +1,4 @@
+import { AccumulatorMap } from './AccumulatorMap.js';
 import { getBySet } from './getBySet.js';
 import { isSameSet } from './isSameSet.js';
 export function buildFieldPlan(originalGroupedFieldSet, parentDeferUsages = new Set()) {
@@ -56,3 +57,28 @@ function getAncestors(deferUsage) {
     }
     return ancestors;
 }
+export function buildBranchingFieldPlan(originalGroupedFieldSet, parentDeferUsages = new Set()) {
+    const groupedFieldSet = new AccumulatorMap();
+    const newGroupedFieldSets = new Map();
+    for (const [responseKey, fieldGroup] of originalGroupedFieldSet) {
+        for (const fieldDetails of fieldGroup) {
+            const deferUsage = fieldDetails.deferUsage;
+            const deferUsageSet = deferUsage === undefined ? new Set() : new Set([deferUsage]);
+            if (isSameSet(parentDeferUsages, deferUsageSet)) {
+                groupedFieldSet.add(responseKey, fieldDetails);
+            }
+            else {
+                let newGroupedFieldSet = getBySet(newGroupedFieldSets, deferUsageSet);
+                if (newGroupedFieldSet === undefined) {
+                    newGroupedFieldSet = new AccumulatorMap();
+                    newGroupedFieldSets.set(deferUsageSet, newGroupedFieldSet);
+                }
+                newGroupedFieldSet.add(responseKey, fieldDetails);
+            }
+        }
+    }
+    return {
+        groupedFieldSet,
+        newGroupedFieldSets,
+    };
+}

package/esm/execution/execute.js

@@ -1,7 +1,7 @@
 import { assertValidSchema, getDirectiveValues, GraphQLError, isAbstractType, isLeafType, isListType, isNonNullType, isObjectType, Kind, locatedError, SchemaMetaFieldDef, TypeMetaFieldDef, TypeNameMetaFieldDef, versionInfo, } from 'graphql';
 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 { buildBranchingFieldPlan, buildFieldPlan, } from './buildFieldPlan.js';
 import { coerceError } from './coerceError.js';
 import { collectSubfields as _collectSubfields, collectFields, } from './collectFields.js';
 import { flattenAsyncIterable } from './flattenAsyncIterable.js';
@@ -144,7 +144,7 @@ export const getFragmentsFromDocument = memoize1(function getFragmentsFromDocume
  * @internal
  */
 export function buildExecutionContext(args) {
-    const { schema, document, rootValue, contextValue, variableValues: rawVariableValues, operationName, fieldResolver, typeResolver, subscribeFieldResolver, enableEarlyExecution, errorWithIncrementalSubscription, signal, } = args;
+    const { schema, document, rootValue, contextValue, variableValues: rawVariableValues, operationName, fieldResolver, typeResolver, subscribeFieldResolver, enableEarlyExecution, deduplicateDefers, sendIncrementalErrorsAsNull, sendPathAndLabelOnIncremental, errorWithIncrementalSubscription, signal, } = args;
     // If the schema used for execution is invalid, throw an error.
     assertValidSchema(schema);
     const fragments = getFragmentsFromDocument(document);
@@ -194,6 +194,9 @@ export function buildExecutionContext(args) {
         typeResolver: typeResolver ?? defaultTypeResolver,
         subscribeFieldResolver: subscribeFieldResolver ?? defaultFieldResolver,
         enableEarlyExecution: enableEarlyExecution !== false,
+        deduplicateDefers: deduplicateDefers !== false,
+        sendIncrementalErrorsAsNull: sendIncrementalErrorsAsNull === true,
+        sendPathAndLabelOnIncremental: sendPathAndLabelOnIncremental === true,
         errorWithIncrementalSubscription: operation.operation === 'subscription' && errorWithIncrementalSubscription !== false,
         signal,
         errors: undefined,
@@ -216,7 +219,7 @@ function executeOperation(exeContext) {
         throw exeContext.signal.reason;
     }
     try {
-        const { operation, schema, fragments, variableValues, rootValue, errorWithIncrementalSubscription, } = exeContext;
+        const { operation, schema, fragments, variableValues, rootValue, deduplicateDefers, errorWithIncrementalSubscription, } = exeContext;
         const rootType = getDefinedRootType(schema, operation.operation, [operation]);
         if (rootType == null) {
             createGraphQLError(`Schema is not configured to execute ${operation.operation} operation.`, {
@@ -231,7 +234,9 @@ function executeOperation(exeContext) {
             data = executeRootGroupedFieldSet(exeContext, operation.operation, rootType, rootValue, groupedFieldSet, undefined);
         }
         else {
-            const fieldPLan = buildFieldPlan(groupedFieldSet);
+            const fieldPLan = deduplicateDefers
+                ? buildFieldPlan(groupedFieldSet)
+                : buildBranchingFieldPlan(groupedFieldSet);
             groupedFieldSet = fieldPLan.groupedFieldSet;
             const newGroupedFieldSets = fieldPLan.newGroupedFieldSets;
             const newDeferMap = addNewDeferredFragments(newDeferUsages, new Map());
@@ -565,6 +570,7 @@ async function completeAsyncIteratorValue(exeContext, itemType, fieldGroup, info
                 streamRecord = {
                     label: streamUsage.label,
                     path,
+                    index,
                     streamItemQueue,
                 };
             }
@@ -572,6 +578,7 @@ async function completeAsyncIteratorValue(exeContext, itemType, fieldGroup, info
                 streamRecord = {
                     label: streamUsage.label,
                     path,
+                    index,
                     streamItemQueue,
                     earlyReturn: returnFn.bind(asyncIterator),
                 };
@@ -649,6 +656,7 @@ function completeIterableValue(exeContext, itemType, fieldGroup, info, path, ite
             const streamRecord = {
                 label: streamUsage.label,
                 path,
+                index,
                 streamItemQueue: buildSyncStreamItemQueue(item, index, path, iterator, exeContext, streamUsage.fieldGroup, info, itemType),
             };
             const context = incrementalContext ?? exeContext;
@@ -826,7 +834,7 @@ function collectAndExecuteSubfields(exeContext, returnType, fieldGroup, path, re
     if (deferMap === undefined && newDeferUsages.length === 0) {
         return executeFields(exeContext, returnType, result, path, groupedFieldSet, incrementalContext, undefined);
     }
-    const subFieldPlan = buildSubFieldPlan(groupedFieldSet, incrementalContext?.deferUsageSet);
+    const subFieldPlan = buildSubFieldPlan(groupedFieldSet, incrementalContext?.deferUsageSet, exeContext.deduplicateDefers);
     groupedFieldSet = subFieldPlan.groupedFieldSet;
     const newGroupedFieldSets = subFieldPlan.newGroupedFieldSets;
     const newDeferMap = addNewDeferredFragments(newDeferUsages, new Map(deferMap), path);
@@ -838,12 +846,14 @@ function collectAndExecuteSubfields(exeContext, returnType, fieldGroup, path, re
     }
     return subFields;
 }
-function buildSubFieldPlan(originalGroupedFieldSet, deferUsageSet) {
+function buildSubFieldPlan(originalGroupedFieldSet, deferUsageSet, deduplicateDefers) {
     let fieldPlan = originalGroupedFieldSet._fieldPlan;
     if (fieldPlan !== undefined) {
         return fieldPlan;
     }
-    fieldPlan = buildFieldPlan(originalGroupedFieldSet, deferUsageSet);
+    fieldPlan = deduplicateDefers
+        ? buildFieldPlan(originalGroupedFieldSet, deferUsageSet)
+        : buildBranchingFieldPlan(originalGroupedFieldSet, deferUsageSet);
     originalGroupedFieldSet._fieldPlan = fieldPlan;
     return fieldPlan;
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@graphql-tools/executor",
-  "version": "2.0.0-alpha-20240702193427-1ce4b1efdef732d2635b657df6273a975a19d217",
+  "version": "2.0.0-alpha-20240708182941-ed27153e85ecdb79083b1d124d470573a65893fd",
   "sideEffects": false,
   "peerDependencies": {
     "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
   },
   "dependencies": {
-    "@graphql-tools/utils": "10.3.0-alpha-20240702193427-1ce4b1efdef732d2635b657df6273a975a19d217",
+    "@graphql-tools/utils": "10.3.0-alpha-20240708182941-ed27153e85ecdb79083b1d124d470573a65893fd",
     "@graphql-typed-document-node/core": "3.2.0",
     "@repeaterjs/repeater": "^3.0.4",
     "tslib": "^2.4.0",

package/typings/execution/IncrementalGraph.d.cts

@@ -9,6 +9,10 @@ export declare class IncrementalGraph {
     constructor();
     getNewPending(incrementalDataRecords: ReadonlyArray<IncrementalDataRecord>): ReadonlyArray<SubsequentResultRecord>;
     addCompletedReconcilableDeferredGroupedFieldSet(reconcilableResult: ReconcilableDeferredGroupedFieldSetResult): void;
+    currentCompletedIncrementalData(): {
+        [Symbol.iterator](): any;
+        next: () => IteratorResult<IncrementalDataRecordResult>;
+    };
     completedIncrementalData(): {
         [Symbol.asyncIterator](): any;
         next: () => Promise<IteratorResult<Iterable<IncrementalDataRecordResult>>>;

package/typings/execution/IncrementalGraph.d.ts

@@ -9,6 +9,10 @@ export declare class IncrementalGraph {
     constructor();
     getNewPending(incrementalDataRecords: ReadonlyArray<IncrementalDataRecord>): ReadonlyArray<SubsequentResultRecord>;
     addCompletedReconcilableDeferredGroupedFieldSet(reconcilableResult: ReconcilableDeferredGroupedFieldSetResult): void;
+    currentCompletedIncrementalData(): {
+        [Symbol.iterator](): any;
+        next: () => IteratorResult<IncrementalDataRecordResult>;
+    };
     completedIncrementalData(): {
         [Symbol.asyncIterator](): any;
         next: () => Promise<IteratorResult<Iterable<IncrementalDataRecordResult>>>;

package/typings/execution/IncrementalPublisher.d.cts

@@ -2,6 +2,8 @@ import type { GraphQLError } from 'graphql';
 import type { CancellableStreamRecord, IncrementalDataRecord, IncrementalExecutionResults } from './types.cjs';
 export declare function buildIncrementalResponse<TData = any>(context: IncrementalPublisherContext, result: TData, errors: ReadonlyArray<GraphQLError> | undefined, incrementalDataRecords: ReadonlyArray<IncrementalDataRecord>): IncrementalExecutionResults<TData>;
 interface IncrementalPublisherContext {
+    sendIncrementalErrorsAsNull: boolean;
+    sendPathAndLabelOnIncremental: boolean;
     signal: AbortSignal | undefined;
     cancellableStreams: Set<CancellableStreamRecord> | undefined;
 }

package/typings/execution/IncrementalPublisher.d.ts

@@ -2,6 +2,8 @@ import type { GraphQLError } from 'graphql';
 import type { CancellableStreamRecord, IncrementalDataRecord, IncrementalExecutionResults } from './types.js';
 export declare function buildIncrementalResponse<TData = any>(context: IncrementalPublisherContext, result: TData, errors: ReadonlyArray<GraphQLError> | undefined, incrementalDataRecords: ReadonlyArray<IncrementalDataRecord>): IncrementalExecutionResults<TData>;
 interface IncrementalPublisherContext {
+    sendIncrementalErrorsAsNull: boolean;
+    sendPathAndLabelOnIncremental: boolean;
     signal: AbortSignal | undefined;
     cancellableStreams: Set<CancellableStreamRecord> | undefined;
 }

package/typings/execution/buildFieldPlan.d.cts

@@ -5,3 +5,4 @@ export interface FieldPlan {
     newGroupedFieldSets: Map<DeferUsageSet, GroupedFieldSet>;
 }
 export declare function buildFieldPlan(originalGroupedFieldSet: GroupedFieldSet, parentDeferUsages?: DeferUsageSet): FieldPlan;
+export declare function buildBranchingFieldPlan(originalGroupedFieldSet: GroupedFieldSet, parentDeferUsages?: DeferUsageSet): FieldPlan;

package/typings/execution/buildFieldPlan.d.ts

@@ -5,3 +5,4 @@ export interface FieldPlan {
     newGroupedFieldSets: Map<DeferUsageSet, GroupedFieldSet>;
 }
 export declare function buildFieldPlan(originalGroupedFieldSet: GroupedFieldSet, parentDeferUsages?: DeferUsageSet): FieldPlan;
+export declare function buildBranchingFieldPlan(originalGroupedFieldSet: GroupedFieldSet, parentDeferUsages?: DeferUsageSet): FieldPlan;

package/typings/execution/execute.d.cts

@@ -38,6 +38,9 @@ export interface ExecutionContext<TVariables = any, TContext = any> {
     typeResolver: GraphQLTypeResolver<any, TContext>;
     subscribeFieldResolver: GraphQLFieldResolver<any, TContext>;
     enableEarlyExecution: boolean;
+    deduplicateDefers: boolean;
+    sendIncrementalErrorsAsNull: boolean;
+    sendPathAndLabelOnIncremental: boolean;
     errorWithIncrementalSubscription: boolean;
     signal: AbortSignal | undefined;
     errors: Map<Path | undefined, GraphQLError> | undefined;
@@ -55,6 +58,9 @@ export interface ExecutionArgs<TData = any, TVariables = any, TContext = any> {
     typeResolver?: Maybe<GraphQLTypeResolver<any, TContext>>;
     subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, TContext>>;
     enableEarlyExecution?: Maybe<boolean>;
+    deduplicateDefers?: Maybe<boolean>;
+    sendIncrementalErrorsAsNull?: Maybe<boolean>;
+    sendPathAndLabelOnIncremental?: Maybe<boolean>;
     errorWithIncrementalSubscription?: Maybe<boolean>;
     signal?: AbortSignal;
 }

package/typings/execution/execute.d.ts

@@ -38,6 +38,9 @@ export interface ExecutionContext<TVariables = any, TContext = any> {
     typeResolver: GraphQLTypeResolver<any, TContext>;
     subscribeFieldResolver: GraphQLFieldResolver<any, TContext>;
     enableEarlyExecution: boolean;
+    deduplicateDefers: boolean;
+    sendIncrementalErrorsAsNull: boolean;
+    sendPathAndLabelOnIncremental: boolean;
     errorWithIncrementalSubscription: boolean;
     signal: AbortSignal | undefined;
     errors: Map<Path | undefined, GraphQLError> | undefined;
@@ -55,6 +58,9 @@ export interface ExecutionArgs<TData = any, TVariables = any, TContext = any> {
     typeResolver?: Maybe<GraphQLTypeResolver<any, TContext>>;
     subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, TContext>>;
     enableEarlyExecution?: Maybe<boolean>;
+    deduplicateDefers?: Maybe<boolean>;
+    sendIncrementalErrorsAsNull?: Maybe<boolean>;
+    sendPathAndLabelOnIncremental?: Maybe<boolean>;
     errorWithIncrementalSubscription?: Maybe<boolean>;
     signal?: AbortSignal;
 }

package/typings/execution/types.d.cts

@@ -54,15 +54,21 @@ interface BareDeferredGroupedFieldSetResult<TData = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLError>;
     data: TData;
 }
-export interface IncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends BareDeferredGroupedFieldSetResult<TData> {
+export interface IncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLError>;
+    data: TData | null;
     id: string;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     subPath?: ReadonlyArray<string | number>;
     extensions?: TExtensions;
 }
 export interface FormattedIncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLFormattedError>;
-    data: TData;
+    data: TData | null;
     id: string;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     subPath?: ReadonlyArray<string | number>;
     extensions?: TExtensions;
 }
@@ -70,16 +76,20 @@ interface BareStreamItemsResult<TData = ReadonlyArray<unknown>> {
     errors?: ReadonlyArray<GraphQLError>;
     items: TData;
 }
-export interface IncrementalStreamResult<TData = ReadonlyArray<unknown>, TExtensions = Record<string, unknown>> extends BareStreamItemsResult<TData> {
+export interface IncrementalStreamResult<TData = ReadonlyArray<unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLError>;
+    items: TData | null;
     id: string;
-    subPath?: ReadonlyArray<string | number>;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     extensions?: TExtensions;
 }
 export interface FormattedIncrementalStreamResult<TData = Array<unknown>, TExtensions = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLFormattedError>;
-    items: TData;
+    items: TData | null;
     id: string;
-    subPath?: ReadonlyArray<string | number>;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     extensions?: TExtensions;
 }
 export type IncrementalResult<TData = unknown, TExtensions = Record<string, unknown>> = IncrementalDeferResult<TData, TExtensions> | IncrementalStreamResult<TData, TExtensions>;
@@ -147,6 +157,7 @@ export type StreamItemRecord = BoxedPromiseOrValue<StreamItemResult> | (() => Bo
 export interface StreamRecord {
     path: Path;
     label: string | undefined;
+    index: number;
     id?: string | undefined;
     streamItemQueue: Array<StreamItemRecord>;
 }

package/typings/execution/types.d.ts

@@ -54,15 +54,21 @@ interface BareDeferredGroupedFieldSetResult<TData = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLError>;
     data: TData;
 }
-export interface IncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends BareDeferredGroupedFieldSetResult<TData> {
+export interface IncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLError>;
+    data: TData | null;
     id: string;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     subPath?: ReadonlyArray<string | number>;
     extensions?: TExtensions;
 }
 export interface FormattedIncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLFormattedError>;
-    data: TData;
+    data: TData | null;
     id: string;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     subPath?: ReadonlyArray<string | number>;
     extensions?: TExtensions;
 }
@@ -70,16 +76,20 @@ interface BareStreamItemsResult<TData = ReadonlyArray<unknown>> {
     errors?: ReadonlyArray<GraphQLError>;
     items: TData;
 }
-export interface IncrementalStreamResult<TData = ReadonlyArray<unknown>, TExtensions = Record<string, unknown>> extends BareStreamItemsResult<TData> {
+export interface IncrementalStreamResult<TData = ReadonlyArray<unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLError>;
+    items: TData | null;
     id: string;
-    subPath?: ReadonlyArray<string | number>;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     extensions?: TExtensions;
 }
 export interface FormattedIncrementalStreamResult<TData = Array<unknown>, TExtensions = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLFormattedError>;
-    items: TData;
+    items: TData | null;
     id: string;
-    subPath?: ReadonlyArray<string | number>;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
     extensions?: TExtensions;
 }
 export type IncrementalResult<TData = unknown, TExtensions = Record<string, unknown>> = IncrementalDeferResult<TData, TExtensions> | IncrementalStreamResult<TData, TExtensions>;
@@ -147,6 +157,7 @@ export type StreamItemRecord = BoxedPromiseOrValue<StreamItemResult> | (() => Bo
 export interface StreamRecord {
     path: Path;
     label: string | undefined;
+    index: number;
     id?: string | undefined;
     streamItemQueue: Array<StreamItemRecord>;
 }