@graphql-tools/executor 0.0.2 → 0.0.3-alpha-20221031181646-cd48ed2f

package/esm/execution/flattenAsyncIterable.js

@@ -0,0 +1,87 @@
+/**
+ * Given an AsyncIterable of AsyncIterables, flatten all yielded results into a
+ * single AsyncIterable.
+ */
+export function flattenAsyncIterable(iterable) {
+    // You might think this whole function could be replaced with
+    //
+    //    async function* flattenAsyncIterable(iterable) {
+    //      for await (const subIterator of iterable) {
+    //        yield* subIterator;
+    //      }
+    //    }
+    //
+    // but calling `.return()` on the iterator it returns won't interrupt the `for await`.
+    const topIterator = iterable[Symbol.asyncIterator]();
+    let currentNestedIterator;
+    let waitForCurrentNestedIterator;
+    let done = false;
+    async function next() {
+        if (done) {
+            return { value: undefined, done: true };
+        }
+        try {
+            if (!currentNestedIterator) {
+                // Somebody else is getting it already.
+                if (waitForCurrentNestedIterator) {
+                    await waitForCurrentNestedIterator;
+                    return await next();
+                }
+                // Nobody else is getting it. We should!
+                let resolve;
+                waitForCurrentNestedIterator = new Promise(r => {
+                    resolve = r;
+                });
+                const topIteratorResult = await topIterator.next();
+                if (topIteratorResult.done) {
+                    // Given that done only ever transitions from false to true,
+                    // require-atomic-updates is being unnecessarily cautious.
+                    done = true;
+                    return await next();
+                }
+                // eslint is making a reasonable point here, but we've explicitly protected
+                // ourself from the race condition by ensuring that only the single call
+                // that assigns to waitForCurrentNestedIterator is allowed to assign to
+                // currentNestedIterator or waitForCurrentNestedIterator.
+                currentNestedIterator = topIteratorResult.value[Symbol.asyncIterator]();
+                waitForCurrentNestedIterator = undefined;
+                resolve();
+                return await next();
+            }
+            const rememberCurrentNestedIterator = currentNestedIterator;
+            const nestedIteratorResult = await currentNestedIterator.next();
+            if (!nestedIteratorResult.done) {
+                return nestedIteratorResult;
+            }
+            // The nested iterator is done. If it's still the current one, make it not
+            // current. (If it's not the current one, somebody else has made us move on.)
+            if (currentNestedIterator === rememberCurrentNestedIterator) {
+                currentNestedIterator = undefined;
+            }
+            return await next();
+        }
+        catch (err) {
+            done = true;
+            throw err;
+        }
+    }
+    return {
+        next,
+        async return() {
+            var _a, _b;
+            done = true;
+            await Promise.all([(_a = currentNestedIterator === null || currentNestedIterator === void 0 ? void 0 : currentNestedIterator.return) === null || _a === void 0 ? void 0 : _a.call(currentNestedIterator), (_b = topIterator.return) === null || _b === void 0 ? void 0 : _b.call(topIterator)]);
+            return { value: undefined, done: true };
+        },
+        async throw(error) {
+            var _a, _b;
+            done = true;
+            await Promise.all([(_a = currentNestedIterator === null || currentNestedIterator === void 0 ? void 0 : currentNestedIterator.throw) === null || _a === void 0 ? void 0 : _a.call(currentNestedIterator, error), (_b = topIterator.throw) === null || _b === void 0 ? void 0 : _b.call(topIterator, error)]);
+            /* c8 ignore next */
+            throw error;
+        },
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+}

package/esm/execution/invariant.js

@@ -0,0 +1,5 @@
+export function invariant(condition, message) {
+    if (!condition) {
+        throw new Error(message != null ? message : 'Unexpected invariant triggered.');
+    }
+}

package/esm/execution/promiseForObject.js

@@ -0,0 +1,17 @@
+/**
+ * This function transforms a JS object `Record<string, Promise<T>>` into
+ * a `Promise<Record<string, T>>`
+ *
+ * This is akin to bluebird's `Promise.props`, but implemented only using
+ * `Promise.all` so it will work with any implementation of ES6 promises.
+ */
+export async function promiseForObject(object) {
+    const keys = Object.keys(object);
+    const values = Object.values(object);
+    const resolvedValues = await Promise.all(values);
+    const resolvedObject = Object.create(null);
+    for (let i = 0; i < keys.length; ++i) {
+        resolvedObject[keys[i]] = resolvedValues[i];
+    }
+    return resolvedObject;
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@graphql-tools/executor",
-  "version": "0.0.2",
+  "version": "0.0.3-alpha-20221031181646-cd48ed2f",
   "sideEffects": false,
   "peerDependencies": {
     "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
   },
   "dependencies": {
-    "@graphql-tools/utils": "8.13.1",
+    "@graphql-tools/utils": "9.0.0-alpha-20221031181646-cd48ed2f",
     "@graphql-typed-document-node/core": "3.1.1"
   },
   "repository": {

package/typings/execution/execute.d.cts

@@ -1,5 +1,6 @@
-import { GraphQLFormattedError, GraphQLError, FieldNode, FragmentDefinitionNode, OperationDefinitionNode, GraphQLField, GraphQLFieldResolver, GraphQLObjectType, GraphQLResolveInfo, GraphQLTypeResolver, GraphQLSchema } from 'graphql';
-import { Maybe, Path, MaybePromise, ExecutionResult } from '@graphql-tools/utils';
+import { GraphQLFormattedError, FieldNode, FragmentDefinitionNode, OperationDefinitionNode, GraphQLField, GraphQLFieldResolver, GraphQLObjectType, GraphQLResolveInfo, GraphQLTypeResolver, GraphQLSchema } from 'graphql';
+import type { GraphQLError } from 'graphql';
+import { Path, Maybe, MaybePromise, ExecutionResult } from '@graphql-tools/utils';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 /**
  * Terminology
@@ -26,25 +27,72 @@ import { TypedDocumentNode } from '@graphql-typed-document-node/core';
  * Namely, schema of the type system that is currently executing,
  * and the fragments defined in the query document
  */
-export interface ExecutionContext<TContext = any> {
+export interface ExecutionContext<TVariables = any, TContext = any> {
     schema: GraphQLSchema;
     fragments: Record<string, FragmentDefinitionNode>;
     rootValue: unknown;
     contextValue: TContext;
     operation: OperationDefinitionNode;
-    variableValues: {
-        [variable: string]: unknown;
-    };
+    variableValues: TVariables;
     fieldResolver: GraphQLFieldResolver<any, TContext>;
     typeResolver: GraphQLTypeResolver<any, TContext>;
     subscribeFieldResolver: GraphQLFieldResolver<any, TContext>;
     errors: Array<GraphQLError>;
+    subsequentPayloads: Set<AsyncPayloadRecord>;
 }
-export interface FormattedExecutionResult<TData = any, TExtensions = any> {
+export interface FormattedExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLFormattedError>;
     data?: TData | null;
     extensions?: TExtensions;
 }
+export interface ExperimentalIncrementalExecutionResults<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    initialResult: InitialIncrementalExecutionResult<TData, TExtensions>;
+    subsequentResults: AsyncGenerator<SubsequentIncrementalExecutionResult<TData, TExtensions>, void, void>;
+}
+export interface InitialIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends ExecutionResult<TData, TExtensions> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<IncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface FormattedInitialIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends FormattedExecutionResult<TData, TExtensions> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<FormattedIncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface SubsequentIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<IncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface FormattedSubsequentIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<FormattedIncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface IncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends ExecutionResult<TData, TExtensions> {
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+}
+export interface FormattedIncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends FormattedExecutionResult<TData, TExtensions> {
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+}
+export interface IncrementalStreamResult<TData = Array<unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLError>;
+    items?: TData | null;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+    extensions?: TExtensions;
+}
+export interface FormattedIncrementalStreamResult<TData = Array<unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLFormattedError>;
+    items?: TData | null;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+    extensions?: TExtensions;
+}
+export declare type IncrementalResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> = IncrementalDeferResult<TData, TExtensions> | IncrementalStreamResult<TData, TExtensions>;
+export declare type FormattedIncrementalResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> = FormattedIncrementalDeferResult<TData, TExtensions> | FormattedIncrementalStreamResult<TData, TExtensions>;
 export interface ExecutionArgs<TData = any, TVariables = any, TContext = any> {
     schema: GraphQLSchema;
     document: TypedDocumentNode<TData, TVariables>;
@@ -65,12 +113,27 @@ export interface ExecutionArgs<TData = any, TVariables = any, TContext = any> {
  *
  * If the arguments to this function do not result in a legal execution context,
  * a GraphQLError will be thrown immediately explaining the invalid input.
+ *
+ * This function does not support incremental delivery (`@defer` and `@stream`).
+ * If an operation which would defer or stream data is executed with this
+ * function, it will throw or resolve to an object containing an error instead.
+ * Use `experimentalExecuteIncrementally` if you want to support incremental
+ * delivery.
+ */
+export declare function execute<TData = any, TVariables = any, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): MaybePromise<ExecutionResult<TData>>;
+/**
+ * Implements the "Executing requests" section of the GraphQL specification,
+ * including `@defer` and `@stream` as proposed in
+ * https://github.com/graphql/graphql-spec/pull/742
+ *
+ * This function returns a Promise of an ExperimentalIncrementalExecutionResults
+ * object. This object either consists of a single ExecutionResult, or an
+ * object containing an `initialResult` and a stream of `subsequentResults`.
+ *
+ * If the arguments to this function do not result in a legal execution context,
+ * a GraphQLError will be thrown immediately explaining the invalid input.
  */
-export declare function execute<TData = {
-    [key: string]: any;
-}, TVariables = {
-    [key: string]: any;
-}, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): MaybePromise<ExecutionResult<TData>>;
+export declare function experimentalExecuteIncrementally<TData = any, TVariables = any, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): MaybePromise<ExecutionResult<TData> | ExperimentalIncrementalExecutionResults<TData>>;
 /**
  * Also implements the "Executing requests" section of the GraphQL specification.
  * However, it guarantees to complete synchronously (or throw an error) assuming
@@ -93,16 +156,12 @@ export declare function assertValidExecutionArguments<TVariables>(schema: GraphQ
  * TODO: consider no longer exporting this function
  * @internal
  */
-export declare function buildExecutionContext<TData = {
-    [key: string]: any;
-}, TVariables = {
-    [key: string]: any;
-}, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): ReadonlyArray<GraphQLError> | ExecutionContext;
+export declare function buildExecutionContext<TData = any, TVariables = any, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): ReadonlyArray<GraphQLError> | ExecutionContext;
 /**
  * TODO: consider no longer exporting this function
  * @internal
  */
-export declare function buildResolveInfo(exeContext: ExecutionContext, fieldDef: GraphQLField<unknown, unknown>, fieldNodes: ReadonlyArray<FieldNode>, parentType: GraphQLObjectType, path: Path): GraphQLResolveInfo;
+export declare function buildResolveInfo(exeContext: ExecutionContext, fieldDef: GraphQLField<unknown, unknown>, fieldNodes: Array<FieldNode>, parentType: GraphQLObjectType, path: Path): GraphQLResolveInfo;
 /**
  * If a resolveType function is not given, then a default resolve behavior is
  * used which attempts two strategies:
@@ -130,19 +189,61 @@ export declare const defaultFieldResolver: GraphQLFieldResolver<unknown, unknown
  * is not an async iterable.
  *
  * If the client-provided arguments to this function do not result in a
- * compliant subscription, a GraphQL Response (ExecutionResult) with
- * descriptive errors and no data will be returned.
+ * compliant subscription, a GraphQL Response (ExecutionResult) with descriptive
+ * errors and no data will be returned.
  *
- * If the source stream could not be created due to faulty subscription
- * resolver logic or underlying systems, the promise will resolve to a single
+ * If the source stream could not be created due to faulty subscription resolver
+ * logic or underlying systems, the promise will resolve to a single
  * ExecutionResult containing `errors` and no `data`.
  *
  * If the operation succeeded, the promise resolves to an AsyncIterator, which
  * yields a stream of ExecutionResults representing the response stream.
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * This function does not support incremental delivery (`@defer` and `@stream`).
+ * If an operation which would defer or stream data is executed with this
+ * function, each `InitialIncrementalExecutionResult` and
+ * `SubsequentIncrementalExecutionResult` in the result stream will be replaced
+ * with an `ExecutionResult` with a single error stating that defer/stream is
+ * not supported.  Use `experimentalSubscribeIncrementally` if you want to
+ * support incremental delivery.
+ *
+ * Accepts an object with named arguments.
  */
 export declare function subscribe(args: ExecutionArgs): MaybePromise<AsyncIterable<ExecutionResult> | ExecutionResult>;
+/**
+ * Implements the "Subscribe" algorithm described in the GraphQL specification,
+ * including `@defer` and `@stream` as proposed in
+ * https://github.com/graphql/graphql-spec/pull/742
+ *
+ * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * or an ExecutionResult (error). The promise will be rejected if the schema or
+ * other arguments to this function are invalid, or if the resolved event stream
+ * is not an async iterable.
+ *
+ * If the client-provided arguments to this function do not result in a
+ * compliant subscription, a GraphQL Response (ExecutionResult) with descriptive
+ * errors and no data will be returned.
+ *
+ * If the source stream could not be created due to faulty subscription resolver
+ * logic or underlying systems, the promise will resolve to a single
+ * ExecutionResult containing `errors` and no `data`.
+ *
+ * If the operation succeeded, the promise resolves to an AsyncIterator, which
+ * yields a stream of result representing the response stream.
+ *
+ * Each result may be an ExecutionResult with no `hasNext` (if executing the
+ * event did not use `@defer` or `@stream`), or an
+ * `InitialIncrementalExecutionResult` or `SubsequentIncrementalExecutionResult`
+ * (if executing the event used `@defer` or `@stream`). In the case of
+ * incremental execution results, each event produces a single
+ * `InitialIncrementalExecutionResult` followed by one or more
+ * `SubsequentIncrementalExecutionResult`s; all but the last have `hasNext: true`,
+ * and the last has `hasNext: false`. There is no interleaving between results
+ * generated from the same original event.
+ *
+ * Accepts an object with named arguments.
+ */
+export declare function experimentalSubscribeIncrementally(args: ExecutionArgs): MaybePromise<AsyncGenerator<ExecutionResult | InitialIncrementalExecutionResult | SubsequentIncrementalExecutionResult, void, void> | ExecutionResult>;
 /**
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
@@ -172,6 +273,49 @@ export declare function subscribe(args: ExecutionArgs): MaybePromise<AsyncIterab
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
  */
 export declare function createSourceEventStream(args: ExecutionArgs): MaybePromise<AsyncIterable<unknown> | ExecutionResult>;
+declare class DeferredFragmentRecord {
+    type: 'defer';
+    errors: Array<GraphQLError>;
+    label: string | undefined;
+    path: Array<string | number>;
+    promise: Promise<void>;
+    data: Record<string, unknown> | null;
+    parentContext: AsyncPayloadRecord | undefined;
+    isCompleted: boolean;
+    _exeContext: ExecutionContext;
+    _resolve?: (arg: MaybePromise<Record<string, unknown> | null>) => void;
+    constructor(opts: {
+        label: string | undefined;
+        path: Path | undefined;
+        parentContext: AsyncPayloadRecord | undefined;
+        exeContext: ExecutionContext;
+    });
+    addData(data: MaybePromise<Record<string, unknown> | null>): void;
+}
+declare class StreamRecord {
+    type: 'stream';
+    errors: Array<GraphQLError>;
+    label: string | undefined;
+    path: Array<string | number>;
+    items: Array<unknown> | null;
+    promise: Promise<void>;
+    parentContext: AsyncPayloadRecord | undefined;
+    iterator: AsyncIterator<unknown> | undefined;
+    isCompletedIterator?: boolean;
+    isCompleted: boolean;
+    _exeContext: ExecutionContext;
+    _resolve?: (arg: MaybePromise<Array<unknown> | null>) => void;
+    constructor(opts: {
+        label: string | undefined;
+        path: Path | undefined;
+        iterator?: AsyncIterator<unknown>;
+        parentContext: AsyncPayloadRecord | undefined;
+        exeContext: ExecutionContext;
+    });
+    addItems(items: MaybePromise<Array<unknown> | null>): void;
+    setIsCompletedIterator(): void;
+}
+declare type AsyncPayloadRecord = DeferredFragmentRecord | StreamRecord;
 /**
  * This method looks up the field on the given type definition.
  * It has special casing for the three introspection fields,
@@ -184,3 +328,4 @@ export declare function createSourceEventStream(args: ExecutionArgs): MaybePromi
  * @internal
  */
 export declare function getFieldDef(schema: GraphQLSchema, parentType: GraphQLObjectType, fieldNode: FieldNode): Maybe<GraphQLField<unknown, unknown>>;
+export {};

package/typings/execution/execute.d.ts

@@ -1,5 +1,6 @@
-import { GraphQLFormattedError, GraphQLError, FieldNode, FragmentDefinitionNode, OperationDefinitionNode, GraphQLField, GraphQLFieldResolver, GraphQLObjectType, GraphQLResolveInfo, GraphQLTypeResolver, GraphQLSchema } from 'graphql';
-import { Maybe, Path, MaybePromise, ExecutionResult } from '@graphql-tools/utils';
+import { GraphQLFormattedError, FieldNode, FragmentDefinitionNode, OperationDefinitionNode, GraphQLField, GraphQLFieldResolver, GraphQLObjectType, GraphQLResolveInfo, GraphQLTypeResolver, GraphQLSchema } from 'graphql';
+import type { GraphQLError } from 'graphql';
+import { Path, Maybe, MaybePromise, ExecutionResult } from '@graphql-tools/utils';
 import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 /**
  * Terminology
@@ -26,25 +27,72 @@ import { TypedDocumentNode } from '@graphql-typed-document-node/core';
  * Namely, schema of the type system that is currently executing,
  * and the fragments defined in the query document
  */
-export interface ExecutionContext<TContext = any> {
+export interface ExecutionContext<TVariables = any, TContext = any> {
     schema: GraphQLSchema;
     fragments: Record<string, FragmentDefinitionNode>;
     rootValue: unknown;
     contextValue: TContext;
     operation: OperationDefinitionNode;
-    variableValues: {
-        [variable: string]: unknown;
-    };
+    variableValues: TVariables;
     fieldResolver: GraphQLFieldResolver<any, TContext>;
     typeResolver: GraphQLTypeResolver<any, TContext>;
     subscribeFieldResolver: GraphQLFieldResolver<any, TContext>;
     errors: Array<GraphQLError>;
+    subsequentPayloads: Set<AsyncPayloadRecord>;
 }
-export interface FormattedExecutionResult<TData = any, TExtensions = any> {
+export interface FormattedExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
     errors?: ReadonlyArray<GraphQLFormattedError>;
     data?: TData | null;
     extensions?: TExtensions;
 }
+export interface ExperimentalIncrementalExecutionResults<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    initialResult: InitialIncrementalExecutionResult<TData, TExtensions>;
+    subsequentResults: AsyncGenerator<SubsequentIncrementalExecutionResult<TData, TExtensions>, void, void>;
+}
+export interface InitialIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends ExecutionResult<TData, TExtensions> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<IncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface FormattedInitialIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends FormattedExecutionResult<TData, TExtensions> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<FormattedIncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface SubsequentIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<IncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface FormattedSubsequentIncrementalExecutionResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> {
+    hasNext: boolean;
+    incremental?: ReadonlyArray<FormattedIncrementalResult<TData, TExtensions>>;
+    extensions?: TExtensions;
+}
+export interface IncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends ExecutionResult<TData, TExtensions> {
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+}
+export interface FormattedIncrementalDeferResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> extends FormattedExecutionResult<TData, TExtensions> {
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+}
+export interface IncrementalStreamResult<TData = Array<unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLError>;
+    items?: TData | null;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+    extensions?: TExtensions;
+}
+export interface FormattedIncrementalStreamResult<TData = Array<unknown>, TExtensions = Record<string, unknown>> {
+    errors?: ReadonlyArray<GraphQLFormattedError>;
+    items?: TData | null;
+    path?: ReadonlyArray<string | number>;
+    label?: string;
+    extensions?: TExtensions;
+}
+export declare type IncrementalResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> = IncrementalDeferResult<TData, TExtensions> | IncrementalStreamResult<TData, TExtensions>;
+export declare type FormattedIncrementalResult<TData = Record<string, unknown>, TExtensions = Record<string, unknown>> = FormattedIncrementalDeferResult<TData, TExtensions> | FormattedIncrementalStreamResult<TData, TExtensions>;
 export interface ExecutionArgs<TData = any, TVariables = any, TContext = any> {
     schema: GraphQLSchema;
     document: TypedDocumentNode<TData, TVariables>;
@@ -65,12 +113,27 @@ export interface ExecutionArgs<TData = any, TVariables = any, TContext = any> {
  *
  * If the arguments to this function do not result in a legal execution context,
  * a GraphQLError will be thrown immediately explaining the invalid input.
+ *
+ * This function does not support incremental delivery (`@defer` and `@stream`).
+ * If an operation which would defer or stream data is executed with this
+ * function, it will throw or resolve to an object containing an error instead.
+ * Use `experimentalExecuteIncrementally` if you want to support incremental
+ * delivery.
+ */
+export declare function execute<TData = any, TVariables = any, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): MaybePromise<ExecutionResult<TData>>;
+/**
+ * Implements the "Executing requests" section of the GraphQL specification,
+ * including `@defer` and `@stream` as proposed in
+ * https://github.com/graphql/graphql-spec/pull/742
+ *
+ * This function returns a Promise of an ExperimentalIncrementalExecutionResults
+ * object. This object either consists of a single ExecutionResult, or an
+ * object containing an `initialResult` and a stream of `subsequentResults`.
+ *
+ * If the arguments to this function do not result in a legal execution context,
+ * a GraphQLError will be thrown immediately explaining the invalid input.
  */
-export declare function execute<TData = {
-    [key: string]: any;
-}, TVariables = {
-    [key: string]: any;
-}, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): MaybePromise<ExecutionResult<TData>>;
+export declare function experimentalExecuteIncrementally<TData = any, TVariables = any, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): MaybePromise<ExecutionResult<TData> | ExperimentalIncrementalExecutionResults<TData>>;
 /**
  * Also implements the "Executing requests" section of the GraphQL specification.
  * However, it guarantees to complete synchronously (or throw an error) assuming
@@ -93,16 +156,12 @@ export declare function assertValidExecutionArguments<TVariables>(schema: GraphQ
  * TODO: consider no longer exporting this function
  * @internal
  */
-export declare function buildExecutionContext<TData = {
-    [key: string]: any;
-}, TVariables = {
-    [key: string]: any;
-}, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): ReadonlyArray<GraphQLError> | ExecutionContext;
+export declare function buildExecutionContext<TData = any, TVariables = any, TContext = any>(args: ExecutionArgs<TData, TVariables, TContext>): ReadonlyArray<GraphQLError> | ExecutionContext;
 /**
  * TODO: consider no longer exporting this function
  * @internal
  */
-export declare function buildResolveInfo(exeContext: ExecutionContext, fieldDef: GraphQLField<unknown, unknown>, fieldNodes: ReadonlyArray<FieldNode>, parentType: GraphQLObjectType, path: Path): GraphQLResolveInfo;
+export declare function buildResolveInfo(exeContext: ExecutionContext, fieldDef: GraphQLField<unknown, unknown>, fieldNodes: Array<FieldNode>, parentType: GraphQLObjectType, path: Path): GraphQLResolveInfo;
 /**
  * If a resolveType function is not given, then a default resolve behavior is
  * used which attempts two strategies:
@@ -130,19 +189,61 @@ export declare const defaultFieldResolver: GraphQLFieldResolver<unknown, unknown
  * is not an async iterable.
  *
  * If the client-provided arguments to this function do not result in a
- * compliant subscription, a GraphQL Response (ExecutionResult) with
- * descriptive errors and no data will be returned.
+ * compliant subscription, a GraphQL Response (ExecutionResult) with descriptive
+ * errors and no data will be returned.
  *
- * If the source stream could not be created due to faulty subscription
- * resolver logic or underlying systems, the promise will resolve to a single
+ * If the source stream could not be created due to faulty subscription resolver
+ * logic or underlying systems, the promise will resolve to a single
  * ExecutionResult containing `errors` and no `data`.
  *
  * If the operation succeeded, the promise resolves to an AsyncIterator, which
  * yields a stream of ExecutionResults representing the response stream.
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * This function does not support incremental delivery (`@defer` and `@stream`).
+ * If an operation which would defer or stream data is executed with this
+ * function, each `InitialIncrementalExecutionResult` and
+ * `SubsequentIncrementalExecutionResult` in the result stream will be replaced
+ * with an `ExecutionResult` with a single error stating that defer/stream is
+ * not supported.  Use `experimentalSubscribeIncrementally` if you want to
+ * support incremental delivery.
+ *
+ * Accepts an object with named arguments.
  */
 export declare function subscribe(args: ExecutionArgs): MaybePromise<AsyncIterable<ExecutionResult> | ExecutionResult>;
+/**
+ * Implements the "Subscribe" algorithm described in the GraphQL specification,
+ * including `@defer` and `@stream` as proposed in
+ * https://github.com/graphql/graphql-spec/pull/742
+ *
+ * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * or an ExecutionResult (error). The promise will be rejected if the schema or
+ * other arguments to this function are invalid, or if the resolved event stream
+ * is not an async iterable.
+ *
+ * If the client-provided arguments to this function do not result in a
+ * compliant subscription, a GraphQL Response (ExecutionResult) with descriptive
+ * errors and no data will be returned.
+ *
+ * If the source stream could not be created due to faulty subscription resolver
+ * logic or underlying systems, the promise will resolve to a single
+ * ExecutionResult containing `errors` and no `data`.
+ *
+ * If the operation succeeded, the promise resolves to an AsyncIterator, which
+ * yields a stream of result representing the response stream.
+ *
+ * Each result may be an ExecutionResult with no `hasNext` (if executing the
+ * event did not use `@defer` or `@stream`), or an
+ * `InitialIncrementalExecutionResult` or `SubsequentIncrementalExecutionResult`
+ * (if executing the event used `@defer` or `@stream`). In the case of
+ * incremental execution results, each event produces a single
+ * `InitialIncrementalExecutionResult` followed by one or more
+ * `SubsequentIncrementalExecutionResult`s; all but the last have `hasNext: true`,
+ * and the last has `hasNext: false`. There is no interleaving between results
+ * generated from the same original event.
+ *
+ * Accepts an object with named arguments.
+ */
+export declare function experimentalSubscribeIncrementally(args: ExecutionArgs): MaybePromise<AsyncGenerator<ExecutionResult | InitialIncrementalExecutionResult | SubsequentIncrementalExecutionResult, void, void> | ExecutionResult>;
 /**
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
@@ -172,6 +273,49 @@ export declare function subscribe(args: ExecutionArgs): MaybePromise<AsyncIterab
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
  */
 export declare function createSourceEventStream(args: ExecutionArgs): MaybePromise<AsyncIterable<unknown> | ExecutionResult>;
+declare class DeferredFragmentRecord {
+    type: 'defer';
+    errors: Array<GraphQLError>;
+    label: string | undefined;
+    path: Array<string | number>;
+    promise: Promise<void>;
+    data: Record<string, unknown> | null;
+    parentContext: AsyncPayloadRecord | undefined;
+    isCompleted: boolean;
+    _exeContext: ExecutionContext;
+    _resolve?: (arg: MaybePromise<Record<string, unknown> | null>) => void;
+    constructor(opts: {
+        label: string | undefined;
+        path: Path | undefined;
+        parentContext: AsyncPayloadRecord | undefined;
+        exeContext: ExecutionContext;
+    });
+    addData(data: MaybePromise<Record<string, unknown> | null>): void;
+}
+declare class StreamRecord {
+    type: 'stream';
+    errors: Array<GraphQLError>;
+    label: string | undefined;
+    path: Array<string | number>;
+    items: Array<unknown> | null;
+    promise: Promise<void>;
+    parentContext: AsyncPayloadRecord | undefined;
+    iterator: AsyncIterator<unknown> | undefined;
+    isCompletedIterator?: boolean;
+    isCompleted: boolean;
+    _exeContext: ExecutionContext;
+    _resolve?: (arg: MaybePromise<Array<unknown> | null>) => void;
+    constructor(opts: {
+        label: string | undefined;
+        path: Path | undefined;
+        iterator?: AsyncIterator<unknown>;
+        parentContext: AsyncPayloadRecord | undefined;
+        exeContext: ExecutionContext;
+    });
+    addItems(items: MaybePromise<Array<unknown> | null>): void;
+    setIsCompletedIterator(): void;
+}
+declare type AsyncPayloadRecord = DeferredFragmentRecord | StreamRecord;
 /**
  * This method looks up the field on the given type definition.
  * It has special casing for the three introspection fields,
@@ -184,3 +328,4 @@ export declare function createSourceEventStream(args: ExecutionArgs): MaybePromi
  * @internal
  */
 export declare function getFieldDef(schema: GraphQLSchema, parentType: GraphQLObjectType, fieldNode: FieldNode): Maybe<GraphQLField<unknown, unknown>>;
+export {};

package/typings/execution/flattenAsyncIterable.d.cts

@@ -0,0 +1,7 @@
+declare type AsyncIterableOrGenerator<T> = AsyncGenerator<T, void, void> | AsyncIterable<T>;
+/**
+ * Given an AsyncIterable of AsyncIterables, flatten all yielded results into a
+ * single AsyncIterable.
+ */
+export declare function flattenAsyncIterable<T>(iterable: AsyncIterableOrGenerator<AsyncIterableOrGenerator<T>>): AsyncGenerator<T, void, void>;
+export {};

package/typings/execution/flattenAsyncIterable.d.ts

@@ -0,0 +1,7 @@
+declare type AsyncIterableOrGenerator<T> = AsyncGenerator<T, void, void> | AsyncIterable<T>;
+/**
+ * Given an AsyncIterable of AsyncIterables, flatten all yielded results into a
+ * single AsyncIterable.
+ */
+export declare function flattenAsyncIterable<T>(iterable: AsyncIterableOrGenerator<AsyncIterableOrGenerator<T>>): AsyncGenerator<T, void, void>;
+export {};