graphql-schema-utilities

A CLI tool to merge schema files, and validate operations against a GraphQL Schema.

Installation

npm install -g graphql-schema-utilities

Usage

Using the CLI tool

>> graphql-schema-utilities

The tool will first merge schema files and then validate the merged schema, throwing errors if the schema isn't valid and exit with exit code 1. If Schema is valid it will check each operation in the file glob by parsing the operation and validating it against the schema. If errors are found, they will be displayed by file name and exit with exit code 1.

Merging schema files

You can merge your schema files across different modules and directories. In this example, you have three different set of files in three different directories:

~/moduleMain/schemas/Root.graphql:
type Query;

~/module1/schemas/Book.graphql:
extend type Query {
  bookById(id: ID!): Book
}
    
type Book {
  id: ID!
  authorId: ID!
}
 
~/module2/schemas/User.graphql:
extend type Query {
  userById(id: ID!): User
}
    
type User {
  id: ID!
  name: String!
}

Running the CLI utility generates the merged schema file, Merged_schema.graphQL:


type Query {
   userById(id: ID!): User
   bookById(id: ID!): Book
 }
 
 type User {
   id: ID!
   name: String!
 }
 
 type Book {
   id: ID!
   authorId: ID!
 }

The CLI options:

Options:
  -V, --version               output the version number.
  -o, --output [pattern]      The file path where the merged schema will be outputted to.
  -s, --schema [pattern]      Use a glob path that would define all of your schema files to merge them into a valid schema. (default: "").
  -r, --rules [pattern]       The file path for your custom rules to validate your operations, and your merged schema. To learn abot how to write your custom rules: check the README.md file  (default: "").
  -p, --operations [pattern]  Use a glob that that contains your graphql operation files to test against the merged schema file. (default: "").
  -d, --includeDirectives     By default will NOT merge the directives, unless you added this flag.
  -h, --help                  output usage information.

How to merge the schema files:

>> graphql-schema-utilities -s "{./First_Directory/**/*.graphql,./Second_Directory/users/**/
*.graphql}"

That will merge all the schema files in both directories. Note that we are passing the directories as Glob.

How to validate your operations against your merged schema:

>> graphql-schema-utilities -s "{./First_Directory/**/*.graphql,./Second_Directory/users/**/
*.graphql}" -p "./path_to_directory/operations/*.graphql"

Note that the "./path_to_directory/operations/*.graphql" operations path is also using Glob.

How to add your custom validation rules:

These tools will use the validation rules as defined in graphql-js validation rules. But you can create your own validation rule. Here is an example for custom validation rule against your operation which validates that your operation name must be prefixed with Hawaii_ .

### file name: custom_rule.ts

import { GraphQLError } from 'graphql';

export function doesNotStartWithHawaii(operationName: string): string {
  return `"${operationName}" operation does not start with Hawaii_.`;
}

/**
 * Valid only if it starts with Hawaii_.
 * A GraphQL document is only valid if all defined operations starts with Hawaii_.
 */
export function OperationNameStartsWithHawaii(
  context: any,
): any {
  const knownOperationNames = Object.create(null);  
  return {
    OperationDefinition(node) {
      const operationName = node.name;
      if (operationName) {
        if (!operationName.value.startsWith('Hawaii_')) {
          
          context.reportError(
            new GraphQLError(
              doesNotStartWithHawaii(operationName.value)
            ),
          );
        } else {
          knownOperationNames[operationName.value] = operationName;
        }
      }
      return false;
    },
    FragmentDefinition: () => false,
  };
}

Then run the CLI with the rules option:

>> graphql-schema-utilities -s "{./First_Directory/**/*.graphql,./Second_Directory/users/**/
*.graphql}" -p "./path_to_directory/operations/*.graphql" -r "path/to/custom_rule.js"

Note:

1- We are referencing the .js file not the .ts.

2- The path here is NOT Glob, You can use either relative or absolute path.

To learn more about how to write your own custom validation rules against graphql schema or operation files: Validate method in graphql-js.

Merge and Validate programmatically

This tool can be used as a library for a JS app as well. you can call the mergeSchemas async using Promise.

const tools = require('graphql-schema-utilities');

const glob = "{./First_Directory/**/*.graphql,./Second_Directory/users/**/
  *.graphql}"
tools.mergeGQLSchemas(glob).then((schema) => {
  console.log('schema files were merged, and the valid schema is: ', schema)
})
  .catch((error) => {
    console.error(error)
  })

Validate operations using promises:

tools.mergeGQLSchemas('./schema/*.graphql').then((schema) => {
  tools.validateOperations('./queries/*.graphql', schema).then((results) => {
    console.log(results)
  })
})

Note: you must use quotes around each file glob or the utility will not work properly.

Development

Install dependencies with

npm install

Build

npm run build

Run test in watch mode

npm run test:watch

Contributing

Please help make this tool better. For more information take a look at CONTRIBUTING.md

License

Apache 2.0

Notes

This package was created based on a fork from graphql-validator that was developed by credit-karma.

mzyil/graphql-schema-utilities