node-graphql-constraint-lambda

GraphQL constraint directive written in functional programming style. This directive provides declarative validation of GraphQL arguments.

Install

1yarn add node-graphql-constraint-lambda
2# or
3npm install node-graphql-constraint-lambda

Usage

Example GraphQL Schema:

1type Query {
2  createUser (
3    name: String! @constraint(minLength: 5, maxLength: 40)
4    emailAddr: String @constraint(format: "email")
5    otherEmailAddr: String @constraint(format: "email", differsFrom: "emailAddr")
6    age: Int @constraint(min: 18)
7  ): User
8}

Use the constraint from your code:

1// when using es6 modules
2import { constraint } from 'node-graphql-constraint-lambda'
3
4// when using commonjs
5const { constraint } = require('node-graphql-constraint-lambda')
6
7// ... initialize your typeDefs and resolvers here ...
8
9const server = new GraphQLServer({
10  typeDefs,
11  resolvers,
12  schemaDirectives: {
13    constraint
14  }
15  // ... additional graphql server config
16})
17// ... start your server

You may need to declare the directive in the schema:

1directive @constraint(
2  minLength: Int
3  maxLength: Int
4  startsWith: String
5  endsWith: String
6  contains: String
7  notContains: String
8  pattern: String
9  format: String
10  differsFrom: String
11  min: Float
12  max: Float
13  exclusiveMin: Float
14  exclusiveMax: Float
15  notEqual: Float
16) on ARGUMENT_DEFINITION

API

Available constraints

See stringValidators, numericValidators and formatValidator mapping in src/validators.js.

Available formats

We use some functions from the validator package. See format2fun mapping in src/validators.js.

Customization

Default behavoir

The following code shows how the constraint directive is configured with default behaviour:

1// this code:
2import { constraint } from 'node-graphql-constraint-lambda'
3
4// is equivalent to:
5import {
6  prepareConstraintDirective,
7  defaultValidationCallback,
8  defaultErrorMessageCallback
9} from 'node-graphql-constraint-lambda'
10
11const constraint = prepareConstraintDirective(
12  defaultValidationCallback, defaultErrorMessageCallback )
13

Custom error messages

Error messages are generated using a callback function that by default shows a generic error message. It is possible to change this behavior by implementing a custom callback similar to this one:

1const myErrorMessageCallback = ({ argName, cName, cVal, data }) =>
2  `Error at field ${argName} in constraint ${cName}:${cVal}, data=${data}`

You might also want to customize certain messages and to keep the default callback as a fallback for all other messages:

1const myErrorMessageCallback = input => {
2  const { argName, cName, cVal, data } = input
3  if (/* decide whether to show custom message */)
4    return "custom error message" // based on input
5  else
6    return defaultErrorMessageCallback(input)
7}
8
9const constraint = prepareConstraintDirective(
10  defaultValidationCallback, myErrorMessageCallback )

Custom validation functions

Also the validation functions are implemented through a callback function. The constraint directive comes with a set of useful defaults but if you want to add your own validator, it can be done as follows:

1import {
2  createValidationCallback,
3  prepareConstraintDirective,
4  defaultValidators } from 'node-graphql-constraint-lambda'
5
6// you can merge default validators with your own validator
7const myValidators = {
8  ...defaultValidators,
9
10  // your custom validator comes here
11  constraintName: constrintValue => dataToValidate => true/false
12
13  // Example: numerical pin codes of certain size `@constraint(pin:4)`
14  pin: size => code => length(code) === size && match(/[0-9]+/)(code)
15}
16
17const myValidationCallback = createValidationCallback(myValidators)
18
19// now you can create the constraint class
20const constraint = prepareConstraintDirective(
21  myValidationCallback, defaultErrorMessageCallback )

There is a special format validator that supports the following:

• @constraint(format: "email")
• @constraint(format: "base64")
• @constraint(format: "date")
• @constraint(format: "ipv4")
• @constraint(format: "ipv6")
• @constraint(format: "url")
• @constraint(format: "uuid")
• @constraint(format: "futuredate")
• @constraint(format: "pastdate")
• @constraint(format: "creditcard")

Let's say we want to extend it to support format: "uppercase" format that checks whether all characters are just uppercase letters:

1import {
2  formatValidator,
3  numericValidators,
4  format2fun,
5  stringValidators } from 'node-graphql-constraint-lambda'
6
7const customFormat2Fun = {
8  ...format2fun,
9
10  uppercase: x => match(/[A-Z]*/)(x)
11  // we could have omitted the `x` parameter due to currying in the
12  // `match` function from ramda
13}
14
15const validators = {
16  ...formatValidator(customFormat2Fun),
17  ...numericValidators,
18  ...stringValidators
19}
20
21// now you can create the constraint class
22const constraint = prepareConstraintDirective(
23  createValidationCallback(validators),
24  defaultErrorMessageCallback
25)
26