Argument and Input validation
Scalars
The standard way to ensure that inputs and arguments are correct, such as an email
field that really contains a proper e-mail address, is to use custom scalars e.g. GraphQLEmail
from graphql-custom-types
. However, creating scalars for all single cases of data types (credit card number, base64, IP, URL) might be cumbersome.
That's why TypeGraphQL has built-in support for argument and input validation.
By default, we can use the class-validator
library and easily declare the requirements for incoming data (e.g. a number is in the range 0-255 or a password that is longer than 8 characters) thanks to the awesomeness of decorators.
We can also use other libraries or our own custom solution, as described in custom validators section.
class-validator
How to use
First we decorate the input/arguments class with the appropriate decorators from class-validator
.
So we take this:
@InputType()
export class RecipeInput {
@Field()
title: string;
@Field({ nullable: true })
description?: string;
}
...and turn it into this:
import { MaxLength, Length } from "class-validator";
@InputType()
export class RecipeInput {
@Field()
@MaxLength(30)
title: string;
@Field({ nullable: true })
@Length(30, 255)
description?: string;
}
And that's it! 😉
TypeGraphQL will automatically validate our inputs and arguments based on the definitions:
@Resolver(of => Recipe)
export class RecipeResolver {
@Mutation(returns => Recipe)
async addRecipe(@Arg("input") recipeInput: RecipeInput): Promise<Recipe> {
// you can be 100% sure that the input is correct
console.assert(recipeInput.title.length <= 30);
console.assert(recipeInput.description.length >= 30);
console.assert(recipeInput.description.length <= 255);
}
}
Of course, there are many more decorators we have access to, not just the simple @Length
decorator used in the example above, so take a look at the class-validator
documentation.
This feature is enabled by default. However, we can disable it if we must:
const schema = await buildSchema({
resolvers: [RecipeResolver],
validate: false, // disable automatic validation or pass the default config object
});
And we can still enable it per resolver's argument if we need to:
class RecipeResolver {
@Mutation(returns => Recipe)
async addRecipe(@Arg("input", { validate: true }) recipeInput: RecipeInput) {
// ...
}
}
The ValidatorOptions
object used for setting features like validation groups can also be passed:
class RecipeResolver {
@Mutation(returns => Recipe)
async addRecipe(
@Arg("input", { validate: { groups: ["admin"] } })
recipeInput: RecipeInput,
) {
// ...
}
}
Note that by default, the skipMissingProperties
setting of the class-validator
is set to true
because GraphQL will independently check whether the params/fields exist or not.
GraphQL will also check whether the fields have correct types (String, Int, Float, Boolean, etc.) so we don't have to use the @IsOptional
, @Allow
, @IsString
or the @IsInt
decorators at all!
However, when using nested input or arrays, we always have to use @ValidateNested()
decorator or { each: true }
option to make nested validation work properly.
Response to the Client
When a client sends incorrect data to the server:
mutation ValidationMutation {
addRecipe(
input: {
# too long!
title: "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
}
) {
title
creationDate
}
}
the ArgumentValidationError
will be thrown.
By default, the apollo-server
package from the bootstrap guide will format the error to match the GraphQLFormattedError
interface. So when the ArgumentValidationError
occurs, the client will receive this JSON with a nice validationErrors
property inside of extensions.exception
:
{
"errors": [
{
"message": "Argument Validation Error",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": ["addRecipe"],
"extensions": {
"code": "INTERNAL_SERVER_ERROR",
"exception": {
"validationErrors": [
{
"target": {
"title": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet"
},
"value": "Lorem ipsum dolor sit amet, Lorem ipsum dolor sit amet",
"property": "title",
"children": [],
"constraints": {
"maxLength": "title must be shorter than or equal to 30 characters"
}
}
],
"stacktrace": [
"Error: Argument Validation Error",
" at Object.<anonymous> (F:\\#Projekty\\type-graphql\\src\\resolvers\\validate-arg.ts:29:11)",
" at Generator.throw (<anonymous>)",
" at rejected (F:\\#Projekty\\type-graphql\\node_modules\\tslib\\tslib.js:105:69)",
" at processTicksAndRejections (internal/process/next_tick.js:81:5)"
]
}
}
}
],
"data": null
}
Of course we can also create our own custom implementation of the formatError
function provided in the ApolloServer
config options which will transform the GraphQLError
with a ValidationError
array in the desired output format (e.g. extensions.code = "ARGUMENT_VALIDATION_ERROR"
).
Example
To see how this works, check out the simple real life example.
Caveats
Even if we don't use the validation feature (and we have provided { validate: false }
option to buildSchema
), we still need to have class-validator
installed as a dev dependency in order to compile our app without errors using tsc
.
An alternative solution that allows to completely get rid off big class-validator
from our project's node_modules
folder is to suppress the error TS2307: Cannot find module 'class-validator'
TS error by providing "skipLibCheck": true
setting in tsconfig.json
.
Custom validator
We can also use other libraries than class-validator
together with TypeGraphQL.
To integrate it, all we need to do is to provide a custom function as validate
option in buildSchema
.
It receives two parameters:
argValue
which is the injected value of@Arg()
or@Args()
argType
which is a runtime type information (e.g.String
orRecipeInput
).
The validate
function can be async and should return nothing (void
) when validation passes or throw an error when validation fails.
So be aware of this while trying to wrap another library in validate
function for TypeGraphQL.
Example using decorators library for Joi validators (joiful
):
const schema = await buildSchema({
// ...other options
validate: argValue => {
// call joiful validate
const { error } = joiful.validate(argValue);
if (error) {
// throw error on failed validation
throw error;
}
},
});
Be aware that when using custom validator, the error won't be wrapped with
ArgumentValidationError
like for the built-inclass-validator
validation.
Example
To see how this works, check out the simple custom validation integration example.