@graphql-tools/executor 4.1.1 → 4.1.2-alpha-20261020170708-72d61a1bbfbf64a0a9d61e801c80001b7ea79dc3

package/esm/execution/incremental.js

@@ -44,6 +44,130 @@ export function deleteAsyncPayload(exeContext, record) {
         record.streamGroup?.release();
     }
 }
+export function pathStartsWith(path, prefix) {
+    if (prefix.length > path.length) {
+        return false;
+    }
+    for (let i = 0; i < prefix.length; i++) {
+        if (path[i] !== prefix[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+export function isAtOrUnderNulledPath(path, nulledPaths) {
+    if (nulledPaths == null || nulledPaths.length === 0) {
+        return false;
+    }
+    for (const nulledPath of nulledPaths) {
+        if (pathStartsWith(path, nulledPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isStrictlyUnderNulledPath(path, nulledPaths) {
+    for (const nulledPath of nulledPaths) {
+        if (path.length > nulledPath.length && pathStartsWith(path, nulledPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isExactNulledPath(path, nulledPaths) {
+    for (const nulledPath of nulledPaths) {
+        if (path.length === nulledPath.length && pathStartsWith(path, nulledPath)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isEmptyIncrementalData(data) {
+    if (data == null) {
+        return true;
+    }
+    if (typeof data !== 'object') {
+        return false;
+    }
+    if (Array.isArray(data)) {
+        return data.length === 0;
+    }
+    const entries = Object.entries(data);
+    if (entries.length === 0) {
+        return true;
+    }
+    return entries.every(([, value]) => value != null && typeof value === 'object' && isEmptyIncrementalData(value));
+}
+/**
+ * Drop keys that would write into a subtree already nulled by error bubbling.
+ * Ancestor deferred records can still deliver sibling fields (e.g. `someField`
+ * next to a nulled `b.c`).
+ */
+export function pruneUnmergeableIncrementalData(data, basePath, nulledPaths) {
+    if (nulledPaths == null || nulledPaths.length === 0 || data == null || typeof data !== 'object') {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map((item, index) => {
+            const itemPath = [...basePath, index];
+            if (isAtOrUnderNulledPath(itemPath, nulledPaths)) {
+                return null;
+            }
+            return pruneUnmergeableIncrementalData(item, itemPath, nulledPaths);
+        });
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const childPath = [...basePath, key];
+        if (isStrictlyUnderNulledPath(childPath, nulledPaths)) {
+            continue;
+        }
+        if (isExactNulledPath(childPath, nulledPaths)) {
+            // Keep a null delivered by this payload; drop a non-null write into an
+            // already-nulled object (Yaacov: unmergeable incremental).
+            if (value != null) {
+                continue;
+            }
+            result[key] = null;
+            continue;
+        }
+        result[key] = pruneUnmergeableIncrementalData(value, childPath, nulledPaths);
+    }
+    return result;
+}
+function isAnnounced(exeContext, record) {
+    const state = exeContext.publisher;
+    if (state == null) {
+        return false;
+    }
+    return state.announced.has(getPublishNode(record));
+}
+/**
+ * Cancel a subsequent record whose path is at or under a nulled position
+ * (graphql-js 17 `hasNulledPosition`). v0.2 records that were already
+ * announced stay in the set so the publisher can emit `completed` without
+ * incremental data.
+ */
+export function cancelAsyncPayload(exeContext, record) {
+    record.cancelled = true;
+    if (isStreamPayload(record) && record.iterator?.return) {
+        record.iterator.return().catch(() => {
+            // ignore error
+        });
+    }
+    if (!record.isCompleted) {
+        if (isStreamPayload(record)) {
+            record.addItems(null);
+        }
+        else {
+            record.addData(null);
+        }
+    }
+    if (exeContext.incrementalSpec === 'v0.2' && isAnnounced(exeContext, record)) {
+        return;
+    }
+    deleteAsyncPayload(exeContext, record);
+}
 export class DeferredFragmentRecord {
     type;
     errors;
@@ -53,7 +177,9 @@ export class DeferredFragmentRecord {
     data;
     parentContext;
     deliveryParent;
+    deferUsage;
     isCompleted;
+    cancelled;
     _exeContext;
     _resolve;
     constructor(opts) {
@@ -62,10 +188,12 @@ export class DeferredFragmentRecord {
         this.path = pathToArray(opts.path);
         this.parentContext = opts.parentContext;
         this.deliveryParent = opts.deliveryParent ?? opts.parentContext;
+        this.deferUsage = opts.deferUsage;
         this.errors = [];
         this._exeContext = opts.exeContext;
         this._exeContext.subsequentPayloads.add(this);
         this.isCompleted = false;
+        this.cancelled = false;
         this.data = null;
         this.promise = new Promise(resolve => {
             this._resolve = MaybePromise => {
@@ -96,6 +224,7 @@ export class StreamRecord {
     iterator;
     isCompletedIterator;
     isCompleted;
+    cancelled;
     streamGroup;
     _exeContext;
     _resolve;
@@ -112,6 +241,7 @@ export class StreamRecord {
         this._exeContext.subsequentPayloads.add(this);
         this.streamGroup?.retain();
         this.isCompleted = false;
+        this.cancelled = false;
         this.items = null;
         this.promise = new Promise(resolve => {
             this._resolve = MaybePromise => {
@@ -178,6 +308,9 @@ function toPendingResult(state, record) {
     return pending;
 }
 function announceIfNeeded(record, state, pending) {
+    if (record.cancelled) {
+        return;
+    }
     const node = getPublishNode(record);
     if (state.announced.has(node)) {
         return;
@@ -210,6 +343,9 @@ function getCompletedIncrementalResults(exeContext) {
             continue;
         }
         deleteAsyncPayload(exeContext, asyncPayloadRecord);
+        if (asyncPayloadRecord.cancelled) {
+            continue;
+        }
         if (isStreamPayload(asyncPayloadRecord)) {
             const items = asyncPayloadRecord.items;
             if (asyncPayloadRecord.isCompletedIterator) {
@@ -219,8 +355,12 @@ function getCompletedIncrementalResults(exeContext) {
             incrementalResult.items = items;
         }
         else {
-            const data = asyncPayloadRecord.data;
-            incrementalResult.data = data ?? null;
+            const data = pruneUnmergeableIncrementalData(asyncPayloadRecord.data, asyncPayloadRecord.path, exeContext.nulledPaths);
+            if (isEmptyIncrementalData(data) && asyncPayloadRecord.errors.length === 0) {
+                continue;
+            }
+            incrementalResult.data =
+                data ?? null;
         }
         incrementalResult.path = asyncPayloadRecord.path;
         if (asyncPayloadRecord.label) {
@@ -260,13 +400,22 @@ function buildSubsequentV02(exeContext, completedRecords) {
                 continue;
             }
             const id = ensureId(state, record);
-            if (record.data == null && record.errors.length > 0) {
+            if (record.cancelled) {
+                completed.push({ id });
+                continue;
+            }
+            const data = pruneUnmergeableIncrementalData(record.data, record.path, exeContext.nulledPaths);
+            if ((record.data == null && record.errors.length > 0) ||
+                (isEmptyIncrementalData(data) && record.errors.length > 0)) {
                 completed.push({ id, errors: record.errors });
             }
+            else if (isEmptyIncrementalData(data) && record.errors.length === 0) {
+                completed.push({ id });
+            }
             else {
                 const incrementalResult = {
                     id,
-                    data: record.data ?? null,
+                    data: data ?? null,
                 };
                 if (record.errors.length > 0) {
                     incrementalResult.errors = record.errors;

package/esm/execution/incrementalCollect.js

@@ -0,0 +1,185 @@
+import { Kind, } from 'graphql';
+import { doesFragmentConditionMatch, getDirectiveValues, getFieldEntryKey, GraphQLDeferDirective, shouldIncludeNode, } from '@graphql-tools/utils';
+import { getBySet } from './getBySet.js';
+import { isSameSet } from './isSameSet.js';
+class FieldDetailsMap extends Map {
+    add(key, item) {
+        const group = this.get(key);
+        if (group === undefined) {
+            this.set(key, [item]);
+        }
+        else {
+            group.push(item);
+        }
+    }
+}
+export function collectIncrementalFields(schema, fragments, variableValues, runtimeType, selectionSet, parentDeferUsage) {
+    const groupedFieldSet = new FieldDetailsMap();
+    const newDeferUsages = [];
+    const context = {
+        schema,
+        fragments,
+        variableValues,
+        runtimeType,
+        visitedFragmentNames: new Map(),
+    };
+    collectFieldsImpl(context, selectionSet, groupedFieldSet, newDeferUsages, parentDeferUsage);
+    return { groupedFieldSet, newDeferUsages };
+}
+const deferUsageByFieldNode = new WeakMap();
+export function collectIncrementalSubfields(schema, fragments, variableValues, returnType, fieldNodes, parentDeferUsage) {
+    const groupedFieldSet = new FieldDetailsMap();
+    const newDeferUsages = [];
+    const context = {
+        schema,
+        fragments,
+        variableValues,
+        runtimeType: returnType,
+        visitedFragmentNames: new Map(),
+    };
+    for (const node of fieldNodes) {
+        if (node.selectionSet) {
+            const deferUsage = deferUsageByFieldNode.has(node)
+                ? deferUsageByFieldNode.get(node)
+                : parentDeferUsage;
+            collectFieldsImpl(context, node.selectionSet, groupedFieldSet, newDeferUsages, deferUsage);
+        }
+    }
+    return { groupedFieldSet, newDeferUsages };
+}
+function collectFieldsImpl(context, selectionSet, groupedFieldSet, newDeferUsages, deferUsage) {
+    const { schema, fragments, variableValues, runtimeType, visitedFragmentNames } = context;
+    for (const selection of selectionSet.selections) {
+        switch (selection.kind) {
+            case Kind.FIELD: {
+                if (!shouldIncludeNode(variableValues, selection)) {
+                    continue;
+                }
+                groupedFieldSet.add(getFieldEntryKey(selection), {
+                    node: selection,
+                    deferUsage,
+                });
+                break;
+            }
+            case Kind.INLINE_FRAGMENT: {
+                if (!shouldIncludeNode(variableValues, selection) ||
+                    !doesFragmentConditionMatch(schema, selection, runtimeType)) {
+                    continue;
+                }
+                const newDeferUsage = getDeferUsage(variableValues, selection, deferUsage);
+                if (!newDeferUsage) {
+                    collectFieldsImpl(context, selection.selectionSet, groupedFieldSet, newDeferUsages, deferUsage);
+                }
+                else {
+                    newDeferUsages.push(newDeferUsage);
+                    collectFieldsImpl(context, selection.selectionSet, groupedFieldSet, newDeferUsages, newDeferUsage);
+                }
+                break;
+            }
+            case Kind.FRAGMENT_SPREAD: {
+                const fragName = selection.name.value;
+                if (!shouldIncludeNode(variableValues, selection)) {
+                    continue;
+                }
+                const fragment = fragments[fragName];
+                if (!fragment || !doesFragmentConditionMatch(schema, fragment, runtimeType)) {
+                    continue;
+                }
+                const newDeferUsage = getDeferUsage(variableValues, selection, deferUsage);
+                const visitedAsDeferred = visitedFragmentNames.get(fragName);
+                let maybeNewDeferUsage;
+                if (!newDeferUsage) {
+                    if (visitedAsDeferred === false) {
+                        continue;
+                    }
+                    visitedFragmentNames.set(fragName, false);
+                    maybeNewDeferUsage = deferUsage;
+                }
+                else {
+                    if (visitedAsDeferred !== undefined) {
+                        continue;
+                    }
+                    visitedFragmentNames.set(fragName, true);
+                    newDeferUsages.push(newDeferUsage);
+                    maybeNewDeferUsage = newDeferUsage;
+                }
+                collectFieldsImpl(context, fragment.selectionSet, groupedFieldSet, newDeferUsages, maybeNewDeferUsage);
+                break;
+            }
+        }
+    }
+}
+function getDeferUsage(variableValues, node, parentDeferUsage) {
+    const defer = getDirectiveValues(GraphQLDeferDirective, node, variableValues);
+    if (!defer || defer['if'] === false) {
+        return;
+    }
+    return {
+        label: typeof defer['label'] === 'string' ? defer['label'] : undefined,
+        parentDeferUsage,
+    };
+}
+export function buildExecutionPlan(originalGroupedFieldSet, parentDeferUsages = new Set()) {
+    const groupedFieldSet = new Map();
+    const newGroupedFieldSets = new Map();
+    for (const [responseKey, fieldDetailsList] of originalGroupedFieldSet) {
+        const filteredDeferUsageSet = getFilteredDeferUsageSet(fieldDetailsList);
+        if (isSameSet(filteredDeferUsageSet, parentDeferUsages)) {
+            groupedFieldSet.set(responseKey, fieldDetailsList);
+            continue;
+        }
+        let newGroupedFieldSet = getBySet(newGroupedFieldSets, filteredDeferUsageSet);
+        if (newGroupedFieldSet === undefined) {
+            newGroupedFieldSet = new Map();
+            newGroupedFieldSets.set(filteredDeferUsageSet, newGroupedFieldSet);
+        }
+        newGroupedFieldSet.set(responseKey, fieldDetailsList);
+    }
+    return { groupedFieldSet, newGroupedFieldSets };
+}
+function getFilteredDeferUsageSet(fieldDetailsList) {
+    const filteredDeferUsageSet = new Set();
+    for (const fieldDetails of fieldDetailsList) {
+        const deferUsage = fieldDetails.deferUsage;
+        if (deferUsage === undefined) {
+            filteredDeferUsageSet.clear();
+            return filteredDeferUsageSet;
+        }
+        filteredDeferUsageSet.add(deferUsage);
+    }
+    for (const deferUsage of filteredDeferUsageSet) {
+        let parentDeferUsage = deferUsage.parentDeferUsage;
+        while (parentDeferUsage !== undefined) {
+            if (filteredDeferUsageSet.has(parentDeferUsage)) {
+                filteredDeferUsageSet.delete(deferUsage);
+                break;
+            }
+            parentDeferUsage = parentDeferUsage.parentDeferUsage;
+        }
+    }
+    return filteredDeferUsageSet;
+}
+export function deferUsageForFieldNode(node) {
+    return deferUsageByFieldNode.get(node);
+}
+export function groupedFieldSetToFieldMap(groupedFieldSet) {
+    const fields = new Map();
+    for (const [responseKey, fieldDetailsList] of groupedFieldSet) {
+        fields.set(responseKey, fieldDetailsList.map(details => {
+            deferUsageByFieldNode.set(details.node, details.deferUsage);
+            return details.node;
+        }));
+    }
+    return fields;
+}
+export function rootDeferUsage(deferUsageSet) {
+    for (const usage of deferUsageSet) {
+        if (usage.parentDeferUsage == null || !deferUsageSet.has(usage.parentDeferUsage)) {
+            return usage;
+        }
+    }
+    return undefined;
+}
+export function labelForDeferUsageSet(deferUsageSet) {
+    return rootDeferUsage(deferUsageSet)?.label;
+}

package/esm/execution/isSameSet.js

@@ -0,0 +1,12 @@
+/** @internal */
+export function isSameSet(setA, setB) {
+    if (setA.size !== setB.size) {
+        return false;
+    }
+    for (const item of setA) {
+        if (!setB.has(item)) {
+            return false;
+        }
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphql-tools/executor",
-  "version": "4.1.1",
+  "version": "4.1.2-alpha-20261020170708-72d61a1bbfbf64a0a9d61e801c80001b7ea79dc3",
   "sideEffects": false,
   "peerDependencies": {
     "graphql": "^16.0.0 || ^17.0.0"

package/typings/execution/execute.d.cts

@@ -1,8 +1,9 @@
-import { DocumentNode, FieldNode, FragmentDefinitionNode, GraphQLError, GraphQLField, GraphQLFieldResolver, GraphQLFormattedError, GraphQLObjectType, GraphQLSchema, GraphQLTypeResolver, OperationDefinitionNode } from 'graphql';
+import { defaultFieldResolver, defaultTypeResolver, DocumentNode, FieldNode, FragmentDefinitionNode, GraphQLError, GraphQLField, GraphQLFieldResolver, GraphQLFormattedError, GraphQLObjectType, GraphQLSchema, GraphQLTypeResolver, OperationDefinitionNode } from 'graphql';
 import { GraphQLResolveInfo, Maybe, Path, VariableValues, type IncrementalSpec } from '@graphql-tools/utils';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { type MaybePromise } from '@whatwg-node/promise-helpers';
 import { type AsyncPayloadRecord, type CompletedResult, type IncrementalPublisherState, type PendingResult } from './incremental.cjs';
+export { defaultFieldResolver, defaultTypeResolver };
 export type { CompletedResult, PendingResult } from './incremental.cjs';
 export interface SingularExecutionResult<TData = any, TExtensions = any> {
     errors?: ReadonlyArray<GraphQLError>;
@@ -50,6 +51,11 @@ export interface ExecutionContext<TVariables = any, TContext = any> {
     subsequentPayloads: Set<AsyncPayloadRecord>;
     incrementalSpec: IncrementalSpec;
     publisher?: IncrementalPublisherState;
+    /**
+     * Allocated only when the operation actually uses @defer/@stream so
+     * default execution does not pay for null-bubble bookkeeping.
+     */
+    nulledPaths?: Array<ReadonlyArray<string | number>>;
     signal?: AbortSignal;
     getAbortSignal: () => AbortSignal | undefined;
     getAsyncHelpers: () => {
@@ -196,24 +202,6 @@ export declare function buildExecutionContext<TData = any, TVariables = any, TCo
  */
 export declare function buildResolveInfo(exeContext: ExecutionContext, fieldDef: GraphQLField<unknown, unknown>, fieldNodes: Array<FieldNode>, parentType: GraphQLObjectType, path: Path): GraphQLResolveInfo;
 export declare const CRITICAL_ERROR: 'CRITICAL_ERROR';
-/**
- * If a resolveType function is not given, then a default resolve behavior is
- * used which attempts two strategies:
- *
- * First, See if the provided value has a `__typename` field defined, if so, use
- * that value as name of the resolved type.
- *
- * Otherwise, test each possible type for the abstract type by calling
- * isTypeOf for the object being coerced, returning the first type that matches.
- */
-export declare const defaultTypeResolver: GraphQLTypeResolver<unknown, unknown>;
-/**
- * If a resolve function is not given, then a default resolve behavior is used
- * which takes the property of the source object of the same name as the field
- * and returns it as the result, or if it's a function, returns the result
- * of calling that function while passing along args and context value.
- */
-export declare const defaultFieldResolver: GraphQLFieldResolver<unknown, unknown>;
 /**
  * Implements the "Subscribe" algorithm described in the GraphQL specification,
  * including `@defer` and `@stream` as proposed in

package/typings/execution/execute.d.ts

@@ -1,8 +1,9 @@
-import { DocumentNode, FieldNode, FragmentDefinitionNode, GraphQLError, GraphQLField, GraphQLFieldResolver, GraphQLFormattedError, GraphQLObjectType, GraphQLSchema, GraphQLTypeResolver, OperationDefinitionNode } from 'graphql';
+import { defaultFieldResolver, defaultTypeResolver, DocumentNode, FieldNode, FragmentDefinitionNode, GraphQLError, GraphQLField, GraphQLFieldResolver, GraphQLFormattedError, GraphQLObjectType, GraphQLSchema, GraphQLTypeResolver, OperationDefinitionNode } from 'graphql';
 import { GraphQLResolveInfo, Maybe, Path, VariableValues, type IncrementalSpec } from '@graphql-tools/utils';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { type MaybePromise } from '@whatwg-node/promise-helpers';
 import { type AsyncPayloadRecord, type CompletedResult, type IncrementalPublisherState, type PendingResult } from './incremental.js';
+export { defaultFieldResolver, defaultTypeResolver };
 export type { CompletedResult, PendingResult } from './incremental.js';
 export interface SingularExecutionResult<TData = any, TExtensions = any> {
     errors?: ReadonlyArray<GraphQLError>;
@@ -50,6 +51,11 @@ export interface ExecutionContext<TVariables = any, TContext = any> {
     subsequentPayloads: Set<AsyncPayloadRecord>;
     incrementalSpec: IncrementalSpec;
     publisher?: IncrementalPublisherState;
+    /**
+     * Allocated only when the operation actually uses @defer/@stream so
+     * default execution does not pay for null-bubble bookkeeping.
+     */
+    nulledPaths?: Array<ReadonlyArray<string | number>>;
     signal?: AbortSignal;
     getAbortSignal: () => AbortSignal | undefined;
     getAsyncHelpers: () => {
@@ -196,24 +202,6 @@ export declare function buildExecutionContext<TData = any, TVariables = any, TCo
  */
 export declare function buildResolveInfo(exeContext: ExecutionContext, fieldDef: GraphQLField<unknown, unknown>, fieldNodes: Array<FieldNode>, parentType: GraphQLObjectType, path: Path): GraphQLResolveInfo;
 export declare const CRITICAL_ERROR: 'CRITICAL_ERROR';
-/**
- * If a resolveType function is not given, then a default resolve behavior is
- * used which attempts two strategies:
- *
- * First, See if the provided value has a `__typename` field defined, if so, use
- * that value as name of the resolved type.
- *
- * Otherwise, test each possible type for the abstract type by calling
- * isTypeOf for the object being coerced, returning the first type that matches.
- */
-export declare const defaultTypeResolver: GraphQLTypeResolver<unknown, unknown>;
-/**
- * If a resolve function is not given, then a default resolve behavior is used
- * which takes the property of the source object of the same name as the field
- * and returns it as the result, or if it's a function, returns the result
- * of calling that function while passing along args and context value.
- */
-export declare const defaultFieldResolver: GraphQLFieldResolver<unknown, unknown>;
 /**
  * Implements the "Subscribe" algorithm described in the GraphQL specification,
  * including `@defer` and `@stream` as proposed in

package/typings/execution/getBySet.d.cts

@@ -0,0 +1,2 @@
+/** @internal */
+export declare function getBySet<T, U>(map: ReadonlyMap<ReadonlySet<T>, U>, setToMatch: ReadonlySet<T>): U | undefined;

package/typings/execution/getBySet.d.ts

@@ -0,0 +1,2 @@
+/** @internal */
+export declare function getBySet<T, U>(map: ReadonlyMap<ReadonlySet<T>, U>, setToMatch: ReadonlySet<T>): U | undefined;

package/typings/execution/incremental.d.cts

@@ -2,6 +2,7 @@ import { GraphQLError } from 'graphql';
 import { Path, type IncrementalSpec } from '@graphql-tools/utils';
 import { type MaybePromise } from '@whatwg-node/promise-helpers';
 import type { SubsequentIncrementalExecutionResult } from './execute.cjs';
+import type { DeferUsage } from './incrementalCollect.cjs';
 export interface PendingResult {
     id: string;
     path: ReadonlyArray<string | number>;
@@ -23,6 +24,11 @@ export interface IncrementalPublisherContext {
     incrementalSpec: IncrementalSpec;
     publisher?: IncrementalPublisherState;
     signalPromise?: Promise<never>;
+    /**
+     * Paths that were set to null by error bubbling. Present only on the
+     * incremental collect path so default execution does not allocate.
+     */
+    nulledPaths?: Array<ReadonlyArray<string | number>>;
 }
 export declare class StreamGroup {
     path: Array<string | number>;
@@ -48,6 +54,21 @@ export declare function createStreamGroupIfV02(exeContext: IncrementalPublisherC
     hasIterator?: boolean;
 }): StreamGroup | undefined;
 export declare function deleteAsyncPayload(exeContext: IncrementalPublisherContext, record: AsyncPayloadRecord): void;
+export declare function pathStartsWith(path: ReadonlyArray<string | number>, prefix: ReadonlyArray<string | number>): boolean;
+export declare function isAtOrUnderNulledPath(path: ReadonlyArray<string | number>, nulledPaths: ReadonlyArray<ReadonlyArray<string | number>> | undefined): boolean;
+/**
+ * Drop keys that would write into a subtree already nulled by error bubbling.
+ * Ancestor deferred records can still deliver sibling fields (e.g. `someField`
+ * next to a nulled `b.c`).
+ */
+export declare function pruneUnmergeableIncrementalData(data: unknown, basePath: ReadonlyArray<string | number>, nulledPaths: ReadonlyArray<ReadonlyArray<string | number>> | undefined): unknown;
+/**
+ * Cancel a subsequent record whose path is at or under a nulled position
+ * (graphql-js 17 `hasNulledPosition`). v0.2 records that were already
+ * announced stay in the set so the publisher can emit `completed` without
+ * incremental data.
+ */
+export declare function cancelAsyncPayload(exeContext: IncrementalPublisherContext, record: AsyncPayloadRecord): void;
 export declare class DeferredFragmentRecord {
     type: 'defer';
     errors: Array<GraphQLError>;
@@ -57,7 +78,9 @@ export declare class DeferredFragmentRecord {
     data: Record<string, unknown> | null;
     parentContext: AsyncPayloadRecord | undefined;
     deliveryParent: AsyncPayloadRecord | undefined;
+    deferUsage: DeferUsage | undefined;
     isCompleted: boolean;
+    cancelled: boolean;
     _exeContext: IncrementalPublisherContext;
     _resolve?: (arg: MaybePromise<Record<string, unknown> | null>) => void;
     constructor(opts: {
@@ -66,6 +89,7 @@ export declare class DeferredFragmentRecord {
         parentContext: AsyncPayloadRecord | undefined;
         deliveryParent?: AsyncPayloadRecord | undefined;
         exeContext: IncrementalPublisherContext;
+        deferUsage?: DeferUsage;
     });
     addData(data: MaybePromise<Record<string, unknown> | null>): void;
 }
@@ -80,6 +104,7 @@ export declare class StreamRecord {
     iterator: AsyncIterator<unknown> | undefined;
     isCompletedIterator?: boolean;
     isCompleted: boolean;
+    cancelled: boolean;
     streamGroup: StreamGroup | undefined;
     _exeContext: IncrementalPublisherContext;
     _resolve?: (arg: MaybePromise<Array<unknown> | null>) => void;

package/typings/execution/incremental.d.ts

@@ -2,6 +2,7 @@ import { GraphQLError } from 'graphql';
 import { Path, type IncrementalSpec } from '@graphql-tools/utils';
 import { type MaybePromise } from '@whatwg-node/promise-helpers';
 import type { SubsequentIncrementalExecutionResult } from './execute.js';
+import type { DeferUsage } from './incrementalCollect.js';
 export interface PendingResult {
     id: string;
     path: ReadonlyArray<string | number>;
@@ -23,6 +24,11 @@ export interface IncrementalPublisherContext {
     incrementalSpec: IncrementalSpec;
     publisher?: IncrementalPublisherState;
     signalPromise?: Promise<never>;
+    /**
+     * Paths that were set to null by error bubbling. Present only on the
+     * incremental collect path so default execution does not allocate.
+     */
+    nulledPaths?: Array<ReadonlyArray<string | number>>;
 }
 export declare class StreamGroup {
     path: Array<string | number>;
@@ -48,6 +54,21 @@ export declare function createStreamGroupIfV02(exeContext: IncrementalPublisherC
     hasIterator?: boolean;
 }): StreamGroup | undefined;
 export declare function deleteAsyncPayload(exeContext: IncrementalPublisherContext, record: AsyncPayloadRecord): void;
+export declare function pathStartsWith(path: ReadonlyArray<string | number>, prefix: ReadonlyArray<string | number>): boolean;
+export declare function isAtOrUnderNulledPath(path: ReadonlyArray<string | number>, nulledPaths: ReadonlyArray<ReadonlyArray<string | number>> | undefined): boolean;
+/**
+ * Drop keys that would write into a subtree already nulled by error bubbling.
+ * Ancestor deferred records can still deliver sibling fields (e.g. `someField`
+ * next to a nulled `b.c`).
+ */
+export declare function pruneUnmergeableIncrementalData(data: unknown, basePath: ReadonlyArray<string | number>, nulledPaths: ReadonlyArray<ReadonlyArray<string | number>> | undefined): unknown;
+/**
+ * Cancel a subsequent record whose path is at or under a nulled position
+ * (graphql-js 17 `hasNulledPosition`). v0.2 records that were already
+ * announced stay in the set so the publisher can emit `completed` without
+ * incremental data.
+ */
+export declare function cancelAsyncPayload(exeContext: IncrementalPublisherContext, record: AsyncPayloadRecord): void;
 export declare class DeferredFragmentRecord {
     type: 'defer';
     errors: Array<GraphQLError>;
@@ -57,7 +78,9 @@ export declare class DeferredFragmentRecord {
     data: Record<string, unknown> | null;
     parentContext: AsyncPayloadRecord | undefined;
     deliveryParent: AsyncPayloadRecord | undefined;
+    deferUsage: DeferUsage | undefined;
     isCompleted: boolean;
+    cancelled: boolean;
     _exeContext: IncrementalPublisherContext;
     _resolve?: (arg: MaybePromise<Record<string, unknown> | null>) => void;
     constructor(opts: {
@@ -66,6 +89,7 @@ export declare class DeferredFragmentRecord {
         parentContext: AsyncPayloadRecord | undefined;
         deliveryParent?: AsyncPayloadRecord | undefined;
         exeContext: IncrementalPublisherContext;
+        deferUsage?: DeferUsage;
     });
     addData(data: MaybePromise<Record<string, unknown> | null>): void;
 }
@@ -80,6 +104,7 @@ export declare class StreamRecord {
     iterator: AsyncIterator<unknown> | undefined;
     isCompletedIterator?: boolean;
     isCompleted: boolean;
+    cancelled: boolean;
     streamGroup: StreamGroup | undefined;
     _exeContext: IncrementalPublisherContext;
     _resolve?: (arg: MaybePromise<Array<unknown> | null>) => void;