graphql 16.14.0 → 16.14.1

package/utilities/findBreakingChanges.mjs

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

package/utilities/getIntrospectionQuery.d.ts

@@ -1,5 +1,7 @@
+/** @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 {
   /**
    * Whether to include descriptions in the introspection result.
@@ -49,25 +51,71 @@ export interface IntrospectionOptions {
 /**
  * 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
+ * ```
  */
 export declare function getIntrospectionQuery(
   options?: IntrospectionOptions,
 ): 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 =
   | IntrospectionScalarType
   | IntrospectionObjectType
@@ -75,82 +123,132 @@ export declare type IntrospectionType =
   | IntrospectionUnionType
   | IntrospectionEnumType
   | IntrospectionInputObjectType;
+/** An introspection type that can appear in output position. */
 export declare type IntrospectionOutputType =
   | IntrospectionScalarType
   | IntrospectionObjectType
   | IntrospectionInterfaceType
   | IntrospectionUnionType
   | IntrospectionEnumType;
+/** An introspection type that can appear in input position. */
 export declare type IntrospectionInputType =
   | IntrospectionScalarType
   | IntrospectionEnumType
   | 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<
     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<
     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<
     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 =
   | IntrospectionNamedTypeRef
   | IntrospectionListTypeRef
   | IntrospectionNonNullTypeRef<
       IntrospectionNamedTypeRef | IntrospectionListTypeRef
     >;
+/** An introspection type reference that can appear in output position. */
 export declare type IntrospectionOutputTypeRef =
   | IntrospectionNamedTypeRef<IntrospectionOutputType>
   | IntrospectionListTypeRef<IntrospectionOutputTypeRef>
@@ -158,6 +256,7 @@ export declare type IntrospectionOutputTypeRef =
       | IntrospectionNamedTypeRef<IntrospectionOutputType>
       | IntrospectionListTypeRef<IntrospectionOutputTypeRef>
     >;
+/** An introspection type reference that can appear in input position. */
 export declare type IntrospectionInputTypeRef =
   | IntrospectionNamedTypeRef<IntrospectionInputType>
   | IntrospectionListTypeRef<IntrospectionInputTypeRef>
@@ -165,40 +264,73 @@ export declare type IntrospectionInputTypeRef =
       | IntrospectionNamedTypeRef<IntrospectionInputType>
       | IntrospectionListTypeRef<IntrospectionInputTypeRef>
     >;
+/**
+ * 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>;
 }

package/utilities/getIntrospectionQuery.js

@@ -5,9 +5,49 @@ Object.defineProperty(exports, '__esModule', {
 });
 exports.getIntrospectionQuery = getIntrospectionQuery;
 
+/** @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
+ * ```
  */
 function getIntrospectionQuery(options) {
   const optionsWithDefault = {
@@ -136,3 +176,4 @@ ${indent}}`;
     }
   `;
 }
+/** The result shape returned by a full introspection query. */

package/utilities/getIntrospectionQuery.mjs

@@ -1,6 +1,46 @@
+/** @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
+ * ```
  */
 export function getIntrospectionQuery(options) {
   const optionsWithDefault = {
@@ -129,3 +169,4 @@ ${indent}}`;
     }
   `;
 }
+/** The result shape returned by a full introspection query. */

package/utilities/getOperationAST.d.ts

@@ -1,9 +1,24 @@
+/** @category Operations */
 import type { Maybe } from '../jsutils/Maybe';
 import type { DocumentNode, OperationDefinitionNode } from '../language/ast';
 /**
  * Returns an operation AST given a document AST and optionally an operation
  * name. If a name is not provided, an operation is only returned if only one is
  * 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
+ * ```
  */
 export declare function getOperationAST(
   documentAST: DocumentNode,

package/utilities/getOperationAST.js

@@ -7,10 +7,26 @@ exports.getOperationAST = getOperationAST;
 
 var _kinds = require('../language/kinds.js');
 
+/** @category Operations */
+
 /**
  * Returns an operation AST given a document AST and optionally an operation
  * name. If a name is not provided, an operation is only returned if only one is
  * 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
+ * ```
  */
 function getOperationAST(documentAST, operationName) {
   let operation = null;

package/utilities/getOperationAST.mjs

@@ -1,8 +1,23 @@
+/** @category Operations */
 import { Kind } from '../language/kinds.mjs';
 /**
  * Returns an operation AST given a document AST and optionally an operation
  * name. If a name is not provided, an operation is only returned if only one is
  * 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
+ * ```
  */
 
 export function getOperationAST(documentAST, operationName) {

package/utilities/getOperationRootType.d.ts

@@ -1,3 +1,4 @@
+/** @category Operations */
 import type {
   OperationDefinitionNode,
   OperationTypeDefinitionNode,
@@ -5,8 +6,24 @@ import type {
 import type { GraphQLObjectType } from '../type/definition';
 import type { GraphQLSchema } from '../type/schema';
 /**
- * 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
  */
 export declare function getOperationRootType(

package/utilities/getOperationRootType.js

@@ -7,9 +7,27 @@ exports.getOperationRootType = getOperationRootType;
 
 var _GraphQLError = require('../error/GraphQLError.js');
 
+/** @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
  */
 function getOperationRootType(schema, operation) {

package/utilities/getOperationRootType.mjs

@@ -1,8 +1,25 @@
+/** @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
  */
 export function getOperationRootType(schema, operation) {

package/utilities/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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';
 export type {
   IntrospectionOptions,