Validator.js Directives
A validator.js wrapper for GraphQL validation directive
Validation directive Example: @validate(method: METHOD[, OPTIONS])
is used to validate input values of GraphQL fields against specific rules defined in the directive.
import val from "@graphql-directive/validator"
import { makeExecutableSchema } from "@graphql-tools/schema"
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone"
const typeDefs = `
input UserInput {
name: String! @validate(method: LENGTH, max: 150)
email: String! @validate(method: EMAIL)
dateOfBirth: Date! @validate(method: BEFORE)
}
type Mutation {
addUser(user:UserInput!): Boolean!
}
`
const schema = val.transform(makeExecutableSchema({
typeDefs: [val.typeDefs, typeDefs],
resolvers: { /* resolvers */ }
}))
const server = new ApolloServer({ schema })
const { url } = await startStandaloneServer(server)
console.log(`Server running at ${url}`)
Validation Result
For each failed validation, server will throw GraphQLError
with message USER_INPUT_ERROR
. The detail error message can be seen in extension.error
property like below.
{
"data": {},
"errors": [
{
"message": "USER_INPUT_ERROR",
"extensions": {
"error": [
{
"message": "Must have a length within the specified range",
"path": "addUser.user.name"
},
{
"message": "Must be a valid email address",
"path": "addUser.user.email"
}
],
"code": "INTERNAL_SERVER_ERROR",
"stacktrace": [ ]
}
}
]
}
Custom Error Message
Currently its possible to create your own error message by providing the message on message
parameter like example below.
@validate(method: EMAIL, message: "Please provide a valid email address")
Validation Methods
The validation directive supports all of the validation functions in Validator.js. Below is a list of the supported methods and their respective parameters.
Method | Description | Parameters / Example Usage |
---|---|---|
AFTER |
Checks if a date is after a specified date. | Example: @validate(method: AFTER)
|
ALPHA |
Checks if a string contains only alphabetical characters. |
locale (optional): The locale to use for alphabet validation (defaults to en-US ). Example: @validate(method: ALPHA, locale: "id-ID")
|
ALPHANUMERIC |
Checks if a string contains only alphanumeric characters. |
locale (optional): The locale to use for alphabet validation (defaults to en-US ). Example: @validate(method: ALPHANUMERIC, locale: "id-ID")
|
ASCII |
Checks if a string contains only ASCII characters. | Example: @validate(method: ASCII)
|
BASE64 |
Checks if a string is a valid base64-encoded string. | Example: @validate(method: BASE64)
|
BEFORE |
Checks if a date is before a specified date. | Example: @validate(method: BEFORE)
|
BOOLEAN |
Checks if a value is a boolean (true or false ). |
Example: @validate(method: BOOLEAN)
|
CREDIT_CARD |
Checks if a string is a valid credit card number. | Example: @validate(method: CREDIT_CARD)
|
CURRENCY |
Checks if a string is a valid currency amount. |
symbol : The currency symbol to use (defaults to $ ).decimal : The decimal separator to use (defaults to . ).symbol_position : The position of the currency symbol (defaults to left ).negative_sign_before : Whether to put the negative sign before or after the currency symbol (defaults to false ).thousands_separator : The thousands separator to use (defaults to , ).allow_negative : Whether to allow negative currency amounts (defaults to false ). Example: @validate(method: CURRENCY, allow_negative: true)
|
DATA_URI |
Checks if a string is a valid data URI. | Example: @validate(method: DATA_URI)
|
DECIMAL |
Checks if a string is a valid decimal number. | Example: @validate(method: DECIMAL)
|
DIVISIBLE_BY |
Checks if a number is divisible by another number. |
number (required): The number to divide value by. Example: @validate(method: DIVISIBLE_BY, number: 3)
|
EMAIL |
Checks if a string is a valid email address. |
allow_display_name : Whether to allow the use of display names (defaults to false ).require_display_name : Whether to require the use of display names (defaults to false ).allow_utf8_local_part : Whether to allow non-ASCII characters in the local part of the email address (defaults to false ).require_tld : Whether to require a top-level domain (defaults to true ).ignore_max_length : Whether to ignore the maximum length of the email address (defaults to false ). Example: @validate(method: EMAIL, ignore_max_length: true)
|
ETHEREUM_ADDRESS |
Checks if a string is a valid Ethereum address. | Example: @validate(method: ETHEREUM_ADDRESS)
|
FQDN |
Checks if a string is a fully qualified domain name (FQDN). |
require_tld : Whether to require a top-level domain (defaults to true ).allow_underscores : Whether to allow underscores in domain names (defaults to false ).allow_trailing_dot : Whether to allow a trailing dot in domain names (defaults to false ). Example: @validate(method: FQDN)
|
FLOAT |
Checks if a string is a valid float. |
min : The minimum value the float can be (defaults to Number.MIN_VALUE ).max : The maximum value the float can be (defaults to Number.MAX_VALUE ).gt : The value the float must be greater than.lt : The value the float must be less than.locale : The locale to use for validation (defaults to en-US ). Example: @validate(method: FLOAT)
|
FULL_WIDTH |
Checks if a string contains any full-width characters. | Example: @validate(method: FULL_WIDTH)
|
HALF_WIDTH |
Checks if a string contains any half-width characters. | Example: @validate(method: HALF_WIDTH)
|
HEX_COLOR |
Checks if a string is a valid hexadecimal color code. | Example: @validate(method: HEX_COLOR)
|
HEXADECIMAL |
Checks if a string is a valid hexadecimal number. | Example: @validate(method: HEXADECIMAL)
|
IP |
Checks if a string is a valid IP address (version 4 or 6). |
version (optional): The IP version to validate against (4 or 6 , defaults to 4 ). Example: @validate(method: IP)
|
IP_RANGE |
Checks if a string is a valid IP range. | Example: @validate(method: IP_RANGE)
|
ISBN |
Checks if a string is a valid International Standard Book Number (ISBN). |
version (optional): The ISBN version to validate against (10 or 13 , defaults to 13 ). Example: @validate(method: ISBN)
|
ISIN |
Checks if a string is a valid International Securities Identification Number (ISIN). | Example: @validate(method: ISIN)
|
ISO8601 |
Checks if a string is a valid ISO 8601 date. | Example: @validate(method: ISO8601)
|
ISO31661_ALPHA2 |
Checks if a string is a valid ISO 3166-1 alpha-2 country code. | Example: @validate(method: ISO31661_ALPHA2)
|
ISO31661_ALPHA3 |
Checks if a string is a valid ISO 3166-1 alpha-3 country code. | Example: @validate(method: ISO31661_ALPHA3)
|
ISRC |
Checks if a string is a valid International Standard Recording Code (ISRC). | Example: @validate(method: ISRC)
|
ISSN |
Checks if a string is a valid International Standard Serial Number (ISSN). | Example: @validate(method: ISSN)
|
JSON |
Checks if a string is valid JSON. | Example: @validate(method: JSON)
|
JWT |
Checks if a string is a valid JSON Web Token (JWT). | Example: @validate(method: JWT)
|
LAT_LONG |
Checks if a string is a valid latitude-longitude coordinate pair. | Example: @validate(method: LAT_LONG)
|
LENGTH |
Checks if a string's length is within a specified range. |
min (optional): The minimum length of the string. max (optional): The maximum length of the string. Example: @validate(method: LENGTH)
|
LOWERCASE |
Checks if a string is all lowercase. | Example: @validate(method: LOWERCASE)
|
MAC_ADDRESS |
Checks if a string is a valid Media Access Control (MAC) address. | Example: @validate(method: MAC_ADDRESS)
|
MIME_TYPE |
Checks if a string is a valid MIME type. | Example: @validate(method: MIME_TYPE)
|
MONGO_ID |
Checks if a string is a valid MongoDB ObjectId. | Example: @validate(method: MONGO_ID)
|
MULTIBYTE |
Checks if a string contains any multibyte characters. | Example: @validate(method: MULTIBYTE)
|
NOT_EMPTY |
Checks if a string is not an empty string. | Example: @validate(method: NOT_EMPTY)
|
NUMERIC |
Checks if a string is a valid number. |
no_symbols (optional): If true, disallows symbols in the number (such as a leading plus or minus sign). Defaults to false. locale (optional): The locale to use when validating the number. Can be a string (such as "en-US") or an array of strings (such as ["en-US", "de-DE"]). Example: @validate(method: NUMERIC)
|
PORT |
Checks if a string is a valid port number. | Example: @validate(method: PORT)
|
POSTAL_CODE |
Checks if a string is a valid postal (ZIP) code for a given locale. |
locale (required): The locale to use when validating the postal code. Example: @validate(method: POSTAL_CODE, locale: "any")
|
REGEX |
Checks if a string matches a pattern. |
pattern (required): The pattern to match against. modifier : (Optional) The regex modifier. Example: @validate(method: REGEX, pattern: "^[a-zA-Z]", modifier: "i")
|
SLUG |
Checks if a string is a valid slug. | Example: @validate(method: SLUG)
|
STRONG_PASSWORD |
Checks if a string is a strong password. |
minLength (optional): The minimum length of the password. Defaults to 8. minLowercase (optional): The minimum number of lowercase letters. Defaults to 1. minUppercase (optional): The minimum number of uppercase letters. Defaults to 1. minNumbers (optional): The minimum number of digits. Defaults to 1. minSymbols (optional): The minimum number of symbols. Defaults to 1. Example: @validate(method: STRONG_PASSWORD)
|
SURROGATE_PAIR |
Checks if a string contains any surrogate pairs characters. | Example: @validate(method: SURROGATE_PAIR)
|
UPPERCASE |
Checks if a string is all uppercase. | Example: @validate(method: UPPERCASE)
|
URL |
Checks if a string is a valid URL. |
protocols (optional): An array of valid protocols (such as http or https ). Defaults to ['http', 'https', 'ftp'] . require_tld (optional): If true, requires a top-level domain (such as .com ). Defaults to true. require_protocol (optional): If true, requires a protocol (such as http ). Defaults to false. Example: @validate(method: URL)
|
UUID |
Checks if a string is a valid UUID. |
version (optional): The UUID version to validate against (such as 3 , 4 , or 5 ). Defaults to all versions. Example: @validate(method: UUID)
|
VARIABLE_WIDTH |
Checks if a string contains any full-width characters. | Example: @validate(method: VARIABLE_WIDTH)
|
WHITELISTED |
Checks if a string contains only whitelisted characters. |
chars (required): A string containing all allowed characters. Example: @validate(method: WHITELISTED, chars: "abcdefghijklkmopqrstuvwxyz")
|
Custom Valdiation
You can define your own custom validation logic by registering it on the transform function. First create your own custom validation logic with plugin
const customValidators: Plugins = {
phone: (val) => /^(\()?\d{3}(\))?(-|\s)?\d{3}(-|\s)\d{4}$/.test(val) || "Invalid phone number"
}
Keep in mind that the name (phone
) will be used to identify the plugin. Next step, register the plugin into the transformer.
const schema = val.transform(/* executable schema*/, { customValidators })
The final process, apply it on the @validate
directive like below
input UserInput {
phone: String! @validate(method: CUSTOM, validator: "phone")
}