graphql 16.14.0 → 16.14.1

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,9 +125,7 @@ function extendSchema(schema, documentAST, options) {
     ? schema
     : new _schema.GraphQLSchema(extendedConfig);
 }
-/**
- * @internal
- */
+/** @internal */
 
 function extendSchemaImpl(schemaConfig, documentAST, options) {
   var _schemaDef, _schemaDef$descriptio, _schemaDef2, _options$assumeValid;
@@ -826,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) {
@@ -840,6 +896,8 @@ function getDeprecationReason(node) {
 }
 /**
  * Given a scalar node, returns the string value for the specifiedByURL.
+ *
+ * @internal
  */
 
 function getSpecifiedByURL(node) {
@@ -854,6 +912,8 @@ function getSpecifiedByURL(node) {
 }
 /**
  * Given an input object node, returns if the node should be OneOf.
+ *
+ * @internal
  */
 
 function isOneOf(node) {

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,9 +133,7 @@ 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;
@@ -824,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) {
@@ -835,6 +890,8 @@ function getDeprecationReason(node) {
 }
 /**
  * Given a scalar node, returns the string value for the specifiedByURL.
+ *
+ * @internal
  */
 
 function getSpecifiedByURL(node) {
@@ -846,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) {