graphql 16.13.2 → 16.14.1

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,

package/utilities/index.mjs

@@ -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
+ */
 // Produce the GraphQL query recommended for a full schema introspection.
 export { getIntrospectionQuery } from './getIntrospectionQuery.mjs';
 // Gets the target Operation from a Document.

package/utilities/introspectionFromSchema.d.ts

@@ -1,3 +1,4 @@
+/** @category Introspection */
 import type { GraphQLSchema } from '../type/schema';
 import type {
   IntrospectionOptions,
@@ -11,6 +12,59 @@ import type {
  *
  * This is the inverse of buildClientSchema. The primary use case is outside
  * 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
+ * ```
  */
 export declare function introspectionFromSchema(
   schema: GraphQLSchema,

package/utilities/introspectionFromSchema.js

@@ -13,6 +13,8 @@ var _execute = require('../execution/execute.js');
 
 var _getIntrospectionQuery = require('./getIntrospectionQuery.js');
 
+/** @category Introspection */
+
 /**
  * Build an IntrospectionQuery from a GraphQLSchema
  *
@@ -21,6 +23,59 @@ var _getIntrospectionQuery = require('./getIntrospectionQuery.js');
  *
  * This is the inverse of buildClientSchema. The primary use case is outside
  * 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
+ * ```
  */
 function introspectionFromSchema(schema, options) {
   const optionsWithDefaults = {
@@ -28,6 +83,7 @@ function introspectionFromSchema(schema, options) {
     directiveIsRepeatable: true,
     schemaDescription: true,
     inputValueDeprecation: true,
+    experimentalDirectiveDeprecation: true,
     oneOf: true,
     ...options,
   };

package/utilities/introspectionFromSchema.mjs

@@ -1,3 +1,4 @@
+/** @category Introspection */
 import { invariant } from '../jsutils/invariant.mjs';
 import { parse } from '../language/parser.mjs';
 import { executeSync } from '../execution/execute.mjs';
@@ -10,6 +11,59 @@ import { getIntrospectionQuery } from './getIntrospectionQuery.mjs';
  *
  * This is the inverse of buildClientSchema. The primary use case is outside
  * 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
+ * ```
  */
 
 export function introspectionFromSchema(schema, options) {
@@ -18,6 +72,7 @@ export function introspectionFromSchema(schema, options) {
     directiveIsRepeatable: true,
     schemaDescription: true,
     inputValueDeprecation: true,
+    experimentalDirectiveDeprecation: true,
     oneOf: true,
     ...options,
   };

package/utilities/lexicographicSortSchema.d.ts

@@ -1,8 +1,43 @@
+/** @category Schema Construction */
 import { GraphQLSchema } from '../type/schema';
 /**
  * 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
+ * // }
+ * ```
  */
 export declare function lexicographicSortSchema(
   schema: GraphQLSchema,

package/utilities/lexicographicSortSchema.js

@@ -21,10 +21,46 @@ var _introspection = require('../type/introspection.js');
 
 var _schema = require('../type/schema.js');
 
+/** @category Schema Construction */
+
 /**
  * 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
+ * // }
+ * ```
  */
 function lexicographicSortSchema(schema) {
   const schemaConfig = schema.toConfig();

package/utilities/lexicographicSortSchema.mjs

@@ -1,3 +1,4 @@
+/** @category Schema Construction */
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
 import { keyValMap } from '../jsutils/keyValMap.mjs';
@@ -26,6 +27,40 @@ import { GraphQLSchema } from '../type/schema.mjs';
  * 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
+ * // }
+ * ```
  */
 
 export function lexicographicSortSchema(schema) {

package/utilities/printSchema.d.ts

@@ -1,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;

package/utilities/printSchema.js

@@ -27,6 +27,27 @@ var _scalars = require('../type/scalars.js');
 
 var _astFromValue = require('./astFromValue.js');
 
+/** @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) {
   return printFilteredSchema(
     schema,
@@ -34,6 +55,27 @@ function printSchema(schema) {
     isDefinedType,
   );
 }
+/**
+ * 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/
+ * ```
+ */
 
 function printIntrospectionSchema(schema) {
   return printFilteredSchema(
@@ -102,6 +144,8 @@ function printSchemaDefinition(schema) {
  * ```
  *
  * When using this naming convention, the schema description can be omitted.
+ *
+ * @internal
  */
 
 function isSchemaOfCommonNames(schema) {
@@ -125,6 +169,28 @@ function isSchemaOfCommonNames(schema) {
 
   return true;
 }
+/**
+ * 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')
+ * ```
+ */
 
 function printType(type) {
   if ((0, _definition.isScalarType)(type)) {
@@ -286,6 +352,7 @@ function printDirective(directive) {
     'directive @' +
     directive.name +
     printArgs(directive.args) +
+    printDeprecated(directive.deprecationReason) +
     (directive.isRepeatable ? ' repeatable' : '') +
     ' on ' +
     directive.locations.join(' | ')