graphql 16.14.0 → 16.14.1

package/utilities/astFromValue.d.ts

@@ -1,12 +1,11 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
 import type { ValueNode } from '../language/ast';
 import type { GraphQLInputType } from '../type/definition';
 /**
  * Produces a GraphQL Value AST given a JavaScript object.
  * Function will match JavaScript/JSON values to GraphQL AST schema format
- * by using suggested GraphQLInputType. For example:
- *
- *     astFromValue("value", GraphQLString)
+ * by using suggested GraphQLInputType.
  *
  * A GraphQL type must be provided, which will be used to interpret different
  * JavaScript values.
@@ -20,7 +19,38 @@ import type { GraphQLInputType } from '../type/definition';
  * | Number        | Int / Float          |
  * | Unknown       | Enum Value           |
  * | null          | NullValue            |
+ * @param value - Runtime value to convert.
+ * @param type - The GraphQL type to inspect.
+ * @returns A GraphQL value AST for the provided JavaScript value, or null when no literal can represent it.
+ * @example
+ * ```ts
+ * import { print } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { astFromValue } from 'graphql/utilities';
+ *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * const valueNode = astFromValue(
+ *   { stars: 5, tags: ['featured', 'verified'] },
+ *   ReviewInput,
+ * );
  *
+ * print(valueNode); // => '{ stars: 5, tags: ["featured", "verified"] }'
+ * astFromValue(undefined, GraphQLString); // => null
+ * astFromValue(null, new GraphQLNonNull(GraphQLString)); // => null
+ * ```
  */
 export declare function astFromValue(
   value: unknown,

package/utilities/astFromValue.js

@@ -19,12 +19,12 @@ var _definition = require('../type/definition.js');
 
 var _scalars = require('../type/scalars.js');
 
+/** @category Values */
+
 /**
  * Produces a GraphQL Value AST given a JavaScript object.
  * Function will match JavaScript/JSON values to GraphQL AST schema format
- * by using suggested GraphQLInputType. For example:
- *
- *     astFromValue("value", GraphQLString)
+ * by using suggested GraphQLInputType.
  *
  * A GraphQL type must be provided, which will be used to interpret different
  * JavaScript values.
@@ -38,7 +38,38 @@ var _scalars = require('../type/scalars.js');
  * | Number        | Int / Float          |
  * | Unknown       | Enum Value           |
  * | null          | NullValue            |
+ * @param value - Runtime value to convert.
+ * @param type - The GraphQL type to inspect.
+ * @returns A GraphQL value AST for the provided JavaScript value, or null when no literal can represent it.
+ * @example
+ * ```ts
+ * import { print } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { astFromValue } from 'graphql/utilities';
+ *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
  *
+ * const valueNode = astFromValue(
+ *   { stars: 5, tags: ['featured', 'verified'] },
+ *   ReviewInput,
+ * );
+ *
+ * print(valueNode); // => '{ stars: 5, tags: ["featured", "verified"] }'
+ * astFromValue(undefined, GraphQLString); // => null
+ * astFromValue(null, new GraphQLNonNull(GraphQLString)); // => null
+ * ```
  */
 function astFromValue(value, type) {
   if ((0, _definition.isNonNullType)(type)) {
@@ -185,6 +216,8 @@ function astFromValue(value, type) {
  * IntValue:
  *   - NegativeSign? 0
  *   - NegativeSign? NonZeroDigit ( Digit+ )?
+ *
+ * @internal
  */
 
 const integerStringRegExp = /^-?(?:0|[1-9][0-9]*)$/;

package/utilities/astFromValue.mjs

@@ -1,3 +1,4 @@
+/** @category Values */
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
 import { isIterableObject } from '../jsutils/isIterableObject.mjs';
@@ -14,9 +15,7 @@ import { GraphQLID } from '../type/scalars.mjs';
 /**
  * Produces a GraphQL Value AST given a JavaScript object.
  * Function will match JavaScript/JSON values to GraphQL AST schema format
- * by using suggested GraphQLInputType. For example:
- *
- *     astFromValue("value", GraphQLString)
+ * by using suggested GraphQLInputType.
  *
  * A GraphQL type must be provided, which will be used to interpret different
  * JavaScript values.
@@ -30,7 +29,38 @@ import { GraphQLID } from '../type/scalars.mjs';
  * | Number        | Int / Float          |
  * | Unknown       | Enum Value           |
  * | null          | NullValue            |
+ * @param value - Runtime value to convert.
+ * @param type - The GraphQL type to inspect.
+ * @returns A GraphQL value AST for the provided JavaScript value, or null when no literal can represent it.
+ * @example
+ * ```ts
+ * import { print } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { astFromValue } from 'graphql/utilities';
+ *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
  *
+ * const valueNode = astFromValue(
+ *   { stars: 5, tags: ['featured', 'verified'] },
+ *   ReviewInput,
+ * );
+ *
+ * print(valueNode); // => '{ stars: 5, tags: ["featured", "verified"] }'
+ * astFromValue(undefined, GraphQLString); // => null
+ * astFromValue(null, new GraphQLNonNull(GraphQLString)); // => null
+ * ```
  */
 
 export function astFromValue(value, type) {
@@ -172,6 +202,8 @@ export function astFromValue(value, type) {
  * IntValue:
  *   - NegativeSign? 0
  *   - NegativeSign? NonZeroDigit ( Digit+ )?
+ *
+ * @internal
  */
 
 const integerStringRegExp = /^-?(?:0|[1-9][0-9]*)$/;

package/utilities/buildASTSchema.d.ts

@@ -1,8 +1,10 @@
+/** @category Schema Construction */
 import type { DocumentNode } from '../language/ast';
 import type { ParseOptions } from '../language/parser';
 import type { Source } from '../language/source';
 import type { GraphQLSchemaValidationOptions } from '../type/schema';
 import { GraphQLSchema } from '../type/schema';
+/** Options used when building a schema from SDL or a parsed SDL document. */
 export interface BuildSchemaOptions extends GraphQLSchemaValidationOptions {
   /**
    * Set to true to assume the SDL is valid.
@@ -12,22 +14,79 @@ export interface BuildSchemaOptions extends GraphQLSchemaValidationOptions {
   assumeValidSDL?: boolean;
 }
 /**
- * This takes the ast of a schema document produced by the parse function in
- * src/language/parser.js.
+ * Builds a GraphQLSchema from a parsed schema definition language document.
  *
  * If no schema definition is provided, then it will look for types named Query,
  * Mutation and Subscription.
  *
- * Given that AST it constructs a GraphQLSchema. The resulting schema
- * has no resolve methods, so execution will use default resolvers.
+ * The resulting schema has no resolver functions, so execution will use the
+ * default field resolver.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param options - Optional configuration for this operation.
+ * @returns The schema built from the provided SDL document.
+ * @example
+ * ```ts
+ * // Build a schema from a valid parsed SDL document.
+ * import { parse } from 'graphql/language';
+ * import { buildASTSchema } from 'graphql/utilities';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const schema = buildASTSchema(document);
+ *
+ * schema.getQueryType().name; // => 'Query'
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses validation options when the SDL references unknown types.
+ * import { parse } from 'graphql/language';
+ * import { buildASTSchema } from 'graphql/utilities';
+ *
+ * const document = parse('type Query { broken: MissingType }');
+ *
+ * buildASTSchema(document); // throws an error
+ * buildASTSchema(document, {
+ *   assumeValid: true,
+ *   assumeValidSDL: true,
+ * }); // does not throw
+ * ```
  */
 export declare function buildASTSchema(
   documentAST: DocumentNode,
   options?: BuildSchemaOptions,
 ): GraphQLSchema;
 /**
- * A helper function to build a GraphQLSchema directly from a source
- * document.
+ * Builds a GraphQLSchema directly from a schema definition language source.
+ * @param source - The GraphQL source text or source object.
+ * @param options - Optional configuration for this operation.
+ * @returns The schema built from the provided SDL document.
+ * @example
+ * ```ts
+ * // Build a schema from SDL source using the default options.
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema('type Query { hello: String }');
+ *
+ * schema.getQueryType().name; // => 'Query'
+ * ```
+ * @example
+ * ```ts
+ * // This variant enables parser options and omits source locations.
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(
+ *   'directive @tag on FIELD_DEFINITION\n' +
+ *     'directive @compose @tag on FIELD_DEFINITION',
+ *   {
+ *     experimentalDirectivesOnDirectiveDefinitions: true,
+ *     noLocation: true,
+ *   },
+ * );
+ *
+ * const directive = schema.getDirective('compose');
+ *
+ * directive.name; // => 'compose'
+ * directive.astNode.loc; // => undefined
+ * ```
  */
 export declare function buildSchema(
   source: string | Source,

package/utilities/buildASTSchema.js

@@ -20,15 +20,44 @@ var _validate = require('../validation/validate.js');
 
 var _extendSchema = require('./extendSchema.js');
 
+/** @category Schema Construction */
+
 /**
- * This takes the ast of a schema document produced by the parse function in
- * src/language/parser.js.
+ * Builds a GraphQLSchema from a parsed schema definition language document.
  *
  * If no schema definition is provided, then it will look for types named Query,
  * Mutation and Subscription.
  *
- * Given that AST it constructs a GraphQLSchema. The resulting schema
- * has no resolve methods, so execution will use default resolvers.
+ * The resulting schema has no resolver functions, so execution will use the
+ * default field resolver.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param options - Optional configuration for this operation.
+ * @returns The schema built from the provided SDL document.
+ * @example
+ * ```ts
+ * // Build a schema from a valid parsed SDL document.
+ * import { parse } from 'graphql/language';
+ * import { buildASTSchema } from 'graphql/utilities';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const schema = buildASTSchema(document);
+ *
+ * schema.getQueryType().name; // => 'Query'
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses validation options when the SDL references unknown types.
+ * import { parse } from 'graphql/language';
+ * import { buildASTSchema } from 'graphql/utilities';
+ *
+ * const document = parse('type Query { broken: MissingType }');
+ *
+ * buildASTSchema(document); // throws an error
+ * buildASTSchema(document, {
+ *   assumeValid: true,
+ *   assumeValidSDL: true,
+ * }); // does not throw
+ * ```
  */
 function buildASTSchema(documentAST, options) {
   (documentAST != null && documentAST.kind === _kinds.Kind.DOCUMENT) ||
@@ -93,8 +122,38 @@ function buildASTSchema(documentAST, options) {
   return new _schema.GraphQLSchema({ ...config, directives });
 }
 /**
- * A helper function to build a GraphQLSchema directly from a source
- * document.
+ * Builds a GraphQLSchema directly from a schema definition language source.
+ * @param source - The GraphQL source text or source object.
+ * @param options - Optional configuration for this operation.
+ * @returns The schema built from the provided SDL document.
+ * @example
+ * ```ts
+ * // Build a schema from SDL source using the default options.
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema('type Query { hello: String }');
+ *
+ * schema.getQueryType().name; // => 'Query'
+ * ```
+ * @example
+ * ```ts
+ * // This variant enables parser options and omits source locations.
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(
+ *   'directive @tag on FIELD_DEFINITION\n' +
+ *     'directive @compose @tag on FIELD_DEFINITION',
+ *   {
+ *     experimentalDirectivesOnDirectiveDefinitions: true,
+ *     noLocation: true,
+ *   },
+ * );
+ *
+ * const directive = schema.getDirective('compose');
+ *
+ * directive.name; // => 'compose'
+ * directive.astNode.loc; // => undefined
+ * ```
  */
 
 function buildSchema(source, options) {

package/utilities/buildASTSchema.mjs

@@ -1,3 +1,4 @@
+/** @category Schema Construction */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { Kind } from '../language/kinds.mjs';
 import { parse } from '../language/parser.mjs';
@@ -5,16 +6,44 @@ import { specifiedDirectives } from '../type/directives.mjs';
 import { GraphQLSchema } from '../type/schema.mjs';
 import { assertValidSDL } from '../validation/validate.mjs';
 import { extendSchemaImpl } from './extendSchema.mjs';
+/** Options used when building a schema from SDL or a parsed SDL document. */
 
 /**
- * This takes the ast of a schema document produced by the parse function in
- * src/language/parser.js.
+ * Builds a GraphQLSchema from a parsed schema definition language document.
  *
  * If no schema definition is provided, then it will look for types named Query,
  * Mutation and Subscription.
  *
- * Given that AST it constructs a GraphQLSchema. The resulting schema
- * has no resolve methods, so execution will use default resolvers.
+ * The resulting schema has no resolver functions, so execution will use the
+ * default field resolver.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param options - Optional configuration for this operation.
+ * @returns The schema built from the provided SDL document.
+ * @example
+ * ```ts
+ * // Build a schema from a valid parsed SDL document.
+ * import { parse } from 'graphql/language';
+ * import { buildASTSchema } from 'graphql/utilities';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const schema = buildASTSchema(document);
+ *
+ * schema.getQueryType().name; // => 'Query'
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses validation options when the SDL references unknown types.
+ * import { parse } from 'graphql/language';
+ * import { buildASTSchema } from 'graphql/utilities';
+ *
+ * const document = parse('type Query { broken: MissingType }');
+ *
+ * buildASTSchema(document); // throws an error
+ * buildASTSchema(document, {
+ *   assumeValid: true,
+ *   assumeValidSDL: true,
+ * }); // does not throw
+ * ```
  */
 export function buildASTSchema(documentAST, options) {
   (documentAST != null && documentAST.kind === Kind.DOCUMENT) ||
@@ -75,8 +104,38 @@ export function buildASTSchema(documentAST, options) {
   return new GraphQLSchema({ ...config, directives });
 }
 /**
- * A helper function to build a GraphQLSchema directly from a source
- * document.
+ * Builds a GraphQLSchema directly from a schema definition language source.
+ * @param source - The GraphQL source text or source object.
+ * @param options - Optional configuration for this operation.
+ * @returns The schema built from the provided SDL document.
+ * @example
+ * ```ts
+ * // Build a schema from SDL source using the default options.
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema('type Query { hello: String }');
+ *
+ * schema.getQueryType().name; // => 'Query'
+ * ```
+ * @example
+ * ```ts
+ * // This variant enables parser options and omits source locations.
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(
+ *   'directive @tag on FIELD_DEFINITION\n' +
+ *     'directive @compose @tag on FIELD_DEFINITION',
+ *   {
+ *     experimentalDirectivesOnDirectiveDefinitions: true,
+ *     noLocation: true,
+ *   },
+ * );
+ *
+ * const directive = schema.getDirective('compose');
+ *
+ * directive.name; // => 'compose'
+ * directive.astNode.loc; // => undefined
+ * ```
  */
 
 export function buildSchema(source, options) {

package/utilities/buildClientSchema.d.ts

@@ -1,3 +1,4 @@
+/** @category Introspection */
 import type { GraphQLSchemaValidationOptions } from '../type/schema';
 import { GraphQLSchema } from '../type/schema';
 import type { IntrospectionQuery } from './getIntrospectionQuery';
@@ -12,6 +13,20 @@ import type { IntrospectionQuery } from './getIntrospectionQuery';
  *
  * This function expects a complete introspection result. Don't forget to check
  * the "errors" field of a server response before calling this function.
+ * @param introspection - Introspection result data to build from.
+ * @param options - Optional configuration for this operation.
+ * @returns The client schema represented by the introspection result.
+ * @example
+ * ```ts
+ * import { buildClientSchema, introspectionFromSchema, buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema('type Query { hello: String }');
+ * const clientSchema = buildClientSchema(introspectionFromSchema(schema), {
+ *   assumeValid: true,
+ * });
+ *
+ * clientSchema.getQueryType().name; // => 'Query'
+ * ```
  */
 export declare function buildClientSchema(
   introspection: IntrospectionQuery,

package/utilities/buildClientSchema.js

@@ -27,6 +27,8 @@ var _schema = require('../type/schema.js');
 
 var _valueFromAST = require('./valueFromAST.js');
 
+/** @category Introspection */
+
 /**
  * Build a GraphQLSchema for use by client tools.
  *
@@ -38,6 +40,20 @@ var _valueFromAST = require('./valueFromAST.js');
  *
  * This function expects a complete introspection result. Don't forget to check
  * the "errors" field of a server response before calling this function.
+ * @param introspection - Introspection result data to build from.
+ * @param options - Optional configuration for this operation.
+ * @returns The client schema represented by the introspection result.
+ * @example
+ * ```ts
+ * import { buildClientSchema, introspectionFromSchema, buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema('type Query { hello: String }');
+ * const clientSchema = buildClientSchema(introspectionFromSchema(schema), {
+ *   assumeValid: true,
+ * });
+ *
+ * clientSchema.getQueryType().name; // => 'Query'
+ * ```
  */
 function buildClientSchema(introspection, options) {
   ((0, _isObjectLike.isObjectLike)(introspection) &&

package/utilities/buildClientSchema.mjs

@@ -1,3 +1,4 @@
+/** @category Introspection */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { isObjectLike } from '../jsutils/isObjectLike.mjs';
@@ -34,6 +35,20 @@ import { valueFromAST } from './valueFromAST.mjs';
  *
  * This function expects a complete introspection result. Don't forget to check
  * the "errors" field of a server response before calling this function.
+ * @param introspection - Introspection result data to build from.
+ * @param options - Optional configuration for this operation.
+ * @returns The client schema represented by the introspection result.
+ * @example
+ * ```ts
+ * import { buildClientSchema, introspectionFromSchema, buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema('type Query { hello: String }');
+ * const clientSchema = buildClientSchema(introspectionFromSchema(schema), {
+ *   assumeValid: true,
+ * });
+ *
+ * clientSchema.getQueryType().name; // => 'Query'
+ * ```
  */
 
 export function buildClientSchema(introspection, options) {

package/utilities/coerceInputValue.d.ts

@@ -1,3 +1,4 @@
+/** @category Values */
 import { GraphQLError } from '../error/GraphQLError';
 import type { GraphQLInputType } from '../type/definition';
 declare type OnErrorCB = (
@@ -7,6 +8,51 @@ declare type OnErrorCB = (
 ) => void;
 /**
  * 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 declare function coerceInputValue(
   inputValue: unknown,

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);