@envelop/extended-validation

@envelop/extended-validation

Extended validation plugin adds support for writing GraphQL validation rules, that has access to all execute parameters, including variables.

While GraphQL supports fair amount of built-in validations, and validations could be extended, it's doesn't expose variables to the validation rules, since operation variables are not available during validate flow (it's only available through execution of the operation, after input/variables coercion is done).

This plugin runs before validate but allow developers to write their validation rules in the same way GraphQL ValidationRule is defined (based on a GraphQL visitor).

Getting Started

Start by installing the plugin:

yarn add @envelop/extended-validation

Then, use the plugin with your validation rules:

import { execute, parse, specifiedRules, subscribe, validate } from 'graphql'
import { envelop, useEngine } from '@envelop/core'
import { useExtendedValidation } from '@envelop/extended-validation'

const getEnveloped = envelop({
  plugins: [
    useEngine({ parse, validate, specifiedRules, execute, subscribe }),
    useExtendedValidation({
      rules: [
        /* ... your rules here  */
      ]
    })
  ]
})

To create your custom rules, implement the ExtendedValidationRule interface and return your GraphQL AST visitor.

For example:

import { ExtendedValidationRule } from '@envelop/extended-validation'

export const MyRule: ExtendedValidationRule = (validationContext, executionArgs) => {
  return {
    OperationDefinition: node => {
      // This will run for every executed Query/Mutation/Subscription
      // And now you also have access to the execution params like variables, context and so on.
      // If you wish to report an error, use validationContext.reportError or throw an exception.
    }
  }
}

Built-in Rules

Union Inputs: @oneOf

This directive provides validation for input types and implements the concept of union inputs. You can find the complete spec RFC here.

You can use union inputs either via a the SDL flow, by annotating types and fields with @oneOf or via the extensions field.

First, make sure to add that rule to your plugin usage:

import { execute, parse, specifiedRules, subscribe, validate } from 'graphql'
import { envelop, useEngine } from '@envelop/core'
import { OneOfInputObjectsRule, useExtendedValidation } from '@envelop/extended-validation'

const getEnveloped = envelop({
  plugins: [
    useEngine({ parse, validate, specifiedRules, execute, subscribe }),
    useExtendedValidation({
      rules: [OneOfInputObjectsRule]
    })
  ]
})

Schema Directive Flow

Make sure to include the following directive in your schema:

directive @oneOf on INPUT_OBJECT | FIELD_DEFINITION

Then, apply it to field definitions, or to a complete input type:

## Apply to entire input type
input FindUserInput @oneOf {
  id: ID
  organizationAndRegistrationNumber: GraphQLInt
}

## Or, apply to a set of input arguments

type Query {
  foo(id: ID, str1: String, str2: String): String @oneOf
}

Programmatic extensions flow

const GraphQLFindUserInput = new GraphQLInputObjectType({
  name: 'FindUserInput',
  fields: {
    id: {
      type: GraphQLID
    },
    organizationAndRegistrationNumber: {
      type: GraphQLInt
    }
  },
  extensions: {
    oneOf: true
  }
})

const Query = new GraphQLObjectType({
  name: 'Query',
  fields: {
    foo: {
      type: GraphQLString,
      args: {
        id: {
          type: GraphQLID
        },
        str1: {
          type: GraphQLString
        },
        str2: {
          type: GraphQLString
        }
      },
      extensions: {
        oneOf: true
      }
    }
  }
})