graphql 16.13.2 → 16.14.1

package/utilities/extendSchema.mjs

@@ -1,3 +1,4 @@
+/** @category Schema Construction */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
@@ -56,6 +57,60 @@ import { valueFromAST } from './valueFromAST.mjs';
  *
  * 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 function extendSchema(schema, documentAST, options) {
   assertSchema(schema);
@@ -78,16 +133,15 @@ export function extendSchema(schema, documentAST, options) {
     ? schema
     : new GraphQLSchema(extendedConfig);
 }
-/**
- * @internal
- */
+/** @internal */
 
 export 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 = [];
@@ -110,6 +164,14 @@ export function extendSchemaImpl(schemaConfig, documentAST, options) {
         : [def];
     } else if (def.kind === Kind.DIRECTIVE_DEFINITION) {
       directiveDefs.push(def);
+    } else if (def.kind === 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.
@@ -117,6 +179,7 @@ export 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
@@ -141,6 +204,12 @@ export 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),
@@ -152,6 +221,8 @@ export 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
@@ -163,7 +234,7 @@ export 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),
@@ -415,6 +486,29 @@ export 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 GraphQLDirective({
+      ...config,
+      deprecationReason,
+      extensionASTNodes: config.extensionASTNodes.concat(extensions),
+    });
+  }
+
   function getNamedType(node) {
     var _stdTypeMap$name2;
 
@@ -445,8 +539,20 @@ export 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 GraphQLDirective({
       name: node.name.value,
       description:
@@ -458,7 +564,9 @@ export function extendSchemaImpl(schemaConfig, documentAST, options) {
       locations: node.locations.map(({ value }) => value),
       isRepeatable: node.repeatable,
       args: buildArgumentMap(node.arguments),
+      deprecationReason,
       astNode: node,
+      extensionASTNodes: extensions,
     });
   }
 
@@ -769,6 +877,8 @@ const stdTypeMap = keyMap(
 /**
  * Given a field or enum value node, returns the string value for the
  * deprecation reason.
+ *
+ * @internal
  */
 
 function getDeprecationReason(node) {
@@ -780,6 +890,8 @@ function getDeprecationReason(node) {
 }
 /**
  * Given a scalar node, returns the string value for the specifiedByURL.
+ *
+ * @internal
  */
 
 function getSpecifiedByURL(node) {
@@ -791,6 +903,8 @@ function getSpecifiedByURL(node) {
 }
 /**
  * Given an input object node, returns if the node should be OneOf.
+ *
+ * @internal
  */
 
 function isOneOf(node) {

package/utilities/findBreakingChanges.d.ts

@@ -1,43 +1,106 @@
+/** @category Schema Changes */
 import type { GraphQLSchema } from '../type/schema';
+/** Categories of schema changes that may break existing operations. */
 declare enum BreakingChangeType {
+  /** Breaking change code for type removed. */
   TYPE_REMOVED = 'TYPE_REMOVED',
+  /** Breaking change code for type changed kind. */
   TYPE_CHANGED_KIND = 'TYPE_CHANGED_KIND',
+  /** Breaking change code for type removed from union. */
   TYPE_REMOVED_FROM_UNION = 'TYPE_REMOVED_FROM_UNION',
+  /** Breaking change code for value removed from enum. */
   VALUE_REMOVED_FROM_ENUM = 'VALUE_REMOVED_FROM_ENUM',
+  /** Breaking change code for required input field added. */
   REQUIRED_INPUT_FIELD_ADDED = 'REQUIRED_INPUT_FIELD_ADDED',
+  /** Breaking change code for implemented interface removed. */
   IMPLEMENTED_INTERFACE_REMOVED = 'IMPLEMENTED_INTERFACE_REMOVED',
+  /** Breaking change code for field removed. */
   FIELD_REMOVED = 'FIELD_REMOVED',
+  /** Breaking change code for field changed kind. */
   FIELD_CHANGED_KIND = 'FIELD_CHANGED_KIND',
+  /** Breaking change code for required arg added. */
   REQUIRED_ARG_ADDED = 'REQUIRED_ARG_ADDED',
+  /** Breaking change code for arg removed. */
   ARG_REMOVED = 'ARG_REMOVED',
+  /** Breaking change code for arg changed kind. */
   ARG_CHANGED_KIND = 'ARG_CHANGED_KIND',
+  /** Breaking change code for directive removed. */
   DIRECTIVE_REMOVED = 'DIRECTIVE_REMOVED',
+  /** Breaking change code for directive arg removed. */
   DIRECTIVE_ARG_REMOVED = 'DIRECTIVE_ARG_REMOVED',
+  /** Breaking change code for required directive arg added. */
   REQUIRED_DIRECTIVE_ARG_ADDED = 'REQUIRED_DIRECTIVE_ARG_ADDED',
+  /** Breaking change code for directive repeatable removed. */
   DIRECTIVE_REPEATABLE_REMOVED = 'DIRECTIVE_REPEATABLE_REMOVED',
+  /** Breaking change code for directive location removed. */
   DIRECTIVE_LOCATION_REMOVED = 'DIRECTIVE_LOCATION_REMOVED',
 }
 export { BreakingChangeType };
+/** Categories of schema changes that may be dangerous for existing operations. */
 declare enum DangerousChangeType {
+  /** Dangerous change code for value added to enum. */
   VALUE_ADDED_TO_ENUM = 'VALUE_ADDED_TO_ENUM',
+  /** Dangerous change code for type added to union. */
   TYPE_ADDED_TO_UNION = 'TYPE_ADDED_TO_UNION',
+  /** Dangerous change code for optional input field added. */
   OPTIONAL_INPUT_FIELD_ADDED = 'OPTIONAL_INPUT_FIELD_ADDED',
+  /** Dangerous change code for optional arg added. */
   OPTIONAL_ARG_ADDED = 'OPTIONAL_ARG_ADDED',
+  /** Dangerous change code for implemented interface added. */
   IMPLEMENTED_INTERFACE_ADDED = 'IMPLEMENTED_INTERFACE_ADDED',
+  /** Dangerous change code for arg default value change. */
   ARG_DEFAULT_VALUE_CHANGE = 'ARG_DEFAULT_VALUE_CHANGE',
 }
 export { DangerousChangeType };
+/** Description of a schema change that may break existing operations. */
 export interface BreakingChange {
+  /** Specific kind of breaking schema change. */
   type: BreakingChangeType;
+  /** Human-readable description of the breaking schema change. */
   description: string;
 }
+/** Description of a schema change that may be dangerous for existing operations. */
 export interface DangerousChange {
+  /** Specific kind of dangerous schema change. */
   type: DangerousChangeType;
+  /** Human-readable description of the dangerous schema change. */
   description: string;
 }
 /**
  * Given two schemas, returns an Array containing descriptions of all the types
  * of breaking changes covered by the other functions down below.
+ * @param oldSchema - Schema before the change.
+ * @param newSchema - Schema after the change.
+ * @returns Breaking changes between the two schemas.
+ * @example
+ * ```ts
+ * import { buildSchema, findBreakingChanges } from 'graphql/utilities';
+ *
+ * const oldSchema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ * const newSchema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ *
+ * const changes = findBreakingChanges(oldSchema, newSchema);
+ *
+ * changes[0].type; // => 'FIELD_REMOVED'
+ * changes[0].description; // matches /User.name was removed/
+ * ```
  */
 export declare function findBreakingChanges(
   oldSchema: GraphQLSchema,
@@ -46,6 +109,38 @@ export declare function findBreakingChanges(
 /**
  * Given two schemas, returns an Array containing descriptions of all the types
  * of potentially dangerous changes covered by the other functions down below.
+ * @param oldSchema - Schema before the change.
+ * @param newSchema - Schema after the change.
+ * @returns Dangerous changes between the two schemas.
+ * @example
+ * ```ts
+ * import { buildSchema, findDangerousChanges } from 'graphql/utilities';
+ *
+ * const oldSchema = buildSchema(`
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     episode: Episode
+ *   }
+ * `);
+ * const newSchema = buildSchema(`
+ *   enum Episode {
+ *     NEW_HOPE
+ *     EMPIRE
+ *   }
+ *
+ *   type Query {
+ *     episode: Episode
+ *   }
+ * `);
+ *
+ * const changes = findDangerousChanges(oldSchema, newSchema);
+ *
+ * changes[0].type; // => 'VALUE_ADDED_TO_ENUM'
+ * changes[0].description; // matches /EMPIRE was added/
+ * ```
  */
 export declare function findDangerousChanges(
   oldSchema: GraphQLSchema,

package/utilities/findBreakingChanges.js

@@ -23,6 +23,9 @@ var _astFromValue = require('./astFromValue.js');
 
 var _sortValueNode = require('./sortValueNode.js');
 
+/** @category Schema Changes */
+
+/** Categories of schema changes that may break existing operations. */
 var BreakingChangeType;
 exports.BreakingChangeType = BreakingChangeType;
 
@@ -52,6 +55,7 @@ exports.BreakingChangeType = BreakingChangeType;
   BreakingChangeType || (exports.BreakingChangeType = BreakingChangeType = {}),
 );
 
+/** Categories of schema changes that may be dangerous for existing operations. */
 var DangerousChangeType;
 exports.DangerousChangeType = DangerousChangeType;
 
@@ -72,6 +76,38 @@ exports.DangerousChangeType = DangerousChangeType;
 /**
  * Given two schemas, returns an Array containing descriptions of all the types
  * of breaking changes covered by the other functions down below.
+ * @param oldSchema - Schema before the change.
+ * @param newSchema - Schema after the change.
+ * @returns Breaking changes between the two schemas.
+ * @example
+ * ```ts
+ * import { buildSchema, findBreakingChanges } from 'graphql/utilities';
+ *
+ * const oldSchema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ * const newSchema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ *
+ * const changes = findBreakingChanges(oldSchema, newSchema);
+ *
+ * changes[0].type; // => 'FIELD_REMOVED'
+ * changes[0].description; // matches /User.name was removed/
+ * ```
  */
 function findBreakingChanges(oldSchema, newSchema) {
   // @ts-expect-error
@@ -82,6 +118,38 @@ function findBreakingChanges(oldSchema, newSchema) {
 /**
  * Given two schemas, returns an Array containing descriptions of all the types
  * of potentially dangerous changes covered by the other functions down below.
+ * @param oldSchema - Schema before the change.
+ * @param newSchema - Schema after the change.
+ * @returns Dangerous changes between the two schemas.
+ * @example
+ * ```ts
+ * import { buildSchema, findDangerousChanges } from 'graphql/utilities';
+ *
+ * const oldSchema = buildSchema(`
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     episode: Episode
+ *   }
+ * `);
+ * const newSchema = buildSchema(`
+ *   enum Episode {
+ *     NEW_HOPE
+ *     EMPIRE
+ *   }
+ *
+ *   type Query {
+ *     episode: Episode
+ *   }
+ * `);
+ *
+ * const changes = findDangerousChanges(oldSchema, newSchema);
+ *
+ * changes[0].type; // => 'VALUE_ADDED_TO_ENUM'
+ * changes[0].description; // matches /EMPIRE was added/
+ * ```
  */
 
 function findDangerousChanges(oldSchema, newSchema) {

package/utilities/findBreakingChanges.mjs

@@ -1,3 +1,4 @@
+/** @category Schema Changes */
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
 import { keyMap } from '../jsutils/keyMap.mjs';
@@ -18,6 +19,8 @@ import {
 import { isSpecifiedScalarType } from '../type/scalars.mjs';
 import { astFromValue } from './astFromValue.mjs';
 import { sortValueNode } from './sortValueNode.mjs';
+/** Categories of schema changes that may break existing operations. */
+
 var BreakingChangeType;
 
 (function (BreakingChangeType) {
@@ -45,6 +48,8 @@ var BreakingChangeType;
 })(BreakingChangeType || (BreakingChangeType = {}));
 
 export { BreakingChangeType };
+/** Categories of schema changes that may be dangerous for existing operations. */
+
 var DangerousChangeType;
 
 (function (DangerousChangeType) {
@@ -59,10 +64,43 @@ var DangerousChangeType;
 })(DangerousChangeType || (DangerousChangeType = {}));
 
 export { DangerousChangeType };
+/** Description of a schema change that may break existing operations. */
 
 /**
  * Given two schemas, returns an Array containing descriptions of all the types
  * of breaking changes covered by the other functions down below.
+ * @param oldSchema - Schema before the change.
+ * @param newSchema - Schema after the change.
+ * @returns Breaking changes between the two schemas.
+ * @example
+ * ```ts
+ * import { buildSchema, findBreakingChanges } from 'graphql/utilities';
+ *
+ * const oldSchema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ * const newSchema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ *
+ * const changes = findBreakingChanges(oldSchema, newSchema);
+ *
+ * changes[0].type; // => 'FIELD_REMOVED'
+ * changes[0].description; // matches /User.name was removed/
+ * ```
  */
 export function findBreakingChanges(oldSchema, newSchema) {
   // @ts-expect-error
@@ -73,6 +111,38 @@ export function findBreakingChanges(oldSchema, newSchema) {
 /**
  * Given two schemas, returns an Array containing descriptions of all the types
  * of potentially dangerous changes covered by the other functions down below.
+ * @param oldSchema - Schema before the change.
+ * @param newSchema - Schema after the change.
+ * @returns Dangerous changes between the two schemas.
+ * @example
+ * ```ts
+ * import { buildSchema, findDangerousChanges } from 'graphql/utilities';
+ *
+ * const oldSchema = buildSchema(`
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     episode: Episode
+ *   }
+ * `);
+ * const newSchema = buildSchema(`
+ *   enum Episode {
+ *     NEW_HOPE
+ *     EMPIRE
+ *   }
+ *
+ *   type Query {
+ *     episode: Episode
+ *   }
+ * `);
+ *
+ * const changes = findDangerousChanges(oldSchema, newSchema);
+ *
+ * changes[0].type; // => 'VALUE_ADDED_TO_ENUM'
+ * changes[0].description; // matches /EMPIRE was added/
+ * ```
  */
 
 export function findDangerousChanges(oldSchema, newSchema) {