graphql 16.11.0 → 16.13.0

package/README.md

@@ -103,9 +103,9 @@ graphql({ schema, source }).then((result) => {
 });
 ```
 
-**Note**: Please don't forget to set `NODE_ENV=production` if you are running a production server. It will disable some checks that can be useful during development but will significantly improve performance.
+**Note**: Please don't forget to set `NODE_ENV=production` if you are running a production server. It will disable some checks that can be useful during development but will significantly impact performance.
 
-### Want to ride the bleeding edge?
+## Want to ride the bleeding edge?
 
 The `npm` branch in this repository is automatically maintained to be the last
 commit to `main` to pass all tests, in the same form found on npm. It is
@@ -127,7 +127,7 @@ Each release of GraphQL.js will be accompanied by an experimental release contai
 
 Community feedback on this experimental release is much appreciated and can be provided on the [issue created for this purpose](https://github.com/graphql/graphql-js/issues/2848).
 
-### Using in a Browser
+## Using in a Browser
 
 GraphQL.js is a general-purpose library and can be used both in a Node server
 and in the browser. As an example, the [GraphiQL](https://github.com/graphql/graphiql/)
@@ -139,7 +139,7 @@ the portions of the library you use. This works because GraphQL.js is distribute
 with both CommonJS (`require()`) and ESModule (`import`) files. Ensure that any
 custom build configurations look for `.mjs` files!
 
-### Contributing
+## Contributing
 
 We actively welcome pull requests. Learn how to [contribute](./.github/CONTRIBUTING.md).
 
@@ -151,10 +151,53 @@ You can find [detailed information here](https://github.com/graphql/graphql-wg/t
 
 If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the [GraphQL Foundation](https://foundation.graphql.org/join).
 
-### Changelog
+## Changelog
 
 Changes are tracked as [GitHub releases](https://github.com/graphql/graphql-js/releases).
 
-### License
+## License
 
 GraphQL.js is [MIT-licensed](./LICENSE).
+
+## Version Support
+
+GraphQL.JS follows Semantic Versioning (SemVer) for its releases. Our version support policy is as follows:
+
+- Latest Major Version: We provide full support, including bug fixes and security updates, for the latest major version of GraphQL.JS.
+- Previous Major Version: We offer feature support for the previous major version for 12 months after the release of the newest major version.
+  This means that for 12 months we can backport features for specification changes _if_ they don't cause any breaking changes. We'll continue
+  supporting the previous major version with bug and security fixes.
+- Older Versions: Versions older than the previous major release are considered unsupported. While the code remains available,
+  we do not actively maintain or provide updates for these versions.
+  One exception to this rule is when the older version has been released < 1 year ago, in that case we
+  will treat it like the "Previous Major Version".
+
+### Long-Term Support (LTS)
+
+We do not currently offer a Long-Term Support version of GraphQL.JS. Users are encouraged to upgrade to the latest stable version
+to receive the most up-to-date features, performance improvements, and security updates.
+
+### End-of-Life (EOL) Schedule
+
+We will announce the EOL date for a major version at least 6 months in advance.
+After a version reaches its EOL, it will no longer receive updates, even for critical security issues.
+
+### Upgrade Assistance
+
+To assist users in upgrading to newer versions:
+
+- We maintain detailed release notes for each version, highlighting new features, breaking changes, and deprecations.
+- [Our documentation](https://www.graphql-js.org/) includes migration guides for moving between major versions.
+- The [community forum (Discord channel #graphql-js)](https://discord.graphql.org) is available for users who need additional assistance with upgrades.
+
+### Security Updates
+
+We prioritize the security of GraphQL.JS:
+
+- Critical security updates will be applied to both the current and previous major version.
+- For versions that have reached EOL, we strongly recommend upgrading to a supported version to receive security updates.
+
+### Community Contributions
+
+We welcome community contributions for all versions of GraphQL.JS. However, our maintainers will primarily focus on reviewing
+and merging contributions for supported versions.

package/execution/execute.d.ts

@@ -55,7 +55,18 @@ export interface ExecutionContext {
   fieldResolver: GraphQLFieldResolver<any, any>;
   typeResolver: GraphQLTypeResolver<any, any>;
   subscribeFieldResolver: GraphQLFieldResolver<any, any>;
-  errors: Array<GraphQLError>;
+  collectedErrors: CollectedErrors;
+}
+/**
+ * @internal
+ */
+declare class CollectedErrors {
+  private _errorPositions;
+  private _errors;
+  constructor();
+  get errors(): ReadonlyArray<GraphQLError>;
+  add(error: GraphQLError, path: Path | undefined): void;
+  private _hasNulledPosition;
 }
 /**
  * The result of GraphQL execution.
@@ -121,6 +132,7 @@ export declare function executeSync(args: ExecutionArgs): ExecutionResult;
  * Essential assertions before executing to provide developer feedback for
  * improper use of the GraphQL library.
  *
+ * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
  * @internal
  */
 export declare function assertValidExecutionArguments(
@@ -188,3 +200,4 @@ export declare function getFieldDef(
   parentType: GraphQLObjectType,
   fieldNode: FieldNode,
 ): Maybe<GraphQLField<unknown, unknown>>;
+export {};

package/execution/execute.js

@@ -91,6 +91,55 @@ const collectSubfields = (0, _memoize.memoize3)(
  * and the fragments defined in the query document
  */
 
+/**
+ * @internal
+ */
+class CollectedErrors {
+  constructor() {
+    this._errorPositions = new Set();
+    this._errors = [];
+  }
+
+  get errors() {
+    return this._errors;
+  }
+
+  add(error, path) {
+    // Do not modify errors list if the execution position for this error or
+    // any of its ancestors has already been nulled via error propagation.
+    // This check should be unnecessary for implementations able to implement
+    // actual cancellation.
+    if (this._hasNulledPosition(path)) {
+      return;
+    }
+
+    this._errorPositions.add(path);
+
+    this._errors.push(error);
+  }
+
+  _hasNulledPosition(startPath) {
+    let path = startPath;
+
+    while (path !== undefined) {
+      if (this._errorPositions.has(path)) {
+        return true;
+      }
+
+      path = path.prev;
+    }
+
+    return this._errorPositions.has(undefined);
+  }
+}
+/**
+ * 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.
+ *   - `extensions` is reserved for adding non-standard properties.
+ */
+
 /**
  * Implements the "Executing requests" section of the GraphQL specification.
  *
@@ -137,18 +186,18 @@ function execute(args) {
 
     if ((0, _isPromise.isPromise)(result)) {
       return result.then(
-        (data) => buildResponse(data, exeContext.errors),
+        (data) => buildResponse(data, exeContext.collectedErrors.errors),
         (error) => {
-          exeContext.errors.push(error);
-          return buildResponse(null, exeContext.errors);
+          exeContext.collectedErrors.add(error, undefined);
+          return buildResponse(null, exeContext.collectedErrors.errors);
         },
       );
     }
 
-    return buildResponse(result, exeContext.errors);
+    return buildResponse(result, exeContext.collectedErrors.errors);
   } catch (error) {
-    exeContext.errors.push(error);
-    return buildResponse(null, exeContext.errors);
+    exeContext.collectedErrors.add(error, undefined);
+    return buildResponse(null, exeContext.collectedErrors.errors);
   }
 }
 /**
@@ -185,6 +234,7 @@ function buildResponse(data, errors) {
  * Essential assertions before executing to provide developer feedback for
  * improper use of the GraphQL library.
  *
+ * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
  * @internal
  */
 
@@ -319,7 +369,7 @@ function buildExecutionContext(args) {
       subscribeFieldResolver !== null && subscribeFieldResolver !== void 0
         ? subscribeFieldResolver
         : defaultFieldResolver,
-    errors: [],
+    collectedErrors: new CollectedErrors(),
   };
 }
 /**
@@ -524,7 +574,7 @@ function executeField(exeContext, parentType, source, fieldNodes, path) {
           fieldNodes,
           (0, _Path.pathToArray)(path),
         );
-        return handleFieldError(error, returnType, exeContext);
+        return handleFieldError(error, returnType, path, exeContext);
       });
     }
 
@@ -535,7 +585,7 @@ function executeField(exeContext, parentType, source, fieldNodes, path) {
       fieldNodes,
       (0, _Path.pathToArray)(path),
     );
-    return handleFieldError(error, returnType, exeContext);
+    return handleFieldError(error, returnType, path, exeContext);
   }
 }
 /**
@@ -559,7 +609,7 @@ function buildResolveInfo(exeContext, fieldDef, fieldNodes, parentType, path) {
   };
 }
 
-function handleFieldError(error, returnType, exeContext) {
+function handleFieldError(error, returnType, path, exeContext) {
   // If the field type is non-nullable, then it is resolved without any
   // protection from errors, however it still properly locates the error.
   if ((0, _definition.isNonNullType)(returnType)) {
@@ -567,7 +617,7 @@ function handleFieldError(error, returnType, exeContext) {
   } // Otherwise, error protection is applied, logging the error and resolving
   // a null value for this field if one is encountered.
 
-  exeContext.errors.push(error);
+  exeContext.collectedErrors.add(error, path);
   return null;
 }
 /**
@@ -732,7 +782,7 @@ function completeListValue(
             fieldNodes,
             (0, _Path.pathToArray)(itemPath),
           );
-          return handleFieldError(error, itemType, exeContext);
+          return handleFieldError(error, itemType, itemPath, exeContext);
         });
       }
 
@@ -743,7 +793,7 @@ function completeListValue(
         fieldNodes,
         (0, _Path.pathToArray)(itemPath),
       );
-      return handleFieldError(error, itemType, exeContext);
+      return handleFieldError(error, itemType, itemPath, exeContext);
     }
   });
   return containsPromise ? Promise.all(completedResults) : completedResults;
@@ -974,6 +1024,15 @@ const defaultTypeResolver = function (value, contextValue, info, abstractType) {
       if ((0, _isPromise.isPromise)(isTypeOfResult)) {
         promisedIsTypeOfResults[i] = isTypeOfResult;
       } else if (isTypeOfResult) {
+        if (promisedIsTypeOfResults.length) {
+          // Explicitly ignore any promise rejections
+          Promise.allSettled(promisedIsTypeOfResults)
+            /* c8 ignore next 3 */
+            .catch(() => {
+              // Do nothing
+            });
+        }
+
         return type.name;
       }
     }

package/execution/execute.mjs

@@ -72,6 +72,55 @@ const collectSubfields = memoize3((exeContext, returnType, fieldNodes) =>
  * and the fragments defined in the query document
  */
 
+/**
+ * @internal
+ */
+class CollectedErrors {
+  constructor() {
+    this._errorPositions = new Set();
+    this._errors = [];
+  }
+
+  get errors() {
+    return this._errors;
+  }
+
+  add(error, path) {
+    // Do not modify errors list if the execution position for this error or
+    // any of its ancestors has already been nulled via error propagation.
+    // This check should be unnecessary for implementations able to implement
+    // actual cancellation.
+    if (this._hasNulledPosition(path)) {
+      return;
+    }
+
+    this._errorPositions.add(path);
+
+    this._errors.push(error);
+  }
+
+  _hasNulledPosition(startPath) {
+    let path = startPath;
+
+    while (path !== undefined) {
+      if (this._errorPositions.has(path)) {
+        return true;
+      }
+
+      path = path.prev;
+    }
+
+    return this._errorPositions.has(undefined);
+  }
+}
+/**
+ * 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.
+ *   - `extensions` is reserved for adding non-standard properties.
+ */
+
 /**
  * Implements the "Executing requests" section of the GraphQL specification.
  *
@@ -118,18 +167,18 @@ export function execute(args) {
 
     if (isPromise(result)) {
       return result.then(
-        (data) => buildResponse(data, exeContext.errors),
+        (data) => buildResponse(data, exeContext.collectedErrors.errors),
         (error) => {
-          exeContext.errors.push(error);
-          return buildResponse(null, exeContext.errors);
+          exeContext.collectedErrors.add(error, undefined);
+          return buildResponse(null, exeContext.collectedErrors.errors);
         },
       );
     }
 
-    return buildResponse(result, exeContext.errors);
+    return buildResponse(result, exeContext.collectedErrors.errors);
   } catch (error) {
-    exeContext.errors.push(error);
-    return buildResponse(null, exeContext.errors);
+    exeContext.collectedErrors.add(error, undefined);
+    return buildResponse(null, exeContext.collectedErrors.errors);
   }
 }
 /**
@@ -166,6 +215,7 @@ function buildResponse(data, errors) {
  * Essential assertions before executing to provide developer feedback for
  * improper use of the GraphQL library.
  *
+ * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
  * @internal
  */
 
@@ -300,7 +350,7 @@ export function buildExecutionContext(args) {
       subscribeFieldResolver !== null && subscribeFieldResolver !== void 0
         ? subscribeFieldResolver
         : defaultFieldResolver,
-    errors: [],
+    collectedErrors: new CollectedErrors(),
   };
 }
 /**
@@ -501,14 +551,14 @@ function executeField(exeContext, parentType, source, fieldNodes, path) {
       // to take a second callback for the error case.
       return completed.then(undefined, (rawError) => {
         const error = locatedError(rawError, fieldNodes, pathToArray(path));
-        return handleFieldError(error, returnType, exeContext);
+        return handleFieldError(error, returnType, path, exeContext);
       });
     }
 
     return completed;
   } catch (rawError) {
     const error = locatedError(rawError, fieldNodes, pathToArray(path));
-    return handleFieldError(error, returnType, exeContext);
+    return handleFieldError(error, returnType, path, exeContext);
   }
 }
 /**
@@ -538,7 +588,7 @@ export function buildResolveInfo(
   };
 }
 
-function handleFieldError(error, returnType, exeContext) {
+function handleFieldError(error, returnType, path, exeContext) {
   // If the field type is non-nullable, then it is resolved without any
   // protection from errors, however it still properly locates the error.
   if (isNonNullType(returnType)) {
@@ -546,7 +596,7 @@ function handleFieldError(error, returnType, exeContext) {
   } // Otherwise, error protection is applied, logging the error and resolving
   // a null value for this field if one is encountered.
 
-  exeContext.errors.push(error);
+  exeContext.collectedErrors.add(error, path);
   return null;
 }
 /**
@@ -710,14 +760,14 @@ function completeListValue(
             fieldNodes,
             pathToArray(itemPath),
           );
-          return handleFieldError(error, itemType, exeContext);
+          return handleFieldError(error, itemType, itemPath, exeContext);
         });
       }
 
       return completedItem;
     } catch (rawError) {
       const error = locatedError(rawError, fieldNodes, pathToArray(itemPath));
-      return handleFieldError(error, itemType, exeContext);
+      return handleFieldError(error, itemType, itemPath, exeContext);
     }
   });
   return containsPromise ? Promise.all(completedResults) : completedResults;
@@ -945,6 +995,15 @@ export const defaultTypeResolver = function (
       if (isPromise(isTypeOfResult)) {
         promisedIsTypeOfResults[i] = isTypeOfResult;
       } else if (isTypeOfResult) {
+        if (promisedIsTypeOfResults.length) {
+          // Explicitly ignore any promise rejections
+          Promise.allSettled(promisedIsTypeOfResults)
+            /* c8 ignore next 3 */
+            .catch(() => {
+              // Do nothing
+            });
+        }
+
         return type.name;
       }
     }

package/execution/subscribe.js

@@ -125,6 +125,7 @@ async function createSourceEventStream(...rawArgs) {
   const args = toNormalizedArgs(rawArgs);
   const { schema, document, variableValues } = args; // If arguments are missing or incorrectly typed, this is an internal
   // developer mistake which should throw an early error.
+  // eslint-disable-next-line import/no-deprecated
 
   (0, _execute.assertValidExecutionArguments)(schema, document, variableValues); // If a valid execution context cannot be created due to incorrect arguments,
   // a "Response" with only errors is returned.

package/execution/subscribe.mjs

@@ -6,6 +6,7 @@ import { GraphQLError } from '../error/GraphQLError.mjs';
 import { locatedError } from '../error/locatedError.mjs';
 import { collectFields } from './collectFields.mjs';
 import {
+  // eslint-disable-next-line import/no-deprecated
   assertValidExecutionArguments,
   buildExecutionContext,
   buildResolveInfo,
@@ -111,6 +112,7 @@ export async function createSourceEventStream(...rawArgs) {
   const args = toNormalizedArgs(rawArgs);
   const { schema, document, variableValues } = args; // If arguments are missing or incorrectly typed, this is an internal
   // developer mistake which should throw an early error.
+  // eslint-disable-next-line import/no-deprecated
 
   assertValidExecutionArguments(schema, document, variableValues); // If a valid execution context cannot be created due to incorrect arguments,
   // a "Response" with only errors is returned.

package/index.d.ts

@@ -190,6 +190,7 @@ export {
   parseValue,
   parseConstValue,
   parseType,
+  parseSchemaCoordinate,
   print,
   visit,
   visitInParallel,
@@ -208,6 +209,7 @@ export {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
+  isSchemaCoordinateNode,
 } from './language/index';
 export type {
   ParseOptions,
@@ -278,6 +280,12 @@ export type {
   UnionTypeExtensionNode,
   EnumTypeExtensionNode,
   InputObjectTypeExtensionNode,
+  SchemaCoordinateNode,
+  TypeCoordinateNode,
+  MemberCoordinateNode,
+  ArgumentCoordinateNode,
+  DirectiveCoordinateNode,
+  DirectiveArgumentCoordinateNode,
 } from './language/index';
 export {
   execute,
@@ -386,6 +394,8 @@ export {
   DangerousChangeType,
   findBreakingChanges,
   findDangerousChanges,
+  resolveSchemaCoordinate,
+  resolveASTSchemaCoordinate,
 } from './utilities/index';
 export type {
   IntrospectionOptions,
@@ -414,4 +424,5 @@ export type {
   BreakingChange,
   DangerousChange,
   TypedQueryDocumentNode,
+  ResolvedSchemaElement,
 } from './utilities/index';

package/index.js

@@ -981,6 +981,12 @@ Object.defineProperty(exports, 'isSchema', {
     return _index.isSchema;
   },
 });
+Object.defineProperty(exports, 'isSchemaCoordinateNode', {
+  enumerable: true,
+  get: function () {
+    return _index2.isSchemaCoordinateNode;
+  },
+});
 Object.defineProperty(exports, 'isSelectionNode', {
   enumerable: true,
   get: function () {
@@ -1089,6 +1095,12 @@ Object.defineProperty(exports, 'parseConstValue', {
     return _index2.parseConstValue;
   },
 });
+Object.defineProperty(exports, 'parseSchemaCoordinate', {
+  enumerable: true,
+  get: function () {
+    return _index2.parseSchemaCoordinate;
+  },
+});
 Object.defineProperty(exports, 'parseType', {
   enumerable: true,
   get: function () {
@@ -1149,6 +1161,12 @@ Object.defineProperty(exports, 'recommendedRules', {
     return _index4.recommendedRules;
   },
 });
+Object.defineProperty(exports, 'resolveASTSchemaCoordinate', {
+  enumerable: true,
+  get: function () {
+    return _index6.resolveASTSchemaCoordinate;
+  },
+});
 Object.defineProperty(exports, 'resolveObjMapThunk', {
   enumerable: true,
   get: function () {
@@ -1161,6 +1179,12 @@ Object.defineProperty(exports, 'resolveReadonlyArrayThunk', {
     return _index.resolveReadonlyArrayThunk;
   },
 });
+Object.defineProperty(exports, 'resolveSchemaCoordinate', {
+  enumerable: true,
+  get: function () {
+    return _index6.resolveSchemaCoordinate;
+  },
+});
 Object.defineProperty(exports, 'responsePathAsArray', {
   enumerable: true,
   get: function () {

package/index.mjs

@@ -135,7 +135,8 @@ export {
   parse,
   parseValue,
   parseConstValue,
-  parseType, // Print
+  parseType,
+  parseSchemaCoordinate, // Print
   print, // Visit
   visit,
   visitInParallel,
@@ -154,6 +155,7 @@ export {
   isTypeDefinitionNode,
   isTypeSystemExtensionNode,
   isTypeExtensionNode,
+  isSchemaCoordinateNode,
 } from './language/index.mjs';
 // Execute GraphQL queries.
 export {
@@ -254,5 +256,7 @@ export {
   BreakingChangeType,
   DangerousChangeType,
   findBreakingChanges,
-  findDangerousChanges,
+  findDangerousChanges, // Schema Coordinates
+  resolveSchemaCoordinate,
+  resolveASTSchemaCoordinate,
 } from './utilities/index.mjs';

package/language/ast.d.ts

@@ -134,7 +134,12 @@ export declare type ASTNode =
   | InterfaceTypeExtensionNode
   | UnionTypeExtensionNode
   | EnumTypeExtensionNode
-  | InputObjectTypeExtensionNode;
+  | InputObjectTypeExtensionNode
+  | TypeCoordinateNode
+  | MemberCoordinateNode
+  | ArgumentCoordinateNode
+  | DirectiveCoordinateNode
+  | DirectiveArgumentCoordinateNode;
 /**
  * Utility type listing all nodes indexed by their kind.
  */
@@ -173,6 +178,7 @@ export declare type ExecutableDefinitionNode =
   | FragmentDefinitionNode;
 export interface OperationDefinitionNode {
   readonly kind: Kind.OPERATION_DEFINITION;
+  readonly description?: StringValueNode;
   readonly loc?: Location;
   readonly operation: OperationTypeNode;
   readonly name?: NameNode;
@@ -188,6 +194,7 @@ declare enum OperationTypeNode {
 export { OperationTypeNode };
 export interface VariableDefinitionNode {
   readonly kind: Kind.VARIABLE_DEFINITION;
+  readonly description?: StringValueNode;
   readonly loc?: Location;
   readonly variable: VariableNode;
   readonly type: TypeNode;
@@ -245,6 +252,7 @@ export interface InlineFragmentNode {
 }
 export interface FragmentDefinitionNode {
   readonly kind: Kind.FRAGMENT_DEFINITION;
+  readonly description?: StringValueNode;
   readonly loc?: Location;
   readonly name: NameNode;
   /** @deprecated variableDefinitions will be removed in v17.0.0 */
@@ -536,3 +544,39 @@ export interface InputObjectTypeExtensionNode {
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
   readonly fields?: ReadonlyArray<InputValueDefinitionNode>;
 }
+/** Schema Coordinates */
+export declare type SchemaCoordinateNode =
+  | TypeCoordinateNode
+  | MemberCoordinateNode
+  | ArgumentCoordinateNode
+  | DirectiveCoordinateNode
+  | DirectiveArgumentCoordinateNode;
+export interface TypeCoordinateNode {
+  readonly kind: Kind.TYPE_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+}
+export interface MemberCoordinateNode {
+  readonly kind: Kind.MEMBER_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+  readonly memberName: NameNode;
+}
+export interface ArgumentCoordinateNode {
+  readonly kind: Kind.ARGUMENT_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+  readonly fieldName: NameNode;
+  readonly argumentName: NameNode;
+}
+export interface DirectiveCoordinateNode {
+  readonly kind: Kind.DIRECTIVE_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+}
+export interface DirectiveArgumentCoordinateNode {
+  readonly kind: Kind.DIRECTIVE_ARGUMENT_COORDINATE;
+  readonly loc?: Location;
+  readonly name: NameNode;
+  readonly argumentName: NameNode;
+}