`graphql/utilities`

The graphql/utilities entry point contains helpers for introspection, building and printing schemas, AST and value conversion, schema coordinates, schema comparison, type-aware visitors, and input coercion.

import { buildSchema, printSchema, coerceInputValue } from 'graphql/utilities';

The same exports are also available from the root graphql entry point.

Introspection Exports
Schema Build, Extend, Sort, and Print Exports
AST, Operation, and Type Utility Exports
Input Coercion and Literal Conversion Exports
Type Comparator Exports
Schema Coordinate Exports
Schema Change Exports
Operation Root and Name Helper Exports

Introspection Exports

Export	Kind	Description
`getIntrospectionQuery()`	Function	Builds the standard introspection query string with configurable options.
`introspectionFromSchema()`	Function	Executes introspection against a schema object and returns introspection data.
`buildClientSchema()`	Function	Builds a non-executable schema from introspection data.

Type export
`IntrospectionOptions`
`IntrospectionQuery`
`IntrospectionSchema`
`IntrospectionType`
`IntrospectionInputType`
`IntrospectionOutputType`
`IntrospectionScalarType`
`IntrospectionObjectType`
`IntrospectionInterfaceType`
`IntrospectionUnionType`
`IntrospectionEnumType`
`IntrospectionInputObjectType`
`IntrospectionTypeRef`
`IntrospectionInputTypeRef`
`IntrospectionOutputTypeRef`
`IntrospectionNamedTypeRef`
`IntrospectionListTypeRef`
`IntrospectionNonNullTypeRef`
`IntrospectionField`
`IntrospectionInputValue`
`IntrospectionEnumValue`
`IntrospectionDirective`

const query = getIntrospectionQuery({ descriptions: true });
const data = await graphql({ schema, source: query });
const clientSchema = buildClientSchema(data.data);

Schema Build, Extend, Sort, and Print Exports

Export	Kind	Description
`buildSchema()`	Function	Builds a schema from SDL source text.
`buildASTSchema()`	Function	Builds a schema from a parsed SDL document.
`BuildSchemaOptions`	Type	Options for building schemas from SDL.
`extendSchema()`	Function	Returns a schema extended with SDL definitions.
`lexicographicSortSchema()`	Function	Returns a copy of a schema sorted by name.
`printSchema()`	Function	Prints a schema as SDL.
`printType()`	Function	Prints one named type as SDL.
`printDirective()` New in v17	Function	Prints one directive definition as SDL.
`printIntrospectionSchema()`	Function	Prints the built-in introspection schema.

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);
 
console.log(printSchema(lexicographicSortSchema(schema)));

AST, Operation, and Type Utility Exports

Export	Kind	Description
`getOperationAST()`	Function	Gets the named operation from a document, or the only operation when no name is provided.
`typeFromAST()`	Function	Resolves a GraphQL type reference AST against a schema.
`concatAST()`	Function	Concatenates multiple documents into one document.
`separateOperations()`	Function	Splits a document into one document per operation.
`stripIgnoredCharacters()`	Function	Removes insignificant characters from a GraphQL document string.
`TypeInfo` Changed in v17	Class	Tracks current output type, parent type, input type, field, directive, argument, enum value, and default while visiting an AST.
`visitWithTypeInfo()`	Function	Wraps a visitor so it maintains a `TypeInfo` instance.
`TypedQueryDocumentNode`	Type	`DocumentNode` wrapper type carrying inferred result and variable types.

const typeInfo = new TypeInfo(schema);
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Field() {
      console.log(typeInfo.getType()?.toString());
    },
  }),
);

Input Coercion and Literal Conversion Exports

v17 splits coercion from diagnostics. coerceInputValue() and coerceInputLiteral() return a value or undefined, while validateInputValue() and validateInputLiteral() report detailed errors. valueFromAST() and astFromValue() remain for compatibility and are deprecated for removal in v18.

Export	Kind	Description
`coerceInputValue()` Changed in v17	Function	Coerces a JavaScript value for a GraphQL input type, returning `undefined` on failure.
`validateInputValue()` New in v17	Function	Validates a JavaScript value and reports every diagnostic through a callback.
`coerceInputLiteral()` New in v17	Function	Coerces a GraphQL value AST for a GraphQL input type, returning `undefined` on failure.
`validateInputLiteral()` New in v17	Function	Validates a GraphQL value AST and reports diagnostics through a callback.
`valueToLiteral()` New in v17	Function	Converts an external JavaScript input value to a GraphQL const value AST.
`replaceVariables()` New in v17	Function	Replaces variable nodes in a value AST with literal values from coerced variable maps.
`valueFromAST()` Deprecated in v17	Function	Deprecated literal coercion helper. Use `coerceInputLiteral()`.
`valueFromASTUntyped()`	Function	Converts a value AST to an untyped JavaScript value.
`astFromValue()` Deprecated in v17	Function	Deprecated value-to-AST helper. Use `valueToLiteral()`.

const errors = [];
validateInputValue(rawValue, inputType, (error, path) => {
  errors.push({ message: error.message, path });
});
 
if (errors.length === 0) {
  const value = coerceInputValue(rawValue, inputType);
}

Type Comparator Exports

Export	Kind	Description
`isEqualType()`	Function	Checks whether two GraphQL types are exactly equal.
`isTypeSubTypeOf()`	Function	Checks whether one type is a valid subtype of another in a schema.
`doTypesOverlap()`	Function	Checks whether two composite types can apply to the same runtime object.

Schema Coordinate Exports

Export	Kind	Description
`resolveSchemaCoordinate()`	Function	Resolves a schema coordinate string against a schema.
`resolveASTSchemaCoordinate()`	Function	Resolves a parsed schema coordinate AST against a schema.
`ResolvedSchemaElement`	Type	Union of named type, field, input field, enum value, argument, directive, and directive argument results.

const element = resolveSchemaCoordinate(schema, 'User.name');
 
if (element.kind === 'FIELD') {
  console.log(element.field.type.toString());
}

Schema Change Exports

findSchemaChanges() is the v17 schema comparison API and returns breaking, dangerous, and safe changes in one call. Legacy wrappers remain available for compatibility and are deprecated for removal in v18.

Export	Kind	Description
`findSchemaChanges()` New in v17	Function	Returns breaking, dangerous, and safe schema changes.
`findBreakingChanges()` Deprecated in v17	Function	Deprecated wrapper returning only breaking changes.
`findDangerousChanges()` Deprecated in v17	Function	Deprecated wrapper returning only dangerous changes.
`BreakingChangeType`	Const object and type	Breaking schema change categories.
`DangerousChangeType`	Const object and type	Potentially dangerous schema change categories.
`SafeChangeType` New in v17	Const object and type	Safe schema change categories.
`BreakingChange`	Type	Breaking change result shape.
`DangerousChange`	Type	Dangerous change result shape.
`SafeChange` New in v17	Type	Safe change result shape.

const changes = findSchemaChanges(oldSchema, newSchema);
 
for (const change of changes) {
  console.log(change.type, change.description);
}

Operation Root and Name Helper Exports

These helpers remain available in v17 for compatibility and are deprecated in favor of schema.getRootType(operation) and assertName().

Export	Kind	Description
`getOperationRootType()` Deprecated in v17	Function	Deprecated operation root lookup helper. Use `schema.getRootType(operation)`.
`assertValidName()` Deprecated in v17	Function	Deprecated name assertion helper. Use `assertName()` from `graphql/type`.
`isValidNameError()` Deprecated in v17	Function	Deprecated name validation helper. Use `assertName()` with normal error handling.

const rootType = getOperationRootType(schema, operation);
const safeName = assertValidName(candidateName);

graphql/type graphql/validation

graphql/utilities

Contents