graphql 17.0.0-beta.1 → 17.0.0-beta.2

package/execution/Executor.d.mts

@@ -1,19 +1,18 @@
+/** @category Execution */
 import type { ObjMap } from "../jsutils/ObjMap.mjs";
 import type { Path } from "../jsutils/Path.mjs";
 import type { PromiseOrValue } from "../jsutils/PromiseOrValue.mjs";
 import type { GraphQLFormattedError } from "../error/GraphQLError.mjs";
 import { GraphQLError } from "../error/GraphQLError.mjs";
-import type { FragmentDefinitionNode, OperationDefinitionNode, SubscriptionOperationDefinitionNode } from "../language/ast.mjs";
-import type { GraphQLAbstractType, GraphQLFieldResolver, GraphQLLeafType, GraphQLList, GraphQLObjectType, GraphQLOutputType, GraphQLResolveInfo, GraphQLResolveInfoHelpers, GraphQLTypeResolver } from "../type/definition.mjs";
+import type { GraphQLAbstractType, GraphQLLeafType, GraphQLList, GraphQLObjectType, GraphQLOutputType, GraphQLResolveInfo, GraphQLResolveInfoHelpers } from "../type/definition.mjs";
 import type { GraphQLSchema } from "../type/schema.mjs";
 import { AbortedGraphQLExecutionError } from "./AbortedGraphQLExecutionError.mjs";
-import type { DeferUsage, FieldDetailsList, FragmentDetails, GroupedFieldSet } from "./collectFields.mjs";
+import type { DeferUsage, FieldDetailsList, GroupedFieldSet } from "./collectFields.mjs";
 import { collectSubfields as _collectSubfields } from "./collectFields.mjs";
 import type { SharedExecutionContext } from "./createSharedExecutionContext.mjs";
+import type { ValidatedExecutionArgs } from "./ExecutionArgs.mjs";
 import type { StreamUsage } from "./getStreamUsage.mjs";
 import { getStreamUsage as _getStreamUsage } from "./getStreamUsage.mjs";
-import type { ExecutionHooks } from "./hooks.mjs";
-import type { VariableValues } from "./values.mjs";
 /**
  * Terminology
  *
@@ -32,43 +31,19 @@ import type { VariableValues } from "./values.mjs";
  * 1) field references e.g `a`
  * 2) fragment "spreads" e.g. `...c`
  * 3) inline fragment "spreads" e.g. `...on Type { a }`
- */
-/**
- * Data that must be available at all points during query execution.
  *
- * Namely, schema of the type system that is currently executing,
- * and the fragments defined in the query document
+ * @internal
  */
-export interface ValidatedExecutionArgs {
-    schema: GraphQLSchema;
-    fragmentDefinitions: ObjMap<FragmentDefinitionNode>;
-    fragments: ObjMap<FragmentDetails>;
-    rootValue: unknown;
-    contextValue: unknown;
-    operation: OperationDefinitionNode;
-    variableValues: VariableValues;
-    fieldResolver: GraphQLFieldResolver<any, any>;
-    typeResolver: GraphQLTypeResolver<any, any>;
-    subscribeFieldResolver: GraphQLFieldResolver<any, any>;
-    hideSuggestions: boolean;
-    errorPropagation: boolean;
-    externalAbortSignal: AbortSignal | undefined;
-    enableEarlyExecution: boolean;
-    hooks: ExecutionHooks | undefined;
-}
-export interface ValidatedSubscriptionArgs extends ValidatedExecutionArgs {
-    operation: SubscriptionOperationDefinitionNode;
-}
 /**
  * A memoized collection of relevant subfields with regard to the return
  * type. Memoizing ensures the subfields are not repeatedly calculated, which
  * saves overhead when resolving lists of values.
+ *
+ * @internal
  */
 export declare const collectSubfields: (validatedExecutionArgs: ValidatedExecutionArgs, returnType: GraphQLObjectType, fieldDetailsList: FieldDetailsList) => ReturnType<typeof _collectSubfields>;
+/** @internal */
 export declare const getStreamUsage: typeof _getStreamUsage;
-/**
- * @internal
- */
 declare class CollectedErrors {
     private _errorPositions;
     private _errors;
@@ -78,22 +53,29 @@ declare class CollectedErrors {
     hasNulledPosition(startPath: Path | undefined): boolean;
 }
 /**
- * The result of GraphQL execution.
- *
- *   - `errors` is included when any errors occurred as a non-empty array.
- *   - `data` is the result of a successful execution of the query.
- *   - `hasNext` is true if a future payload is expected.
- *   - `extensions` is reserved for adding non-standard properties.
- *   - `incremental` is a list of the results from defer/stream directives.
+ * Represents the response produced by executing a GraphQL operation.
+ * @typeParam TData - Shape of the execution data payload.
+ * @typeParam TExtensions - Shape of the extensions payload.
  */
 export interface ExecutionResult<TData = ObjMap<unknown>, TExtensions = ObjMap<unknown>> {
+    /** Errors raised while parsing, validating, or executing the operation. */
     errors?: ReadonlyArray<GraphQLError>;
+    /** Data returned by execution, or null when execution could not produce data. */
     data?: TData | null;
+    /** Additional non-standard metadata included in the execution result. */
     extensions?: TExtensions;
 }
+/**
+ * A JSON-serializable GraphQL execution result.
+ * @typeParam TData - Shape of the formatted data payload.
+ * @typeParam TExtensions - Shape of the formatted extensions payload.
+ */
 export interface FormattedExecutionResult<TData = ObjMap<unknown>, TExtensions = ObjMap<unknown>> {
+    /** Errors raised while parsing, validating, or executing the operation. */
     errors?: ReadonlyArray<GraphQLFormattedError>;
+    /** Data returned by execution, or null when execution could not produce data. */
     data?: TData | null;
+    /** Additional non-standard metadata included in the formatted result. */
     extensions?: TExtensions;
 }
 /** @internal */
@@ -118,6 +100,8 @@ TAlternativeInitialResponse = ExecutionResult> {
     /**
      * Given a completed execution context and data, build the `{ errors, data }`
      * response defined by the "Response" section of the GraphQL specification.
+     *
+     * @internal
      */
     buildResponse(data: ObjMap<unknown> | null): ExecutionResult | TAlternativeInitialResponse;
     executeCollectedRootFields(rootType: GraphQLObjectType, rootValue: unknown, originalGroupedFieldSet: GroupedFieldSet, serially: boolean, _newDeferUsages: ReadonlyArray<DeferUsage>): PromiseOrValue<ObjMap<unknown>>;
@@ -125,11 +109,15 @@ TAlternativeInitialResponse = ExecutionResult> {
     /**
      * Implements the "Executing selection sets" section of the spec
      * for fields that must be executed serially.
+     *
+     * @internal
      */
     executeFieldsSerially(parentType: GraphQLObjectType, sourceValue: unknown, path: Path | undefined, groupedFieldSet: GroupedFieldSet, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     /**
      * Implements the "Executing selection sets" section of the spec
      * for fields that may be executed in parallel.
+     *
+     * @internal
      */
     executeFields(parentType: GraphQLObjectType, sourceValue: unknown, path: Path | undefined, groupedFieldSet: GroupedFieldSet, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     /**
@@ -137,6 +125,8 @@ TAlternativeInitialResponse = ExecutionResult> {
      * In particular, this function figures out the value that the field returns by
      * calling its resolve function, then calls completeValue to complete promises,
      * coercing scalars, or execute the sub-selection-set for objects.
+     *
+     * @internal
      */
     executeField(parentType: GraphQLObjectType, source: unknown, fieldDetailsList: FieldDetailsList, path: Path, positionContext: TPositionContext | undefined): PromiseOrValue<unknown>;
     handleFieldError(rawError: unknown, returnType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, path: Path): void;
@@ -160,12 +150,16 @@ TAlternativeInitialResponse = ExecutionResult> {
      *
      * Otherwise, the field type expects a sub-selection set, and will complete the
      * value by executing all sub-selections.
+     *
+     * @internal
      */
     completeValue(returnType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<unknown>;
     completePromisedValue(returnType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: PromiseLike<unknown>, positionContext: TPositionContext | undefined): Promise<unknown>;
     /**
      * Complete a async iterator value by completing the result and calling
      * recursively until all the results are completed.
+     *
+     * @internal
      */
     completeAsyncIterableValue(itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, items: AsyncIterable<unknown>, positionContext: TPositionContext | undefined): Promise<ReadonlyArray<unknown>>;
     handleStream(_index: number, _path: Path, _iterator: {
@@ -178,6 +172,8 @@ TAlternativeInitialResponse = ExecutionResult> {
     /**
      * Complete a list value by completing each item in the list with the
      * inner type
+     *
+     * @internal
      */
     completeListValue(returnType: GraphQLList<GraphQLOutputType>, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<ReadonlyArray<unknown>>;
     completeIterableValue(itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, items: Iterable<unknown>, positionContext: TPositionContext | undefined): PromiseOrValue<ReadonlyArray<unknown>>;
@@ -186,22 +182,30 @@ TAlternativeInitialResponse = ExecutionResult> {
      * Complete a list item value by adding it to the completed results.
      *
      * Returns true if the value is a Promise.
+     *
+     * @internal
      */
     completeListItemValue(item: unknown, completedResults: Array<unknown>, itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, itemPath: Path, positionContext: TPositionContext | undefined): boolean;
     completePromisedListItemValue(item: PromiseLike<unknown>, itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, itemPath: Path, positionContext: TPositionContext | undefined): Promise<unknown>;
     /**
      * Complete a Scalar or Enum by serializing to a valid value, returning
      * null if serialization is not possible.
+     *
+     * @internal
      */
     completeLeafValue(returnType: GraphQLLeafType, result: unknown): unknown;
     /**
      * Complete a value of an abstract type by determining the runtime object type
      * of that value, then complete the value for that type.
+     *
+     * @internal
      */
     completeAbstractValue(returnType: GraphQLAbstractType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     ensureValidRuntimeType(runtimeTypeName: unknown, schema: GraphQLSchema, returnType: GraphQLAbstractType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, result: unknown): GraphQLObjectType;
     /**
      * Complete an Object value by executing all sub-selections.
+     *
+     * @internal
      */
     completeObjectValue(returnType: GraphQLObjectType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     invalidReturnTypeError(returnType: GraphQLObjectType, result: unknown, fieldDetailsList: FieldDetailsList): GraphQLError;

package/execution/Executor.d.ts

@@ -1,19 +1,18 @@
+/** @category Execution */
 import type { ObjMap } from "../jsutils/ObjMap.js";
 import type { Path } from "../jsutils/Path.js";
 import type { PromiseOrValue } from "../jsutils/PromiseOrValue.js";
 import type { GraphQLFormattedError } from "../error/GraphQLError.js";
 import { GraphQLError } from "../error/GraphQLError.js";
-import type { FragmentDefinitionNode, OperationDefinitionNode, SubscriptionOperationDefinitionNode } from "../language/ast.js";
-import type { GraphQLAbstractType, GraphQLFieldResolver, GraphQLLeafType, GraphQLList, GraphQLObjectType, GraphQLOutputType, GraphQLResolveInfo, GraphQLResolveInfoHelpers, GraphQLTypeResolver } from "../type/definition.js";
+import type { GraphQLAbstractType, GraphQLLeafType, GraphQLList, GraphQLObjectType, GraphQLOutputType, GraphQLResolveInfo, GraphQLResolveInfoHelpers } from "../type/definition.js";
 import type { GraphQLSchema } from "../type/schema.js";
 import { AbortedGraphQLExecutionError } from "./AbortedGraphQLExecutionError.js";
-import type { DeferUsage, FieldDetailsList, FragmentDetails, GroupedFieldSet } from "./collectFields.js";
+import type { DeferUsage, FieldDetailsList, GroupedFieldSet } from "./collectFields.js";
 import { collectSubfields as _collectSubfields } from "./collectFields.js";
 import type { SharedExecutionContext } from "./createSharedExecutionContext.js";
+import type { ValidatedExecutionArgs } from "./ExecutionArgs.js";
 import type { StreamUsage } from "./getStreamUsage.js";
 import { getStreamUsage as _getStreamUsage } from "./getStreamUsage.js";
-import type { ExecutionHooks } from "./hooks.js";
-import type { VariableValues } from "./values.js";
 /**
  * Terminology
  *
@@ -32,43 +31,19 @@ import type { VariableValues } from "./values.js";
  * 1) field references e.g `a`
  * 2) fragment "spreads" e.g. `...c`
  * 3) inline fragment "spreads" e.g. `...on Type { a }`
- */
-/**
- * Data that must be available at all points during query execution.
  *
- * Namely, schema of the type system that is currently executing,
- * and the fragments defined in the query document
+ * @internal
  */
-export interface ValidatedExecutionArgs {
-    schema: GraphQLSchema;
-    fragmentDefinitions: ObjMap<FragmentDefinitionNode>;
-    fragments: ObjMap<FragmentDetails>;
-    rootValue: unknown;
-    contextValue: unknown;
-    operation: OperationDefinitionNode;
-    variableValues: VariableValues;
-    fieldResolver: GraphQLFieldResolver<any, any>;
-    typeResolver: GraphQLTypeResolver<any, any>;
-    subscribeFieldResolver: GraphQLFieldResolver<any, any>;
-    hideSuggestions: boolean;
-    errorPropagation: boolean;
-    externalAbortSignal: AbortSignal | undefined;
-    enableEarlyExecution: boolean;
-    hooks: ExecutionHooks | undefined;
-}
-export interface ValidatedSubscriptionArgs extends ValidatedExecutionArgs {
-    operation: SubscriptionOperationDefinitionNode;
-}
 /**
  * A memoized collection of relevant subfields with regard to the return
  * type. Memoizing ensures the subfields are not repeatedly calculated, which
  * saves overhead when resolving lists of values.
+ *
+ * @internal
  */
 export declare const collectSubfields: (validatedExecutionArgs: ValidatedExecutionArgs, returnType: GraphQLObjectType, fieldDetailsList: FieldDetailsList) => ReturnType<typeof _collectSubfields>;
+/** @internal */
 export declare const getStreamUsage: typeof _getStreamUsage;
-/**
- * @internal
- */
 declare class CollectedErrors {
     private _errorPositions;
     private _errors;
@@ -78,22 +53,29 @@ declare class CollectedErrors {
     hasNulledPosition(startPath: Path | undefined): boolean;
 }
 /**
- * The result of GraphQL execution.
- *
- *   - `errors` is included when any errors occurred as a non-empty array.
- *   - `data` is the result of a successful execution of the query.
- *   - `hasNext` is true if a future payload is expected.
- *   - `extensions` is reserved for adding non-standard properties.
- *   - `incremental` is a list of the results from defer/stream directives.
+ * Represents the response produced by executing a GraphQL operation.
+ * @typeParam TData - Shape of the execution data payload.
+ * @typeParam TExtensions - Shape of the extensions payload.
  */
 export interface ExecutionResult<TData = ObjMap<unknown>, TExtensions = ObjMap<unknown>> {
+    /** Errors raised while parsing, validating, or executing the operation. */
     errors?: ReadonlyArray<GraphQLError>;
+    /** Data returned by execution, or null when execution could not produce data. */
     data?: TData | null;
+    /** Additional non-standard metadata included in the execution result. */
     extensions?: TExtensions;
 }
+/**
+ * A JSON-serializable GraphQL execution result.
+ * @typeParam TData - Shape of the formatted data payload.
+ * @typeParam TExtensions - Shape of the formatted extensions payload.
+ */
 export interface FormattedExecutionResult<TData = ObjMap<unknown>, TExtensions = ObjMap<unknown>> {
+    /** Errors raised while parsing, validating, or executing the operation. */
     errors?: ReadonlyArray<GraphQLFormattedError>;
+    /** Data returned by execution, or null when execution could not produce data. */
     data?: TData | null;
+    /** Additional non-standard metadata included in the formatted result. */
     extensions?: TExtensions;
 }
 /** @internal */
@@ -118,6 +100,8 @@ TAlternativeInitialResponse = ExecutionResult> {
     /**
      * Given a completed execution context and data, build the `{ errors, data }`
      * response defined by the "Response" section of the GraphQL specification.
+     *
+     * @internal
      */
     buildResponse(data: ObjMap<unknown> | null): ExecutionResult | TAlternativeInitialResponse;
     executeCollectedRootFields(rootType: GraphQLObjectType, rootValue: unknown, originalGroupedFieldSet: GroupedFieldSet, serially: boolean, _newDeferUsages: ReadonlyArray<DeferUsage>): PromiseOrValue<ObjMap<unknown>>;
@@ -125,11 +109,15 @@ TAlternativeInitialResponse = ExecutionResult> {
     /**
      * Implements the "Executing selection sets" section of the spec
      * for fields that must be executed serially.
+     *
+     * @internal
      */
     executeFieldsSerially(parentType: GraphQLObjectType, sourceValue: unknown, path: Path | undefined, groupedFieldSet: GroupedFieldSet, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     /**
      * Implements the "Executing selection sets" section of the spec
      * for fields that may be executed in parallel.
+     *
+     * @internal
      */
     executeFields(parentType: GraphQLObjectType, sourceValue: unknown, path: Path | undefined, groupedFieldSet: GroupedFieldSet, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     /**
@@ -137,6 +125,8 @@ TAlternativeInitialResponse = ExecutionResult> {
      * In particular, this function figures out the value that the field returns by
      * calling its resolve function, then calls completeValue to complete promises,
      * coercing scalars, or execute the sub-selection-set for objects.
+     *
+     * @internal
      */
     executeField(parentType: GraphQLObjectType, source: unknown, fieldDetailsList: FieldDetailsList, path: Path, positionContext: TPositionContext | undefined): PromiseOrValue<unknown>;
     handleFieldError(rawError: unknown, returnType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, path: Path): void;
@@ -160,12 +150,16 @@ TAlternativeInitialResponse = ExecutionResult> {
      *
      * Otherwise, the field type expects a sub-selection set, and will complete the
      * value by executing all sub-selections.
+     *
+     * @internal
      */
     completeValue(returnType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<unknown>;
     completePromisedValue(returnType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: PromiseLike<unknown>, positionContext: TPositionContext | undefined): Promise<unknown>;
     /**
      * Complete a async iterator value by completing the result and calling
      * recursively until all the results are completed.
+     *
+     * @internal
      */
     completeAsyncIterableValue(itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, items: AsyncIterable<unknown>, positionContext: TPositionContext | undefined): Promise<ReadonlyArray<unknown>>;
     handleStream(_index: number, _path: Path, _iterator: {
@@ -178,6 +172,8 @@ TAlternativeInitialResponse = ExecutionResult> {
     /**
      * Complete a list value by completing each item in the list with the
      * inner type
+     *
+     * @internal
      */
     completeListValue(returnType: GraphQLList<GraphQLOutputType>, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<ReadonlyArray<unknown>>;
     completeIterableValue(itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, items: Iterable<unknown>, positionContext: TPositionContext | undefined): PromiseOrValue<ReadonlyArray<unknown>>;
@@ -186,22 +182,30 @@ TAlternativeInitialResponse = ExecutionResult> {
      * Complete a list item value by adding it to the completed results.
      *
      * Returns true if the value is a Promise.
+     *
+     * @internal
      */
     completeListItemValue(item: unknown, completedResults: Array<unknown>, itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, itemPath: Path, positionContext: TPositionContext | undefined): boolean;
     completePromisedListItemValue(item: PromiseLike<unknown>, itemType: GraphQLOutputType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, itemPath: Path, positionContext: TPositionContext | undefined): Promise<unknown>;
     /**
      * Complete a Scalar or Enum by serializing to a valid value, returning
      * null if serialization is not possible.
+     *
+     * @internal
      */
     completeLeafValue(returnType: GraphQLLeafType, result: unknown): unknown;
     /**
      * Complete a value of an abstract type by determining the runtime object type
      * of that value, then complete the value for that type.
+     *
+     * @internal
      */
     completeAbstractValue(returnType: GraphQLAbstractType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     ensureValidRuntimeType(runtimeTypeName: unknown, schema: GraphQLSchema, returnType: GraphQLAbstractType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, result: unknown): GraphQLObjectType;
     /**
      * Complete an Object value by executing all sub-selections.
+     *
+     * @internal
      */
     completeObjectValue(returnType: GraphQLObjectType, fieldDetailsList: FieldDetailsList, info: GraphQLResolveInfo, path: Path, result: unknown, positionContext: TPositionContext | undefined): PromiseOrValue<ObjMap<unknown>>;
     invalidReturnTypeError(returnType: GraphQLObjectType, result: unknown, fieldDetailsList: FieldDetailsList): GraphQLError;