GraphQL constraint directive ^+^

Allows using @constraint directive to validate GraphQL resolver input data.

Inspired by Constraints Directives RFC and OpenAPI

This library is an extension of graphql-constraint-directive

This library by default uses validator for string validation.

We include a test suite that covers using all constraint directives (See running tests), except for the List constraint validator (WIP).

If you add support for validating additional string formats (or other validations), please make sure to add tests to cover success/failure cases before making a PR.

Install

npm install graphql-constraint-directive-plus

Usage

const ConstraintDirective = require("graphql-constraint-directive-plus");
const express = require("express");
const bodyParser = require("body-parser");
const { graphqlExpress } = require("apollo-server-express");
const { makeExecutableSchema } = require("graphql-tools");
const typeDefs = `
  type Query {
    books: [Book]
  }
  type Book {
    title: String
  }
  type Mutation {
    createBook(input: BookInput): Book
  }
  input BookInput {
    title: String! @constraint(minLength: 5, format: "email")
  }`;
const schema = makeExecutableSchema({
  typeDefs,
  schemaDirectives: { constraint: ConstraintDirective }
});
const app = express();

app.use("/graphql", bodyParser.json(), graphqlExpress({ schema }));

Integrations

Syncing validation for:

• entity models (on mutation save)
• forms (on field change or submit)

You can use the constraints of this library with graphql-typeorm-validation to generate decorators for [class-validator] that can be used on any entity model, such as a TypeOrm entity

@Entity
class Person extends BaseEntity {
  @MinLength(2)
  @MaxLength(60)
  name: string;
}

Use this with a typeorm connection to build an entity class map, where each map entry is a model class with matching class-validator validation decorators applied.

The validation constraints are extracted via graphGenTypeorm from a GraphQL type definition

import { buildEntityClassMap } from "graphql-typeorm-validation";

const entityClassMap = buildEntityClassMap(connection);
const { Post } = entityClassMap;
// ...

First your createPost mutation resolver applies directive constraints on input object. It can then call createPostModel to create an in-memory Post model, validate it and then save it to the typeorm storage repository.

const createPostModel = async ({title, text}) {
  try {
    let postRepository = connection.getRepository("Post");
    let post = new Post();
    post.title = title;
    post.text = text;
    await validate(post, {
      // ... optional validation options
    });
    await postRepository.save(post);
    return post
  } catch (err) {
    handleError(`createPostModel failure: ${err.message}`, err)
  }
}

Mapping to general entity models

graphGenTypeorm uses graphSchemaToJson to first convert GraphQL type definitions (schema) to a Javascript object (JSON).

You could feed this schema object directly to the mapper.

This can be done using the decorate class API which lets you decorate any entity class with class-validator decorators.

Syncing validations with forms

You can further use the schema object to generate Yup form validations, using custom models in json-schema-to-yup.

Yup goes hand-in-glove with Formik, the amazing form builder. Ideally you would then also generate the form, mapping model/type fields to form fields...

We then need to use Yup addMethod to create additional Yup validators to match those available for the @constraint directive

const validator = require("validator");

Yup.addMethod(Yup.string, "isHexColor", function(args) {
  const { message } = args;
  return this.test("hex-color", message, function(value) {
    const { path, createError } = this;
    // [value] - value of the property being tested
    // [path]  - property name,
    // ...
    return validator.isHexColor(value) || createError({ path, message });
  });
});

With a little "trickery", you can sync your validations across:

• models
• mutation resolvers
• forms

Would love to see your contributions to make this dream into reality. Almost there!

API

String

minLength

@constraint(minLength: 5) Restrict to a minimum length

maxLength

@constraint(maxLength: 5) Restrict to a maximum length

startsWith

@constraint(startsWith: "foo") Ensure value starts with foo

endsWith

@constraint(endsWith: "foo") Ensure value ends with foo

contains

@constraint(contains: "foo") Ensure value contains foo

notContains

@constraint(notContains: "foo") Ensure value does not contain foo

pattern

@constraint(pattern: "^[0-9a-zA-Z]*$") Ensure value matches regex, e.g. alphanumeric

format

@constraint(format: "email") Ensure value is in a particular format

Supported formats:

• alpha-numeric
• alpha
• ascii
• byte
• credit-card
• currency-amount
• data-uri
• date-time
• date
• domain-name
• email
• hash
• hex-color
• ipv4
• ipv6
• isbn
• magnet-uri
• mime-type
• mobile-phone
• mongo-id
• postal-code
• uri
• uuid

Format validator options can be set as additional directive arguments:

@constraint(format: 'alpha-numeric', locale: 'en-US')

Format options available (with default values):

• alphaLocale (string)
• postalLocale (string)
• phoneLocale (string)
• hashAlgo (string)
• domainName (object)
• email (object)
• currency (object)

{
  locale: "en-US", // used by alpha, alphanumeric, postalCode and mobilePhone
  hashAlgo: "md5",
  domainName: {
    require_tld: true,
    allow_underscores: false,
    allow_trailing_dot: false
  },
  email: {
    allow_display_name: false,
    require_display_name: false,
    allow_utf8_local_part: true,
    require_tld: true,
    allow_ip_domain: false,
    domain_specific_validation: false
  },
  currency: {
    symbol: "$",
    require_symbol: false,
    allow_space_after_symbol: false,
    symbol_after_digits: false,
    allow_negatives: true,
    parens_for_negatives: false,
    negative_sign_before_digits: false,
    negative_sign_after_digits: false,
    allow_negative_sign_placeholder: false,
    thousands_separator: ",",
    decimal_separator: ".",
    allow_decimal: true,
    require_decimal: false,
    digits_after_decimal: [2],
    allow_space_after_digits: false
  }
}

Int/Float

min

@constraint(min: 3) Ensure value is greater than or equal to

max

@constraint(max: 3) Ensure value is less than or equal to

exclusiveMin

@constraint(exclusiveMin: 3) Ensure value is greater than

exclusiveMax

@constraint(exclusiveMax: 3) Ensure value is less than

multipleOf

@constraint(multipleOf: 10) Ensure value is a multiple

ConstraintDirectiveError

Each validation error throws a ConstraintDirectiveError. Combined with a formatError function, this can be used to customise error messages.

{
  code: 'ERR_GRAPHQL_CONSTRAINT_VALIDATION',
  fieldName: 'theFieldName',
  context: [ { arg: 'argument name which failed', value: 'value of argument' } ]
}

const formatError = function(error) {
  if (
    error.originalError &&
    error.originalError.code === "ERR_GRAPHQL_CONSTRAINT_VALIDATION"
  ) {
    // return a custom object
  }

  return error;
};

app.use("/graphql", bodyParser.json(), graphqlExpress({ schema, formatError }));

Customization

By default, the constraint directive uses validator.js

You can pass your own validator in the GraphQL context object, conforming to this API:

• isLength(value)
• contains(value)
• isAlphanumeric(value, locale)
• isAlpha(value, locale)
• isAscii(value)
• isByte(value)
• isCreditCard(value)
• isCurrency(value)
• isDataUri(value)
• isDateTime(value)
• isDate(value)
• isDomainName(value)
• isEmail(value)
• isHash(value)
• isHexColor(value)
• isIPv6(value)
• isIPv4(value)
• isIsbn(value)
• isMagnetUri(value)
• isMimeType(value)
• isMobilePhone(value, locale)
• isMongoId(value)
• `isPostalCode(value, countryCode)
• isUri(value)
• isUUID(value)

Note: All the above methods expect value to be a string.

The default validator is wrapped as follows:

const wrappedValidator = {
  // wrap your own validator using the same API
  isLength: validator.isLength,
  contains: validator.contains,

  isAlpha: validator.isAlpha,
  isAlphanumeric: validator.isAlphanumeric,
  isAscii: validator.isAscii,

  isByte: validator.isBase64,

  isCreditCard: validator.isCreditCard,
  isCurrency: validator.isCurrency,

  isDataUri: validator.isDataURI,
  isDateTime: validator.isRFC3339,
  isDate: validator.isISO8601,
  isDomainName: validator.isFQDN,

  isEmail: validator.isEmail,

  isHash: validator.isHash,
  isHexColor: validator.isHexColor,

  isIPv6: value => validator.isIP(value, 6),
  isIPv4: value => validator.isIP(value, 4),
  isIsbn: validator.isISBN,

  isMagnetUri: validator.isMagnetURI,
  isMobilePhone: validator.isMobilePhone,
  isMongoId: validator.isMongoId,
  isMimeType: validator.isMimeType,

  isPostalCode: validator.isPostalCode,

  isUri: validator.isURL,
  isUUID: validator.isUUID
};

Validation messages

You can set a validationError function map on the GraphQL context object to provide your own validator error handlers.

• format(key, value)
• `string(name, msg, args[])
• `number(name, msg, args[])

The format validators will call: validationError.format('date', value)

The string and number validators will call the error handler like this:

validationError.string(name, `Must match ${args.pattern}`, [
  { arg: "pattern", value: args.pattern }
]);

Note that the third argument contains a list where each object has an arg entry that indicates the constraint that failed. You can use this as a key to lookup in your own validation error message map to return or output a localized error message as you see fit.

Reusing validators

You can re-use the core validators as follows:

import {
  string,
  number,
  list
} from "graphql-constraint-directive/scalars/validate";
import { validationError } from "graphql-constraint-directive/scalars/error";
import { validator } from "graphql-constraint-directive/validator";

const field = "name";
const args = { minLength: 4, maxLength: 40 };
value = "John Smith";

string.validate(name, args, value, { validator, validationError });

Complex types

See Complex types

Development

Tests

Run npm run test:nolint to run all tests without linting

Resources

• GraphQL List - How to use arrays in GraphQL schema (GraphQL Modifiers)
• Deep dive into GraphQL type system
• Life of a GraphQL Query — Validation
• Graphql validated types

License

See License