graphql - npm Package Compare versions

Comparing version 16.14.0 to 16.14.1

error/GraphQLError.d.ts

@@ -0,1 +1,2 @@
+/** @category Errors */
 import type { Maybe } from '../jsutils/Maybe';
@@ -7,3 +8,2 @@ import type { ASTNode } from '../language/ast';
  * Custom extensions
- *
  * @remarks
@@ -20,3 +20,2 @@ * Use a unique identifier name for your extension, for example the name of
  * Custom formatted extensions
- *
  * @remarks
@@ -31,12 +30,20 @@ * Use a unique identifier name for your extension, for example the name of
 }
+/** Options used to construct a GraphQLError. */
 export interface GraphQLErrorOptions {
+  /** AST node or nodes associated with this error. */
   nodes?: ReadonlyArray<ASTNode> | ASTNode | null;
+  /** Source document used to derive error locations. */
   source?: Maybe<Source>;
+  /** Character offsets in the source document associated with this error. */
   positions?: Maybe<ReadonlyArray<number>>;
+  /** Response path where this error occurred during execution. */
   path?: Maybe<ReadonlyArray<string | number>>;
+  /** Original error that caused this GraphQLError, if one exists. */
   originalError?: Maybe<
     Error & {
+      /** Extension fields associated with this value. */
       readonly extensions?: unknown;
     }
   >;
+  /** Extension fields to include in the formatted result. */
   extensions?: Maybe<GraphQLErrorExtensions>;
@@ -69,5 +76,3 @@ }
   readonly path: ReadonlyArray<string | number> | undefined;
-  /**
-   * An array of GraphQL AST Nodes corresponding to this error.
-   */
+  /** An array of GraphQL AST Nodes corresponding to this error. */
   readonly nodes: ReadonlyArray<ASTNode> | undefined;
@@ -86,12 +91,88 @@ /**
   readonly positions: ReadonlyArray<number> | undefined;
-  /**
-   * The original error thrown from a field resolver during execution.
-   */
+  /** Original error that caused this GraphQLError, if one exists. */
   readonly originalError: Error | undefined;
+  /** Extension fields to add to the formatted error. */
+  readonly extensions: GraphQLErrorExtensions;
   /**
-   * Extension fields to add to the formatted error.
+   * Creates a GraphQLError instance.
+   * @param message - Human-readable error message.
+   * @param options - Error metadata such as source locations, response path, original error, and extensions.
+   * This positional-arguments constructor overload is deprecated. Use the
+   * `GraphQLError(message, options)` overload instead.
+   * @example
+   * ```ts
+   * // Create an error from AST nodes and response metadata.
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const document = parse('{ greeting }');
+   * const fieldNode = document.definitions[0].selectionSet.selections[0];
+   * const error = new GraphQLError('Cannot query this field.', {
+   *   nodes: fieldNode,
+   *   path: ['greeting'],
+   *   extensions: { code: 'FORBIDDEN' },
+   * });
+   *
+   * error.message; // => 'Cannot query this field.'
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.extensions; // => { code: 'FORBIDDEN' }
+   * ```
+   * @example
+   * ```ts
+   * // This variant derives locations from source positions and preserves the original error.
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError('Resolver failed.', {
+   *   source,
+   *   positions: [2],
+   *   path: ['greeting'],
+   *   originalError,
+   * });
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * ```
    */
-  readonly extensions: GraphQLErrorExtensions;
   constructor(message: string, options?: GraphQLErrorOptions);
   /**
+   * Creates a GraphQLError instance using the legacy positional constructor.
+   * This deprecated overload will be removed in v17. Prefer the
+   * `GraphQLErrorOptions` object overload, which keeps optional error metadata
+   * in a single options bag.
+   * @param message - Human-readable error message.
+   * @param nodes - AST node or nodes associated with this error.
+   * @param source - Source document used to derive error locations.
+   * @param positions - Character offsets in the source document associated with
+   * this error.
+   * @param path - Response path where this error occurred during execution.
+   * @param originalError - Original error that caused this GraphQLError, if one
+   * exists.
+   * @param extensions - Extension fields to include in the formatted error.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError(
+   *   'Resolver failed.',
+   *   undefined,
+   *   source,
+   *   [2],
+   *   ['greeting'],
+   *   originalError,
+   *   { code: 'INTERNAL' },
+   * );
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * error.extensions; // => { code: 'INTERNAL' }
+   * ```
    * @deprecated Please use the `GraphQLErrorOptions` constructor overload instead.
@@ -112,9 +193,42 @@ */
   );
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * Returns this error as a human-readable message with source locations.
+   * @returns The formatted error string.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Cannot query field "name".', {
+   *   source: new Source('{ name }'),
+   *   positions: [2],
+   * });
+   *
+   * error.toString(); // => 'Cannot query field "name".\n\nGraphQL request:1:3\n1 | { name }\n  |   ^'
+   * ```
+   */
   toString(): string;
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Resolver failed.', {
+   *   path: ['viewer', 'name'],
+   *   extensions: { code: 'INTERNAL' },
+   * });
+   *
+   * error.toJSON(); // => { message: 'Resolver failed.', path: ['viewer', 'name'], extensions: { code: 'INTERNAL' } }
+   * ```
+   */
   toJSON(): GraphQLFormattedError;
 }
-/**
- * See: https://spec.graphql.org/draft/#sec-Errors
- */
+/** See: https://spec.graphql.org/draft/#sec-Errors */
 export interface GraphQLFormattedError {
@@ -147,4 +261,15 @@ /**
  * Prints a GraphQLError to a string, representing useful location information
- * about the error's position in the source.
+ * about the error's position in the source. This deprecated helper is retained
+ * for backwards compatibility; call `error.toString()` instead because
+ * printError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { GraphQLError, printError } from 'graphql/error';
  *
+ * const message = printError(new GraphQLError('Example error'));
+ *
+ * message; // => 'Example error'
+ * ```
  * @deprecated Please use `error.toString` instead. Will be removed in v17
@@ -155,6 +280,17 @@ */
  * Given a GraphQLError, format it according to the rules described by the
- * Response Format, Errors section of the GraphQL Specification.
+ * Response Format, Errors section of the GraphQL Specification. This deprecated
+ * helper is retained for backwards compatibility; call `error.toJSON()`
+ * instead because formatError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The JSON-serializable formatted error.
+ * @example
+ * ```ts
+ * import { GraphQLError, formatError } from 'graphql/error';
  *
+ * const formatted = formatError(new GraphQLError('Example error'));
+ *
+ * formatted; // => { message: 'Example error' }
+ * ```
  * @deprecated Please use `error.toJSON` instead. Will be removed in v17
  */
 export declare function formatError(error: GraphQLError): GraphQLFormattedError;

error/GraphQLError.js

@@ -16,2 +16,3 @@ 'use strict';
 
+/** @category Errors */
 function toNormalizedOptions(args) {
@@ -59,5 +60,3 @@ const firstArg = args[0];
 
-  /**
-   * An array of GraphQL AST Nodes corresponding to this error.
-   */
+  /** An array of GraphQL AST Nodes corresponding to this error. */
 
@@ -76,11 +75,88 @@ /**
 
-  /**
-   * The original error thrown from a field resolver during execution.
-   */
+  /** Original error that caused this GraphQLError, if one exists. */
 
+  /** Extension fields to add to the formatted error. */
+
   /**
-   * Extension fields to add to the formatted error.
+   * Creates a GraphQLError instance.
+   * @param message - Human-readable error message.
+   * @param options - Error metadata such as source locations, response path, original error, and extensions.
+   * This positional-arguments constructor overload is deprecated. Use the
+   * `GraphQLError(message, options)` overload instead.
+   * @example
+   * ```ts
+   * // Create an error from AST nodes and response metadata.
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const document = parse('{ greeting }');
+   * const fieldNode = document.definitions[0].selectionSet.selections[0];
+   * const error = new GraphQLError('Cannot query this field.', {
+   *   nodes: fieldNode,
+   *   path: ['greeting'],
+   *   extensions: { code: 'FORBIDDEN' },
+   * });
+   *
+   * error.message; // => 'Cannot query this field.'
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.extensions; // => { code: 'FORBIDDEN' }
+   * ```
+   * @example
+   * ```ts
+   * // This variant derives locations from source positions and preserves the original error.
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError('Resolver failed.', {
+   *   source,
+   *   positions: [2],
+   *   path: ['greeting'],
+   *   originalError,
+   * });
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * ```
    */
 
   /**
+   * Creates a GraphQLError instance using the legacy positional constructor.
+   * This deprecated overload will be removed in v17. Prefer the
+   * `GraphQLErrorOptions` object overload, which keeps optional error metadata
+   * in a single options bag.
+   * @param message - Human-readable error message.
+   * @param nodes - AST node or nodes associated with this error.
+   * @param source - Source document used to derive error locations.
+   * @param positions - Character offsets in the source document associated with
+   * this error.
+   * @param path - Response path where this error occurred during execution.
+   * @param originalError - Original error that caused this GraphQLError, if one
+   * exists.
+   * @param extensions - Extension fields to include in the formatted error.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError(
+   *   'Resolver failed.',
+   *   undefined,
+   *   source,
+   *   [2],
+   *   ['greeting'],
+   *   originalError,
+   *   { code: 'INTERNAL' },
+   * );
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * error.extensions; // => { code: 'INTERNAL' }
+   * ```
    * @deprecated Please use the `GraphQLErrorOptions` constructor overload instead.
@@ -197,2 +273,6 @@ */
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -202,2 +282,18 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns this error as a human-readable message with source locations.
+   * @returns The formatted error string.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Cannot query field "name".', {
+   *   source: new Source('{ name }'),
+   *   positions: [2],
+   * });
+   *
+   * error.toString(); // => 'Cannot query field "name".\n\nGraphQL request:1:3\n1 | { name }\n  |   ^'
+   * ```
+   */
 
@@ -223,2 +319,17 @@ toString() {
   }
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Resolver failed.', {
+   *   path: ['viewer', 'name'],
+   *   extensions: { code: 'INTERNAL' },
+   * });
+   *
+   * error.toJSON(); // => { message: 'Resolver failed.', path: ['viewer', 'name'], extensions: { code: 'INTERNAL' } }
+   * ```
+   */
 
@@ -251,10 +362,19 @@ toJSON() {
 }
-/**
- * See: https://spec.graphql.org/draft/#sec-Errors
- */
+/** See: https://spec.graphql.org/draft/#sec-Errors */
 
 /**
  * Prints a GraphQLError to a string, representing useful location information
- * about the error's position in the source.
+ * about the error's position in the source. This deprecated helper is retained
+ * for backwards compatibility; call `error.toString()` instead because
+ * printError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { GraphQLError, printError } from 'graphql/error';
  *
+ * const message = printError(new GraphQLError('Example error'));
+ *
+ * message; // => 'Example error'
+ * ```
  * @deprecated Please use `error.toString` instead. Will be removed in v17
@@ -267,4 +387,15 @@ */
  * Given a GraphQLError, format it according to the rules described by the
- * Response Format, Errors section of the GraphQL Specification.
+ * Response Format, Errors section of the GraphQL Specification. This deprecated
+ * helper is retained for backwards compatibility; call `error.toJSON()`
+ * instead because formatError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The JSON-serializable formatted error.
+ * @example
+ * ```ts
+ * import { GraphQLError, formatError } from 'graphql/error';
  *
+ * const formatted = formatError(new GraphQLError('Example error'));
+ *
+ * formatted; // => { message: 'Example error' }
+ * ```
  * @deprecated Please use `error.toJSON` instead. Will be removed in v17
@@ -271,0 +402,0 @@ */

error/GraphQLError.mjs

@@ -0,1 +1,2 @@
+/** @category Errors */
 import { isObjectLike } from '../jsutils/isObjectLike.mjs';
@@ -50,5 +51,3 @@ import { getLocation } from '../language/location.mjs';
 
-  /**
-   * An array of GraphQL AST Nodes corresponding to this error.
-   */
+  /** An array of GraphQL AST Nodes corresponding to this error. */
 
@@ -67,11 +66,88 @@ /**
 
-  /**
-   * The original error thrown from a field resolver during execution.
-   */
+  /** Original error that caused this GraphQLError, if one exists. */
 
+  /** Extension fields to add to the formatted error. */
+
   /**
-   * Extension fields to add to the formatted error.
+   * Creates a GraphQLError instance.
+   * @param message - Human-readable error message.
+   * @param options - Error metadata such as source locations, response path, original error, and extensions.
+   * This positional-arguments constructor overload is deprecated. Use the
+   * `GraphQLError(message, options)` overload instead.
+   * @example
+   * ```ts
+   * // Create an error from AST nodes and response metadata.
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const document = parse('{ greeting }');
+   * const fieldNode = document.definitions[0].selectionSet.selections[0];
+   * const error = new GraphQLError('Cannot query this field.', {
+   *   nodes: fieldNode,
+   *   path: ['greeting'],
+   *   extensions: { code: 'FORBIDDEN' },
+   * });
+   *
+   * error.message; // => 'Cannot query this field.'
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.extensions; // => { code: 'FORBIDDEN' }
+   * ```
+   * @example
+   * ```ts
+   * // This variant derives locations from source positions and preserves the original error.
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError('Resolver failed.', {
+   *   source,
+   *   positions: [2],
+   *   path: ['greeting'],
+   *   originalError,
+   * });
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * ```
    */
 
   /**
+   * Creates a GraphQLError instance using the legacy positional constructor.
+   * This deprecated overload will be removed in v17. Prefer the
+   * `GraphQLErrorOptions` object overload, which keeps optional error metadata
+   * in a single options bag.
+   * @param message - Human-readable error message.
+   * @param nodes - AST node or nodes associated with this error.
+   * @param source - Source document used to derive error locations.
+   * @param positions - Character offsets in the source document associated with
+   * this error.
+   * @param path - Response path where this error occurred during execution.
+   * @param originalError - Original error that caused this GraphQLError, if one
+   * exists.
+   * @param extensions - Extension fields to include in the formatted error.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const source = new Source('{ greeting }');
+   * const originalError = new Error('Database unavailable.');
+   * const error = new GraphQLError(
+   *   'Resolver failed.',
+   *   undefined,
+   *   source,
+   *   [2],
+   *   ['greeting'],
+   *   originalError,
+   *   { code: 'INTERNAL' },
+   * );
+   *
+   * error.locations; // => [{ line: 1, column: 3 }]
+   * error.path; // => ['greeting']
+   * error.originalError; // => originalError
+   * error.extensions; // => { code: 'INTERNAL' }
+   * ```
    * @deprecated Please use the `GraphQLErrorOptions` constructor overload instead.
@@ -186,2 +262,6 @@ */
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -191,2 +271,18 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns this error as a human-readable message with source locations.
+   * @returns The formatted error string.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Cannot query field "name".', {
+   *   source: new Source('{ name }'),
+   *   positions: [2],
+   * });
+   *
+   * error.toString(); // => 'Cannot query field "name".\n\nGraphQL request:1:3\n1 | { name }\n  |   ^'
+   * ```
+   */
 
@@ -210,2 +306,17 @@ toString() {
   }
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { GraphQLError } from 'graphql/error';
+   *
+   * const error = new GraphQLError('Resolver failed.', {
+   *   path: ['viewer', 'name'],
+   *   extensions: { code: 'INTERNAL' },
+   * });
+   *
+   * error.toJSON(); // => { message: 'Resolver failed.', path: ['viewer', 'name'], extensions: { code: 'INTERNAL' } }
+   * ```
+   */
 
@@ -236,10 +347,19 @@ toJSON() {
 }
-/**
- * See: https://spec.graphql.org/draft/#sec-Errors
- */
+/** See: https://spec.graphql.org/draft/#sec-Errors */
 
 /**
  * Prints a GraphQLError to a string, representing useful location information
- * about the error's position in the source.
+ * about the error's position in the source. This deprecated helper is retained
+ * for backwards compatibility; call `error.toString()` instead because
+ * printError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { GraphQLError, printError } from 'graphql/error';
  *
+ * const message = printError(new GraphQLError('Example error'));
+ *
+ * message; // => 'Example error'
+ * ```
  * @deprecated Please use `error.toString` instead. Will be removed in v17
@@ -252,4 +372,15 @@ */
  * Given a GraphQLError, format it according to the rules described by the
- * Response Format, Errors section of the GraphQL Specification.
+ * Response Format, Errors section of the GraphQL Specification. This deprecated
+ * helper is retained for backwards compatibility; call `error.toJSON()`
+ * instead because formatError will be removed in v17.
+ * @param error - The error to format.
+ * @returns The JSON-serializable formatted error.
+ * @example
+ * ```ts
+ * import { GraphQLError, formatError } from 'graphql/error';
  *
+ * const formatted = formatError(new GraphQLError('Example error'));
+ *
+ * formatted; // => { message: 'Example error' }
+ * ```
  * @deprecated Please use `error.toJSON` instead. Will be removed in v17
@@ -256,0 +387,0 @@ */

error/index.d.ts

@@ -0,1 +1,7 @@
+/**
+ * Create, format, and locate GraphQL errors.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { GraphQLError, printError, formatError } from './GraphQLError';
@@ -2,0 +8,0 @@ export type {

error/index.mjs

@@ -0,3 +1,9 @@
+/**
+ * Create, format, and locate GraphQL errors.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { GraphQLError, printError, formatError } from './GraphQLError.mjs';
 export { syntaxError } from './syntaxError.mjs';
 export { locatedError } from './locatedError.mjs';

error/locatedError.d.ts

@@ -0,1 +1,2 @@
+/** @category Errors */
 import type { Maybe } from '../jsutils/Maybe';
@@ -8,2 +9,21 @@ import type { ASTNode } from '../language/ast';
  * document responsible for the original Error.
+ * @param rawOriginalError - The original error value to wrap.
+ * @param nodes - The AST nodes associated with the error.
+ * @param path - The response path associated with the error.
+ * @returns The GraphQL error.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { locatedError } from 'graphql/error';
+ *
+ * const document = parse('{ viewer { name } }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const error = locatedError(new Error('Resolver failed'), fieldNode, [
+ *   'viewer',
+ * ]);
+ *
+ * error.message; // => 'Resolver failed'
+ * error.locations; // => [{ line: 1, column: 3 }]
+ * error.path; // => ['viewer']
+ * ```
  */
@@ -10,0 +30,0 @@ export declare function locatedError(

error/locatedError.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Errors */
+
 /**
@@ -17,2 +19,21 @@ * Given an arbitrary value, presumably thrown while attempting to execute a
  * document responsible for the original Error.
+ * @param rawOriginalError - The original error value to wrap.
+ * @param nodes - The AST nodes associated with the error.
+ * @param path - The response path associated with the error.
+ * @returns The GraphQL error.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { locatedError } from 'graphql/error';
+ *
+ * const document = parse('{ viewer { name } }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const error = locatedError(new Error('Resolver failed'), fieldNode, [
+ *   'viewer',
+ * ]);
+ *
+ * error.message; // => 'Resolver failed'
+ * error.locations; // => [{ line: 1, column: 3 }]
+ * error.path; // => ['viewer']
+ * ```
  */
@@ -19,0 +40,0 @@ function locatedError(rawOriginalError, nodes, path) {

error/locatedError.mjs

@@ -0,1 +1,2 @@
+/** @category Errors */
 import { toError } from '../jsutils/toError.mjs';
@@ -7,2 +8,21 @@ import { GraphQLError } from './GraphQLError.mjs';
  * document responsible for the original Error.
+ * @param rawOriginalError - The original error value to wrap.
+ * @param nodes - The AST nodes associated with the error.
+ * @param path - The response path associated with the error.
+ * @returns The GraphQL error.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { locatedError } from 'graphql/error';
+ *
+ * const document = parse('{ viewer { name } }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ * const error = locatedError(new Error('Resolver failed'), fieldNode, [
+ *   'viewer',
+ * ]);
+ *
+ * error.message; // => 'Resolver failed'
+ * error.locations; // => [{ line: 1, column: 3 }]
+ * error.path; // => ['viewer']
+ * ```
  */
@@ -9,0 +29,0 @@

error/syntaxError.d.ts

@@ -0,1 +1,2 @@
+/** @category Errors */
 import type { Source } from '../language/source';
@@ -6,2 +7,16 @@ import { GraphQLError } from './GraphQLError';
  * descriptive information about the syntax error's position in the source.
+ * @param source - The GraphQL source containing the syntax error.
+ * @param position - Character offset where the syntax error was encountered.
+ * @param description - Human-readable description of the syntax error.
+ * @returns A GraphQLError located at the syntax error position.
+ * @example
+ * ```ts
+ * import { Source } from 'graphql/language';
+ * import { syntaxError } from 'graphql/error';
+ *
+ * const error = syntaxError(new Source('query {'), 7, 'Expected Name');
+ *
+ * error.message; // => 'Syntax Error: Expected Name'
+ * error.locations; // => [{ line: 1, column: 8 }]
+ * ```
  */
@@ -8,0 +23,0 @@ export declare function syntaxError(

error/syntaxError.js

@@ -10,5 +10,21 @@ 'use strict';
 
+/** @category Errors */
+
 /**
  * Produces a GraphQLError representing a syntax error, containing useful
  * descriptive information about the syntax error's position in the source.
+ * @param source - The GraphQL source containing the syntax error.
+ * @param position - Character offset where the syntax error was encountered.
+ * @param description - Human-readable description of the syntax error.
+ * @returns A GraphQLError located at the syntax error position.
+ * @example
+ * ```ts
+ * import { Source } from 'graphql/language';
+ * import { syntaxError } from 'graphql/error';
+ *
+ * const error = syntaxError(new Source('query {'), 7, 'Expected Name');
+ *
+ * error.message; // => 'Syntax Error: Expected Name'
+ * error.locations; // => [{ line: 1, column: 8 }]
+ * ```
  */
@@ -15,0 +31,0 @@ function syntaxError(source, position, description) {

error/syntaxError.mjs

@@ -0,1 +1,2 @@
+/** @category Errors */
 import { GraphQLError } from './GraphQLError.mjs';
@@ -5,2 +6,16 @@ /**
  * descriptive information about the syntax error's position in the source.
+ * @param source - The GraphQL source containing the syntax error.
+ * @param position - Character offset where the syntax error was encountered.
+ * @param description - Human-readable description of the syntax error.
+ * @returns A GraphQLError located at the syntax error position.
+ * @example
+ * ```ts
+ * import { Source } from 'graphql/language';
+ * import { syntaxError } from 'graphql/error';
+ *
+ * const error = syntaxError(new Source('query {'), 7, 'Expected Name');
+ *
+ * error.message; // => 'Syntax Error: Expected Name'
+ * error.locations; // => [{ line: 1, column: 8 }]
+ * ```
  */
@@ -7,0 +22,0 @@

execution/collectFields.js

@@ -170,2 +170,4 @@ 'use strict';
  * directives, where `@skip` has higher precedence than `@include`.
+ *
+ * @internal
  */
@@ -200,2 +202,4 @@
  * Determines if a fragment is applicable to the given type.
+ *
+ * @internal
  */
@@ -227,2 +231,4 @@
  * Implements the logic to compute the key of a given field's entry
+ *
+ * @internal
  */
@@ -229,0 +235,0 @@

execution/collectFields.mjs

@@ -161,2 +161,4 @@ import { Kind } from '../language/kinds.mjs';
  * directives, where `@skip` has higher precedence than `@include`.
+ *
+ * @internal
  */
@@ -187,2 +189,4 @@
  * Determines if a fragment is applicable to the given type.
+ *
+ * @internal
  */
@@ -211,2 +215,4 @@
  * Implements the logic to compute the key of a given field's entry
+ *
+ * @internal
  */
@@ -213,0 +219,0 @@

execution/execute.d.ts

@@ -0,1 +1,2 @@
+/** @category Execution */
 import type { Maybe } from '../jsutils/Maybe';
@@ -45,2 +46,4 @@ import type { ObjMap } from '../jsutils/ObjMap';
  * and the fragments defined in the query document
+ *
+ * @internal
  */
@@ -61,5 +64,2 @@ export interface ExecutionContext {
 }
-/**
- * @internal
- */
 declare class CollectedErrors {
@@ -74,7 +74,5 @@ private _errorPositions;
 /**
- * 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.
+ * Represents the response produced by executing a GraphQL operation.
+ * @typeParam TData - Shape of the execution data payload.
+ * @typeParam TExtensions - Shape of the extensions payload.
  */
@@ -85,6 +83,14 @@ export interface ExecutionResult<
 > {
+  /** Errors raised while parsing, validating, or executing the operation. */
   errors?: ReadonlyArray<GraphQLError>;
+  /** Data returned by execution, or null when execution could not produce data. */
   data?: TData | null;
+  /** Extension fields to include in the formatted result. */
   extensions?: TExtensions;
 }
+/**
+ * A JSON-serializable GraphQL execution result.
+ * @typeParam TData - Shape of the formatted data payload.
+ * @typeParam TExtensions - Shape of the formatted extensions payload.
+ */
 export interface FormattedExecutionResult<
@@ -94,17 +100,30 @@ TData = ObjMap<unknown>,
 > {
+  /** Errors raised while parsing, validating, or executing the operation. */
   errors?: ReadonlyArray<GraphQLFormattedError>;
+  /** Data returned by execution, or null when execution could not produce data. */
   data?: TData | null;
+  /** Extension fields to include in the formatted result. */
   extensions?: TExtensions;
 }
+/** Arguments accepted by execute and executeSync. */
 export interface ExecutionArgs {
+  /** The schema used for validation or execution. */
   schema: GraphQLSchema;
+  /** The parsed GraphQL document to execute. */
   document: DocumentNode;
+  /** Initial root value passed to the operation. */
   rootValue?: unknown;
+  /** Application context value passed to every resolver. */
   contextValue?: unknown;
+  /** Runtime variable values keyed by variable name. */
   variableValues?: Maybe<{
     readonly [variable: string]: unknown;
   }>;
+  /** Name of the operation to execute when the document contains multiple operations. */
   operationName?: Maybe<string>;
+  /** Resolver used when a field does not define its own resolver. */
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  /** Resolver used when an abstract type does not define its own resolver. */
   typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
+  /** Resolver used for the root subscription field. */
   subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
@@ -126,2 +145,135 @@ /** Additional execution options. */
  * a GraphQLError will be thrown immediately explaining the invalid input.
+ *
+ * Field errors are collected into the response instead of rejecting the
+ * returned promise. Only the field that produced the error and its descendants
+ * are omitted; sibling fields continue to execute. Errors from fields of
+ * non-null type may propagate to the nearest nullable parent, which can be the
+ * entire response data.
+ * @param args - The arguments used to perform the operation.
+ * @returns A completed execution result, or a promise resolving to one when execution is asynchronous.
+ * @example
+ * ```ts
+ * // Execute an asynchronous operation with variables.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query ($name: String!) { greeting(name: $name) }'),
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query Viewer { viewer { __typename name } }'),
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   operationName: 'Viewer',
+ *   fieldResolver: (source, _args, contextValue, info) => {
+ *     contextValue.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows how resolver errors become field errors in the result.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     broken: String
+ *   }
+ * `);
+ * const document = parse('{ broken }');
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     broken: () => {
+ *       throw new Error('Resolver failed.');
+ *     },
+ *   },
+ * });
+ *
+ * result.data.broken; // => null
+ * result.errors[0].message; // => 'Resolver failed.'
+ * ```
+ * @example
+ * ```ts
+ * // This variant limits how many variable coercion errors are reported.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   variableValues: {
+ *     first: { stars: 'bad' },
+ *     second: { stars: 'also bad' },
+ *   },
+ *   options: { maxCoercionErrors: 1 },
+ * });
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
@@ -135,2 +287,49 @@ export declare function execute(
  * that all field resolvers are also synchronous.
+ * @param args - The arguments used to perform the operation.
+ * @returns Completed execution output for a synchronous operation.
+ * @example
+ * ```ts
+ * // Execute an operation synchronously when all resolvers are synchronous.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ greeting }');
+ *
+ * const result = executeSync({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     greeting: 'Hello',
+ *   },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows executeSync throwing when a resolver returns a promise.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * executeSync({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: {
+ *     greeting: async () => 'Hello',
+ *   },
+ * }); // throws an error
+ * ```
  */
@@ -140,3 +339,5 @@ export declare function executeSync(args: ExecutionArgs): ExecutionResult;
  * Essential assertions before executing to provide developer feedback for
- * improper use of the GraphQL library.
+ * improper use of the GraphQL library. This deprecated internal helper will be
+ * removed in v17; call `assertValidSchema()` and rely on TypeScript checks
+ * instead.
  *
@@ -164,5 +365,3 @@ * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
 ): ReadonlyArray<GraphQLError> | ExecutionContext;
-/**
- * @internal
- */
+/** @internal */
 export declare function buildResolveInfo(
@@ -169,0 +368,0 @@ exeContext: ExecutionContext,

execution/execute.js

@@ -52,2 +52,4 @@ 'use strict';
 
+/** @category Execution */
+
 /**
@@ -57,2 +59,4 @@ * A memoized collection of relevant subfields with regard to the return
  * saves overhead when resolving lists of values.
+ *
+ * @internal
  */
@@ -94,7 +98,6 @@ const collectSubfields = (0, _memoize.memoize3)(
  * and the fragments defined in the query document
+ *
+ * @internal
  */
 
-/**
- * @internal
- */
 class CollectedErrors {
@@ -139,7 +142,5 @@ constructor() {
 /**
- * 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.
+ * Represents the response produced by executing a GraphQL operation.
+ * @typeParam TData - Shape of the execution data payload.
+ * @typeParam TExtensions - Shape of the extensions payload.
  */
@@ -156,2 +157,135 @@
  * a GraphQLError will be thrown immediately explaining the invalid input.
+ *
+ * Field errors are collected into the response instead of rejecting the
+ * returned promise. Only the field that produced the error and its descendants
+ * are omitted; sibling fields continue to execute. Errors from fields of
+ * non-null type may propagate to the nearest nullable parent, which can be the
+ * entire response data.
+ * @param args - The arguments used to perform the operation.
+ * @returns A completed execution result, or a promise resolving to one when execution is asynchronous.
+ * @example
+ * ```ts
+ * // Execute an asynchronous operation with variables.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query ($name: String!) { greeting(name: $name) }'),
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query Viewer { viewer { __typename name } }'),
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   operationName: 'Viewer',
+ *   fieldResolver: (source, _args, contextValue, info) => {
+ *     contextValue.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows how resolver errors become field errors in the result.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     broken: String
+ *   }
+ * `);
+ * const document = parse('{ broken }');
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     broken: () => {
+ *       throw new Error('Resolver failed.');
+ *     },
+ *   },
+ * });
+ *
+ * result.data.broken; // => null
+ * result.errors[0].message; // => 'Resolver failed.'
+ * ```
+ * @example
+ * ```ts
+ * // This variant limits how many variable coercion errors are reported.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   variableValues: {
+ *     first: { stars: 'bad' },
+ *     second: { stars: 'also bad' },
+ *   },
+ *   options: { maxCoercionErrors: 1 },
+ * });
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
@@ -176,13 +310,3 @@ function execute(args) {
     };
-  } // Return a Promise that will eventually resolve to the data described by
-  // The "Response" section of the GraphQL specification.
-  //
-  // If errors are encountered while executing a GraphQL field, only that
-  // field and its descendants will be omitted, and sibling fields will still
-  // be executed. An execution which encounters errors will still result in a
-  // resolved Promise.
-  //
-  // Errors from sub-fields of a NonNull type may propagate to the top level,
-  // at which point we still log the error and null the parent field, which
-  // in this case is the entire response.
+  }
 
@@ -213,2 +337,49 @@ try {
  * that all field resolvers are also synchronous.
+ * @param args - The arguments used to perform the operation.
+ * @returns Completed execution output for a synchronous operation.
+ * @example
+ * ```ts
+ * // Execute an operation synchronously when all resolvers are synchronous.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ greeting }');
+ *
+ * const result = executeSync({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     greeting: 'Hello',
+ *   },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows executeSync throwing when a resolver returns a promise.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * executeSync({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: {
+ *     greeting: async () => 'Hello',
+ *   },
+ * }); // throws an error
+ * ```
  */
@@ -228,2 +399,4 @@
  * response defined by the "Response" section of the GraphQL specification.
+ *
+ * @internal
  */
@@ -243,3 +416,5 @@
  * Essential assertions before executing to provide developer feedback for
- * improper use of the GraphQL library.
+ * improper use of the GraphQL library. This deprecated internal helper will be
+ * removed in v17; call `assertValidSchema()` and rely on TypeScript checks
+ * instead.
  *
@@ -386,2 +561,4 @@ * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
  * Implements the "Executing operations" section of the spec.
+ *
+ * @internal
  */
@@ -432,2 +609,4 @@
  * for fields that must be executed serially.
+ *
+ * @internal
  */
@@ -474,2 +653,4 @@
  * for fields that may be executed in parallel.
+ *
+ * @internal
  */
@@ -524,2 +705,4 @@
  * serialize scalars, or execute the sub-selection-set for objects.
+ *
+ * @internal
  */
@@ -604,5 +787,3 @@
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -657,2 +838,4 @@ function buildResolveInfo(exeContext, fieldDef, fieldNodes, parentType, path) {
  * value by executing all sub-selections.
+ *
+ * @internal
  */
@@ -741,2 +924,4 @@
  * inner type
+ *
+ * @internal
  */
@@ -820,2 +1005,4 @@
  * null if serialization is not possible.
+ *
+ * @internal
  */
@@ -841,2 +1028,4 @@
  * of that value, then complete the value for that type.
+ *
+ * @internal
  */
@@ -962,2 +1151,4 @@
  * Complete an Object value by executing all sub-selections.
+ *
+ * @internal
  */
@@ -964,0 +1155,0 @@

execution/execute.mjs

@@ -0,1 +1,2 @@
+/** @category Execution */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -37,2 +38,4 @@ import { inspect } from '../jsutils/inspect.mjs';
  * saves overhead when resolving lists of values.
+ *
+ * @internal
  */
@@ -74,7 +77,6 @@
  * and the fragments defined in the query document
+ *
+ * @internal
  */
 
-/**
- * @internal
- */
 class CollectedErrors {
@@ -119,7 +121,5 @@ constructor() {
 /**
- * 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.
+ * Represents the response produced by executing a GraphQL operation.
+ * @typeParam TData - Shape of the execution data payload.
+ * @typeParam TExtensions - Shape of the extensions payload.
  */
@@ -136,2 +136,135 @@
  * a GraphQLError will be thrown immediately explaining the invalid input.
+ *
+ * Field errors are collected into the response instead of rejecting the
+ * returned promise. Only the field that produced the error and its descendants
+ * are omitted; sibling fields continue to execute. Errors from fields of
+ * non-null type may propagate to the nearest nullable parent, which can be the
+ * entire response data.
+ * @param args - The arguments used to perform the operation.
+ * @returns A completed execution result, or a promise resolving to one when execution is asynchronous.
+ * @example
+ * ```ts
+ * // Execute an asynchronous operation with variables.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query ($name: String!) { greeting(name: $name) }'),
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document: parse('query Viewer { viewer { __typename name } }'),
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   operationName: 'Viewer',
+ *   fieldResolver: (source, _args, contextValue, info) => {
+ *     contextValue.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows how resolver errors become field errors in the result.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     broken: String
+ *   }
+ * `);
+ * const document = parse('{ broken }');
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     broken: () => {
+ *       throw new Error('Resolver failed.');
+ *     },
+ *   },
+ * });
+ *
+ * result.data.broken; // => null
+ * result.errors[0].message; // => 'Resolver failed.'
+ * ```
+ * @example
+ * ```ts
+ * // This variant limits how many variable coercion errors are reported.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { execute } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ *
+ * const result = await execute({
+ *   schema,
+ *   document,
+ *   variableValues: {
+ *     first: { stars: 'bad' },
+ *     second: { stars: 'also bad' },
+ *   },
+ *   options: { maxCoercionErrors: 1 },
+ * });
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
@@ -156,13 +289,3 @@ export function execute(args) {
     };
-  } // Return a Promise that will eventually resolve to the data described by
-  // The "Response" section of the GraphQL specification.
-  //
-  // If errors are encountered while executing a GraphQL field, only that
-  // field and its descendants will be omitted, and sibling fields will still
-  // be executed. An execution which encounters errors will still result in a
-  // resolved Promise.
-  //
-  // Errors from sub-fields of a NonNull type may propagate to the top level,
-  // at which point we still log the error and null the parent field, which
-  // in this case is the entire response.
+  }
 
@@ -193,2 +316,49 @@ try {
  * that all field resolvers are also synchronous.
+ * @param args - The arguments used to perform the operation.
+ * @returns Completed execution output for a synchronous operation.
+ * @example
+ * ```ts
+ * // Execute an operation synchronously when all resolvers are synchronous.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ greeting }');
+ *
+ * const result = executeSync({
+ *   schema,
+ *   document,
+ *   rootValue: {
+ *     greeting: 'Hello',
+ *   },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows executeSync throwing when a resolver returns a promise.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { executeSync } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * executeSync({
+ *   schema,
+ *   document: parse('{ greeting }'),
+ *   rootValue: {
+ *     greeting: async () => 'Hello',
+ *   },
+ * }); // throws an error
+ * ```
  */
@@ -208,2 +378,4 @@
  * response defined by the "Response" section of the GraphQL specification.
+ *
+ * @internal
  */
@@ -223,3 +395,5 @@
  * Essential assertions before executing to provide developer feedback for
- * improper use of the GraphQL library.
+ * improper use of the GraphQL library. This deprecated internal helper will be
+ * removed in v17; call `assertValidSchema()` and rely on TypeScript checks
+ * instead.
  *
@@ -366,2 +540,4 @@ * @deprecated will be removed in v17 in favor of assertValidSchema() and TS checks
  * Implements the "Executing operations" section of the spec.
+ *
+ * @internal
  */
@@ -412,2 +588,4 @@
  * for fields that must be executed serially.
+ *
+ * @internal
  */
@@ -454,2 +632,4 @@
  * for fields that may be executed in parallel.
+ *
+ * @internal
  */
@@ -504,2 +684,4 @@
  * serialize scalars, or execute the sub-selection-set for objects.
+ *
+ * @internal
  */
@@ -576,5 +758,3 @@
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -635,2 +815,4 @@ export function buildResolveInfo(
  * value by executing all sub-selections.
+ *
+ * @internal
  */
@@ -718,2 +900,4 @@
  * inner type
+ *
+ * @internal
  */
@@ -793,2 +977,4 @@
  * null if serialization is not possible.
+ *
+ * @internal
  */
@@ -811,2 +997,4 @@
  * of that value, then complete the value for that type.
+ *
+ * @internal
  */
@@ -931,2 +1119,4 @@
  * Complete an Object value by executing all sub-selections.
+ *
+ * @internal
  */
@@ -933,0 +1123,0 @@

execution/index.d.ts

@@ -0,1 +1,7 @@
+/**
+ * Execute GraphQL operations and produce GraphQL execution results.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { pathToArray as responsePathAsArray } from '../jsutils/Path';
@@ -2,0 +8,0 @@ export {

execution/index.mjs

@@ -0,1 +1,7 @@
+/**
+ * Execute GraphQL operations and produce GraphQL execution results.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { pathToArray as responsePathAsArray } from '../jsutils/Path.mjs';
@@ -2,0 +8,0 @@ export {

execution/mapAsyncIterator.d.ts

@@ -5,2 +5,4 @@ import type { PromiseOrValue } from '../jsutils/PromiseOrValue';
  * which produces values mapped via calling the callback function.
+ *
+ * @internal
  */
@@ -7,0 +9,0 @@ export declare function mapAsyncIterator<T, U, R = undefined>(

execution/mapAsyncIterator.js

@@ -11,2 +11,4 @@ 'use strict';
  * which produces values mapped via calling the callback function.
+ *
+ * @internal
  */
@@ -13,0 +15,0 @@ function mapAsyncIterator(iterable, callback) {

execution/mapAsyncIterator.mjs

 /**
  * Given an AsyncIterable and a callback function, return an AsyncIterator
  * which produces values mapped via calling the callback function.
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export function mapAsyncIterator(iterable, callback) {

execution/subscribe.d.ts

@@ -0,1 +1,2 @@
+/** @category Subscriptions */
 import type { Maybe } from '../jsutils/Maybe';
@@ -9,3 +10,3 @@ import type { DocumentNode } from '../language/ast';
  *
- * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * Returns a Promise that resolves to either an AsyncIterator (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
@@ -26,3 +27,118 @@ * other arguments to this function are invalid, or if the resolved event stream
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * Each payload yielded by the source event stream is executed with the payload
+ * as the root value. This maps the subscription source stream into the response
+ * stream described by the GraphQL specification.
+ *
+ * Accepts an object with named arguments.
+ * @param args - The arguments used to perform the operation.
+ * @returns A source stream mapped to execution results, or an execution result
+ * containing subscription errors.
+ * @example
+ * ```ts
+ * // Use a same-named rootValue function to provide the source event stream.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies events through a custom subscribeFieldResolver.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* defaultGreetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * async function* frenchGreetings() {
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting(locale: String): String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse(
+ *     'subscription Greeting($locale: String) { greeting(locale: $locale) }',
+ *   ),
+ *   rootValue: {
+ *     greeting: (args, contextValue) => {
+ *       const locale = args.locale ?? contextValue.defaultLocale;
+ *       return locale === 'fr' ? frenchGreetings() : defaultGreetings();
+ *     },
+ *   },
+ *   contextValue: { defaultLocale: 'fr' },
+ *   variableValues: { locale: 'fr' },
+ *   operationName: 'Greeting',
+ *   subscribeFieldResolver: (rootValue, args, contextValue, info) => {
+ *     args.locale; // => 'fr'
+ *     return rootValue[info.fieldName](args, contextValue);
+ *   },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Bonjour' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows the error result when the schema has no subscription root.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('errors' in result);
+ *
+ * result.errors[0].message; // => 'Schema is not configured to execute subscription operation.'
+ * ```
  */
@@ -36,3 +152,3 @@ export declare function subscribe(
  *
- * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * Returns a Promise that resolves to either an AsyncIterable (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
@@ -46,3 +162,3 @@ * other arguments to this function are invalid, or if the resolved event stream
  *
- * If the the source stream could not be created due to faulty subscription
+ * If the source stream could not be created due to faulty subscription
  * resolver logic or underlying systems, the promise will resolve to a single
@@ -61,2 +177,32 @@ * ExecutionResult containing `errors` and no `data`.
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
+ * @param args - The arguments used to perform the operation.
+ * @returns The source event stream, or an execution result containing subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const stream = await createSourceEventStream({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
  */
@@ -66,3 +212,47 @@ export declare function createSourceEventStream(
 ): Promise<AsyncIterable<unknown> | ExecutionResult>;
-/** @deprecated will be removed in next major version in favor of named arguments */
+/**
+ * Creates the source event stream for a subscription operation using the legacy
+ * positional argument overload. This deprecated overload will be removed in the
+ * next major version; use the args object overload instead.
+ * @param schema - GraphQL schema to use.
+ * @param document - The parsed GraphQL document containing the subscription
+ * operation.
+ * @param rootValue - Initial root value passed to the subscription resolver.
+ * @param contextValue - Application context value passed to resolvers.
+ * @param variableValues - Runtime variable values keyed by variable name.
+ * @param operationName - Name of the subscription operation to execute when
+ * the document contains multiple operations.
+ * @param subscribeFieldResolver - Resolver used for the root subscription
+ * field.
+ * @returns The source event stream, or an execution result containing
+ * subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('subscription { greeting }');
+ *
+ * const stream = await createSourceEventStream(schema, document, {
+ *   greeting: () => greetings(),
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
+ * @deprecated Will be removed in next major version in favor of named arguments.
+ */
 export declare function createSourceEventStream(
@@ -69,0 +259,0 @@ schema: GraphQLSchema,

execution/subscribe.js

@@ -29,6 +29,8 @@ 'use strict';
 
+/** @category Subscriptions */
+
 /**
  * Implements the "Subscribe" algorithm described in the GraphQL specification.
  *
- * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * Returns a Promise that resolves to either an AsyncIterator (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
@@ -49,3 +51,118 @@ * other arguments to this function are invalid, or if the resolved event stream
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * Each payload yielded by the source event stream is executed with the payload
+ * as the root value. This maps the subscription source stream into the response
+ * stream described by the GraphQL specification.
+ *
+ * Accepts an object with named arguments.
+ * @param args - The arguments used to perform the operation.
+ * @returns A source stream mapped to execution results, or an execution result
+ * containing subscription errors.
+ * @example
+ * ```ts
+ * // Use a same-named rootValue function to provide the source event stream.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies events through a custom subscribeFieldResolver.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* defaultGreetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * async function* frenchGreetings() {
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting(locale: String): String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse(
+ *     'subscription Greeting($locale: String) { greeting(locale: $locale) }',
+ *   ),
+ *   rootValue: {
+ *     greeting: (args, contextValue) => {
+ *       const locale = args.locale ?? contextValue.defaultLocale;
+ *       return locale === 'fr' ? frenchGreetings() : defaultGreetings();
+ *     },
+ *   },
+ *   contextValue: { defaultLocale: 'fr' },
+ *   variableValues: { locale: 'fr' },
+ *   operationName: 'Greeting',
+ *   subscribeFieldResolver: (rootValue, args, contextValue, info) => {
+ *     args.locale; // => 'fr'
+ *     return rootValue[info.fieldName](args, contextValue);
+ *   },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Bonjour' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows the error result when the schema has no subscription root.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('errors' in result);
+ *
+ * result.errors[0].message; // => 'Schema is not configured to execute subscription operation.'
+ * ```
  */
@@ -63,11 +180,6 @@ async function subscribe(args) {
     return resultOrStream;
-  } // For each payload yielded from a subscription, map it over the normal
-  // GraphQL `execute` function, with `payload` as the rootValue.
-  // This implements the "MapSourceToResponseEvent" algorithm described in
-  // the GraphQL specification. The `execute` function provides the
-  // "ExecuteSubscriptionEvent" algorithm, as it is nearly identical to the
-  // "ExecuteQuery" algorithm, for which `execute` is also used.
+  }
 
   const mapSourceToResponse = (payload) =>
-    (0, _execute.execute)({ ...args, rootValue: payload }); // Map every source value to a ExecutionResult value as described above.
+    (0, _execute.execute)({ ...args, rootValue: payload });
 
@@ -102,3 +214,3 @@ return (0, _mapAsyncIterator.mapAsyncIterator)(
  *
- * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * Returns a Promise that resolves to either an AsyncIterable (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
@@ -112,3 +224,3 @@ * other arguments to this function are invalid, or if the resolved event stream
  *
- * If the the source stream could not be created due to faulty subscription
+ * If the source stream could not be created due to faulty subscription
  * resolver logic or underlying systems, the promise will resolve to a single
@@ -127,4 +239,35 @@ * ExecutionResult containing `errors` and no `data`.
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
+ * @param args - The arguments used to perform the operation.
+ * @returns The source event stream, or an execution result containing subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const stream = await createSourceEventStream({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
  */
 
+/** @internal */
 async function createSourceEventStream(...rawArgs) {
@@ -131,0 +274,0 @@ const args = toNormalizedArgs(rawArgs);

execution/subscribe.mjs

@@ -0,1 +1,2 @@
+/** @category Subscriptions */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -21,3 +22,3 @@ import { inspect } from '../jsutils/inspect.mjs';
  *
- * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * Returns a Promise that resolves to either an AsyncIterator (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
@@ -38,3 +39,118 @@ * other arguments to this function are invalid, or if the resolved event stream
  *
- * Accepts either an object with named arguments, or individual arguments.
+ * Each payload yielded by the source event stream is executed with the payload
+ * as the root value. This maps the subscription source stream into the response
+ * stream described by the GraphQL specification.
+ *
+ * Accepts an object with named arguments.
+ * @param args - The arguments used to perform the operation.
+ * @returns A source stream mapped to execution results, or an execution result
+ * containing subscription errors.
+ * @example
+ * ```ts
+ * // Use a same-named rootValue function to provide the source event stream.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies events through a custom subscribeFieldResolver.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * async function* defaultGreetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * async function* frenchGreetings() {
+ *   yield { greeting: 'Bonjour' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting(locale: String): String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse(
+ *     'subscription Greeting($locale: String) { greeting(locale: $locale) }',
+ *   ),
+ *   rootValue: {
+ *     greeting: (args, contextValue) => {
+ *       const locale = args.locale ?? contextValue.defaultLocale;
+ *       return locale === 'fr' ? frenchGreetings() : defaultGreetings();
+ *     },
+ *   },
+ *   contextValue: { defaultLocale: 'fr' },
+ *   variableValues: { locale: 'fr' },
+ *   operationName: 'Greeting',
+ *   subscribeFieldResolver: (rootValue, args, contextValue, info) => {
+ *     args.locale; // => 'fr'
+ *     return rootValue[info.fieldName](args, contextValue);
+ *   },
+ * });
+ *
+ * assert('next' in result);
+ *
+ * const firstPayload = await result.next();
+ * firstPayload.value; // => { data: { greeting: 'Bonjour' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant shows the error result when the schema has no subscription root.
+ * import assert from 'node:assert';
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { subscribe } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ * `);
+ *
+ * const result = await subscribe({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ * });
+ *
+ * assert('errors' in result);
+ *
+ * result.errors[0].message; // => 'Schema is not configured to execute subscription operation.'
+ * ```
  */
@@ -53,11 +169,6 @@
     return resultOrStream;
-  } // For each payload yielded from a subscription, map it over the normal
-  // GraphQL `execute` function, with `payload` as the rootValue.
-  // This implements the "MapSourceToResponseEvent" algorithm described in
-  // the GraphQL specification. The `execute` function provides the
-  // "ExecuteSubscriptionEvent" algorithm, as it is nearly identical to the
-  // "ExecuteQuery" algorithm, for which `execute` is also used.
+  }
 
   const mapSourceToResponse = (payload) =>
-    execute({ ...args, rootValue: payload }); // Map every source value to a ExecutionResult value as described above.
+    execute({ ...args, rootValue: payload });
 
@@ -89,3 +200,3 @@ return mapAsyncIterator(resultOrStream, mapSourceToResponse);
  *
- * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * Returns a Promise that resolves to either an AsyncIterable (if successful)
  * or an ExecutionResult (error). The promise will be rejected if the schema or
@@ -99,3 +210,3 @@ * other arguments to this function are invalid, or if the resolved event stream
  *
- * If the the source stream could not be created due to faulty subscription
+ * If the source stream could not be created due to faulty subscription
  * resolver logic or underlying systems, the promise will resolve to a single
@@ -114,4 +225,35 @@ * ExecutionResult containing `errors` and no `data`.
  * "Supporting Subscriptions at Scale" information in the GraphQL specification.
+ * @param args - The arguments used to perform the operation.
+ * @returns The source event stream, or an execution result containing subscription errors.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { createSourceEventStream } from 'graphql/execution';
+ *
+ * async function* greetings() {
+ *   yield { greeting: 'Hello' };
+ * }
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     noop: String
+ *   }
+ *
+ *   type Subscription {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const stream = await createSourceEventStream({
+ *   schema,
+ *   document: parse('subscription { greeting }'),
+ *   rootValue: { greeting: () => greetings() },
+ * });
+ *
+ * Symbol.asyncIterator in stream; // => true
+ * ```
  */
 
+/** @internal */
 export async function createSourceEventStream(...rawArgs) {
@@ -118,0 +260,0 @@ const args = toNormalizedArgs(rawArgs);

execution/values.d.ts

@@ -0,1 +1,2 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
@@ -24,9 +25,86 @@ import type { ObjMap } from '../jsutils/ObjMap';
 /**
+ * Options used when coercing variable values before execution.
+ * @internal
+ */
+export interface GetVariableValuesOptions {
+  /**
+   * Maximum number of variable coercion errors before coercion stops.
+   * @internal
+   */
+  maxErrors?: number;
+}
+/**
  * Prepares an object map of variableValues of the correct type based on the
  * provided variable definitions and arbitrary input. If the input cannot be
- * parsed to match the variable definitions, a GraphQLError will be thrown.
+ * parsed to match the variable definitions, GraphQLError values are returned.
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param schema - GraphQL schema to use.
+ * @param varDefNodes - The variable definition AST nodes to coerce.
+ * @param inputs - The runtime variable values keyed by variable name.
+ * @param options - Optional variable coercion options, including error limits.
+ * @returns Coerced variable values, or request errors.
+ * @example
+ * ```ts
+ * // Coerce provided variables and apply operation defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($stars: Int!, $limit: Int = 10) {
+ *     reviews(stars: $stars, limit: $limit)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { stars: '5' },
+ * );
+ *
+ * result; // => { coerced: { stars: 5, limit: 10 } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses maxErrors to cap reported coercion errors.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { first: { stars: 'bad' }, second: { stars: 'also bad' } },
+ *   { maxErrors: 1 },
+ * );
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
@@ -39,5 +117,3 @@ export declare function getVariableValues(
   },
-  options?: {
-    maxErrors?: number;
-  },
+  options?: GetVariableValuesOptions,
 ): CoercedVariableValues;
@@ -48,5 +124,46 @@ /**
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param def - The field or directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced argument values keyed by argument name.
+ * @example
+ * ```ts
+ * // Read literal argument values and defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('{ reviews(stars: 5) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode); // => { stars: 5, limit: 10 }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves argument values from operation variables.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('query ($stars: Int!) { reviews(stars: $stars) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode, { stars: 5 }); // => { stars: 5 }
+ * getArgumentValues(fieldDef, fieldNode, {}); // throws an error
+ * ```
  */
@@ -61,2 +178,13 @@ export declare function getArgumentValues(
 /**
+ * AST node shape accepted by getDirectiveValues.
+ * @internal
+ */
+export interface DirectiveValuesNode {
+  /**
+   * Directives attached to the AST node.
+   * @internal
+   */
+  readonly directives?: ReadonlyArray<DirectiveNode>;
+}
+/**
  * Prepares an object map of argument values given a directive definition
@@ -68,11 +196,40 @@ * and a AST node which may contain directives. Optionally also accepts a map
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param directiveDef - The directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced directive argument values keyed by argument name.
+ * @example
+ * ```ts
+ * // Read literal directive arguments from a node.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLSkipDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('{ name @skip(if: true) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLSkipDirective, fieldNode); // => { if: true }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves directive arguments from variables and handles absent directives.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLIncludeDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('query ($includeName: Boolean!) { name @include(if: $includeName) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLIncludeDirective, fieldNode, {
+ *   includeName: false,
+ * }); // => { if: false }
+ * getDirectiveValues(GraphQLIncludeDirective, { directives: [] }); // => undefined
+ * ```
  */
 export declare function getDirectiveValues(
   directiveDef: GraphQLDirective,
-  node: {
-    readonly directives?: ReadonlyArray<DirectiveNode>;
-  },
+  node: DirectiveValuesNode,
   variableValues?: Maybe<ObjMap<unknown>>,
@@ -79,0 +236,0 @@ ):

execution/values.js

@@ -30,10 +30,78 @@ 'use strict';
 
+/** @category Values */
+
 /**
  * Prepares an object map of variableValues of the correct type based on the
  * provided variable definitions and arbitrary input. If the input cannot be
- * parsed to match the variable definitions, a GraphQLError will be thrown.
+ * parsed to match the variable definitions, GraphQLError values are returned.
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param schema - GraphQL schema to use.
+ * @param varDefNodes - The variable definition AST nodes to coerce.
+ * @param inputs - The runtime variable values keyed by variable name.
+ * @param options - Optional variable coercion options, including error limits.
+ * @returns Coerced variable values, or request errors.
+ * @example
+ * ```ts
+ * // Coerce provided variables and apply operation defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($stars: Int!, $limit: Int = 10) {
+ *     reviews(stars: $stars, limit: $limit)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { stars: '5' },
+ * );
+ *
+ * result; // => { coerced: { stars: 5, limit: 10 } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses maxErrors to cap reported coercion errors.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { first: { stars: 'bad' }, second: { stars: 'also bad' } },
+ *   { maxErrors: 1 },
+ * );
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
@@ -163,5 +231,46 @@ function getVariableValues(schema, varDefNodes, inputs, options) {
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param def - The field or directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced argument values keyed by argument name.
+ * @example
+ * ```ts
+ * // Read literal argument values and defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('{ reviews(stars: 5) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode); // => { stars: 5, limit: 10 }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves argument values from operation variables.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('query ($stars: Int!) { reviews(stars: $stars) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode, { stars: 5 }); // => { stars: 5 }
+ * getArgumentValues(fieldDef, fieldNode, {}); // throws an error
+ * ```
  */
@@ -274,2 +383,7 @@
 /**
+ * AST node shape accepted by getDirectiveValues.
+ * @internal
+ */
+
+/**
  * Prepares an object map of argument values given a directive definition
@@ -281,7 +395,37 @@ * and a AST node which may contain directives. Optionally also accepts a map
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param directiveDef - The directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced directive argument values keyed by argument name.
+ * @example
+ * ```ts
+ * // Read literal directive arguments from a node.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLSkipDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('{ name @skip(if: true) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLSkipDirective, fieldNode); // => { if: true }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves directive arguments from variables and handles absent directives.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLIncludeDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('query ($includeName: Boolean!) { name @include(if: $includeName) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLIncludeDirective, fieldNode, {
+ *   includeName: false,
+ * }); // => { if: false }
+ * getDirectiveValues(GraphQLIncludeDirective, { directives: [] }); // => undefined
+ * ```
  */
-
 function getDirectiveValues(directiveDef, node, variableValues) {
@@ -288,0 +432,0 @@ var _node$directives;

execution/values.mjs

@@ -0,1 +1,2 @@
+/** @category Values */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -15,7 +16,73 @@ import { keyMap } from '../jsutils/keyMap.mjs';
  * provided variable definitions and arbitrary input. If the input cannot be
- * parsed to match the variable definitions, a GraphQLError will be thrown.
+ * parsed to match the variable definitions, GraphQLError values are returned.
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param schema - GraphQL schema to use.
+ * @param varDefNodes - The variable definition AST nodes to coerce.
+ * @param inputs - The runtime variable values keyed by variable name.
+ * @param options - Optional variable coercion options, including error limits.
+ * @returns Coerced variable values, or request errors.
+ * @example
+ * ```ts
+ * // Coerce provided variables and apply operation defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($stars: Int!, $limit: Int = 10) {
+ *     reviews(stars: $stars, limit: $limit)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { stars: '5' },
+ * );
+ *
+ * result; // => { coerced: { stars: 5, limit: 10 } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses maxErrors to cap reported coercion errors.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getVariableValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   type Query {
+ *     review(input: ReviewInput!): String
+ *   }
+ * `);
+ * const document = parse(`
+ *   query ($first: ReviewInput!, $second: ReviewInput!) {
+ *     first: review(input: $first)
+ *     second: review(input: $second)
+ *   }
+ * `);
+ * const operation = document.definitions[0];
+ *
+ * const result = getVariableValues(
+ *   schema,
+ *   operation.variableDefinitions,
+ *   { first: { stars: 'bad' }, second: { stars: 'also bad' } },
+ *   { maxErrors: 1 },
+ * );
+ *
+ * result.errors.length; // => 2
+ * result.errors[1].message; // matches /error limit reached/
+ * ```
  */
@@ -139,5 +206,46 @@ export function getVariableValues(schema, varDefNodes, inputs, options) {
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param def - The field or directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced argument values keyed by argument name.
+ * @example
+ * ```ts
+ * // Read literal argument values and defaults.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!, limit: Int = 10): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('{ reviews(stars: 5) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode); // => { stars: 5, limit: 10 }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves argument values from operation variables.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { getArgumentValues } from 'graphql/execution';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     reviews(stars: Int!): [String]
+ *   }
+ * `);
+ * const fieldDef = schema.getQueryType().getFields().reviews;
+ * const document = parse('query ($stars: Int!) { reviews(stars: $stars) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getArgumentValues(fieldDef, fieldNode, { stars: 5 }); // => { stars: 5 }
+ * getArgumentValues(fieldDef, fieldNode, {}); // throws an error
+ * ```
  */
@@ -237,2 +345,7 @@
 /**
+ * AST node shape accepted by getDirectiveValues.
+ * @internal
+ */
+
+/**
  * Prepares an object map of argument values given a directive definition
@@ -244,7 +357,37 @@ * and a AST node which may contain directives. Optionally also accepts a map
  *
- * Note: The returned value is a plain Object with a prototype, since it is
+ * Note: Returned value is a plain Object with a prototype, since it is
  * exposed to user code. Care should be taken to not pull values from the
  * Object prototype.
+ * @param directiveDef - The directive definition whose arguments should be coerced.
+ * @param node - The AST node to inspect.
+ * @param variableValues - The runtime variable values keyed by variable name.
+ * @returns Coerced directive argument values keyed by argument name.
+ * @example
+ * ```ts
+ * // Read literal directive arguments from a node.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLSkipDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('{ name @skip(if: true) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLSkipDirective, fieldNode); // => { if: true }
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves directive arguments from variables and handles absent directives.
+ * import { parse } from 'graphql/language';
+ * import { GraphQLIncludeDirective } from 'graphql/type';
+ * import { getDirectiveValues } from 'graphql/execution';
+ *
+ * const document = parse('query ($includeName: Boolean!) { name @include(if: $includeName) }');
+ * const fieldNode = document.definitions[0].selectionSet.selections[0];
+ *
+ * getDirectiveValues(GraphQLIncludeDirective, fieldNode, {
+ *   includeName: false,
+ * }); // => { if: false }
+ * getDirectiveValues(GraphQLIncludeDirective, { directives: [] }); // => undefined
+ * ```
  */
-
 export function getDirectiveValues(directiveDef, node, variableValues) {
@@ -251,0 +394,0 @@ var _node$directives;

graphql.d.ts

@@ -10,59 +10,181 @@ import type { Maybe } from './jsutils/Maybe';
 /**
- * This is the primary entry point function for fulfilling GraphQL operations
- * by parsing, validating, and executing a GraphQL document along side a
- * GraphQL schema.
+ * Describes the input object accepted by `graphql` and `graphqlSync`.
  *
- * More sophisticated GraphQL servers, such as those which persist queries,
- * may wish to separate the validation and execution phases to a static time
- * tooling step, and a server runtime step.
- *
- * Accepts either an object with named arguments, or individual arguments:
- *
- * schema:
- *    The GraphQL type system to use when validating and executing a query.
- * source:
- *    A GraphQL language formatted string representing the requested operation.
- * rootValue:
- *    The value provided as the first argument to resolver functions on the top
- *    level type (e.g. the query object type).
- * contextValue:
- *    The context value is provided as an argument to resolver functions after
- *    field arguments. It is used to pass shared information useful at any point
- *    during executing this query, for example the currently logged in user and
- *    connections to databases or other services.
- * variableValues:
- *    A mapping of variable name to runtime value to use for all variables
- *    defined in the requestString.
- * operationName:
- *    The name of the operation to use if requestString contains multiple
- *    possible operations. Can be omitted if requestString contains only
- *    one operation.
- * fieldResolver:
- *    A resolver function to use when one is not provided by the schema.
- *    If not provided, the default field resolver is used (which looks for a
- *    value or method on the source value with the field's name).
- * typeResolver:
- *    A type resolver function to use when none is provided by the schema.
- *    If not provided, the default type resolver is used (which looks for a
- *    `__typename` field or alternatively calls the `isTypeOf` method).
+ * These arguments describe the full parse, validate, and execute lifecycle for
+ * a GraphQL request.
+ * @category Request Pipeline
  */
 export interface GraphQLArgs {
+  /** The GraphQL type system to use when validating and executing a query. */
   schema: GraphQLSchema;
+  /**
+   * A GraphQL language-formatted string or source object representing the
+   * requested operation.
+   */
   source: string | Source;
+  /**
+   * The value provided as the first argument to resolver functions on the top
+   * level type, such as the query object type.
+   */
   rootValue?: unknown;
+  /**
+   * Application context value passed to every resolver.
+   *
+   * Use this for shared request data such as the currently logged in user and
+   * connections to databases or other services.
+   */
   contextValue?: unknown;
+  /** A mapping of variable name to runtime value for variables defined by the operation. */
   variableValues?: Maybe<{
     readonly [variable: string]: unknown;
   }>;
+  /**
+   * The operation to execute when the source contains multiple possible
+   * operations. This can be omitted when the source contains only one operation.
+   */
   operationName?: Maybe<string>;
+  /**
+   * A resolver function to use when one is not provided by the schema.
+   *
+   * If not provided, the default field resolver is used, which looks for a value
+   * or method on the source value with the field's name.
+   */
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  /**
+   * A type resolver function to use when none is provided by the schema.
+   *
+   * If not provided, the default type resolver is used, which looks for a
+   * `__typename` field or alternatively calls the `isTypeOf` method.
+   */
   typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
 }
+/**
+ * Parses, validates, and executes a GraphQL document against a schema.
+ *
+ * This is the primary entry point for fulfilling GraphQL operations. Use this
+ * when you want a single-call request lifecycle that returns a promise in all
+ * cases.
+ *
+ * More sophisticated GraphQL servers, such as those which persist queries, may
+ * wish to separate the validation and execution phases to a static-time tooling
+ * step and a server runtime step.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns A promise that resolves to an execution result or validation errors.
+ * @example
+ * ```ts
+ * // Execute a complete asynchronous request with variables.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: '{ viewer { __typename name } }',
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   fieldResolver: (source, _args, context, info) => {
+ *     context.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @category Request Pipeline
+ */
 export declare function graphql(args: GraphQLArgs): Promise<ExecutionResult>;
 /**
- * The graphqlSync function also fulfills GraphQL operations by parsing,
- * validating, and executing a GraphQL document along side a GraphQL schema.
- * However, it guarantees to complete synchronously (or throw an error) assuming
- * that all field resolvers are also synchronous.
+ * Parses, validates, and executes a GraphQL document synchronously.
+ *
+ * This function guarantees that execution completes synchronously, or throws an
+ * error, assuming that all field resolvers are also synchronous. It throws when
+ * any resolver returns a promise.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns Completed execution output, or request errors if parsing or
+ * validation fails.
+ * @example
+ * ```ts
+ * // Execute a complete synchronous request with variables.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a synchronous custom field resolver and context.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: '{ greeting }',
+ *   fieldResolver: (_source, _args, contextValue) => {
+ *     return contextValue.defaultGreeting;
+ *   },
+ *   contextValue: { defaultGreeting: 'Hello' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @category Request Pipeline
  */
 export declare function graphqlSync(args: GraphQLArgs): ExecutionResult;

graphql.js

@@ -21,2 +21,74 @@ 'use strict';
 
+/**
+ * Parses, validates, and executes a GraphQL document against a schema.
+ *
+ * This is the primary entry point for fulfilling GraphQL operations. Use this
+ * when you want a single-call request lifecycle that returns a promise in all
+ * cases.
+ *
+ * More sophisticated GraphQL servers, such as those which persist queries, may
+ * wish to separate the validation and execution phases to a static-time tooling
+ * step and a server runtime step.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns A promise that resolves to an execution result or validation errors.
+ * @example
+ * ```ts
+ * // Execute a complete asynchronous request with variables.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: '{ viewer { __typename name } }',
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   fieldResolver: (source, _args, context, info) => {
+ *     context.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @category Request Pipeline
+ */
 function graphql(args) {
@@ -27,6 +99,56 @@ // Always return a Promise for a consistent API.
 /**
- * The graphqlSync function also fulfills GraphQL operations by parsing,
- * validating, and executing a GraphQL document along side a GraphQL schema.
- * However, it guarantees to complete synchronously (or throw an error) assuming
- * that all field resolvers are also synchronous.
+ * Parses, validates, and executes a GraphQL document synchronously.
+ *
+ * This function guarantees that execution completes synchronously, or throws an
+ * error, assuming that all field resolvers are also synchronous. It throws when
+ * any resolver returns a promise.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns Completed execution output, or request errors if parsing or
+ * validation fails.
+ * @example
+ * ```ts
+ * // Execute a complete synchronous request with variables.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a synchronous custom field resolver and context.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: '{ greeting }',
+ *   fieldResolver: (_source, _args, contextValue) => {
+ *     return contextValue.defaultGreeting;
+ *   },
+ *   contextValue: { defaultGreeting: 'Hello' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @category Request Pipeline
  */
@@ -33,0 +155,0 @@

graphql.mjs

@@ -8,41 +8,81 @@ import { devAssert } from './jsutils/devAssert.mjs';
 /**
- * This is the primary entry point function for fulfilling GraphQL operations
- * by parsing, validating, and executing a GraphQL document along side a
- * GraphQL schema.
+ * Describes the input object accepted by `graphql` and `graphqlSync`.
  *
- * More sophisticated GraphQL servers, such as those which persist queries,
- * may wish to separate the validation and execution phases to a static time
- * tooling step, and a server runtime step.
+ * These arguments describe the full parse, validate, and execute lifecycle for
+ * a GraphQL request.
+ * @category Request Pipeline
+ */
+
+/**
+ * Parses, validates, and executes a GraphQL document against a schema.
  *
- * Accepts either an object with named arguments, or individual arguments:
+ * This is the primary entry point for fulfilling GraphQL operations. Use this
+ * when you want a single-call request lifecycle that returns a promise in all
+ * cases.
  *
- * schema:
- *    The GraphQL type system to use when validating and executing a query.
- * source:
- *    A GraphQL language formatted string representing the requested operation.
- * rootValue:
- *    The value provided as the first argument to resolver functions on the top
- *    level type (e.g. the query object type).
- * contextValue:
- *    The context value is provided as an argument to resolver functions after
- *    field arguments. It is used to pass shared information useful at any point
- *    during executing this query, for example the currently logged in user and
- *    connections to databases or other services.
- * variableValues:
- *    A mapping of variable name to runtime value to use for all variables
- *    defined in the requestString.
- * operationName:
- *    The name of the operation to use if requestString contains multiple
- *    possible operations. Can be omitted if requestString contains only
- *    one operation.
- * fieldResolver:
- *    A resolver function to use when one is not provided by the schema.
- *    If not provided, the default field resolver is used (which looks for a
- *    value or method on the source value with the field's name).
- * typeResolver:
- *    A type resolver function to use when none is provided by the schema.
- *    If not provided, the default type resolver is used (which looks for a
- *    `__typename` field or alternatively calls the `isTypeOf` method).
+ * More sophisticated GraphQL servers, such as those which persist queries, may
+ * wish to separate the validation and execution phases to a static-time tooling
+ * step and a server runtime step.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns A promise that resolves to an execution result or validation errors.
+ * @example
+ * ```ts
+ * // Execute a complete asynchronous request with variables.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant supplies context plus custom field and type resolvers.
+ * import { graphql, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   interface Named {
+ *     name: String!
+ *   }
+ *
+ *   type User implements Named {
+ *     name: String!
+ *   }
+ *
+ *   type Query {
+ *     viewer: Named
+ *   }
+ * `);
+ *
+ * const result = await graphql({
+ *   schema,
+ *   source: '{ viewer { __typename name } }',
+ *   rootValue: { viewer: { kind: 'user', name: 'Ada' } },
+ *   contextValue: { locale: 'en' },
+ *   fieldResolver: (source, _args, context, info) => {
+ *     context.locale; // => 'en'
+ *     return source[info.fieldName];
+ *   },
+ *   typeResolver: (value) => {
+ *     return value.kind === 'user' ? 'User' : undefined;
+ *   },
+ * });
+ *
+ * result; // => { data: { viewer: { __typename: 'User', name: 'Ada' } } }
+ * ```
+ * @category Request Pipeline
  */
-
 export function graphql(args) {
@@ -53,6 +93,56 @@ // Always return a Promise for a consistent API.
 /**
- * The graphqlSync function also fulfills GraphQL operations by parsing,
- * validating, and executing a GraphQL document along side a GraphQL schema.
- * However, it guarantees to complete synchronously (or throw an error) assuming
- * that all field resolvers are also synchronous.
+ * Parses, validates, and executes a GraphQL document synchronously.
+ *
+ * This function guarantees that execution completes synchronously, or throws an
+ * error, assuming that all field resolvers are also synchronous. It throws when
+ * any resolver returns a promise.
+ * @param args - Request execution arguments, including schema and source.
+ * @returns Completed execution output, or request errors if parsing or
+ * validation fails.
+ * @example
+ * ```ts
+ * // Execute a complete synchronous request with variables.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String!): String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: 'query SayHello($name: String!) { greeting(name: $name) }',
+ *   rootValue: {
+ *     greeting: ({ name }) => `Hello, ${name}!`,
+ *   },
+ *   variableValues: { name: 'Ada' },
+ *   operationName: 'SayHello',
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello, Ada!' } }
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a synchronous custom field resolver and context.
+ * import { graphqlSync, buildSchema } from 'graphql';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const result = graphqlSync({
+ *   schema,
+ *   source: '{ greeting }',
+ *   fieldResolver: (_source, _args, contextValue) => {
+ *     return contextValue.defaultGreeting;
+ *   },
+ *   contextValue: { defaultGreeting: 'Hello' },
+ * });
+ *
+ * result; // => { data: { greeting: 'Hello' } }
+ * ```
+ * @category Request Pipeline
  */
@@ -59,0 +149,0 @@

index.d.ts

 /**
- * GraphQL.js provides a reference implementation for the GraphQL specification
- * but is also a useful utility for operating on GraphQL files and building
- * sophisticated tools.
+ * The root `graphql` package re-exports the public GraphQL.js API from its
+ * submodules and provides the high-level request pipeline helpers defined in
+ * this module.
  *
- * This primary module exports a general purpose function for fulfilling all
- * steps of the GraphQL specification in a single operation, but also includes
- * utilities for every part of the GraphQL specification:
+ * You can import public exports from GraphQL.js modules through the root
+ * `graphql` package or through their module-specific entry point. For example,
+ * these two references resolve to the same `parse` function:
  *
- *   - Parsing the GraphQL language.
- *   - Building a GraphQL type schema.
- *   - Validating a GraphQL request against a type schema.
- *   - Executing a GraphQL request against a type schema.
- *
- * This also includes utility functions for operating on GraphQL types and
- * GraphQL documents to facilitate building tools.
- *
- * You may also import from each sub-directory directly. For example, the
- * following two import statements are equivalent:
- *
  * ```ts
@@ -26,2 +15,7 @@ * import { parse } from 'graphql';
  *
+ * Use the root package when you want a single import surface, or use submodules
+ * such as `graphql/language`, `graphql/type`, `graphql/execution`, and
+ * `graphql/utilities` when you want module-focused imports. This module also
+ * defines root-only APIs, such as request pipeline helpers and version
+ * metadata, that do not belong to a narrower submodule.
  * @packageDocumentation
@@ -28,0 +22,0 @@ */

index.mjs

 /**
- * GraphQL.js provides a reference implementation for the GraphQL specification
- * but is also a useful utility for operating on GraphQL files and building
- * sophisticated tools.
+ * The root `graphql` package re-exports the public GraphQL.js API from its
+ * submodules and provides the high-level request pipeline helpers defined in
+ * this module.
  *
- * This primary module exports a general purpose function for fulfilling all
- * steps of the GraphQL specification in a single operation, but also includes
- * utilities for every part of the GraphQL specification:
+ * You can import public exports from GraphQL.js modules through the root
+ * `graphql` package or through their module-specific entry point. For example,
+ * these two references resolve to the same `parse` function:
  *
- *   - Parsing the GraphQL language.
- *   - Building a GraphQL type schema.
- *   - Validating a GraphQL request against a type schema.
- *   - Executing a GraphQL request against a type schema.
- *
- * This also includes utility functions for operating on GraphQL types and
- * GraphQL documents to facilitate building tools.
- *
- * You may also import from each sub-directory directly. For example, the
- * following two import statements are equivalent:
- *
  * ```ts
@@ -26,6 +15,11 @@ * import { parse } from 'graphql';
  *
+ * Use the root package when you want a single import surface, or use submodules
+ * such as `graphql/language`, `graphql/type`, `graphql/execution`, and
+ * `graphql/utilities` when you want module-focused imports. This module also
+ * defines root-only APIs, such as request pipeline helpers and version
+ * metadata, that do not belong to a narrower submodule.
  * @packageDocumentation
  */
-// The GraphQL.js version info.
-export { version, versionInfo } from './version.mjs'; // The primary entry point into fulfilling a GraphQL request.
+// Version constants for the GraphQL.js package.
+export { version, versionInfo } from './version.mjs'; // Top-level helpers for fulfilling a GraphQL request.
 
@@ -32,0 +26,0 @@ export { graphql, graphqlSync } from './graphql.mjs'; // Create and operate on GraphQL type definitions and schema.

jsutils/devAssert.d.ts

@@ -0,1 +1,2 @@
+/** @internal */
 export declare function devAssert(condition: unknown, message: string): void;

jsutils/devAssert.js

@@ -8,2 +8,3 @@ 'use strict';
 
+/** @internal */
 function devAssert(condition, message) {
@@ -10,0 +11,0 @@ const booleanCondition = Boolean(condition);

jsutils/devAssert.mjs

@@ -0,1 +1,2 @@
+/** @internal */
 export function devAssert(condition, message) {
@@ -2,0 +3,0 @@ const booleanCondition = Boolean(condition);

jsutils/didYouMean.d.ts

 /**
- * Given [ A, B, C ] return ' Did you mean A, B, or C?'.
+ * Given [A, B, C] return ' Did you mean A, B, or C?'.
+ *
+ * @internal
  */
 export declare function didYouMean(suggestions: ReadonlyArray<string>): string;
+/** @internal */
 export declare function didYouMean(
@@ -6,0 +9,0 @@ subMessage: string,

jsutils/didYouMean.js

@@ -9,5 +9,8 @@ 'use strict';
 /**
- * Given [ A, B, C ] return ' Did you mean A, B, or C?'.
+ * Given [A, B, C] return ' Did you mean A, B, or C?'.
+ *
+ * @internal
  */
 
+/** @internal */
 function didYouMean(firstArg, secondArg) {
@@ -14,0 +17,0 @@ const [subMessage, suggestionsArg] = secondArg

jsutils/didYouMean.mjs

 const MAX_SUGGESTIONS = 5;
 /**
- * Given [ A, B, C ] return ' Did you mean A, B, or C?'.
+ * Given [A, B, C] return ' Did you mean A, B, or C?'.
+ *
+ * @internal
  */
 
+/** @internal */
 export function didYouMean(firstArg, secondArg) {
@@ -7,0 +10,0 @@ const [subMessage, suggestionsArg] = secondArg

jsutils/groupBy.d.ts

 /**
  * Groups array items into a Map, given a function to produce grouping key.
+ *
+ * @internal
  */
@@ -4,0 +6,0 @@ export declare function groupBy<K, T>(

jsutils/groupBy.js

@@ -10,2 +10,4 @@ 'use strict';
  * Groups array items into a Map, given a function to produce grouping key.
+ *
+ * @internal
  */
@@ -12,0 +14,0 @@ function groupBy(list, keyFn) {

jsutils/groupBy.mjs

 /**
  * Groups array items into a Map, given a function to produce grouping key.
+ *
+ * @internal
  */
@@ -4,0 +6,0 @@ export function groupBy(list, keyFn) {

jsutils/identityFunc.d.ts

 /**
  * Returns the first argument it receives.
+ *
+ * @internal
  */
 export declare function identityFunc<T>(x: T): T;

jsutils/identityFunc.js

@@ -10,2 +10,4 @@ 'use strict';
  * Returns the first argument it receives.
+ *
+ * @internal
  */
@@ -12,0 +14,0 @@ function identityFunc(x) {

jsutils/identityFunc.mjs

 /**
  * Returns the first argument it receives.
+ *
+ * @internal
  */
@@ -4,0 +6,0 @@ export function identityFunc(x) {

jsutils/inspect.d.ts

 /**
  * Used to print values in error messages.
+ *
+ * @internal
  */
 export declare function inspect(value: unknown): string;

jsutils/inspect.js

@@ -11,2 +11,4 @@ 'use strict';
  * Used to print values in error messages.
+ *
+ * @internal
  */
@@ -13,0 +15,0 @@

jsutils/inspect.mjs

@@ -5,2 +5,4 @@ const MAX_ARRAY_LENGTH = 10;
  * Used to print values in error messages.
+ *
+ * @internal
  */
@@ -7,0 +9,0 @@

jsutils/instanceOf.d.ts

@@ -6,2 +6,4 @@ /**
  * See: https://webpack.js.org/guides/production/
+ *
+ * @internal
  */
@@ -8,0 +10,0 @@ export declare const instanceOf: (

jsutils/instanceOf.js

@@ -19,2 +19,4 @@ 'use strict';
  * See: https://webpack.js.org/guides/production/
+ *
+ * @internal
  */
@@ -21,0 +23,0 @@

jsutils/instanceOf.mjs

@@ -12,2 +12,4 @@ import { inspect } from './inspect.mjs';
  * See: https://webpack.js.org/guides/production/
+ *
+ * @internal
  */
@@ -14,0 +16,0 @@

jsutils/invariant.d.ts

@@ -0,1 +1,2 @@
+/** @internal */
 export declare function invariant(
@@ -2,0 +3,0 @@ condition: unknown,

jsutils/invariant.js

@@ -8,2 +8,3 @@ 'use strict';
 
+/** @internal */
 function invariant(condition, message) {
@@ -10,0 +11,0 @@ const booleanCondition = Boolean(condition);

jsutils/invariant.mjs

@@ -0,1 +1,2 @@
+/** @internal */
 export function invariant(condition, message) {
@@ -2,0 +3,0 @@ const booleanCondition = Boolean(condition);

jsutils/isAsyncIterable.d.ts

 /**
  * Returns true if the provided object implements the AsyncIterator protocol via
  * implementing a `Symbol.asyncIterator` method.
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export declare function isAsyncIterable(

jsutils/isAsyncIterable.js

@@ -11,2 +11,4 @@ 'use strict';
  * implementing a `Symbol.asyncIterator` method.
+ *
+ * @internal
  */
@@ -13,0 +15,0 @@ function isAsyncIterable(maybeAsyncIterable) {

jsutils/isAsyncIterable.mjs

 /**
  * Returns true if the provided object implements the AsyncIterator protocol via
  * implementing a `Symbol.asyncIterator` method.
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export function isAsyncIterable(maybeAsyncIterable) {

jsutils/isIterableObject.d.ts

@@ -9,9 +9,10 @@ /**
  *
+ * @internal
  * @example
  * ```ts
- * isIterableObject([ 1, 2, 3 ]) // true
- * isIterableObject(new Map()) // true
- * isIterableObject('ABC') // false
- * isIterableObject({ key: 'value' }) // false
- * isIterableObject({ length: 1, 0: 'Alpha' }) // false
+ * isIterableObject([1, 2, 3]); // => true
+ * isIterableObject(new Map()); // => true
+ * isIterableObject('ABC'); // => false
+ * isIterableObject({ key: 'value' }); // => false
+ * isIterableObject({ length: 1, 0: 'Alpha' }); // => false
  * ```
@@ -18,0 +19,0 @@ */

jsutils/isIterableObject.js

@@ -16,9 +16,10 @@ 'use strict';
  *
+ * @internal
  * @example
  * ```ts
- * isIterableObject([ 1, 2, 3 ]) // true
- * isIterableObject(new Map()) // true
- * isIterableObject('ABC') // false
- * isIterableObject({ key: 'value' }) // false
- * isIterableObject({ length: 1, 0: 'Alpha' }) // false
+ * isIterableObject([1, 2, 3]); // => true
+ * isIterableObject(new Map()); // => true
+ * isIterableObject('ABC'); // => false
+ * isIterableObject({ key: 'value' }); // => false
+ * isIterableObject({ length: 1, 0: 'Alpha' }); // => false
  * ```
@@ -25,0 +26,0 @@ */

jsutils/isIterableObject.mjs

@@ -9,9 +9,10 @@ /**
  *
+ * @internal
  * @example
  * ```ts
- * isIterableObject([ 1, 2, 3 ]) // true
- * isIterableObject(new Map()) // true
- * isIterableObject('ABC') // false
- * isIterableObject({ key: 'value' }) // false
- * isIterableObject({ length: 1, 0: 'Alpha' }) // false
+ * isIterableObject([1, 2, 3]); // => true
+ * isIterableObject(new Map()); // => true
+ * isIterableObject('ABC'); // => false
+ * isIterableObject({ key: 'value' }); // => false
+ * isIterableObject({ length: 1, 0: 'Alpha' }); // => false
  * ```
@@ -18,0 +19,0 @@ */

jsutils/isObjectLike.d.ts

 /**
  * Return true if `value` is object-like. A value is object-like if it's not
  * `null` and has a `typeof` result of "object".
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export declare function isObjectLike(value: unknown): value is {

jsutils/isObjectLike.js

@@ -11,2 +11,4 @@ 'use strict';
  * `null` and has a `typeof` result of "object".
+ *
+ * @internal
  */
@@ -13,0 +15,0 @@ function isObjectLike(value) {

jsutils/isObjectLike.mjs

 /**
  * Return true if `value` is object-like. A value is object-like if it's not
  * `null` and has a `typeof` result of "object".
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export function isObjectLike(value) {

jsutils/isPromise.d.ts

 /**
  * Returns true if the value acts like a Promise, i.e. has a "then" function,
  * otherwise returns false.
+ *
+ * @internal
  */
 export declare function isPromise(value: any): value is Promise<unknown>;

jsutils/isPromise.js

@@ -11,2 +11,4 @@ 'use strict';
  * otherwise returns false.
+ *
+ * @internal
  */
@@ -13,0 +15,0 @@ function isPromise(value) {

jsutils/isPromise.mjs

 /**
  * Returns true if the value acts like a Promise, i.e. has a "then" function,
  * otherwise returns false.
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export function isPromise(value) {

jsutils/keyMap.d.ts

@@ -8,21 +8,14 @@ import type { ObjMap } from './ObjMap';
  * produces unique results.
+ * @internal
+ * @example
  * ```ts
  * const phoneBook = [
  *   { name: 'Jon', num: '555-1234' },
- *   { name: 'Jenny', num: '867-5309' }
- * ]
+ *   { name: 'Jenny', num: '867-5309' },
+ * ];
  *
- * const entriesByName = keyMap(
- *   phoneBook,
- *   entry => entry.name
- * )
+ * const entriesByName = keyMap(phoneBook, (entry) => entry.name);
  *
- * // {
- * //   Jon: { name: 'Jon', num: '555-1234' },
- * //   Jenny: { name: 'Jenny', num: '867-5309' }
- * // }
- *
- * const jennyEntry = entriesByName['Jenny']
- *
- * // { name: 'Jenny', num: '857-6309' }
+ * Object.keys(entriesByName); // => ['Jon', 'Jenny']
+ * entriesByName['Jenny']; // => { name: 'Jenny', num: '867-5309' }
  * ```
@@ -29,0 +22,0 @@ */

jsutils/keyMap.js

@@ -14,21 +14,14 @@ 'use strict';
  * produces unique results.
+ * @internal
+ * @example
  * ```ts
  * const phoneBook = [
  *   { name: 'Jon', num: '555-1234' },
- *   { name: 'Jenny', num: '867-5309' }
- * ]
+ *   { name: 'Jenny', num: '867-5309' },
+ * ];
  *
- * const entriesByName = keyMap(
- *   phoneBook,
- *   entry => entry.name
- * )
+ * const entriesByName = keyMap(phoneBook, (entry) => entry.name);
  *
- * // {
- * //   Jon: { name: 'Jon', num: '555-1234' },
- * //   Jenny: { name: 'Jenny', num: '867-5309' }
- * // }
- *
- * const jennyEntry = entriesByName['Jenny']
- *
- * // { name: 'Jenny', num: '857-6309' }
+ * Object.keys(entriesByName); // => ['Jon', 'Jenny']
+ * entriesByName['Jenny']; // => { name: 'Jenny', num: '867-5309' }
  * ```
@@ -35,0 +28,0 @@ */

jsutils/keyMap.mjs

@@ -7,21 +7,14 @@ /**
  * produces unique results.
+ * @internal
+ * @example
  * ```ts
  * const phoneBook = [
  *   { name: 'Jon', num: '555-1234' },
- *   { name: 'Jenny', num: '867-5309' }
- * ]
+ *   { name: 'Jenny', num: '867-5309' },
+ * ];
  *
- * const entriesByName = keyMap(
- *   phoneBook,
- *   entry => entry.name
- * )
+ * const entriesByName = keyMap(phoneBook, (entry) => entry.name);
  *
- * // {
- * //   Jon: { name: 'Jon', num: '555-1234' },
- * //   Jenny: { name: 'Jenny', num: '867-5309' }
- * // }
- *
- * const jennyEntry = entriesByName['Jenny']
- *
- * // { name: 'Jenny', num: '857-6309' }
+ * Object.keys(entriesByName); // => ['Jon', 'Jenny']
+ * entriesByName['Jenny']; // => { name: 'Jenny', num: '867-5309' }
  * ```
@@ -28,0 +21,0 @@ */

jsutils/keyValMap.d.ts

@@ -5,14 +5,17 @@ import type { ObjMap } from './ObjMap';
  * and a function to produce the values from each item in the array.
+ * @internal
+ * @example
  * ```ts
  * const phoneBook = [
  *   { name: 'Jon', num: '555-1234' },
- *   { name: 'Jenny', num: '867-5309' }
- * ]
+ *   { name: 'Jenny', num: '867-5309' },
+ * ];
  *
- * // { Jon: '555-1234', Jenny: '867-5309' }
  * const phonesByName = keyValMap(
  *   phoneBook,
- *   entry => entry.name,
- *   entry => entry.num
- * )
+ *   (entry) => entry.name,
+ *   (entry) => entry.num,
+ * );
+ *
+ * phonesByName; // => { Jon: '555-1234', Jenny: '867-5309' }
  * ```
@@ -19,0 +22,0 @@ */

jsutils/keyValMap.js

@@ -11,14 +11,17 @@ 'use strict';
  * and a function to produce the values from each item in the array.
+ * @internal
+ * @example
  * ```ts
  * const phoneBook = [
  *   { name: 'Jon', num: '555-1234' },
- *   { name: 'Jenny', num: '867-5309' }
- * ]
+ *   { name: 'Jenny', num: '867-5309' },
+ * ];
  *
- * // { Jon: '555-1234', Jenny: '867-5309' }
  * const phonesByName = keyValMap(
  *   phoneBook,
- *   entry => entry.name,
- *   entry => entry.num
- * )
+ *   (entry) => entry.name,
+ *   (entry) => entry.num,
+ * );
+ *
+ * phonesByName; // => { Jon: '555-1234', Jenny: '867-5309' }
  * ```
@@ -25,0 +28,0 @@ */

jsutils/keyValMap.mjs

 /**
  * Creates a keyed JS object from an array, given a function to produce the keys
  * and a function to produce the values from each item in the array.
+ * @internal
+ * @example
  * ```ts
  * const phoneBook = [
  *   { name: 'Jon', num: '555-1234' },
- *   { name: 'Jenny', num: '867-5309' }
- * ]
+ *   { name: 'Jenny', num: '867-5309' },
+ * ];
  *
- * // { Jon: '555-1234', Jenny: '867-5309' }
  * const phonesByName = keyValMap(
  *   phoneBook,
- *   entry => entry.name,
- *   entry => entry.num
- * )
+ *   (entry) => entry.name,
+ *   (entry) => entry.num,
+ * );
+ *
+ * phonesByName; // => { Jon: '555-1234', Jenny: '867-5309' }
  * ```
@@ -17,0 +20,0 @@ */

jsutils/mapValue.d.ts

@@ -5,2 +5,4 @@ import type { ObjMap, ReadOnlyObjMap } from './ObjMap';
  * running each value of `map` thru `fn`.
+ *
+ * @internal
  */
@@ -7,0 +9,0 @@ export declare function mapValue<T, V>(

jsutils/mapValue.js

@@ -11,2 +11,4 @@ 'use strict';
  * running each value of `map` thru `fn`.
+ *
+ * @internal
  */
@@ -13,0 +15,0 @@ function mapValue(map, fn) {

jsutils/mapValue.mjs

 /**
  * Creates an object map with the same keys as `map` and values generated by
  * running each value of `map` thru `fn`.
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export function mapValue(map, fn) {

jsutils/Maybe.d.ts

@@ -1,2 +0,6 @@
-/** Conveniently represents flow's "Maybe" type https://flow.org/en/docs/types/maybe/ */
+/**
+ * Conveniently represents flow's "Maybe" type https://flow.org/en/docs/types/maybe/
+ *
+ * @internal
+ */
 export declare type Maybe<T> = null | undefined | T;

jsutils/memoize3.d.ts

 /**
  * Memoizes the provided three-argument function.
+ *
+ * @internal
  */
@@ -4,0 +6,0 @@ export declare function memoize3<

jsutils/memoize3.js

@@ -10,2 +10,4 @@ 'use strict';
  * Memoizes the provided three-argument function.
+ *
+ * @internal
  */
@@ -12,0 +14,0 @@ function memoize3(fn) {

jsutils/memoize3.mjs

 /**
  * Memoizes the provided three-argument function.
+ *
+ * @internal
  */
@@ -4,0 +6,0 @@ export function memoize3(fn) {

jsutils/naturalCompare.d.ts

@@ -7,3 +7,5 @@ /**
  *
+ *
+ * @internal
  */
 export declare function naturalCompare(aStr: string, bStr: string): number;

jsutils/naturalCompare.js

@@ -14,2 +14,4 @@ 'use strict';
  *
+ *
+ * @internal
  */
@@ -16,0 +18,0 @@ function naturalCompare(aStr, bStr) {

jsutils/naturalCompare.mjs

@@ -7,2 +7,4 @@ /**
  *
+ *
+ * @internal
  */
@@ -9,0 +11,0 @@ export function naturalCompare(aStr, bStr) {

jsutils/ObjMap.d.ts

@@ -0,4 +1,6 @@
+/** @internal */
 export interface ObjMap<T> {
   [key: string]: T;
 }
+/** @internal */
 export declare type ObjMapLike<T> =
@@ -9,5 +11,7 @@ | ObjMap<T>
     };
+/** @internal */
 export interface ReadOnlyObjMap<T> {
   readonly [key: string]: T;
 }
+/** @internal */
 export declare type ReadOnlyObjMapLike<T> =
@@ -14,0 +18,0 @@ | ReadOnlyObjMap<T>

jsutils/Path.d.ts

@@ -0,5 +1,10 @@
+/** @category Paths */
 import type { Maybe } from './Maybe';
+/** Represents a linked response path from a field back to the root response. */
 export interface Path {
+  /** The previous segment in the linked response path, or undefined at the root. */
   readonly prev: Path | undefined;
+  /** The field name or list index for this response path segment. */
   readonly key: string | number;
+  /** The runtime object type name associated with this path segment, if known. */
   readonly typename: string | undefined;
@@ -9,2 +14,4 @@ }
  * Given a Path and a key, return a new Path containing the new key.
+ *
+ * @internal
  */
@@ -18,2 +25,25 @@ export declare function addPath(
  * Given a Path, return an Array of the path keys.
+ * @param path - The linked response path to flatten.
+ * @returns An array of response path keys from root to leaf.
+ * @example
+ * ```ts
+ * import { pathToArray } from 'graphql/jsutils/Path';
+ *
+ * const path = {
+ *   prev: {
+ *     prev: {
+ *       prev: undefined,
+ *       key: 'viewer',
+ *       typename: 'Query',
+ *     },
+ *     key: 'friends',
+ *     typename: 'User',
+ *   },
+ *   key: 0,
+ *   typename: undefined,
+ * };
+ *
+ * pathToArray(path); // => ['viewer', 'friends', 0]
+ * pathToArray(undefined); // => []
+ * ```
  */
@@ -20,0 +50,0 @@ export declare function pathToArray(

jsutils/Path.js

@@ -9,4 +9,10 @@ 'use strict';
 
+/** @category Paths */
+
+/** Represents a linked response path from a field back to the root response. */
+
 /**
  * Given a Path and a key, return a new Path containing the new key.
+ *
+ * @internal
  */
@@ -22,2 +28,25 @@ function addPath(prev, key, typename) {
  * Given a Path, return an Array of the path keys.
+ * @param path - The linked response path to flatten.
+ * @returns An array of response path keys from root to leaf.
+ * @example
+ * ```ts
+ * import { pathToArray } from 'graphql/jsutils/Path';
+ *
+ * const path = {
+ *   prev: {
+ *     prev: {
+ *       prev: undefined,
+ *       key: 'viewer',
+ *       typename: 'Query',
+ *     },
+ *     key: 'friends',
+ *     typename: 'User',
+ *   },
+ *   key: 0,
+ *   typename: undefined,
+ * };
+ *
+ * pathToArray(path); // => ['viewer', 'friends', 0]
+ * pathToArray(undefined); // => []
+ * ```
  */
@@ -24,0 +53,0 @@

jsutils/Path.mjs

@@ -0,3 +1,9 @@
+/** @category Paths */
+
+/** Represents a linked response path from a field back to the root response. */
+
 /**
  * Given a Path and a key, return a new Path containing the new key.
+ *
+ * @internal
  */
@@ -13,2 +19,25 @@ export function addPath(prev, key, typename) {
  * Given a Path, return an Array of the path keys.
+ * @param path - The linked response path to flatten.
+ * @returns An array of response path keys from root to leaf.
+ * @example
+ * ```ts
+ * import { pathToArray } from 'graphql/jsutils/Path';
+ *
+ * const path = {
+ *   prev: {
+ *     prev: {
+ *       prev: undefined,
+ *       key: 'viewer',
+ *       typename: 'Query',
+ *     },
+ *     key: 'friends',
+ *     typename: 'User',
+ *   },
+ *   key: 0,
+ *   typename: undefined,
+ * };
+ *
+ * pathToArray(path); // => ['viewer', 'friends', 0]
+ * pathToArray(undefined); // => []
+ * ```
  */
@@ -15,0 +44,0 @@

jsutils/printPathArray.d.ts

 /**
  * Build a string describing the path.
+ *
+ * @internal
  */
@@ -4,0 +6,0 @@ export declare function printPathArray(

jsutils/printPathArray.js

@@ -10,2 +10,4 @@ 'use strict';
  * Build a string describing the path.
+ *
+ * @internal
  */
@@ -12,0 +14,0 @@ function printPathArray(path) {

jsutils/printPathArray.mjs

 /**
  * Build a string describing the path.
+ *
+ * @internal
  */
@@ -4,0 +6,0 @@ export function printPathArray(path) {

jsutils/promiseForObject.d.ts

@@ -8,2 +8,4 @@ import type { ObjMap } from './ObjMap';
  * `Promise.all` so it will work with any implementation of ES6 promises.
+ *
+ * @internal
  */
@@ -10,0 +12,0 @@ export declare function promiseForObject<T>(

jsutils/promiseForObject.js

@@ -14,2 +14,4 @@ 'use strict';
  * `Promise.all` so it will work with any implementation of ES6 promises.
+ *
+ * @internal
  */
@@ -16,0 +18,0 @@ function promiseForObject(object) {

jsutils/promiseForObject.mjs

@@ -7,2 +7,4 @@ /**
  * `Promise.all` so it will work with any implementation of ES6 promises.
+ *
+ * @internal
  */
@@ -9,0 +11,0 @@ export function promiseForObject(object) {

jsutils/PromiseOrValue.d.ts

@@ -0,1 +1,2 @@
+/** @internal */
 export declare type PromiseOrValue<T> = Promise<T> | T;

jsutils/promiseReduce.d.ts

@@ -8,2 +8,4 @@ import type { PromiseOrValue } from './PromiseOrValue';
  * return a Promise.
+ *
+ * @internal
  */
@@ -10,0 +12,0 @@ export declare function promiseReduce<T, U>(

jsutils/promiseReduce.js

@@ -16,2 +16,4 @@ 'use strict';
  * return a Promise.
+ *
+ * @internal
  */
@@ -18,0 +20,0 @@ function promiseReduce(values, callbackFn, initialValue) {

jsutils/promiseReduce.mjs

@@ -9,2 +9,4 @@ import { isPromise } from './isPromise.mjs';
  * return a Promise.
+ *
+ * @internal
  */
@@ -11,0 +13,0 @@ export function promiseReduce(values, callbackFn, initialValue) {

jsutils/suggestionList.d.ts

 /**
  * Given an invalid input string and a list of valid options, returns a filtered
  * list of valid options sorted based on their similarity with the input.
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@ export declare function suggestionList(

jsutils/suggestionList.js

@@ -13,2 +13,4 @@ 'use strict';
  * list of valid options sorted based on their similarity with the input.
+ *
+ * @internal
  */
@@ -48,2 +50,4 @@ function suggestionList(input, options) {
  * This distance can be useful for detecting typos in input or sorting
+ *
+ * @internal
  */
@@ -50,0 +54,0 @@

jsutils/suggestionList.mjs

@@ -5,2 +5,4 @@ import { naturalCompare } from './naturalCompare.mjs';
  * list of valid options sorted based on their similarity with the input.
+ *
+ * @internal
  */
@@ -39,2 +41,4 @@
  * This distance can be useful for detecting typos in input or sorting
+ *
+ * @internal
  */
@@ -41,0 +45,0 @@

jsutils/toError.d.ts

 /**
  * Sometimes a non-error is thrown, wrap it as an Error instance to ensure a consistent Error interface.
+ *
+ * @internal
  */
 export declare function toError(thrownValue: unknown): Error;

jsutils/toError.js

@@ -12,2 +12,4 @@ 'use strict';
  * Sometimes a non-error is thrown, wrap it as an Error instance to ensure a consistent Error interface.
+ *
+ * @internal
  */
@@ -14,0 +16,0 @@ function toError(thrownValue) {

jsutils/toError.mjs

 import { inspect } from './inspect.mjs';
 /**
  * Sometimes a non-error is thrown, wrap it as an Error instance to ensure a consistent Error interface.
+ *
+ * @internal
  */
@@ -5,0 +7,0 @@

jsutils/toObjMap.d.ts

 import type { Maybe } from './Maybe';
 import type { ReadOnlyObjMap, ReadOnlyObjMapLike } from './ObjMap';
+/** @internal */
 export declare function toObjMap<T>(
   obj: Maybe<ReadOnlyObjMapLike<T>>,
 ): ReadOnlyObjMap<T>;

jsutils/toObjMap.js

@@ -8,2 +8,3 @@ 'use strict';
 
+/** @internal */
 function toObjMap(obj) {
@@ -10,0 +11,0 @@ if (obj == null) {

jsutils/toObjMap.mjs

@@ -0,1 +1,2 @@
+/** @internal */
 export function toObjMap(obj) {
@@ -2,0 +3,0 @@ if (obj == null) {

language/ast.d.ts

@@ -0,1 +1,2 @@
+/** @category AST */
 import type { Kind } from './kinds';
@@ -9,24 +10,50 @@ import type { Source } from './source';
 export declare class Location {
-  /**
-   * The character offset at which this Node begins.
-   */
+  /** The character offset at which this Node begins. */
   readonly start: number;
-  /**
-   * The character offset at which this Node ends.
-   */
+  /** The character offset at which this Node ends. */
   readonly end: number;
+  /** The Token at which this Node begins. */
+  readonly startToken: Token;
+  /** The Token at which this Node ends. */
+  readonly endToken: Token;
+  /** The Source document the AST represents. */
+  readonly source: Source;
   /**
-   * The Token at which this Node begins.
+   * Creates a Location instance.
+   * @param startToken - The start token.
+   * @param endToken - The end token.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Location, Source, Token, TokenKind } from 'graphql/language';
+   *
+   * const source = new Source('{ hello }');
+   * const startToken = new Token(TokenKind.BRACE_L, 0, 1, 1, 1);
+   * const endToken = new Token(TokenKind.BRACE_R, 8, 9, 1, 9);
+   * const location = new Location(startToken, endToken, source);
+   *
+   * location.start; // => 0
+   * location.end; // => 9
+   * location.source.body; // => '{ hello }'
+   * ```
    */
-  readonly startToken: Token;
+  constructor(startToken: Token, endToken: Token, source: Source);
   /**
-   * The Token at which this Node ends.
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
    */
-  readonly endToken: Token;
+  get [Symbol.toStringTag](): string;
   /**
-   * The Source document the AST represents.
+   * Returns a JSON representation of this location.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   *
+   * const document = parse('{ hello }');
+   * const location = document.loc?.toJSON();
+   *
+   * location; // => { start: 0, end: 9 }
+   * ```
    */
-  readonly source: Source;
-  constructor(startToken: Token, endToken: Token, source: Source);
-  get [Symbol.toStringTag](): string;
   toJSON(): {
@@ -42,21 +69,11 @@ start: number;
 export declare class Token {
-  /**
-   * The kind of Token.
-   */
+  /** The kind of Token. */
   readonly kind: TokenKind;
-  /**
-   * The character offset at which this Node begins.
-   */
+  /** The character offset at which this Node begins. */
   readonly start: number;
-  /**
-   * The character offset at which this Node ends.
-   */
+  /** The character offset at which this Node ends. */
   readonly end: number;
-  /**
-   * The 1-indexed line number on which this Token appears.
-   */
+  /** The 1-indexed line number on which this Token appears. */
   readonly line: number;
-  /**
-   * The 1-indexed column number at which this Token begins.
-   */
+  /** The 1-indexed column number at which this Token begins. */
   readonly column: number;
@@ -76,3 +93,23 @@ /**
   readonly prev: Token | null;
+  /** Next token in the token stream, including ignored tokens. */
   readonly next: Token | null;
+  /**
+   * Creates a Token instance.
+   * @param kind - Token kind produced by lexical analysis.
+   * @param start - Character offset where this token begins.
+   * @param end - Character offset where this token ends.
+   * @param line - One-indexed line number where this token begins.
+   * @param column - One-indexed column number where this token begins.
+   * @param value - Interpreted value for non-punctuation tokens.
+   * @example
+   * ```ts
+   * import { Token, TokenKind } from 'graphql/language';
+   *
+   * const token = new Token(TokenKind.NAME, 2, 7, 1, 3, 'hello');
+   *
+   * token.kind; // => TokenKind.NAME
+   * token.value; // => 'hello'
+   * token.toJSON(); // => { kind: 'Name', value: 'hello', line: 1, column: 3 }
+   * ```
+   */
   constructor(
@@ -86,3 +123,20 @@ kind: TokenKind,
   );
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * Returns a JSON representation of this token.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance().toJSON();
+   *
+   * token; // => { kind: '{', value: undefined, line: 1, column: 1 }
+   * ```
+   */
   toJSON(): {
@@ -95,5 +149,3 @@ kind: TokenKind;
 }
-/**
- * The list of all possible AST node types.
- */
+/** The list of all possible AST node types. */
 export declare type ASTNode =
@@ -149,31 +201,33 @@ | NameNode
   | DirectiveArgumentCoordinateNode;
-/**
- * Utility type listing all nodes indexed by their kind.
- */
+/** Utility type listing all nodes indexed by their kind. */
 export declare type ASTKindToNode = {
   [NodeT in ASTNode as NodeT['kind']]: NodeT;
 };
-/**
- * @internal
- */
+/** @internal */
 export declare const QueryDocumentKeys: {
   [NodeT in ASTNode as NodeT['kind']]: ReadonlyArray<keyof NodeT>;
 };
-/**
- * @internal
- */
+/** @internal */
 export declare function isNode(maybeNode: any): maybeNode is ASTNode;
-/** Name */
+/** An identifier in a GraphQL document. */
 export interface NameNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.NAME;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Parsed value represented by this node. */
   readonly value: string;
 }
-/** Document */
+/** The root AST node for a parsed GraphQL document. */
 export interface DocumentNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.DOCUMENT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Top-level executable and type-system definitions in this document. */
   readonly definitions: ReadonlyArray<DefinitionNode>;
+  /** The number of lexical tokens parsed for this document, if token counting was enabled. */
   readonly tokenCount?: number | undefined;
 }
+/** Any top-level definition that may appear in a GraphQL document. */
 export declare type DefinitionNode =
@@ -183,40 +237,74 @@ | ExecutableDefinitionNode
   | TypeSystemExtensionNode;
+/** Any executable definition that may appear in an operation document. */
 export declare type ExecutableDefinitionNode =
   | OperationDefinitionNode
   | FragmentDefinitionNode;
+/** A query, mutation, or subscription operation definition. */
 export interface OperationDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OPERATION_DEFINITION;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The operation selected for execution. */
   readonly operation: OperationTypeNode;
+  /** Name node identifying this AST node. */
   readonly name?: NameNode;
+  /** Variable definitions declared by this operation or fragment. */
   readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<DirectiveNode>;
+  /** Selections made by this operation, field, or fragment. */
   readonly selectionSet: SelectionSetNode;
 }
+/**
+ * The operation types supported by GraphQL executable definitions.
+ * @category Kinds
+ */
 declare enum OperationTypeNode {
+  /** A query operation. */
   QUERY = 'query',
+  /** A mutation operation. */
   MUTATION = 'mutation',
+  /** A subscription operation. */
   SUBSCRIPTION = 'subscription',
 }
 export { OperationTypeNode };
+/** A variable declaration in an operation or legacy fragment definition. */
 export interface VariableDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.VARIABLE_DEFINITION;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The variable being defined or referenced. */
   readonly variable: VariableNode;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: TypeNode;
+  /** Default value used when no explicit value is supplied. */
   readonly defaultValue?: ConstValueNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
 }
+/** A variable reference, such as `$id`. */
 export interface VariableNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.VARIABLE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
 }
+/** A set of fields and fragments selected from an object, interface, or union. */
 export interface SelectionSetNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   kind: Kind.SELECTION_SET;
+  /** The source location for this AST node, if location tracking was enabled. */
   loc?: Location;
+  /** Fields and fragments contained in this selection set. */
   selections: ReadonlyArray<SelectionNode>;
 }
+/** Any selection that may appear inside a selection set. */
 export declare type SelectionNode =
@@ -226,49 +314,92 @@ | FieldNode
   | InlineFragmentNode;
+/** A field selected in an executable GraphQL document. */
 export interface FieldNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.FIELD;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The response-key alias for this field, if one was supplied. */
   readonly alias?: NameNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Arguments supplied to this field, directive, or coordinate. */
   readonly arguments?: ReadonlyArray<ArgumentNode>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<DirectiveNode>;
+  /** Selections made by this operation, field, or fragment. */
   readonly selectionSet?: SelectionSetNode;
 }
+/** An argument supplied to a field or directive. */
 export interface ArgumentNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.ARGUMENT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Parsed value represented by this node. */
   readonly value: ValueNode;
 }
+/** An argument node whose value is guaranteed to be constant. */
 export interface ConstArgumentNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.ARGUMENT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Parsed value represented by this node. */
   readonly value: ConstValueNode;
 }
-/** Fragments */
+/** A named fragment spread, such as `...userFields`. */
 export interface FragmentSpreadNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.FRAGMENT_SPREAD;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<DirectiveNode>;
 }
+/** An inline fragment spread with an optional type condition. */
 export interface InlineFragmentNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.INLINE_FRAGMENT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The type condition that limits where this fragment applies. */
   readonly typeCondition?: NamedTypeNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<DirectiveNode>;
+  /** Selections made by this operation, field, or fragment. */
   readonly selectionSet: SelectionSetNode;
 }
+/** A reusable fragment definition declared in an executable document. */
 export interface FragmentDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.FRAGMENT_DEFINITION;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
-  /** @deprecated variableDefinitions will be removed in v17.0.0 */
+  /**
+   * Deprecated variable definitions declared by this legacy fragment
+   * definition. This legacy fragment variable syntax will be removed in v17.
+   * Move variable definitions to operations for spec-compliant documents; if
+   * you need variables or arguments scoped to fragments, v17 has a more
+   * complete experimental fragment-arguments feature.
+   * @deprecated variableDefinitions will be removed in v17.0.0
+   */
   readonly variableDefinitions?: ReadonlyArray<VariableDefinitionNode>;
+  /** The type condition that limits where this fragment applies. */
   readonly typeCondition: NamedTypeNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<DirectiveNode>;
+  /** Selections made by this operation, field, or fragment. */
   readonly selectionSet: SelectionSetNode;
 }
-/** Values */
+/** Any value literal that may appear in an executable GraphQL document. */
 export declare type ValueNode =
@@ -284,2 +415,3 @@ | VariableNode
   | ObjectValueNode;
+/** Any value literal that is guaranteed not to contain a variable reference. */
 export declare type ConstValueNode =
@@ -294,95 +426,166 @@ | IntValueNode
   | ConstObjectValueNode;
+/** An integer value literal. */
 export interface IntValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.INT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Parsed value represented by this node. */
   readonly value: string;
 }
+/** A floating-point value literal. */
 export interface FloatValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.FLOAT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Parsed value represented by this node. */
   readonly value: string;
 }
+/** A string value literal. */
 export interface StringValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.STRING;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Parsed value represented by this node. */
   readonly value: string;
+  /** Whether this string was parsed from block string syntax. */
   readonly block?: boolean;
 }
+/** A boolean value literal. */
 export interface BooleanValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.BOOLEAN;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Parsed value represented by this node. */
   readonly value: boolean;
 }
+/** A null value literal. */
 export interface NullValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.NULL;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
 }
+/** An enum value literal. */
 export interface EnumValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.ENUM;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Parsed value represented by this node. */
   readonly value: string;
 }
+/** A list value literal. */
 export interface ListValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.LIST;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Values contained in this enum, list, or input-object definition. */
   readonly values: ReadonlyArray<ValueNode>;
 }
+/** A list value literal whose elements are all constant values. */
 export interface ConstListValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.LIST;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Values contained in this enum, list, or input-object definition. */
   readonly values: ReadonlyArray<ConstValueNode>;
 }
+/** An input object value literal. */
 export interface ObjectValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OBJECT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields: ReadonlyArray<ObjectFieldNode>;
 }
+/** An input object value literal whose fields are all constant values. */
 export interface ConstObjectValueNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OBJECT;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields: ReadonlyArray<ConstObjectFieldNode>;
 }
+/** A field inside an input object value literal. */
 export interface ObjectFieldNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OBJECT_FIELD;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Parsed value represented by this node. */
   readonly value: ValueNode;
 }
+/** A field inside a constant input object value literal. */
 export interface ConstObjectFieldNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OBJECT_FIELD;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Parsed value represented by this node. */
   readonly value: ConstValueNode;
 }
-/** Directives */
+/** A directive applied to an executable or type-system location. */
 export interface DirectiveNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.DIRECTIVE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Arguments supplied to this field, directive, or coordinate. */
   readonly arguments?: ReadonlyArray<ArgumentNode>;
 }
+/** A directive whose arguments are all constant values. */
 export interface ConstDirectiveNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.DIRECTIVE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Arguments supplied to this field, directive, or coordinate. */
   readonly arguments?: ReadonlyArray<ConstArgumentNode>;
 }
-/** Type Reference */
+/** Any GraphQL type reference AST node. */
 export declare type TypeNode = NamedTypeNode | ListTypeNode | NonNullTypeNode;
+/** A named type reference. */
 export interface NamedTypeNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.NAMED_TYPE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
 }
+/** A list type reference. */
 export interface ListTypeNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.LIST_TYPE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: TypeNode;
 }
+/** A non-null type reference. */
 export interface NonNullTypeNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.NON_NULL_TYPE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: NamedTypeNode | ListTypeNode;
 }
-/** Type System Definition */
+/** Any type-system definition that may appear in a schema document. */
 export declare type TypeSystemDefinitionNode =
@@ -392,16 +595,27 @@ | SchemaDefinitionNode
   | DirectiveDefinitionNode;
+/** A schema definition in a type-system document. */
 export interface SchemaDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.SCHEMA_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Root operation types declared by this schema definition or extension. */
   readonly operationTypes: ReadonlyArray<OperationTypeDefinitionNode>;
 }
+/** A root operation type declaration inside a schema definition or extension. */
 export interface OperationTypeDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OPERATION_TYPE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The operation selected for execution. */
   readonly operation: OperationTypeNode;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: NamedTypeNode;
 }
-/** Type Definition */
+/** Any named type definition that may appear in a schema document. */
 export declare type TypeDefinitionNode =
@@ -414,88 +628,161 @@ | ScalarTypeDefinitionNode
   | InputObjectTypeDefinitionNode;
+/** A scalar type definition in a type-system document. */
 export interface ScalarTypeDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.SCALAR_TYPE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
 }
+/** An object type definition in a type-system document. */
 export interface ObjectTypeDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OBJECT_TYPE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Interfaces implemented by this object or interface type. */
   readonly interfaces?: ReadonlyArray<NamedTypeNode>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields?: ReadonlyArray<FieldDefinitionNode>;
 }
+/** A field definition declared by an object or interface type. */
 export interface FieldDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.FIELD_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Arguments supplied to this field, directive, or coordinate. */
   readonly arguments?: ReadonlyArray<InputValueDefinitionNode>;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: TypeNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
 }
+/** An argument or input-field definition. */
 export interface InputValueDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.INPUT_VALUE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: TypeNode;
+  /** Default value used when no explicit value is supplied. */
   readonly defaultValue?: ConstValueNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
 }
+/** An interface type definition in a type-system document. */
 export interface InterfaceTypeDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.INTERFACE_TYPE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Interfaces implemented by this object or interface type. */
   readonly interfaces?: ReadonlyArray<NamedTypeNode>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields?: ReadonlyArray<FieldDefinitionNode>;
 }
+/** A union type definition in a type-system document. */
 export interface UnionTypeDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.UNION_TYPE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Object types that belong to this union type. */
   readonly types?: ReadonlyArray<NamedTypeNode>;
 }
+/** An enum type definition in a type-system document. */
 export interface EnumTypeDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.ENUM_TYPE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Values contained in this enum, list, or input-object definition. */
   readonly values?: ReadonlyArray<EnumValueDefinitionNode>;
 }
+/** An enum value definition. */
 export interface EnumValueDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.ENUM_VALUE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
 }
+/** An input object type definition in a type-system document. */
 export interface InputObjectTypeDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.INPUT_OBJECT_TYPE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields?: ReadonlyArray<InputValueDefinitionNode>;
 }
-/** Directive Definitions */
+/** A directive definition in a type-system document. */
 export interface DirectiveDefinitionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.DIRECTIVE_DEFINITION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** The optional GraphQL description associated with this definition. */
   readonly description?: StringValueNode;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Arguments supplied to this field, directive, or coordinate. */
   readonly arguments?: ReadonlyArray<InputValueDefinitionNode>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Whether this directive may appear more than once at the same location. */
   readonly repeatable: boolean;
+  /** Locations where this directive may be applied. */
   readonly locations: ReadonlyArray<NameNode>;
 }
-/** Type System Extensions */
+/** Any type-system extension that may appear in a schema extension document. */
 export declare type TypeSystemExtensionNode =
@@ -505,9 +792,14 @@ | SchemaExtensionNode
   | DirectiveExtensionNode;
+/** A schema extension in a type-system document. */
 export interface SchemaExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.SCHEMA_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Root operation types declared by this schema definition or extension. */
   readonly operationTypes?: ReadonlyArray<OperationTypeDefinitionNode>;
 }
-/** Type Extensions */
+/** Any named type extension that may appear in a schema extension document. */
 export declare type TypeExtensionNode =
@@ -520,52 +812,94 @@ | ScalarTypeExtensionNode
   | InputObjectTypeExtensionNode;
+/** A scalar type extension. */
 export interface ScalarTypeExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.SCALAR_TYPE_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
 }
+/** An object type extension. */
 export interface ObjectTypeExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.OBJECT_TYPE_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Interfaces implemented by this object or interface type. */
   readonly interfaces?: ReadonlyArray<NamedTypeNode>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields?: ReadonlyArray<FieldDefinitionNode>;
 }
+/** An interface type extension. */
 export interface InterfaceTypeExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.INTERFACE_TYPE_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Interfaces implemented by this object or interface type. */
   readonly interfaces?: ReadonlyArray<NamedTypeNode>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields?: ReadonlyArray<FieldDefinitionNode>;
 }
+/** A union type extension. */
 export interface UnionTypeExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.UNION_TYPE_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Object types that belong to this union type. */
   readonly types?: ReadonlyArray<NamedTypeNode>;
 }
+/** An enum type extension. */
 export interface EnumTypeExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.ENUM_TYPE_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Values contained in this enum, list, or input-object definition. */
   readonly values?: ReadonlyArray<EnumValueDefinitionNode>;
 }
+/** An input object type extension. */
 export interface InputObjectTypeExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.INPUT_OBJECT_TYPE_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields?: ReadonlyArray<InputValueDefinitionNode>;
 }
+/** A directive extension. */
 export interface DirectiveExtensionNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.DIRECTIVE_EXTENSION;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives?: ReadonlyArray<ConstDirectiveNode>;
 }
-/** Schema Coordinates */
+/** Any AST node representing a GraphQL schema coordinate. */
 export declare type SchemaCoordinateNode =
@@ -577,30 +911,54 @@ | TypeCoordinateNode
   | DirectiveArgumentCoordinateNode;
+/** A schema coordinate that refers to a named type. */
 export interface TypeCoordinateNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.TYPE_COORDINATE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
 }
+/** A schema coordinate that refers to a member of a named type. */
 export interface MemberCoordinateNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.MEMBER_COORDINATE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** The member name referenced by this schema coordinate. */
   readonly memberName: NameNode;
 }
+/** A schema coordinate that refers to a field or directive argument. */
 export interface ArgumentCoordinateNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.ARGUMENT_COORDINATE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** The field name referenced by this schema coordinate. */
   readonly fieldName: NameNode;
+  /** The argument name referenced by this schema coordinate. */
   readonly argumentName: NameNode;
 }
+/** A schema coordinate that refers to a directive. */
 export interface DirectiveCoordinateNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.DIRECTIVE_COORDINATE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
 }
+/** A schema coordinate that refers to a directive argument. */
 export interface DirectiveArgumentCoordinateNode {
+  /** The discriminator identifying the concrete AST or introspection kind. */
   readonly kind: Kind.DIRECTIVE_ARGUMENT_COORDINATE;
+  /** The source location for this AST node, if location tracking was enabled. */
   readonly loc?: Location;
+  /** Name node identifying this AST node. */
   readonly name: NameNode;
+  /** The argument name referenced by this schema coordinate. */
   readonly argumentName: NameNode;
 }

language/ast.js

@@ -13,2 +13,4 @@ 'use strict';
 
+/** @category AST */
+
 /**
@@ -19,20 +21,30 @@ * Contains a range of UTF-8 character offsets and token references that
 class Location {
-  /**
-   * The character offset at which this Node begins.
-   */
+  /** The character offset at which this Node begins. */
 
-  /**
-   * The character offset at which this Node ends.
-   */
+  /** The character offset at which this Node ends. */
 
-  /**
-   * The Token at which this Node begins.
-   */
+  /** The Token at which this Node begins. */
 
-  /**
-   * The Token at which this Node ends.
-   */
+  /** The Token at which this Node ends. */
 
+  /** The Source document the AST represents. */
+
   /**
-   * The Source document the AST represents.
+   * Creates a Location instance.
+   * @param startToken - The start token.
+   * @param endToken - The end token.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Location, Source, Token, TokenKind } from 'graphql/language';
+   *
+   * const source = new Source('{ hello }');
+   * const startToken = new Token(TokenKind.BRACE_L, 0, 1, 1, 1);
+   * const endToken = new Token(TokenKind.BRACE_R, 8, 9, 1, 9);
+   * const location = new Location(startToken, endToken, source);
+   *
+   * location.start; // => 0
+   * location.end; // => 9
+   * location.source.body; // => '{ hello }'
+   * ```
    */
@@ -46,2 +58,6 @@ constructor(startToken, endToken, source) {
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -51,2 +67,15 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns a JSON representation of this location.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   *
+   * const document = parse('{ hello }');
+   * const location = document.loc?.toJSON();
+   *
+   * location; // => { start: 0, end: 9 }
+   * ```
+   */
 
@@ -68,21 +97,11 @@ toJSON() {
 class Token {
-  /**
-   * The kind of Token.
-   */
+  /** The kind of Token. */
 
-  /**
-   * The character offset at which this Node begins.
-   */
+  /** The character offset at which this Node begins. */
 
-  /**
-   * The character offset at which this Node ends.
-   */
+  /** The character offset at which this Node ends. */
 
-  /**
-   * The 1-indexed line number on which this Token appears.
-   */
+  /** The 1-indexed line number on which this Token appears. */
 
-  /**
-   * The 1-indexed column number at which this Token begins.
-   */
+  /** The 1-indexed column number at which this Token begins. */
 
@@ -101,2 +120,24 @@ /**
    */
+
+  /** Next token in the token stream, including ignored tokens. */
+
+  /**
+   * Creates a Token instance.
+   * @param kind - Token kind produced by lexical analysis.
+   * @param start - Character offset where this token begins.
+   * @param end - Character offset where this token ends.
+   * @param line - One-indexed line number where this token begins.
+   * @param column - One-indexed column number where this token begins.
+   * @param value - Interpreted value for non-punctuation tokens.
+   * @example
+   * ```ts
+   * import { Token, TokenKind } from 'graphql/language';
+   *
+   * const token = new Token(TokenKind.NAME, 2, 7, 1, 3, 'hello');
+   *
+   * token.kind; // => TokenKind.NAME
+   * token.value; // => 'hello'
+   * token.toJSON(); // => { kind: 'Name', value: 'hello', line: 1, column: 3 }
+   * ```
+   */
   constructor(kind, start, end, line, column, value) {
@@ -113,2 +154,6 @@ this.kind = kind;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -118,2 +163,15 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns a JSON representation of this token.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance().toJSON();
+   *
+   * token; // => { kind: '{', value: undefined, line: 1, column: 1 }
+   * ```
+   */
 
@@ -129,11 +187,7 @@ toJSON() {
 }
-/**
- * The list of all possible AST node types.
- */
+/** The list of all possible AST node types. */
 
 exports.Token = Token;
 
-/**
- * @internal
- */
+/** @internal */
 const QueryDocumentKeys = {
@@ -235,5 +289,3 @@ Name: [],
 const kindValues = new Set(Object.keys(QueryDocumentKeys));
-/**
- * @internal
- */
+/** @internal */
 
@@ -245,4 +297,8 @@ function isNode(maybeNode) {
 }
-/** Name */
+/** An identifier in a GraphQL document. */
 
+/**
+ * The operation types supported by GraphQL executable definitions.
+ * @category Kinds
+ */
 var OperationTypeNode;
@@ -256,1 +312,2 @@ exports.OperationTypeNode = OperationTypeNode;
 })(OperationTypeNode || (exports.OperationTypeNode = OperationTypeNode = {}));
+/** A variable declaration in an operation or legacy fragment definition. */

language/ast.mjs

@@ -0,1 +1,3 @@
+/** @category AST */
+
 /**
@@ -6,20 +8,30 @@ * Contains a range of UTF-8 character offsets and token references that
 export class Location {
-  /**
-   * The character offset at which this Node begins.
-   */
+  /** The character offset at which this Node begins. */
 
-  /**
-   * The character offset at which this Node ends.
-   */
+  /** The character offset at which this Node ends. */
 
-  /**
-   * The Token at which this Node begins.
-   */
+  /** The Token at which this Node begins. */
 
-  /**
-   * The Token at which this Node ends.
-   */
+  /** The Token at which this Node ends. */
 
+  /** The Source document the AST represents. */
+
   /**
-   * The Source document the AST represents.
+   * Creates a Location instance.
+   * @param startToken - The start token.
+   * @param endToken - The end token.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Location, Source, Token, TokenKind } from 'graphql/language';
+   *
+   * const source = new Source('{ hello }');
+   * const startToken = new Token(TokenKind.BRACE_L, 0, 1, 1, 1);
+   * const endToken = new Token(TokenKind.BRACE_R, 8, 9, 1, 9);
+   * const location = new Location(startToken, endToken, source);
+   *
+   * location.start; // => 0
+   * location.end; // => 9
+   * location.source.body; // => '{ hello }'
+   * ```
    */
@@ -33,2 +45,6 @@ constructor(startToken, endToken, source) {
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -38,2 +54,15 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns a JSON representation of this location.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   *
+   * const document = parse('{ hello }');
+   * const location = document.loc?.toJSON();
+   *
+   * location; // => { start: 0, end: 9 }
+   * ```
+   */
 
@@ -53,21 +82,11 @@ toJSON() {
 export class Token {
-  /**
-   * The kind of Token.
-   */
+  /** The kind of Token. */
 
-  /**
-   * The character offset at which this Node begins.
-   */
+  /** The character offset at which this Node begins. */
 
-  /**
-   * The character offset at which this Node ends.
-   */
+  /** The character offset at which this Node ends. */
 
-  /**
-   * The 1-indexed line number on which this Token appears.
-   */
+  /** The 1-indexed line number on which this Token appears. */
 
-  /**
-   * The 1-indexed column number at which this Token begins.
-   */
+  /** The 1-indexed column number at which this Token begins. */
 
@@ -86,2 +105,24 @@ /**
    */
+
+  /** Next token in the token stream, including ignored tokens. */
+
+  /**
+   * Creates a Token instance.
+   * @param kind - Token kind produced by lexical analysis.
+   * @param start - Character offset where this token begins.
+   * @param end - Character offset where this token ends.
+   * @param line - One-indexed line number where this token begins.
+   * @param column - One-indexed column number where this token begins.
+   * @param value - Interpreted value for non-punctuation tokens.
+   * @example
+   * ```ts
+   * import { Token, TokenKind } from 'graphql/language';
+   *
+   * const token = new Token(TokenKind.NAME, 2, 7, 1, 3, 'hello');
+   *
+   * token.kind; // => TokenKind.NAME
+   * token.value; // => 'hello'
+   * token.toJSON(); // => { kind: 'Name', value: 'hello', line: 1, column: 3 }
+   * ```
+   */
   constructor(kind, start, end, line, column, value) {
@@ -98,2 +139,6 @@ this.kind = kind;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -103,2 +148,15 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns a JSON representation of this token.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance().toJSON();
+   *
+   * token; // => { kind: '{', value: undefined, line: 1, column: 1 }
+   * ```
+   */
 
@@ -114,9 +172,5 @@ toJSON() {
 }
-/**
- * The list of all possible AST node types.
- */
+/** The list of all possible AST node types. */
 
-/**
- * @internal
- */
+/** @internal */
 export const QueryDocumentKeys = {
@@ -217,5 +271,3 @@ Name: [],
 const kindValues = new Set(Object.keys(QueryDocumentKeys));
-/**
- * @internal
- */
+/** @internal */
 
@@ -227,4 +279,8 @@ export function isNode(maybeNode) {
 }
-/** Name */
+/** An identifier in a GraphQL document. */
 
+/**
+ * The operation types supported by GraphQL executable definitions.
+ * @category Kinds
+ */
 var OperationTypeNode;
@@ -239,1 +295,2 @@
 export { OperationTypeNode };
+/** A variable declaration in an operation or legacy fragment definition. */

language/blockString.d.ts

@@ -12,5 +12,3 @@ /**
 ): Array<string>;
-/**
- * @internal
- */
+/** @internal */
 export declare function isPrintableAsBlockString(value: string): boolean;
@@ -17,0 +15,0 @@ /**

language/blockString.js

@@ -72,5 +72,3 @@ 'use strict';
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -77,0 +75,0 @@ function isPrintableAsBlockString(value) {

language/blockString.mjs

@@ -60,5 +60,3 @@ import { isWhiteSpace } from './characterClasses.mjs';
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -65,0 +63,0 @@ export function isPrintableAsBlockString(value) {

language/directiveLocation.d.ts

@@ -1,26 +0,43 @@
-/**
- * The set of allowed directive location values.
- */
+/** @category Kinds */
+/** The set of allowed directive location values. */
 declare enum DirectiveLocation {
-  /** Request Definitions */
+  /** Directive location for query operations. */
   QUERY = 'QUERY',
+  /** Directive location for mutation operations. */
   MUTATION = 'MUTATION',
+  /** Directive location for subscription operations. */
   SUBSCRIPTION = 'SUBSCRIPTION',
+  /** Directive location for field selections. */
   FIELD = 'FIELD',
+  /** Directive location for fragment definitions. */
   FRAGMENT_DEFINITION = 'FRAGMENT_DEFINITION',
+  /** Directive location for fragment spreads. */
   FRAGMENT_SPREAD = 'FRAGMENT_SPREAD',
+  /** Directive location for inline fragments. */
   INLINE_FRAGMENT = 'INLINE_FRAGMENT',
+  /** Directive location for variable definitions. */
   VARIABLE_DEFINITION = 'VARIABLE_DEFINITION',
-  /** Type System Definitions */
+  /** Directive location for schema definitions and extensions. */
   SCHEMA = 'SCHEMA',
+  /** Directive location for scalar type definitions and extensions. */
   SCALAR = 'SCALAR',
+  /** Directive location for object type definitions and extensions. */
   OBJECT = 'OBJECT',
+  /** Directive location for field definitions. */
   FIELD_DEFINITION = 'FIELD_DEFINITION',
+  /** Directive location for argument definitions. */
   ARGUMENT_DEFINITION = 'ARGUMENT_DEFINITION',
+  /** Directive location for interface type definitions and extensions. */
   INTERFACE = 'INTERFACE',
+  /** Directive location for union type definitions and extensions. */
   UNION = 'UNION',
+  /** Directive location for enum type definitions and extensions. */
   ENUM = 'ENUM',
+  /** Directive location for enum value definitions. */
   ENUM_VALUE = 'ENUM_VALUE',
+  /** Directive location for input object type definitions and extensions. */
   INPUT_OBJECT = 'INPUT_OBJECT',
+  /** Directive location for input object field definitions. */
   INPUT_FIELD_DEFINITION = 'INPUT_FIELD_DEFINITION',
+  /** Directive location for directive definitions and extensions. */
   DIRECTIVE_DEFINITION = 'DIRECTIVE_DEFINITION',
@@ -30,6 +47,9 @@ }
 /**
- * The enum type representing the directive location values.
- *
- * @deprecated Please use `DirectiveLocation`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing directive location
+ * values. This alias will be removed in v17. In v17, `DirectiveLocation` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `DirectiveLocation` as both
+ * the runtime value and the type.
  */
 export declare type DirectiveLocationEnum = typeof DirectiveLocation;

language/directiveLocation.js

@@ -8,5 +8,5 @@ 'use strict';
 
-/**
- * The set of allowed directive location values.
- */
+/** @category Kinds */
+
+/** The set of allowed directive location values. */
 var DirectiveLocation;
@@ -38,5 +38,8 @@ exports.DirectiveLocation = DirectiveLocation;
 /**
- * The enum type representing the directive location values.
- *
- * @deprecated Please use `DirectiveLocation`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing directive location
+ * values. This alias will be removed in v17. In v17, `DirectiveLocation` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `DirectiveLocation` as both
+ * the runtime value and the type.
  */

language/directiveLocation.mjs

@@ -1,4 +0,4 @@
-/**
- * The set of allowed directive location values.
- */
+/** @category Kinds */
+
+/** The set of allowed directive location values. */
 var DirectiveLocation;
@@ -31,5 +31,8 @@
 /**
- * The enum type representing the directive location values.
- *
- * @deprecated Please use `DirectiveLocation`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing directive location
+ * values. This alias will be removed in v17. In v17, `DirectiveLocation` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `DirectiveLocation` as both
+ * the runtime value and the type.
  */

language/index.d.ts

@@ -0,1 +1,7 @@
+/**
+ * Parse, print, and visit GraphQL language source files and AST nodes.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { Source } from './source';
@@ -2,0 +8,0 @@ export { getLocation } from './location';

language/index.mjs

@@ -0,1 +1,7 @@
+/**
+ * Parse, print, and visit GraphQL language source files and AST nodes.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { Source } from './source.mjs';
@@ -2,0 +8,0 @@ export { getLocation } from './location.mjs';

language/kinds.d.ts

@@ -1,65 +0,101 @@
-/**
- * The set of allowed kind values for AST nodes.
- */
+/** @category Kinds */
+/** The set of allowed kind values for AST nodes. */
 declare enum Kind {
-  /** Name */
+  /** AST kind for name nodes. */
   NAME = 'Name',
-  /** Document */
+  /** AST kind for document nodes. */
   DOCUMENT = 'Document',
+  /** AST kind for operation definition nodes. */
   OPERATION_DEFINITION = 'OperationDefinition',
+  /** AST kind for variable definition nodes. */
   VARIABLE_DEFINITION = 'VariableDefinition',
+  /** AST kind for selection set nodes. */
   SELECTION_SET = 'SelectionSet',
+  /** AST kind for field selection nodes. */
   FIELD = 'Field',
+  /** AST kind for argument nodes. */
   ARGUMENT = 'Argument',
-  /** Fragments */
+  /** AST kind for fragment spread nodes. */
   FRAGMENT_SPREAD = 'FragmentSpread',
+  /** AST kind for inline fragment nodes. */
   INLINE_FRAGMENT = 'InlineFragment',
+  /** AST kind for fragment definition nodes. */
   FRAGMENT_DEFINITION = 'FragmentDefinition',
-  /** Values */
+  /** AST kind for variable reference nodes. */
   VARIABLE = 'Variable',
+  /** AST kind for integer value nodes. */
   INT = 'IntValue',
+  /** AST kind for floating-point value nodes. */
   FLOAT = 'FloatValue',
+  /** AST kind for string value nodes. */
   STRING = 'StringValue',
+  /** AST kind for boolean value nodes. */
   BOOLEAN = 'BooleanValue',
+  /** AST kind for null value nodes. */
   NULL = 'NullValue',
+  /** AST kind for enum value nodes. */
   ENUM = 'EnumValue',
+  /** AST kind for list value nodes. */
   LIST = 'ListValue',
+  /** AST kind for object value nodes. */
   OBJECT = 'ObjectValue',
+  /** AST kind for object field nodes. */
   OBJECT_FIELD = 'ObjectField',
-  /** Directives */
+  /** AST kind for directive nodes. */
   DIRECTIVE = 'Directive',
-  /** Types */
+  /** AST kind for named type reference nodes. */
   NAMED_TYPE = 'NamedType',
+  /** AST kind for list type reference nodes. */
   LIST_TYPE = 'ListType',
+  /** AST kind for non-null type reference nodes. */
   NON_NULL_TYPE = 'NonNullType',
-  /** Type System Definitions */
+  /** AST kind for schema definition nodes. */
   SCHEMA_DEFINITION = 'SchemaDefinition',
+  /** AST kind for operation type definition nodes. */
   OPERATION_TYPE_DEFINITION = 'OperationTypeDefinition',
-  /** Type Definitions */
+  /** AST kind for scalar type definition nodes. */
   SCALAR_TYPE_DEFINITION = 'ScalarTypeDefinition',
+  /** AST kind for object type definition nodes. */
   OBJECT_TYPE_DEFINITION = 'ObjectTypeDefinition',
+  /** AST kind for field definition nodes. */
   FIELD_DEFINITION = 'FieldDefinition',
+  /** AST kind for input value definition nodes. */
   INPUT_VALUE_DEFINITION = 'InputValueDefinition',
+  /** AST kind for interface type definition nodes. */
   INTERFACE_TYPE_DEFINITION = 'InterfaceTypeDefinition',
+  /** AST kind for union type definition nodes. */
   UNION_TYPE_DEFINITION = 'UnionTypeDefinition',
+  /** AST kind for enum type definition nodes. */
   ENUM_TYPE_DEFINITION = 'EnumTypeDefinition',
+  /** AST kind for enum value definition nodes. */
   ENUM_VALUE_DEFINITION = 'EnumValueDefinition',
+  /** AST kind for input object type definition nodes. */
   INPUT_OBJECT_TYPE_DEFINITION = 'InputObjectTypeDefinition',
-  /** Directive Definitions */
+  /** AST kind for directive definition nodes. */
   DIRECTIVE_DEFINITION = 'DirectiveDefinition',
-  /** Type System Extensions */
+  /** AST kind for schema extension nodes. */
   SCHEMA_EXTENSION = 'SchemaExtension',
+  /** AST kind for directive extension nodes. */
   DIRECTIVE_EXTENSION = 'DirectiveExtension',
-  /** Type Extensions */
+  /** AST kind for scalar type extension nodes. */
   SCALAR_TYPE_EXTENSION = 'ScalarTypeExtension',
+  /** AST kind for object type extension nodes. */
   OBJECT_TYPE_EXTENSION = 'ObjectTypeExtension',
+  /** AST kind for interface type extension nodes. */
   INTERFACE_TYPE_EXTENSION = 'InterfaceTypeExtension',
+  /** AST kind for union type extension nodes. */
   UNION_TYPE_EXTENSION = 'UnionTypeExtension',
+  /** AST kind for enum type extension nodes. */
   ENUM_TYPE_EXTENSION = 'EnumTypeExtension',
+  /** AST kind for input object type extension nodes. */
   INPUT_OBJECT_TYPE_EXTENSION = 'InputObjectTypeExtension',
-  /** Schema Coordinates */
+  /** AST kind for type coordinate nodes. */
   TYPE_COORDINATE = 'TypeCoordinate',
+  /** AST kind for member coordinate nodes. */
   MEMBER_COORDINATE = 'MemberCoordinate',
+  /** AST kind for argument coordinate nodes. */
   ARGUMENT_COORDINATE = 'ArgumentCoordinate',
+  /** AST kind for directive coordinate nodes. */
   DIRECTIVE_COORDINATE = 'DirectiveCoordinate',
+  /** AST kind for directive argument coordinate nodes. */
   DIRECTIVE_ARGUMENT_COORDINATE = 'DirectiveArgumentCoordinate',
@@ -69,6 +105,9 @@ }
 /**
- * The enum type representing the possible kind values of AST nodes.
- *
- * @deprecated Please use `Kind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing the possible kind
+ * values of AST nodes. This alias will be removed in v17. In v17, `Kind` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `Kind` as both the runtime
+ * value and the type.
  */
 export declare type KindEnum = typeof Kind;

language/kinds.js

@@ -8,5 +8,5 @@ 'use strict';
 
-/**
- * The set of allowed kind values for AST nodes.
- */
+/** @category Kinds */
+
+/** The set of allowed kind values for AST nodes. */
 var Kind;
@@ -67,5 +67,8 @@ exports.Kind = Kind;
 /**
- * The enum type representing the possible kind values of AST nodes.
- *
- * @deprecated Please use `Kind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing the possible kind
+ * values of AST nodes. This alias will be removed in v17. In v17, `Kind` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `Kind` as both the runtime
+ * value and the type.
  */

language/kinds.mjs

@@ -1,4 +0,4 @@
-/**
- * The set of allowed kind values for AST nodes.
- */
+/** @category Kinds */
+
+/** The set of allowed kind values for AST nodes. */
 var Kind;
@@ -60,5 +60,8 @@
 /**
- * The enum type representing the possible kind values of AST nodes.
- *
- * @deprecated Please use `Kind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing the possible kind
+ * values of AST nodes. This alias will be removed in v17. In v17, `Kind` is
+ * exported as the single public symbol for both the runtime object and the
+ * corresponding TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `Kind` as both the runtime
+ * value and the type.
  */

language/lexer.d.ts

@@ -0,1 +1,2 @@
+/** @category Lexing */
 import { Token } from './ast';
@@ -28,23 +29,46 @@ import type { Source } from './source';
 export declare class Lexer implements LexerInterface {
+  /** Source document used to derive error locations. */
   source: Source;
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** Most recent non-ignored token returned by the lexer. */
   lastToken: Token;
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** Current non-ignored token at the lexer cursor. */
   token: Token;
+  /** The (1-indexed) line containing the current token. */
+  line: number;
+  /** Character offset where the current line starts. */
+  lineStart: number;
   /**
-   * The (1-indexed) line containing the current token.
+   * Creates a Lexer instance.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Lexer, Source, TokenKind } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   *
+   * lexer.token.kind; // => TokenKind.SOF
+   * lexer.advance().kind; // => TokenKind.BRACE_L
+   * lexer.advance().value; // => 'hello'
+   * lexer.advance().kind; // => TokenKind.BRACE_R
+   * ```
    */
-  line: number;
+  constructor(source: Source);
   /**
-   * The character offset at which the current line begins.
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
    */
-  lineStart: number;
-  constructor(source: Source);
   get [Symbol.toStringTag](): string;
   /**
    * Advances the token stream to the next non-ignored token.
+   * @returns The next non-ignored token.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance();
+   *
+   * token.kind; // => '{'
+   * lexer.token; // => token
+   * ```
    */
@@ -55,8 +79,17 @@ advance(): Token;
    * the state of Lexer.
+   * @returns The next non-ignored token without advancing the lexer.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.lookahead();
+   *
+   * token.kind; // => '{'
+   * lexer.token.kind; // => '<SOF>'
+   * ```
    */
   lookahead(): Token;
 }
-/**
- * @internal
- */
+/** @internal */
 export declare function isPunctuatorTokenKind(kind: TokenKind): boolean;
@@ -63,0 +96,0 @@ /**

language/lexer.js

@@ -22,2 +22,4 @@ 'use strict';
 
+/** @category Lexing */
+
 /**
@@ -32,16 +34,26 @@ * Given a Source object, creates a Lexer for that source.
 class Lexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** Source document used to derive error locations. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** Most recent non-ignored token returned by the lexer. */
 
-  /**
-   * The (1-indexed) line containing the current token.
-   */
+  /** Current non-ignored token at the lexer cursor. */
 
+  /** The (1-indexed) line containing the current token. */
+
+  /** Character offset where the current line starts. */
+
   /**
-   * The character offset at which the current line begins.
+   * Creates a Lexer instance.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Lexer, Source, TokenKind } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   *
+   * lexer.token.kind; // => TokenKind.SOF
+   * lexer.advance().kind; // => TokenKind.BRACE_L
+   * lexer.advance().value; // => 'hello'
+   * lexer.advance().kind; // => TokenKind.BRACE_R
+   * ```
    */
@@ -62,2 +74,6 @@ constructor(source) {
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -69,2 +85,13 @@ get [Symbol.toStringTag]() {
    * Advances the token stream to the next non-ignored token.
+   * @returns The next non-ignored token.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance();
+   *
+   * token.kind; // => '{'
+   * lexer.token; // => token
+   * ```
    */
@@ -80,2 +107,13 @@
    * the state of Lexer.
+   * @returns The next non-ignored token without advancing the lexer.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.lookahead();
+   *
+   * token.kind; // => '{'
+   * lexer.token.kind; // => '<SOF>'
+   * ```
    */
@@ -105,5 +143,3 @@
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -138,2 +174,4 @@ exports.Lexer = Lexer;
  *   - "Any Unicode scalar value"
+ *
+ * @internal
  */
@@ -153,2 +191,4 @@
  * code points are not valid source characters.
+ *
+ * @internal
  */
@@ -210,2 +250,4 @@
  * complicated tokens.
+ *
+ * @internal
  */
@@ -458,2 +500,4 @@
  * ```
+ *
+ * @internal
  */
@@ -518,2 +562,4 @@
  * ```
+ *
+ * @internal
  */
@@ -589,2 +635,4 @@
  * Returns the new position in the source after reading one or more digits.
+ *
+ * @internal
  */
@@ -632,2 +680,4 @@
  * ```
+ *
+ * @internal
  */
@@ -781,2 +831,4 @@
  * Returns a negative number if any char was not a valid hexadecimal digit.
+ *
+ * @internal
  */
@@ -807,2 +859,4 @@
  *   - `a` `b` `c` `d` `e` `f`
+ *
+ * @internal
  */
@@ -830,2 +884,4 @@
  * | `t`               | U+0009     | horizontal tab               |
+ *
+ * @internal
  */
@@ -915,2 +971,4 @@
  * ```
+ *
+ * @internal
  */
@@ -917,0 +975,0 @@

language/lexer.mjs

@@ -0,1 +1,2 @@
+/** @category Lexing */
 import { syntaxError } from '../error/syntaxError.mjs';
@@ -22,16 +23,26 @@ import { Token } from './ast.mjs';
 export class Lexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** Source document used to derive error locations. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** Most recent non-ignored token returned by the lexer. */
 
-  /**
-   * The (1-indexed) line containing the current token.
-   */
+  /** Current non-ignored token at the lexer cursor. */
 
+  /** The (1-indexed) line containing the current token. */
+
+  /** Character offset where the current line starts. */
+
   /**
-   * The character offset at which the current line begins.
+   * Creates a Lexer instance.
+   * @param source - Source document used to derive error locations.
+   * @example
+   * ```ts
+   * import { Lexer, Source, TokenKind } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   *
+   * lexer.token.kind; // => TokenKind.SOF
+   * lexer.advance().kind; // => TokenKind.BRACE_L
+   * lexer.advance().value; // => 'hello'
+   * lexer.advance().kind; // => TokenKind.BRACE_R
+   * ```
    */
@@ -46,2 +57,6 @@ constructor(source) {
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -53,2 +68,13 @@ get [Symbol.toStringTag]() {
    * Advances the token stream to the next non-ignored token.
+   * @returns The next non-ignored token.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.advance();
+   *
+   * token.kind; // => '{'
+   * lexer.token; // => token
+   * ```
    */
@@ -64,2 +90,13 @@
    * the state of Lexer.
+   * @returns The next non-ignored token without advancing the lexer.
+   * @example
+   * ```ts
+   * import { Lexer, Source } from 'graphql/language';
+   *
+   * const lexer = new Lexer(new Source('{ hello }'));
+   * const token = lexer.lookahead();
+   *
+   * token.kind; // => '{'
+   * lexer.token.kind; // => '<SOF>'
+   * ```
    */
@@ -89,5 +126,3 @@
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -120,2 +155,4 @@ export function isPunctuatorTokenKind(kind) {
  *   - "Any Unicode scalar value"
+ *
+ * @internal
  */
@@ -135,2 +172,4 @@
  * code points are not valid source characters.
+ *
+ * @internal
  */
@@ -192,2 +231,4 @@
  * complicated tokens.
+ *
+ * @internal
  */
@@ -370,2 +411,4 @@
  * ```
+ *
+ * @internal
  */
@@ -430,2 +473,4 @@
  * ```
+ *
+ * @internal
  */
@@ -501,2 +546,4 @@
  * Returns the new position in the source after reading one or more digits.
+ *
+ * @internal
  */
@@ -544,2 +591,4 @@
  * ```
+ *
+ * @internal
  */
@@ -683,2 +732,4 @@
  * Returns a negative number if any char was not a valid hexadecimal digit.
+ *
+ * @internal
  */
@@ -709,2 +760,4 @@
  *   - `a` `b` `c` `d` `e` `f`
+ *
+ * @internal
  */
@@ -732,2 +785,4 @@
  * | `t`               | U+0009     | horizontal tab               |
+ *
+ * @internal
  */
@@ -817,2 +872,4 @@
  * ```
+ *
+ * @internal
  */
@@ -819,0 +876,0 @@

language/location.d.ts

@@ -0,7 +1,8 @@
+/** @category Source */
 import type { Source } from './source';
-/**
- * Represents a location in a Source.
- */
+/** Represents a location in a Source. */
 export interface SourceLocation {
+  /** One-indexed line number in the source document. */
   readonly line: number;
+  /** One-indexed column number in the source document. */
   readonly column: number;
@@ -12,2 +13,14 @@ }
  * line and column as a SourceLocation.
+ * @param source - The source document that contains the position.
+ * @param position - The UTF-8 character offset in the source body.
+ * @returns The 1-indexed line and column for the given source position.
+ * @example
+ * ```ts
+ * import { Source, getLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const location = getLocation(source, 13);
+ *
+ * location; // => { line: 1, column: 14 }
+ * ```
  */
@@ -14,0 +27,0 @@ export declare function getLocation(

language/location.js

@@ -10,6 +10,5 @@ 'use strict';
 
+/** @category Source */
 const LineRegExp = /\r\n|[\n\r]/g;
-/**
- * Represents a location in a Source.
- */
+/** Represents a location in a Source. */
 
@@ -19,2 +18,14 @@ /**
  * line and column as a SourceLocation.
+ * @param source - The source document that contains the position.
+ * @param position - The UTF-8 character offset in the source body.
+ * @returns The 1-indexed line and column for the given source position.
+ * @example
+ * ```ts
+ * import { Source, getLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const location = getLocation(source, 13);
+ *
+ * location; // => { line: 1, column: 14 }
+ * ```
  */
@@ -21,0 +32,0 @@ function getLocation(source, position) {

language/location.mjs

@@ -0,6 +1,5 @@
+/** @category Source */
 import { invariant } from '../jsutils/invariant.mjs';
 const LineRegExp = /\r\n|[\n\r]/g;
-/**
- * Represents a location in a Source.
- */
+/** Represents a location in a Source. */
 
@@ -10,2 +9,14 @@ /**
  * line and column as a SourceLocation.
+ * @param source - The source document that contains the position.
+ * @param position - The UTF-8 character offset in the source body.
+ * @returns The 1-indexed line and column for the given source position.
+ * @example
+ * ```ts
+ * import { Source, getLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const location = getLocation(source, 13);
+ *
+ * location; // => { line: 1, column: 14 }
+ * ```
  */
@@ -12,0 +23,0 @@ export function getLocation(source, position) {

language/parser.d.ts

@@ -0,1 +1,2 @@
+/** @category Parsing */
 import type { Maybe } from '../jsutils/Maybe';
@@ -59,5 +60,3 @@ import type { GraphQLError } from '../error/GraphQLError';
 import { TokenKind } from './tokenKind';
-/**
- * Configuration options to control parser behavior
- */
+/** Configuration options to control parser behavior */
 export interface ParseOptions {
@@ -79,10 +78,10 @@ /**
   /**
-   * @deprecated will be removed in the v17.0.0
+   * Deprecated option that allows legacy fragment variable definitions to be
+   * parsed. This legacy fragment variable syntax will be removed in v17. Move
+   * variable definitions to operations for spec-compliant documents; if you
+   * need variables or arguments scoped to fragments, v17 has a more complete
+   * experimental fragment-arguments feature.
+   * @example
+   * The syntax is identical to normal, query-defined variables.
    *
-   * If enabled, the parser will understand and parse variable definitions
-   * contained in a fragment definition. They'll be represented in the
-   * `variableDefinitions` field of the FragmentDefinitionNode.
-   *
-   * The syntax is identical to normal, query-defined variables. For example:
-   *
    * ```graphql
@@ -93,2 +92,7 @@ * fragment A($var: Boolean = false) on T {
    * ```
+   * @deprecated will be removed in the v17.0.0
+   *
+   * If enabled, the parser will understand and parse variable definitions
+   * contained in a fragment definition. They'll be represented in the
+   * `variableDefinitions` field of the FragmentDefinitionNode.
    */
@@ -101,3 +105,3 @@ allowLegacyFragmentVariables?: boolean;
    * This syntax is not part of the GraphQL specification and may change.
-   *
+   * @example
    * ```graphql
@@ -109,4 +113,5 @@ * directive @foo @bar on FIELD
   /**
-   * You may override the Lexer class used to lex the source; this is used by
-   * schema coordinates to introduce a lexer with a restricted syntax.
+   * Internal parser hook for GraphQL.js entry points that need to parse a
+   * restricted grammar with an alternate lexer.
+   * @internal
    */
@@ -118,2 +123,35 @@ lexer?: LexerInterface | undefined;
  * Throws GraphQLError if a syntax error is encountered.
+ * @param source - A GraphQL source string or source object.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL document AST.
+ * @example
+ * ```ts
+ * // Parse a GraphQL document with the default parser options.
+ * import { parse } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ *
+ * document.kind; // => 'Document'
+ * ```
+ * @example
+ * ```ts
+ * // This variant enables parser options and provides an explicit lexer.
+ * import { Lexer, Source, parse } from 'graphql/language';
+ *
+ * const document = parse('fragment A($var: Boolean) on Query { field }', {
+ *   allowLegacyFragmentVariables: true,
+ *   maxTokens: 20,
+ *   noLocation: true,
+ * });
+ * const directiveDocument = parse('directive @foo @bar on FIELD', {
+ *   experimentalDirectivesOnDirectiveDefinitions: true,
+ * });
+ * const source = new Source('{ hero }');
+ * const lexerDocument = parse(source, { lexer: new Lexer(source) });
+ *
+ * document.definitions[0].kind; // => 'FragmentDefinition'
+ * document.loc; // => undefined
+ * directiveDocument.definitions[0].kind; // => 'DirectiveDefinition'
+ * lexerDocument.definitions[0].kind; // => 'OperationDefinition'
+ * ```
  */
@@ -133,2 +171,13 @@ export declare function parse(
  * Consider providing the results to the utility function: valueFromAST().
+ * @param source - A GraphQL source string or source object containing a value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ *
+ * const value = parseValue('[42]');
+ *
+ * value.kind; // => 'ListValue'
+ * ```
  */
@@ -142,2 +191,14 @@ export declare function parseValue(
  * variable. The return type will be a constant value.
+ * @param source - A GraphQL source string or source object containing a constant value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL constant value AST.
+ * @example
+ * ```ts
+ * import { parseConstValue } from 'graphql/language';
+ *
+ * const value = parseConstValue('{ enabled: true }');
+ *
+ * value.kind; // => 'ObjectValue'
+ * parseConstValue('$variable'); // throws an error
+ * ```
  */
@@ -157,2 +218,13 @@ export declare function parseConstValue(
  * Consider providing the results to the utility function: typeFromAST().
+ * @param source - A GraphQL source string or source object containing a type reference.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL type AST.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ *
+ * const type = parseType('[String!]');
+ *
+ * type.kind; // => 'ListType'
+ * ```
  */
@@ -171,2 +243,12 @@ export declare function parseType(
  * with an unparsed source.
+ * @param source - A GraphQL source string or source object containing a schema coordinate.
+ * @returns The parsed GraphQL schema coordinate AST.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ *
+ * const coordinate = parseSchemaCoordinate('Query.hero');
+ *
+ * coordinate.kind; // => 'MemberCoordinate'
+ * ```
  */
@@ -195,2 +277,4 @@ export declare function parseSchemaCoordinate(
    * Converts a name lex token into a name parse node.
+   *
+   * @internal
    */
@@ -200,2 +284,4 @@ parseName(): NameNode;
    * Document : Definition+
+   *
+   * @internal
    */
@@ -225,2 +311,4 @@ parseDocument(): DocumentNode;
    *   - InputObjectTypeDefinition
+   *
+   * @internal
    */
@@ -232,2 +320,4 @@ parseDefinition(): DefinitionNode;
    *  - OperationType Name? VariableDefinitions? Directives? SelectionSet
+   *
+   * @internal
    */
@@ -237,2 +327,4 @@ parseOperationDefinition(): OperationDefinitionNode;
    * OperationType : one of query mutation subscription
+   *
+   * @internal
    */
@@ -242,2 +334,4 @@ parseOperationType(): OperationTypeNode;
    * VariableDefinitions : ( VariableDefinition+ )
+   *
+   * @internal
    */
@@ -247,2 +341,4 @@ parseVariableDefinitions(): Array<VariableDefinitionNode>;
    * VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
@@ -252,2 +348,4 @@ parseVariableDefinition(): VariableDefinitionNode;
    * Variable : $ Name
+   *
+   * @internal
    */
@@ -259,2 +357,4 @@ parseVariable(): VariableNode;
    * ```
+   *
+   * @internal
    */
@@ -267,2 +367,4 @@ parseSelectionSet(): SelectionSetNode;
    *   - InlineFragment
+   *
+   * @internal
    */
@@ -274,2 +376,4 @@ parseSelection(): SelectionNode;
    * Alias : Name :
+   *
+   * @internal
    */
@@ -279,2 +383,4 @@ parseField(): FieldNode;
    * Arguments[Const] : ( Argument[?Const]+ )
+   *
+   * @internal
    */
@@ -285,2 +391,4 @@ parseArguments(isConst: true): Array<ConstArgumentNode>;
    * Argument[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
@@ -296,2 +404,4 @@ parseArgument(isConst: true): ConstArgumentNode;
    * InlineFragment : ... TypeCondition? Directives? SelectionSet
+   *
+   * @internal
    */
@@ -304,2 +414,4 @@ parseFragment(): FragmentSpreadNode | InlineFragmentNode;
    * TypeCondition : NamedType
+   *
+   * @internal
    */
@@ -309,2 +421,4 @@ parseFragmentDefinition(): FragmentDefinitionNode;
    * FragmentName : Name but not `on`
+   *
+   * @internal
    */
@@ -329,2 +443,4 @@ parseFragmentName(): NameNode;
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
@@ -339,2 +455,4 @@ parseValueLiteral(isConst: true): ConstValueNode;
    *   - [ Value[?Const]+ ]
+   *
+   * @internal
    */
@@ -349,2 +467,4 @@ parseList(isConst: true): ConstListValueNode;
    * ```
+   *
+   * @internal
    */
@@ -355,2 +475,4 @@ parseObject(isConst: true): ConstObjectValueNode;
    * ObjectField[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
@@ -361,2 +483,4 @@ parseObjectField(isConst: true): ConstObjectFieldNode;
    * Directives[Const] : Directive[?Const]+
+   *
+   * @internal
    */
@@ -370,2 +494,4 @@ parseDirectives(isConst: true): Array<ConstDirectiveNode>;
    * ```
+   *
+   * @internal
    */
@@ -379,2 +505,4 @@ parseDirective(isConst: true): ConstDirectiveNode;
    *   - NonNullType
+   *
+   * @internal
    */
@@ -384,2 +512,4 @@ parseTypeReference(): TypeNode;
    * NamedType : Name
+   *
+   * @internal
    */
@@ -390,2 +520,4 @@ parseNamedType(): NamedTypeNode;
    * Description : StringValue
+   *
+   * @internal
    */
@@ -397,2 +529,4 @@ parseDescription(): undefined | StringValueNode;
    * ```
+   *
+   * @internal
    */
@@ -402,2 +536,4 @@ parseSchemaDefinition(): SchemaDefinitionNode;
    * OperationTypeDefinition : OperationType : NamedType
+   *
+   * @internal
    */
@@ -407,2 +543,4 @@ parseOperationTypeDefinition(): OperationTypeDefinitionNode;
    * ScalarTypeDefinition : Description? scalar Name Directives[Const]?
+   *
+   * @internal
    */
@@ -414,2 +552,4 @@ parseScalarTypeDefinition(): ScalarTypeDefinitionNode;
    *   type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
@@ -421,2 +561,4 @@ parseObjectTypeDefinition(): ObjectTypeDefinitionNode;
    *   - ImplementsInterfaces & NamedType
+   *
+   * @internal
    */
@@ -428,2 +570,4 @@ parseImplementsInterfaces(): Array<NamedTypeNode>;
    * ```
+   *
+   * @internal
    */
@@ -434,2 +578,4 @@ parseFieldsDefinition(): Array<FieldDefinitionNode>;
    *   - Description? Name ArgumentsDefinition? : Type Directives[Const]?
+   *
+   * @internal
    */
@@ -439,2 +585,4 @@ parseFieldDefinition(): FieldDefinitionNode;
    * ArgumentsDefinition : ( InputValueDefinition+ )
+   *
+   * @internal
    */
@@ -445,2 +593,4 @@ parseArgumentDefs(): Array<InputValueDefinitionNode>;
    *   - Description? Name : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
@@ -451,2 +601,4 @@ parseInputValueDef(): InputValueDefinitionNode;
    *   - Description? interface Name Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
@@ -457,2 +609,4 @@ parseInterfaceTypeDefinition(): InterfaceTypeDefinitionNode;
    *   - Description? union Name Directives[Const]? UnionMemberTypes?
+   *
+   * @internal
    */
@@ -464,2 +618,4 @@ parseUnionTypeDefinition(): UnionTypeDefinitionNode;
    *   - UnionMemberTypes | NamedType
+   *
+   * @internal
    */
@@ -470,2 +626,4 @@ parseUnionMemberTypes(): Array<NamedTypeNode>;
    *   - Description? enum Name Directives[Const]? EnumValuesDefinition?
+   *
+   * @internal
    */
@@ -477,2 +635,4 @@ parseEnumTypeDefinition(): EnumTypeDefinitionNode;
    * ```
+   *
+   * @internal
    */
@@ -482,2 +642,4 @@ parseEnumValuesDefinition(): Array<EnumValueDefinitionNode>;
    * EnumValueDefinition : Description? EnumValue Directives[Const]?
+   *
+   * @internal
    */
@@ -487,2 +649,4 @@ parseEnumValueDefinition(): EnumValueDefinitionNode;
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
@@ -493,2 +657,4 @@ parseEnumValueName(): NameNode;
    *   - Description? input Name Directives[Const]? InputFieldsDefinition?
+   *
+   * @internal
    */
@@ -500,2 +666,4 @@ parseInputObjectTypeDefinition(): InputObjectTypeDefinitionNode;
    * ```
+   *
+   * @internal
    */
@@ -516,2 +684,4 @@ parseInputFieldsDefinition(): Array<InputValueDefinitionNode>;
    *   - DirectiveDefinitionExtension
+   *
+   * @internal
    */
@@ -525,2 +695,4 @@ parseTypeSystemExtension(): TypeSystemExtensionNode;
    * ```
+   *
+   * @internal
    */
@@ -531,2 +703,4 @@ parseSchemaExtension(): SchemaExtensionNode;
    *   - extend scalar Name Directives[Const]
+   *
+   * @internal
    */
@@ -539,2 +713,4 @@ parseScalarTypeExtension(): ScalarTypeExtensionNode;
    *  - extend type Name ImplementsInterfaces
+   *
+   * @internal
    */
@@ -547,2 +723,4 @@ parseObjectTypeExtension(): ObjectTypeExtensionNode;
    *  - extend interface Name ImplementsInterfaces
+   *
+   * @internal
    */
@@ -554,2 +732,4 @@ parseInterfaceTypeExtension(): InterfaceTypeExtensionNode;
    *   - extend union Name Directives[Const]
+   *
+   * @internal
    */
@@ -561,2 +741,4 @@ parseUnionTypeExtension(): UnionTypeExtensionNode;
    *   - extend enum Name Directives[Const]
+   *
+   * @internal
    */
@@ -568,2 +750,4 @@ parseEnumTypeExtension(): EnumTypeExtensionNode;
    *   - extend input Name Directives[Const]
+   *
+   * @internal
    */
@@ -577,2 +761,4 @@ parseInputObjectTypeExtension(): InputObjectTypeExtensionNode;
    * ```
+   *
+   * @internal
    */
@@ -584,2 +770,4 @@ parseDirectiveDefinition(): DirectiveDefinitionNode;
    *   - DirectiveLocations | DirectiveLocation
+   *
+   * @internal
    */
@@ -595,2 +783,15 @@ parseDirectiveLocations(): Array<NameNode>;
    *   - \@ Name ( Name : )
+   * @returns Parsed schema coordinate AST.
+   * @example
+   * ```ts
+   * import { Parser, Source } from 'graphql/language';
+   *
+   * const typeCoordinate = new Parser(new Source('User.name')).parseSchemaCoordinate();
+   * const directiveCoordinate = new Parser(new Source('@include(if:)')).parseSchemaCoordinate();
+   *
+   * typeCoordinate.name.value; // => 'User'
+   * typeCoordinate.memberName?.value; // => 'name'
+   * directiveCoordinate.name.value; // => 'deprecated'
+   * directiveCoordinate.argumentName?.value; // => 'reason'
+   * ```
    */
@@ -602,2 +803,4 @@ parseSchemaCoordinate(): SchemaCoordinateNode;
    * given parsed object.
+   *
+   * @internal
    */
@@ -611,2 +814,4 @@ node<
    * Determines if the next token is of a given kind
+   *
+   * @internal
    */
@@ -617,2 +822,4 @@ peek(kind: TokenKind): boolean;
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
@@ -623,2 +830,4 @@ expectToken(kind: TokenKind): Token;
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
@@ -629,2 +838,4 @@ expectOptionalToken(kind: TokenKind): boolean;
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
@@ -635,2 +846,4 @@ expectKeyword(value: string): void;
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
@@ -640,2 +853,4 @@ expectOptionalKeyword(value: string): boolean;
    * Helper function for creating an error when an unexpected lexed token is encountered.
+   *
+   * @internal
    */
@@ -647,2 +862,4 @@ unexpected(atToken?: Maybe<Token>): GraphQLError;
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -655,2 +872,4 @@ any<T>(openKind: TokenKind, parseFn: () => T, closeKind: TokenKind): Array<T>;
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -666,2 +885,4 @@ optionalMany<T>(
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -677,2 +898,4 @@ many<T>(
    * Advances the parser to the next lex token after last item in the list.
+   *
+   * @internal
    */
@@ -679,0 +902,0 @@ delimitedMany<T>(delimiterKind: TokenKind, parseFn: () => T): Array<T>;

language/parser.js

@@ -29,5 +29,40 @@ 'use strict';
 
+/** @category Parsing */
+
 /**
  * Given a GraphQL source, parses it into a Document.
  * Throws GraphQLError if a syntax error is encountered.
+ * @param source - A GraphQL source string or source object.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL document AST.
+ * @example
+ * ```ts
+ * // Parse a GraphQL document with the default parser options.
+ * import { parse } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ *
+ * document.kind; // => 'Document'
+ * ```
+ * @example
+ * ```ts
+ * // This variant enables parser options and provides an explicit lexer.
+ * import { Lexer, Source, parse } from 'graphql/language';
+ *
+ * const document = parse('fragment A($var: Boolean) on Query { field }', {
+ *   allowLegacyFragmentVariables: true,
+ *   maxTokens: 20,
+ *   noLocation: true,
+ * });
+ * const directiveDocument = parse('directive @foo @bar on FIELD', {
+ *   experimentalDirectivesOnDirectiveDefinitions: true,
+ * });
+ * const source = new Source('{ hero }');
+ * const lexerDocument = parse(source, { lexer: new Lexer(source) });
+ *
+ * document.definitions[0].kind; // => 'FragmentDefinition'
+ * document.loc; // => undefined
+ * directiveDocument.definitions[0].kind; // => 'DirectiveDefinition'
+ * lexerDocument.definitions[0].kind; // => 'OperationDefinition'
+ * ```
  */
@@ -52,2 +87,13 @@ function parse(source, options) {
  * Consider providing the results to the utility function: valueFromAST().
+ * @param source - A GraphQL source string or source object containing a value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ *
+ * const value = parseValue('[42]');
+ *
+ * value.kind; // => 'ListValue'
+ * ```
  */
@@ -65,2 +111,14 @@
  * variable. The return type will be a constant value.
+ * @param source - A GraphQL source string or source object containing a constant value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL constant value AST.
+ * @example
+ * ```ts
+ * import { parseConstValue } from 'graphql/language';
+ *
+ * const value = parseConstValue('{ enabled: true }');
+ *
+ * value.kind; // => 'ObjectValue'
+ * parseConstValue('$variable'); // throws an error
+ * ```
  */
@@ -84,2 +142,13 @@
  * Consider providing the results to the utility function: typeFromAST().
+ * @param source - A GraphQL source string or source object containing a type reference.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL type AST.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ *
+ * const type = parseType('[String!]');
+ *
+ * type.kind; // => 'ListType'
+ * ```
  */
@@ -102,2 +171,12 @@
  * with an unparsed source.
+ * @param source - A GraphQL source string or source object containing a schema coordinate.
+ * @returns The parsed GraphQL schema coordinate AST.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ *
+ * const coordinate = parseSchemaCoordinate('Query.hero');
+ *
+ * coordinate.kind; // => 'MemberCoordinate'
+ * ```
  */
@@ -152,2 +231,4 @@
    * Converts a name lex token into a name parse node.
+   *
+   * @internal
    */
@@ -165,2 +246,4 @@
    * Document : Definition+
+   *
+   * @internal
    */
@@ -200,2 +283,4 @@
    *   - InputObjectTypeDefinition
+   *
+   * @internal
    */
@@ -279,2 +364,4 @@
    *  - OperationType Name? VariableDefinitions? Directives? SelectionSet
+   *
+   * @internal
    */
@@ -317,2 +404,4 @@
    * OperationType : one of query mutation subscription
+   *
+   * @internal
    */
@@ -338,2 +427,4 @@
    * VariableDefinitions : ( VariableDefinition+ )
+   *
+   * @internal
    */
@@ -350,2 +441,4 @@
    * VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
@@ -369,2 +462,4 @@
    * Variable : $ Name
+   *
+   * @internal
    */
@@ -384,2 +479,4 @@
    * ```
+   *
+   * @internal
    */
@@ -402,2 +499,4 @@
    *   - InlineFragment
+   *
+   * @internal
    */
@@ -414,2 +513,4 @@
    * Alias : Name :
+   *
+   * @internal
    */
@@ -443,2 +544,4 @@
    * Arguments[Const] : ( Argument[?Const]+ )
+   *
+   * @internal
    */
@@ -456,2 +559,4 @@
    * Argument[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
@@ -480,2 +585,4 @@
    * InlineFragment : ... TypeCondition? Directives? SelectionSet
+   *
+   * @internal
    */
@@ -508,2 +615,4 @@
    * TypeCondition : NamedType
+   *
+   * @internal
    */
@@ -541,2 +650,4 @@
    * FragmentName : Name but not `on`
+   *
+   * @internal
    */
@@ -569,2 +680,4 @@
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
@@ -668,2 +781,4 @@
    *   - [ Value[?Const]+ ]
+   *
+   * @internal
    */
@@ -689,2 +804,4 @@
    * ```
+   *
+   * @internal
    */
@@ -706,2 +823,4 @@
    * ObjectField[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
@@ -722,2 +841,4 @@
    * Directives[Const] : Directive[?Const]+
+   *
+   * @internal
    */
@@ -742,2 +863,4 @@
    * ```
+   *
+   * @internal
    */
@@ -760,2 +883,4 @@
    *   - NonNullType
+   *
+   * @internal
    */
@@ -789,2 +914,4 @@
    * NamedType : Name
+   *
+   * @internal
    */
@@ -807,2 +934,4 @@
    * Description : StringValue
+   *
+   * @internal
    */
@@ -819,2 +948,4 @@
    * ```
+   *
+   * @internal
    */
@@ -841,2 +972,4 @@
    * OperationTypeDefinition : OperationType : NamedType
+   *
+   * @internal
    */
@@ -857,2 +990,4 @@
    * ScalarTypeDefinition : Description? scalar Name Directives[Const]?
+   *
+   * @internal
    */
@@ -877,2 +1012,4 @@
    *   type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
@@ -901,2 +1038,4 @@
    *   - ImplementsInterfaces & NamedType
+   *
+   * @internal
    */
@@ -913,2 +1052,4 @@
    * ```
+   *
+   * @internal
    */
@@ -926,2 +1067,4 @@
    *   - Description? Name ArgumentsDefinition? : Type Directives[Const]?
+   *
+   * @internal
    */
@@ -948,2 +1091,4 @@
    * ArgumentsDefinition : ( InputValueDefinition+ )
+   *
+   * @internal
    */
@@ -961,2 +1106,4 @@
    *   - Description? Name : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
@@ -989,2 +1136,4 @@
    *   - Description? interface Name Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
@@ -1012,2 +1161,4 @@
    *   - Description? union Name Directives[Const]? UnionMemberTypes?
+   *
+   * @internal
    */
@@ -1034,2 +1185,4 @@
    *   - UnionMemberTypes | NamedType
+   *
+   * @internal
    */
@@ -1045,2 +1198,4 @@
    *   - Description? enum Name Directives[Const]? EnumValuesDefinition?
+   *
+   * @internal
    */
@@ -1067,2 +1222,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1079,2 +1236,4 @@
    * EnumValueDefinition : Description? EnumValue Directives[Const]?
+   *
+   * @internal
    */
@@ -1096,2 +1255,4 @@
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
@@ -1119,2 +1280,4 @@
    *   - Description? input Name Directives[Const]? InputFieldsDefinition?
+   *
+   * @internal
    */
@@ -1141,2 +1304,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1164,2 +1329,4 @@
    *   - DirectiveDefinitionExtension
+   *
+   * @internal
    */
@@ -1210,2 +1377,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1237,2 +1406,4 @@
    *   - extend scalar Name Directives[Const]
+   *
+   * @internal
    */
@@ -1262,2 +1433,4 @@
    *  - extend type Name ImplementsInterfaces
+   *
+   * @internal
    */
@@ -1295,2 +1468,4 @@
    *  - extend interface Name ImplementsInterfaces
+   *
+   * @internal
    */
@@ -1327,2 +1502,4 @@
    *   - extend union Name Directives[Const]
+   *
+   * @internal
    */
@@ -1353,2 +1530,4 @@
    *   - extend enum Name Directives[Const]
+   *
+   * @internal
    */
@@ -1379,2 +1558,4 @@
    *   - extend input Name Directives[Const]
+   *
+   * @internal
    */
@@ -1425,2 +1606,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1456,2 +1639,4 @@
    *   - DirectiveLocations | DirectiveLocation
+   *
+   * @internal
    */
@@ -1517,2 +1702,15 @@
    *   - \@ Name ( Name : )
+   * @returns Parsed schema coordinate AST.
+   * @example
+   * ```ts
+   * import { Parser, Source } from 'graphql/language';
+   *
+   * const typeCoordinate = new Parser(new Source('User.name')).parseSchemaCoordinate();
+   * const directiveCoordinate = new Parser(new Source('@include(if:)')).parseSchemaCoordinate();
+   *
+   * typeCoordinate.name.value; // => 'User'
+   * typeCoordinate.memberName?.value; // => 'name'
+   * directiveCoordinate.name.value; // => 'deprecated'
+   * directiveCoordinate.argumentName?.value; // => 'reason'
+   * ```
    */
@@ -1581,2 +1779,4 @@
    * given parsed object.
+   *
+   * @internal
    */
@@ -1597,2 +1797,4 @@
    * Determines if the next token is of a given kind
+   *
+   * @internal
    */
@@ -1606,2 +1808,4 @@
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
@@ -1626,2 +1830,4 @@
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
@@ -1642,2 +1848,4 @@
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
@@ -1661,2 +1869,4 @@
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
@@ -1676,2 +1886,4 @@
    * Helper function for creating an error when an unexpected lexed token is encountered.
+   *
+   * @internal
    */
@@ -1692,2 +1904,4 @@
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -1710,2 +1924,4 @@
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -1730,2 +1946,4 @@
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -1747,2 +1965,4 @@
    * Advances the parser to the next lex token after last item in the list.
+   *
+   * @internal
    */
@@ -1781,2 +2001,4 @@
  * A helper function to describe a token as a string for debugging.
+ *
+ * @internal
  */
@@ -1792,2 +2014,4 @@
  * A helper function to describe a token kind as a string for debugging.
+ *
+ * @internal
  */
@@ -1794,0 +2018,0 @@

language/parser.mjs

@@ -0,1 +1,2 @@
+/** @category Parsing */
 import { syntaxError } from '../error/syntaxError.mjs';
@@ -9,5 +10,3 @@ import { Location, OperationTypeNode } from './ast.mjs';
 import { TokenKind } from './tokenKind.mjs';
-/**
- * Configuration options to control parser behavior
- */
+/** Configuration options to control parser behavior */
 
@@ -17,2 +16,35 @@ /**
  * Throws GraphQLError if a syntax error is encountered.
+ * @param source - A GraphQL source string or source object.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL document AST.
+ * @example
+ * ```ts
+ * // Parse a GraphQL document with the default parser options.
+ * import { parse } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ *
+ * document.kind; // => 'Document'
+ * ```
+ * @example
+ * ```ts
+ * // This variant enables parser options and provides an explicit lexer.
+ * import { Lexer, Source, parse } from 'graphql/language';
+ *
+ * const document = parse('fragment A($var: Boolean) on Query { field }', {
+ *   allowLegacyFragmentVariables: true,
+ *   maxTokens: 20,
+ *   noLocation: true,
+ * });
+ * const directiveDocument = parse('directive @foo @bar on FIELD', {
+ *   experimentalDirectivesOnDirectiveDefinitions: true,
+ * });
+ * const source = new Source('{ hero }');
+ * const lexerDocument = parse(source, { lexer: new Lexer(source) });
+ *
+ * document.definitions[0].kind; // => 'FragmentDefinition'
+ * document.loc; // => undefined
+ * directiveDocument.definitions[0].kind; // => 'DirectiveDefinition'
+ * lexerDocument.definitions[0].kind; // => 'OperationDefinition'
+ * ```
  */
@@ -37,2 +69,13 @@ export function parse(source, options) {
  * Consider providing the results to the utility function: valueFromAST().
+ * @param source - A GraphQL source string or source object containing a value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ *
+ * const value = parseValue('[42]');
+ *
+ * value.kind; // => 'ListValue'
+ * ```
  */
@@ -50,2 +93,14 @@
  * variable. The return type will be a constant value.
+ * @param source - A GraphQL source string or source object containing a constant value.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL constant value AST.
+ * @example
+ * ```ts
+ * import { parseConstValue } from 'graphql/language';
+ *
+ * const value = parseConstValue('{ enabled: true }');
+ *
+ * value.kind; // => 'ObjectValue'
+ * parseConstValue('$variable'); // throws an error
+ * ```
  */
@@ -69,2 +124,13 @@
  * Consider providing the results to the utility function: typeFromAST().
+ * @param source - A GraphQL source string or source object containing a type reference.
+ * @param options - Optional parser configuration.
+ * @returns The parsed GraphQL type AST.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ *
+ * const type = parseType('[String!]');
+ *
+ * type.kind; // => 'ListType'
+ * ```
  */
@@ -87,2 +153,12 @@
  * with an unparsed source.
+ * @param source - A GraphQL source string or source object containing a schema coordinate.
+ * @returns The parsed GraphQL schema coordinate AST.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ *
+ * const coordinate = parseSchemaCoordinate('Query.hero');
+ *
+ * coordinate.kind; // => 'MemberCoordinate'
+ * ```
  */
@@ -133,2 +209,4 @@
    * Converts a name lex token into a name parse node.
+   *
+   * @internal
    */
@@ -146,2 +224,4 @@
    * Document : Definition+
+   *
+   * @internal
    */
@@ -181,2 +261,4 @@
    *   - InputObjectTypeDefinition
+   *
+   * @internal
    */
@@ -260,2 +342,4 @@
    *  - OperationType Name? VariableDefinitions? Directives? SelectionSet
+   *
+   * @internal
    */
@@ -298,2 +382,4 @@
    * OperationType : one of query mutation subscription
+   *
+   * @internal
    */
@@ -319,2 +405,4 @@
    * VariableDefinitions : ( VariableDefinition+ )
+   *
+   * @internal
    */
@@ -331,2 +419,4 @@
    * VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
@@ -348,2 +438,4 @@
    * Variable : $ Name
+   *
+   * @internal
    */
@@ -363,2 +455,4 @@
    * ```
+   *
+   * @internal
    */
@@ -381,2 +475,4 @@
    *   - InlineFragment
+   *
+   * @internal
    */
@@ -393,2 +489,4 @@
    * Alias : Name :
+   *
+   * @internal
    */
@@ -422,2 +520,4 @@
    * Arguments[Const] : ( Argument[?Const]+ )
+   *
+   * @internal
    */
@@ -431,2 +531,4 @@
    * Argument[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
@@ -455,2 +557,4 @@
    * InlineFragment : ... TypeCondition? Directives? SelectionSet
+   *
+   * @internal
    */
@@ -483,2 +587,4 @@
    * TypeCondition : NamedType
+   *
+   * @internal
    */
@@ -516,2 +622,4 @@
    * FragmentName : Name but not `on`
+   *
+   * @internal
    */
@@ -544,2 +652,4 @@
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
@@ -643,2 +753,4 @@
    *   - [ Value[?Const]+ ]
+   *
+   * @internal
    */
@@ -660,2 +772,4 @@
    * ```
+   *
+   * @internal
    */
@@ -673,2 +787,4 @@
    * ObjectField[Const] : Name : Value[?Const]
+   *
+   * @internal
    */
@@ -689,2 +805,4 @@
    * Directives[Const] : Directive[?Const]+
+   *
+   * @internal
    */
@@ -709,2 +827,4 @@
    * ```
+   *
+   * @internal
    */
@@ -727,2 +847,4 @@
    *   - NonNullType
+   *
+   * @internal
    */
@@ -756,2 +878,4 @@
    * NamedType : Name
+   *
+   * @internal
    */
@@ -771,2 +895,4 @@
    * Description : StringValue
+   *
+   * @internal
    */
@@ -783,2 +909,4 @@
    * ```
+   *
+   * @internal
    */
@@ -805,2 +933,4 @@
    * OperationTypeDefinition : OperationType : NamedType
+   *
+   * @internal
    */
@@ -821,2 +951,4 @@
    * ScalarTypeDefinition : Description? scalar Name Directives[Const]?
+   *
+   * @internal
    */
@@ -841,2 +973,4 @@
    *   type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
@@ -865,2 +999,4 @@
    *   - ImplementsInterfaces & NamedType
+   *
+   * @internal
    */
@@ -877,2 +1013,4 @@
    * ```
+   *
+   * @internal
    */
@@ -890,2 +1028,4 @@
    *   - Description? Name ArgumentsDefinition? : Type Directives[Const]?
+   *
+   * @internal
    */
@@ -912,2 +1052,4 @@
    * ArgumentsDefinition : ( InputValueDefinition+ )
+   *
+   * @internal
    */
@@ -925,2 +1067,4 @@
    *   - Description? Name : Type DefaultValue? Directives[Const]?
+   *
+   * @internal
    */
@@ -953,2 +1097,4 @@
    *   - Description? interface Name Directives[Const]? FieldsDefinition?
+   *
+   * @internal
    */
@@ -976,2 +1122,4 @@
    *   - Description? union Name Directives[Const]? UnionMemberTypes?
+   *
+   * @internal
    */
@@ -998,2 +1146,4 @@
    *   - UnionMemberTypes | NamedType
+   *
+   * @internal
    */
@@ -1009,2 +1159,4 @@
    *   - Description? enum Name Directives[Const]? EnumValuesDefinition?
+   *
+   * @internal
    */
@@ -1031,2 +1183,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1043,2 +1197,4 @@
    * EnumValueDefinition : Description? EnumValue Directives[Const]?
+   *
+   * @internal
    */
@@ -1060,2 +1216,4 @@
    * EnumValue : Name but not `true`, `false` or `null`
+   *
+   * @internal
    */
@@ -1083,2 +1241,4 @@
    *   - Description? input Name Directives[Const]? InputFieldsDefinition?
+   *
+   * @internal
    */
@@ -1105,2 +1265,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1128,2 +1290,4 @@
    *   - DirectiveDefinitionExtension
+   *
+   * @internal
    */
@@ -1174,2 +1338,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1201,2 +1367,4 @@
    *   - extend scalar Name Directives[Const]
+   *
+   * @internal
    */
@@ -1226,2 +1394,4 @@
    *  - extend type Name ImplementsInterfaces
+   *
+   * @internal
    */
@@ -1259,2 +1429,4 @@
    *  - extend interface Name ImplementsInterfaces
+   *
+   * @internal
    */
@@ -1291,2 +1463,4 @@
    *   - extend union Name Directives[Const]
+   *
+   * @internal
    */
@@ -1317,2 +1491,4 @@
    *   - extend enum Name Directives[Const]
+   *
+   * @internal
    */
@@ -1343,2 +1519,4 @@
    *   - extend input Name Directives[Const]
+   *
+   * @internal
    */
@@ -1389,2 +1567,4 @@
    * ```
+   *
+   * @internal
    */
@@ -1420,2 +1600,4 @@
    *   - DirectiveLocations | DirectiveLocation
+   *
+   * @internal
    */
@@ -1473,2 +1655,15 @@
    *   - \@ Name ( Name : )
+   * @returns Parsed schema coordinate AST.
+   * @example
+   * ```ts
+   * import { Parser, Source } from 'graphql/language';
+   *
+   * const typeCoordinate = new Parser(new Source('User.name')).parseSchemaCoordinate();
+   * const directiveCoordinate = new Parser(new Source('@include(if:)')).parseSchemaCoordinate();
+   *
+   * typeCoordinate.name.value; // => 'User'
+   * typeCoordinate.memberName?.value; // => 'name'
+   * directiveCoordinate.name.value; // => 'deprecated'
+   * directiveCoordinate.argumentName?.value; // => 'reason'
+   * ```
    */
@@ -1537,2 +1732,4 @@
    * given parsed object.
+   *
+   * @internal
    */
@@ -1553,2 +1750,4 @@
    * Determines if the next token is of a given kind
+   *
+   * @internal
    */
@@ -1562,2 +1761,4 @@
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
@@ -1582,2 +1783,4 @@
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
@@ -1598,2 +1801,4 @@
    * Otherwise, do not change the parser state and throw an error.
+   *
+   * @internal
    */
@@ -1617,2 +1822,4 @@
    * Otherwise, do not change the parser state and return "false".
+   *
+   * @internal
    */
@@ -1632,2 +1839,4 @@
    * Helper function for creating an error when an unexpected lexed token is encountered.
+   *
+   * @internal
    */
@@ -1648,2 +1857,4 @@
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -1666,2 +1877,4 @@
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -1686,2 +1899,4 @@
    * Advances the parser to the next lex token after the closing token.
+   *
+   * @internal
    */
@@ -1703,2 +1918,4 @@
    * Advances the parser to the next lex token after last item in the list.
+   *
+   * @internal
    */
@@ -1737,2 +1954,4 @@
  * A helper function to describe a token as a string for debugging.
+ *
+ * @internal
  */
@@ -1746,2 +1965,4 @@
  * A helper function to describe a token kind as a string for debugging.
+ *
+ * @internal
  */
@@ -1748,0 +1969,0 @@

language/predicates.d.ts

@@ -0,1 +1,2 @@
+/** @category AST Predicates */
 import type {
@@ -15,24 +16,192 @@ ASTNode,
 } from './ast';
+/**
+ * Returns true when the AST node is a definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a definition node.
+ * @example
+ * ```ts
+ * import { parse, isDefinitionNode } from 'graphql/language';
+ *
+ * const document = parse('{ hello }');
+ *
+ * isDefinitionNode(document.definitions[0]); // => true
+ * isDefinitionNode(document); // => false
+ * ```
+ */
 export declare function isDefinitionNode(node: ASTNode): node is DefinitionNode;
+/**
+ * Returns true when the AST node is an executable definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is an executable definition node.
+ * @example
+ * ```ts
+ * import { parse, isExecutableDefinitionNode } from 'graphql/language';
+ *
+ * const query = parse('{ hello }');
+ * const schema = parse('type Query { hello: String }');
+ *
+ * isExecutableDefinitionNode(query.definitions[0]); // => true
+ * isExecutableDefinitionNode(schema.definitions[0]); // => false
+ * ```
+ */
 export declare function isExecutableDefinitionNode(
   node: ASTNode,
 ): node is ExecutableDefinitionNode;
+/**
+ * Returns true when the AST node is a selection node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a selection node.
+ * @example
+ * ```ts
+ * import { Kind, isSelectionNode } from 'graphql/language';
+ *
+ * const field = { kind: Kind.FIELD, name: { kind: Kind.NAME, value: 'hello' } };
+ * const document = { kind: Kind.DOCUMENT, definitions: [] };
+ *
+ * isSelectionNode(field); // => true
+ * isSelectionNode(document); // => false
+ * ```
+ */
 export declare function isSelectionNode(node: ASTNode): node is SelectionNode;
+/**
+ * Returns true when the AST node is a value node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a value node.
+ * @example
+ * ```ts
+ * import { parseType, parseValue, isValueNode } from 'graphql/language';
+ *
+ * const value = parseValue('[42]');
+ * const type = parseType('[String!]');
+ *
+ * isValueNode(value); // => true
+ * isValueNode(type); // => false
+ * ```
+ */
 export declare function isValueNode(node: ASTNode): node is ValueNode;
+/**
+ * Returns true when the AST node is a constant value node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a constant value node.
+ * @example
+ * ```ts
+ * import { parseConstValue, parseValue, isConstValueNode } from 'graphql/language';
+ *
+ * const value = parseConstValue('[42]');
+ * const variable = parseValue('$id');
+ *
+ * isConstValueNode(value); // => true
+ * isConstValueNode(variable); // => false
+ * ```
+ */
 export declare function isConstValueNode(node: ASTNode): node is ConstValueNode;
+/**
+ * Returns true when the AST node is a type node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type node.
+ * @example
+ * ```ts
+ * import { parseType, parseValue, isTypeNode } from 'graphql/language';
+ *
+ * const type = parseType('[String!]');
+ * const value = parseValue('[42]');
+ *
+ * isTypeNode(type); // => true
+ * isTypeNode(value); // => false
+ * ```
+ */
 export declare function isTypeNode(node: ASTNode): node is TypeNode;
+/**
+ * Returns true when the AST node is a type system definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type system definition node.
+ * @example
+ * ```ts
+ * import { parse, isTypeSystemDefinitionNode } from 'graphql/language';
+ *
+ * const schema = parse('type Query { hello: String }');
+ * const query = parse('{ hello }');
+ *
+ * isTypeSystemDefinitionNode(schema.definitions[0]); // => true
+ * isTypeSystemDefinitionNode(query.definitions[0]); // => false
+ * ```
+ */
 export declare function isTypeSystemDefinitionNode(
   node: ASTNode,
 ): node is TypeSystemDefinitionNode;
+/**
+ * Returns true when the AST node is a type definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type definition node.
+ * @example
+ * ```ts
+ * import { parse, isTypeDefinitionNode } from 'graphql/language';
+ *
+ * const typeDefinition = parse('type Query { hello: String }');
+ * const directiveDefinition = parse('directive @cache on FIELD');
+ *
+ * isTypeDefinitionNode(typeDefinition.definitions[0]); // => true
+ * isTypeDefinitionNode(directiveDefinition.definitions[0]); // => false
+ * ```
+ */
 export declare function isTypeDefinitionNode(
   node: ASTNode,
 ): node is TypeDefinitionNode;
+/**
+ * Returns true when the AST node is a type system extension node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type system extension node.
+ * @example
+ * ```ts
+ * import { parse, isTypeSystemExtensionNode } from 'graphql/language';
+ *
+ * const extension = parse('extend type Query { hello: String }');
+ * const definition = parse('type Query { hello: String }');
+ *
+ * isTypeSystemExtensionNode(extension.definitions[0]); // => true
+ * isTypeSystemExtensionNode(definition.definitions[0]); // => false
+ * ```
+ */
 export declare function isTypeSystemExtensionNode(
   node: ASTNode,
 ): node is TypeSystemExtensionNode;
+/**
+ * Returns true when the AST node is a type extension node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type extension node.
+ * @example
+ * ```ts
+ * import { parse, isTypeExtensionNode } from 'graphql/language';
+ *
+ * const extension = parse('extend type Query { hello: String }');
+ * const schemaExtension = parse('extend schema { query: Query }');
+ *
+ * isTypeExtensionNode(extension.definitions[0]); // => true
+ * isTypeExtensionNode(schemaExtension.definitions[0]); // => false
+ * ```
+ */
 export declare function isTypeExtensionNode(
   node: ASTNode,
 ): node is TypeExtensionNode;
+/**
+ * Returns true when the AST node is a schema coordinate node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a schema coordinate node.
+ * @example
+ * ```ts
+ * import {
+ *   parse,
+ *   parseSchemaCoordinate,
+ *   isSchemaCoordinateNode,
+ * } from 'graphql/language';
+ *
+ * const coordinate = parseSchemaCoordinate('Query.hero');
+ * const document = parse('{ hero }');
+ *
+ * isSchemaCoordinateNode(coordinate); // => true
+ * isSchemaCoordinateNode(document); // => false
+ * ```
+ */
 export declare function isSchemaCoordinateNode(
   node: ASTNode,
 ): node is SchemaCoordinateNode;

language/predicates.js

@@ -20,2 +20,18 @@ 'use strict';
 
+/** @category AST Predicates */
+
+/**
+ * Returns true when the AST node is a definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a definition node.
+ * @example
+ * ```ts
+ * import { parse, isDefinitionNode } from 'graphql/language';
+ *
+ * const document = parse('{ hello }');
+ *
+ * isDefinitionNode(document.definitions[0]); // => true
+ * isDefinitionNode(document); // => false
+ * ```
+ */
 function isDefinitionNode(node) {
@@ -28,2 +44,17 @@ return (
 }
+/**
+ * Returns true when the AST node is an executable definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is an executable definition node.
+ * @example
+ * ```ts
+ * import { parse, isExecutableDefinitionNode } from 'graphql/language';
+ *
+ * const query = parse('{ hello }');
+ * const schema = parse('type Query { hello: String }');
+ *
+ * isExecutableDefinitionNode(query.definitions[0]); // => true
+ * isExecutableDefinitionNode(schema.definitions[0]); // => false
+ * ```
+ */
 
@@ -36,2 +67,17 @@ function isExecutableDefinitionNode(node) {
 }
+/**
+ * Returns true when the AST node is a selection node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a selection node.
+ * @example
+ * ```ts
+ * import { Kind, isSelectionNode } from 'graphql/language';
+ *
+ * const field = { kind: Kind.FIELD, name: { kind: Kind.NAME, value: 'hello' } };
+ * const document = { kind: Kind.DOCUMENT, definitions: [] };
+ *
+ * isSelectionNode(field); // => true
+ * isSelectionNode(document); // => false
+ * ```
+ */
 
@@ -45,2 +91,17 @@ function isSelectionNode(node) {
 }
+/**
+ * Returns true when the AST node is a value node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a value node.
+ * @example
+ * ```ts
+ * import { parseType, parseValue, isValueNode } from 'graphql/language';
+ *
+ * const value = parseValue('[42]');
+ * const type = parseType('[String!]');
+ *
+ * isValueNode(value); // => true
+ * isValueNode(type); // => false
+ * ```
+ */
 
@@ -60,2 +121,17 @@ function isValueNode(node) {
 }
+/**
+ * Returns true when the AST node is a constant value node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a constant value node.
+ * @example
+ * ```ts
+ * import { parseConstValue, parseValue, isConstValueNode } from 'graphql/language';
+ *
+ * const value = parseConstValue('[42]');
+ * const variable = parseValue('$id');
+ *
+ * isConstValueNode(value); // => true
+ * isConstValueNode(variable); // => false
+ * ```
+ */
 
@@ -72,2 +148,17 @@ function isConstValueNode(node) {
 }
+/**
+ * Returns true when the AST node is a type node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type node.
+ * @example
+ * ```ts
+ * import { parseType, parseValue, isTypeNode } from 'graphql/language';
+ *
+ * const type = parseType('[String!]');
+ * const value = parseValue('[42]');
+ *
+ * isTypeNode(type); // => true
+ * isTypeNode(value); // => false
+ * ```
+ */
 
@@ -81,2 +172,17 @@ function isTypeNode(node) {
 }
+/**
+ * Returns true when the AST node is a type system definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type system definition node.
+ * @example
+ * ```ts
+ * import { parse, isTypeSystemDefinitionNode } from 'graphql/language';
+ *
+ * const schema = parse('type Query { hello: String }');
+ * const query = parse('{ hello }');
+ *
+ * isTypeSystemDefinitionNode(schema.definitions[0]); // => true
+ * isTypeSystemDefinitionNode(query.definitions[0]); // => false
+ * ```
+ */
 
@@ -90,2 +196,17 @@ function isTypeSystemDefinitionNode(node) {
 }
+/**
+ * Returns true when the AST node is a type definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type definition node.
+ * @example
+ * ```ts
+ * import { parse, isTypeDefinitionNode } from 'graphql/language';
+ *
+ * const typeDefinition = parse('type Query { hello: String }');
+ * const directiveDefinition = parse('directive @cache on FIELD');
+ *
+ * isTypeDefinitionNode(typeDefinition.definitions[0]); // => true
+ * isTypeDefinitionNode(directiveDefinition.definitions[0]); // => false
+ * ```
+ */
 
@@ -102,2 +223,17 @@ function isTypeDefinitionNode(node) {
 }
+/**
+ * Returns true when the AST node is a type system extension node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type system extension node.
+ * @example
+ * ```ts
+ * import { parse, isTypeSystemExtensionNode } from 'graphql/language';
+ *
+ * const extension = parse('extend type Query { hello: String }');
+ * const definition = parse('type Query { hello: String }');
+ *
+ * isTypeSystemExtensionNode(extension.definitions[0]); // => true
+ * isTypeSystemExtensionNode(definition.definitions[0]); // => false
+ * ```
+ */
 
@@ -111,2 +247,17 @@ function isTypeSystemExtensionNode(node) {
 }
+/**
+ * Returns true when the AST node is a type extension node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type extension node.
+ * @example
+ * ```ts
+ * import { parse, isTypeExtensionNode } from 'graphql/language';
+ *
+ * const extension = parse('extend type Query { hello: String }');
+ * const schemaExtension = parse('extend schema { query: Query }');
+ *
+ * isTypeExtensionNode(extension.definitions[0]); // => true
+ * isTypeExtensionNode(schemaExtension.definitions[0]); // => false
+ * ```
+ */
 
@@ -123,2 +274,21 @@ function isTypeExtensionNode(node) {
 }
+/**
+ * Returns true when the AST node is a schema coordinate node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a schema coordinate node.
+ * @example
+ * ```ts
+ * import {
+ *   parse,
+ *   parseSchemaCoordinate,
+ *   isSchemaCoordinateNode,
+ * } from 'graphql/language';
+ *
+ * const coordinate = parseSchemaCoordinate('Query.hero');
+ * const document = parse('{ hero }');
+ *
+ * isSchemaCoordinateNode(coordinate); // => true
+ * isSchemaCoordinateNode(document); // => false
+ * ```
+ */
 
@@ -125,0 +295,0 @@ function isSchemaCoordinateNode(node) {

language/predicates.mjs

@@ -0,2 +1,18 @@
+/** @category AST Predicates */
 import { Kind } from './kinds.mjs';
+/**
+ * Returns true when the AST node is a definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a definition node.
+ * @example
+ * ```ts
+ * import { parse, isDefinitionNode } from 'graphql/language';
+ *
+ * const document = parse('{ hello }');
+ *
+ * isDefinitionNode(document.definitions[0]); // => true
+ * isDefinitionNode(document); // => false
+ * ```
+ */
+
 export function isDefinitionNode(node) {
@@ -9,2 +25,18 @@ return (
 }
+/**
+ * Returns true when the AST node is an executable definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is an executable definition node.
+ * @example
+ * ```ts
+ * import { parse, isExecutableDefinitionNode } from 'graphql/language';
+ *
+ * const query = parse('{ hello }');
+ * const schema = parse('type Query { hello: String }');
+ *
+ * isExecutableDefinitionNode(query.definitions[0]); // => true
+ * isExecutableDefinitionNode(schema.definitions[0]); // => false
+ * ```
+ */
+
 export function isExecutableDefinitionNode(node) {
@@ -16,2 +48,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a selection node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a selection node.
+ * @example
+ * ```ts
+ * import { Kind, isSelectionNode } from 'graphql/language';
+ *
+ * const field = { kind: Kind.FIELD, name: { kind: Kind.NAME, value: 'hello' } };
+ * const document = { kind: Kind.DOCUMENT, definitions: [] };
+ *
+ * isSelectionNode(field); // => true
+ * isSelectionNode(document); // => false
+ * ```
+ */
+
 export function isSelectionNode(node) {
@@ -24,2 +72,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a value node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a value node.
+ * @example
+ * ```ts
+ * import { parseType, parseValue, isValueNode } from 'graphql/language';
+ *
+ * const value = parseValue('[42]');
+ * const type = parseType('[String!]');
+ *
+ * isValueNode(value); // => true
+ * isValueNode(type); // => false
+ * ```
+ */
+
 export function isValueNode(node) {
@@ -38,2 +102,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a constant value node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a constant value node.
+ * @example
+ * ```ts
+ * import { parseConstValue, parseValue, isConstValueNode } from 'graphql/language';
+ *
+ * const value = parseConstValue('[42]');
+ * const variable = parseValue('$id');
+ *
+ * isConstValueNode(value); // => true
+ * isConstValueNode(variable); // => false
+ * ```
+ */
+
 export function isConstValueNode(node) {
@@ -49,2 +129,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a type node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type node.
+ * @example
+ * ```ts
+ * import { parseType, parseValue, isTypeNode } from 'graphql/language';
+ *
+ * const type = parseType('[String!]');
+ * const value = parseValue('[42]');
+ *
+ * isTypeNode(type); // => true
+ * isTypeNode(value); // => false
+ * ```
+ */
+
 export function isTypeNode(node) {
@@ -57,2 +153,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a type system definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type system definition node.
+ * @example
+ * ```ts
+ * import { parse, isTypeSystemDefinitionNode } from 'graphql/language';
+ *
+ * const schema = parse('type Query { hello: String }');
+ * const query = parse('{ hello }');
+ *
+ * isTypeSystemDefinitionNode(schema.definitions[0]); // => true
+ * isTypeSystemDefinitionNode(query.definitions[0]); // => false
+ * ```
+ */
+
 export function isTypeSystemDefinitionNode(node) {
@@ -65,2 +177,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a type definition node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type definition node.
+ * @example
+ * ```ts
+ * import { parse, isTypeDefinitionNode } from 'graphql/language';
+ *
+ * const typeDefinition = parse('type Query { hello: String }');
+ * const directiveDefinition = parse('directive @cache on FIELD');
+ *
+ * isTypeDefinitionNode(typeDefinition.definitions[0]); // => true
+ * isTypeDefinitionNode(directiveDefinition.definitions[0]); // => false
+ * ```
+ */
+
 export function isTypeDefinitionNode(node) {
@@ -76,2 +204,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a type system extension node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type system extension node.
+ * @example
+ * ```ts
+ * import { parse, isTypeSystemExtensionNode } from 'graphql/language';
+ *
+ * const extension = parse('extend type Query { hello: String }');
+ * const definition = parse('type Query { hello: String }');
+ *
+ * isTypeSystemExtensionNode(extension.definitions[0]); // => true
+ * isTypeSystemExtensionNode(definition.definitions[0]); // => false
+ * ```
+ */
+
 export function isTypeSystemExtensionNode(node) {
@@ -84,2 +228,18 @@ return (
 }
+/**
+ * Returns true when the AST node is a type extension node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a type extension node.
+ * @example
+ * ```ts
+ * import { parse, isTypeExtensionNode } from 'graphql/language';
+ *
+ * const extension = parse('extend type Query { hello: String }');
+ * const schemaExtension = parse('extend schema { query: Query }');
+ *
+ * isTypeExtensionNode(extension.definitions[0]); // => true
+ * isTypeExtensionNode(schemaExtension.definitions[0]); // => false
+ * ```
+ */
+
 export function isTypeExtensionNode(node) {
@@ -95,2 +255,22 @@ return (
 }
+/**
+ * Returns true when the AST node is a schema coordinate node.
+ * @param node - The AST node to test.
+ * @returns True when the AST node is a schema coordinate node.
+ * @example
+ * ```ts
+ * import {
+ *   parse,
+ *   parseSchemaCoordinate,
+ *   isSchemaCoordinateNode,
+ * } from 'graphql/language';
+ *
+ * const coordinate = parseSchemaCoordinate('Query.hero');
+ * const document = parse('{ hero }');
+ *
+ * isSchemaCoordinateNode(coordinate); // => true
+ * isSchemaCoordinateNode(document); // => false
+ * ```
+ */
+
 export function isSchemaCoordinateNode(node) {
@@ -97,0 +277,0 @@ return (

language/printer.d.ts

@@ -0,1 +1,2 @@
+/** @category Printing */
 import type { ASTNode } from './ast';
@@ -5,3 +6,14 @@ /**
  * formatting rules.
+ * @param ast - The GraphQL AST node to print.
+ * @returns A stable string representation of the AST.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql';
+ *
+ * const ast = parse('{ hero { name } }');
+ * const text = print(ast);
+ *
+ * text; // => '{\n  hero {\n    name\n  }\n}'
+ * ```
  */
 export declare function print(ast: ASTNode): string;

language/printer.js

@@ -14,5 +14,18 @@ 'use strict';
 
+/** @category Printing */
+
 /**
  * Converts an AST into a string, using one set of reasonable
  * formatting rules.
+ * @param ast - The GraphQL AST node to print.
+ * @returns A stable string representation of the AST.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql';
+ *
+ * const ast = parse('{ hero { name } }');
+ * const text = print(ast);
+ *
+ * text; // => '{\n  hero {\n    name\n  }\n}'
+ * ```
  */
@@ -346,2 +359,4 @@ function print(ast) {
  * print all items together separated by separator if provided
+ *
+ * @internal
  */
@@ -362,2 +377,4 @@
  * Given array, print each item on its own line, wrapped in an indented `{ }` block.
+ *
+ * @internal
  */
@@ -370,2 +387,4 @@
  * If maybeString is not null or empty, then wrap with start and end, otherwise print an empty string.
+ *
+ * @internal
  */
@@ -372,0 +391,0 @@

language/printer.mjs

@@ -0,1 +1,2 @@
+/** @category Printing */
 import { printBlockString } from './blockString.mjs';
@@ -7,2 +8,13 @@ import { printString } from './printString.mjs';
  * formatting rules.
+ * @param ast - The GraphQL AST node to print.
+ * @returns A stable string representation of the AST.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql';
+ *
+ * const ast = parse('{ hero { name } }');
+ * const text = print(ast);
+ *
+ * text; // => '{\n  hero {\n    name\n  }\n}'
+ * ```
  */
@@ -334,2 +346,4 @@
  * print all items together separated by separator if provided
+ *
+ * @internal
  */
@@ -350,2 +364,4 @@
  * Given array, print each item on its own line, wrapped in an indented `{ }` block.
+ *
+ * @internal
  */
@@ -358,2 +374,4 @@
  * If maybeString is not null or empty, then wrap with start and end, otherwise print an empty string.
+ *
+ * @internal
  */
@@ -360,0 +378,0 @@

language/printLocation.d.ts

@@ -0,1 +1,2 @@
+/** @category Source */
 import type { Location } from './ast';
@@ -6,2 +7,17 @@ import type { SourceLocation } from './location';
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param location - The AST location to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { parse, printLocation } from 'graphql/language';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const location = document.definitions[0].loc;
+ *
+ * if (location) {
+ *   const printed = printLocation(location);
+ *
+ *   printed; // => 'GraphQL request:1:1\n1 | type Query { hello: String }\n  | ^'
+ * }
+ * ```
  */
@@ -11,2 +27,14 @@ export declare function printLocation(location: Location): string;
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param source - The source document that contains the location.
+ * @param sourceLocation - The 1-indexed line and column to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { Source, printSourceLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const printed = printSourceLocation(source, { line: 1, column: 14 });
+ *
+ * printed; // => 'GraphQL request:1:14\n1 | type Query { hello: String }\n  |              ^'
+ * ```
  */
@@ -13,0 +41,0 @@ export declare function printSourceLocation(

language/printLocation.js

@@ -11,4 +11,21 @@ 'use strict';
 
+/** @category Source */
+
 /**
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param location - The AST location to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { parse, printLocation } from 'graphql/language';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const location = document.definitions[0].loc;
+ *
+ * if (location) {
+ *   const printed = printLocation(location);
+ *
+ *   printed; // => 'GraphQL request:1:1\n1 | type Query { hello: String }\n  | ^'
+ * }
+ * ```
  */
@@ -23,2 +40,14 @@ function printLocation(location) {
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param source - The source document that contains the location.
+ * @param sourceLocation - The 1-indexed line and column to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { Source, printSourceLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const printed = printSourceLocation(source, { line: 1, column: 14 });
+ *
+ * printed; // => 'GraphQL request:1:14\n1 | type Query { hello: String }\n  |              ^'
+ * ```
  */
@@ -25,0 +54,0 @@

language/printLocation.mjs

@@ -0,1 +1,2 @@
+/** @category Source */
 import { getLocation } from './location.mjs';
@@ -5,2 +6,17 @@
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param location - The AST location to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { parse, printLocation } from 'graphql/language';
+ *
+ * const document = parse('type Query { hello: String }');
+ * const location = document.definitions[0].loc;
+ *
+ * if (location) {
+ *   const printed = printLocation(location);
+ *
+ *   printed; // => 'GraphQL request:1:1\n1 | type Query { hello: String }\n  | ^'
+ * }
+ * ```
  */
@@ -15,2 +31,14 @@ export function printLocation(location) {
  * Render a helpful description of the location in the GraphQL Source document.
+ * @param source - The source document that contains the location.
+ * @param sourceLocation - The 1-indexed line and column to print.
+ * @returns A formatted source excerpt with line and column information.
+ * @example
+ * ```ts
+ * import { Source, printSourceLocation } from 'graphql/language';
+ *
+ * const source = new Source('type Query { hello: String }');
+ * const printed = printSourceLocation(source, { line: 1, column: 14 });
+ *
+ * printed; // => 'GraphQL request:1:14\n1 | type Query { hello: String }\n  |              ^'
+ * ```
  */
@@ -17,0 +45,0 @@

language/printString.d.ts

 /**
  * Prints a string as a GraphQL StringValue literal. Replaces control characters
  * and excluded characters (" U+0022 and \\ U+005C) with escape sequences.
+ *
+ * @internal
  */
 export declare function printString(str: string): string;

language/printString.js

@@ -11,6 +11,10 @@ 'use strict';
  * and excluded characters (" U+0022 and \\ U+005C) with escape sequences.
+ *
+ * @internal
  */
 function printString(str) {
   return `"${str.replace(escapedRegExp, escapedReplacer)}"`;
-} // eslint-disable-next-line no-control-regex
+}
+/** @internal */
+// eslint-disable-next-line no-control-regex
 
@@ -17,0 +21,0 @@ const escapedRegExp = /[\x00-\x1f\x22\x5c\x7f-\x9f]/g;

language/printString.mjs

 /**
  * Prints a string as a GraphQL StringValue literal. Replaces control characters
  * and excluded characters (" U+0022 and \\ U+005C) with escape sequences.
+ *
+ * @internal
  */
 export function printString(str) {
   return `"${str.replace(escapedRegExp, escapedReplacer)}"`;
-} // eslint-disable-next-line no-control-regex
+}
+/** @internal */
+// eslint-disable-next-line no-control-regex
 
@@ -9,0 +13,0 @@ const escapedRegExp = /[\x00-\x1f\x22\x5c\x7f-\x9f]/g;

language/schemaCoordinateLexer.d.ts

@@ -11,12 +11,10 @@ import { Token } from './ast';
  * whenever called.
+ *
+ * @internal
  */
 export declare class SchemaCoordinateLexer implements LexerInterface {
   source: Source;
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** The previously focused non-ignored token. */
   lastToken: Token;
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** The currently focused non-ignored token. */
   token: Token;
@@ -37,2 +35,4 @@ /**
    * Advances the token stream to the next non-ignored token.
+   *
+   * @internal
    */
@@ -43,4 +43,6 @@ advance(): Token;
    * the current Lexer token.
+   *
+   * @internal
    */
   lookahead(): Token;
 }

language/schemaCoordinateLexer.js

@@ -25,11 +25,9 @@ 'use strict';
  * whenever called.
+ *
+ * @internal
  */
 class SchemaCoordinateLexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** The previously focused non-ignored token. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** The currently focused non-ignored token. */
 
@@ -66,2 +64,4 @@ /**
    * Advances the token stream to the next non-ignored token.
+   *
+   * @internal
    */
@@ -77,2 +77,4 @@
    * the current Lexer token.
+   *
+   * @internal
    */
@@ -98,2 +100,4 @@
  * Gets the next token from the source starting at the given position.
+ *
+ * @internal
  */
@@ -100,0 +104,0 @@

language/schemaCoordinateLexer.mjs

@@ -13,12 +13,10 @@ import { syntaxError } from '../error/syntaxError.mjs';
  * whenever called.
+ *
+ * @internal
  */
 
 export class SchemaCoordinateLexer {
-  /**
-   * The previously focused non-ignored token.
-   */
+  /** The previously focused non-ignored token. */
 
-  /**
-   * The currently focused non-ignored token.
-   */
+  /** The currently focused non-ignored token. */
 
@@ -49,2 +47,4 @@ /**
    * Advances the token stream to the next non-ignored token.
+   *
+   * @internal
    */
@@ -60,2 +60,4 @@
    * the current Lexer token.
+   *
+   * @internal
    */
@@ -81,2 +83,4 @@
  * Gets the next token from the source starting at the given position.
+ *
+ * @internal
  */
@@ -83,0 +87,0 @@

language/source.d.ts

@@ -0,1 +1,2 @@
+/** @category Source */
 interface Location {
@@ -13,6 +14,33 @@ line: number;
 export declare class Source {
+  /** The GraphQL source text. */
   body: string;
+  /** Name used in diagnostics for this source, such as a file path or request name. */
   name: string;
+  /** One-indexed line and column where this source begins. */
   locationOffset: Location;
+  /**
+   * Creates a Source instance.
+   * @param body - The GraphQL source text.
+   * @param name - Name used in diagnostics for this source.
+   * @param locationOffset - One-indexed line and column where this source begins.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   *
+   * const source = new Source(
+   *   'type Query { greeting: String }',
+   *   'schema.graphql',
+   *   { line: 10, column: 1 },
+   * );
+   *
+   * source.body; // => 'type Query { greeting: String }'
+   * source.name; // => 'schema.graphql'
+   * source.locationOffset; // => { line: 10, column: 1 }
+   * ```
+   */
   constructor(body: string, name?: string, locationOffset?: Location);
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
@@ -19,0 +47,0 @@ }

language/source.js

@@ -15,2 +15,4 @@ 'use strict';
 
+/** @category Source */
+
 /**
@@ -24,2 +26,28 @@ * A representation of source input to GraphQL. The `name` and `locationOffset` parameters are
 class Source {
+  /** The GraphQL source text. */
+
+  /** Name used in diagnostics for this source, such as a file path or request name. */
+
+  /** One-indexed line and column where this source begins. */
+
+  /**
+   * Creates a Source instance.
+   * @param body - The GraphQL source text.
+   * @param name - Name used in diagnostics for this source.
+   * @param locationOffset - One-indexed line and column where this source begins.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   *
+   * const source = new Source(
+   *   'type Query { greeting: String }',
+   *   'schema.graphql',
+   *   { line: 10, column: 1 },
+   * );
+   *
+   * source.body; // => 'type Query { greeting: String }'
+   * source.name; // => 'schema.graphql'
+   * source.locationOffset; // => { line: 10, column: 1 }
+   * ```
+   */
   constructor(
@@ -52,2 +80,6 @@ body,
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -54,0 +86,0 @@ get [Symbol.toStringTag]() {

language/source.mjs

@@ -0,1 +1,2 @@
+/** @category Source */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -13,2 +14,28 @@ import { inspect } from '../jsutils/inspect.mjs';
 export class Source {
+  /** The GraphQL source text. */
+
+  /** Name used in diagnostics for this source, such as a file path or request name. */
+
+  /** One-indexed line and column where this source begins. */
+
+  /**
+   * Creates a Source instance.
+   * @param body - The GraphQL source text.
+   * @param name - Name used in diagnostics for this source.
+   * @param locationOffset - One-indexed line and column where this source begins.
+   * @example
+   * ```ts
+   * import { Source } from 'graphql/language';
+   *
+   * const source = new Source(
+   *   'type Query { greeting: String }',
+   *   'schema.graphql',
+   *   { line: 10, column: 1 },
+   * );
+   *
+   * source.body; // => 'type Query { greeting: String }'
+   * source.name; // => 'schema.graphql'
+   * source.locationOffset; // => { line: 10, column: 1 }
+   * ```
+   */
   constructor(
@@ -38,2 +65,6 @@ body,
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -40,0 +71,0 @@ get [Symbol.toStringTag]() {

language/tokenKind.d.ts

@@ -0,1 +1,2 @@
+/** @category Lexing */
 /**
@@ -6,24 +7,47 @@ * An exported enum describing the different kinds of tokens that the
 declare enum TokenKind {
+  /** Start-of-file token. */
   SOF = '<SOF>',
+  /** End-of-file token. */
   EOF = '<EOF>',
+  /** The `!` punctuation token. */
   BANG = '!',
+  /** The `$` punctuation token. */
   DOLLAR = '$',
+  /** The `&` punctuation token. */
   AMP = '&',
+  /** The `(` punctuation token. */
   PAREN_L = '(',
+  /** The `)` punctuation token. */
   PAREN_R = ')',
+  /** The `.` punctuation token. */
   DOT = '.',
+  /** The `...` spread punctuation token. */
   SPREAD = '...',
+  /** The `:` punctuation token. */
   COLON = ':',
+  /** The `=` punctuation token. */
   EQUALS = '=',
+  /** The `@` punctuation token. */
   AT = '@',
+  /** The `[` punctuation token. */
   BRACKET_L = '[',
+  /** The `]` punctuation token. */
   BRACKET_R = ']',
+  /** The `{` punctuation token. */
   BRACE_L = '{',
+  /** The `|` punctuation token. */
   PIPE = '|',
+  /** The `}` punctuation token. */
   BRACE_R = '}',
+  /** A GraphQL name token or name AST node. */
   NAME = 'Name',
+  /** An integer value token or AST node. */
   INT = 'Int',
+  /** A floating-point value token or AST node. */
   FLOAT = 'Float',
+  /** A string value token or AST node. */
   STRING = 'String',
+  /** A block string value token. */
   BLOCK_STRING = 'BlockString',
+  /** A comment token. */
   COMMENT = 'Comment',
@@ -33,6 +57,9 @@ }
 /**
- * The enum type representing the token kinds values.
- *
- * @deprecated Please use `TokenKind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing token kind values.
+ * This alias will be removed in v17. In v17, `TokenKind` is exported as the
+ * single public symbol for both the runtime object and the corresponding
+ * TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `TokenKind` as both the
+ * runtime value and the type.
  */
 export declare type TokenKindEnum = typeof TokenKind;

language/tokenKind.js

@@ -8,2 +8,4 @@ 'use strict';
 
+/** @category Lexing */
+
 /**
@@ -42,5 +44,8 @@ * An exported enum describing the different kinds of tokens that the
 /**
- * The enum type representing the token kinds values.
- *
- * @deprecated Please use `TokenKind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing token kind values.
+ * This alias will be removed in v17. In v17, `TokenKind` is exported as the
+ * single public symbol for both the runtime object and the corresponding
+ * TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `TokenKind` as both the
+ * runtime value and the type.
  */

language/tokenKind.mjs

@@ -0,1 +1,3 @@
+/** @category Lexing */
+
 /**
@@ -35,5 +37,8 @@ * An exported enum describing the different kinds of tokens that the
 /**
- * The enum type representing the token kinds values.
- *
- * @deprecated Please use `TokenKind`. Will be remove in v17.
+ * Deprecated legacy alias for the enum type representing token kind values.
+ * This alias will be removed in v17. In v17, `TokenKind` is exported as the
+ * single public symbol for both the runtime object and the corresponding
+ * TypeScript type.
+ * @deprecated Will be removed in v17. In v17, use `TokenKind` as both the
+ * runtime value and the type.
  */

language/visitor.d.ts

@@ -0,7 +1,5 @@
+/** @category Visiting */
 import type { ASTNode } from './ast';
 import { Kind } from './kinds';
-/**
- * A visitor is provided to visit, it contains the collection of
- * relevant functions to be called during the visitor's traversal.
- */
+/** A visitor defines the callbacks called during AST traversal. */
 export declare type ASTVisitor = EnterLeaveVisitor<ASTNode> | KindVisitor;
@@ -18,18 +16,18 @@ declare type KindVisitor = {
 /**
- * A visitor is comprised of visit functions, which are called on each node
- * during the visitor's traversal.
+ * A visitor is composed of visit functions called for each node during traversal.
+ * @typeParam TVisitedNode - AST node type handled by this visitor function.
  */
 export declare type ASTVisitFn<TVisitedNode extends ASTNode> = (
-  /** The current node being visiting. */
+  /** Current node being visited. */
   node: TVisitedNode,
-  /** The index or key to this node from the parent node or Array. */
+  /** Index or key for this node within the parent node or array. */
   key: string | number | undefined,
-  /** The parent immediately above this node, which may be an Array. */
+  /** Parent immediately above this node, which may be an array. */
   parent: ASTNode | ReadonlyArray<ASTNode> | undefined,
-  /** The key path to get to this node from the root node. */
+  /** Key path from the root node to this node. */
   path: ReadonlyArray<string | number>,
   /**
-   * All nodes and Arrays visited before reaching parent of this node.
+   * All nodes and arrays visited before reaching this node's parent.
    * These correspond to array indices in `path`.
-   * Note: ancestors includes arrays which contain the parent of visited node.
+   * Note: ancestors includes arrays that contain the visited node's parent.
    */
@@ -39,4 +37,5 @@ ancestors: ReadonlyArray<ASTNode | ReadonlyArray<ASTNode>>,
 /**
- * A reducer is comprised of reducer functions which convert AST nodes into
- * another form.
+ * A reducer is composed of reducer functions that convert AST nodes into another form.
+ *
+ * @internal
  */
@@ -50,16 +49,29 @@ export declare type ASTReducer<R> = {
 declare type ASTReducerFn<TReducedNode extends ASTNode, R> = (
-  /** The current node being visiting. */
+  /**
+   * Current node being visited.
+   * @internal
+   */
   node: {
     [K in keyof TReducedNode]: ReducedField<TReducedNode[K], R>;
   },
-  /** The index or key to this node from the parent node or Array. */
+  /**
+   * Index or key for this node within the parent node or array.
+   * @internal
+   */
   key: string | number | undefined,
-  /** The parent immediately above this node, which may be an Array. */
+  /**
+   * Parent immediately above this node, which may be an array.
+   * @internal
+   */
   parent: ASTNode | ReadonlyArray<ASTNode> | undefined,
-  /** The key path to get to this node from the root node. */
+  /**
+   * Key path from the root node to this node.
+   * @internal
+   */
   path: ReadonlyArray<string | number>,
   /**
-   * All nodes and Arrays visited before reaching parent of this node.
+   * All nodes and arrays visited before reaching this node's parent.
    * These correspond to array indices in `path`.
-   * Note: ancestors includes arrays which contain the parent of visited node.
+   * Note: ancestors includes arrays that contain the visited node's parent.
+   * @internal
    */
@@ -74,4 +86,4 @@ ancestors: ReadonlyArray<ASTNode | ReadonlyArray<ASTNode>>,
 /**
- * A KeyMap describes each the traversable properties of each kind of node.
- *
+ * Deprecated visitor key map type retained for compatibility. Inline this
+ * mapped type at use sites because ASTVisitorKeyMap will be removed in v17.
  * @deprecated Please inline it. Will be removed in v17
@@ -82,2 +94,3 @@ */
 };
+/** A value that can be returned from a visitor function to stop traversal. */
 export declare const BREAK: unknown;
@@ -97,65 +110,86 @@ /**
  * visit function.
+ * @param root - The AST node at which to start traversal.
+ * @param visitor - The visitor or reducer functions to call while traversing.
+ * @param visitorKeys - Optional map of child keys to visit for each AST node kind.
+ * @returns The original AST, an edited AST, or a reduced value depending on the visitor.
+ * @typeParam N - The root AST node type returned when visiting without reducing.
+ * @example
+ * ```ts
+ * // Return values control traversal: undefined makes no change, false skips
+ * // a subtree, BREAK stops traversal, null removes a node, and any other
+ * // value replaces the current node.
+ * import { Kind, parse, print, visit } from 'graphql/language';
  *
- * ```ts
- * const editedAST = visit(ast, {
- *   enter(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: skip visiting this node
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
+ * const document = parse('{ hero { name } }');
+ * const editedAST = visit(document, {
+ *   Field: (node) => {
+ *     if (node.name.value === 'hero') {
+ *       return {
+ *         ...node,
+ *         name: { kind: Kind.NAME, value: 'human' },
+ *       };
+ *     }
  *   },
- *   leave(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: no action
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
- *   }
  * });
+ *
+ * print(editedAST); // => '{\n  human {\n    name\n  }\n}'
  * ```
+ * @example
+ * ```ts
+ * // A named visitor function runs when entering nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * Alternatively to providing enter() and leave() functions, a visitor can
- * instead provide functions named the same as the kinds of AST nodes, or
- * enter/leave visitors at a named key, leading to three permutations of the
- * visitor API:
+ * const document = parse('{ hero { name } }');
+ * const fieldNames = [];
  *
- * 1) Named visitors triggered when entering a node of a specific kind.
+ * visit(document, {
+ *   Field: (node) => {
+ *     fieldNames.push(node.name.value);
+ *   },
+ * });
  *
+ * fieldNames; // => ['hero', 'name']
+ * ```
+ * @example
  * ```ts
- * visit(ast, {
- *   Kind(node) {
- *     // enter the "Kind" node
- *   }
- * })
- * ```
+ * // A named visitor object can provide separate enter and leave handlers for
+ * // nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * 2) Named visitors that trigger upon entering and leaving a node of a specific kind.
+ * const document = parse('{ hero { name } }');
+ * const events = [];
  *
+ * visit(document, {
+ *   Field: {
+ *     enter: (node) => {
+ *       events.push(`enter:${node.name.value}`);
+ *     },
+ *     leave: (node) => {
+ *       events.push(`leave:${node.name.value}`);
+ *     },
+ *   },
+ * });
+ *
+ * events; // => ['enter:hero', 'enter:name', 'leave:name', 'leave:hero']
+ * ```
+ * @example
  * ```ts
- * visit(ast, {
- *   Kind: {
- *     enter(node) {
- *       // enter the "Kind" node
- *     }
- *     leave(node) {
- *       // leave the "Kind" node
- *     }
- *   }
- * })
- * ```
+ * // Generic enter and leave handlers run for every node.
+ * import { parse, visit } from 'graphql/language';
  *
- * 3) Generic visitors that trigger upon entering and leaving any node.
+ * const document = parse('{ hero { name } }');
+ * let enterCount = 0;
+ * let leaveCount = 0;
  *
- * ```ts
- * visit(ast, {
- *   enter(node) {
- *     // enter any node
+ * visit(document, {
+ *   enter: (node) => {
+ *     enterCount += 1;
  *   },
- *   leave(node) {
- *     // leave any node
- *   }
- * })
+ *   leave: (node) => {
+ *     leaveCount += 1;
+ *   },
+ * });
+ *
+ * enterCount; // => leaveCount
+ * enterCount > 0; // => true
  * ```
@@ -168,2 +202,49 @@ */
 ): N;
+/**
+ * Traverses an AST with reducer callbacks and returns the reduced value.
+ * @param root - The AST node where traversal starts.
+ * @param visitor - Reducer callbacks to invoke during traversal.
+ * @param visitorKeys - Optional mapping of child keys for each AST node kind.
+ * @returns The value produced by the reducer visitor.
+ * @typeParam R - The value produced by reducer visitor callbacks.
+ * @example
+ * ```ts
+ * // A reducer visitor returns values from leave handlers to build a reduced
+ * // result instead of returning an edited AST.
+ * import { parse, visit } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ * const printed = visit(document, {
+ *   Name: {
+ *     leave: (node) => {
+ *       return node.value;
+ *     },
+ *   },
+ *   Field: {
+ *     leave: (node) => {
+ *       return node.selectionSet == null
+ *         ? node.name
+ *         : `${node.name} { ${node.selectionSet} }`;
+ *     },
+ *   },
+ *   SelectionSet: {
+ *     leave: (node) => {
+ *       return node.selections.join(' ');
+ *     },
+ *   },
+ *   OperationDefinition: {
+ *     leave: (node) => {
+ *       return node.selectionSet;
+ *     },
+ *   },
+ *   Document: {
+ *     leave: (node) => {
+ *       return node.definitions.join('\n');
+ *     },
+ *   },
+ * });
+ *
+ * printed; // => 'hero { name }'
+ * ```
+ */
 export declare function visit<R>(
@@ -179,2 +260,21 @@ root: ASTNode,
  * If a prior visitor edits a node, no following visitors will see that node.
+ * @param visitors - The visitors to merge into one parallel visitor.
+ * @returns A visitor that delegates traversal to each provided visitor.
+ * @example
+ * ```ts
+ * import { parse, visit, visitInParallel } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ * const events = [];
+ *
+ * visit(
+ *   document,
+ *   visitInParallel([
+ *     { Field: (node) => { events.push(`field:${node.name.value}`); } },
+ *     { Name: (node) => { events.push(`name:${node.value}`); } },
+ *   ]),
+ * );
+ *
+ * events; // => ['field:hero', 'name:hero', 'field:name', 'name:name']
+ * ```
  */
@@ -186,2 +286,14 @@ export declare function visitInParallel(
  * Given a visitor instance and a node kind, return EnterLeaveVisitor for that kind.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve handlers for.
+ * @returns The enter and leave handlers that apply for the given node kind.
+ * @example
+ * ```ts
+ * import { Kind, getEnterLeaveForKind } from 'graphql/language';
+ *
+ * const handlers = getEnterLeaveForKind({ Field: () => {} }, Kind.FIELD);
+ *
+ * typeof handlers.enter; // => 'function'
+ * handlers.leave; // => undefined
+ * ```
  */
@@ -194,4 +306,20 @@ export declare function getEnterLeaveForKind(
  * Given a visitor instance, if it is leaving or not, and a node kind, return
- * the function the visitor runtime should call.
+ * the function the visitor runtime should call. This deprecated compatibility
+ * helper delegates to `getEnterLeaveForKind`; call `getEnterLeaveForKind`
+ * directly because getVisitFn will be removed in v17.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve a handler for.
+ * @param isLeaving - Whether to resolve the leave handler instead of the enter handler.
+ * @returns The visit function that applies for the given node kind and traversal phase, if one exists.
+ * @example
+ * ```ts
+ * import { Kind, getVisitFn } from 'graphql/language';
  *
+ * const enter = getVisitFn({ Field: () => {} }, Kind.FIELD, false);
+ * const leave = getVisitFn({ Field: () => {} }, Kind.FIELD, true);
+ *
+ * typeof enter; // => 'function'
+ * leave; // => undefined
+ * ```
+ * @category Visiting
  * @deprecated Please use `getEnterLeaveForKind` instead. Will be removed in v17
@@ -198,0 +326,0 @@ */

language/visitor.js

@@ -20,2 +20,5 @@ 'use strict';
 
+/** @category Visiting */
+
+/** A value that can be returned from a visitor function to stop traversal. */
 const BREAK = Object.freeze({});
@@ -35,65 +38,86 @@ /**
  * visit function.
+ * @param root - The AST node at which to start traversal.
+ * @param visitor - The visitor or reducer functions to call while traversing.
+ * @param visitorKeys - Optional map of child keys to visit for each AST node kind.
+ * @returns The original AST, an edited AST, or a reduced value depending on the visitor.
+ * @typeParam N - The root AST node type returned when visiting without reducing.
+ * @example
+ * ```ts
+ * // Return values control traversal: undefined makes no change, false skips
+ * // a subtree, BREAK stops traversal, null removes a node, and any other
+ * // value replaces the current node.
+ * import { Kind, parse, print, visit } from 'graphql/language';
  *
- * ```ts
- * const editedAST = visit(ast, {
- *   enter(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: skip visiting this node
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
+ * const document = parse('{ hero { name } }');
+ * const editedAST = visit(document, {
+ *   Field: (node) => {
+ *     if (node.name.value === 'hero') {
+ *       return {
+ *         ...node,
+ *         name: { kind: Kind.NAME, value: 'human' },
+ *       };
+ *     }
  *   },
- *   leave(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: no action
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
- *   }
  * });
+ *
+ * print(editedAST); // => '{\n  human {\n    name\n  }\n}'
  * ```
+ * @example
+ * ```ts
+ * // A named visitor function runs when entering nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * Alternatively to providing enter() and leave() functions, a visitor can
- * instead provide functions named the same as the kinds of AST nodes, or
- * enter/leave visitors at a named key, leading to three permutations of the
- * visitor API:
+ * const document = parse('{ hero { name } }');
+ * const fieldNames = [];
  *
- * 1) Named visitors triggered when entering a node of a specific kind.
+ * visit(document, {
+ *   Field: (node) => {
+ *     fieldNames.push(node.name.value);
+ *   },
+ * });
  *
+ * fieldNames; // => ['hero', 'name']
+ * ```
+ * @example
  * ```ts
- * visit(ast, {
- *   Kind(node) {
- *     // enter the "Kind" node
- *   }
- * })
- * ```
+ * // A named visitor object can provide separate enter and leave handlers for
+ * // nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * 2) Named visitors that trigger upon entering and leaving a node of a specific kind.
+ * const document = parse('{ hero { name } }');
+ * const events = [];
  *
+ * visit(document, {
+ *   Field: {
+ *     enter: (node) => {
+ *       events.push(`enter:${node.name.value}`);
+ *     },
+ *     leave: (node) => {
+ *       events.push(`leave:${node.name.value}`);
+ *     },
+ *   },
+ * });
+ *
+ * events; // => ['enter:hero', 'enter:name', 'leave:name', 'leave:hero']
+ * ```
+ * @example
  * ```ts
- * visit(ast, {
- *   Kind: {
- *     enter(node) {
- *       // enter the "Kind" node
- *     }
- *     leave(node) {
- *       // leave the "Kind" node
- *     }
- *   }
- * })
- * ```
+ * // Generic enter and leave handlers run for every node.
+ * import { parse, visit } from 'graphql/language';
  *
- * 3) Generic visitors that trigger upon entering and leaving any node.
+ * const document = parse('{ hero { name } }');
+ * let enterCount = 0;
+ * let leaveCount = 0;
  *
- * ```ts
- * visit(ast, {
- *   enter(node) {
- *     // enter any node
+ * visit(document, {
+ *   enter: (node) => {
+ *     enterCount += 1;
  *   },
- *   leave(node) {
- *     // leave any node
- *   }
- * })
+ *   leave: (node) => {
+ *     leaveCount += 1;
+ *   },
+ * });
+ *
+ * enterCount; // => leaveCount
+ * enterCount > 0; // => true
  * ```
@@ -104,2 +128,3 @@ */
 
+/** @internal */
 function visit(root, visitor, visitorKeys = _ast.QueryDocumentKeys) {
@@ -268,2 +293,21 @@ const enterLeaveMap = new Map();
  * If a prior visitor edits a node, no following visitors will see that node.
+ * @param visitors - The visitors to merge into one parallel visitor.
+ * @returns A visitor that delegates traversal to each provided visitor.
+ * @example
+ * ```ts
+ * import { parse, visit, visitInParallel } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ * const events = [];
+ *
+ * visit(
+ *   document,
+ *   visitInParallel([
+ *     { Field: (node) => { events.push(`field:${node.name.value}`); } },
+ *     { Name: (node) => { events.push(`name:${node.value}`); } },
+ *   ]),
+ * );
+ *
+ * events; // => ['field:hero', 'name:hero', 'field:name', 'name:name']
+ * ```
  */
@@ -345,2 +389,14 @@
  * Given a visitor instance and a node kind, return EnterLeaveVisitor for that kind.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve handlers for.
+ * @returns The enter and leave handlers that apply for the given node kind.
+ * @example
+ * ```ts
+ * import { Kind, getEnterLeaveForKind } from 'graphql/language';
+ *
+ * const handlers = getEnterLeaveForKind({ Field: () => {} }, Kind.FIELD);
+ *
+ * typeof handlers.enter; // => 'function'
+ * handlers.leave; // => undefined
+ * ```
  */
@@ -369,4 +425,20 @@
  * Given a visitor instance, if it is leaving or not, and a node kind, return
- * the function the visitor runtime should call.
+ * the function the visitor runtime should call. This deprecated compatibility
+ * helper delegates to `getEnterLeaveForKind`; call `getEnterLeaveForKind`
+ * directly because getVisitFn will be removed in v17.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve a handler for.
+ * @param isLeaving - Whether to resolve the leave handler instead of the enter handler.
+ * @returns The visit function that applies for the given node kind and traversal phase, if one exists.
+ * @example
+ * ```ts
+ * import { Kind, getVisitFn } from 'graphql/language';
  *
+ * const enter = getVisitFn({ Field: () => {} }, Kind.FIELD, false);
+ * const leave = getVisitFn({ Field: () => {} }, Kind.FIELD, true);
+ *
+ * typeof enter; // => 'function'
+ * leave; // => undefined
+ * ```
+ * @category Visiting
  * @deprecated Please use `getEnterLeaveForKind` instead. Will be removed in v17
@@ -373,0 +445,0 @@ */

language/visitor.mjs

@@ -0,1 +1,2 @@
+/** @category Visiting */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -5,7 +6,5 @@ import { inspect } from '../jsutils/inspect.mjs';
 import { Kind } from './kinds.mjs';
-/**
- * A visitor is provided to visit, it contains the collection of
- * relevant functions to be called during the visitor's traversal.
- */
+/** A visitor defines the callbacks called during AST traversal. */
 
+/** A value that can be returned from a visitor function to stop traversal. */
 export const BREAK = Object.freeze({});
@@ -25,68 +24,90 @@ /**
  * visit function.
+ * @param root - The AST node at which to start traversal.
+ * @param visitor - The visitor or reducer functions to call while traversing.
+ * @param visitorKeys - Optional map of child keys to visit for each AST node kind.
+ * @returns The original AST, an edited AST, or a reduced value depending on the visitor.
+ * @typeParam N - The root AST node type returned when visiting without reducing.
+ * @example
+ * ```ts
+ * // Return values control traversal: undefined makes no change, false skips
+ * // a subtree, BREAK stops traversal, null removes a node, and any other
+ * // value replaces the current node.
+ * import { Kind, parse, print, visit } from 'graphql/language';
  *
- * ```ts
- * const editedAST = visit(ast, {
- *   enter(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: skip visiting this node
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
+ * const document = parse('{ hero { name } }');
+ * const editedAST = visit(document, {
+ *   Field: (node) => {
+ *     if (node.name.value === 'hero') {
+ *       return {
+ *         ...node,
+ *         name: { kind: Kind.NAME, value: 'human' },
+ *       };
+ *     }
  *   },
- *   leave(node, key, parent, path, ancestors) {
- *     // @return
- *     //   undefined: no action
- *     //   false: no action
- *     //   visitor.BREAK: stop visiting altogether
- *     //   null: delete this node
- *     //   any value: replace this node with the returned value
- *   }
  * });
+ *
+ * print(editedAST); // => '{\n  human {\n    name\n  }\n}'
  * ```
+ * @example
+ * ```ts
+ * // A named visitor function runs when entering nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * Alternatively to providing enter() and leave() functions, a visitor can
- * instead provide functions named the same as the kinds of AST nodes, or
- * enter/leave visitors at a named key, leading to three permutations of the
- * visitor API:
+ * const document = parse('{ hero { name } }');
+ * const fieldNames = [];
  *
- * 1) Named visitors triggered when entering a node of a specific kind.
+ * visit(document, {
+ *   Field: (node) => {
+ *     fieldNames.push(node.name.value);
+ *   },
+ * });
  *
+ * fieldNames; // => ['hero', 'name']
+ * ```
+ * @example
  * ```ts
- * visit(ast, {
- *   Kind(node) {
- *     // enter the "Kind" node
- *   }
- * })
- * ```
+ * // A named visitor object can provide separate enter and leave handlers for
+ * // nodes of that kind.
+ * import { parse, visit } from 'graphql/language';
  *
- * 2) Named visitors that trigger upon entering and leaving a node of a specific kind.
+ * const document = parse('{ hero { name } }');
+ * const events = [];
  *
+ * visit(document, {
+ *   Field: {
+ *     enter: (node) => {
+ *       events.push(`enter:${node.name.value}`);
+ *     },
+ *     leave: (node) => {
+ *       events.push(`leave:${node.name.value}`);
+ *     },
+ *   },
+ * });
+ *
+ * events; // => ['enter:hero', 'enter:name', 'leave:name', 'leave:hero']
+ * ```
+ * @example
  * ```ts
- * visit(ast, {
- *   Kind: {
- *     enter(node) {
- *       // enter the "Kind" node
- *     }
- *     leave(node) {
- *       // leave the "Kind" node
- *     }
- *   }
- * })
- * ```
+ * // Generic enter and leave handlers run for every node.
+ * import { parse, visit } from 'graphql/language';
  *
- * 3) Generic visitors that trigger upon entering and leaving any node.
+ * const document = parse('{ hero { name } }');
+ * let enterCount = 0;
+ * let leaveCount = 0;
  *
- * ```ts
- * visit(ast, {
- *   enter(node) {
- *     // enter any node
+ * visit(document, {
+ *   enter: (node) => {
+ *     enterCount += 1;
  *   },
- *   leave(node) {
- *     // leave any node
- *   }
- * })
+ *   leave: (node) => {
+ *     leaveCount += 1;
+ *   },
+ * });
+ *
+ * enterCount; // => leaveCount
+ * enterCount > 0; // => true
  * ```
  */
 
+/** @internal */
 export function visit(root, visitor, visitorKeys = QueryDocumentKeys) {
@@ -251,2 +272,21 @@ const enterLeaveMap = new Map();
  * If a prior visitor edits a node, no following visitors will see that node.
+ * @param visitors - The visitors to merge into one parallel visitor.
+ * @returns A visitor that delegates traversal to each provided visitor.
+ * @example
+ * ```ts
+ * import { parse, visit, visitInParallel } from 'graphql/language';
+ *
+ * const document = parse('{ hero { name } }');
+ * const events = [];
+ *
+ * visit(
+ *   document,
+ *   visitInParallel([
+ *     { Field: (node) => { events.push(`field:${node.name.value}`); } },
+ *     { Name: (node) => { events.push(`name:${node.value}`); } },
+ *   ]),
+ * );
+ *
+ * events; // => ['field:hero', 'name:hero', 'field:name', 'name:name']
+ * ```
  */
@@ -328,2 +368,14 @@
  * Given a visitor instance and a node kind, return EnterLeaveVisitor for that kind.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve handlers for.
+ * @returns The enter and leave handlers that apply for the given node kind.
+ * @example
+ * ```ts
+ * import { Kind, getEnterLeaveForKind } from 'graphql/language';
+ *
+ * const handlers = getEnterLeaveForKind({ Field: () => {} }, Kind.FIELD);
+ *
+ * typeof handlers.enter; // => 'function'
+ * handlers.leave; // => undefined
+ * ```
  */
@@ -352,4 +404,20 @@
  * Given a visitor instance, if it is leaving or not, and a node kind, return
- * the function the visitor runtime should call.
+ * the function the visitor runtime should call. This deprecated compatibility
+ * helper delegates to `getEnterLeaveForKind`; call `getEnterLeaveForKind`
+ * directly because getVisitFn will be removed in v17.
+ * @param visitor - The visitor object to inspect.
+ * @param kind - The AST node kind to resolve a handler for.
+ * @param isLeaving - Whether to resolve the leave handler instead of the enter handler.
+ * @returns The visit function that applies for the given node kind and traversal phase, if one exists.
+ * @example
+ * ```ts
+ * import { Kind, getVisitFn } from 'graphql/language';
  *
+ * const enter = getVisitFn({ Field: () => {} }, Kind.FIELD, false);
+ * const leave = getVisitFn({ Field: () => {} }, Kind.FIELD, true);
+ *
+ * typeof enter; // => 'function'
+ * leave; // => undefined
+ * ```
+ * @category Visiting
  * @deprecated Please use `getEnterLeaveForKind` instead. Will be removed in v17
@@ -356,0 +424,0 @@ */

package.json

 {
   "name": "graphql",
-  "version": "16.14.0",
+  "version": "16.14.1",
   "description": "A Query Language and Runtime which can target any service.",
@@ -5,0 +5,0 @@ "license": "MIT",

subscription/index.d.ts

@@ -8,13 +8,19 @@ /**
  * currently re-exports the moved functions from the `graphql/execution`
- * module. In the next major release, the `graphql/subscription` module
- * will be dropped entirely.
+ * module. In v17, the `graphql/subscription` module will be dropped entirely.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ * @category Subscriptions
  */
 import type { ExecutionArgs } from '../execution/execute';
 /**
- * @deprecated use ExecutionArgs instead. Will be removed in v17
+ * Deprecated legacy alias for ExecutionArgs retained by the subscription
+ * module. Use `ExecutionArgs` directly instead because SubscriptionArgs will be
+ * removed in v17.
  *
  * ExecutionArgs has been broadened to include all properties within SubscriptionArgs.
  * The SubscriptionArgs type is retained for backwards compatibility.
+ * @deprecated use ExecutionArgs instead. Will be removed in v17
  */
 export interface SubscriptionArgs extends ExecutionArgs {}
 export { subscribe, createSourceEventStream } from '../execution/subscribe';

subscription/index.mjs

@@ -8,13 +8,19 @@ /**
  * currently re-exports the moved functions from the `graphql/execution`
- * module. In the next major release, the `graphql/subscription` module
- * will be dropped entirely.
+ * module. In v17, the `graphql/subscription` module will be dropped entirely.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ * @category Subscriptions
  */
 
 /**
- * @deprecated use ExecutionArgs instead. Will be removed in v17
+ * Deprecated legacy alias for ExecutionArgs retained by the subscription
+ * module. Use `ExecutionArgs` directly instead because SubscriptionArgs will be
+ * removed in v17.
  *
  * ExecutionArgs has been broadened to include all properties within SubscriptionArgs.
  * The SubscriptionArgs type is retained for backwards compatibility.
+ * @deprecated use ExecutionArgs instead. Will be removed in v17
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export { subscribe, createSourceEventStream } from '../execution/subscribe.mjs';

type/assertName.d.ts

@@ -0,3 +1,13 @@
+/** @category Names */
 /**
  * Upholds the spec rules about naming.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertName } from 'graphql/type';
+ *
+ * assertName('User'); // => 'User'
+ * assertName('123User'); // throws an error
+ * ```
  */
@@ -7,5 +17,12 @@ export declare function assertName(name: string): string;
  * Upholds the spec rules about naming enum values.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertEnumValueName } from 'graphql/type';
  *
- * @internal
+ * assertEnumValueName('ACTIVE'); // => 'ACTIVE'
+ * assertEnumValueName('true'); // throws an error
+ * ```
  */
 export declare function assertEnumValueName(name: string): string;

type/assertName.js

@@ -15,4 +15,15 @@ 'use strict';
 
+/** @category Names */
+
 /**
  * Upholds the spec rules about naming.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertName } from 'graphql/type';
+ *
+ * assertName('User'); // => 'User'
+ * assertName('123User'); // throws an error
+ * ```
  */
@@ -48,4 +59,11 @@ function assertName(name) {
  * Upholds the spec rules about naming enum values.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertEnumValueName } from 'graphql/type';
  *
- * @internal
+ * assertEnumValueName('ACTIVE'); // => 'ACTIVE'
+ * assertEnumValueName('true'); // throws an error
+ * ```
  */
@@ -52,0 +70,0 @@

type/assertName.mjs

@@ -0,1 +1,2 @@
+/** @category Names */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -6,2 +7,11 @@ import { GraphQLError } from '../error/GraphQLError.mjs';
  * Upholds the spec rules about naming.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertName } from 'graphql/type';
+ *
+ * assertName('User'); // => 'User'
+ * assertName('123User'); // throws an error
+ * ```
  */
@@ -35,4 +45,11 @@
  * Upholds the spec rules about naming enum values.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertEnumValueName } from 'graphql/type';
  *
- * @internal
+ * assertEnumValueName('ACTIVE'); // => 'ACTIVE'
+ * assertEnumValueName('true'); // throws an error
+ * ```
  */
@@ -39,0 +56,0 @@

type/directives.d.ts

@@ -0,1 +1,2 @@
+/** @category Directives */
 import type { Maybe } from '../jsutils/Maybe';
@@ -13,2 +14,17 @@ import type {
  * Test if the given value is a GraphQL directive.
+ * @param directive - Value to inspect.
+ * @returns True when the value is a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { GraphQLDirective, GraphQLString, isDirective } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isDirective(upper); // => true
+ * isDirective(GraphQLString); // => false
+ * ```
  */
@@ -18,6 +34,23 @@ export declare function isDirective(
 ): directive is GraphQLDirective;
+/**
+ * Returns the value as a GraphQLDirective, or throws if it is not a directive.
+ * @param directive - Value to inspect.
+ * @returns The value typed as a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { assertDirective, GraphQLDirective, GraphQLString } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * assertDirective(upper); // => upper
+ * assertDirective(GraphQLString); // throws an error
+ * ```
+ */
 export declare function assertDirective(directive: unknown): GraphQLDirective;
 /**
  * Custom extensions
- *
  * @remarks
@@ -37,26 +70,156 @@ * Use a unique identifier name for your extension, for example the name of
 export declare class GraphQLDirective {
+  /** The GraphQL name for this schema element. */
   name: string;
+  /** Human-readable description for this schema element, if provided. */
   description: Maybe<string>;
+  /** Locations where this directive may be applied. */
   locations: ReadonlyArray<DirectiveLocation>;
+  /** Arguments accepted by this field or directive. */
   args: ReadonlyArray<GraphQLArgument>;
+  /** Whether this directive may appear more than once at the same location. */
   isRepeatable: boolean;
+  /** Reason this element is deprecated, if one was provided. */
   deprecationReason: Maybe<string>;
+  /** Extension fields to include in the formatted result. */
   extensions: Readonly<GraphQLDirectiveExtensions>;
+  /** AST node from which this schema element was built, if available. */
   astNode: Maybe<DirectiveDefinitionNode>;
+  /** AST extension nodes applied to this schema element. */
   extensionASTNodes: ReadonlyArray<DirectiveExtensionNode>;
+  /**
+   * Creates a GraphQLDirective instance.
+   * @param config - Configuration describing this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation, parse } from 'graphql/language';
+   * import {
+   *   GraphQLBoolean,
+   *   GraphQLDirective,
+   *   GraphQLInt,
+   *   GraphQLNonNull,
+   * } from 'graphql/type';
+   *
+   * const document = parse(`
+   *   directive @cacheControl(maxAge: Int) repeatable on FIELD_DEFINITION
+   *   extend directive @cacheControl(maxAge: Int) on FIELD_DEFINITION
+   * `);
+   * const definition = document.definitions[0];
+   *
+   * const cacheControl = new GraphQLDirective({
+   *   name: 'cacheControl',
+   *   description: 'Controls HTTP cache hints for a field.',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     inheritMaxAge: {
+   *       description: 'Inherit the parent cache hint.',
+   *       type: new GraphQLNonNull(GraphQLBoolean),
+   *       defaultValue: false,
+   *       deprecationReason: 'Use maxAge instead.',
+   *       extensions: { scope: 'cache' },
+   *     },
+   *     maxAge: {
+   *       type: GraphQLInt,
+   *       astNode: definition.arguments[0],
+   *     },
+   *   },
+   *   isRepeatable: true,
+   *   deprecationReason: 'Use @cache instead.',
+   *   extensions: { scope: 'cache' },
+   *   astNode: definition,
+   *   extensionASTNodes: [ document.definitions[1] ],
+   * });
+   *
+   * cacheControl.name; // => 'cacheControl'
+   * cacheControl.description; // => 'Controls HTTP cache hints for a field.'
+   * cacheControl.args[0].name; // => 'inheritMaxAge'
+   * cacheControl.args[0].defaultValue; // => false
+   * cacheControl.isRepeatable; // => true
+   * cacheControl.extensions; // => { scope: 'cache' }
+   * ```
+   */
   constructor(config: Readonly<GraphQLDirectiveConfig>);
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * Returns a normalized configuration object for this object.
+   * @returns A configuration object that can be used to recreate this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective, GraphQLString } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     name: { type: GraphQLString },
+   *   },
+   * });
+   *
+   * const config = tag.toConfig();
+   * const tagCopy = new GraphQLDirective(config);
+   *
+   * config.args.name.type; // => GraphQLString
+   * tagCopy.args[0].name; // => 'name'
+   * ```
+   */
   toConfig(): GraphQLDirectiveNormalizedConfig;
+  /**
+   * Returns the schema coordinate identifying this directive.
+   * @returns The directive schema coordinate.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toString(); // => '@tag'
+   * ```
+   */
   toString(): string;
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toJSON(); // => '@tag'
+   * JSON.stringify({ directive: tag }); // => '{"directive":"@tag"}'
+   * ```
+   */
   toJSON(): string;
 }
+/** Configuration used to construct a GraphQLDirective. */
 export interface GraphQLDirectiveConfig {
+  /** The GraphQL name for this schema element. */
   name: string;
+  /** Human-readable description for this schema element, if provided. */
   description?: Maybe<string>;
+  /** Locations where this directive may be applied. */
   locations: ReadonlyArray<DirectiveLocation>;
+  /** Arguments accepted by this field or directive. */
   args?: Maybe<GraphQLFieldConfigArgumentMap>;
+  /** Whether this directive may appear more than once at the same location. */
   isRepeatable?: Maybe<boolean>;
+  /** Reason this element is deprecated, if one was provided. */
   deprecationReason?: Maybe<string>;
+  /** Extension fields to include in the formatted result. */
   extensions?: Maybe<Readonly<GraphQLDirectiveExtensions>>;
+  /** AST node from which this schema element was built, if available. */
   astNode?: Maybe<DirectiveDefinitionNode>;
+  /** AST extension nodes applied to this schema element. */
   extensionASTNodes?: Maybe<ReadonlyArray<DirectiveExtensionNode>>;
@@ -70,30 +233,42 @@ }
 }
-/**
- * Used to conditionally include fields or fragments.
- */
+/** Used to conditionally include fields or fragments. */
 export declare const GraphQLIncludeDirective: GraphQLDirective;
-/**
- * Used to conditionally skip (exclude) fields or fragments.
- */
+/** Used to conditionally skip (exclude) fields or fragments. */
 export declare const GraphQLSkipDirective: GraphQLDirective;
-/**
- * Constant string used for default reason for a deprecation.
- */
+/** Constant string used for default reason for a deprecation. */
 export declare const DEFAULT_DEPRECATION_REASON = 'No longer supported';
 /**
  * Used to declare element of a GraphQL schema as deprecated.
+ *
+ * The optional `reason` argument defaults to `DEFAULT_DEPRECATION_REASON`.
  */
 export declare const GraphQLDeprecatedDirective: GraphQLDirective;
-/**
- * Used to provide a URL for specifying the behavior of custom scalar definitions.
- */
+/** Used to provide a URL for specifying the behavior of custom scalar definitions. */
 export declare const GraphQLSpecifiedByDirective: GraphQLDirective;
-/**
- * Used to indicate an Input Object is a OneOf Input Object.
- */
+/** Used to indicate an Input Object is a OneOf Input Object. */
 export declare const GraphQLOneOfDirective: GraphQLDirective;
+/** Full list of stable directives specified by GraphQL.js. */
+export declare const specifiedDirectives: ReadonlyArray<GraphQLDirective>;
 /**
- * The full list of specified directives.
+ * Returns true when the directive is one of the directives specified by GraphQL.
+ * @param directive - Directive to inspect.
+ * @returns True when the directive is specified by GraphQL.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLDirective,
+ *   GraphQLIncludeDirective,
+ *   isSpecifiedDirective,
+ * } from 'graphql/type';
+ * import { DirectiveLocation } from 'graphql/language';
+ *
+ * const customDirective = new GraphQLDirective({
+ *   name: 'auth',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isSpecifiedDirective(GraphQLIncludeDirective); // => true
+ * isSpecifiedDirective(customDirective); // => false
+ * ```
  */
-export declare const specifiedDirectives: ReadonlyArray<GraphQLDirective>;
 export declare function isSpecifiedDirective(
@@ -100,0 +275,0 @@ directive: GraphQLDirective,

type/directives.js

@@ -37,4 +37,21 @@ 'use strict';
 
+/** @category Directives */
+
 /**
  * Test if the given value is a GraphQL directive.
+ * @param directive - Value to inspect.
+ * @returns True when the value is a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { GraphQLDirective, GraphQLString, isDirective } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isDirective(upper); // => true
+ * isDirective(GraphQLString); // => false
+ * ```
  */
@@ -44,2 +61,20 @@ function isDirective(directive) {
 }
+/**
+ * Returns the value as a GraphQLDirective, or throws if it is not a directive.
+ * @param directive - Value to inspect.
+ * @returns The value typed as a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { assertDirective, GraphQLDirective, GraphQLString } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * assertDirective(upper); // => upper
+ * assertDirective(GraphQLString); // throws an error
+ * ```
+ */
 
@@ -57,3 +92,2 @@ function assertDirective(directive) {
  * Custom extensions
- *
  * @remarks
@@ -71,2 +105,71 @@ * Use a unique identifier name for your extension, for example the name of
 class GraphQLDirective {
+  /** The GraphQL name for this schema element. */
+
+  /** Human-readable description for this schema element, if provided. */
+
+  /** Locations where this directive may be applied. */
+
+  /** Arguments accepted by this field or directive. */
+
+  /** Whether this directive may appear more than once at the same location. */
+
+  /** Reason this element is deprecated, if one was provided. */
+
+  /** Extension fields to include in the formatted result. */
+
+  /** AST node from which this schema element was built, if available. */
+
+  /** AST extension nodes applied to this schema element. */
+
+  /**
+   * Creates a GraphQLDirective instance.
+   * @param config - Configuration describing this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation, parse } from 'graphql/language';
+   * import {
+   *   GraphQLBoolean,
+   *   GraphQLDirective,
+   *   GraphQLInt,
+   *   GraphQLNonNull,
+   * } from 'graphql/type';
+   *
+   * const document = parse(`
+   *   directive @cacheControl(maxAge: Int) repeatable on FIELD_DEFINITION
+   *   extend directive @cacheControl(maxAge: Int) on FIELD_DEFINITION
+   * `);
+   * const definition = document.definitions[0];
+   *
+   * const cacheControl = new GraphQLDirective({
+   *   name: 'cacheControl',
+   *   description: 'Controls HTTP cache hints for a field.',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     inheritMaxAge: {
+   *       description: 'Inherit the parent cache hint.',
+   *       type: new GraphQLNonNull(GraphQLBoolean),
+   *       defaultValue: false,
+   *       deprecationReason: 'Use maxAge instead.',
+   *       extensions: { scope: 'cache' },
+   *     },
+   *     maxAge: {
+   *       type: GraphQLInt,
+   *       astNode: definition.arguments[0],
+   *     },
+   *   },
+   *   isRepeatable: true,
+   *   deprecationReason: 'Use @cache instead.',
+   *   extensions: { scope: 'cache' },
+   *   astNode: definition,
+   *   extensionASTNodes: [ document.definitions[1] ],
+   * });
+   *
+   * cacheControl.name; // => 'cacheControl'
+   * cacheControl.description; // => 'Controls HTTP cache hints for a field.'
+   * cacheControl.args[0].name; // => 'inheritMaxAge'
+   * cacheControl.args[0].defaultValue; // => false
+   * cacheControl.isRepeatable; // => true
+   * cacheControl.extensions; // => { scope: 'cache' }
+   * ```
+   */
   constructor(config) {
@@ -107,2 +210,6 @@ var _config$isRepeatable, _config$extensionASTN, _config$args;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -112,2 +219,25 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns a normalized configuration object for this object.
+   * @returns A configuration object that can be used to recreate this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective, GraphQLString } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     name: { type: GraphQLString },
+   *   },
+   * });
+   *
+   * const config = tag.toConfig();
+   * const tagCopy = new GraphQLDirective(config);
+   *
+   * config.args.name.type; // => GraphQLString
+   * tagCopy.args[0].name; // => 'name'
+   * ```
+   */
 
@@ -127,2 +257,18 @@ toConfig() {
   }
+  /**
+   * Returns the schema coordinate identifying this directive.
+   * @returns The directive schema coordinate.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toString(); // => '@tag'
+   * ```
+   */
 
@@ -132,2 +278,19 @@ toString() {
   }
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toJSON(); // => '@tag'
+   * JSON.stringify({ directive: tag }); // => '{"directive":"@tag"}'
+   * ```
+   */
 
@@ -138,8 +301,7 @@ toJSON() {
 }
+/** Configuration used to construct a GraphQLDirective. */
 
 exports.GraphQLDirective = GraphQLDirective;
 
-/**
- * Used to conditionally include fields or fragments.
- */
+/** Used to conditionally include fields or fragments. */
 const GraphQLIncludeDirective = new GraphQLDirective({
@@ -161,5 +323,3 @@ name: 'include',
 });
-/**
- * Used to conditionally skip (exclude) fields or fragments.
- */
+/** Used to conditionally skip (exclude) fields or fragments. */
 
@@ -183,5 +343,3 @@ exports.GraphQLIncludeDirective = GraphQLIncludeDirective;
 });
-/**
- * Constant string used for default reason for a deprecation.
- */
+/** Constant string used for default reason for a deprecation. */
 
@@ -192,2 +350,4 @@ exports.GraphQLSkipDirective = GraphQLSkipDirective;
  * Used to declare element of a GraphQL schema as deprecated.
+ *
+ * The optional `reason` argument defaults to `DEFAULT_DEPRECATION_REASON`.
  */
@@ -215,5 +375,3 @@
 });
-/**
- * Used to provide a URL for specifying the behavior of custom scalar definitions.
- */
+/** Used to provide a URL for specifying the behavior of custom scalar definitions. */
 
@@ -232,5 +390,3 @@ exports.GraphQLDeprecatedDirective = GraphQLDeprecatedDirective;
 });
-/**
- * Used to indicate an Input Object is a OneOf Input Object.
- */
+/** Used to indicate an Input Object is a OneOf Input Object. */
 
@@ -245,5 +401,3 @@ exports.GraphQLSpecifiedByDirective = GraphQLSpecifiedByDirective;
 });
-/**
- * The full list of specified directives.
- */
+/** Full list of stable directives specified by GraphQL.js. */
 
@@ -258,2 +412,25 @@ exports.GraphQLOneOfDirective = GraphQLOneOfDirective;
 ]);
+/**
+ * Returns true when the directive is one of the directives specified by GraphQL.
+ * @param directive - Directive to inspect.
+ * @returns True when the directive is specified by GraphQL.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLDirective,
+ *   GraphQLIncludeDirective,
+ *   isSpecifiedDirective,
+ * } from 'graphql/type';
+ * import { DirectiveLocation } from 'graphql/language';
+ *
+ * const customDirective = new GraphQLDirective({
+ *   name: 'auth',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isSpecifiedDirective(GraphQLIncludeDirective); // => true
+ * isSpecifiedDirective(customDirective); // => false
+ * ```
+ */
+
 exports.specifiedDirectives = specifiedDirectives;
@@ -260,0 +437,0 @@

type/directives.mjs

@@ -0,1 +1,2 @@
+/** @category Directives */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -16,2 +17,17 @@ import { inspect } from '../jsutils/inspect.mjs';
  * Test if the given value is a GraphQL directive.
+ * @param directive - Value to inspect.
+ * @returns True when the value is a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { GraphQLDirective, GraphQLString, isDirective } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isDirective(upper); // => true
+ * isDirective(GraphQLString); // => false
+ * ```
  */
@@ -22,2 +38,21 @@
 }
+/**
+ * Returns the value as a GraphQLDirective, or throws if it is not a directive.
+ * @param directive - Value to inspect.
+ * @returns The value typed as a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { assertDirective, GraphQLDirective, GraphQLString } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * assertDirective(upper); // => upper
+ * assertDirective(GraphQLString); // throws an error
+ * ```
+ */
+
 export function assertDirective(directive) {
@@ -34,3 +69,2 @@ if (!isDirective(directive)) {
  * Custom extensions
- *
  * @remarks
@@ -48,2 +82,71 @@ * Use a unique identifier name for your extension, for example the name of
 export class GraphQLDirective {
+  /** The GraphQL name for this schema element. */
+
+  /** Human-readable description for this schema element, if provided. */
+
+  /** Locations where this directive may be applied. */
+
+  /** Arguments accepted by this field or directive. */
+
+  /** Whether this directive may appear more than once at the same location. */
+
+  /** Reason this element is deprecated, if one was provided. */
+
+  /** Extension fields to include in the formatted result. */
+
+  /** AST node from which this schema element was built, if available. */
+
+  /** AST extension nodes applied to this schema element. */
+
+  /**
+   * Creates a GraphQLDirective instance.
+   * @param config - Configuration describing this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation, parse } from 'graphql/language';
+   * import {
+   *   GraphQLBoolean,
+   *   GraphQLDirective,
+   *   GraphQLInt,
+   *   GraphQLNonNull,
+   * } from 'graphql/type';
+   *
+   * const document = parse(`
+   *   directive @cacheControl(maxAge: Int) repeatable on FIELD_DEFINITION
+   *   extend directive @cacheControl(maxAge: Int) on FIELD_DEFINITION
+   * `);
+   * const definition = document.definitions[0];
+   *
+   * const cacheControl = new GraphQLDirective({
+   *   name: 'cacheControl',
+   *   description: 'Controls HTTP cache hints for a field.',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     inheritMaxAge: {
+   *       description: 'Inherit the parent cache hint.',
+   *       type: new GraphQLNonNull(GraphQLBoolean),
+   *       defaultValue: false,
+   *       deprecationReason: 'Use maxAge instead.',
+   *       extensions: { scope: 'cache' },
+   *     },
+   *     maxAge: {
+   *       type: GraphQLInt,
+   *       astNode: definition.arguments[0],
+   *     },
+   *   },
+   *   isRepeatable: true,
+   *   deprecationReason: 'Use @cache instead.',
+   *   extensions: { scope: 'cache' },
+   *   astNode: definition,
+   *   extensionASTNodes: [ document.definitions[1] ],
+   * });
+   *
+   * cacheControl.name; // => 'cacheControl'
+   * cacheControl.description; // => 'Controls HTTP cache hints for a field.'
+   * cacheControl.args[0].name; // => 'inheritMaxAge'
+   * cacheControl.args[0].defaultValue; // => false
+   * cacheControl.isRepeatable; // => true
+   * cacheControl.extensions; // => { scope: 'cache' }
+   * ```
+   */
   constructor(config) {
@@ -81,2 +184,6 @@ var _config$isRepeatable, _config$extensionASTN, _config$args;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -86,2 +193,25 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns a normalized configuration object for this object.
+   * @returns A configuration object that can be used to recreate this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective, GraphQLString } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     name: { type: GraphQLString },
+   *   },
+   * });
+   *
+   * const config = tag.toConfig();
+   * const tagCopy = new GraphQLDirective(config);
+   *
+   * config.args.name.type; // => GraphQLString
+   * tagCopy.args[0].name; // => 'name'
+   * ```
+   */
 
@@ -101,2 +231,18 @@ toConfig() {
   }
+  /**
+   * Returns the schema coordinate identifying this directive.
+   * @returns The directive schema coordinate.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toString(); // => '@tag'
+   * ```
+   */
 
@@ -106,2 +252,19 @@ toString() {
   }
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toJSON(); // => '@tag'
+   * JSON.stringify({ directive: tag }); // => '{"directive":"@tag"}'
+   * ```
+   */
 
@@ -112,6 +275,5 @@ toJSON() {
 }
+/** Configuration used to construct a GraphQLDirective. */
 
-/**
- * Used to conditionally include fields or fragments.
- */
+/** Used to conditionally include fields or fragments. */
 export const GraphQLIncludeDirective = new GraphQLDirective({
@@ -133,5 +295,3 @@ name: 'include',
 });
-/**
- * Used to conditionally skip (exclude) fields or fragments.
- */
+/** Used to conditionally skip (exclude) fields or fragments. */
 
@@ -154,5 +314,3 @@ export const GraphQLSkipDirective = new GraphQLDirective({
 });
-/**
- * Constant string used for default reason for a deprecation.
- */
+/** Constant string used for default reason for a deprecation. */
 
@@ -162,2 +320,4 @@ export const DEFAULT_DEPRECATION_REASON = 'No longer supported';
  * Used to declare element of a GraphQL schema as deprecated.
+ *
+ * The optional `reason` argument defaults to `DEFAULT_DEPRECATION_REASON`.
  */
@@ -184,5 +344,3 @@
 });
-/**
- * Used to provide a URL for specifying the behavior of custom scalar definitions.
- */
+/** Used to provide a URL for specifying the behavior of custom scalar definitions. */
 
@@ -200,5 +358,3 @@ export const GraphQLSpecifiedByDirective = new GraphQLDirective({
 });
-/**
- * Used to indicate an Input Object is a OneOf Input Object.
- */
+/** Used to indicate an Input Object is a OneOf Input Object. */
 
@@ -212,5 +368,3 @@ export const GraphQLOneOfDirective = new GraphQLDirective({
 });
-/**
- * The full list of specified directives.
- */
+/** Full list of stable directives specified by GraphQL.js. */
 
@@ -224,4 +378,27 @@ export const specifiedDirectives = Object.freeze([
 ]);
+/**
+ * Returns true when the directive is one of the directives specified by GraphQL.
+ * @param directive - Directive to inspect.
+ * @returns True when the directive is specified by GraphQL.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLDirective,
+ *   GraphQLIncludeDirective,
+ *   isSpecifiedDirective,
+ * } from 'graphql/type';
+ * import { DirectiveLocation } from 'graphql/language';
+ *
+ * const customDirective = new GraphQLDirective({
+ *   name: 'auth',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isSpecifiedDirective(GraphQLIncludeDirective); // => true
+ * isSpecifiedDirective(customDirective); // => false
+ * ```
+ */
+
 export function isSpecifiedDirective(directive) {
   return specifiedDirectives.some(({ name }) => name === directive.name);
 }

type/index.d.ts

@@ -0,1 +1,7 @@
+/**
+ * Create and inspect GraphQL type definitions and schemas.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export type { Path as ResponsePath } from '../jsutils/Path';
@@ -2,0 +8,0 @@ export { isSchema, assertSchema, GraphQLSchema } from './schema';

type/index.mjs

@@ -0,1 +1,7 @@
+/**
+ * Create and inspect GraphQL type definitions and schemas.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export {
@@ -2,0 +8,0 @@ // Predicate

type/introspection.d.ts

@@ -0,21 +1,42 @@
+/** @category Introspection */
 import type { GraphQLField, GraphQLNamedType } from './definition';
 import { GraphQLEnumType, GraphQLObjectType } from './definition';
+/** The introspection type describing a GraphQL schema. */
 export declare const __Schema: GraphQLObjectType;
+/** The introspection type describing a GraphQL directive. */
 export declare const __Directive: GraphQLObjectType;
+/** The introspection enum describing directive locations. */
 export declare const __DirectiveLocation: GraphQLEnumType;
+/** The introspection type describing GraphQL types. */
 export declare const __Type: GraphQLObjectType;
+/** The introspection type describing object and interface fields. */
 export declare const __Field: GraphQLObjectType;
+/** The introspection type describing arguments and input fields. */
 export declare const __InputValue: GraphQLObjectType;
+/** The introspection type describing enum values. */
 export declare const __EnumValue: GraphQLObjectType;
+/**
+ * The introspection enum describing the different kinds of GraphQL types.
+ * @category Introspection
+ */
 declare enum TypeKind {
+  /** A scalar type. */
   SCALAR = 'SCALAR',
+  /** An object type. */
   OBJECT = 'OBJECT',
+  /** An interface type. */
   INTERFACE = 'INTERFACE',
+  /** A union type. */
   UNION = 'UNION',
+  /** An enum type. */
   ENUM = 'ENUM',
+  /** An input object type. */
   INPUT_OBJECT = 'INPUT_OBJECT',
+  /** A list wrapper type. */
   LIST = 'LIST',
+  /** A non-null wrapper type. */
   NON_NULL = 'NON_NULL',
 }
 export { TypeKind };
+/** The introspection enum describing GraphQL type kinds. */
 export declare const __TypeKind: GraphQLEnumType;
@@ -27,5 +48,20 @@ /**
 export declare const SchemaMetaFieldDef: GraphQLField<unknown, unknown>;
+/** The `__type` meta field definition used by introspection. */
 export declare const TypeMetaFieldDef: GraphQLField<unknown, unknown>;
+/** The `__typename` meta field definition used by execution and introspection. */
 export declare const TypeNameMetaFieldDef: GraphQLField<unknown, unknown>;
+/** All introspection types defined by the GraphQL specification. */
 export declare const introspectionTypes: ReadonlyArray<GraphQLNamedType>;
+/**
+ * Returns true when the type is one of the built-in introspection types.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the type is one of the built-in introspection types.
+ * @example
+ * ```ts
+ * import { GraphQLString, isIntrospectionType, __Type } from 'graphql/type';
+ *
+ * isIntrospectionType(__Type); // => true
+ * isIntrospectionType(GraphQLString); // => false
+ * ```
+ */
 export declare function isIntrospectionType(type: GraphQLNamedType): boolean;

type/introspection.js

@@ -36,2 +36,5 @@ 'use strict';
 
+/** @category Introspection */
+
+/** The introspection type describing a GraphQL schema. */
 const __Schema = new _definition.GraphQLObjectType({
@@ -95,2 +98,3 @@ name: '__Schema',
 });
+/** The introspection type describing a GraphQL directive. */
 
@@ -153,2 +157,3 @@ exports.__Schema = __Schema;
 });
+/** The introspection enum describing directive locations. */
 
@@ -244,2 +249,3 @@ exports.__Directive = __Directive;
 });
+/** The introspection type describing GraphQL types. */
 
@@ -413,2 +419,3 @@ exports.__DirectiveLocation = __DirectiveLocation;
 });
+/** The introspection type describing object and interface fields. */
 
@@ -463,2 +470,3 @@ exports.__Type = __Type;
 });
+/** The introspection type describing arguments and input fields. */
 
@@ -505,2 +513,3 @@ exports.__Field = __Field;
 });
+/** The introspection type describing enum values. */
 
@@ -532,2 +541,6 @@ exports.__InputValue = __InputValue;
 });
+/**
+ * The introspection enum describing the different kinds of GraphQL types.
+ * @category Introspection
+ */
 
@@ -549,2 +562,3 @@ exports.__EnumValue = __EnumValue;
 
+/** The introspection enum describing GraphQL type kinds. */
 const __TypeKind = new _definition.GraphQLEnumType({
@@ -610,2 +624,4 @@ name: '__TypeKind',
 };
+/** The `__type` meta field definition used by introspection. */
+
 exports.SchemaMetaFieldDef = SchemaMetaFieldDef;
@@ -632,2 +648,4 @@ const TypeMetaFieldDef = {
 };
+/** The `__typename` meta field definition used by execution and introspection. */
+
 exports.TypeMetaFieldDef = TypeMetaFieldDef;
@@ -644,2 +662,4 @@ const TypeNameMetaFieldDef = {
 };
+/** All introspection types defined by the GraphQL specification. */
+
 exports.TypeNameMetaFieldDef = TypeNameMetaFieldDef;
@@ -656,2 +676,15 @@ const introspectionTypes = Object.freeze([
 ]);
+/**
+ * Returns true when the type is one of the built-in introspection types.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the type is one of the built-in introspection types.
+ * @example
+ * ```ts
+ * import { GraphQLString, isIntrospectionType, __Type } from 'graphql/type';
+ *
+ * isIntrospectionType(__Type); // => true
+ * isIntrospectionType(GraphQLString); // => false
+ * ```
+ */
+
 exports.introspectionTypes = introspectionTypes;
@@ -658,0 +691,0 @@

type/introspection.mjs

@@ -0,1 +1,2 @@
+/** @category Introspection */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -22,2 +23,4 @@ import { invariant } from '../jsutils/invariant.mjs';
 import { GraphQLBoolean, GraphQLString } from './scalars.mjs';
+
+/** The introspection type describing a GraphQL schema. */
 export const __Schema = new GraphQLObjectType({
@@ -77,2 +80,4 @@ name: '__Schema',
 });
+/** The introspection type describing a GraphQL directive. */
+
 export const __Directive = new GraphQLObjectType({
@@ -128,2 +133,4 @@ name: '__Directive',
 });
+/** The introspection enum describing directive locations. */
+
 export const __DirectiveLocation = new GraphQLEnumType({
@@ -216,2 +223,4 @@ name: '__DirectiveLocation',
 });
+/** The introspection type describing GraphQL types. */
+
 export const __Type = new GraphQLObjectType({
@@ -366,2 +375,4 @@ name: '__Type',
 });
+/** The introspection type describing object and interface fields. */
+
 export const __Field = new GraphQLObjectType({
@@ -411,2 +422,4 @@ name: '__Field',
 });
+/** The introspection type describing arguments and input fields. */
+
 export const __InputValue = new GraphQLObjectType({
@@ -450,2 +463,4 @@ name: '__InputValue',
 });
+/** The introspection type describing enum values. */
+
 export const __EnumValue = new GraphQLObjectType({
@@ -474,2 +489,7 @@ name: '__EnumValue',
 });
+/**
+ * The introspection enum describing the different kinds of GraphQL types.
+ * @category Introspection
+ */
+
 var TypeKind;
@@ -489,2 +509,4 @@
 export { TypeKind };
+/** The introspection enum describing GraphQL type kinds. */
+
 export const __TypeKind = new GraphQLEnumType({
@@ -549,2 +571,4 @@ name: '__TypeKind',
 };
+/** The `__type` meta field definition used by introspection. */
+
 export const TypeMetaFieldDef = {
@@ -570,2 +594,4 @@ name: '__type',
 };
+/** The `__typename` meta field definition used by execution and introspection. */
+
 export const TypeNameMetaFieldDef = {
@@ -581,2 +607,4 @@ name: '__typename',
 };
+/** All introspection types defined by the GraphQL specification. */
+
 export const introspectionTypes = Object.freeze([
@@ -592,4 +620,17 @@ __Schema,
 ]);
+/**
+ * Returns true when the type is one of the built-in introspection types.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the type is one of the built-in introspection types.
+ * @example
+ * ```ts
+ * import { GraphQLString, isIntrospectionType, __Type } from 'graphql/type';
+ *
+ * isIntrospectionType(__Type); // => true
+ * isIntrospectionType(GraphQLString); // => false
+ * ```
+ */
+
 export function isIntrospectionType(type) {
   return introspectionTypes.some(({ name }) => type.name === name);
 }

type/scalars.d.ts

@@ -0,1 +1,2 @@
+/** @category Scalars */
 import type { GraphQLNamedType } from './definition';
@@ -6,3 +7,3 @@ import { GraphQLScalarType } from './definition';
  * n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe up-to 2^53 - 1
- * */
+ */
 export declare const GRAPHQL_MAX_INT = 2147483647;
@@ -12,10 +13,36 @@ /**
  * n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe starting at -(2^53 - 1)
- * */
+ */
 export declare const GRAPHQL_MIN_INT = -2147483648;
+/** The built-in `Int` scalar type. */
 export declare const GraphQLInt: GraphQLScalarType<number, number>;
+/** The built-in `Float` scalar type. */
 export declare const GraphQLFloat: GraphQLScalarType<number, number>;
+/** The built-in `String` scalar type. */
 export declare const GraphQLString: GraphQLScalarType<string, string>;
+/** The built-in `Boolean` scalar type. */
 export declare const GraphQLBoolean: GraphQLScalarType<boolean, boolean>;
+/** The built-in `ID` scalar type. */
 export declare const GraphQLID: GraphQLScalarType<string, string>;
+/** All built-in scalar types defined by the GraphQL specification. */
 export declare const specifiedScalarTypes: ReadonlyArray<GraphQLScalarType>;
+/**
+ * Returns true when the scalar type is one of the scalars specified by GraphQL.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the scalar type is one of the scalars specified by GraphQL.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLScalarType,
+ *   GraphQLString,
+ *   isSpecifiedScalarType,
+ * } from 'graphql/type';
+ *
+ * const DateTime = new GraphQLScalarType({
+ *   name: 'DateTime',
+ * });
+ *
+ * isSpecifiedScalarType(GraphQLString); // => true
+ * isSpecifiedScalarType(DateTime); // => false
+ * ```
+ */
 export declare function isSpecifiedScalarType(type: GraphQLNamedType): boolean;

type/scalars.js

@@ -29,6 +29,8 @@ 'use strict';
 
+/** @category Scalars */
+
 /**
  * Maximum possible Int value as per GraphQL Spec (32-bit signed integer).
  * n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe up-to 2^53 - 1
- * */
+ */
 const GRAPHQL_MAX_INT = 2147483647;
@@ -38,6 +40,8 @@ /**
  * n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe starting at -(2^53 - 1)
- * */
+ */
 
 exports.GRAPHQL_MAX_INT = GRAPHQL_MAX_INT;
 const GRAPHQL_MIN_INT = -2147483648;
+/** The built-in `Int` scalar type. */
+
 exports.GRAPHQL_MIN_INT = GRAPHQL_MIN_INT;
@@ -124,2 +128,4 @@ const GraphQLInt = new _definition.GraphQLScalarType({
 });
+/** The built-in `Float` scalar type. */
+
 exports.GraphQLInt = GraphQLInt;
@@ -183,2 +189,4 @@ const GraphQLFloat = new _definition.GraphQLScalarType({
 });
+/** The built-in `String` scalar type. */
+
 exports.GraphQLFloat = GraphQLFloat;
@@ -238,2 +246,4 @@ const GraphQLString = new _definition.GraphQLScalarType({
 });
+/** The built-in `Boolean` scalar type. */
+
 exports.GraphQLString = GraphQLString;
@@ -289,2 +299,4 @@ const GraphQLBoolean = new _definition.GraphQLScalarType({
 });
+/** The built-in `ID` scalar type. */
+
 exports.GraphQLBoolean = GraphQLBoolean;
@@ -343,2 +355,4 @@ const GraphQLID = new _definition.GraphQLScalarType({
 });
+/** All built-in scalar types defined by the GraphQL specification. */
+
 exports.GraphQLID = GraphQLID;
@@ -352,2 +366,23 @@ const specifiedScalarTypes = Object.freeze([
 ]);
+/**
+ * Returns true when the scalar type is one of the scalars specified by GraphQL.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the scalar type is one of the scalars specified by GraphQL.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLScalarType,
+ *   GraphQLString,
+ *   isSpecifiedScalarType,
+ * } from 'graphql/type';
+ *
+ * const DateTime = new GraphQLScalarType({
+ *   name: 'DateTime',
+ * });
+ *
+ * isSpecifiedScalarType(GraphQLString); // => true
+ * isSpecifiedScalarType(DateTime); // => false
+ * ```
+ */
+
 exports.specifiedScalarTypes = specifiedScalarTypes;
@@ -354,0 +389,0 @@

type/scalars.mjs

@@ -0,1 +1,2 @@
+/** @category Scalars */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -10,3 +11,3 @@ import { isObjectLike } from '../jsutils/isObjectLike.mjs';
  * n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe up-to 2^53 - 1
- * */
+ */
 
@@ -17,5 +18,7 @@ export const GRAPHQL_MAX_INT = 2147483647;
  * n.b. This differs from JavaScript's numbers that are IEEE 754 doubles safe starting at -(2^53 - 1)
- * */
+ */
 
 export const GRAPHQL_MIN_INT = -2147483648;
+/** The built-in `Int` scalar type. */
+
 export const GraphQLInt = new GraphQLScalarType({
@@ -95,2 +98,4 @@ name: 'Int',
 });
+/** The built-in `Float` scalar type. */
+
 export const GraphQLFloat = new GraphQLScalarType({
@@ -144,2 +149,4 @@ name: 'Float',
 });
+/** The built-in `String` scalar type. */
+
 export const GraphQLString = new GraphQLScalarType({
@@ -194,2 +201,4 @@ name: 'String',
 });
+/** The built-in `Boolean` scalar type. */
+
 export const GraphQLBoolean = new GraphQLScalarType({
@@ -238,2 +247,4 @@ name: 'Boolean',
 });
+/** The built-in `ID` scalar type. */
+
 export const GraphQLID = new GraphQLScalarType({
@@ -286,2 +297,4 @@ name: 'ID',
 });
+/** All built-in scalar types defined by the GraphQL specification. */
+
 export const specifiedScalarTypes = Object.freeze([
@@ -294,2 +307,23 @@ GraphQLString,
 ]);
+/**
+ * Returns true when the scalar type is one of the scalars specified by GraphQL.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the scalar type is one of the scalars specified by GraphQL.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLScalarType,
+ *   GraphQLString,
+ *   isSpecifiedScalarType,
+ * } from 'graphql/type';
+ *
+ * const DateTime = new GraphQLScalarType({
+ *   name: 'DateTime',
+ * });
+ *
+ * isSpecifiedScalarType(GraphQLString); // => true
+ * isSpecifiedScalarType(DateTime); // => false
+ * ```
+ */
+
 export function isSpecifiedScalarType(type) {
@@ -296,0 +330,0 @@ return specifiedScalarTypes.some(({ name }) => type.name === name);

type/schema.d.ts

@@ -0,1 +1,2 @@
+/** @category Schema */
 import type { Maybe } from '../jsutils/Maybe';
@@ -18,8 +19,42 @@ import type { ObjMap } from '../jsutils/ObjMap';
  * Test if the given value is a GraphQL schema.
+ * @param schema - Value to inspect.
+ * @returns True when the value is a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { GraphQLString, isSchema } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * isSchema(schema); // => true
+ * isSchema(GraphQLString); // => false
+ * ```
  */
 export declare function isSchema(schema: unknown): schema is GraphQLSchema;
+/**
+ * Returns the value as a GraphQLSchema, or throws if it is not a schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The value typed as a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertSchema, GraphQLString } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * assertSchema(schema); // => schema
+ * assertSchema(GraphQLString); // throws an error
+ * ```
+ */
 export declare function assertSchema(schema: unknown): GraphQLSchema;
 /**
  * Custom extensions
- *
  * @remarks
@@ -40,22 +75,34 @@ * Use a unique identifier name for your extension, for example the name of
  * validator and executor.
+ * @example
+ * ```ts
+ * const MyAppQueryRootType = new GraphQLObjectType({
+ *   name: 'Query',
+ *   fields: {
+ *     greeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * Example:
+ * const MyAppMutationRootType = new GraphQLObjectType({
+ *   name: 'Mutation',
+ *   fields: {
+ *     setGreeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * ```ts
  * const MyAppSchema = new GraphQLSchema({
  *   query: MyAppQueryRootType,
  *   mutation: MyAppMutationRootType,
- * })
+ * });
  * ```
+ * @example
+ * When the schema is constructed, by default only the types that are reachable
+ * by traversing the root types are included, other types must be explicitly
+ * referenced.
  *
- * Note: When the schema is constructed, by default only the types that are
- * reachable by traversing the root types are included, other types must be
- * explicitly referenced.
- *
- * Example:
- *
  * ```ts
  * const characterInterface = new GraphQLInterfaceType({
  *   name: 'Character',
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -66,3 +113,5 @@ *
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -73,3 +122,5 @@ *
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -81,6 +132,5 @@ *
  *     fields: {
- *       hero: { type: characterInterface, ... },
- *     }
+ *       hero: { type: characterInterface },
+ *     },
  *   }),
- *   ...
  *   // Since this schema references only the `Character` interface it's
@@ -90,23 +140,31 @@ *   // necessary to explicitly list the types that implement it if
  *   types: [humanType, droidType],
- * })
+ * });
  * ```
- *
- * Note: If an array of `directives` are provided to GraphQLSchema, that will be
- * the exact list of directives represented and allowed. If `directives` is not
+ * @example
+ * If an array of `directives` are provided to GraphQLSchema, that will be the
+ * exact list of directives represented and allowed. If `directives` is not
  * provided then a default set of the specified directives (e.g. `@include` and
- * `@skip`) will be used. If you wish to provide *additional* directives to these
- * specified directives, you must explicitly declare them. Example:
+ * `@skip`) will be used. If you wish to provide *additional* directives to
+ * these specified directives, you must explicitly declare them.
  *
  * ```ts
  * const MyAppSchema = new GraphQLSchema({
- *   ...
- *   directives: specifiedDirectives.concat([ myCustomDirective ]),
- * })
+ *   query: MyAppQueryRootType,
+ *   directives: specifiedDirectives.concat([myCustomDirective]),
+ * });
  * ```
  */
 export declare class GraphQLSchema {
+  /** Human-readable description for this schema element, if provided. */
   description: Maybe<string>;
+  /** Extension fields to include in the formatted result. */
   extensions: Readonly<GraphQLSchemaExtensions>;
+  /** AST node from which this schema element was built, if available. */
   astNode: Maybe<SchemaDefinitionNode>;
+  /** AST extension nodes applied to this schema element. */
   extensionASTNodes: ReadonlyArray<SchemaExtensionNode>;
+  /**
+   * Cached schema validation errors, if validation has already run.
+   * @internal
+   */
   __validationErrors: Maybe<ReadonlyArray<GraphQLError>>;
@@ -120,13 +178,309 @@ private _queryType;
   private _implementationsMap;
+  /**
+   * Creates a GraphQLSchema instance.
+   * @param config - Configuration describing this object.
+   * @example
+   * ```ts
+   * // Create a schema with the required query root.
+   * import {
+   *   GraphQLObjectType,
+   *   GraphQLSchema,
+   *   GraphQLString,
+   * } from 'graphql/type';
+   *
+   * const Query = new GraphQLObjectType({
+   *   name: 'Query',
+   *   fields: {
+   *     greeting: {
+   *       type: GraphQLString,
+   *       resolve: () => 'Hello',
+   *     },
+   *   },
+   * });
+   *
+   * const schema = new GraphQLSchema({
+   *   description: 'The application schema.',
+   *   query: Query,
+   * });
+   *
+   * schema.getQueryType(); // => Query
+   * schema.description; // => 'The application schema.'
+   * ```
+   * @example
+   * ```ts
+   * // This variant configures every schema option, including directives and extensions.
+   * import { DirectiveLocation, parse } from 'graphql/language';
+   * import {
+   *   GraphQLBoolean,
+   *   GraphQLDirective,
+   *   GraphQLObjectType,
+   *   GraphQLSchema,
+   *   GraphQLString,
+   * } from 'graphql/type';
+   *
+   * const Query = new GraphQLObjectType({
+   *   name: 'Query',
+   *   fields: { greeting: { type: GraphQLString } },
+   * });
+   * const Mutation = new GraphQLObjectType({
+   *   name: 'Mutation',
+   *   fields: { setGreeting: { type: GraphQLString } },
+   * });
+   * const Subscription = new GraphQLObjectType({
+   *   name: 'Subscription',
+   *   fields: { greetingChanged: { type: GraphQLString } },
+   * });
+   * const AuditEvent = new GraphQLObjectType({
+   *   name: 'AuditEvent',
+   *   fields: { message: { type: GraphQLString } },
+   * });
+   * const authDirective = new GraphQLDirective({
+   *   name: 'auth',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: { required: { type: GraphQLBoolean } },
+   * });
+   * const schemaDocument = parse(`
+   *   schema {
+   *     query: Query
+   *     mutation: Mutation
+   *     subscription: Subscription
+   *   }
+   *
+   *   extend schema @auth
+   * `);
+   *
+   * const schema = new GraphQLSchema({
+   *   description: 'Operations exposed by the application.',
+   *   query: Query,
+   *   mutation: Mutation,
+   *   subscription: Subscription,
+   *   types: [AuditEvent],
+   *   directives: [authDirective],
+   *   extensions: { owner: 'platform' },
+   *   astNode: schemaDocument.definitions[0],
+   *   extensionASTNodes: [ schemaDocument.definitions[1] ],
+   *   assumeValid: true,
+   * });
+   *
+   * schema.getMutationType(); // => Mutation
+   * schema.getSubscriptionType(); // => Subscription
+   * schema.getType('AuditEvent'); // => AuditEvent
+   * schema.getDirective('auth'); // => authDirective
+   * schema.extensions; // => { owner: 'platform' }
+   * ```
+   */
   constructor(config: Readonly<GraphQLSchemaConfig>);
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * Returns the root object type for query operations.
+   * @returns The query root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   *
+   * schema.getQueryType()?.name; // => 'Query'
+   * ```
+   */
   getQueryType(): Maybe<GraphQLObjectType>;
+  /**
+   * Returns the root object type for mutation operations.
+   * @returns The mutation root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Mutation {
+   *     setGreeting(value: String!): String
+   *   }
+   * `);
+   *
+   * schema.getMutationType()?.name; // => 'Mutation'
+   * ```
+   */
   getMutationType(): Maybe<GraphQLObjectType>;
+  /**
+   * Returns the root object type for subscription operations.
+   * @returns The subscription root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Subscription {
+   *     greetings: String
+   *   }
+   * `);
+   *
+   * schema.getSubscriptionType()?.name; // => 'Subscription'
+   * ```
+   */
   getSubscriptionType(): Maybe<GraphQLObjectType>;
+  /**
+   * Returns the root object type for the requested operation kind.
+   * @param operation - Operation kind to resolve.
+   * @returns The root object type for the operation kind, if this schema defines one.
+   * @example
+   * ```ts
+   * import { OperationTypeNode } from 'graphql/language';
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Mutation {
+   *     setGreeting(value: String!): String
+   *   }
+   * `);
+   *
+   * schema.getRootType(OperationTypeNode.QUERY)?.name; // => 'Query'
+   * schema.getRootType(OperationTypeNode.MUTATION)?.name; // => 'Mutation'
+   * schema.getRootType(OperationTypeNode.SUBSCRIPTION); // => undefined
+   * ```
+   */
   getRootType(operation: OperationTypeNode): Maybe<GraphQLObjectType>;
+  /**
+   * Returns all named types known to this schema.
+   * @returns A map of schema types keyed by type name.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type User {
+   *     name: String
+   *   }
+   *
+   *   type Query {
+   *     viewer: User
+   *   }
+   * `);
+   *
+   * const typeMap = schema.getTypeMap();
+   *
+   * typeMap.User.name; // => 'User'
+   * typeMap.Query.name; // => 'Query'
+   * typeMap.String.name; // => 'String'
+   * ```
+   */
   getTypeMap(): TypeMap;
+  /**
+   * Returns the named type with the provided name.
+   * @param name - The GraphQL name to look up.
+   * @returns The named schema type, if one exists.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type User {
+   *     name: String
+   *   }
+   *
+   *   type Query {
+   *     viewer: User
+   *   }
+   * `);
+   *
+   * schema.getType('User')?.toString(); // => 'User'
+   * schema.getType('Missing'); // => undefined
+   * ```
+   */
   getType(name: string): GraphQLNamedType | undefined;
+  /**
+   * Returns object types that may be returned for an abstract type.
+   * @param abstractType - Interface or union type to inspect.
+   * @returns Object types that may satisfy the abstract type.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType, assertUnionType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Node {
+   *     id: ID!
+   *   }
+   *
+   *   type User implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   type Organization implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   union SearchResult = User | Organization
+   *
+   *   type Query {
+   *     node: Node
+   *     search: [SearchResult]
+   *   }
+   * `);
+   *
+   * const Node = assertInterfaceType(schema.getType('Node'));
+   * const SearchResult = assertUnionType(schema.getType('SearchResult'));
+   *
+   * schema.getPossibleTypes(Node).map((type) => type.name); // => ['User', 'Organization']
+   * schema.getPossibleTypes(SearchResult).map((type) => type.name); // => ['User', 'Organization']
+   * ```
+   */
   getPossibleTypes(
     abstractType: GraphQLAbstractType,
   ): ReadonlyArray<GraphQLObjectType>;
+  /**
+   * Returns objects and interfaces that implement an interface type.
+   * @param interfaceType - Interface type to inspect.
+   * @returns Object and interface implementations of the interface.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Resource {
+   *     url: String!
+   *   }
+   *
+   *   interface Image implements Resource {
+   *     url: String!
+   *     width: Int
+   *   }
+   *
+   *   type Photo implements Resource & Image {
+   *     url: String!
+   *     width: Int
+   *   }
+   *
+   *   type Query {
+   *     resource: Resource
+   *   }
+   * `);
+   *
+   * const Resource = assertInterfaceType(schema.getType('Resource'));
+   * const implementations = schema.getImplementations(Resource);
+   *
+   * implementations.interfaces.map((type) => type.name); // => ['Image']
+   * implementations.objects.map((type) => type.name); // => ['Photo']
+   * ```
+   */
   getImplementations(interfaceType: GraphQLInterfaceType): {
@@ -136,2 +490,39 @@ objects: ReadonlyArray<GraphQLObjectType>;
   };
+  /**
+   * Returns whether one type is a possible runtime subtype of an abstract type.
+   * @param abstractType - Interface or union type to inspect.
+   * @param maybeSubType - Object or interface type to test as a possible subtype.
+   * @returns True when the subtype may satisfy the abstract type.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType, assertObjectType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Node {
+   *     id: ID!
+   *   }
+   *
+   *   type User implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   type Review {
+   *     body: String
+   *   }
+   *
+   *   type Query {
+   *     node: Node
+   *     review: Review
+   *   }
+   * `);
+   *
+   * const Node = assertInterfaceType(schema.getType('Node'));
+   * const User = assertObjectType(schema.getType('User'));
+   * const Review = assertObjectType(schema.getType('Review'));
+   *
+   * schema.isSubType(Node, User); // => true
+   * schema.isSubType(Node, Review); // => false
+   * ```
+   */
   isSubType(
@@ -141,7 +532,70 @@ abstractType: GraphQLAbstractType,
   ): boolean;
+  /**
+   * Returns directives available in this schema.
+   * @returns Directives available in this schema.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   directive @upper on FIELD_DEFINITION
+   *
+   *   type Query {
+   *     greeting: String @upper
+   *   }
+   * `);
+   *
+   * schema.getDirectives().map((directive) => directive.name); // => ['include', 'skip', 'deprecated', 'specifiedBy', 'oneOf', 'upper']
+   * ```
+   */
   getDirectives(): ReadonlyArray<GraphQLDirective>;
+  /**
+   * Returns the current directive definition.
+   * @param name - The GraphQL name to look up.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   directive @upper on FIELD_DEFINITION
+   *
+   *   type Query {
+   *     greeting: String @upper
+   *   }
+   * `);
+   *
+   * schema.getDirective('upper')?.name; // => 'upper'
+   * schema.getDirective('missing'); // => undefined
+   * ```
+   */
   getDirective(name: string): Maybe<GraphQLDirective>;
+  /**
+   * Returns a normalized configuration object for this object.
+   *
+   * The returned config preserves the original `assumeValid` flag so the schema
+   * can be recreated with the same validation behavior.
+   * @returns A configuration object that can be used to recreate this object.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { GraphQLSchema } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   *
+   * const config = schema.toConfig();
+   * const schemaCopy = new GraphQLSchema(config);
+   *
+   * config.query?.name; // => 'Query'
+   * schemaCopy.getQueryType()?.name; // => 'Query'
+   * ```
+   */
   toConfig(): GraphQLSchemaNormalizedConfig;
 }
 declare type TypeMap = ObjMap<GraphQLNamedType>;
+/** @internal */
 export interface GraphQLSchemaValidationOptions {
@@ -157,16 +611,24 @@ /**
 }
+/** Configuration used to construct a GraphQLSchema. */
 export interface GraphQLSchemaConfig extends GraphQLSchemaValidationOptions {
+  /** Human-readable description for this schema element, if provided. */
   description?: Maybe<string>;
+  /** Root object type for query operations. */
   query?: Maybe<GraphQLObjectType>;
+  /** Root object type for mutation operations. */
   mutation?: Maybe<GraphQLObjectType>;
+  /** Root object type for subscription operations. */
   subscription?: Maybe<GraphQLObjectType>;
+  /** Object types that belong to this union type. */
   types?: Maybe<ReadonlyArray<GraphQLNamedType>>;
+  /** Directives available in this schema or applied to this AST node. */
   directives?: Maybe<ReadonlyArray<GraphQLDirective>>;
+  /** Extension fields to include in the formatted result. */
   extensions?: Maybe<Readonly<GraphQLSchemaExtensions>>;
+  /** AST node from which this schema element was built, if available. */
   astNode?: Maybe<SchemaDefinitionNode>;
+  /** AST extension nodes applied to this schema element. */
   extensionASTNodes?: Maybe<ReadonlyArray<SchemaExtensionNode>>;
 }
-/**
- * @internal
- */
+/** @internal */
 export interface GraphQLSchemaNormalizedConfig extends GraphQLSchemaConfig {
@@ -173,0 +635,0 @@ description: Maybe<string>;

type/schema.js

@@ -28,4 +28,22 @@ 'use strict';
 
+/** @category Schema */
+
 /**
  * Test if the given value is a GraphQL schema.
+ * @param schema - Value to inspect.
+ * @returns True when the value is a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { GraphQLString, isSchema } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * isSchema(schema); // => true
+ * isSchema(GraphQLString); // => false
+ * ```
  */
@@ -35,2 +53,21 @@ function isSchema(schema) {
 }
+/**
+ * Returns the value as a GraphQLSchema, or throws if it is not a schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The value typed as a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertSchema, GraphQLString } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * assertSchema(schema); // => schema
+ * assertSchema(GraphQLString); // throws an error
+ * ```
+ */
 
@@ -48,3 +85,2 @@ function assertSchema(schema) {
  * Custom extensions
- *
  * @remarks
@@ -63,22 +99,34 @@ * Use a unique identifier name for your extension, for example the name of
  * validator and executor.
+ * @example
+ * ```ts
+ * const MyAppQueryRootType = new GraphQLObjectType({
+ *   name: 'Query',
+ *   fields: {
+ *     greeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * Example:
+ * const MyAppMutationRootType = new GraphQLObjectType({
+ *   name: 'Mutation',
+ *   fields: {
+ *     setGreeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * ```ts
  * const MyAppSchema = new GraphQLSchema({
  *   query: MyAppQueryRootType,
  *   mutation: MyAppMutationRootType,
- * })
+ * });
  * ```
+ * @example
+ * When the schema is constructed, by default only the types that are reachable
+ * by traversing the root types are included, other types must be explicitly
+ * referenced.
  *
- * Note: When the schema is constructed, by default only the types that are
- * reachable by traversing the root types are included, other types must be
- * explicitly referenced.
- *
- * Example:
- *
  * ```ts
  * const characterInterface = new GraphQLInterfaceType({
  *   name: 'Character',
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -89,3 +137,5 @@ *
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -96,3 +146,5 @@ *
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -104,6 +156,5 @@ *
  *     fields: {
- *       hero: { type: characterInterface, ... },
- *     }
+ *       hero: { type: characterInterface },
+ *     },
  *   }),
- *   ...
  *   // Since this schema references only the `Character` interface it's
@@ -113,20 +164,125 @@ *   // necessary to explicitly list the types that implement it if
  *   types: [humanType, droidType],
- * })
+ * });
  * ```
- *
- * Note: If an array of `directives` are provided to GraphQLSchema, that will be
- * the exact list of directives represented and allowed. If `directives` is not
+ * @example
+ * If an array of `directives` are provided to GraphQLSchema, that will be the
+ * exact list of directives represented and allowed. If `directives` is not
  * provided then a default set of the specified directives (e.g. `@include` and
- * `@skip`) will be used. If you wish to provide *additional* directives to these
- * specified directives, you must explicitly declare them. Example:
+ * `@skip`) will be used. If you wish to provide *additional* directives to
+ * these specified directives, you must explicitly declare them.
  *
  * ```ts
  * const MyAppSchema = new GraphQLSchema({
- *   ...
- *   directives: specifiedDirectives.concat([ myCustomDirective ]),
- * })
+ *   query: MyAppQueryRootType,
+ *   directives: specifiedDirectives.concat([myCustomDirective]),
+ * });
  * ```
  */
 class GraphQLSchema {
-  // Used as a cache for validateSchema().
+  /** Human-readable description for this schema element, if provided. */
+
+  /** Extension fields to include in the formatted result. */
+
+  /** AST node from which this schema element was built, if available. */
+
+  /** AST extension nodes applied to this schema element. */
+
+  /**
+   * Cached schema validation errors, if validation has already run.
+   * @internal
+   */
+
+  /**
+   * Creates a GraphQLSchema instance.
+   * @param config - Configuration describing this object.
+   * @example
+   * ```ts
+   * // Create a schema with the required query root.
+   * import {
+   *   GraphQLObjectType,
+   *   GraphQLSchema,
+   *   GraphQLString,
+   * } from 'graphql/type';
+   *
+   * const Query = new GraphQLObjectType({
+   *   name: 'Query',
+   *   fields: {
+   *     greeting: {
+   *       type: GraphQLString,
+   *       resolve: () => 'Hello',
+   *     },
+   *   },
+   * });
+   *
+   * const schema = new GraphQLSchema({
+   *   description: 'The application schema.',
+   *   query: Query,
+   * });
+   *
+   * schema.getQueryType(); // => Query
+   * schema.description; // => 'The application schema.'
+   * ```
+   * @example
+   * ```ts
+   * // This variant configures every schema option, including directives and extensions.
+   * import { DirectiveLocation, parse } from 'graphql/language';
+   * import {
+   *   GraphQLBoolean,
+   *   GraphQLDirective,
+   *   GraphQLObjectType,
+   *   GraphQLSchema,
+   *   GraphQLString,
+   * } from 'graphql/type';
+   *
+   * const Query = new GraphQLObjectType({
+   *   name: 'Query',
+   *   fields: { greeting: { type: GraphQLString } },
+   * });
+   * const Mutation = new GraphQLObjectType({
+   *   name: 'Mutation',
+   *   fields: { setGreeting: { type: GraphQLString } },
+   * });
+   * const Subscription = new GraphQLObjectType({
+   *   name: 'Subscription',
+   *   fields: { greetingChanged: { type: GraphQLString } },
+   * });
+   * const AuditEvent = new GraphQLObjectType({
+   *   name: 'AuditEvent',
+   *   fields: { message: { type: GraphQLString } },
+   * });
+   * const authDirective = new GraphQLDirective({
+   *   name: 'auth',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: { required: { type: GraphQLBoolean } },
+   * });
+   * const schemaDocument = parse(`
+   *   schema {
+   *     query: Query
+   *     mutation: Mutation
+   *     subscription: Subscription
+   *   }
+   *
+   *   extend schema @auth
+   * `);
+   *
+   * const schema = new GraphQLSchema({
+   *   description: 'Operations exposed by the application.',
+   *   query: Query,
+   *   mutation: Mutation,
+   *   subscription: Subscription,
+   *   types: [AuditEvent],
+   *   directives: [authDirective],
+   *   extensions: { owner: 'platform' },
+   *   astNode: schemaDocument.definitions[0],
+   *   extensionASTNodes: [ schemaDocument.definitions[1] ],
+   *   assumeValid: true,
+   * });
+   *
+   * schema.getMutationType(); // => Mutation
+   * schema.getSubscriptionType(); // => Subscription
+   * schema.getType('AuditEvent'); // => AuditEvent
+   * schema.getDirective('auth'); // => authDirective
+   * schema.extensions; // => { owner: 'platform' }
+   * ```
+   */
   constructor(config) {
@@ -269,2 +425,6 @@ var _config$extensionASTN, _config$directives;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -274,2 +434,18 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns the root object type for query operations.
+   * @returns The query root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   *
+   * schema.getQueryType()?.name; // => 'Query'
+   * ```
+   */
 
@@ -279,2 +455,22 @@ getQueryType() {
   }
+  /**
+   * Returns the root object type for mutation operations.
+   * @returns The mutation root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Mutation {
+   *     setGreeting(value: String!): String
+   *   }
+   * `);
+   *
+   * schema.getMutationType()?.name; // => 'Mutation'
+   * ```
+   */
 
@@ -284,2 +480,22 @@ getMutationType() {
   }
+  /**
+   * Returns the root object type for subscription operations.
+   * @returns The subscription root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Subscription {
+   *     greetings: String
+   *   }
+   * `);
+   *
+   * schema.getSubscriptionType()?.name; // => 'Subscription'
+   * ```
+   */
 
@@ -289,2 +505,26 @@ getSubscriptionType() {
   }
+  /**
+   * Returns the root object type for the requested operation kind.
+   * @param operation - Operation kind to resolve.
+   * @returns The root object type for the operation kind, if this schema defines one.
+   * @example
+   * ```ts
+   * import { OperationTypeNode } from 'graphql/language';
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Mutation {
+   *     setGreeting(value: String!): String
+   *   }
+   * `);
+   *
+   * schema.getRootType(OperationTypeNode.QUERY)?.name; // => 'Query'
+   * schema.getRootType(OperationTypeNode.MUTATION)?.name; // => 'Mutation'
+   * schema.getRootType(OperationTypeNode.SUBSCRIPTION); // => undefined
+   * ```
+   */
 
@@ -303,2 +543,26 @@ getRootType(operation) {
   }
+  /**
+   * Returns all named types known to this schema.
+   * @returns A map of schema types keyed by type name.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type User {
+   *     name: String
+   *   }
+   *
+   *   type Query {
+   *     viewer: User
+   *   }
+   * `);
+   *
+   * const typeMap = schema.getTypeMap();
+   *
+   * typeMap.User.name; // => 'User'
+   * typeMap.Query.name; // => 'Query'
+   * typeMap.String.name; // => 'String'
+   * ```
+   */
 
@@ -308,2 +572,24 @@ getTypeMap() {
   }
+  /**
+   * Returns the named type with the provided name.
+   * @param name - The GraphQL name to look up.
+   * @returns The named schema type, if one exists.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type User {
+   *     name: String
+   *   }
+   *
+   *   type Query {
+   *     viewer: User
+   *   }
+   * `);
+   *
+   * schema.getType('User')?.toString(); // => 'User'
+   * schema.getType('Missing'); // => undefined
+   * ```
+   */
 
@@ -313,2 +599,39 @@ getType(name) {
   }
+  /**
+   * Returns object types that may be returned for an abstract type.
+   * @param abstractType - Interface or union type to inspect.
+   * @returns Object types that may satisfy the abstract type.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType, assertUnionType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Node {
+   *     id: ID!
+   *   }
+   *
+   *   type User implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   type Organization implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   union SearchResult = User | Organization
+   *
+   *   type Query {
+   *     node: Node
+   *     search: [SearchResult]
+   *   }
+   * `);
+   *
+   * const Node = assertInterfaceType(schema.getType('Node'));
+   * const SearchResult = assertUnionType(schema.getType('SearchResult'));
+   *
+   * schema.getPossibleTypes(Node).map((type) => type.name); // => ['User', 'Organization']
+   * schema.getPossibleTypes(SearchResult).map((type) => type.name); // => ['User', 'Organization']
+   * ```
+   */
 
@@ -320,2 +643,38 @@ getPossibleTypes(abstractType) {
   }
+  /**
+   * Returns objects and interfaces that implement an interface type.
+   * @param interfaceType - Interface type to inspect.
+   * @returns Object and interface implementations of the interface.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Resource {
+   *     url: String!
+   *   }
+   *
+   *   interface Image implements Resource {
+   *     url: String!
+   *     width: Int
+   *   }
+   *
+   *   type Photo implements Resource & Image {
+   *     url: String!
+   *     width: Int
+   *   }
+   *
+   *   type Query {
+   *     resource: Resource
+   *   }
+   * `);
+   *
+   * const Resource = assertInterfaceType(schema.getType('Resource'));
+   * const implementations = schema.getImplementations(Resource);
+   *
+   * implementations.interfaces.map((type) => type.name); // => ['Image']
+   * implementations.objects.map((type) => type.name); // => ['Photo']
+   * ```
+   */
 
@@ -331,2 +690,39 @@ getImplementations(interfaceType) {
   }
+  /**
+   * Returns whether one type is a possible runtime subtype of an abstract type.
+   * @param abstractType - Interface or union type to inspect.
+   * @param maybeSubType - Object or interface type to test as a possible subtype.
+   * @returns True when the subtype may satisfy the abstract type.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType, assertObjectType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Node {
+   *     id: ID!
+   *   }
+   *
+   *   type User implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   type Review {
+   *     body: String
+   *   }
+   *
+   *   type Query {
+   *     node: Node
+   *     review: Review
+   *   }
+   * `);
+   *
+   * const Node = assertInterfaceType(schema.getType('Node'));
+   * const User = assertObjectType(schema.getType('User'));
+   * const Review = assertObjectType(schema.getType('Review'));
+   *
+   * schema.isSubType(Node, User); // => true
+   * schema.isSubType(Node, Review); // => false
+   * ```
+   */
 
@@ -360,2 +756,20 @@ isSubType(abstractType, maybeSubType) {
   }
+  /**
+   * Returns directives available in this schema.
+   * @returns Directives available in this schema.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   directive @upper on FIELD_DEFINITION
+   *
+   *   type Query {
+   *     greeting: String @upper
+   *   }
+   * `);
+   *
+   * schema.getDirectives().map((directive) => directive.name); // => ['include', 'skip', 'deprecated', 'specifiedBy', 'oneOf', 'upper']
+   * ```
+   */
 
@@ -365,2 +779,22 @@ getDirectives() {
   }
+  /**
+   * Returns the current directive definition.
+   * @param name - The GraphQL name to look up.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   directive @upper on FIELD_DEFINITION
+   *
+   *   type Query {
+   *     greeting: String @upper
+   *   }
+   * `);
+   *
+   * schema.getDirective('upper')?.name; // => 'upper'
+   * schema.getDirective('missing'); // => undefined
+   * ```
+   */
 
@@ -370,2 +804,26 @@ getDirective(name) {
   }
+  /**
+   * Returns a normalized configuration object for this object.
+   *
+   * The returned config preserves the original `assumeValid` flag so the schema
+   * can be recreated with the same validation behavior.
+   * @returns A configuration object that can be used to recreate this object.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { GraphQLSchema } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   *
+   * const config = schema.toConfig();
+   * const schemaCopy = new GraphQLSchema(config);
+   *
+   * config.query?.name; // => 'Query'
+   * schemaCopy.getQueryType()?.name; // => 'Query'
+   * ```
+   */
 
@@ -372,0 +830,0 @@ toConfig() {

type/schema.mjs

@@ -0,1 +1,2 @@
+/** @category Schema */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -18,2 +19,18 @@ import { inspect } from '../jsutils/inspect.mjs';
  * Test if the given value is a GraphQL schema.
+ * @param schema - Value to inspect.
+ * @returns True when the value is a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { GraphQLString, isSchema } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * isSchema(schema); // => true
+ * isSchema(GraphQLString); // => false
+ * ```
  */
@@ -24,2 +41,22 @@
 }
+/**
+ * Returns the value as a GraphQLSchema, or throws if it is not a schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The value typed as a GraphQLSchema.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertSchema, GraphQLString } from 'graphql/type';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * assertSchema(schema); // => schema
+ * assertSchema(GraphQLString); // throws an error
+ * ```
+ */
+
 export function assertSchema(schema) {
@@ -34,3 +71,2 @@ if (!isSchema(schema)) {
  * Custom extensions
- *
  * @remarks
@@ -49,22 +85,34 @@ * Use a unique identifier name for your extension, for example the name of
  * validator and executor.
+ * @example
+ * ```ts
+ * const MyAppQueryRootType = new GraphQLObjectType({
+ *   name: 'Query',
+ *   fields: {
+ *     greeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * Example:
+ * const MyAppMutationRootType = new GraphQLObjectType({
+ *   name: 'Mutation',
+ *   fields: {
+ *     setGreeting: { type: GraphQLString },
+ *   },
+ * });
  *
- * ```ts
  * const MyAppSchema = new GraphQLSchema({
  *   query: MyAppQueryRootType,
  *   mutation: MyAppMutationRootType,
- * })
+ * });
  * ```
+ * @example
+ * When the schema is constructed, by default only the types that are reachable
+ * by traversing the root types are included, other types must be explicitly
+ * referenced.
  *
- * Note: When the schema is constructed, by default only the types that are
- * reachable by traversing the root types are included, other types must be
- * explicitly referenced.
- *
- * Example:
- *
  * ```ts
  * const characterInterface = new GraphQLInterfaceType({
  *   name: 'Character',
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -75,3 +123,5 @@ *
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -82,3 +132,5 @@ *
  *   interfaces: [characterInterface],
- *   ...
+ *   fields: {
+ *     name: { type: GraphQLString },
+ *   },
  * });
@@ -90,6 +142,5 @@ *
  *     fields: {
- *       hero: { type: characterInterface, ... },
- *     }
+ *       hero: { type: characterInterface },
+ *     },
  *   }),
- *   ...
  *   // Since this schema references only the `Character` interface it's
@@ -99,20 +150,125 @@ *   // necessary to explicitly list the types that implement it if
  *   types: [humanType, droidType],
- * })
+ * });
  * ```
- *
- * Note: If an array of `directives` are provided to GraphQLSchema, that will be
- * the exact list of directives represented and allowed. If `directives` is not
+ * @example
+ * If an array of `directives` are provided to GraphQLSchema, that will be the
+ * exact list of directives represented and allowed. If `directives` is not
  * provided then a default set of the specified directives (e.g. `@include` and
- * `@skip`) will be used. If you wish to provide *additional* directives to these
- * specified directives, you must explicitly declare them. Example:
+ * `@skip`) will be used. If you wish to provide *additional* directives to
+ * these specified directives, you must explicitly declare them.
  *
  * ```ts
  * const MyAppSchema = new GraphQLSchema({
- *   ...
- *   directives: specifiedDirectives.concat([ myCustomDirective ]),
- * })
+ *   query: MyAppQueryRootType,
+ *   directives: specifiedDirectives.concat([myCustomDirective]),
+ * });
  * ```
  */
 export class GraphQLSchema {
-  // Used as a cache for validateSchema().
+  /** Human-readable description for this schema element, if provided. */
+
+  /** Extension fields to include in the formatted result. */
+
+  /** AST node from which this schema element was built, if available. */
+
+  /** AST extension nodes applied to this schema element. */
+
+  /**
+   * Cached schema validation errors, if validation has already run.
+   * @internal
+   */
+
+  /**
+   * Creates a GraphQLSchema instance.
+   * @param config - Configuration describing this object.
+   * @example
+   * ```ts
+   * // Create a schema with the required query root.
+   * import {
+   *   GraphQLObjectType,
+   *   GraphQLSchema,
+   *   GraphQLString,
+   * } from 'graphql/type';
+   *
+   * const Query = new GraphQLObjectType({
+   *   name: 'Query',
+   *   fields: {
+   *     greeting: {
+   *       type: GraphQLString,
+   *       resolve: () => 'Hello',
+   *     },
+   *   },
+   * });
+   *
+   * const schema = new GraphQLSchema({
+   *   description: 'The application schema.',
+   *   query: Query,
+   * });
+   *
+   * schema.getQueryType(); // => Query
+   * schema.description; // => 'The application schema.'
+   * ```
+   * @example
+   * ```ts
+   * // This variant configures every schema option, including directives and extensions.
+   * import { DirectiveLocation, parse } from 'graphql/language';
+   * import {
+   *   GraphQLBoolean,
+   *   GraphQLDirective,
+   *   GraphQLObjectType,
+   *   GraphQLSchema,
+   *   GraphQLString,
+   * } from 'graphql/type';
+   *
+   * const Query = new GraphQLObjectType({
+   *   name: 'Query',
+   *   fields: { greeting: { type: GraphQLString } },
+   * });
+   * const Mutation = new GraphQLObjectType({
+   *   name: 'Mutation',
+   *   fields: { setGreeting: { type: GraphQLString } },
+   * });
+   * const Subscription = new GraphQLObjectType({
+   *   name: 'Subscription',
+   *   fields: { greetingChanged: { type: GraphQLString } },
+   * });
+   * const AuditEvent = new GraphQLObjectType({
+   *   name: 'AuditEvent',
+   *   fields: { message: { type: GraphQLString } },
+   * });
+   * const authDirective = new GraphQLDirective({
+   *   name: 'auth',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: { required: { type: GraphQLBoolean } },
+   * });
+   * const schemaDocument = parse(`
+   *   schema {
+   *     query: Query
+   *     mutation: Mutation
+   *     subscription: Subscription
+   *   }
+   *
+   *   extend schema @auth
+   * `);
+   *
+   * const schema = new GraphQLSchema({
+   *   description: 'Operations exposed by the application.',
+   *   query: Query,
+   *   mutation: Mutation,
+   *   subscription: Subscription,
+   *   types: [AuditEvent],
+   *   directives: [authDirective],
+   *   extensions: { owner: 'platform' },
+   *   astNode: schemaDocument.definitions[0],
+   *   extensionASTNodes: [ schemaDocument.definitions[1] ],
+   *   assumeValid: true,
+   * });
+   *
+   * schema.getMutationType(); // => Mutation
+   * schema.getSubscriptionType(); // => Subscription
+   * schema.getType('AuditEvent'); // => AuditEvent
+   * schema.getDirective('auth'); // => authDirective
+   * schema.extensions; // => { owner: 'platform' }
+   * ```
+   */
   constructor(config) {
@@ -253,2 +409,6 @@ var _config$extensionASTN, _config$directives;
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -258,2 +418,18 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns the root object type for query operations.
+   * @returns The query root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   *
+   * schema.getQueryType()?.name; // => 'Query'
+   * ```
+   */
 
@@ -263,2 +439,22 @@ getQueryType() {
   }
+  /**
+   * Returns the root object type for mutation operations.
+   * @returns The mutation root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Mutation {
+   *     setGreeting(value: String!): String
+   *   }
+   * `);
+   *
+   * schema.getMutationType()?.name; // => 'Mutation'
+   * ```
+   */
 
@@ -268,2 +464,22 @@ getMutationType() {
   }
+  /**
+   * Returns the root object type for subscription operations.
+   * @returns The subscription root type, if this schema defines one.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Subscription {
+   *     greetings: String
+   *   }
+   * `);
+   *
+   * schema.getSubscriptionType()?.name; // => 'Subscription'
+   * ```
+   */
 
@@ -273,2 +489,26 @@ getSubscriptionType() {
   }
+  /**
+   * Returns the root object type for the requested operation kind.
+   * @param operation - Operation kind to resolve.
+   * @returns The root object type for the operation kind, if this schema defines one.
+   * @example
+   * ```ts
+   * import { OperationTypeNode } from 'graphql/language';
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   *
+   *   type Mutation {
+   *     setGreeting(value: String!): String
+   *   }
+   * `);
+   *
+   * schema.getRootType(OperationTypeNode.QUERY)?.name; // => 'Query'
+   * schema.getRootType(OperationTypeNode.MUTATION)?.name; // => 'Mutation'
+   * schema.getRootType(OperationTypeNode.SUBSCRIPTION); // => undefined
+   * ```
+   */
 
@@ -287,2 +527,26 @@ getRootType(operation) {
   }
+  /**
+   * Returns all named types known to this schema.
+   * @returns A map of schema types keyed by type name.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type User {
+   *     name: String
+   *   }
+   *
+   *   type Query {
+   *     viewer: User
+   *   }
+   * `);
+   *
+   * const typeMap = schema.getTypeMap();
+   *
+   * typeMap.User.name; // => 'User'
+   * typeMap.Query.name; // => 'Query'
+   * typeMap.String.name; // => 'String'
+   * ```
+   */
 
@@ -292,2 +556,24 @@ getTypeMap() {
   }
+  /**
+   * Returns the named type with the provided name.
+   * @param name - The GraphQL name to look up.
+   * @returns The named schema type, if one exists.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type User {
+   *     name: String
+   *   }
+   *
+   *   type Query {
+   *     viewer: User
+   *   }
+   * `);
+   *
+   * schema.getType('User')?.toString(); // => 'User'
+   * schema.getType('Missing'); // => undefined
+   * ```
+   */
 
@@ -297,2 +583,39 @@ getType(name) {
   }
+  /**
+   * Returns object types that may be returned for an abstract type.
+   * @param abstractType - Interface or union type to inspect.
+   * @returns Object types that may satisfy the abstract type.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType, assertUnionType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Node {
+   *     id: ID!
+   *   }
+   *
+   *   type User implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   type Organization implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   union SearchResult = User | Organization
+   *
+   *   type Query {
+   *     node: Node
+   *     search: [SearchResult]
+   *   }
+   * `);
+   *
+   * const Node = assertInterfaceType(schema.getType('Node'));
+   * const SearchResult = assertUnionType(schema.getType('SearchResult'));
+   *
+   * schema.getPossibleTypes(Node).map((type) => type.name); // => ['User', 'Organization']
+   * schema.getPossibleTypes(SearchResult).map((type) => type.name); // => ['User', 'Organization']
+   * ```
+   */
 
@@ -304,2 +627,38 @@ getPossibleTypes(abstractType) {
   }
+  /**
+   * Returns objects and interfaces that implement an interface type.
+   * @param interfaceType - Interface type to inspect.
+   * @returns Object and interface implementations of the interface.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Resource {
+   *     url: String!
+   *   }
+   *
+   *   interface Image implements Resource {
+   *     url: String!
+   *     width: Int
+   *   }
+   *
+   *   type Photo implements Resource & Image {
+   *     url: String!
+   *     width: Int
+   *   }
+   *
+   *   type Query {
+   *     resource: Resource
+   *   }
+   * `);
+   *
+   * const Resource = assertInterfaceType(schema.getType('Resource'));
+   * const implementations = schema.getImplementations(Resource);
+   *
+   * implementations.interfaces.map((type) => type.name); // => ['Image']
+   * implementations.objects.map((type) => type.name); // => ['Photo']
+   * ```
+   */
 
@@ -315,2 +674,39 @@ getImplementations(interfaceType) {
   }
+  /**
+   * Returns whether one type is a possible runtime subtype of an abstract type.
+   * @param abstractType - Interface or union type to inspect.
+   * @param maybeSubType - Object or interface type to test as a possible subtype.
+   * @returns True when the subtype may satisfy the abstract type.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { assertInterfaceType, assertObjectType } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   interface Node {
+   *     id: ID!
+   *   }
+   *
+   *   type User implements Node {
+   *     id: ID!
+   *   }
+   *
+   *   type Review {
+   *     body: String
+   *   }
+   *
+   *   type Query {
+   *     node: Node
+   *     review: Review
+   *   }
+   * `);
+   *
+   * const Node = assertInterfaceType(schema.getType('Node'));
+   * const User = assertObjectType(schema.getType('User'));
+   * const Review = assertObjectType(schema.getType('Review'));
+   *
+   * schema.isSubType(Node, User); // => true
+   * schema.isSubType(Node, Review); // => false
+   * ```
+   */
 
@@ -344,2 +740,20 @@ isSubType(abstractType, maybeSubType) {
   }
+  /**
+   * Returns directives available in this schema.
+   * @returns Directives available in this schema.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   directive @upper on FIELD_DEFINITION
+   *
+   *   type Query {
+   *     greeting: String @upper
+   *   }
+   * `);
+   *
+   * schema.getDirectives().map((directive) => directive.name); // => ['include', 'skip', 'deprecated', 'specifiedBy', 'oneOf', 'upper']
+   * ```
+   */
 
@@ -349,2 +763,22 @@ getDirectives() {
   }
+  /**
+   * Returns the current directive definition.
+   * @param name - The GraphQL name to look up.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   directive @upper on FIELD_DEFINITION
+   *
+   *   type Query {
+   *     greeting: String @upper
+   *   }
+   * `);
+   *
+   * schema.getDirective('upper')?.name; // => 'upper'
+   * schema.getDirective('missing'); // => undefined
+   * ```
+   */
 
@@ -354,2 +788,26 @@ getDirective(name) {
   }
+  /**
+   * Returns a normalized configuration object for this object.
+   *
+   * The returned config preserves the original `assumeValid` flag so the schema
+   * can be recreated with the same validation behavior.
+   * @returns A configuration object that can be used to recreate this object.
+   * @example
+   * ```ts
+   * import { buildSchema } from 'graphql/utilities';
+   * import { GraphQLSchema } from 'graphql/type';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   *
+   * const config = schema.toConfig();
+   * const schemaCopy = new GraphQLSchema(config);
+   *
+   * config.query?.name; // => 'Query'
+   * schemaCopy.getQueryType()?.name; // => 'Query'
+   * ```
+   */
 
@@ -356,0 +814,0 @@ toConfig() {

type/validate.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation */
 import { GraphQLError } from '../error/GraphQLError';
@@ -9,2 +10,18 @@ import type { GraphQLSchema } from './schema';
  * an empty array if no errors were encountered and the Schema is valid.
+ * @param schema - GraphQL schema to use.
+ * @returns Schema validation errors, or an empty array when the schema is valid.
+ * @example
+ * ```ts
+ * import { validateSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ * const errors = validateSchema(schema);
+ *
+ * errors; // => []
+ * ```
  */
@@ -17,3 +34,17 @@ export declare function validateSchema(
  * it is invalid.
+ * @param schema - GraphQL schema to use.
+ * @example
+ * ```ts
+ * import { assertValidSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * assertValidSchema(schema); // does not throw
+ * ```
  */
 export declare function assertValidSchema(schema: GraphQLSchema): void;

type/validate.js

@@ -25,2 +25,4 @@ 'use strict';
 
+/** @category Validation */
+
 /**
@@ -32,2 +34,18 @@ * Implements the "Type Validation" sub-sections of the specification's
  * an empty array if no errors were encountered and the Schema is valid.
+ * @param schema - GraphQL schema to use.
+ * @returns Schema validation errors, or an empty array when the schema is valid.
+ * @example
+ * ```ts
+ * import { validateSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ * const errors = validateSchema(schema);
+ *
+ * errors; // => []
+ * ```
  */
@@ -55,2 +73,16 @@ function validateSchema(schema) {
  * it is invalid.
+ * @param schema - GraphQL schema to use.
+ * @example
+ * ```ts
+ * import { assertValidSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * assertValidSchema(schema); // does not throw
+ * ```
  */
@@ -57,0 +89,0 @@

type/validate.mjs

@@ -0,1 +1,2 @@
+/** @category Validation */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -27,2 +28,18 @@ import { GraphQLError } from '../error/GraphQLError.mjs';
  * an empty array if no errors were encountered and the Schema is valid.
+ * @param schema - GraphQL schema to use.
+ * @returns Schema validation errors, or an empty array when the schema is valid.
+ * @example
+ * ```ts
+ * import { validateSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ * const errors = validateSchema(schema);
+ *
+ * errors; // => []
+ * ```
  */
@@ -51,2 +68,16 @@
  * it is invalid.
+ * @param schema - GraphQL schema to use.
+ * @example
+ * ```ts
+ * import { assertValidSchema } from 'graphql/type';
+ * import { buildSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * assertValidSchema(schema); // does not throw
+ * ```
  */
@@ -53,0 +84,0 @@

utilities/assertValidName.d.ts

@@ -0,4 +1,16 @@
+/** @category Validation */
 import { GraphQLError } from '../error/GraphQLError';
 /**
- * Upholds the spec rules about naming.
+ * Upholds the spec rules about naming. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` instead because assertValidName
+ * will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertValidName } from 'graphql/utilities';
+ *
+ * assertValidName('User'); // => 'User'
+ * assertValidName('__typename'); // throws an error
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
@@ -8,3 +20,16 @@ */
 /**
- * Returns an Error if a name is invalid.
+ * Returns an Error if a name is invalid. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` and catch the thrown GraphQLError
+ * instead because isValidNameError will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns A GraphQLError if the name is invalid; otherwise undefined.
+ * @example
+ * ```ts
+ * import { isValidNameError } from 'graphql/utilities';
+ *
+ * isValidNameError('User'); // => undefined
+ *
+ * const error = isValidNameError('__typename');
+ * error.message; // => 'Name "__typename" must not begin with "__", which is reserved by GraphQL introspection.'
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
@@ -11,0 +36,0 @@ */

utilities/assertValidName.js

@@ -15,6 +15,19 @@ 'use strict';
 
+/** @category Validation */
+
 /* c8 ignore start */
 
 /**
- * Upholds the spec rules about naming.
+ * Upholds the spec rules about naming. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` instead because assertValidName
+ * will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertValidName } from 'graphql/utilities';
+ *
+ * assertValidName('User'); // => 'User'
+ * assertValidName('__typename'); // throws an error
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
@@ -32,3 +45,16 @@ */
 /**
- * Returns an Error if a name is invalid.
+ * Returns an Error if a name is invalid. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` and catch the thrown GraphQLError
+ * instead because isValidNameError will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns A GraphQLError if the name is invalid; otherwise undefined.
+ * @example
+ * ```ts
+ * import { isValidNameError } from 'graphql/utilities';
+ *
+ * isValidNameError('User'); // => undefined
+ *
+ * const error = isValidNameError('__typename');
+ * error.message; // => 'Name "__typename" must not begin with "__", which is reserved by GraphQL introspection.'
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
@@ -35,0 +61,0 @@ */

utilities/assertValidName.mjs

@@ -0,1 +1,2 @@
+/** @category Validation */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -7,3 +8,14 @@ import { GraphQLError } from '../error/GraphQLError.mjs';
 /**
- * Upholds the spec rules about naming.
+ * Upholds the spec rules about naming. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` instead because assertValidName
+ * will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns The validated GraphQL name.
+ * @example
+ * ```ts
+ * import { assertValidName } from 'graphql/utilities';
+ *
+ * assertValidName('User'); // => 'User'
+ * assertValidName('__typename'); // throws an error
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
@@ -22,3 +34,16 @@ */
 /**
- * Returns an Error if a name is invalid.
+ * Returns an Error if a name is invalid. This deprecated helper is retained for
+ * backwards compatibility; call `assertName` and catch the thrown GraphQLError
+ * instead because isValidNameError will be removed in v17.
+ * @param name - The GraphQL name to validate.
+ * @returns A GraphQLError if the name is invalid; otherwise undefined.
+ * @example
+ * ```ts
+ * import { isValidNameError } from 'graphql/utilities';
+ *
+ * isValidNameError('User'); // => undefined
+ *
+ * const error = isValidNameError('__typename');
+ * error.message; // => 'Name "__typename" must not begin with "__", which is reserved by GraphQL introspection.'
+ * ```
  * @deprecated Please use `assertName` instead. Will be removed in v17
@@ -25,0 +50,0 @@ */

utilities/astFromValue.d.ts

@@ -0,1 +1,2 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
@@ -7,6 +8,4 @@ import type { ValueNode } from '../language/ast';
  * Function will match JavaScript/JSON values to GraphQL AST schema format
- * by using suggested GraphQLInputType. For example:
+ * by using suggested GraphQLInputType.
  *
- *     astFromValue("value", GraphQLString)
- *
  * A GraphQL type must be provided, which will be used to interpret different
@@ -24,3 +23,34 @@ * JavaScript values.
  * | 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
+ * ```
  */
@@ -27,0 +57,0 @@ export declare function astFromValue(

utilities/astFromValue.js

@@ -22,9 +22,9 @@ 'use strict';
 
+/** @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:
+ * by using suggested GraphQLInputType.
  *
- *     astFromValue("value", GraphQLString)
- *
  * A GraphQL type must be provided, which will be used to interpret different
@@ -42,3 +42,34 @@ * JavaScript values.
  * | 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
+ * ```
  */
@@ -190,4 +221,6 @@ function astFromValue(value, type) {
  *   - NegativeSign? NonZeroDigit ( Digit+ )?
+ *
+ * @internal
  */
 
 const integerStringRegExp = /^-?(?:0|[1-9][0-9]*)$/;

utilities/astFromValue.mjs

@@ -0,1 +1,2 @@
+/** @category Values */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -17,6 +18,4 @@ import { invariant } from '../jsutils/invariant.mjs';
  * Function will match JavaScript/JSON values to GraphQL AST schema format
- * by using suggested GraphQLInputType. For example:
+ * by using suggested GraphQLInputType.
  *
- *     astFromValue("value", GraphQLString)
- *
  * A GraphQL type must be provided, which will be used to interpret different
@@ -34,3 +33,34 @@ * JavaScript values.
  * | 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
+ * ```
  */
@@ -177,4 +207,6 @@
  *   - NegativeSign? NonZeroDigit ( Digit+ )?
+ *
+ * @internal
  */
 
 const integerStringRegExp = /^-?(?:0|[1-9][0-9]*)$/;

utilities/buildASTSchema.d.ts

@@ -0,1 +1,2 @@
+/** @category Schema Construction */
 import type { DocumentNode } from '../language/ast';
@@ -6,2 +7,3 @@ import type { ParseOptions } from '../language/parser';
 import { GraphQLSchema } from '../type/schema';
+/** Options used when building a schema from SDL or a parsed SDL document. */
 export interface BuildSchemaOptions extends GraphQLSchemaValidationOptions {
@@ -16,4 +18,3 @@ /**
 /**
- * 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.
  *
@@ -23,4 +24,32 @@ * If no schema definition is provided, then it will look for types named Query,
  *
- * 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
+ * ```
  */
@@ -32,4 +61,34 @@ export declare function buildASTSchema(
 /**
- * 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
+ * ```
  */
@@ -36,0 +95,0 @@ export declare function buildSchema(

utilities/buildASTSchema.js

@@ -23,5 +23,6 @@ 'use strict';
 
+/** @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.
  *
@@ -31,4 +32,32 @@ * If no schema definition is provided, then it will look for types named Query,
  *
- * 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
+ * ```
  */
@@ -98,4 +127,34 @@ function buildASTSchema(documentAST, options) {
 /**
- * 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
+ * ```
  */
@@ -102,0 +161,0 @@

utilities/buildASTSchema.mjs

@@ -0,1 +1,2 @@
+/** @category Schema Construction */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -8,6 +9,6 @@ import { Kind } from '../language/kinds.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.
  *
@@ -17,4 +18,32 @@ * If no schema definition is provided, then it will look for types named Query,
  *
- * 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
+ * ```
  */
@@ -80,4 +109,34 @@ export function buildASTSchema(documentAST, options) {
 /**
- * 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
+ * ```
  */
@@ -84,0 +143,0 @@

utilities/buildClientSchema.d.ts

@@ -0,1 +1,2 @@
+/** @category Introspection */
 import type { GraphQLSchemaValidationOptions } from '../type/schema';
@@ -15,2 +16,16 @@ import { GraphQLSchema } from '../type/schema';
  * 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'
+ * ```
  */
@@ -17,0 +32,0 @@ export declare function buildClientSchema(

utilities/buildClientSchema.js

@@ -30,2 +30,4 @@ 'use strict';
 
+/** @category Introspection */
+
 /**
@@ -42,2 +44,16 @@ * Build a GraphQLSchema for use by client tools.
  * 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'
+ * ```
  */
@@ -44,0 +60,0 @@ function buildClientSchema(introspection, options) {

utilities/buildClientSchema.mjs

@@ -0,1 +1,2 @@
+/** @category Introspection */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -37,2 +38,16 @@ import { inspect } from '../jsutils/inspect.mjs';
  * 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'
+ * ```
  */
@@ -39,0 +54,0 @@

utilities/coerceInputValue.d.ts

@@ -0,1 +1,2 @@
+/** @category Values */
 import { GraphQLError } from '../error/GraphQLError';
@@ -10,2 +11,47 @@ import type { GraphQLInputType } from '../type/definition';
  * 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.' } ]
+ * ```
  */
@@ -12,0 +58,0 @@ export declare function coerceInputValue(

utilities/coerceInputValue.js

@@ -28,4 +28,51 @@ 'use strict';
 
+/** @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.' } ]
+ * ```
  */
@@ -32,0 +79,0 @@ function coerceInputValue(inputValue, type, onError = defaultOnError) {

utilities/coerceInputValue.mjs

@@ -0,1 +1,2 @@
+/** @category Values */
 import { didYouMean } from '../jsutils/didYouMean.mjs';
@@ -19,2 +20,47 @@ import { inspect } from '../jsutils/inspect.mjs';
  * 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.' } ]
+ * ```
  */
@@ -21,0 +67,0 @@ export function coerceInputValue(inputValue, type, onError = defaultOnError) {

utilities/concatAST.d.ts

@@ -0,1 +1,2 @@
+/** @category AST Utilities */
 import type { DocumentNode } from '../language/ast';
@@ -6,2 +7,13 @@ /**
  * 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
+ * ```
  */
@@ -8,0 +20,0 @@ export declare function concatAST(

utilities/concatAST.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category AST Utilities */
+
 /**
@@ -15,2 +17,13 @@ * Provided a collection of ASTs, presumably each from different files,
  * 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
+ * ```
  */
@@ -17,0 +30,0 @@ function concatAST(documents) {

utilities/concatAST.mjs

@@ -0,1 +1,2 @@
+/** @category AST Utilities */
 import { Kind } from '../language/kinds.mjs';
@@ -6,2 +7,13 @@ /**
  * 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
+ * ```
  */
@@ -8,0 +20,0 @@

utilities/extendSchema.d.ts

@@ -0,1 +1,2 @@
+/** @category Schema Construction */
 import type { DocumentNode } from '../language/ast';
@@ -26,2 +27,56 @@ import type {
  * 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
+ * ```
  */
@@ -33,5 +88,3 @@ export declare function extendSchema(
 ): GraphQLSchema;
-/**
- * @internal
- */
+/** @internal */
 export declare function extendSchemaImpl(
@@ -38,0 +91,0 @@ schemaConfig: GraphQLSchemaNormalizedConfig,

utilities/extendSchema.js

@@ -39,2 +39,4 @@ 'use strict';
 
+/** @category Schema Construction */
+
 /**
@@ -51,2 +53,56 @@ * Produces a new schema given an existing schema and a document which may
  * 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
+ * ```
  */
@@ -74,5 +130,3 @@ function extendSchema(schema, documentAST, options) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -832,2 +886,4 @@ function extendSchemaImpl(schemaConfig, documentAST, options) {
  * deprecation reason.
+ *
+ * @internal
  */
@@ -847,2 +903,4 @@
  * Given a scalar node, returns the string value for the specifiedByURL.
+ *
+ * @internal
  */
@@ -862,2 +920,4 @@
  * Given an input object node, returns if the node should be OneOf.
+ *
+ * @internal
  */
@@ -864,0 +924,0 @@

utilities/extendSchema.mjs

@@ -0,1 +1,2 @@
+/** @category Schema Construction */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -59,2 +60,56 @@ import { inspect } from '../jsutils/inspect.mjs';
  * 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
+ * ```
  */
@@ -82,5 +137,3 @@ export function extendSchema(schema, documentAST, options) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -829,2 +882,4 @@ export function extendSchemaImpl(schemaConfig, documentAST, options) {
  * deprecation reason.
+ *
+ * @internal
  */
@@ -841,2 +896,4 @@
  * Given a scalar node, returns the string value for the specifiedByURL.
+ *
+ * @internal
  */
@@ -853,2 +910,4 @@
  * Given an input object node, returns if the node should be OneOf.
+ *
+ * @internal
  */
@@ -855,0 +914,0 @@

utilities/findBreakingChanges.d.ts

@@ -0,36 +1,67 @@
+/** @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;
@@ -41,2 +72,34 @@ }
  * 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/
+ * ```
  */
@@ -50,2 +113,34 @@ export declare function findBreakingChanges(
  * 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/
+ * ```
  */
@@ -52,0 +147,0 @@ export declare function findDangerousChanges(

utilities/findBreakingChanges.js

@@ -26,2 +26,5 @@ 'use strict';
 
+/** @category Schema Changes */
+
+/** Categories of schema changes that may break existing operations. */
 var BreakingChangeType;
@@ -56,2 +59,3 @@ exports.BreakingChangeType = BreakingChangeType;
 
+/** Categories of schema changes that may be dangerous for existing operations. */
 var DangerousChangeType;
@@ -77,2 +81,34 @@ exports.DangerousChangeType = DangerousChangeType;
  * 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/
+ * ```
  */
@@ -88,2 +124,34 @@ function findBreakingChanges(oldSchema, newSchema) {
  * 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/
+ * ```
  */
@@ -90,0 +158,0 @@

utilities/findBreakingChanges.mjs

@@ -0,1 +1,2 @@
+/** @category Schema Changes */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -21,2 +22,4 @@ import { invariant } from '../jsutils/invariant.mjs';
 import { sortValueNode } from './sortValueNode.mjs';
+/** Categories of schema changes that may break existing operations. */
+
 var BreakingChangeType;
@@ -49,2 +52,4 @@
 export { BreakingChangeType };
+/** Categories of schema changes that may be dangerous for existing operations. */
+
 var DangerousChangeType;
@@ -64,2 +69,3 @@
 export { DangerousChangeType };
+/** Description of a schema change that may break existing operations. */
 
@@ -69,2 +75,34 @@ /**
  * 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/
+ * ```
  */
@@ -80,2 +118,34 @@ export function findBreakingChanges(oldSchema, newSchema) {
  * 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/
+ * ```
  */
@@ -82,0 +152,0 @@

utilities/getIntrospectionQuery.d.ts

@@ -0,3 +1,5 @@
+/** @category Introspection */
 import type { Maybe } from '../jsutils/Maybe';
 import type { DirectiveLocation } from '../language/directiveLocation';
+/** Options controlling which fields are included in the introspection query. */
 export interface IntrospectionOptions {
@@ -52,2 +54,38 @@ /**
  * Accepts optional IntrospectionOptions.
+ * @param options - Optional configuration for this operation.
+ * @returns The resolved introspection query.
+ * @example
+ * ```ts
+ * // Generate the default introspection query.
+ * import { getIntrospectionQuery } from 'graphql/utilities';
+ *
+ * const query = getIntrospectionQuery();
+ *
+ * query; // matches /__schema/
+ * query; // matches /description/
+ * query; // does not match /specifiedByURL/
+ * ```
+ * @example
+ * ```ts
+ * // This variant customizes optional introspection fields and nesting depth.
+ * import { getIntrospectionQuery } from 'graphql/utilities';
+ *
+ * const query = getIntrospectionQuery({
+ *   descriptions: false,
+ *   specifiedByUrl: true,
+ *   directiveIsRepeatable: true,
+ *   schemaDescription: true,
+ *   inputValueDeprecation: true,
+ *   experimentalDirectiveDeprecation: true,
+ *   oneOf: true,
+ *   typeDepth: 3,
+ * });
+ *
+ * query; // does not match /description/
+ * query; // matches /specifiedByURL/
+ * query; // matches /isRepeatable/
+ * query; // matches /includeDeprecated: true/
+ * query; // matches /isOneOf/
+ * (query.match(/ofType/g)?.length ?? 0) > 0; // => true
+ * ```
  */
@@ -57,17 +95,27 @@ export declare function getIntrospectionQuery(
 ): string;
+/** The result shape returned by a full introspection query. */
 export interface IntrospectionQuery {
+  /** The  schema. */
   readonly __schema: IntrospectionSchema;
 }
+/** The introspection representation of a GraphQL schema. */
 export interface IntrospectionSchema {
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** The root object type used for query operations. */
   readonly queryType: IntrospectionNamedTypeRef<IntrospectionObjectType>;
+  /** The root object type used for mutation operations, if supported. */
   readonly mutationType: Maybe<
     IntrospectionNamedTypeRef<IntrospectionObjectType>
   >;
+  /** The root object type used for subscription operations, if supported. */
   readonly subscriptionType: Maybe<
     IntrospectionNamedTypeRef<IntrospectionObjectType>
   >;
+  /** Object types that belong to this union type. */
   readonly types: ReadonlyArray<IntrospectionType>;
+  /** Directives available in this schema or applied to this AST node. */
   readonly directives: ReadonlyArray<IntrospectionDirective>;
 }
+/** Any introspection representation of a GraphQL type. */
 export declare type IntrospectionType =
@@ -80,2 +128,3 @@ | IntrospectionScalarType
   | IntrospectionInputObjectType;
+/** An introspection type that can appear in output position. */
 export declare type IntrospectionOutputType =
@@ -87,2 +136,3 @@ | IntrospectionScalarType
   | IntrospectionEnumType;
+/** An introspection type that can appear in input position. */
 export declare type IntrospectionInputType =
@@ -92,13 +142,24 @@ | IntrospectionScalarType
   | IntrospectionInputObjectType;
+/** The introspection representation of a scalar type. */
 export interface IntrospectionScalarType {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'SCALAR';
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** URL identifying the behavior specified for this custom scalar. */
   readonly specifiedByURL?: Maybe<string>;
 }
+/** The introspection representation of an object type. */
 export interface IntrospectionObjectType {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'OBJECT';
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields: ReadonlyArray<IntrospectionField>;
+  /** Interfaces implemented by this object or interface type. */
   readonly interfaces: ReadonlyArray<
@@ -108,10 +169,17 @@ IntrospectionNamedTypeRef<IntrospectionInterfaceType>
 }
+/** The introspection representation of an interface type. */
 export interface IntrospectionInterfaceType {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'INTERFACE';
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Fields declared by this object, interface, input object, or literal. */
   readonly fields: ReadonlyArray<IntrospectionField>;
+  /** Interfaces implemented by this object or interface type. */
   readonly interfaces: ReadonlyArray<
     IntrospectionNamedTypeRef<IntrospectionInterfaceType>
   >;
+  /** Object types that may be returned for this abstract type. */
   readonly possibleTypes: ReadonlyArray<
@@ -121,6 +189,11 @@ IntrospectionNamedTypeRef<IntrospectionObjectType>
 }
+/** The introspection representation of a union type. */
 export interface IntrospectionUnionType {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'UNION';
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Object types that may be returned for this abstract type. */
   readonly possibleTypes: ReadonlyArray<
@@ -130,27 +203,51 @@ IntrospectionNamedTypeRef<IntrospectionObjectType>
 }
+/** The introspection representation of an enum type. */
 export interface IntrospectionEnumType {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'ENUM';
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Values declared by this enum type. */
   readonly enumValues: ReadonlyArray<IntrospectionEnumValue>;
 }
+/** The introspection representation of an input object type. */
 export interface IntrospectionInputObjectType {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'INPUT_OBJECT';
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Input fields declared by this input object type. */
   readonly inputFields: ReadonlyArray<IntrospectionInputValue>;
+  /** Whether this input object uses the experimental OneOf input object semantics. */
   readonly isOneOf: boolean;
 }
+/**
+ * The introspection representation of a list type reference.
+ * @typeParam T - The introspection type reference wrapped by this list type reference.
+ */
 export interface IntrospectionListTypeRef<
   T extends IntrospectionTypeRef = IntrospectionTypeRef,
 > {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'LIST';
+  /** The type wrapped by this list or non-null type. */
   readonly ofType: T;
 }
+/**
+ * The introspection representation of a non-null type reference.
+ * @typeParam T - The introspection type reference wrapped by this non-null type reference.
+ */
 export interface IntrospectionNonNullTypeRef<
   T extends IntrospectionTypeRef = IntrospectionTypeRef,
 > {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: 'NON_NULL';
+  /** The type wrapped by this list or non-null type. */
   readonly ofType: T;
 }
+/** Any introspection representation of a type reference. */
 export declare type IntrospectionTypeRef =
@@ -162,2 +259,3 @@ | IntrospectionNamedTypeRef
     >;
+/** An introspection type reference that can appear in output position. */
 export declare type IntrospectionOutputTypeRef =
@@ -170,2 +268,3 @@ | IntrospectionNamedTypeRef<IntrospectionOutputType>
     >;
+/** An introspection type reference that can appear in input position. */
 export declare type IntrospectionInputTypeRef =
@@ -178,38 +277,71 @@ | IntrospectionNamedTypeRef<IntrospectionInputType>
     >;
+/**
+ * The introspection representation of a named type reference.
+ * @typeParam T - The introspection type represented by this named type reference.
+ */
 export interface IntrospectionNamedTypeRef<
   T extends IntrospectionType = IntrospectionType,
 > {
+  /** The introspection kind discriminator for this type reference or type. */
   readonly kind: T['kind'];
+  /** The GraphQL name for this schema element. */
   readonly name: string;
 }
+/** The introspection representation of a field. */
 export interface IntrospectionField {
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Arguments accepted by this field or directive. */
   readonly args: ReadonlyArray<IntrospectionInputValue>;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: IntrospectionOutputTypeRef;
+  /** Whether this field, argument, enum value, or input value is deprecated. */
   readonly isDeprecated: boolean;
+  /** Reason this element is deprecated, if one was provided. */
   readonly deprecationReason: Maybe<string>;
 }
+/** The introspection representation of an argument or input field. */
 export interface IntrospectionInputValue {
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** The GraphQL type reference or runtime type for this element. */
   readonly type: IntrospectionInputTypeRef;
+  /** Default value used when no explicit value is supplied. */
   readonly defaultValue: Maybe<string>;
+  /** Whether this field, argument, enum value, or input value is deprecated. */
   readonly isDeprecated?: boolean;
+  /** Reason this element is deprecated, if one was provided. */
   readonly deprecationReason?: Maybe<string>;
 }
+/** The introspection representation of an enum value. */
 export interface IntrospectionEnumValue {
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Whether this field, argument, enum value, or input value is deprecated. */
   readonly isDeprecated: boolean;
+  /** Reason this element is deprecated, if one was provided. */
   readonly deprecationReason: Maybe<string>;
 }
+/** The introspection representation of a directive. */
 export interface IntrospectionDirective {
+  /** The GraphQL name for this schema element. */
   readonly name: string;
+  /** Human-readable description for this schema element, if provided. */
   readonly description?: Maybe<string>;
+  /** Whether this directive may appear more than once at the same location. */
   readonly isRepeatable?: boolean;
+  /** Whether this field, argument, enum value, or input value is deprecated. */
   readonly isDeprecated?: boolean;
+  /** Reason this element is deprecated, if one was provided. */
   readonly deprecationReason?: Maybe<string>;
+  /** Locations where this directive may be applied. */
   readonly locations: ReadonlyArray<DirectiveLocation>;
+  /** Arguments accepted by this field or directive. */
   readonly args: ReadonlyArray<IntrospectionInputValue>;
 }

utilities/getIntrospectionQuery.js

@@ -8,5 +8,45 @@ 'use strict';
 
+/** @category Introspection */
+
+/** Options controlling which fields are included in the introspection query. */
+
 /**
  * Produce the GraphQL query recommended for a full schema introspection.
  * Accepts optional IntrospectionOptions.
+ * @param options - Optional configuration for this operation.
+ * @returns The resolved introspection query.
+ * @example
+ * ```ts
+ * // Generate the default introspection query.
+ * import { getIntrospectionQuery } from 'graphql/utilities';
+ *
+ * const query = getIntrospectionQuery();
+ *
+ * query; // matches /__schema/
+ * query; // matches /description/
+ * query; // does not match /specifiedByURL/
+ * ```
+ * @example
+ * ```ts
+ * // This variant customizes optional introspection fields and nesting depth.
+ * import { getIntrospectionQuery } from 'graphql/utilities';
+ *
+ * const query = getIntrospectionQuery({
+ *   descriptions: false,
+ *   specifiedByUrl: true,
+ *   directiveIsRepeatable: true,
+ *   schemaDescription: true,
+ *   inputValueDeprecation: true,
+ *   experimentalDirectiveDeprecation: true,
+ *   oneOf: true,
+ *   typeDepth: 3,
+ * });
+ *
+ * query; // does not match /description/
+ * query; // matches /specifiedByURL/
+ * query; // matches /isRepeatable/
+ * query; // matches /includeDeprecated: true/
+ * query; // matches /isOneOf/
+ * (query.match(/ofType/g)?.length ?? 0) > 0; // => true
+ * ```
  */
@@ -140,1 +180,2 @@ function getIntrospectionQuery(options) {
 }
+/** The result shape returned by a full introspection query. */

utilities/getIntrospectionQuery.mjs

@@ -0,4 +1,44 @@
+/** @category Introspection */
+
+/** Options controlling which fields are included in the introspection query. */
+
 /**
  * Produce the GraphQL query recommended for a full schema introspection.
  * Accepts optional IntrospectionOptions.
+ * @param options - Optional configuration for this operation.
+ * @returns The resolved introspection query.
+ * @example
+ * ```ts
+ * // Generate the default introspection query.
+ * import { getIntrospectionQuery } from 'graphql/utilities';
+ *
+ * const query = getIntrospectionQuery();
+ *
+ * query; // matches /__schema/
+ * query; // matches /description/
+ * query; // does not match /specifiedByURL/
+ * ```
+ * @example
+ * ```ts
+ * // This variant customizes optional introspection fields and nesting depth.
+ * import { getIntrospectionQuery } from 'graphql/utilities';
+ *
+ * const query = getIntrospectionQuery({
+ *   descriptions: false,
+ *   specifiedByUrl: true,
+ *   directiveIsRepeatable: true,
+ *   schemaDescription: true,
+ *   inputValueDeprecation: true,
+ *   experimentalDirectiveDeprecation: true,
+ *   oneOf: true,
+ *   typeDepth: 3,
+ * });
+ *
+ * query; // does not match /description/
+ * query; // matches /specifiedByURL/
+ * query; // matches /isRepeatable/
+ * query; // matches /includeDeprecated: true/
+ * query; // matches /isOneOf/
+ * (query.match(/ofType/g)?.length ?? 0) > 0; // => true
+ * ```
  */
@@ -132,1 +172,2 @@ export function getIntrospectionQuery(options) {
 }
+/** The result shape returned by a full introspection query. */

utilities/getOperationAST.d.ts

@@ -0,1 +1,2 @@
+/** @category Operations */
 import type { Maybe } from '../jsutils/Maybe';
@@ -7,2 +8,16 @@ import type { DocumentNode, OperationDefinitionNode } from '../language/ast';
  * provided in the document.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param operationName - The optional operation name to select.
+ * @returns The resolved operation ast.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { getOperationAST } from 'graphql/utilities';
+ *
+ * const document = parse('query GetName { name }');
+ * const operation = getOperationAST(document, 'GetName');
+ *
+ * operation.name.value; // => 'GetName'
+ * getOperationAST(document, 'Missing'); // => undefined
+ * ```
  */
@@ -9,0 +24,0 @@ export declare function getOperationAST(

utilities/getOperationAST.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Operations */
+
 /**
@@ -15,2 +17,16 @@ * Returns an operation AST given a document AST and optionally an operation
  * provided in the document.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param operationName - The optional operation name to select.
+ * @returns The resolved operation ast.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { getOperationAST } from 'graphql/utilities';
+ *
+ * const document = parse('query GetName { name }');
+ * const operation = getOperationAST(document, 'GetName');
+ *
+ * operation.name.value; // => 'GetName'
+ * getOperationAST(document, 'Missing'); // => undefined
+ * ```
  */
@@ -17,0 +33,0 @@ function getOperationAST(documentAST, operationName) {

utilities/getOperationAST.mjs

@@ -0,1 +1,2 @@
+/** @category Operations */
 import { Kind } from '../language/kinds.mjs';
@@ -6,2 +7,16 @@ /**
  * provided in the document.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @param operationName - The optional operation name to select.
+ * @returns The resolved operation ast.
+ * @example
+ * ```ts
+ * import { parse } from 'graphql/language';
+ * import { getOperationAST } from 'graphql/utilities';
+ *
+ * const document = parse('query GetName { name }');
+ * const operation = getOperationAST(document, 'GetName');
+ *
+ * operation.name.value; // => 'GetName'
+ * getOperationAST(document, 'Missing'); // => undefined
+ * ```
  */
@@ -8,0 +23,0 @@

utilities/getOperationRootType.d.ts

@@ -0,1 +1,2 @@
+/** @category Operations */
 import type {
@@ -8,4 +9,20 @@ OperationDefinitionNode,
 /**
- * Extracts the root type of the operation from the schema.
+ * Extracts the root type of the operation from the schema. This deprecated
+ * helper is retained for backwards compatibility; call
+ * `GraphQLSchema.getRootType` instead because getOperationRootType will be
+ * removed in v17.
+ * @param schema - GraphQL schema to use.
+ * @param operation - The operation definition to inspect.
+ * @returns The resolved operation root type.
+ * @example
+ * ```ts
+ * import { buildSchema, getOperationRootType } from 'graphql/utilities';
+ * import { parse } from 'graphql/language';
  *
+ * const schema = buildSchema('type Query { name: String }');
+ * const operation = parse('{ name }').definitions[0];
+ * const rootType = getOperationRootType(schema, operation);
+ *
+ * rootType.name; // => 'Query'
+ * ```
  * @deprecated Please use `GraphQLSchema.getRootType` instead. Will be removed in v17
@@ -12,0 +29,0 @@ */

utilities/getOperationRootType.js

@@ -10,5 +10,23 @@ 'use strict';
 
+/** @category Operations */
+
 /**
- * Extracts the root type of the operation from the schema.
+ * Extracts the root type of the operation from the schema. This deprecated
+ * helper is retained for backwards compatibility; call
+ * `GraphQLSchema.getRootType` instead because getOperationRootType will be
+ * removed in v17.
+ * @param schema - GraphQL schema to use.
+ * @param operation - The operation definition to inspect.
+ * @returns The resolved operation root type.
+ * @example
+ * ```ts
+ * import { buildSchema, getOperationRootType } from 'graphql/utilities';
+ * import { parse } from 'graphql/language';
  *
+ * const schema = buildSchema('type Query { name: String }');
+ * const operation = parse('{ name }').definitions[0];
+ * const rootType = getOperationRootType(schema, operation);
+ *
+ * rootType.name; // => 'Query'
+ * ```
  * @deprecated Please use `GraphQLSchema.getRootType` instead. Will be removed in v17
@@ -15,0 +33,0 @@ */

utilities/getOperationRootType.mjs

@@ -0,6 +1,23 @@
+/** @category Operations */
 import { GraphQLError } from '../error/GraphQLError.mjs';
 
 /**
- * Extracts the root type of the operation from the schema.
+ * Extracts the root type of the operation from the schema. This deprecated
+ * helper is retained for backwards compatibility; call
+ * `GraphQLSchema.getRootType` instead because getOperationRootType will be
+ * removed in v17.
+ * @param schema - GraphQL schema to use.
+ * @param operation - The operation definition to inspect.
+ * @returns The resolved operation root type.
+ * @example
+ * ```ts
+ * import { buildSchema, getOperationRootType } from 'graphql/utilities';
+ * import { parse } from 'graphql/language';
  *
+ * const schema = buildSchema('type Query { name: String }');
+ * const operation = parse('{ name }').definitions[0];
+ * const rootType = getOperationRootType(schema, operation);
+ *
+ * rootType.name; // => 'Query'
+ * ```
  * @deprecated Please use `GraphQLSchema.getRootType` instead. Will be removed in v17
@@ -7,0 +24,0 @@ */

utilities/index.d.ts

@@ -0,1 +1,8 @@
+/**
+ * Utilities for building schemas, working with introspection, transforming ASTs,
+ * and comparing GraphQL types.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { getIntrospectionQuery } from './getIntrospectionQuery';
@@ -2,0 +9,0 @@ export type {

utilities/index.mjs

@@ -0,1 +1,8 @@
+/**
+ * Utilities for building schemas, working with introspection, transforming ASTs,
+ * and comparing GraphQL types.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 // Produce the GraphQL query recommended for a full schema introspection.
@@ -2,0 +9,0 @@ export { getIntrospectionQuery } from './getIntrospectionQuery.mjs';

utilities/introspectionFromSchema.d.ts

@@ -0,1 +1,2 @@
+/** @category Introspection */
 import type { GraphQLSchema } from '../type/schema';
@@ -14,2 +15,55 @@ import type {
  * of the server context, for instance when doing schema comparisons.
+ * @param schema - GraphQL schema to use.
+ * @param options - Optional configuration for this operation.
+ * @returns Introspection result data for the schema.
+ * @example
+ * ```ts
+ * // Include schema metadata using the default introspection options.
+ * import { buildSchema, introspectionFromSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   scalar Url @specifiedBy(url: "https://url.spec.whatwg.org/")
+ *
+ *   type Query {
+ *     homepage: Url
+ *   }
+ * `);
+ *
+ * const introspection = introspectionFromSchema(schema);
+ * const urlType = introspection.__schema.types.find((type) => type.name === 'Url');
+ *
+ * urlType.specifiedByURL; // => 'https://url.spec.whatwg.org/'
+ * ```
+ * @example
+ * ```ts
+ * // This variant disables optional introspection metadata.
+ * import { buildSchema, introspectionFromSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   scalar Url @specifiedBy(url: "https://url.spec.whatwg.org/")
+ *
+ *   type Query {
+ *     homepage: Url
+ *   }
+ * `);
+ *
+ * const introspection = introspectionFromSchema(schema, {
+ *   descriptions: false,
+ *   specifiedByUrl: false,
+ *   directiveIsRepeatable: false,
+ *   schemaDescription: false,
+ *   inputValueDeprecation: false,
+ *   experimentalDirectiveDeprecation: false,
+ *   oneOf: false,
+ * });
+ * const urlType = introspection.__schema.types.find((type) => type.name === 'Url');
+ * const deprecatedDirective = introspection.__schema.directives.find(
+ *   (directive) => directive.name === 'deprecated',
+ * );
+ *
+ * urlType.specifiedByURL; // => undefined
+ * urlType.description; // => undefined
+ * introspection.__schema.description; // => undefined
+ * deprecatedDirective.isRepeatable; // => undefined
+ * ```
  */
@@ -16,0 +70,0 @@ export declare function introspectionFromSchema(

utilities/introspectionFromSchema.js

@@ -16,2 +16,4 @@ 'use strict';
 
+/** @category Introspection */
+
 /**
@@ -25,2 +27,55 @@ * Build an IntrospectionQuery from a GraphQLSchema
  * of the server context, for instance when doing schema comparisons.
+ * @param schema - GraphQL schema to use.
+ * @param options - Optional configuration for this operation.
+ * @returns Introspection result data for the schema.
+ * @example
+ * ```ts
+ * // Include schema metadata using the default introspection options.
+ * import { buildSchema, introspectionFromSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   scalar Url @specifiedBy(url: "https://url.spec.whatwg.org/")
+ *
+ *   type Query {
+ *     homepage: Url
+ *   }
+ * `);
+ *
+ * const introspection = introspectionFromSchema(schema);
+ * const urlType = introspection.__schema.types.find((type) => type.name === 'Url');
+ *
+ * urlType.specifiedByURL; // => 'https://url.spec.whatwg.org/'
+ * ```
+ * @example
+ * ```ts
+ * // This variant disables optional introspection metadata.
+ * import { buildSchema, introspectionFromSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   scalar Url @specifiedBy(url: "https://url.spec.whatwg.org/")
+ *
+ *   type Query {
+ *     homepage: Url
+ *   }
+ * `);
+ *
+ * const introspection = introspectionFromSchema(schema, {
+ *   descriptions: false,
+ *   specifiedByUrl: false,
+ *   directiveIsRepeatable: false,
+ *   schemaDescription: false,
+ *   inputValueDeprecation: false,
+ *   experimentalDirectiveDeprecation: false,
+ *   oneOf: false,
+ * });
+ * const urlType = introspection.__schema.types.find((type) => type.name === 'Url');
+ * const deprecatedDirective = introspection.__schema.directives.find(
+ *   (directive) => directive.name === 'deprecated',
+ * );
+ *
+ * urlType.specifiedByURL; // => undefined
+ * urlType.description; // => undefined
+ * introspection.__schema.description; // => undefined
+ * deprecatedDirective.isRepeatable; // => undefined
+ * ```
  */
@@ -27,0 +82,0 @@ function introspectionFromSchema(schema, options) {

utilities/introspectionFromSchema.mjs

@@ -0,1 +1,2 @@
+/** @category Introspection */
 import { invariant } from '../jsutils/invariant.mjs';
@@ -13,2 +14,55 @@ import { parse } from '../language/parser.mjs';
  * of the server context, for instance when doing schema comparisons.
+ * @param schema - GraphQL schema to use.
+ * @param options - Optional configuration for this operation.
+ * @returns Introspection result data for the schema.
+ * @example
+ * ```ts
+ * // Include schema metadata using the default introspection options.
+ * import { buildSchema, introspectionFromSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   scalar Url @specifiedBy(url: "https://url.spec.whatwg.org/")
+ *
+ *   type Query {
+ *     homepage: Url
+ *   }
+ * `);
+ *
+ * const introspection = introspectionFromSchema(schema);
+ * const urlType = introspection.__schema.types.find((type) => type.name === 'Url');
+ *
+ * urlType.specifiedByURL; // => 'https://url.spec.whatwg.org/'
+ * ```
+ * @example
+ * ```ts
+ * // This variant disables optional introspection metadata.
+ * import { buildSchema, introspectionFromSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   scalar Url @specifiedBy(url: "https://url.spec.whatwg.org/")
+ *
+ *   type Query {
+ *     homepage: Url
+ *   }
+ * `);
+ *
+ * const introspection = introspectionFromSchema(schema, {
+ *   descriptions: false,
+ *   specifiedByUrl: false,
+ *   directiveIsRepeatable: false,
+ *   schemaDescription: false,
+ *   inputValueDeprecation: false,
+ *   experimentalDirectiveDeprecation: false,
+ *   oneOf: false,
+ * });
+ * const urlType = introspection.__schema.types.find((type) => type.name === 'Url');
+ * const deprecatedDirective = introspection.__schema.directives.find(
+ *   (directive) => directive.name === 'deprecated',
+ * );
+ *
+ * urlType.specifiedByURL; // => undefined
+ * urlType.description; // => undefined
+ * introspection.__schema.description; // => undefined
+ * deprecatedDirective.isRepeatable; // => undefined
+ * ```
  */
@@ -15,0 +69,0 @@

utilities/lexicographicSortSchema.d.ts

@@ -0,1 +1,2 @@
+/** @category Schema Construction */
 import { GraphQLSchema } from '../type/schema';
@@ -6,2 +7,36 @@ /**
  * This function returns a sorted copy of the given GraphQLSchema.
+ * @param schema - GraphQL schema to use.
+ * @returns A copy of the schema with types, fields, arguments, and values sorted lexicographically.
+ * @example
+ * ```ts
+ * import { buildSchema, lexicographicSortSchema, printSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     zebra: String
+ *     apple: String
+ *   }
+ *
+ *   enum Episode {
+ *     JEDI
+ *     NEW_HOPE
+ *     EMPIRE
+ *   }
+ * `);
+ *
+ * const sortedSchema = lexicographicSortSchema(schema);
+ *
+ * printSchema(sortedSchema);
+ * // =>
+ * // enum Episode {
+ * //   EMPIRE
+ * //   JEDI
+ * //   NEW_HOPE
+ * // }
+ * //
+ * // type Query {
+ * //   apple: String
+ * //   zebra: String
+ * // }
+ * ```
  */
@@ -8,0 +43,0 @@ export declare function lexicographicSortSchema(

utilities/lexicographicSortSchema.js

@@ -24,2 +24,4 @@ 'use strict';
 
+/** @category Schema Construction */
+
 /**
@@ -29,2 +31,36 @@ * Sort GraphQLSchema.
  * This function returns a sorted copy of the given GraphQLSchema.
+ * @param schema - GraphQL schema to use.
+ * @returns A copy of the schema with types, fields, arguments, and values sorted lexicographically.
+ * @example
+ * ```ts
+ * import { buildSchema, lexicographicSortSchema, printSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     zebra: String
+ *     apple: String
+ *   }
+ *
+ *   enum Episode {
+ *     JEDI
+ *     NEW_HOPE
+ *     EMPIRE
+ *   }
+ * `);
+ *
+ * const sortedSchema = lexicographicSortSchema(schema);
+ *
+ * printSchema(sortedSchema);
+ * // =>
+ * // enum Episode {
+ * //   EMPIRE
+ * //   JEDI
+ * //   NEW_HOPE
+ * // }
+ * //
+ * // type Query {
+ * //   apple: String
+ * //   zebra: String
+ * // }
+ * ```
  */
@@ -31,0 +67,0 @@ function lexicographicSortSchema(schema) {

utilities/lexicographicSortSchema.mjs

@@ -0,1 +1,2 @@
+/** @category Schema Construction */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -29,2 +30,36 @@ import { invariant } from '../jsutils/invariant.mjs';
  * This function returns a sorted copy of the given GraphQLSchema.
+ * @param schema - GraphQL schema to use.
+ * @returns A copy of the schema with types, fields, arguments, and values sorted lexicographically.
+ * @example
+ * ```ts
+ * import { buildSchema, lexicographicSortSchema, printSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     zebra: String
+ *     apple: String
+ *   }
+ *
+ *   enum Episode {
+ *     JEDI
+ *     NEW_HOPE
+ *     EMPIRE
+ *   }
+ * `);
+ *
+ * const sortedSchema = lexicographicSortSchema(schema);
+ *
+ * printSchema(sortedSchema);
+ * // =>
+ * // enum Episode {
+ * //   EMPIRE
+ * //   JEDI
+ * //   NEW_HOPE
+ * // }
+ * //
+ * // type Query {
+ * //   apple: String
+ * //   zebra: String
+ * // }
+ * ```
  */
@@ -31,0 +66,0 @@

utilities/printSchema.d.ts

@@ -0,5 +1,68 @@
+/** @category Schema Printing */
 import type { GraphQLNamedType } from '../type/definition';
 import type { GraphQLSchema } from '../type/schema';
+/**
+ * Prints the schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @upper on FIELD_DEFINITION
+ *
+ *   type Query {
+ *     greeting: String @upper
+ *   }
+ * `);
+ *
+ * printSchema(schema); // => ['directive @upper on FIELD_DEFINITION', '', 'type Query {', '  greeting: String', '}'].join('\n')
+ * ```
+ */
 export declare function printSchema(schema: GraphQLSchema): string;
+/**
+ * Prints the introspection schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printIntrospectionSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const printed = printIntrospectionSchema(schema);
+ *
+ * printed; // matches /type __Schema/
+ * printed; // matches /enum __TypeKind/
+ * printed; // does not match /type Query/
+ * ```
+ */
 export declare function printIntrospectionSchema(schema: GraphQLSchema): string;
+/**
+ * Prints the type.
+ * @param type - The GraphQL type to inspect.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printType } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ *
+ * printType(schema.getType('User')); // => ['type User {', '  id: ID!', '  name: String', '}'].join('\n')
+ * ```
+ */
 export declare function printType(type: GraphQLNamedType): string;

utilities/printSchema.js

@@ -30,2 +30,23 @@ 'use strict';
 
+/** @category Schema Printing */
+
+/**
+ * Prints the schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @upper on FIELD_DEFINITION
+ *
+ *   type Query {
+ *     greeting: String @upper
+ *   }
+ * `);
+ *
+ * printSchema(schema); // => ['directive @upper on FIELD_DEFINITION', '', 'type Query {', '  greeting: String', '}'].join('\n')
+ * ```
+ */
 function printSchema(schema) {
@@ -38,2 +59,23 @@ return printFilteredSchema(
 }
+/**
+ * Prints the introspection schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printIntrospectionSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const printed = printIntrospectionSchema(schema);
+ *
+ * printed; // matches /type __Schema/
+ * printed; // matches /enum __TypeKind/
+ * printed; // does not match /type Query/
+ * ```
+ */
 
@@ -107,2 +149,4 @@ function printIntrospectionSchema(schema) {
  * When using this naming convention, the schema description can be omitted.
+ *
+ * @internal
  */
@@ -131,2 +175,24 @@
 }
+/**
+ * Prints the type.
+ * @param type - The GraphQL type to inspect.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printType } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ *
+ * printType(schema.getType('User')); // => ['type User {', '  id: ID!', '  name: String', '}'].join('\n')
+ * ```
+ */
 
@@ -133,0 +199,0 @@ function printType(type) {

utilities/printSchema.mjs

@@ -0,1 +1,2 @@
+/** @category Schema Printing */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -21,2 +22,22 @@ import { invariant } from '../jsutils/invariant.mjs';
 import { astFromValue } from './astFromValue.mjs';
+/**
+ * Prints the schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @upper on FIELD_DEFINITION
+ *
+ *   type Query {
+ *     greeting: String @upper
+ *   }
+ * `);
+ *
+ * printSchema(schema); // => ['directive @upper on FIELD_DEFINITION', '', 'type Query {', '  greeting: String', '}'].join('\n')
+ * ```
+ */
+
 export function printSchema(schema) {
@@ -29,2 +50,24 @@ return printFilteredSchema(
 }
+/**
+ * Prints the introspection schema.
+ * @param schema - GraphQL schema to use.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printIntrospectionSchema } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * const printed = printIntrospectionSchema(schema);
+ *
+ * printed; // matches /type __Schema/
+ * printed; // matches /enum __TypeKind/
+ * printed; // does not match /type Query/
+ * ```
+ */
+
 export function printIntrospectionSchema(schema) {
@@ -90,2 +133,4 @@ return printFilteredSchema(schema, isSpecifiedDirective, isIntrospectionType);
  * When using this naming convention, the schema description can be omitted.
+ *
+ * @internal
  */
@@ -114,2 +159,24 @@
 }
+/**
+ * Prints the type.
+ * @param type - The GraphQL type to inspect.
+ * @returns The printed string representation.
+ * @example
+ * ```ts
+ * import { buildSchema, printType } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type User {
+ *     id: ID!
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     viewer: User
+ *   }
+ * `);
+ *
+ * printType(schema.getType('User')); // => ['type User {', '  id: ID!', '  name: String', '}'].join('\n')
+ * ```
+ */
 
@@ -116,0 +183,0 @@ export function printType(type) {

utilities/resolveSchemaCoordinate.d.ts

@@ -0,1 +1,2 @@
+/** @category Schema Coordinates */
 import type { SchemaCoordinateNode } from '../language/ast';
@@ -18,2 +19,4 @@ import type { Source } from '../language/source';
  * A resolved schema element may be one of the following kinds:
+ *
+ * @internal
  */
@@ -24,2 +27,3 @@ export interface ResolvedNamedType {
 }
+/** @internal */
 export interface ResolvedField {
@@ -30,2 +34,3 @@ readonly kind: 'Field';
 }
+/** @internal */
 export interface ResolvedInputField {
@@ -36,2 +41,3 @@ readonly kind: 'InputField';
 }
+/** @internal */
 export interface ResolvedEnumValue {
@@ -42,2 +48,3 @@ readonly kind: 'EnumValue';
 }
+/** @internal */
 export interface ResolvedFieldArgument {
@@ -49,2 +56,3 @@ readonly kind: 'FieldArgument';
 }
+/** @internal */
 export interface ResolvedDirective {
@@ -54,2 +62,3 @@ readonly kind: 'Directive';
 }
+/** @internal */
 export interface ResolvedDirectiveArgument {
@@ -60,2 +69,3 @@ readonly kind: 'DirectiveArgument';
 }
+/** A schema element resolved from a schema coordinate. */
 export declare type ResolvedSchemaElement =
@@ -77,2 +87,34 @@ | ResolvedNamedType
  * https://spec.graphql.org/draft/#sec-Schema-Coordinates.Semantics
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { buildSchema, resolveSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @tag(name: String!) on FIELD_DEFINITION
+ *
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     reviews(input: ReviewInput): [String] @tag(name: "reviews")
+ *   }
+ * `);
+ *
+ * resolveSchemaCoordinate(schema, 'Query').kind; // => 'NamedType'
+ * resolveSchemaCoordinate(schema, 'Query.reviews').kind; // => 'Field'
+ * resolveSchemaCoordinate(schema, 'Query.reviews(input:)').kind; // => 'FieldArgument'
+ * resolveSchemaCoordinate(schema, 'ReviewInput.stars').kind; // => 'InputField'
+ * resolveSchemaCoordinate(schema, 'Episode.NEW_HOPE').kind; // => 'EnumValue'
+ * resolveSchemaCoordinate(schema, '@tag').kind; // => 'Directive'
+ * resolveSchemaCoordinate(schema, '@tag(name:)').kind; // => 'DirectiveArgument'
+ * resolveSchemaCoordinate(schema, 'Query.missing'); // => undefined
+ * ```
  */
@@ -85,2 +127,22 @@ export declare function resolveSchemaCoordinate(
  * Resolves schema coordinate from a parsed SchemaCoordinate node.
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the parsed coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ * import { buildSchema, resolveASTSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String): String
+ *   }
+ * `);
+ * const coordinate = parseSchemaCoordinate('Query.greeting(name:)');
+ * const resolved = resolveASTSchemaCoordinate(schema, coordinate);
+ *
+ * resolved.kind; // => 'FieldArgument'
+ * resolved.field.name; // => 'greeting'
+ * resolved.fieldArgument.name; // => 'name'
+ * ```
  */
@@ -87,0 +149,0 @@ export declare function resolveASTSchemaCoordinate(

utilities/resolveSchemaCoordinate.js

@@ -17,2 +17,4 @@ 'use strict';
 
+/** @category Schema Coordinates */
+
 /**
@@ -26,2 +28,34 @@ * A schema coordinate is resolved in the context of a GraphQL schema to
  * https://spec.graphql.org/draft/#sec-Schema-Coordinates.Semantics
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { buildSchema, resolveSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @tag(name: String!) on FIELD_DEFINITION
+ *
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     reviews(input: ReviewInput): [String] @tag(name: "reviews")
+ *   }
+ * `);
+ *
+ * resolveSchemaCoordinate(schema, 'Query').kind; // => 'NamedType'
+ * resolveSchemaCoordinate(schema, 'Query.reviews').kind; // => 'Field'
+ * resolveSchemaCoordinate(schema, 'Query.reviews(input:)').kind; // => 'FieldArgument'
+ * resolveSchemaCoordinate(schema, 'ReviewInput.stars').kind; // => 'InputField'
+ * resolveSchemaCoordinate(schema, 'Episode.NEW_HOPE').kind; // => 'EnumValue'
+ * resolveSchemaCoordinate(schema, '@tag').kind; // => 'Directive'
+ * resolveSchemaCoordinate(schema, '@tag(name:)').kind; // => 'DirectiveArgument'
+ * resolveSchemaCoordinate(schema, 'Query.missing'); // => undefined
+ * ```
  */
@@ -36,2 +70,4 @@ function resolveSchemaCoordinate(schema, schemaCoordinate) {
  * TypeCoordinate : Name
+ *
+ * @internal
  */
@@ -55,2 +91,4 @@
  * MemberCoordinate : Name . Name
+ *
+ * @internal
  */
@@ -133,2 +171,4 @@
  * ArgumentCoordinate : Name . Name ( Name : )
+ *
+ * @internal
  */
@@ -193,2 +233,4 @@
  * DirectiveCoordinate : \@ Name
+ *
+ * @internal
  */
@@ -212,2 +254,4 @@
  * DirectiveArgumentCoordinate : \@ Name ( Name : )
+ *
+ * @internal
  */
@@ -248,2 +292,22 @@
  * Resolves schema coordinate from a parsed SchemaCoordinate node.
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the parsed coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ * import { buildSchema, resolveASTSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String): String
+ *   }
+ * `);
+ * const coordinate = parseSchemaCoordinate('Query.greeting(name:)');
+ * const resolved = resolveASTSchemaCoordinate(schema, coordinate);
+ *
+ * resolved.kind; // => 'FieldArgument'
+ * resolved.field.name; // => 'greeting'
+ * resolved.fieldArgument.name; // => 'name'
+ * ```
  */
@@ -250,0 +314,0 @@

utilities/resolveSchemaCoordinate.mjs

@@ -0,1 +1,2 @@
+/** @category Schema Coordinates */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -19,2 +20,34 @@ import { Kind } from '../language/kinds.mjs';
  * https://spec.graphql.org/draft/#sec-Schema-Coordinates.Semantics
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { buildSchema, resolveSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @tag(name: String!) on FIELD_DEFINITION
+ *
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     reviews(input: ReviewInput): [String] @tag(name: "reviews")
+ *   }
+ * `);
+ *
+ * resolveSchemaCoordinate(schema, 'Query').kind; // => 'NamedType'
+ * resolveSchemaCoordinate(schema, 'Query.reviews').kind; // => 'Field'
+ * resolveSchemaCoordinate(schema, 'Query.reviews(input:)').kind; // => 'FieldArgument'
+ * resolveSchemaCoordinate(schema, 'ReviewInput.stars').kind; // => 'InputField'
+ * resolveSchemaCoordinate(schema, 'Episode.NEW_HOPE').kind; // => 'EnumValue'
+ * resolveSchemaCoordinate(schema, '@tag').kind; // => 'Directive'
+ * resolveSchemaCoordinate(schema, '@tag(name:)').kind; // => 'DirectiveArgument'
+ * resolveSchemaCoordinate(schema, 'Query.missing'); // => undefined
+ * ```
  */
@@ -29,2 +62,4 @@ export function resolveSchemaCoordinate(schema, schemaCoordinate) {
  * TypeCoordinate : Name
+ *
+ * @internal
  */
@@ -48,2 +83,4 @@
  * MemberCoordinate : Name . Name
+ *
+ * @internal
  */
@@ -124,2 +161,4 @@
  * ArgumentCoordinate : Name . Name ( Name : )
+ *
+ * @internal
  */
@@ -175,2 +214,4 @@
  * DirectiveCoordinate : \@ Name
+ *
+ * @internal
  */
@@ -194,2 +235,4 @@
  * DirectiveArgumentCoordinate : \@ Name ( Name : )
+ *
+ * @internal
  */
@@ -230,2 +273,22 @@
  * Resolves schema coordinate from a parsed SchemaCoordinate node.
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the parsed coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ * import { buildSchema, resolveASTSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String): String
+ *   }
+ * `);
+ * const coordinate = parseSchemaCoordinate('Query.greeting(name:)');
+ * const resolved = resolveASTSchemaCoordinate(schema, coordinate);
+ *
+ * resolved.kind; // => 'FieldArgument'
+ * resolved.field.name; // => 'greeting'
+ * resolved.fieldArgument.name; // => 'name'
+ * ```
  */
@@ -232,0 +295,0 @@

utilities/separateOperations.d.ts

@@ -0,1 +1,2 @@
+/** @category AST Utilities */
 import type { ObjMap } from '../jsutils/ObjMap';
@@ -8,2 +9,31 @@ import type { DocumentNode } from '../language/ast';
  * refers to.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @returns A map of operation names to documents containing each operation and its referenced fragments.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql/language';
+ * import { separateOperations } from 'graphql/utilities';
+ *
+ * const document = parse(`
+ *   query GetUser {
+ *     viewer {
+ *       ...UserFields
+ *     }
+ *   }
+ *
+ *   query GetStatus {
+ *     status
+ *   }
+ *
+ *   fragment UserFields on User {
+ *     id
+ *   }
+ * `);
+ *
+ * const separated = separateOperations(document);
+ *
+ * Object.keys(separated); // => ['GetUser', 'GetStatus']
+ * print(separated.GetUser); // matches /fragment UserFields/
+ * print(separated.GetStatus); // does not match /fragment UserFields/
+ * ```
  */
@@ -10,0 +40,0 @@ export declare function separateOperations(

utilities/separateOperations.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category AST Utilities */
+
 /**
@@ -18,2 +20,31 @@ * separateOperations accepts a single AST document which may contain many
  * refers to.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @returns A map of operation names to documents containing each operation and its referenced fragments.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql/language';
+ * import { separateOperations } from 'graphql/utilities';
+ *
+ * const document = parse(`
+ *   query GetUser {
+ *     viewer {
+ *       ...UserFields
+ *     }
+ *   }
+ *
+ *   query GetStatus {
+ *     status
+ *   }
+ *
+ *   fragment UserFields on User {
+ *     id
+ *   }
+ * `);
+ *
+ * const separated = separateOperations(document);
+ *
+ * Object.keys(separated); // => ['GetUser', 'GetStatus']
+ * print(separated.GetUser); // matches /fragment UserFields/
+ * print(separated.GetStatus); // does not match /fragment UserFields/
+ * ```
  */
@@ -20,0 +51,0 @@ function separateOperations(documentAST) {

utilities/separateOperations.mjs

@@ -0,1 +1,2 @@
+/** @category AST Utilities */
 import { Kind } from '../language/kinds.mjs';
@@ -8,2 +9,31 @@ import { visit } from '../language/visitor.mjs';
  * refers to.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @returns A map of operation names to documents containing each operation and its referenced fragments.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql/language';
+ * import { separateOperations } from 'graphql/utilities';
+ *
+ * const document = parse(`
+ *   query GetUser {
+ *     viewer {
+ *       ...UserFields
+ *     }
+ *   }
+ *
+ *   query GetStatus {
+ *     status
+ *   }
+ *
+ *   fragment UserFields on User {
+ *     id
+ *   }
+ * `);
+ *
+ * const separated = separateOperations(document);
+ *
+ * Object.keys(separated); // => ['GetUser', 'GetStatus']
+ * print(separated.GetUser); // matches /fragment UserFields/
+ * print(separated.GetStatus); // does not match /fragment UserFields/
+ * ```
  */
@@ -10,0 +40,0 @@

utilities/stripIgnoredCharacters.d.ts

@@ -0,1 +1,2 @@
+/** @category AST Utilities */
 import { Source } from '../language/source';
@@ -21,5 +22,5 @@ /**
  * releases due to bugfixes or changes in the GraphQL specification.
- *
- * Query example:
- *
+ * @param source - The GraphQL source text or source object.
+ * @returns A semantically equivalent GraphQL source string without ignored characters.
+ * @example Query source
  * ```graphql
@@ -42,5 +43,3 @@ * query SomeQuery($foo: String!, $bar: String) {
  * ```
- *
- * SDL example:
- *
+ * @example SDL source
  * ```graphql
@@ -63,3 +62,11 @@ * """
  * ```
+ * @example
+ * ```ts
+ * import { stripIgnoredCharacters } from 'graphql/utilities';
+ *
+ * const source = stripIgnoredCharacters('query Example { name }');
+ *
+ * source; // => 'query Example{name}'
+ * ```
  */
 export declare function stripIgnoredCharacters(source: string | Source): string;

utilities/stripIgnoredCharacters.js

@@ -16,2 +16,4 @@ 'use strict';
 
+/** @category AST Utilities */
+
 /**
@@ -36,5 +38,5 @@ * Strips characters that are not significant to the validity or execution
  * releases due to bugfixes or changes in the GraphQL specification.
- *
- * Query example:
- *
+ * @param source - The GraphQL source text or source object.
+ * @returns A semantically equivalent GraphQL source string without ignored characters.
+ * @example Query source
  * ```graphql
@@ -57,5 +59,3 @@ * query SomeQuery($foo: String!, $bar: String) {
  * ```
- *
- * SDL example:
- *
+ * @example SDL source
  * ```graphql
@@ -78,2 +78,10 @@ * """
  * ```
+ * @example
+ * ```ts
+ * import { stripIgnoredCharacters } from 'graphql/utilities';
+ *
+ * const source = stripIgnoredCharacters('query Example { name }');
+ *
+ * source; // => 'query Example{name}'
+ * ```
  */
@@ -96,2 +104,4 @@ function stripIgnoredCharacters(source) {
      * in invalid token (e.g. `1...` is invalid Float token).
+     *
+     * @internal
      */
@@ -98,0 +108,0 @@

utilities/stripIgnoredCharacters.mjs

@@ -0,1 +1,2 @@
+/** @category AST Utilities */
 import { printBlockString } from '../language/blockString.mjs';
@@ -24,5 +25,5 @@ import { isPunctuatorTokenKind, Lexer } from '../language/lexer.mjs';
  * releases due to bugfixes or changes in the GraphQL specification.
- *
- * Query example:
- *
+ * @param source - The GraphQL source text or source object.
+ * @returns A semantically equivalent GraphQL source string without ignored characters.
+ * @example Query source
  * ```graphql
@@ -45,5 +46,3 @@ * query SomeQuery($foo: String!, $bar: String) {
  * ```
- *
- * SDL example:
- *
+ * @example SDL source
  * ```graphql
@@ -66,2 +65,10 @@ * """
  * ```
+ * @example
+ * ```ts
+ * import { stripIgnoredCharacters } from 'graphql/utilities';
+ *
+ * const source = stripIgnoredCharacters('query Example { name }');
+ *
+ * source; // => 'query Example{name}'
+ * ```
  */
@@ -83,2 +90,4 @@
      * in invalid token (e.g. `1...` is invalid Float token).
+     *
+     * @internal
      */
@@ -85,0 +94,0 @@

utilities/typeComparators.d.ts

@@ -0,1 +1,2 @@
+/** @category Type Comparisons */
 import type { GraphQLCompositeType, GraphQLType } from '../type/definition';
@@ -5,2 +6,18 @@ import type { GraphQLSchema } from '../type/schema';
  * Provided two types, return true if the types are equal (invariant).
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when both types are equal.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { isEqualType } from 'graphql/utilities';
+ *
+ * isEqualType(GraphQLString, GraphQLString); // => true
+ * isEqualType(new GraphQLList(GraphQLString), new GraphQLList(GraphQLString)); // => true
+ * isEqualType(new GraphQLNonNull(GraphQLString), GraphQLString); // => false
+ * ```
  */
@@ -14,2 +31,36 @@ export declare function isEqualType(
  * equal or a subset of the second super type (covariant).
+ * @param schema - GraphQL schema to use.
+ * @param maybeSubType - The possible subtype to compare.
+ * @param superType - The possible supertype to compare.
+ * @returns True when `maybeSubType` is equal to or a subtype of `superType`.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import {
+ *   GraphQLNonNull,
+ *   assertInterfaceType,
+ *   assertObjectType,
+ * } from 'graphql/type';
+ * import { isTypeSubTypeOf } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   interface Node {
+ *     id: ID!
+ *   }
+ *
+ *   type User implements Node {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     node: Node
+ *   }
+ * `);
+ * const Node = assertInterfaceType(schema.getType('Node'));
+ * const User = assertObjectType(schema.getType('User'));
+ *
+ * isTypeSubTypeOf(schema, User, Node); // => true
+ * isTypeSubTypeOf(schema, new GraphQLNonNull(User), Node); // => true
+ * isTypeSubTypeOf(schema, Node, User); // => false
+ * ```
  */
@@ -29,2 +80,35 @@ export declare function isTypeSubTypeOf(
  * This function is commutative.
+ * @param schema - GraphQL schema to use.
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when the two composite types can apply to at least one common object type.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertObjectType, assertUnionType } from 'graphql/type';
+ * import { doTypesOverlap } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Photo {
+ *     url: String!
+ *   }
+ *
+ *   type Video {
+ *     url: String!
+ *   }
+ *
+ *   union Media = Photo | Video
+ *   union StillImage = Photo
+ *
+ *   type Query {
+ *     media: [Media]
+ *   }
+ * `);
+ * const Media = assertUnionType(schema.getType('Media'));
+ * const StillImage = assertUnionType(schema.getType('StillImage'));
+ * const Video = assertObjectType(schema.getType('Video'));
+ *
+ * doTypesOverlap(schema, Media, StillImage); // => true
+ * doTypesOverlap(schema, StillImage, Video); // => false
+ * ```
  */
@@ -31,0 +115,0 @@ export declare function doTypesOverlap(

utilities/typeComparators.js

@@ -12,4 +12,22 @@ 'use strict';
 
+/** @category Type Comparisons */
+
 /**
  * Provided two types, return true if the types are equal (invariant).
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when both types are equal.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { isEqualType } from 'graphql/utilities';
+ *
+ * isEqualType(GraphQLString, GraphQLString); // => true
+ * isEqualType(new GraphQLList(GraphQLString), new GraphQLList(GraphQLString)); // => true
+ * isEqualType(new GraphQLNonNull(GraphQLString), GraphQLString); // => false
+ * ```
  */
@@ -41,2 +59,36 @@ function isEqualType(typeA, typeB) {
  * equal or a subset of the second super type (covariant).
+ * @param schema - GraphQL schema to use.
+ * @param maybeSubType - The possible subtype to compare.
+ * @param superType - The possible supertype to compare.
+ * @returns True when `maybeSubType` is equal to or a subtype of `superType`.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import {
+ *   GraphQLNonNull,
+ *   assertInterfaceType,
+ *   assertObjectType,
+ * } from 'graphql/type';
+ * import { isTypeSubTypeOf } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   interface Node {
+ *     id: ID!
+ *   }
+ *
+ *   type User implements Node {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     node: Node
+ *   }
+ * `);
+ * const Node = assertInterfaceType(schema.getType('Node'));
+ * const User = assertObjectType(schema.getType('User'));
+ *
+ * isTypeSubTypeOf(schema, User, Node); // => true
+ * isTypeSubTypeOf(schema, new GraphQLNonNull(User), Node); // => true
+ * isTypeSubTypeOf(schema, Node, User); // => false
+ * ```
  */
@@ -92,2 +144,35 @@
  * This function is commutative.
+ * @param schema - GraphQL schema to use.
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when the two composite types can apply to at least one common object type.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertObjectType, assertUnionType } from 'graphql/type';
+ * import { doTypesOverlap } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Photo {
+ *     url: String!
+ *   }
+ *
+ *   type Video {
+ *     url: String!
+ *   }
+ *
+ *   union Media = Photo | Video
+ *   union StillImage = Photo
+ *
+ *   type Query {
+ *     media: [Media]
+ *   }
+ * `);
+ * const Media = assertUnionType(schema.getType('Media'));
+ * const StillImage = assertUnionType(schema.getType('StillImage'));
+ * const Video = assertObjectType(schema.getType('Video'));
+ *
+ * doTypesOverlap(schema, Media, StillImage); // => true
+ * doTypesOverlap(schema, StillImage, Video); // => false
+ * ```
  */
@@ -94,0 +179,0 @@

utilities/typeComparators.mjs

@@ -0,1 +1,2 @@
+/** @category Type Comparisons */
 import {
@@ -11,2 +12,18 @@ isAbstractType,
  * Provided two types, return true if the types are equal (invariant).
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when both types are equal.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { isEqualType } from 'graphql/utilities';
+ *
+ * isEqualType(GraphQLString, GraphQLString); // => true
+ * isEqualType(new GraphQLList(GraphQLString), new GraphQLList(GraphQLString)); // => true
+ * isEqualType(new GraphQLNonNull(GraphQLString), GraphQLString); // => false
+ * ```
  */
@@ -32,2 +49,36 @@ export function isEqualType(typeA, typeB) {
  * equal or a subset of the second super type (covariant).
+ * @param schema - GraphQL schema to use.
+ * @param maybeSubType - The possible subtype to compare.
+ * @param superType - The possible supertype to compare.
+ * @returns True when `maybeSubType` is equal to or a subtype of `superType`.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import {
+ *   GraphQLNonNull,
+ *   assertInterfaceType,
+ *   assertObjectType,
+ * } from 'graphql/type';
+ * import { isTypeSubTypeOf } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   interface Node {
+ *     id: ID!
+ *   }
+ *
+ *   type User implements Node {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     node: Node
+ *   }
+ * `);
+ * const Node = assertInterfaceType(schema.getType('Node'));
+ * const User = assertObjectType(schema.getType('User'));
+ *
+ * isTypeSubTypeOf(schema, User, Node); // => true
+ * isTypeSubTypeOf(schema, new GraphQLNonNull(User), Node); // => true
+ * isTypeSubTypeOf(schema, Node, User); // => false
+ * ```
  */
@@ -82,2 +133,35 @@
  * This function is commutative.
+ * @param schema - GraphQL schema to use.
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when the two composite types can apply to at least one common object type.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertObjectType, assertUnionType } from 'graphql/type';
+ * import { doTypesOverlap } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Photo {
+ *     url: String!
+ *   }
+ *
+ *   type Video {
+ *     url: String!
+ *   }
+ *
+ *   union Media = Photo | Video
+ *   union StillImage = Photo
+ *
+ *   type Query {
+ *     media: [Media]
+ *   }
+ * `);
+ * const Media = assertUnionType(schema.getType('Media'));
+ * const StillImage = assertUnionType(schema.getType('StillImage'));
+ * const Video = assertObjectType(schema.getType('Video'));
+ *
+ * doTypesOverlap(schema, Media, StillImage); // => true
+ * doTypesOverlap(schema, StillImage, Video); // => false
+ * ```
  */
@@ -84,0 +168,0 @@

utilities/typedQueryDocumentNode.d.ts

@@ -0,4 +1,7 @@
+/** @category Typed Documents */
 import type { DocumentNode, ExecutableDefinitionNode } from '../language/ast';
 /**
  * Wrapper type that contains DocumentNode and types that can be deduced from it.
+ * @typeParam TResponseData - Typed GraphQL response data shape.
+ * @typeParam TRequestVariables - Typed GraphQL request variables shape.
  */
@@ -13,2 +16,3 @@ export interface TypedQueryDocumentNode<
 > extends DocumentNode {
+  /** Top-level executable and type-system definitions in this document. */
   readonly definitions: ReadonlyArray<ExecutableDefinitionNode>;
@@ -15,0 +19,0 @@ /**

utilities/typeFromAST.d.ts

@@ -0,1 +1,2 @@
+/** @category Values */
 import type {
@@ -16,2 +17,19 @@ ListTypeNode,
  * found in the schema, then undefined will be returned.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The GraphQL type AST node to resolve.
+ * @returns The GraphQL type referenced by the AST node, or undefined if it cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('String'))?.toString(); // => 'String'
+ * typeFromAST(schema, parseType('Missing')); // => undefined
+ * ```
  */
@@ -22,2 +40,23 @@ export declare function typeFromAST(
 ): GraphQLNamedType | undefined;
+/**
+ * Resolves a list type AST node against a schema.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The list type AST node to resolve.
+ * @returns The GraphQL list type referenced by the AST node, or undefined if
+ * it cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     tags: [String]
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('[String]'))?.toString(); // => '[String]'
+ * typeFromAST(schema, parseType('[Missing]')); // => undefined
+ * ```
+ */
 export declare function typeFromAST(
@@ -27,2 +66,23 @@ schema: GraphQLSchema,
 ): GraphQLList<any> | undefined;
+/**
+ * Resolves a non-null type AST node against a schema.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The non-null type AST node to resolve.
+ * @returns The GraphQL non-null type referenced by the AST node, or undefined
+ * if it cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String!
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('String!'))?.toString(); // => 'String!'
+ * typeFromAST(schema, parseType('[String!]!'))?.toString(); // => '[String!]!'
+ * ```
+ */
 export declare function typeFromAST(
@@ -32,2 +92,28 @@ schema: GraphQLSchema,
 ): GraphQLNonNull<any> | undefined;
+/**
+ * Resolves a type AST node against a schema.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The GraphQL type AST node to resolve.
+ * @returns The GraphQL type referenced by the AST node, or undefined if it
+ * cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type User {
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     users: [User!]!
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('User'))?.toString(); // => 'User'
+ * typeFromAST(schema, parseType('[User!]!'))?.toString(); // => '[User!]!'
+ * typeFromAST(schema, parseType('Missing')); // => undefined
+ * ```
+ */
 export declare function typeFromAST(
@@ -34,0 +120,0 @@ schema: GraphQLSchema,

utilities/typeFromAST.js

@@ -12,2 +12,5 @@ 'use strict';
 
+/** @category Values */
+
+/** @internal */
 function typeFromAST(schema, typeNode) {
@@ -14,0 +17,0 @@ switch (typeNode.kind) {

utilities/typeFromAST.mjs

@@ -0,3 +1,6 @@
+/** @category Values */
 import { Kind } from '../language/kinds.mjs';
 import { GraphQLList, GraphQLNonNull } from '../type/definition.mjs';
+
+/** @internal */
 export function typeFromAST(schema, typeNode) {
@@ -4,0 +7,0 @@ switch (typeNode.kind) {

utilities/TypeInfo.d.ts

@@ -0,1 +1,2 @@
+/** @category Type Info */
 import type { Maybe } from '../jsutils/Maybe';
@@ -31,2 +32,70 @@ import type { ASTNode, FieldNode } from '../language/ast';
   private _getFieldDef;
+  /**
+   * Creates a TypeInfo instance.
+   * @param schema - Schema used for type lookups.
+   * @param initialType - Optional type to use at the start of traversal.
+   * @param getFieldDefFn - Optional field definition lookup override.
+   * @example
+   * ```ts
+   * // Track field types during a visitWithTypeInfo traversal.
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema } from 'graphql/utilities';
+   * import { TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const seenTypes = [];
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       seenTypes.push(String(typeInfo.getType()));
+   *     },
+   *   }),
+   * );
+   *
+   * seenTypes; // => ['String']
+   * ```
+   * @example
+   * ```ts
+   * // This variant starts from an initial type and supplies a field definition resolver.
+   * import { Kind } from 'graphql/language';
+   * import { GraphQLString } from 'graphql/type';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema, schema.getQueryType(), () => ({
+   *   name: 'virtualGreeting',
+   *   description: undefined,
+   *   type: GraphQLString,
+   *   args: [],
+   *   resolve: undefined,
+   *   subscribe: undefined,
+   *   deprecationReason: undefined,
+   *   extensions: Object.create(null),
+   *   astNode: undefined,
+   * }));
+   *
+   * typeInfo.enter({
+   *   kind: Kind.SELECTION_SET,
+   *   selections: [],
+   * });
+   * typeInfo.enter({
+   *   kind: Kind.FIELD,
+   *   name: { kind: Kind.NAME, value: 'ignored' },
+   * });
+   *
+   * typeInfo.getFieldDef()?.name; // => 'virtualGreeting'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
   constructor(
@@ -39,16 +108,356 @@ schema: GraphQLSchema,
     initialType?: Maybe<GraphQLType>,
-    /** @deprecated will be removed in 17.0.0 */
+    /**
+     * Deprecated field definition lookup override. Use TypeInfo's built-in
+     * field definition lookup instead because this hook will be removed in v17.
+     * @deprecated will be removed in 17.0.0
+     */
     getFieldDefFn?: GetFieldDefFn,
   );
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * Returns the current output type at this point in traversal.
+   * @returns The current output type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const fieldTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       fieldTypes[node.name.value] = String(typeInfo.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * fieldTypes; // => { viewer: 'User', name: 'String' }
+   * ```
+   */
   getType(): Maybe<GraphQLOutputType>;
+  /**
+   * Returns the current parent composite type.
+   * @returns The current parent composite type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       parentTypes[node.name.value] = String(typeInfo.getParentType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypes; // => { viewer: 'Query', name: 'User' }
+   * ```
+   */
   getParentType(): Maybe<GraphQLCompositeType>;
+  /**
+   * Returns the current input type at this point in traversal.
+   * @returns The current input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(stars: Int!, sort: Sort = NEWEST): [String]
+   *   }
+   *
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const inputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(stars: 5, sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: (node) => {
+   *       inputTypes[node.name.value] = String(typeInfo.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypes; // => { stars: 'Int!', sort: 'Sort' }
+   * ```
+   */
   getInputType(): Maybe<GraphQLInputType>;
+  /**
+   * Returns the parent input type for the current input position.
+   * @returns The parent input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int!
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentInputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(filter: { stars: 5 }) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: (node) => {
+   *       parentInputTypes[node.name.value] = String(typeInfo.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypes; // => { stars: 'ReviewFilter' }
+   * ```
+   */
   getParentInputType(): Maybe<GraphQLInputType>;
+  /**
+   * Returns the current field definition.
+   * @returns The current field definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let fieldName;
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = typeInfo.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
   getFieldDef(): Maybe<GraphQLField<unknown, unknown>>;
+  /**
+   * Returns the default value for the current input position.
+   * @returns The current default value, if one is available.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let defaultLimit;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       defaultLimit = typeInfo.getDefaultValue();
+   *     },
+   *   }),
+   * );
+   *
+   * defaultLimit; // => 10
+   * ```
+   */
   getDefaultValue(): Maybe<unknown>;
+  /**
+   * Returns the current directive definition.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let directiveName;
+   *
+   * visit(
+   *   parse('{ greeting @include(if: true) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = typeInfo.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
   getDirective(): Maybe<GraphQLDirective>;
+  /**
+   * Returns the current argument definition.
+   * @returns The current argument definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let argumentName;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = typeInfo.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
   getArgument(): Maybe<GraphQLArgument>;
+  /**
+   * Returns the current enum value definition.
+   * @returns The current enum value definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort = NEWEST): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let enumValueName;
+   *
+   * visit(
+   *   parse('{ reviews(sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = typeInfo.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
   getEnumValue(): Maybe<GraphQLEnumValue>;
+  /**
+   * Updates this TypeInfo instance for an entered AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { Kind, parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   *
+   * field.kind; // => Kind.FIELD
+   * typeInfo.getParentType()?.name; // => 'Query'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
   enter(node: ASTNode): void;
+  /**
+   * Updates this TypeInfo instance for a left AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   * String(typeInfo.getType()); // => 'String'
+   *
+   * typeInfo.leave(field);
+   * typeInfo.getType(); // => undefined
+   * ```
+   */
   leave(node: ASTNode): void;
@@ -64,2 +473,33 @@ }
  * along with visiting visitor.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @param visitor - Visitor callbacks to wrap with TypeInfo updates.
+ * @returns A visitor that keeps TypeInfo in sync while delegating callbacks.
+ * @example
+ * ```ts
+ * import { parse, visit } from 'graphql/language';
+ * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const typeInfo = new TypeInfo(schema);
+ * const fields = [];
+ *
+ * visit(
+ *   parse('{ greeting }'),
+ *   visitWithTypeInfo(typeInfo, {
+ *     Field: (node) => {
+ *       fields.push({
+ *         name: node.name.value,
+ *         parentType: String(typeInfo.getParentType()),
+ *         type: String(typeInfo.getType()),
+ *       });
+ *     },
+ *   }),
+ * );
+ *
+ * fields; // => [{ name: 'greeting', parentType: 'Query', type: 'String' }]
+ * ```
  */
@@ -66,0 +506,0 @@ export declare function visitWithTypeInfo(

utilities/TypeInfo.js

@@ -21,2 +21,4 @@ 'use strict';
 
+/** @category Type Info */
+
 /**
@@ -28,2 +30,70 @@ * TypeInfo is a utility class which, given a GraphQL schema, can keep track
 class TypeInfo {
+  /**
+   * Creates a TypeInfo instance.
+   * @param schema - Schema used for type lookups.
+   * @param initialType - Optional type to use at the start of traversal.
+   * @param getFieldDefFn - Optional field definition lookup override.
+   * @example
+   * ```ts
+   * // Track field types during a visitWithTypeInfo traversal.
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema } from 'graphql/utilities';
+   * import { TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const seenTypes = [];
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       seenTypes.push(String(typeInfo.getType()));
+   *     },
+   *   }),
+   * );
+   *
+   * seenTypes; // => ['String']
+   * ```
+   * @example
+   * ```ts
+   * // This variant starts from an initial type and supplies a field definition resolver.
+   * import { Kind } from 'graphql/language';
+   * import { GraphQLString } from 'graphql/type';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema, schema.getQueryType(), () => ({
+   *   name: 'virtualGreeting',
+   *   description: undefined,
+   *   type: GraphQLString,
+   *   args: [],
+   *   resolve: undefined,
+   *   subscribe: undefined,
+   *   deprecationReason: undefined,
+   *   extensions: Object.create(null),
+   *   astNode: undefined,
+   * }));
+   *
+   * typeInfo.enter({
+   *   kind: Kind.SELECTION_SET,
+   *   selections: [],
+   * });
+   * typeInfo.enter({
+   *   kind: Kind.FIELD,
+   *   name: { kind: Kind.NAME, value: 'ignored' },
+   * });
+   *
+   * typeInfo.getFieldDef()?.name; // => 'virtualGreeting'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
   constructor(
@@ -36,3 +106,7 @@ schema,
     initialType,
-    /** @deprecated will be removed in 17.0.0 */
+    /**
+     * Deprecated field definition lookup override. Use TypeInfo's built-in
+     * field definition lookup instead because this hook will be removed in v17.
+     * @deprecated will be removed in 17.0.0
+     */
     getFieldDefFn,
@@ -68,2 +142,6 @@ ) {
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -73,2 +151,34 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns the current output type at this point in traversal.
+   * @returns The current output type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const fieldTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       fieldTypes[node.name.value] = String(typeInfo.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * fieldTypes; // => { viewer: 'User', name: 'String' }
+   * ```
+   */
 
@@ -80,2 +190,34 @@ getType() {
   }
+  /**
+   * Returns the current parent composite type.
+   * @returns The current parent composite type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       parentTypes[node.name.value] = String(typeInfo.getParentType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypes; // => { viewer: 'Query', name: 'User' }
+   * ```
+   */
 
@@ -87,2 +229,35 @@ getParentType() {
   }
+  /**
+   * Returns the current input type at this point in traversal.
+   * @returns The current input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(stars: Int!, sort: Sort = NEWEST): [String]
+   *   }
+   *
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const inputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(stars: 5, sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: (node) => {
+   *       inputTypes[node.name.value] = String(typeInfo.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypes; // => { stars: 'Int!', sort: 'Sort' }
+   * ```
+   */
 
@@ -94,2 +269,34 @@ getInputType() {
   }
+  /**
+   * Returns the parent input type for the current input position.
+   * @returns The parent input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int!
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentInputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(filter: { stars: 5 }) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: (node) => {
+   *       parentInputTypes[node.name.value] = String(typeInfo.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypes; // => { stars: 'ReviewFilter' }
+   * ```
+   */
 
@@ -101,2 +308,30 @@ getParentInputType() {
   }
+  /**
+   * Returns the current field definition.
+   * @returns The current field definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let fieldName;
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = typeInfo.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
 
@@ -108,2 +343,30 @@ getFieldDef() {
   }
+  /**
+   * Returns the default value for the current input position.
+   * @returns The current default value, if one is available.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let defaultLimit;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       defaultLimit = typeInfo.getDefaultValue();
+   *     },
+   *   }),
+   * );
+   *
+   * defaultLimit; // => 10
+   * ```
+   */
 
@@ -115,2 +378,30 @@ getDefaultValue() {
   }
+  /**
+   * Returns the current directive definition.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let directiveName;
+   *
+   * visit(
+   *   parse('{ greeting @include(if: true) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = typeInfo.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
 
@@ -120,2 +411,30 @@ getDirective() {
   }
+  /**
+   * Returns the current argument definition.
+   * @returns The current argument definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let argumentName;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = typeInfo.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
 
@@ -125,2 +444,35 @@ getArgument() {
   }
+  /**
+   * Returns the current enum value definition.
+   * @returns The current enum value definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort = NEWEST): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let enumValueName;
+   *
+   * visit(
+   *   parse('{ reviews(sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = typeInfo.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
 
@@ -130,2 +482,31 @@ getEnumValue() {
   }
+  /**
+   * Updates this TypeInfo instance for an entered AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { Kind, parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   *
+   * field.kind; // => Kind.FIELD
+   * typeInfo.getParentType()?.name; // => 'Query'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
 
@@ -297,2 +678,31 @@ enter(node) {
   }
+  /**
+   * Updates this TypeInfo instance for a left AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   * String(typeInfo.getType()); // => 'String'
+   *
+   * typeInfo.leave(field);
+   * typeInfo.getType(); // => undefined
+   * ```
+   */
 
@@ -361,2 +771,4 @@ leave(node) {
  * and need to handle Interface and Union types.
+ *
+ * @internal
  */
@@ -397,2 +809,33 @@ function getFieldDef(schema, parentType, fieldNode) {
  * along with visiting visitor.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @param visitor - Visitor callbacks to wrap with TypeInfo updates.
+ * @returns A visitor that keeps TypeInfo in sync while delegating callbacks.
+ * @example
+ * ```ts
+ * import { parse, visit } from 'graphql/language';
+ * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const typeInfo = new TypeInfo(schema);
+ * const fields = [];
+ *
+ * visit(
+ *   parse('{ greeting }'),
+ *   visitWithTypeInfo(typeInfo, {
+ *     Field: (node) => {
+ *       fields.push({
+ *         name: node.name.value,
+ *         parentType: String(typeInfo.getParentType()),
+ *         type: String(typeInfo.getType()),
+ *       });
+ *     },
+ *   }),
+ * );
+ *
+ * fields; // => [{ name: 'greeting', parentType: 'Query', type: 'String' }]
+ * ```
  */
@@ -399,0 +842,0 @@

utilities/TypeInfo.mjs

@@ -0,1 +1,2 @@
+/** @category Type Info */
 import { isNode } from '../language/ast.mjs';
@@ -29,2 +30,70 @@ import { Kind } from '../language/kinds.mjs';
 export class TypeInfo {
+  /**
+   * Creates a TypeInfo instance.
+   * @param schema - Schema used for type lookups.
+   * @param initialType - Optional type to use at the start of traversal.
+   * @param getFieldDefFn - Optional field definition lookup override.
+   * @example
+   * ```ts
+   * // Track field types during a visitWithTypeInfo traversal.
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema } from 'graphql/utilities';
+   * import { TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const seenTypes = [];
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       seenTypes.push(String(typeInfo.getType()));
+   *     },
+   *   }),
+   * );
+   *
+   * seenTypes; // => ['String']
+   * ```
+   * @example
+   * ```ts
+   * // This variant starts from an initial type and supplies a field definition resolver.
+   * import { Kind } from 'graphql/language';
+   * import { GraphQLString } from 'graphql/type';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema, schema.getQueryType(), () => ({
+   *   name: 'virtualGreeting',
+   *   description: undefined,
+   *   type: GraphQLString,
+   *   args: [],
+   *   resolve: undefined,
+   *   subscribe: undefined,
+   *   deprecationReason: undefined,
+   *   extensions: Object.create(null),
+   *   astNode: undefined,
+   * }));
+   *
+   * typeInfo.enter({
+   *   kind: Kind.SELECTION_SET,
+   *   selections: [],
+   * });
+   * typeInfo.enter({
+   *   kind: Kind.FIELD,
+   *   name: { kind: Kind.NAME, value: 'ignored' },
+   * });
+   *
+   * typeInfo.getFieldDef()?.name; // => 'virtualGreeting'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
   constructor(
@@ -37,3 +106,7 @@ schema,
     initialType,
-    /** @deprecated will be removed in 17.0.0 */
+    /**
+     * Deprecated field definition lookup override. Use TypeInfo's built-in
+     * field definition lookup instead because this hook will be removed in v17.
+     * @deprecated will be removed in 17.0.0
+     */
     getFieldDefFn,
@@ -69,2 +142,6 @@ ) {
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -74,2 +151,34 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns the current output type at this point in traversal.
+   * @returns The current output type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const fieldTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       fieldTypes[node.name.value] = String(typeInfo.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * fieldTypes; // => { viewer: 'User', name: 'String' }
+   * ```
+   */
 
@@ -81,2 +190,34 @@ getType() {
   }
+  /**
+   * Returns the current parent composite type.
+   * @returns The current parent composite type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentTypes = {};
+   *
+   * visit(
+   *   parse('{ viewer { name } }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: (node) => {
+   *       parentTypes[node.name.value] = String(typeInfo.getParentType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypes; // => { viewer: 'Query', name: 'User' }
+   * ```
+   */
 
@@ -88,2 +229,35 @@ getParentType() {
   }
+  /**
+   * Returns the current input type at this point in traversal.
+   * @returns The current input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(stars: Int!, sort: Sort = NEWEST): [String]
+   *   }
+   *
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const inputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(stars: 5, sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: (node) => {
+   *       inputTypes[node.name.value] = String(typeInfo.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypes; // => { stars: 'Int!', sort: 'Sort' }
+   * ```
+   */
 
@@ -95,2 +269,34 @@ getInputType() {
   }
+  /**
+   * Returns the parent input type for the current input position.
+   * @returns The parent input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int!
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * const parentInputTypes = {};
+   *
+   * visit(
+   *   parse('{ reviews(filter: { stars: 5 }) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: (node) => {
+   *       parentInputTypes[node.name.value] = String(typeInfo.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypes; // => { stars: 'ReviewFilter' }
+   * ```
+   */
 
@@ -102,2 +308,30 @@ getParentInputType() {
   }
+  /**
+   * Returns the current field definition.
+   * @returns The current field definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let fieldName;
+   *
+   * visit(
+   *   parse('{ greeting }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = typeInfo.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
 
@@ -109,2 +343,30 @@ getFieldDef() {
   }
+  /**
+   * Returns the default value for the current input position.
+   * @returns The current default value, if one is available.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let defaultLimit;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       defaultLimit = typeInfo.getDefaultValue();
+   *     },
+   *   }),
+   * );
+   *
+   * defaultLimit; // => 10
+   * ```
+   */
 
@@ -116,2 +378,30 @@ getDefaultValue() {
   }
+  /**
+   * Returns the current directive definition.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let directiveName;
+   *
+   * visit(
+   *   parse('{ greeting @include(if: true) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = typeInfo.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
 
@@ -121,2 +411,30 @@ getDirective() {
   }
+  /**
+   * Returns the current argument definition.
+   * @returns The current argument definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int = 10): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let argumentName;
+   *
+   * visit(
+   *   parse('{ reviews(limit: 5) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = typeInfo.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
 
@@ -126,2 +444,35 @@ getArgument() {
   }
+  /**
+   * Returns the current enum value definition.
+   * @returns The current enum value definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort = NEWEST): [String]
+   *   }
+   * `);
+   * const typeInfo = new TypeInfo(schema);
+   * let enumValueName;
+   *
+   * visit(
+   *   parse('{ reviews(sort: OLDEST) }'),
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = typeInfo.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
 
@@ -131,2 +482,31 @@ getEnumValue() {
   }
+  /**
+   * Updates this TypeInfo instance for an entered AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { Kind, parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   *
+   * field.kind; // => Kind.FIELD
+   * typeInfo.getParentType()?.name; // => 'Query'
+   * String(typeInfo.getType()); // => 'String'
+   * ```
+   */
 
@@ -284,2 +664,31 @@ enter(node) {
   }
+  /**
+   * Updates this TypeInfo instance for a left AST node.
+   * @param node - AST node being entered.
+   * @returns Nothing.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const operation = document.definitions[0];
+   * const selectionSet = operation.selectionSet;
+   * const field = selectionSet.selections[0];
+   * const typeInfo = new TypeInfo(schema);
+   *
+   * typeInfo.enter(operation);
+   * typeInfo.enter(selectionSet);
+   * typeInfo.enter(field);
+   * String(typeInfo.getType()); // => 'String'
+   *
+   * typeInfo.leave(field);
+   * typeInfo.getType(); // => undefined
+   * ```
+   */
 
@@ -346,2 +755,4 @@ leave(node) {
  * and need to handle Interface and Union types.
+ *
+ * @internal
  */
@@ -373,2 +784,33 @@ function getFieldDef(schema, parentType, fieldNode) {
  * along with visiting visitor.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @param visitor - Visitor callbacks to wrap with TypeInfo updates.
+ * @returns A visitor that keeps TypeInfo in sync while delegating callbacks.
+ * @example
+ * ```ts
+ * import { parse, visit } from 'graphql/language';
+ * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const typeInfo = new TypeInfo(schema);
+ * const fields = [];
+ *
+ * visit(
+ *   parse('{ greeting }'),
+ *   visitWithTypeInfo(typeInfo, {
+ *     Field: (node) => {
+ *       fields.push({
+ *         name: node.name.value,
+ *         parentType: String(typeInfo.getParentType()),
+ *         type: String(typeInfo.getType()),
+ *       });
+ *     },
+ *   }),
+ * );
+ *
+ * fields; // => [{ name: 'greeting', parentType: 'Query', type: 'String' }]
+ * ```
  */
@@ -375,0 +817,0 @@

utilities/valueFromAST.d.ts

@@ -0,1 +1,2 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
@@ -23,3 +24,40 @@ import type { ObjMap } from '../jsutils/ObjMap';
  * | NullValue            | null          |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param type - The GraphQL type to inspect.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns The coerced JavaScript value, or undefined if the AST value cannot be coerced to the type.
+ * @example
+ * ```ts
+ * // Coerce literal values without variables.
+ * import { parseValue } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
  *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * valueFromAST(parseValue('{ stars: 5, tags: ["featured"] }'), ReviewInput); // => { stars: 5, tags: ['featured'] }
+ * valueFromAST(parseValue('{ stars: "bad" }'), ReviewInput); // => undefined
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves variable references from runtime values.
+ * import { parseValue } from 'graphql/language';
+ * import { GraphQLInt } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
+ *
+ * valueFromAST(parseValue('$stars'), GraphQLInt, { stars: 5 }); // => 5
+ * valueFromAST(parseValue('$stars'), GraphQLInt, {}); // => undefined
+ * ```
  */
@@ -26,0 +64,0 @@ export declare function valueFromAST(

utilities/valueFromAST.js

@@ -18,2 +18,4 @@ 'use strict';
 
+/** @category Values */
+
 /**
@@ -37,3 +39,40 @@ * Produces a JavaScript value given a GraphQL Value AST.
  * | NullValue            | null          |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param type - The GraphQL type to inspect.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns The coerced JavaScript value, or undefined if the AST value cannot be coerced to the type.
+ * @example
+ * ```ts
+ * // Coerce literal values without variables.
+ * import { parseValue } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
  *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * valueFromAST(parseValue('{ stars: 5, tags: ["featured"] }'), ReviewInput); // => { stars: 5, tags: ['featured'] }
+ * valueFromAST(parseValue('{ stars: "bad" }'), ReviewInput); // => undefined
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves variable references from runtime values.
+ * import { parseValue } from 'graphql/language';
+ * import { GraphQLInt } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
+ *
+ * valueFromAST(parseValue('$stars'), GraphQLInt, { stars: 5 }); // => 5
+ * valueFromAST(parseValue('$stars'), GraphQLInt, {}); // => undefined
+ * ```
  */
@@ -40,0 +79,0 @@ function valueFromAST(valueNode, type, variables) {

utilities/valueFromAST.mjs

@@ -0,1 +1,2 @@
+/** @category Values */
 import { inspect } from '../jsutils/inspect.mjs';
@@ -29,3 +30,40 @@ import { invariant } from '../jsutils/invariant.mjs';
  * | NullValue            | null          |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param type - The GraphQL type to inspect.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns The coerced JavaScript value, or undefined if the AST value cannot be coerced to the type.
+ * @example
+ * ```ts
+ * // Coerce literal values without variables.
+ * import { parseValue } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
  *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * valueFromAST(parseValue('{ stars: 5, tags: ["featured"] }'), ReviewInput); // => { stars: 5, tags: ['featured'] }
+ * valueFromAST(parseValue('{ stars: "bad" }'), ReviewInput); // => undefined
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves variable references from runtime values.
+ * import { parseValue } from 'graphql/language';
+ * import { GraphQLInt } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
+ *
+ * valueFromAST(parseValue('$stars'), GraphQLInt, { stars: 5 }); // => 5
+ * valueFromAST(parseValue('$stars'), GraphQLInt, {}); // => undefined
+ * ```
  */
@@ -32,0 +70,0 @@

utilities/valueFromASTUntyped.d.ts

@@ -0,1 +1,2 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
@@ -7,4 +8,4 @@ import type { ObjMap } from '../jsutils/ObjMap';
  *
- * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value
- * will reflect the provided GraphQL value AST.
+ * Because no GraphQL type is provided, the returned JavaScript value reflects
+ * the provided GraphQL value AST.
  *
@@ -19,3 +20,15 @@ * | GraphQL Value        | JavaScript Value |
  * | Null                 | null             |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns JavaScript value represented by the GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ * import { valueFromASTUntyped } from 'graphql/utilities';
  *
+ * const value = valueFromASTUntyped(parseValue('[1, 2, 3]'));
+ *
+ * value; // => [1, 2, 3]
+ * valueFromASTUntyped(parseValue('$name'), { name: 'Ada' }); // => 'Ada'
+ * ```
  */
@@ -22,0 +35,0 @@ export declare function valueFromASTUntyped(

utilities/valueFromASTUntyped.js

@@ -12,7 +12,9 @@ 'use strict';
 
+/** @category Values */
+
 /**
  * Produces a JavaScript value given a GraphQL Value AST.
  *
- * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value
- * will reflect the provided GraphQL value AST.
+ * Because no GraphQL type is provided, the returned JavaScript value reflects
+ * the provided GraphQL value AST.
  *
@@ -27,3 +29,15 @@ * | GraphQL Value        | JavaScript Value |
  * | Null                 | null             |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns JavaScript value represented by the GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ * import { valueFromASTUntyped } from 'graphql/utilities';
  *
+ * const value = valueFromASTUntyped(parseValue('[1, 2, 3]'));
+ *
+ * value; // => [1, 2, 3]
+ * valueFromASTUntyped(parseValue('$name'), { name: 'Ada' }); // => 'Ada'
+ * ```
  */
@@ -30,0 +44,0 @@ function valueFromASTUntyped(valueNode, variables) {

utilities/valueFromASTUntyped.mjs

@@ -0,1 +1,2 @@
+/** @category Values */
 import { keyValMap } from '../jsutils/keyValMap.mjs';
@@ -6,4 +7,4 @@ import { Kind } from '../language/kinds.mjs';
  *
- * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value
- * will reflect the provided GraphQL value AST.
+ * Because no GraphQL type is provided, the returned JavaScript value reflects
+ * the provided GraphQL value AST.
  *
@@ -18,3 +19,15 @@ * | GraphQL Value        | JavaScript Value |
  * | Null                 | null             |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns JavaScript value represented by the GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ * import { valueFromASTUntyped } from 'graphql/utilities';
  *
+ * const value = valueFromASTUntyped(parseValue('[1, 2, 3]'));
+ *
+ * value; // => [1, 2, 3]
+ * valueFromASTUntyped(parseValue('$name'), { name: 'Ada' }); // => 'Ada'
+ * ```
  */
@@ -21,0 +34,0 @@

validation/index.d.ts

@@ -0,1 +1,7 @@
+/**
+ * Validate GraphQL documents and schemas with the specified validation rules.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { validate } from './validate';
@@ -2,0 +8,0 @@ export { ValidationContext } from './ValidationContext';

validation/index.mjs

@@ -0,1 +1,7 @@
+/**
+ * Validate GraphQL documents and schemas with the specified validation rules.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export { validate } from './validate.mjs';
@@ -2,0 +8,0 @@ export { ValidationContext } from './ValidationContext.mjs';

validation/rules/custom/NoDeprecatedCustomRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Custom Rules */
 import type { ASTVisitor } from '../../../language/visitor';
@@ -12,2 +13,42 @@ import type { ValidationContext } from '../../ValidationContext';
  * necessarily to forbid their use when querying a service.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLObjectType,
+ *   GraphQLSchema,
+ *   GraphQLString,
+ *   parse,
+ *   validate,
+ * } from 'graphql';
+ * import { NoDeprecatedCustomRule } from 'graphql/validation';
+ *
+ * const schema = new GraphQLSchema({
+ *   query: new GraphQLObjectType({
+ *     name: 'Query',
+ *     fields: {
+ *       name: { type: GraphQLString },
+ *       oldName: {
+ *         type: GraphQLString,
+ *         deprecationReason: 'Use name instead.',
+ *       },
+ *     },
+ *   }),
+ * });
+ *
+ * const invalidDocument = parse(`
+ *   { oldName }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoDeprecatedCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoDeprecatedCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -14,0 +55,0 @@ export declare function NoDeprecatedCustomRule(

validation/rules/custom/NoDeprecatedCustomRule.js

@@ -14,2 +14,4 @@ 'use strict';
 
+/** @category Custom Rules */
+
 /**
@@ -24,2 +26,42 @@ * No deprecated
  * necessarily to forbid their use when querying a service.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLObjectType,
+ *   GraphQLSchema,
+ *   GraphQLString,
+ *   parse,
+ *   validate,
+ * } from 'graphql';
+ * import { NoDeprecatedCustomRule } from 'graphql/validation';
+ *
+ * const schema = new GraphQLSchema({
+ *   query: new GraphQLObjectType({
+ *     name: 'Query',
+ *     fields: {
+ *       name: { type: GraphQLString },
+ *       oldName: {
+ *         type: GraphQLString,
+ *         deprecationReason: 'Use name instead.',
+ *       },
+ *     },
+ *   }),
+ * });
+ *
+ * const invalidDocument = parse(`
+ *   { oldName }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoDeprecatedCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoDeprecatedCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -26,0 +68,0 @@ function NoDeprecatedCustomRule(context) {

validation/rules/custom/NoDeprecatedCustomRule.mjs

@@ -0,1 +1,2 @@
+/** @category Custom Rules */
 import { invariant } from '../../../jsutils/invariant.mjs';
@@ -14,2 +15,42 @@ import { GraphQLError } from '../../../error/GraphQLError.mjs';
  * necessarily to forbid their use when querying a service.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLObjectType,
+ *   GraphQLSchema,
+ *   GraphQLString,
+ *   parse,
+ *   validate,
+ * } from 'graphql';
+ * import { NoDeprecatedCustomRule } from 'graphql/validation';
+ *
+ * const schema = new GraphQLSchema({
+ *   query: new GraphQLObjectType({
+ *     name: 'Query',
+ *     fields: {
+ *       name: { type: GraphQLString },
+ *       oldName: {
+ *         type: GraphQLString,
+ *         deprecationReason: 'Use name instead.',
+ *       },
+ *     },
+ *   }),
+ * });
+ *
+ * const invalidDocument = parse(`
+ *   { oldName }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoDeprecatedCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoDeprecatedCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -16,0 +57,0 @@ export function NoDeprecatedCustomRule(context) {

validation/rules/custom/NoSchemaIntrospectionCustomRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Custom Rules */
 import type { ASTVisitor } from '../../../language/visitor';
@@ -12,2 +13,29 @@ import type { ValidationContext } from '../../ValidationContext';
  * does not reflect best practices and should only be done if absolutely necessary.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoSchemaIntrospectionCustomRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -14,0 +42,0 @@ export declare function NoSchemaIntrospectionCustomRule(

validation/rules/custom/NoSchemaIntrospectionCustomRule.js

@@ -14,2 +14,4 @@ 'use strict';
 
+/** @category Custom Rules */
+
 /**
@@ -24,2 +26,29 @@ * Prohibit introspection queries
  * does not reflect best practices and should only be done if absolutely necessary.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoSchemaIntrospectionCustomRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -26,0 +55,0 @@ function NoSchemaIntrospectionCustomRule(context) {

validation/rules/custom/NoSchemaIntrospectionCustomRule.mjs

@@ -0,1 +1,2 @@
+/** @category Custom Rules */
 import { GraphQLError } from '../../../error/GraphQLError.mjs';
@@ -14,2 +15,29 @@ import { getNamedType } from '../../../type/definition.mjs';
  * does not reflect best practices and should only be done if absolutely necessary.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoSchemaIntrospectionCustomRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoSchemaIntrospectionCustomRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -16,0 +44,0 @@ export function NoSchemaIntrospectionCustomRule(context) {

validation/rules/ExecutableDefinitionsRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Executable-Definitions
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ExecutableDefinitionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   type Extra { field: String }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ExecutableDefinitionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ExecutableDefinitionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function ExecutableDefinitionsRule(

validation/rules/ExecutableDefinitionsRule.js

@@ -14,2 +14,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -22,2 +24,29 @@ * Executable definitions
  * See https://spec.graphql.org/draft/#sec-Executable-Definitions
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ExecutableDefinitionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   type Extra { field: String }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ExecutableDefinitionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ExecutableDefinitionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -24,0 +53,0 @@ function ExecutableDefinitionsRule(context) {

validation/rules/ExecutableDefinitionsRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -12,2 +13,29 @@ import { Kind } from '../../language/kinds.mjs';
  * See https://spec.graphql.org/draft/#sec-Executable-Definitions
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ExecutableDefinitionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   type Extra { field: String }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ExecutableDefinitionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ExecutableDefinitionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -14,0 +42,0 @@ export function ExecutableDefinitionsRule(context) {

validation/rules/FieldsOnCorrectTypeRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Field-Selections
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { FieldsOnCorrectTypeRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { missing }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function FieldsOnCorrectTypeRule(

validation/rules/FieldsOnCorrectTypeRule.js

@@ -18,2 +18,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -26,2 +28,29 @@ * Fields on correct type
  * See https://spec.graphql.org/draft/#sec-Field-Selections
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { FieldsOnCorrectTypeRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { missing }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -70,2 +99,4 @@ function FieldsOnCorrectTypeRule(context) {
  * sorted by how often the type is referenced.
+ *
+ * @internal
  */
@@ -136,2 +167,4 @@
  * that may be the result of a typo.
+ *
+ * @internal
  */
@@ -138,0 +171,0 @@

validation/rules/FieldsOnCorrectTypeRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { didYouMean } from '../../jsutils/didYouMean.mjs';
@@ -18,2 +19,29 @@ import { naturalCompare } from '../../jsutils/naturalCompare.mjs';
  * See https://spec.graphql.org/draft/#sec-Field-Selections
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { FieldsOnCorrectTypeRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { missing }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [FieldsOnCorrectTypeRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -60,2 +88,4 @@ export function FieldsOnCorrectTypeRule(context) {
  * sorted by how often the type is referenced.
+ *
+ * @internal
  */
@@ -120,2 +150,4 @@
  * that may be the result of a typo.
+ *
+ * @internal
  */
@@ -122,0 +154,0 @@

validation/rules/FragmentsOnCompositeTypesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -11,2 +12,29 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Fragments-On-Composite-Types
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { FragmentsOnCompositeTypesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Bad on String { length }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [FragmentsOnCompositeTypesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Good on Query { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [FragmentsOnCompositeTypesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -13,0 +41,0 @@ export declare function FragmentsOnCompositeTypesRule(

validation/rules/FragmentsOnCompositeTypesRule.js

@@ -16,2 +16,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -25,2 +27,29 @@ * Fragments on composite type
  * See https://spec.graphql.org/draft/#sec-Fragments-On-Composite-Types
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { FragmentsOnCompositeTypesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Bad on String { length }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [FragmentsOnCompositeTypesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Good on Query { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [FragmentsOnCompositeTypesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -27,0 +56,0 @@ function FragmentsOnCompositeTypesRule(context) {

validation/rules/FragmentsOnCompositeTypesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -14,2 +15,29 @@ import { print } from '../../language/printer.mjs';
  * See https://spec.graphql.org/draft/#sec-Fragments-On-Composite-Types
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { FragmentsOnCompositeTypesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Bad on String { length }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [FragmentsOnCompositeTypesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Good on Query { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [FragmentsOnCompositeTypesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -16,0 +44,0 @@ export function FragmentsOnCompositeTypesRule(context) {

validation/rules/KnownArgumentNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -14,2 +15,29 @@ import type {
  * See https://spec.graphql.org/draft/#sec-Directives-Are-In-Valid-Locations
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownArgumentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: String): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field(unknown: "1") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownArgumentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(arg: "1") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownArgumentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -19,7 +47,5 @@ export declare function KnownArgumentNamesRule(
 ): ASTVisitor;
-/**
- * @internal
- */
+/** @internal */
 export declare function KnownArgumentNamesOnDirectivesRule(
   context: ValidationContext | SDLValidationContext,
 ): ASTVisitor;

validation/rules/KnownArgumentNamesRule.js

@@ -19,2 +19,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -28,2 +30,29 @@ * Known argument names
  * See https://spec.graphql.org/draft/#sec-Directives-Are-In-Valid-Locations
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownArgumentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: String): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field(unknown: "1") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownArgumentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(arg: "1") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownArgumentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -60,5 +89,3 @@ function KnownArgumentNamesRule(context) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -65,0 +92,0 @@ function KnownArgumentNamesOnDirectivesRule(context) {

validation/rules/KnownArgumentNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { didYouMean } from '../../jsutils/didYouMean.mjs';
@@ -15,2 +16,29 @@ import { suggestionList } from '../../jsutils/suggestionList.mjs';
  * See https://spec.graphql.org/draft/#sec-Directives-Are-In-Valid-Locations
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownArgumentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: String): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field(unknown: "1") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownArgumentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(arg: "1") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownArgumentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -44,5 +72,3 @@ export function KnownArgumentNamesRule(context) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -49,0 +75,0 @@ export function KnownArgumentNamesOnDirectivesRule(context) {

validation/rules/KnownDirectivesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -13,2 +14,29 @@ import type {
  * See https://spec.graphql.org/draft/#sec-Directives-Are-Defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownDirectivesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name @unknown }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownDirectivesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name @include(if: true) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownDirectivesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -15,0 +43,0 @@ export declare function KnownDirectivesRule(

validation/rules/KnownDirectivesRule.js

@@ -22,2 +22,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -30,2 +32,29 @@ * Known directives
  * See https://spec.graphql.org/draft/#sec-Directives-Are-Defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownDirectivesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name @unknown }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownDirectivesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name @include(if: true) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownDirectivesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -32,0 +61,0 @@ function KnownDirectivesRule(context) {

validation/rules/KnownDirectivesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { inspect } from '../../jsutils/inspect.mjs';
@@ -16,2 +17,29 @@ import { invariant } from '../../jsutils/invariant.mjs';
  * See https://spec.graphql.org/draft/#sec-Directives-Are-Defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownDirectivesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name @unknown }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownDirectivesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name @include(if: true) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownDirectivesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -18,0 +46,0 @@ export function KnownDirectivesRule(context) {

validation/rules/KnownFragmentNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownFragmentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { ...Missing }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownFragmentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment NameFields on Query { name } query { ...NameFields }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownFragmentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function KnownFragmentNamesRule(

validation/rules/KnownFragmentNamesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -18,2 +20,29 @@ * Known fragment names
  * See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownFragmentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { ...Missing }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownFragmentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment NameFields on Query { name } query { ...NameFields }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownFragmentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -20,0 +49,0 @@ function KnownFragmentNamesRule(context) {

validation/rules/KnownFragmentNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -10,2 +11,29 @@
  * See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownFragmentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { ...Missing }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownFragmentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment NameFields on Query { name } query { ...NameFields }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownFragmentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export function KnownFragmentNamesRule(context) {

validation/rules/KnownTypeNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -13,2 +14,29 @@ import type {
  * See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownTypeNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Bad on Missing { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownTypeNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Good on Query { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownTypeNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -15,0 +43,0 @@ export declare function KnownTypeNamesRule(

validation/rules/KnownTypeNamesRule.js

@@ -20,2 +20,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -28,2 +30,29 @@ * Known type names
  * See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownTypeNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Bad on Missing { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownTypeNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Good on Query { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownTypeNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -30,0 +59,0 @@ function KnownTypeNamesRule(context) {

validation/rules/KnownTypeNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { didYouMean } from '../../jsutils/didYouMean.mjs';
@@ -19,2 +20,29 @@ import { suggestionList } from '../../jsutils/suggestionList.mjs';
  * See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { KnownTypeNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Bad on Missing { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [KnownTypeNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Good on Query { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [KnownTypeNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -21,0 +49,0 @@ export function KnownTypeNamesRule(context) {

validation/rules/LoneAnonymousOperationRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { LoneAnonymousOperationRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query { name } query Other { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [LoneAnonymousOperationRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [LoneAnonymousOperationRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function LoneAnonymousOperationRule(

validation/rules/LoneAnonymousOperationRule.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -20,2 +22,29 @@ * Lone anonymous operation
  * See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { LoneAnonymousOperationRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query { name } query Other { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [LoneAnonymousOperationRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [LoneAnonymousOperationRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -22,0 +51,0 @@ function LoneAnonymousOperationRule(context) {

validation/rules/LoneAnonymousOperationRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -11,2 +12,29 @@ import { Kind } from '../../language/kinds.mjs';
  * See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { LoneAnonymousOperationRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query { name } query Other { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [LoneAnonymousOperationRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [LoneAnonymousOperationRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -13,0 +41,0 @@ export function LoneAnonymousOperationRule(context) {

validation/rules/LoneSchemaDefinitionRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A GraphQL document is only valid if it contains only one schema definition.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { LoneSchemaDefinitionRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   schema { query: Query } schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * LoneSchemaDefinitionRule.name; // => 'LoneSchemaDefinitionRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export declare function LoneSchemaDefinitionRule(

validation/rules/LoneSchemaDefinitionRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -15,2 +17,22 @@ * Lone Schema definition
  * A GraphQL document is only valid if it contains only one schema definition.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { LoneSchemaDefinitionRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   schema { query: Query } schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * LoneSchemaDefinitionRule.name; // => 'LoneSchemaDefinitionRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -17,0 +39,0 @@ function LoneSchemaDefinitionRule(context) {

validation/rules/LoneSchemaDefinitionRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -7,2 +8,22 @@
  * A GraphQL document is only valid if it contains only one schema definition.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { LoneSchemaDefinitionRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   schema { query: Query } schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * LoneSchemaDefinitionRule.name; // => 'LoneSchemaDefinitionRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export function LoneSchemaDefinitionRule(context) {

validation/rules/MaxIntrospectionDepthRule.d.ts

@@ -0,5 +1,36 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
 import type { ASTValidationContext } from '../ValidationContext';
+/**
+ * Implements the max introspection depth validation rule.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { MaxIntrospectionDepthRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { types { fields { type { fields { type { fields { name } } } } } } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [MaxIntrospectionDepthRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [MaxIntrospectionDepthRule]);
+ *
+ * validErrors; // => []
+ * ```
+ */
 export declare function MaxIntrospectionDepthRule(
   context: ASTValidationContext,
 ): ASTVisitor;

validation/rules/MaxIntrospectionDepthRule.js

@@ -12,3 +12,34 @@ 'use strict';
 
+/** @category Validation Rules */
 const MAX_LISTS_DEPTH = 3;
+/**
+ * Implements the max introspection depth validation rule.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { MaxIntrospectionDepthRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { types { fields { type { fields { type { fields { name } } } } } } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [MaxIntrospectionDepthRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [MaxIntrospectionDepthRule]);
+ *
+ * validErrors; // => []
+ * ```
+ */
 
@@ -19,2 +50,4 @@ function MaxIntrospectionDepthRule(context) {
    * returns `true` if the limit has been reached.
+   *
+   * @internal
    */
@@ -21,0 +54,0 @@ function checkDepth(node, visitedFragments = Object.create(null), depth = 0) {

validation/rules/MaxIntrospectionDepthRule.mjs

@@ -0,4 +1,36 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
 import { Kind } from '../../language/kinds.mjs';
 const MAX_LISTS_DEPTH = 3;
+/**
+ * Implements the max introspection depth validation rule.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { MaxIntrospectionDepthRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { __schema { types { fields { type { fields { type { fields { name } } } } } } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [MaxIntrospectionDepthRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { __schema { queryType { name } } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [MaxIntrospectionDepthRule]);
+ *
+ * validErrors; // => []
+ * ```
+ */
+
 export function MaxIntrospectionDepthRule(context) {
@@ -8,2 +40,4 @@ /**
    * returns `true` if the limit has been reached.
+   *
+   * @internal
    */
@@ -10,0 +44,0 @@ function checkDepth(node, visitedFragments = Object.create(null), depth = 0) {

validation/rules/NoFragmentCyclesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoFragmentCyclesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment A on Query { ...B } fragment B on Query { ...A } query { ...A }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoFragmentCyclesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment A on Query { name } query { ...A }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoFragmentCyclesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function NoFragmentCyclesRule(

validation/rules/NoFragmentCyclesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -18,2 +20,29 @@ * No fragment cycles
  * See https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoFragmentCyclesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment A on Query { ...B } fragment B on Query { ...A } query { ...A }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoFragmentCyclesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment A on Query { name } query { ...A }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoFragmentCyclesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -20,0 +49,0 @@ function NoFragmentCyclesRule(context) {

validation/rules/NoFragmentCyclesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -10,2 +11,29 @@
  * See https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoFragmentCyclesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment A on Query { ...B } fragment B on Query { ...A } query { ...A }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoFragmentCyclesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment A on Query { name } query { ...A }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoFragmentCyclesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export function NoFragmentCyclesRule(context) {

validation/rules/NoUndefinedVariablesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-All-Variable-Uses-Defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUndefinedVariablesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID) { field(arg: $missing) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUndefinedVariablesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUndefinedVariablesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function NoUndefinedVariablesRule(

validation/rules/NoUndefinedVariablesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -18,2 +20,29 @@ * No undefined variables
  * See https://spec.graphql.org/draft/#sec-All-Variable-Uses-Defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUndefinedVariablesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID) { field(arg: $missing) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUndefinedVariablesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUndefinedVariablesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -20,0 +49,0 @@ function NoUndefinedVariablesRule(context) {

validation/rules/NoUndefinedVariablesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -10,2 +11,29 @@
  * See https://spec.graphql.org/draft/#sec-All-Variable-Uses-Defined
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUndefinedVariablesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID) { field(arg: $missing) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUndefinedVariablesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUndefinedVariablesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export function NoUndefinedVariablesRule(context) {

validation/rules/NoUnusedFragmentsRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Fragments-Must-Be-Used
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUnusedFragmentsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Unused on Query { name } query { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUnusedFragmentsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Used on Query { name } query { ...Used }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUnusedFragmentsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function NoUnusedFragmentsRule(

validation/rules/NoUnusedFragmentsRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -18,2 +20,29 @@ * No unused fragments
  * See https://spec.graphql.org/draft/#sec-Fragments-Must-Be-Used
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUnusedFragmentsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Unused on Query { name } query { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUnusedFragmentsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Used on Query { name } query { ...Used }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUnusedFragmentsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -20,0 +49,0 @@ function NoUnusedFragmentsRule(context) {

validation/rules/NoUnusedFragmentsRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -10,2 +11,29 @@
  * See https://spec.graphql.org/draft/#sec-Fragments-Must-Be-Used
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUnusedFragmentsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment Unused on Query { name } query { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUnusedFragmentsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment Used on Query { name } query { ...Used }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUnusedFragmentsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export function NoUnusedFragmentsRule(context) {

validation/rules/NoUnusedVariablesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,30 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-All-Variables-Used
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUnusedVariablesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID) { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUnusedVariablesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUnusedVariablesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +41,0 @@ export declare function NoUnusedVariablesRule(

validation/rules/NoUnusedVariablesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -18,2 +20,30 @@ * No unused variables
  * See https://spec.graphql.org/draft/#sec-All-Variables-Used
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUnusedVariablesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID) { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUnusedVariablesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUnusedVariablesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -20,0 +50,0 @@ function NoUnusedVariablesRule(context) {

validation/rules/NoUnusedVariablesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -10,2 +11,30 @@
  * See https://spec.graphql.org/draft/#sec-All-Variables-Used
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { NoUnusedVariablesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID) { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [NoUnusedVariablesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [NoUnusedVariablesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +41,0 @@ export function NoUnusedVariablesRule(context) {

validation/rules/OverlappingFieldsCanBeMergedRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -11,2 +12,34 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Field-Selection-Merging
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { OverlappingFieldsCanBeMergedRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     dog: Dog
+ *   }
+ *
+ *   type Dog {
+ *     name: String
+ *     barkVolume: Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { dog { value: barkVolume value: name } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { dog { barkVolume name } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -13,0 +46,0 @@ export declare function OverlappingFieldsCanBeMergedRule(

validation/rules/OverlappingFieldsCanBeMergedRule.js

@@ -22,2 +22,3 @@ 'use strict';
 
+/** @category Validation Rules */
 function reasonMessage(reason) {
@@ -44,2 +45,34 @@ if (Array.isArray(reason)) {
  * See https://spec.graphql.org/draft/#sec-Field-Selection-Merging
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { OverlappingFieldsCanBeMergedRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     dog: Dog
+ *   }
+ *
+ *   type Dog {
+ *     name: String
+ *     barkVolume: Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { dog { value: barkVolume value: name } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { dog { barkVolume name } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -84,2 +117,6 @@
 /**
+ * Find all conflicts found "within" a selection set, including those found
+ * via spreading in fragments. Called when visiting each SelectionSet in the
+ * GraphQL Document.
+ *
  * Algorithm:
@@ -100,3 +137,3 @@ *
  * overlapping fields.
- * Note: This is the *only time* that a the fields "within" a set are compared
+ * Note: This is the *only time* that the fields "within" a set are compared
  * to each other. After this only fields "between" sets are compared.
@@ -113,3 +150,3 @@ *
  * a comparison is made between each field in the original set of fields and
- * each field in the the referenced set of fields.
+ * each field in the referenced set of fields.
  *
@@ -121,3 +158,3 @@ * E) Also, if any fragment is referenced in the referenced selection set,
  * F) When comparing "between" two fragments, first a comparison is made between
- * each field in the first referenced set of fields and each field in the the
+ * each field in the first referenced set of fields and each field in the
  * second referenced set of fields.
@@ -140,6 +177,4 @@ *
  *
+ * @internal
  */
-// Find all conflicts found "within" a selection set, including those found
-// via spreading in fragments. Called when visiting each SelectionSet in the
-// GraphQL Document.
 function findConflictsWithinSelectionSet(
@@ -819,2 +854,4 @@ context,
  * weakly or strongly present within the collection.
+ *
+ * @internal
  */
@@ -856,2 +893,4 @@
  * does not matter.
+ *
+ * @internal
  */
@@ -858,0 +897,0 @@

validation/rules/OverlappingFieldsCanBeMergedRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { inspect } from '../../jsutils/inspect.mjs';
@@ -37,2 +38,34 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * See https://spec.graphql.org/draft/#sec-Field-Selection-Merging
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { OverlappingFieldsCanBeMergedRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     dog: Dog
+ *   }
+ *
+ *   type Dog {
+ *     name: String
+ *     barkVolume: Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { dog { value: barkVolume value: name } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { dog { barkVolume name } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [OverlappingFieldsCanBeMergedRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -77,2 +110,6 @@
 /**
+ * Find all conflicts found "within" a selection set, including those found
+ * via spreading in fragments. Called when visiting each SelectionSet in the
+ * GraphQL Document.
+ *
  * Algorithm:
@@ -93,3 +130,3 @@ *
  * overlapping fields.
- * Note: This is the *only time* that a the fields "within" a set are compared
+ * Note: This is the *only time* that the fields "within" a set are compared
  * to each other. After this only fields "between" sets are compared.
@@ -106,3 +143,3 @@ *
  * a comparison is made between each field in the original set of fields and
- * each field in the the referenced set of fields.
+ * each field in the referenced set of fields.
  *
@@ -114,3 +151,3 @@ * E) Also, if any fragment is referenced in the referenced selection set,
  * F) When comparing "between" two fragments, first a comparison is made between
- * each field in the first referenced set of fields and each field in the the
+ * each field in the first referenced set of fields and each field in the
  * second referenced set of fields.
@@ -133,6 +170,4 @@ *
  *
+ * @internal
  */
-// Find all conflicts found "within" a selection set, including those found
-// via spreading in fragments. Called when visiting each SelectionSet in the
-// GraphQL Document.
 function findConflictsWithinSelectionSet(
@@ -803,2 +838,4 @@ context,
  * weakly or strongly present within the collection.
+ *
+ * @internal
  */
@@ -840,2 +877,4 @@
  * does not matter.
+ *
+ * @internal
  */
@@ -842,0 +881,0 @@

validation/rules/PossibleFragmentSpreadsRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -9,2 +10,37 @@ import type { ValidationContext } from '../ValidationContext';
  * and possible types which pass the type condition.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { PossibleFragmentSpreadsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     dog: Dog
+ *   }
+ *
+ *   type Dog {
+ *     barkVolume: Int
+ *   }
+ *
+ *   type Cat {
+ *     meowVolume: Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { dog { ... on Cat { meowVolume } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [PossibleFragmentSpreadsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { dog { ... on Dog { barkVolume } } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [PossibleFragmentSpreadsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -11,0 +47,0 @@ export declare function PossibleFragmentSpreadsRule(

validation/rules/PossibleFragmentSpreadsRule.js

@@ -18,2 +18,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -25,2 +27,37 @@ * Possible fragment spread
  * and possible types which pass the type condition.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { PossibleFragmentSpreadsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     dog: Dog
+ *   }
+ *
+ *   type Dog {
+ *     barkVolume: Int
+ *   }
+ *
+ *   type Cat {
+ *     meowVolume: Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { dog { ... on Cat { meowVolume } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [PossibleFragmentSpreadsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { dog { ... on Dog { barkVolume } } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [PossibleFragmentSpreadsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -27,0 +64,0 @@ function PossibleFragmentSpreadsRule(context) {

validation/rules/PossibleFragmentSpreadsRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { inspect } from '../../jsutils/inspect.mjs';
@@ -13,2 +14,37 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * and possible types which pass the type condition.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { PossibleFragmentSpreadsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     dog: Dog
+ *   }
+ *
+ *   type Dog {
+ *     barkVolume: Int
+ *   }
+ *
+ *   type Cat {
+ *     meowVolume: Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { dog { ... on Cat { meowVolume } } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [PossibleFragmentSpreadsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { dog { ... on Dog { barkVolume } } }
+ * `);
+ * const validErrors = validate(schema, validDocument, [PossibleFragmentSpreadsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -15,0 +51,0 @@ export function PossibleFragmentSpreadsRule(context) {

validation/rules/PossibleTypeExtensionsRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A type extension is only valid if the type is defined and has the same kind.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { PossibleTypeExtensionsRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   extend type Missing { name: String } type Query { name: String }
+ * `;
+ *
+ * PossibleTypeExtensionsRule.name; // => 'PossibleTypeExtensionsRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String } extend type Query { other: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export declare function PossibleTypeExtensionsRule(

validation/rules/PossibleTypeExtensionsRule.js

@@ -24,2 +24,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -29,2 +31,22 @@ * Possible type extension
  * A type extension is only valid if the type is defined and has the same kind.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { PossibleTypeExtensionsRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   extend type Missing { name: String } type Query { name: String }
+ * `;
+ *
+ * PossibleTypeExtensionsRule.name; // => 'PossibleTypeExtensionsRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String } extend type Query { other: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -31,0 +53,0 @@ function PossibleTypeExtensionsRule(context) {

validation/rules/PossibleTypeExtensionsRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { didYouMean } from '../../jsutils/didYouMean.mjs';
@@ -21,2 +22,22 @@ import { inspect } from '../../jsutils/inspect.mjs';
  * A type extension is only valid if the type is defined and has the same kind.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { PossibleTypeExtensionsRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   extend type Missing { name: String } type Query { name: String }
+ * `;
+ *
+ * PossibleTypeExtensionsRule.name; // => 'PossibleTypeExtensionsRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String } extend type Query { other: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -23,0 +44,0 @@ export function PossibleTypeExtensionsRule(context) {

validation/rules/ProvidedRequiredArgumentsRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -11,2 +12,29 @@ import type {
  * default value) field arguments have been provided.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ProvidedRequiredArgumentsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(required: String!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ProvidedRequiredArgumentsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(required: "x") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ProvidedRequiredArgumentsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -16,7 +44,5 @@ export declare function ProvidedRequiredArgumentsRule(
 ): ASTVisitor;
-/**
- * @internal
- */
+/** @internal */
 export declare function ProvidedRequiredArgumentsOnDirectivesRule(
   context: ValidationContext | SDLValidationContext,
 ): ASTVisitor;

validation/rules/ProvidedRequiredArgumentsRule.js

@@ -24,2 +24,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -30,2 +32,29 @@ * Provided required arguments
  * default value) field arguments have been provided.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ProvidedRequiredArgumentsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(required: String!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ProvidedRequiredArgumentsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(required: "x") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ProvidedRequiredArgumentsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -75,5 +104,3 @@ function ProvidedRequiredArgumentsRule(context) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -80,0 +107,0 @@ function ProvidedRequiredArgumentsOnDirectivesRule(context) {

validation/rules/ProvidedRequiredArgumentsRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { inspect } from '../../jsutils/inspect.mjs';
@@ -14,2 +15,29 @@ import { keyMap } from '../../jsutils/keyMap.mjs';
  * default value) field arguments have been provided.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ProvidedRequiredArgumentsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(required: String!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ProvidedRequiredArgumentsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(required: "x") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ProvidedRequiredArgumentsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -56,5 +84,3 @@ export function ProvidedRequiredArgumentsRule(context) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -61,0 +87,0 @@ export function ProvidedRequiredArgumentsOnDirectivesRule(context) {

validation/rules/ScalarLeafsRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -8,3 +9,30 @@ import type { ValidationContext } from '../ValidationContext';
  * sub selections) are of scalar or enum types.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ScalarLeafsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name { length } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ScalarLeafsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ScalarLeafsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
 export declare function ScalarLeafsRule(context: ValidationContext): ASTVisitor;

validation/rules/ScalarLeafsRule.js

@@ -14,2 +14,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -20,2 +22,29 @@ * Scalar leafs
  * sub selections) are of scalar or enum types.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ScalarLeafsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name { length } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ScalarLeafsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ScalarLeafsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -22,0 +51,0 @@ function ScalarLeafsRule(context) {

validation/rules/ScalarLeafsRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { inspect } from '../../jsutils/inspect.mjs';
@@ -10,2 +11,29 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * sub selections) are of scalar or enum types.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ScalarLeafsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name { length } }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ScalarLeafsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ScalarLeafsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export function ScalarLeafsRule(context) {

validation/rules/SingleFieldSubscriptionsRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,34 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Single-root-field
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { SingleFieldSubscriptionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ *
+ *   type Subscription {
+ *     a: String
+ *     b: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   subscription { a b }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [SingleFieldSubscriptionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   subscription { a }
+ * `);
+ * const validErrors = validate(schema, validDocument, [SingleFieldSubscriptionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +45,0 @@ export declare function SingleFieldSubscriptionsRule(

validation/rules/SingleFieldSubscriptionsRule.js

@@ -14,2 +14,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -22,2 +24,34 @@ * Subscriptions must only include a non-introspection field.
  * See https://spec.graphql.org/draft/#sec-Single-root-field
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { SingleFieldSubscriptionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ *
+ *   type Subscription {
+ *     a: String
+ *     b: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   subscription { a b }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [SingleFieldSubscriptionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   subscription { a }
+ * `);
+ * const validErrors = validate(schema, validDocument, [SingleFieldSubscriptionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -24,0 +58,0 @@ function SingleFieldSubscriptionsRule(context) {

validation/rules/SingleFieldSubscriptionsRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -12,2 +13,34 @@ import { Kind } from '../../language/kinds.mjs';
  * See https://spec.graphql.org/draft/#sec-Single-root-field
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { SingleFieldSubscriptionsRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ *
+ *   type Subscription {
+ *     a: String
+ *     b: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   subscription { a b }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [SingleFieldSubscriptionsRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   subscription { a }
+ * `);
+ * const validErrors = validate(schema, validDocument, [SingleFieldSubscriptionsRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -14,0 +47,0 @@ export function SingleFieldSubscriptionsRule(context) {

validation/rules/UniqueArgumentDefinitionNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -8,2 +9,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A GraphQL Directive is only valid if all its arguments are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueArgumentDefinitionNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { field(arg: String, arg: Int): String }
+ * `;
+ *
+ * UniqueArgumentDefinitionNamesRule.name; // => 'UniqueArgumentDefinitionNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { field(arg: String): String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -10,0 +31,0 @@ export declare function UniqueArgumentDefinitionNamesRule(

validation/rules/UniqueArgumentDefinitionNamesRule.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -18,2 +20,22 @@ * Unique argument definition names
  * A GraphQL Directive is only valid if all its arguments are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueArgumentDefinitionNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { field(arg: String, arg: Int): String }
+ * `;
+ *
+ * UniqueArgumentDefinitionNamesRule.name; // => 'UniqueArgumentDefinitionNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { field(arg: String): String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -20,0 +42,0 @@ function UniqueArgumentDefinitionNamesRule(context) {

validation/rules/UniqueArgumentDefinitionNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { groupBy } from '../../jsutils/groupBy.mjs';
@@ -9,2 +10,22 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * A GraphQL Directive is only valid if all its arguments are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueArgumentDefinitionNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { field(arg: String, arg: Int): String }
+ * `;
+ *
+ * UniqueArgumentDefinitionNamesRule.name; // => 'UniqueArgumentDefinitionNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { field(arg: String): String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -11,0 +32,0 @@ export function UniqueArgumentDefinitionNamesRule(context) {

validation/rules/UniqueArgumentNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Argument-Names
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueArgumentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: String): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field(arg: "1", arg: "2") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueArgumentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(arg: "1") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueArgumentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function UniqueArgumentNamesRule(

validation/rules/UniqueArgumentNamesRule.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -20,2 +22,29 @@ * Unique argument names
  * See https://spec.graphql.org/draft/#sec-Argument-Names
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueArgumentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: String): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field(arg: "1", arg: "2") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueArgumentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(arg: "1") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueArgumentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -22,0 +51,0 @@ function UniqueArgumentNamesRule(context) {

validation/rules/UniqueArgumentNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { groupBy } from '../../jsutils/groupBy.mjs';
@@ -11,2 +12,29 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * See https://spec.graphql.org/draft/#sec-Argument-Names
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueArgumentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: String): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { field(arg: "1", arg: "2") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueArgumentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { field(arg: "1") }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueArgumentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -13,0 +41,0 @@ export function UniqueArgumentNamesRule(context) {

validation/rules/UniqueDirectiveNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A GraphQL document is only valid if all defined directives have unique names.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueDirectiveNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   directive @tag on FIELD directive @tag on QUERY type Query { name: String }
+ * `;
+ *
+ * UniqueDirectiveNamesRule.name; // => 'UniqueDirectiveNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   directive @tag on FIELD type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export declare function UniqueDirectiveNamesRule(

validation/rules/UniqueDirectiveNamesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -15,2 +17,22 @@ * Unique directive names
  * A GraphQL document is only valid if all defined directives have unique names.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueDirectiveNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   directive @tag on FIELD directive @tag on QUERY type Query { name: String }
+ * `;
+ *
+ * UniqueDirectiveNamesRule.name; // => 'UniqueDirectiveNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   directive @tag on FIELD type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -17,0 +39,0 @@ function UniqueDirectiveNamesRule(context) {

validation/rules/UniqueDirectiveNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -7,2 +8,22 @@
  * A GraphQL document is only valid if all defined directives have unique names.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueDirectiveNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   directive @tag on FIELD directive @tag on QUERY type Query { name: String }
+ * `;
+ *
+ * UniqueDirectiveNamesRule.name; // => 'UniqueDirectiveNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   directive @tag on FIELD type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export function UniqueDirectiveNamesRule(context) {

validation/rules/UniqueDirectivesPerLocationRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -13,2 +14,29 @@ import type {
  * See https://spec.graphql.org/draft/#sec-Directives-Are-Unique-Per-Location
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueDirectivesPerLocationRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name @include(if: true) @include(if: false) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueDirectivesPerLocationRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name @include(if: true) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueDirectivesPerLocationRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -15,0 +43,0 @@ export declare function UniqueDirectivesPerLocationRule(

validation/rules/UniqueDirectivesPerLocationRule.js

@@ -16,2 +16,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -24,2 +26,29 @@ * Unique directive names per location
  * See https://spec.graphql.org/draft/#sec-Directives-Are-Unique-Per-Location
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueDirectivesPerLocationRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name @include(if: true) @include(if: false) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueDirectivesPerLocationRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name @include(if: true) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueDirectivesPerLocationRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -26,0 +55,0 @@ function UniqueDirectivesPerLocationRule(context) {

validation/rules/UniqueDirectivesPerLocationRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -16,2 +17,29 @@ import { Kind } from '../../language/kinds.mjs';
  * See https://spec.graphql.org/draft/#sec-Directives-Are-Unique-Per-Location
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueDirectivesPerLocationRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { name @include(if: true) @include(if: false) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueDirectivesPerLocationRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { name @include(if: true) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueDirectivesPerLocationRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -18,0 +46,0 @@ export function UniqueDirectivesPerLocationRule(context) {

validation/rules/UniqueEnumValueNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A GraphQL enum type is only valid if all its values are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueEnumValueNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   enum Status { ACTIVE ACTIVE } type Query { status: Status }
+ * `;
+ *
+ * UniqueEnumValueNamesRule.name; // => 'UniqueEnumValueNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   enum Status { ACTIVE INACTIVE } type Query { status: Status }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export declare function UniqueEnumValueNamesRule(

validation/rules/UniqueEnumValueNamesRule.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -17,2 +19,22 @@ * Unique enum value names
  * A GraphQL enum type is only valid if all its values are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueEnumValueNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   enum Status { ACTIVE ACTIVE } type Query { status: Status }
+ * `;
+ *
+ * UniqueEnumValueNamesRule.name; // => 'UniqueEnumValueNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   enum Status { ACTIVE INACTIVE } type Query { status: Status }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -19,0 +41,0 @@ function UniqueEnumValueNamesRule(context) {

validation/rules/UniqueEnumValueNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -8,2 +9,22 @@ import { isEnumType } from '../../type/definition.mjs';
  * A GraphQL enum type is only valid if all its values are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueEnumValueNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   enum Status { ACTIVE ACTIVE } type Query { status: Status }
+ * `;
+ *
+ * UniqueEnumValueNamesRule.name; // => 'UniqueEnumValueNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   enum Status { ACTIVE INACTIVE } type Query { status: Status }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -10,0 +31,0 @@ export function UniqueEnumValueNamesRule(context) {

validation/rules/UniqueFieldDefinitionNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A GraphQL complex type is only valid if all its fields are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueFieldDefinitionNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { name: String name: String }
+ * `;
+ *
+ * UniqueFieldDefinitionNamesRule.name; // => 'UniqueFieldDefinitionNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String other: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export declare function UniqueFieldDefinitionNamesRule(

validation/rules/UniqueFieldDefinitionNamesRule.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -17,2 +19,22 @@ * Unique field definition names
  * A GraphQL complex type is only valid if all its fields are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueFieldDefinitionNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { name: String name: String }
+ * `;
+ *
+ * UniqueFieldDefinitionNamesRule.name; // => 'UniqueFieldDefinitionNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String other: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -19,0 +41,0 @@ function UniqueFieldDefinitionNamesRule(context) {

validation/rules/UniqueFieldDefinitionNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -12,2 +13,22 @@ import {
  * A GraphQL complex type is only valid if all its fields are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueFieldDefinitionNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { name: String name: String }
+ * `;
+ *
+ * UniqueFieldDefinitionNamesRule.name; // => 'UniqueFieldDefinitionNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String other: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -14,0 +35,0 @@ export function UniqueFieldDefinitionNamesRule(context) {

validation/rules/UniqueFragmentNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -9,2 +10,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Fragment-Name-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueFragmentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment A on Query { name } fragment A on Query { name } query { ...A }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueFragmentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment A on Query { name } query { ...A }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueFragmentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -11,0 +39,0 @@ export declare function UniqueFragmentNamesRule(

validation/rules/UniqueFragmentNamesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -17,2 +19,29 @@ * Unique fragment names
  * See https://spec.graphql.org/draft/#sec-Fragment-Name-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueFragmentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment A on Query { name } fragment A on Query { name } query { ...A }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueFragmentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment A on Query { name } query { ...A }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueFragmentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -19,0 +48,0 @@ function UniqueFragmentNamesRule(context) {

validation/rules/UniqueFragmentNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -9,2 +10,29 @@
  * See https://spec.graphql.org/draft/#sec-Fragment-Name-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueFragmentNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   fragment A on Query { name } fragment A on Query { name } query { ...A }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueFragmentNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   fragment A on Query { name } query { ...A }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueFragmentNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -11,0 +39,0 @@ export function UniqueFragmentNamesRule(context) {

validation/rules/UniqueInputFieldNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,33 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Input-Object-Field-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueInputFieldNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   input Filter {
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     search(filter: Filter): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { search(filter: { name: "a", name: "b" }) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueInputFieldNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { search(filter: { name: "a" }) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueInputFieldNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +44,0 @@ export declare function UniqueInputFieldNamesRule(

validation/rules/UniqueInputFieldNamesRule.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -20,2 +22,33 @@ * Unique input field names
  * See https://spec.graphql.org/draft/#sec-Input-Object-Field-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueInputFieldNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   input Filter {
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     search(filter: Filter): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { search(filter: { name: "a", name: "b" }) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueInputFieldNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { search(filter: { name: "a" }) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueInputFieldNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -22,0 +55,0 @@ function UniqueInputFieldNamesRule(context) {

validation/rules/UniqueInputFieldNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { invariant } from '../../jsutils/invariant.mjs';
@@ -11,2 +12,33 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * See https://spec.graphql.org/draft/#sec-Input-Object-Field-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueInputFieldNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   input Filter {
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     search(filter: Filter): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { search(filter: { name: "a", name: "b" }) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueInputFieldNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { search(filter: { name: "a" }) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueInputFieldNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -13,0 +45,0 @@ export function UniqueInputFieldNamesRule(context) {

validation/rules/UniqueOperationNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -9,2 +10,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Operation-Name-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueOperationNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query Same { name } query Same { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueOperationNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query One { name } query Two { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueOperationNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -11,0 +39,0 @@ export declare function UniqueOperationNamesRule(

validation/rules/UniqueOperationNamesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -17,2 +19,29 @@ * Unique operation names
  * See https://spec.graphql.org/draft/#sec-Operation-Name-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueOperationNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query Same { name } query Same { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueOperationNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query One { name } query Two { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueOperationNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -19,0 +48,0 @@ function UniqueOperationNamesRule(context) {

validation/rules/UniqueOperationNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -9,2 +10,29 @@
  * See https://spec.graphql.org/draft/#sec-Operation-Name-Uniqueness
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueOperationNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query Same { name } query Same { name }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueOperationNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query One { name } query Two { name }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueOperationNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -11,0 +39,0 @@ export function UniqueOperationNamesRule(context) {

validation/rules/UniqueOperationTypesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A GraphQL document is only valid if it has only one type per operation.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueOperationTypesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   schema { query: Query query: Other } type Query { name: String } type Other { name: String }
+ * `;
+ *
+ * UniqueOperationTypesRule.name; // => 'UniqueOperationTypesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export declare function UniqueOperationTypesRule(

validation/rules/UniqueOperationTypesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -15,2 +17,22 @@ * Unique operation types
  * A GraphQL document is only valid if it has only one type per operation.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueOperationTypesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   schema { query: Query query: Other } type Query { name: String } type Other { name: String }
+ * `;
+ *
+ * UniqueOperationTypesRule.name; // => 'UniqueOperationTypesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -17,0 +39,0 @@ function UniqueOperationTypesRule(context) {

validation/rules/UniqueOperationTypesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -7,2 +8,22 @@
  * A GraphQL document is only valid if it has only one type per operation.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueOperationTypesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   schema { query: Query query: Other } type Query { name: String } type Other { name: String }
+ * `;
+ *
+ * UniqueOperationTypesRule.name; // => 'UniqueOperationTypesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   schema { query: Query } type Query { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export function UniqueOperationTypesRule(context) {

validation/rules/UniqueTypeNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,22 @@ import type { SDLValidationContext } from '../ValidationContext';
  * A GraphQL document is only valid if all defined types have unique names.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueTypeNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { name: String } type Query { other: String }
+ * `;
+ *
+ * UniqueTypeNamesRule.name; // => 'UniqueTypeNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String } type Other { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export declare function UniqueTypeNamesRule(

validation/rules/UniqueTypeNamesRule.js

@@ -10,2 +10,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -15,2 +17,22 @@ * Unique type names
  * A GraphQL document is only valid if all defined types have unique names.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueTypeNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { name: String } type Query { other: String }
+ * `;
+ *
+ * UniqueTypeNamesRule.name; // => 'UniqueTypeNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String } type Other { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -17,0 +39,0 @@ function UniqueTypeNamesRule(context) {

validation/rules/UniqueTypeNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -7,2 +8,22 @@
  * A GraphQL document is only valid if all defined types have unique names.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql';
+ * import { UniqueTypeNamesRule } from 'graphql/validation';
+ *
+ * const invalidSDL = `
+ *   type Query { name: String } type Query { other: String }
+ * `;
+ *
+ * UniqueTypeNamesRule.name; // => 'UniqueTypeNamesRule'
+ * buildSchema(invalidSDL); // throws an error
+ *
+ * const validSDL = `
+ *   type Query { name: String } type Other { name: String }
+ * `;
+ *
+ * buildSchema(validSDL); // does not throw
+ * ```
  */
@@ -9,0 +30,0 @@ export function UniqueTypeNamesRule(context) {

validation/rules/UniqueVariableNamesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -7,2 +8,29 @@ import type { ASTValidationContext } from '../ValidationContext';
  * A GraphQL operation is only valid if all its variables are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueVariableNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID, $id: ID) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueVariableNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueVariableNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -9,0 +37,0 @@ export declare function UniqueVariableNamesRule(

validation/rules/UniqueVariableNamesRule.js

@@ -12,2 +12,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -17,2 +19,29 @@ * Unique variable names
  * A GraphQL operation is only valid if all its variables are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueVariableNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID, $id: ID) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueVariableNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueVariableNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -19,0 +48,0 @@ function UniqueVariableNamesRule(context) {

validation/rules/UniqueVariableNamesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { groupBy } from '../../jsutils/groupBy.mjs';
@@ -8,2 +9,29 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * A GraphQL operation is only valid if all its variables are uniquely named.
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { UniqueVariableNamesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: ID, $id: ID) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [UniqueVariableNamesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [UniqueVariableNamesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -10,0 +38,0 @@ export function UniqueVariableNamesRule(context) {

validation/rules/ValuesOfCorrectTypeRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,29 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Values-of-Correct-Type
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ValuesOfCorrectTypeRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     count(limit: Int): Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { count(limit: "many") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ValuesOfCorrectTypeRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { count(limit: 1) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ValuesOfCorrectTypeRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +40,0 @@ export declare function ValuesOfCorrectTypeRule(

validation/rules/ValuesOfCorrectTypeRule.js

@@ -24,2 +24,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -32,2 +34,29 @@ * Value literals of correct type
  * See https://spec.graphql.org/draft/#sec-Values-of-Correct-Type
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ValuesOfCorrectTypeRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     count(limit: Int): Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { count(limit: "many") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ValuesOfCorrectTypeRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { count(limit: 1) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ValuesOfCorrectTypeRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -138,2 +167,4 @@ function ValuesOfCorrectTypeRule(context) {
  * that scalar type.
+ *
+ * @internal
  */
@@ -140,0 +171,0 @@

validation/rules/ValuesOfCorrectTypeRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { didYouMean } from '../../jsutils/didYouMean.mjs';
@@ -25,2 +26,29 @@ import { inspect } from '../../jsutils/inspect.mjs';
  * See https://spec.graphql.org/draft/#sec-Values-of-Correct-Type
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { ValuesOfCorrectTypeRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     count(limit: Int): Int
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   { count(limit: "many") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [ValuesOfCorrectTypeRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   { count(limit: 1) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [ValuesOfCorrectTypeRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -122,2 +150,4 @@ export function ValuesOfCorrectTypeRule(context) {
  * that scalar type.
+ *
+ * @internal
  */
@@ -124,0 +154,0 @@

validation/rules/VariablesAreInputTypesRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -10,2 +11,33 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { VariablesAreInputTypesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ *
+ *   type User {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($user: User) { field(arg: "1") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesAreInputTypesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesAreInputTypesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -12,0 +44,0 @@ export declare function VariablesAreInputTypesRule(

validation/rules/VariablesAreInputTypesRule.js

@@ -16,2 +16,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -24,2 +26,33 @@ * Variables are input types
  * See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { VariablesAreInputTypesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ *
+ *   type User {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($user: User) { field(arg: "1") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesAreInputTypesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesAreInputTypesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -26,0 +59,0 @@ function VariablesAreInputTypesRule(context) {

validation/rules/VariablesAreInputTypesRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { GraphQLError } from '../../error/GraphQLError.mjs';
@@ -13,2 +14,33 @@ import { print } from '../../language/printer.mjs';
  * See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { VariablesAreInputTypesRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID): String
+ *   }
+ *
+ *   type User {
+ *     name: String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($user: User) { field(arg: "1") }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesAreInputTypesRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesAreInputTypesRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -15,0 +47,0 @@ export function VariablesAreInputTypesRule(context) {

validation/rules/VariablesInAllowedPositionRule.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import type { ASTVisitor } from '../../language/visitor';
@@ -9,2 +10,29 @@ import type { ValidationContext } from '../ValidationContext';
  * See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { VariablesInAllowedPositionRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: String) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesInAllowedPositionRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID!) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesInAllowedPositionRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -11,0 +39,0 @@ export declare function VariablesInAllowedPositionRule(

validation/rules/VariablesInAllowedPositionRule.js

@@ -20,2 +20,4 @@ 'use strict';
 
+/** @category Validation Rules */
+
 /**
@@ -27,2 +29,29 @@ * Variables in allowed position
  * See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { VariablesInAllowedPositionRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: String) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesInAllowedPositionRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID!) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesInAllowedPositionRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -101,4 +130,9 @@ function VariablesInAllowedPositionRule(context) {
  * Returns true if the variable is allowed in the location it was found,
- * which includes considering if default values exist for either the variable
+ * including considering if default values exist for either the variable
  * or the location at which it is located.
+ *
+ * OneOf Input Object Type fields are considered separately above to
+ * provide a more descriptive error message.
+ *
+ * @internal
  */
@@ -105,0 +139,0 @@

validation/rules/VariablesInAllowedPositionRule.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { inspect } from '../../jsutils/inspect.mjs';
@@ -18,2 +19,29 @@ import { GraphQLError } from '../../error/GraphQLError.mjs';
  * See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed
+ * @param context - The validation context used while checking the document.
+ * @returns A visitor that reports validation errors for this rule.
+ * @example
+ * ```ts
+ * import { buildSchema, parse, validate } from 'graphql';
+ * import { VariablesInAllowedPositionRule } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     field(arg: ID!): String
+ *   }
+ * `);
+ *
+ * const invalidDocument = parse(`
+ *   query ($id: String) { field(arg: $id) }
+ * `);
+ * const invalidErrors = validate(schema, invalidDocument, [VariablesInAllowedPositionRule]);
+ *
+ * invalidErrors.length; // => 1
+ *
+ * const validDocument = parse(`
+ *   query ($id: ID!) { field(arg: $id) }
+ * `);
+ * const validErrors = validate(schema, validDocument, [VariablesInAllowedPositionRule]);
+ *
+ * validErrors; // => []
+ * ```
  */
@@ -92,4 +120,9 @@ export function VariablesInAllowedPositionRule(context) {
  * Returns true if the variable is allowed in the location it was found,
- * which includes considering if default values exist for either the variable
+ * including considering if default values exist for either the variable
  * or the location at which it is located.
+ *
+ * OneOf Input Object Type fields are considered separately above to
+ * provide a more descriptive error message.
+ *
+ * @internal
  */
@@ -96,0 +129,0 @@

validation/specifiedRules.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 import { MaxIntrospectionDepthRule } from './rules/MaxIntrospectionDepthRule';
@@ -15,5 +16,3 @@ import type { SDLValidationRule, ValidationRule } from './ValidationContext';
 export declare const specifiedRules: ReadonlyArray<ValidationRule>;
-/**
- * @internal
- */
+/** @internal */
 export declare const specifiedSDLRules: ReadonlyArray<SDLValidationRule>;

validation/specifiedRules.js

@@ -81,2 +81,3 @@ 'use strict';
 
+/** @category Validation Rules */
 // Spec Section: "Executable Definitions"
@@ -155,5 +156,3 @@ // Spec Section: "Field Selections on Objects, Interfaces, and Unions Types"
 ]);
-/**
- * @internal
- */
+/** @internal */
 
@@ -160,0 +159,0 @@ exports.specifiedRules = specifiedRules;

validation/specifiedRules.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Rules */
 // Spec Section: "Executable Definitions"
@@ -112,5 +113,3 @@ import { ExecutableDefinitionsRule } from './rules/ExecutableDefinitionsRule.mjs'; // Spec Section: "Field Selections on Objects, Interfaces, and Unions Types"
 ]);
-/**
- * @internal
- */
+/** @internal */
 
@@ -117,0 +116,0 @@ export const specifiedSDLRules = Object.freeze([

validation/validate.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation */
 import type { Maybe } from '../jsutils/Maybe';
@@ -8,2 +9,13 @@ import { GraphQLError } from '../error/GraphQLError';
 /**
+ * Options used when validating a GraphQL document.
+ * @internal
+ */
+export interface ValidationOptions {
+  /**
+   * Maximum number of validation errors before validation stops.
+   * @internal
+   */
+  maxErrors?: number;
+}
+/**
  * Implements the "Validation" section of the spec.
@@ -17,3 +29,3 @@ *
  *
- * Each validation rules is a function which returns a visitor
+ * Each validation rule is a function that returns a visitor
  * (see the language/visitor API). Visitor methods are expected to return
@@ -24,6 +36,55 @@ * GraphQLErrors, or Arrays of GraphQLErrors when invalid.
  * Attackers can send pathologically invalid queries to induce a DoS attack,
- * so by default `maxErrors` set to 100 errors.
+ * so `maxErrors` defaults to 100 errors.
  *
  * Optionally a custom TypeInfo instance may be provided. If not provided, one
  * will be created from the provided schema.
+ * @param schema - Schema to validate against.
+ * @param documentAST - Document AST to validate.
+ * @param rules - Validation rules to apply.
+ * @param options - Validation options, including error limits.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @returns Validation errors, or an empty array when the document is valid.
+ * @example
+ * ```ts
+ * // Validate with the default specified rules.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * validate(schema, parse('{ greeting }')); // => []
+ *
+ * const errors = validate(schema, parse('{ missing }'));
+ * errors[0].message; // => 'Cannot query field "missing" on type "Query".'
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a custom rule list, TypeInfo, and validation options.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, TypeInfo } from 'graphql/utilities';
+ * import { FieldsOnCorrectTypeRule, validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ missingOne missingTwo }');
+ *
+ * const errors = validate(
+ *   schema,
+ *   document,
+ *   [FieldsOnCorrectTypeRule],
+ *   { maxErrors: 1 },
+ *   new TypeInfo(schema),
+ * );
+ *
+ * errors.length; // => 2
+ * errors[1].message; // => 'Too many validation errors, error limit reached. Validation aborted.'
+ * ```
  */
@@ -34,11 +95,11 @@ export declare function validate(
   rules?: ReadonlyArray<ValidationRule>,
-  options?: {
-    maxErrors?: number;
-  },
-  /** @deprecated will be removed in 17.0.0 */
+  options?: ValidationOptions,
+  /**
+   * Deprecated TypeInfo instance used to track traversal state during
+   * validation. Omit this argument so validate creates the TypeInfo instance.
+   * @deprecated will be removed in 17.0.0
+   */
   typeInfo?: TypeInfo,
 ): ReadonlyArray<GraphQLError>;
-/**
- * @internal
- */
+/** @internal */
 export declare function validateSDL(
@@ -45,0 +106,0 @@ documentAST: DocumentNode,

validation/validate.js

@@ -29,2 +29,3 @@ 'use strict';
 
+/** @category Validation */
 // Per the specification, descriptions must not affect validation.
@@ -37,2 +38,7 @@ // See https://spec.graphql.org/draft/#sec-Descriptions
 /**
+ * Options used when validating a GraphQL document.
+ * @internal
+ */
+
+/**
  * Implements the "Validation" section of the spec.
@@ -46,3 +52,3 @@ *
  *
- * Each validation rules is a function which returns a visitor
+ * Each validation rule is a function that returns a visitor
  * (see the language/visitor API). Visitor methods are expected to return
@@ -53,8 +59,56 @@ * GraphQLErrors, or Arrays of GraphQLErrors when invalid.
  * Attackers can send pathologically invalid queries to induce a DoS attack,
- * so by default `maxErrors` set to 100 errors.
+ * so `maxErrors` defaults to 100 errors.
  *
  * Optionally a custom TypeInfo instance may be provided. If not provided, one
  * will be created from the provided schema.
+ * @param schema - Schema to validate against.
+ * @param documentAST - Document AST to validate.
+ * @param rules - Validation rules to apply.
+ * @param options - Validation options, including error limits.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @returns Validation errors, or an empty array when the document is valid.
+ * @example
+ * ```ts
+ * // Validate with the default specified rules.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * validate(schema, parse('{ greeting }')); // => []
+ *
+ * const errors = validate(schema, parse('{ missing }'));
+ * errors[0].message; // => 'Cannot query field "missing" on type "Query".'
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a custom rule list, TypeInfo, and validation options.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, TypeInfo } from 'graphql/utilities';
+ * import { FieldsOnCorrectTypeRule, validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ missingOne missingTwo }');
+ *
+ * const errors = validate(
+ *   schema,
+ *   document,
+ *   [FieldsOnCorrectTypeRule],
+ *   { maxErrors: 1 },
+ *   new TypeInfo(schema),
+ * );
+ *
+ * errors.length; // => 2
+ * errors[1].message; // => 'Too many validation errors, error limit reached. Validation aborted.'
+ * ```
  */
-
 function validate(
@@ -65,3 +119,7 @@ schema,
   options,
-  /** @deprecated will be removed in 17.0.0 */
+  /**
+   * Deprecated TypeInfo instance used to track traversal state during
+   * validation. Omit this argument so validate creates the TypeInfo instance.
+   * @deprecated will be removed in 17.0.0
+   */
   typeInfo = new _TypeInfo.TypeInfo(schema),
@@ -120,5 +178,3 @@ ) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -125,0 +181,0 @@ function validateSDL(

validation/validate.mjs

@@ -0,1 +1,2 @@
+/** @category Validation */
 import { devAssert } from '../jsutils/devAssert.mjs';
@@ -19,2 +20,7 @@ import { mapValue } from '../jsutils/mapValue.mjs';
 /**
+ * Options used when validating a GraphQL document.
+ * @internal
+ */
+
+/**
  * Implements the "Validation" section of the spec.
@@ -28,3 +34,3 @@ *
  *
- * Each validation rules is a function which returns a visitor
+ * Each validation rule is a function that returns a visitor
  * (see the language/visitor API). Visitor methods are expected to return
@@ -35,8 +41,56 @@ * GraphQLErrors, or Arrays of GraphQLErrors when invalid.
  * Attackers can send pathologically invalid queries to induce a DoS attack,
- * so by default `maxErrors` set to 100 errors.
+ * so `maxErrors` defaults to 100 errors.
  *
  * Optionally a custom TypeInfo instance may be provided. If not provided, one
  * will be created from the provided schema.
+ * @param schema - Schema to validate against.
+ * @param documentAST - Document AST to validate.
+ * @param rules - Validation rules to apply.
+ * @param options - Validation options, including error limits.
+ * @param typeInfo - TypeInfo instance to update during traversal.
+ * @returns Validation errors, or an empty array when the document is valid.
+ * @example
+ * ```ts
+ * // Validate with the default specified rules.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema } from 'graphql/utilities';
+ * import { validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ *
+ * validate(schema, parse('{ greeting }')); // => []
+ *
+ * const errors = validate(schema, parse('{ missing }'));
+ * errors[0].message; // => 'Cannot query field "missing" on type "Query".'
+ * ```
+ * @example
+ * ```ts
+ * // This variant uses a custom rule list, TypeInfo, and validation options.
+ * import { parse } from 'graphql/language';
+ * import { buildSchema, TypeInfo } from 'graphql/utilities';
+ * import { FieldsOnCorrectTypeRule, validate } from 'graphql/validation';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting: String
+ *   }
+ * `);
+ * const document = parse('{ missingOne missingTwo }');
+ *
+ * const errors = validate(
+ *   schema,
+ *   document,
+ *   [FieldsOnCorrectTypeRule],
+ *   { maxErrors: 1 },
+ *   new TypeInfo(schema),
+ * );
+ *
+ * errors.length; // => 2
+ * errors[1].message; // => 'Too many validation errors, error limit reached. Validation aborted.'
+ * ```
  */
-
 export function validate(
@@ -47,3 +101,7 @@ schema,
   options,
-  /** @deprecated will be removed in 17.0.0 */
+  /**
+   * Deprecated TypeInfo instance used to track traversal state during
+   * validation. Omit this argument so validate creates the TypeInfo instance.
+   * @deprecated will be removed in 17.0.0
+   */
   typeInfo = new TypeInfo(schema),
@@ -100,5 +158,3 @@ ) {
 }
-/**
- * @internal
- */
+/** @internal */
 
@@ -105,0 +161,0 @@ export function validateSDL(

validation/ValidationContext.d.ts

@@ -0,1 +1,2 @@
+/** @category Validation Context */
 import type { Maybe } from '../jsutils/Maybe';
@@ -36,2 +37,4 @@ import type { GraphQLError } from '../error/GraphQLError';
  * validation rule.
+ *
+ * @internal
  */
@@ -54,5 +57,7 @@ export declare class ASTValidationContext {
 }
+/** @internal */
 export declare type ASTValidationRule = (
   context: ASTValidationContext,
 ) => ASTVisitor;
+/** @internal */
 export declare class SDLValidationContext extends ASTValidationContext {
@@ -68,5 +73,7 @@ private _schema;
 }
+/** @internal */
 export declare type SDLValidationRule = (
   context: SDLValidationContext,
 ) => ASTVisitor;
+/** Validation context passed to query validation rules. */
 export declare class ValidationContext extends ASTValidationContext {
@@ -77,2 +84,35 @@ private _schema;
   private _recursiveVariableUsages;
+  /**
+   * Creates a ValidationContext instance.
+   * @param schema - Schema used to validate the document.
+   * @param ast - Document AST being validated.
+   * @param typeInfo - TypeInfo instance used to track traversal state.
+   * @param onError - Callback invoked for each validation error.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const errors = [];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   (error) => errors.push(error),
+   * );
+   *
+   * context.reportError(new GraphQLError('Example validation error.'));
+   *
+   * context.getSchema(); // => schema
+   * errors[0].message; // => 'Example validation error.'
+   * ```
+   */
   constructor(
@@ -84,18 +124,377 @@ schema: GraphQLSchema,
   );
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * Returns the schema being used by this validation context.
+   * @returns The schema being validated against.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const context = new ValidationContext(
+   *   schema,
+   *   parse('{ greeting }'),
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * context.getSchema().getQueryType()?.name; // => 'Query'
+   * ```
+   */
   getSchema(): GraphQLSchema;
+  /**
+   * Returns variable usages found directly within this node.
+   * @param node - The AST node to inspect or visit.
+   * @returns Variable usages found directly within this node.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting(name: String): String
+   *   }
+   * `);
+   * const document = parse('query ($name: String) { greeting(name: $name) }');
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getVariableUsages(operation);
+   *
+   * usages[0].node.name.value; // => 'name'
+   * String(usages[0].type); // => 'String'
+   * ```
+   */
   getVariableUsages(node: NodeWithSelectionSet): ReadonlyArray<VariableUsage>;
+  /**
+   * Returns variable usages for an operation, including variables used by referenced fragments.
+   * @param operation - Operation definition to inspect.
+   * @returns Variable usages reachable from the operation.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name(prefix: String): String
+   *   }
+   * `);
+   * const document = parse(`
+   *   query ($prefix: String) {
+   *     viewer {
+   *       ...UserName
+   *     }
+   *   }
+   *
+   *   fragment UserName on User {
+   *     name(prefix: $prefix)
+   *   }
+   * `);
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getRecursiveVariableUsages(operation);
+   *
+   * usages.map((usage) => usage.node.name.value); // => ['prefix']
+   * ```
+   */
   getRecursiveVariableUsages(
     operation: OperationDefinitionNode,
   ): ReadonlyArray<VariableUsage>;
+  /**
+   * Returns the current output type at this point in traversal.
+   * @returns The current output type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let typeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       typeName = String(context.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * typeName; // => 'String'
+   * ```
+   */
   getType(): Maybe<GraphQLOutputType>;
+  /**
+   * Returns the current parent composite type.
+   * @returns The current parent composite type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       parentTypeName = context.getParentType()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypeName; // => 'Query'
+   * ```
+   */
   getParentType(): Maybe<GraphQLCompositeType>;
+  /**
+   * Returns the current input type at this point in traversal.
+   * @returns The current input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let inputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       inputTypeName = String(context.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypeName; // => 'Int'
+   * ```
+   */
   getInputType(): Maybe<GraphQLInputType>;
+  /**
+   * Returns the parent input type for the current input position.
+   * @returns The parent input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(filter: { stars: 5 }) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentInputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: () => {
+   *       parentInputTypeName = String(context.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypeName; // => 'ReviewFilter'
+   * ```
+   */
   getParentInputType(): Maybe<GraphQLInputType>;
+  /**
+   * Returns the current field definition.
+   * @returns The current field definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let fieldName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = context.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
   getFieldDef(): Maybe<GraphQLField<unknown, unknown>>;
+  /**
+   * Returns the current directive definition.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting @include(if: true) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let directiveName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = context.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
   getDirective(): Maybe<GraphQLDirective>;
+  /**
+   * Returns the current argument definition.
+   * @returns The current argument definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let argumentName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = context.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
   getArgument(): Maybe<GraphQLArgument>;
+  /**
+   * Returns the current enum value definition.
+   * @returns The current enum value definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(sort: OLDEST) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let enumValueName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = context.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
   getEnumValue(): Maybe<GraphQLEnumValue>;
 }
+/** A function that creates an AST visitor for validating a GraphQL document. */
 export declare type ValidationRule = (context: ValidationContext) => ASTVisitor;
 export {};

validation/ValidationContext.js

@@ -17,2 +17,4 @@ 'use strict';
 
+/** @category Validation Context */
+
 /**
@@ -22,2 +24,4 @@ * An instance of this class is passed as the "this" context to all validators,
  * validation rule.
+ *
+ * @internal
  */
@@ -120,5 +124,7 @@ class ASTValidationContext {
 }
+/** @internal */
 
 exports.ASTValidationContext = ASTValidationContext;
 
+/** @internal */
 class SDLValidationContext extends ASTValidationContext {
@@ -138,6 +144,41 @@ constructor(ast, schema, onError) {
 }
+/** @internal */
 
 exports.SDLValidationContext = SDLValidationContext;
 
+/** Validation context passed to query validation rules. */
 class ValidationContext extends ASTValidationContext {
+  /**
+   * Creates a ValidationContext instance.
+   * @param schema - Schema used to validate the document.
+   * @param ast - Document AST being validated.
+   * @param typeInfo - TypeInfo instance used to track traversal state.
+   * @param onError - Callback invoked for each validation error.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const errors = [];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   (error) => errors.push(error),
+   * );
+   *
+   * context.reportError(new GraphQLError('Example validation error.'));
+   *
+   * context.getSchema(); // => schema
+   * errors[0].message; // => 'Example validation error.'
+   * ```
+   */
   constructor(schema, ast, typeInfo, onError) {
@@ -150,2 +191,6 @@ super(ast, onError);
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -155,2 +200,26 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns the schema being used by this validation context.
+   * @returns The schema being validated against.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const context = new ValidationContext(
+   *   schema,
+   *   parse('{ greeting }'),
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * context.getSchema().getQueryType()?.name; // => 'Query'
+   * ```
+   */
 
@@ -160,2 +229,32 @@ getSchema() {
   }
+  /**
+   * Returns variable usages found directly within this node.
+   * @param node - The AST node to inspect or visit.
+   * @returns Variable usages found directly within this node.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting(name: String): String
+   *   }
+   * `);
+   * const document = parse('query ($name: String) { greeting(name: $name) }');
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getVariableUsages(operation);
+   *
+   * usages[0].node.name.value; // => 'name'
+   * String(usages[0].type); // => 'String'
+   * ```
+   */
 
@@ -190,2 +289,45 @@ getVariableUsages(node) {
   }
+  /**
+   * Returns variable usages for an operation, including variables used by referenced fragments.
+   * @param operation - Operation definition to inspect.
+   * @returns Variable usages reachable from the operation.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name(prefix: String): String
+   *   }
+   * `);
+   * const document = parse(`
+   *   query ($prefix: String) {
+   *     viewer {
+   *       ...UserName
+   *     }
+   *   }
+   *
+   *   fragment UserName on User {
+   *     name(prefix: $prefix)
+   *   }
+   * `);
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getRecursiveVariableUsages(operation);
+   *
+   * usages.map((usage) => usage.node.name.value); // => ['prefix']
+   * ```
+   */
 
@@ -207,2 +349,33 @@ getRecursiveVariableUsages(operation) {
   }
+  /**
+   * Returns the current output type at this point in traversal.
+   * @returns The current output type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let typeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       typeName = String(context.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * typeName; // => 'String'
+   * ```
+   */
 
@@ -212,2 +385,33 @@ getType() {
   }
+  /**
+   * Returns the current parent composite type.
+   * @returns The current parent composite type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       parentTypeName = context.getParentType()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypeName; // => 'Query'
+   * ```
+   */
 
@@ -217,2 +421,33 @@ getParentType() {
   }
+  /**
+   * Returns the current input type at this point in traversal.
+   * @returns The current input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let inputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       inputTypeName = String(context.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypeName; // => 'Int'
+   * ```
+   */
 
@@ -222,2 +457,37 @@ getInputType() {
   }
+  /**
+   * Returns the parent input type for the current input position.
+   * @returns The parent input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(filter: { stars: 5 }) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentInputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: () => {
+   *       parentInputTypeName = String(context.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypeName; // => 'ReviewFilter'
+   * ```
+   */
 
@@ -227,2 +497,33 @@ getParentInputType() {
   }
+  /**
+   * Returns the current field definition.
+   * @returns The current field definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let fieldName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = context.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
 
@@ -232,2 +533,33 @@ getFieldDef() {
   }
+  /**
+   * Returns the current directive definition.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting @include(if: true) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let directiveName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = context.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
 
@@ -237,2 +569,33 @@ getDirective() {
   }
+  /**
+   * Returns the current argument definition.
+   * @returns The current argument definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let argumentName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = context.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
 
@@ -242,2 +605,38 @@ getArgument() {
   }
+  /**
+   * Returns the current enum value definition.
+   * @returns The current enum value definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(sort: OLDEST) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let enumValueName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = context.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
 
@@ -248,3 +647,4 @@ getEnumValue() {
 }
+/** A function that creates an AST visitor for validating a GraphQL document. */
 
 exports.ValidationContext = ValidationContext;

validation/ValidationContext.mjs

@@ -0,1 +1,2 @@
+/** @category Validation Context */
 import { Kind } from '../language/kinds.mjs';
@@ -9,2 +10,4 @@ import { visit } from '../language/visitor.mjs';
  * validation rule.
+ *
+ * @internal
  */
@@ -107,2 +110,5 @@ export class ASTValidationContext {
 }
+/** @internal */
+
+/** @internal */
 export class SDLValidationContext extends ASTValidationContext {
@@ -122,3 +128,39 @@ constructor(ast, schema, onError) {
 }
+/** @internal */
+
+/** Validation context passed to query validation rules. */
 export class ValidationContext extends ASTValidationContext {
+  /**
+   * Creates a ValidationContext instance.
+   * @param schema - Schema used to validate the document.
+   * @param ast - Document AST being validated.
+   * @param typeInfo - TypeInfo instance used to track traversal state.
+   * @param onError - Callback invoked for each validation error.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { GraphQLError } from 'graphql/error';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const errors = [];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   (error) => errors.push(error),
+   * );
+   *
+   * context.reportError(new GraphQLError('Example validation error.'));
+   *
+   * context.getSchema(); // => schema
+   * errors[0].message; // => 'Example validation error.'
+   * ```
+   */
   constructor(schema, ast, typeInfo, onError) {
@@ -131,2 +173,6 @@ super(ast, onError);
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
@@ -136,2 +182,26 @@ get [Symbol.toStringTag]() {
   }
+  /**
+   * Returns the schema being used by this validation context.
+   * @returns The schema being validated against.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const context = new ValidationContext(
+   *   schema,
+   *   parse('{ greeting }'),
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * context.getSchema().getQueryType()?.name; // => 'Query'
+   * ```
+   */
 
@@ -141,2 +211,32 @@ getSchema() {
   }
+  /**
+   * Returns variable usages found directly within this node.
+   * @param node - The AST node to inspect or visit.
+   * @returns Variable usages found directly within this node.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting(name: String): String
+   *   }
+   * `);
+   * const document = parse('query ($name: String) { greeting(name: $name) }');
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getVariableUsages(operation);
+   *
+   * usages[0].node.name.value; // => 'name'
+   * String(usages[0].type); // => 'String'
+   * ```
+   */
 
@@ -171,2 +271,45 @@ getVariableUsages(node) {
   }
+  /**
+   * Returns variable usages for an operation, including variables used by referenced fragments.
+   * @param operation - Operation definition to inspect.
+   * @returns Variable usages reachable from the operation.
+   * @example
+   * ```ts
+   * import { parse } from 'graphql/language';
+   * import { buildSchema, TypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     viewer: User
+   *   }
+   *
+   *   type User {
+   *     name(prefix: String): String
+   *   }
+   * `);
+   * const document = parse(`
+   *   query ($prefix: String) {
+   *     viewer {
+   *       ...UserName
+   *     }
+   *   }
+   *
+   *   fragment UserName on User {
+   *     name(prefix: $prefix)
+   *   }
+   * `);
+   * const operation = document.definitions[0];
+   * const context = new ValidationContext(
+   *   schema,
+   *   document,
+   *   new TypeInfo(schema),
+   *   () => {},
+   * );
+   *
+   * const usages = context.getRecursiveVariableUsages(operation);
+   *
+   * usages.map((usage) => usage.node.name.value); // => ['prefix']
+   * ```
+   */
 
@@ -188,2 +331,33 @@ getRecursiveVariableUsages(operation) {
   }
+  /**
+   * Returns the current output type at this point in traversal.
+   * @returns The current output type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let typeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       typeName = String(context.getType());
+   *     },
+   *   }),
+   * );
+   *
+   * typeName; // => 'String'
+   * ```
+   */
 
@@ -193,2 +367,33 @@ getType() {
   }
+  /**
+   * Returns the current parent composite type.
+   * @returns The current parent composite type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       parentTypeName = context.getParentType()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * parentTypeName; // => 'Query'
+   * ```
+   */
 
@@ -198,2 +403,33 @@ getParentType() {
   }
+  /**
+   * Returns the current input type at this point in traversal.
+   * @returns The current input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let inputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       inputTypeName = String(context.getInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * inputTypeName; // => 'Int'
+   * ```
+   */
 
@@ -203,2 +439,37 @@ getInputType() {
   }
+  /**
+   * Returns the parent input type for the current input position.
+   * @returns The parent input type, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   input ReviewFilter {
+   *     stars: Int
+   *   }
+   *
+   *   type Query {
+   *     reviews(filter: ReviewFilter): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(filter: { stars: 5 }) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let parentInputTypeName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     ObjectField: () => {
+   *       parentInputTypeName = String(context.getParentInputType());
+   *     },
+   *   }),
+   * );
+   *
+   * parentInputTypeName; // => 'ReviewFilter'
+   * ```
+   */
 
@@ -208,2 +479,33 @@ getParentInputType() {
   }
+  /**
+   * Returns the current field definition.
+   * @returns The current field definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let fieldName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Field: () => {
+   *       fieldName = context.getFieldDef()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * fieldName; // => 'greeting'
+   * ```
+   */
 
@@ -213,2 +515,33 @@ getFieldDef() {
   }
+  /**
+   * Returns the current directive definition.
+   * @returns The current directive definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     greeting: String
+   *   }
+   * `);
+   * const document = parse('{ greeting @include(if: true) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let directiveName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Directive: () => {
+   *       directiveName = context.getDirective()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * directiveName; // => 'include'
+   * ```
+   */
 
@@ -218,2 +551,33 @@ getDirective() {
   }
+  /**
+   * Returns the current argument definition.
+   * @returns The current argument definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   type Query {
+   *     reviews(limit: Int): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(limit: 5) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let argumentName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     Argument: () => {
+   *       argumentName = context.getArgument()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * argumentName; // => 'limit'
+   * ```
+   */
 
@@ -223,2 +587,38 @@ getArgument() {
   }
+  /**
+   * Returns the current enum value definition.
+   * @returns The current enum value definition, if known.
+   * @example
+   * ```ts
+   * import { parse, visit } from 'graphql/language';
+   * import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
+   * import { ValidationContext } from 'graphql/validation';
+   *
+   * const schema = buildSchema(`
+   *   enum Sort {
+   *     NEWEST
+   *     OLDEST
+   *   }
+   *
+   *   type Query {
+   *     reviews(sort: Sort): [String]
+   *   }
+   * `);
+   * const document = parse('{ reviews(sort: OLDEST) }');
+   * const typeInfo = new TypeInfo(schema);
+   * const context = new ValidationContext(schema, document, typeInfo, () => {});
+   * let enumValueName;
+   *
+   * visit(
+   *   document,
+   *   visitWithTypeInfo(typeInfo, {
+   *     EnumValue: () => {
+   *       enumValueName = context.getEnumValue()?.name;
+   *     },
+   *   }),
+   * );
+   *
+   * enumValueName; // => 'OLDEST'
+   * ```
+   */
 
@@ -229,1 +629,2 @@ getEnumValue() {
 }
+/** A function that creates an AST visitor for validating a GraphQL document. */

version.d.ts

@@ -1,8 +0,5 @@
-/**
- * A string containing the version of the GraphQL.js library
- */
+/** @category Version */
+/** A string containing the version of the GraphQL.js library */
 export declare const version: string;
-/**
- * An object containing the components of the GraphQL.js version string
- */
+/** An object containing the components of the GraphQL.js version string */
 export declare const versionInfo: Readonly<{
@@ -9,0 +6,0 @@ major: number;

version.js

@@ -7,12 +7,10 @@ 'use strict';
 exports.versionInfo = exports.version = void 0;
+
+/** @category Version */
 // Note: This file is autogenerated using "resources/gen-version.js" script and
 // automatically updated by "npm version" command.
 
-/**
- * A string containing the version of the GraphQL.js library
- */
-const version = '16.14.0';
-/**
- * An object containing the components of the GraphQL.js version string
- */
+/** A string containing the version of the GraphQL.js library */
+const version = '16.14.1';
+/** An object containing the components of the GraphQL.js version string */
 
@@ -23,5 +21,5 @@ exports.version = version;
   minor: 14,
-  patch: 0,
+  patch: 1,
   preReleaseTag: null,
 });
 exports.versionInfo = versionInfo;

version.mjs

@@ -0,11 +1,8 @@
+/** @category Version */
 // Note: This file is autogenerated using "resources/gen-version.js" script and
 // automatically updated by "npm version" command.
 
-/**
- * A string containing the version of the GraphQL.js library
- */
-export const version = '16.14.0';
-/**
- * An object containing the components of the GraphQL.js version string
- */
+/** A string containing the version of the GraphQL.js library */
+export const version = '16.14.1';
+/** An object containing the components of the GraphQL.js version string */
 
@@ -15,4 +12,4 @@ export const versionInfo = Object.freeze({
   minor: 14,
-  patch: 0,
+  patch: 1,
   preReleaseTag: null,
 });

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

2105472

47.51%

Lines of code

66601

50.06%

No dependency changes