graphql-schema-diff

Diff GraphQL schemas to find differences between schema versions

Install

Install by typing

npm install @beforeyoubid/graphql-schema-diff

yarn add @beforeyoubid/graphql-schema-diff

Usage

You can use like the following:

import Schema from '@beforeyoubid/graphql-schema-diff';

const previousSchema = `.....`;
const currentSchema = `.....`;

const schema = new Schema(previousSchema, currentSchema);
const mismatches = await schema.compareSchemas();

Printing

You can print the schema values by using some of the print utils:

import Schema, { printType, printField } from '@beforeyoubid/graphql-schema-diff';

const previousSchema = `.....`;
const currentSchema = `.....`;

const schema = new Schema(previousSchema, currentSchema);
const mismatches = await schema.compareSchemas();

let msg = '';
if (mismatches.addedTypes.length > 0) {
  msg += ` - Added types: ${mismatches.addedTypes.map(printType('green')).map(tilde).join(', ')}`;
}
if (mismatches.removedTypes.length > 0) {
  msg += ` - Removed types: ${mismatches.removedTypes.map(printType('red')).map(tilde).join(', ')}`;
}
if (mismatches.addedFields.length > 0) {
  msg += ` - Added fields: ${mismatches.addedFields.map(printField('green')).map(tilde).join(', ')}`;
}
if (mismatches.removedFields.length > 0) {
  msg += ` - Removed fields: ${mismatches.removedFields.map(printField('red')).map(tilde).join(', ')}`;
}
console.log(msg);

Documentation

Config

config.showDeprecatedAlongsideRegularRemovals

The parameter showDeprecatedAlongsideRegularRemovals controls whether removed fields/types that were marked deprecated show in the removed mismatch outputs.

This defaults to false.

Schema class

The Schema class is instatiated with the following arguments:

  constructor(
    schemaOne: string | DocumentNode, // either a string of the schema, or a GraphQL document node
    schemaTwo: string | DocumentNode, // either a string of the schema, or a GraphQL document node
    config: Config // see config section above
  )

Schema.compareSchemas

This function will result in an object containing the mismatches between the two schema versions. This object is explained below in the mismatches section

Mismatches

Mismatches containes all the differences between the two schemas, typically these are outputted as the AST nodes returned by GraphQL when parsing these documents.

They contain the following properties:

Mismatches.addedTypes

addedTypes includes a list of GraphQL types added in the new schema. (either Object type) or Input type)

Mismatches.removedTypes

removedTypes includes a list of GraphQL types removed in the new schema. (either Object type or Input type)

This will not contain any types that were deprecated in the previous schema, unless the configuration value showDeprecatedAlongsideRegularRemovals is set to true.

Mismatches.removedDeprecatedFields

removedDeprecatedFields includes a list of GraphQL types removed in the new schema that were deprecated in the previous schema. (either Object type or Input type).

This is an array containing the type alongside the reason for deprecation as specified on the @deprecated directive.

Mismatches.typesMadeDeprecated

typesMadeDeprecated includes a list of types newly made deprecated alongside the reason for deprecation as specified on the @deprecated directive. (either Object type or Input type)

Mismatches.addedFields

addedFields includes a list of fields newly added to the new schema. This list includes the type that the field is attached to also

Mismatches.removedFields

removedFields includes a list of fields removed in the new schema. This list includes the type that the field is attached to also

This will not contain any fields that were deprecated in the previous schema, unless the configuration value showDeprecatedAlongsideRegularRemovals is set to true.

Mismatches.removedDeprecatedFields

removedDeprecatedFields includes a list of fields removed in the new schema that were deprecated in the last schema. This list includes the type that the field is attached to also.

Mismatches.fieldsMadeNotNull

fieldsMadeNotNull includes a list of fields that were made not-null in the new schema that were nullable in the last schema. This list includes the type that the field is attached to also.

Mismatches.addedScalars

addedScalars includes a list of scalars added in the new schema that were not in the previous schema.

Mismatches.removedScalars

removedScalars includes a list of scalars removed in the new schema that were in the previous schema.

Mismatches.fieldTypesChanged

fieldTypesChanged includes a list of fields that had their type changed (ie from Int to String) (either Object type or Input type)

Mismatches.addedArguments

addedArguments includes a list of arguments added to fields in the new schema that weren't in the previous schema.

The list of results includes the type and field the argument is attached to.

Mismatches.addedNotNullArguments

addedNotNullArguments includes a list of not null arguments added to fields in the new schema that weren't in the previous schema.

The list of results includes the type and field the argument is attached to.

Mismatches.removedArguments

removedArguments includes a list of arguments removed from fields in the new schema that were in the previous schema.

The list of results includes the type and field the argument is attached to.

Mismatches.argumentTypesChanged

argumentTypesChanged includes a list of arguments on fields that had their type changed between schema versions.

The list of results includes the type and field the argument is attached to.

Mismatches.argumentsMadeNotNull

argumentsMadeNotNull includes a list of arguments on fields that had their type made not null where it was previously nullable.

The list of results includes the type and field the argument is attached to.

Mismatches.argumentsMadeNullable

argumentsMadeNullable includes a list of arguments on fields that had their type made nullable where it was previously not null.

The list of results includes the type and field the argument is attached to.

Mismatches.typesChanged

typesChanged includes a list of types that had their type changed (ie from Input to Type or vice-versa).