@graphql-inspector/core

What is @graphql-inspector/core?

@graphql-inspector/core is a powerful tool for GraphQL schema management. It helps developers detect changes, validate schemas, and compare different versions of GraphQL schemas. This package is particularly useful for maintaining the integrity of GraphQL APIs over time.

What are @graphql-inspector/core's main functionalities?

Schema Comparison

This feature allows you to compare two GraphQL schemas and detect changes between them. The code sample demonstrates how to use the `diff` function to find differences between an old schema and a new schema.

const { diff } = require('@graphql-inspector/core');
const oldSchema = `type Query { hello: String }`;
const newSchema = `type Query { hello: String, goodbye: String }`;
const changes = diff(oldSchema, newSchema);
console.log(changes);

Schema Validation

This feature helps you validate a GraphQL schema to ensure it adheres to the GraphQL specification. The code sample shows how to use the `validate` function to check a schema for errors.

const { validate } = require('@graphql-inspector/core');
const schema = `type Query { hello: String }`;
const errors = validate(schema);
console.log(errors);

Schema Coverage

This feature allows you to check how well your GraphQL queries cover your schema. The code sample demonstrates how to use the `coverage` function to analyze the coverage of a schema based on provided documents.

const { coverage } = require('@graphql-inspector/core');
const schema = `type Query { hello: String }`;
const documents = [{ content: `{ hello }` }];
const result = coverage(schema, documents);
console.log(result);

Other packages similar to @graphql-inspector/core

graphql

The `graphql` package is the reference implementation of GraphQL for JavaScript. It provides the core functionality for building GraphQL schemas and executing queries. While it does not offer schema comparison or validation out of the box, it is a fundamental building block for any GraphQL-related tool.

graphql-tools

The `graphql-tools` package provides a set of utilities for building and manipulating GraphQL schemas. It includes features for schema stitching, mocking, and schema transformations. While it overlaps with some of the functionality of @graphql-inspector/core, it is more focused on schema construction and manipulation rather than inspection and validation.

apollo-server

The `apollo-server` package is a popular GraphQL server implementation that includes tools for schema creation, query execution, and performance monitoring. It provides some validation and schema management features, but its primary focus is on serving GraphQL APIs rather than inspecting and comparing schemas.

README

GraphQL Inspector

GraphQL Inspector ouputs a list of changes between two GraphQL schemas. Every change is precisely explained and marked as breaking, non-breaking or dangerous. It helps you validate documents and fragments against a schema and even find similar or duplicated types.

Features

Major features:

• Compares schemas
• Finds breaking or dangerous changes
• Validates documents against a schema
• Finds similar / duplicated types
• Schema coverage based on documents
• Serves a GraphQL server with faked data and GraphQL Playground

GraphQL Inspector has a CLI and also a programatic API, so you can use it however you want to and even build tools on top of it.

Installation

yarn add @graphql-inspector/core

Examples

import {
  diff,
  validate,
  similar,
  coverage,
  Change,
  InvalidDocument,
  SimilarMap,
  SchemaCoverage,
} from '@graphql-inspector/core';

// diff
const changes: Change[] = diff(schemaA, schemaB);
// validate
const invalid: InvalidDocument[] = validate(documentsGlob, schema);
// similar
const similar: SimilarMap = similar(schema, typename, threshold);
// coverage
const schemaCoverage: SchemaCoverage = coverage(schema, documents);
// ...

License

MIT © Kamil Kisiela

Changelog

v2.0.0

Read "New GraphQL Inspector" on our blog

• github put annotations of removed parts of schema on new schema #1414
• ci: improve UX #1413
• github schema change notifications on Slack, Discord and through Webhook.
• github action opt-out annotations
• github action opt-in forced success on breaking changes
• github action endpoint as source of schema
• github support multiple environments (production, preview etc)
• github remote interception of detected changes (schema check) via http
• github managing unrelated PRs separately
• action use original SHA, not SHA from pull_request event PR #1440
• github action assume valid schema to avoid missing directive definitions PR #1440
• cli ci fix --header and --token PR #1442
• cli ci BREAKING: don't use preceding comments as the description by default (--comments flag to enable comments) PR #1443
• github use SHA of the most recent commit on ref before the push PR #1448
• github send annotations in batches PR #1402
• github use failure instead of action_required - allows to call re-runs
• github reduce the number of GitHub API calls by batching file fetching calls PR #1460