graphql 16.14.0 → 16.14.1

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 = {

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

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

package/utilities/printSchema.mjs

@@ -1,3 +1,4 @@
+/** @category Schema Printing */
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
 import { isPrintableAsBlockString } from '../language/blockString.mjs';
@@ -18,6 +19,26 @@ import {
 import { isIntrospectionType } from '../type/introspection.mjs';
 import { isSpecifiedScalarType } from '../type/scalars.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) {
   return printFilteredSchema(
     schema,
@@ -25,6 +46,28 @@ export 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/
+ * ```
+ */
+
 export function printIntrospectionSchema(schema) {
   return printFilteredSchema(schema, isSpecifiedDirective, isIntrospectionType);
 }
@@ -85,6 +128,8 @@ function printSchemaDefinition(schema) {
  * ```
  *
  * When using this naming convention, the schema description can be omitted.
+ *
+ * @internal
  */
 
 function isSchemaOfCommonNames(schema) {
@@ -108,6 +153,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')
+ * ```
+ */
 
 export function printType(type) {
   if (isScalarType(type)) {