graphql 16.13.2 → 16.14.1

package/utilities/coerceInputValue.js

@@ -25,8 +25,55 @@ var _GraphQLError = require('../error/GraphQLError.js');
 
 var _definition = require('../type/definition.js');
 
+/** @category Values */
+
 /**
  * Coerces a JavaScript value given a GraphQL Input Type.
+ * @param inputValue - JavaScript value to coerce.
+ * @param type - GraphQL input type to coerce the value against.
+ * @param onError - Callback invoked for each coercion error.
+ * @returns Coerced value, or undefined if coercion failed and errors were reported.
+ * @example
+ * ```ts
+ * // Coerce runtime input values and throw on invalid input by default.
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { coerceInputValue } from 'graphql/utilities';
+ *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * coerceInputValue({ stars: '5', tags: ['featured'] }, ReviewInput); // => { stars: 5, tags: ['featured'] }
+ * coerceInputValue({ stars: 'bad' }, ReviewInput); // throws an error
+ * ```
+ * @example
+ * ```ts
+ * // This variant collects coercion errors with a custom onError callback.
+ * import { GraphQLInt, GraphQLNonNull } from 'graphql/type';
+ * import { coerceInputValue } from 'graphql/utilities';
+ *
+ * const errors = [];
+ * const value = coerceInputValue(
+ *   null,
+ *   new GraphQLNonNull(GraphQLInt),
+ *   (path, invalidValue, error) => {
+ *     errors.push({ path, invalidValue, message: error.message });
+ *   },
+ * );
+ *
+ * value; // => undefined
+ * errors; // => [ { path: [], invalidValue: null, message: 'Expected non-nullable type "Int!" not to be null.' } ]
+ * ```
  */
 function coerceInputValue(inputValue, type, onError = defaultOnError) {
   return coerceInputValueImpl(inputValue, type, onError, undefined);

package/utilities/coerceInputValue.mjs

@@ -1,3 +1,4 @@
+/** @category Values */
 import { didYouMean } from '../jsutils/didYouMean.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
@@ -16,6 +17,51 @@ import {
 
 /**
  * Coerces a JavaScript value given a GraphQL Input Type.
+ * @param inputValue - JavaScript value to coerce.
+ * @param type - GraphQL input type to coerce the value against.
+ * @param onError - Callback invoked for each coercion error.
+ * @returns Coerced value, or undefined if coercion failed and errors were reported.
+ * @example
+ * ```ts
+ * // Coerce runtime input values and throw on invalid input by default.
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { coerceInputValue } from 'graphql/utilities';
+ *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * coerceInputValue({ stars: '5', tags: ['featured'] }, ReviewInput); // => { stars: 5, tags: ['featured'] }
+ * coerceInputValue({ stars: 'bad' }, ReviewInput); // throws an error
+ * ```
+ * @example
+ * ```ts
+ * // This variant collects coercion errors with a custom onError callback.
+ * import { GraphQLInt, GraphQLNonNull } from 'graphql/type';
+ * import { coerceInputValue } from 'graphql/utilities';
+ *
+ * const errors = [];
+ * const value = coerceInputValue(
+ *   null,
+ *   new GraphQLNonNull(GraphQLInt),
+ *   (path, invalidValue, error) => {
+ *     errors.push({ path, invalidValue, message: error.message });
+ *   },
+ * );
+ *
+ * value; // => undefined
+ * errors; // => [ { path: [], invalidValue: null, message: 'Expected non-nullable type "Int!" not to be null.' } ]
+ * ```
  */
 export function coerceInputValue(inputValue, type, onError = defaultOnError) {
   return coerceInputValueImpl(inputValue, type, onError, undefined);

package/utilities/concatAST.d.ts

@@ -1,8 +1,20 @@
+/** @category AST Utilities */
 import type { DocumentNode } from '../language/ast';
 /**
  * Provided a collection of ASTs, presumably each from different files,
  * concatenate the ASTs together into batched AST, useful for validating many
  * GraphQL source files which together represent one conceptual application.
+ * @param documents - Document ASTs to concatenate.
+ * @returns A document AST containing all definitions from the provided documents.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { concatAST } from 'graphql/utilities';
+ *
+ * const document = concatAST([parse('type Query { a: String }'), parse('type User { id: ID }')]);
+ *
+ * document.definitions.length; // => 2
+ * ```
  */
 export declare function concatAST(
   documents: ReadonlyArray<DocumentNode>,

package/utilities/concatAST.js

@@ -7,10 +7,23 @@ exports.concatAST = concatAST;
 
 var _kinds = require('../language/kinds.js');
 
+/** @category AST Utilities */
+
 /**
  * Provided a collection of ASTs, presumably each from different files,
  * concatenate the ASTs together into batched AST, useful for validating many
  * GraphQL source files which together represent one conceptual application.
+ * @param documents - Document ASTs to concatenate.
+ * @returns A document AST containing all definitions from the provided documents.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { concatAST } from 'graphql/utilities';
+ *
+ * const document = concatAST([parse('type Query { a: String }'), parse('type User { id: ID }')]);
+ *
+ * document.definitions.length; // => 2
+ * ```
  */
 function concatAST(documents) {
   const definitions = [];

package/utilities/concatAST.mjs

@@ -1,8 +1,20 @@
+/** @category AST Utilities */
 import { Kind } from '../language/kinds.mjs';
 /**
  * Provided a collection of ASTs, presumably each from different files,
  * concatenate the ASTs together into batched AST, useful for validating many
  * GraphQL source files which together represent one conceptual application.
+ * @param documents - Document ASTs to concatenate.
+ * @returns A document AST containing all definitions from the provided documents.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { concatAST } from 'graphql/utilities';
+ *
+ * const document = concatAST([parse('type Query { a: String }'), parse('type User { id: ID }')]);
+ *
+ * document.definitions.length; // => 2
+ * ```
  */
 
 export function concatAST(documents) {

package/utilities/extendSchema.d.ts

@@ -1,3 +1,4 @@
+/** @category Schema Construction */
 import type { DocumentNode } from '../language/ast';
 import type {
   GraphQLSchemaNormalizedConfig,
@@ -23,15 +24,67 @@ interface Options extends GraphQLSchemaValidationOptions {
  *
  * This algorithm copies the provided schema, applying extensions while
  * producing the copy. The original schema remains unaltered.
+ * @param schema - GraphQL schema to use.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param options - Optional configuration for this operation.
+ * @returns A new schema with the extensions and definitions applied.
+ * @example
+ * ```ts
+ * // Extend a schema with new fields and types.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, extendSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const extensionAST = parse(`
+ *   extend type Query {
+ *     farewell: String
+ *   }
+ *
+ *   type Review {
+ *     body: String
+ *   }
+ * `);
+ *
+ * const extendedSchema = extendSchema(schema, extensionAST);
+ *
+ * schema.getType('Review'); // => undefined
+ * extendedSchema.getType('Review')?.name; // => 'Review'
+ * Object.keys(extendedSchema.getQueryType().getFields()); // => ['greeting', 'farewell']
+ * ```
+ * @example
+ * ```ts
+ * // This variant bypasses validation for an otherwise invalid extension.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, extendSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const invalidExtension = parse(`
+ *   extend type Missing {
+ *     field: String
+ *   }
+ * `);
+ *
+ * extendSchema(schema, invalidExtension); // throws an error
+ * extendSchema(schema, invalidExtension, {
+ *     assumeValid: true,
+ *     assumeValidSDL: true,
+ *   }); // does not throw
+ * ```
  */
 export declare function extendSchema(
   schema: GraphQLSchema,
   documentAST: DocumentNode,
   options?: Options,
 ): GraphQLSchema;
-/**
- * @internal
- */
+/** @internal */
 export declare function extendSchemaImpl(
   schemaConfig: GraphQLSchemaNormalizedConfig,
   documentAST: DocumentNode,

package/utilities/extendSchema.js

@@ -36,6 +36,8 @@ var _values = require('../execution/values.js');
 
 var _valueFromAST = require('./valueFromAST.js');
 
+/** @category Schema Construction */
+
 /**
  * Produces a new schema given an existing schema and a document which may
  * contain GraphQL type extensions and definitions. The original schema will
@@ -47,6 +49,60 @@ var _valueFromAST = require('./valueFromAST.js');
  *
  * This algorithm copies the provided schema, applying extensions while
  * producing the copy. The original schema remains unaltered.
+ * @param schema - GraphQL schema to use.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param options - Optional configuration for this operation.
+ * @returns A new schema with the extensions and definitions applied.
+ * @example
+ * ```ts
+ * // Extend a schema with new fields and types.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, extendSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const extensionAST = parse(`
+ *   extend type Query {
+ *     farewell: String
+ *   }
+ *
+ *   type Review {
+ *     body: String
+ *   }
+ * `);
+ *
+ * const extendedSchema = extendSchema(schema, extensionAST);
+ *
+ * schema.getType('Review'); // => undefined
+ * extendedSchema.getType('Review')?.name; // => 'Review'
+ * Object.keys(extendedSchema.getQueryType().getFields()); // => ['greeting', 'farewell']
+ * ```
+ * @example
+ * ```ts
+ * // This variant bypasses validation for an otherwise invalid extension.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, extendSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const invalidExtension = parse(`
+ *   extend type Missing {
+ *     field: String
+ *   }
+ * `);
+ *
+ * extendSchema(schema, invalidExtension); // throws an error
+ * extendSchema(schema, invalidExtension, {
+ *     assumeValid: true,
+ *     assumeValidSDL: true,
+ *   }); // does not throw
+ * ```
  */
 function extendSchema(schema, documentAST, options) {
   (0, _schema.assertSchema)(schema);
@@ -69,16 +125,15 @@ function extendSchema(schema, documentAST, options) {
     ? schema
     : new _schema.GraphQLSchema(extendedConfig);
 }
-/**
- * @internal
- */
+/** @internal */
 
 function extendSchemaImpl(schemaConfig, documentAST, options) {
   var _schemaDef, _schemaDef$descriptio, _schemaDef2, _options$assumeValid;
 
   // Collect the type definitions and extensions found in the document.
   const typeDefs = [];
-  const typeExtensionsMap = Object.create(null); // New directives and types are separate because a directives and types can
+  const typeExtensionsMap = Object.create(null);
+  const directiveExtensionsMap = Object.create(null); // New directives and types are separate because a directives and types can
   // have the same name. For example, a type named "skip".
 
   const directiveDefs = [];
@@ -101,6 +156,14 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
         : [def];
     } else if (def.kind === _kinds.Kind.DIRECTIVE_DEFINITION) {
       directiveDefs.push(def);
+    } else if (def.kind === _kinds.Kind.DIRECTIVE_EXTENSION) {
+      const extendedDirectiveName = def.name.value;
+      const existingDirectiveExtensions =
+        directiveExtensionsMap[extendedDirectiveName];
+      directiveExtensionsMap[extendedDirectiveName] =
+        existingDirectiveExtensions
+          ? existingDirectiveExtensions.concat([def])
+          : [def];
     }
   } // If this document contains no new types, extensions, or directives then
   // return the same unmodified GraphQLSchema instance.
@@ -108,6 +171,7 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
   if (
     Object.keys(typeExtensionsMap).length === 0 &&
     typeDefs.length === 0 &&
+    Object.keys(directiveExtensionsMap).length === 0 &&
     directiveDefs.length === 0 &&
     schemaExtensions.length === 0 &&
     schemaDef == null
@@ -132,6 +196,12 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
         : buildType(typeNode);
   }
 
+  const directiveMap = Object.create(null);
+
+  for (const existingDirective of schemaConfig.directives) {
+    directiveMap[existingDirective.name] = extendDirective(existingDirective);
+  }
+
   const operationTypes = {
     // Get the extended root operation types.
     query: schemaConfig.query && replaceNamedType(schemaConfig.query),
@@ -143,6 +213,8 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
     ...getOperationTypes(schemaExtensions),
   }; // Then produce and return a Schema config with these types.
 
+  const directives = Object.values(directiveMap); // will be `Array<GraphQLDirective>`
+
   return {
     description:
       (_schemaDef = schemaDef) === null || _schemaDef === void 0
@@ -154,7 +226,7 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
     ...operationTypes,
     types: Object.values(typeMap),
     directives: [
-      ...schemaConfig.directives.map(replaceDirective),
+      ...directives.map(replaceDirective),
       ...directiveDefs.map(buildDirective),
     ],
     extensions: Object.create(null),
@@ -413,6 +485,29 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
     return opTypes;
   }
 
+  function extendDirective(directive) {
+    var _directiveExtensionsM, _config$deprecationRe;
+
+    const config = directive.toConfig();
+    const extensions =
+      (_directiveExtensionsM = directiveExtensionsMap[config.name]) !== null &&
+      _directiveExtensionsM !== void 0
+        ? _directiveExtensionsM
+        : [];
+    const deprecationReason =
+      (_config$deprecationRe = config.deprecationReason) !== null &&
+      _config$deprecationRe !== void 0
+        ? _config$deprecationRe
+        : extensions
+            .map((ext) => getDeprecationReason(ext))
+            .find((reason) => reason != null);
+    return new _directives.GraphQLDirective({
+      ...config,
+      deprecationReason,
+      extensionASTNodes: config.extensionASTNodes.concat(extensions),
+    });
+  }
+
   function getNamedType(node) {
     var _stdTypeMap$name2;
 
@@ -443,8 +538,20 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
   }
 
   function buildDirective(node) {
-    var _node$description;
+    var _directiveExtensionsM2, _getDeprecationReason, _node$description;
 
+    const extensions =
+      (_directiveExtensionsM2 = directiveExtensionsMap[node.name.value]) !==
+        null && _directiveExtensionsM2 !== void 0
+        ? _directiveExtensionsM2
+        : [];
+    const deprecationReason =
+      (_getDeprecationReason = getDeprecationReason(node)) !== null &&
+      _getDeprecationReason !== void 0
+        ? _getDeprecationReason
+        : extensions
+            .map((ext) => getDeprecationReason(ext))
+            .find((reason) => reason != null);
     return new _directives.GraphQLDirective({
       name: node.name.value,
       description:
@@ -456,7 +563,9 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
       locations: node.locations.map(({ value }) => value),
       isRepeatable: node.repeatable,
       args: buildArgumentMap(node.arguments),
+      deprecationReason,
       astNode: node,
+      extensionASTNodes: extensions,
     });
   }
 
@@ -771,6 +880,8 @@ const stdTypeMap = (0, _keyMap.keyMap)(
 /**
  * Given a field or enum value node, returns the string value for the
  * deprecation reason.
+ *
+ * @internal
  */
 
 function getDeprecationReason(node) {
@@ -785,6 +896,8 @@ function getDeprecationReason(node) {
 }
 /**
  * Given a scalar node, returns the string value for the specifiedByURL.
+ *
+ * @internal
  */
 
 function getSpecifiedByURL(node) {
@@ -799,6 +912,8 @@ function getSpecifiedByURL(node) {
 }
 /**
  * Given an input object node, returns if the node should be OneOf.
+ *
+ * @internal
  */
 
 function isOneOf(node) {