validatorjs-chain v1.8.1

ValidatorJSChain

Version 1.11

A framework-agnostic validator and sanitizer chain inspired by express-validator. Very useful for GraphQL resolvers! Experimental, still under development. Please report bugs so I can ignore them.

How to install

npm i validatorjs-chain

Basic usage

First, import the ValidatorJSChain object, and create an instance:

import ValidatorJSChain from `validatorjs-chain`;

const validatorJSChain = new ValidatorJSChain();

Now you can verify any variable using one or multiple validators.

All validators and sanitizers of validator.js can be used the same way as in express-validator. For more information, please refer to the documentation of validator.js.

In the following example we verify the value myEmailAddress if it's a correctly formed email, and then whether it's one of the authorized addresses:

const myEmailAddress = 'somedude@company.com';

const authorizedEmails = [
    'boss@company.com',
    'secretary@company.com',
    'somedude@company.com',
    'someotherdude@company.com'
]

validatorJSChain
  .setValue('myEmailAddress', myEmailAddress)
  .isEmail()
  .isIn(authorizedEmails);

console.log(validatorJSChain.errorCount);
console.log(validatorJSChain.results);

The output will be:

0
{
  "myEmailAddress": {
    "value": "somedude@company.com",
    "isEmail": {
      "error": false
    },
    "isIn": {
      "error": false
    }
  }
}

If you use the same validator multiple times, the results will be numbered with a postfix:

validatorJSChain
  .setValue('myEmailAddress', myEmailAddress)
  .isEmail()
  .isEmail()
  .isEmail()

Result:

{
  "email": {
    "value": "somedude@company.com",
    "isEmail_0": {
      "error": false
    },
    "isEmail_1": {
      "error": false
    },
    "isEmail_2": {
      "error": false
    },
  }
}

Sanitizers

As you can see in the previous example, the result returned by the .results getter contains a value field. This is holding the value passed to the chain, and every sanitizer will change it. Extract this value to update your original variables. For example:

const validatorChain = new ValidatorChain();
let myValue = '  This string is going to be trimmed  ';

validatorChain()
  .setValue('myValue', myValue)
  .trim()

myValue = validatorChain.results.myValue.value;
console.log('"' + myValue + '"');

This should output:

"This string is going to be trimmed"

Alternatively you can use the values property to get a key-value list of all values passed to the validator chain:

console.log(validatorChain.values);

Result:

{ myValue: 'This string is going to be trimmed' }

Note that validate.js validators only accept string values, and they will emit strings as well. ValidatorJSChain will convert any value passed to the chain to a string, and as a consequence, the corresponding value will be a string too. To change this, use type conversion sanitizers, like toInt():

validatorChain()
  setValue('myNumber', 1541)
  .isInt({ min: 1000, max: 2000 })
  .toInt()

Validating data structures

If you have to validate a JSON data structure, use the .setValue() method to go through each field.

const employee = {
    name: 'John Doe',
    office: 1541,
    email: "somedude@company.com"
}

validatorJSChain
    .clearResults()
    .setValue('name', employee.name)
    .isLength({ min: 6, max: 128 })
    .matches(/^[A-Z]{1}[a-z]{2,32}\s([A-Z]{1}[a-z]{0,32}(\.?)\s)?[A-Z]{1}[a-z]{2,32}$/g)

    .setValue('office', employee.office)
    .isInt({ min: 1, max: 2000 })

    .setValue('email', employee.email)
    .isEmail()
    .isIn(authorizedEmails);

    console.log(validatorJSChain.results);

Notice that we called clearResults() at the beginning of the chain. In case you're reusing the same ValidatorJSChain instance, this method must be called or the instance may retain previous results. See more about clearResults() in the method reference.

The above example will produce the following console output:

{
  "name": {
    "value": "John Doe",
    "isLength": {
      "error": false
    },
    "matches": {
      "error": false
    }
  },
  "office": {
    "vale": "1541",
    "isInt": {
      "error": false
    }
  },
  "email": {
    "value": "somedude@company.com",
    "isEmail": {
      "error": false
    },
    "isIn": {
      "error": false
    }
  }
}

As there were no validation errors, all error flags are false.

Inverting a validator

You can turn around a validator with the .not() method. The result of the next validator will be negated, meaning the error value will be false if the validator did not pass, and true if it did pass.

Example:

validatorJSChain
    .setValue('name', employee.name)
    .not()
    .equals('John Doe')

Output:

{
  "name": {
    "value": "John Doe",
    "equals": {
      "error": true
    }
  }
}

Error handling

If a validation error occurs, the chain will not stop executing. If you wish to stop it on errors, use the bail() method:

validatorJSChain
    .setValue('email', employee.email)
    .isLength({ min: 100, max: 128 })
    .bail()
    .isEmail()

In this case if isLength() finds an error, .isEmail() will not be executed, and it's not going to appear in the results.

Attention: .bail() shuts down the entire validation chain. Everything after .bail() will be ignored. There are two ways to change this.

Method 1: setting a new value with the optional unbail argument. For example:

validatorJSChain
    .setValue('email', employee.email)
    .isLength({ min: 100, max: 128 })
    .bail()
    .isEmail()
    .setValue('name', 'employee.email', true)
    .isLength({ min: 6, max: 128 })
    .matches(/^[A-Z]{1}[a-z]{2,32}\s([A-Z]{1}[a-z]{0,32}(\.?)\s)?[A-Z]{1}[a-z]{2,32}$/g)

Although .bail() will stop the execution of the chain, and .isEmail() will be ignored, .setValue() will "unbail" the chain, and execution continues normally.

Method 2: using the unbail() method:

validatorJSChain
    .setValue('email', employee.email)
    .isLength({ min: 100, max: 128 })
    .bail()
    .isEmail()
    .isIn(authorizedEmails)
    .unbail()
    .isLength({ min: 6, max: 128 })

If the first .isLength() validator fails, the following .isEmail() and .isIn() will not execute, but .unbail() restores the chain, and the second .isLength() will trigger again.

Custom error messages

If the simple error flag won't do, you can define custom error messages with the .withMessage() method.

validatorJSChain
    .setValue('email', 'totally not an email')
    .isEmail()
    .withMessage(value => {
        return `Invalid email address: "${value}"`;
    });

console.log(validatorJSChain.results)

Output:

{
  email: {
    value: "totally not an email",
    isEmail: {
      error: true,
      message: 'Invalid email address: "totally not an email"'
    }
  }
}

The function passed to withMessage() may return any data type, including objects or arrays.

Conditionals

Elements of the validator chain may be made conditional with the .if() method. The block ends with the .endif() method. In this example, the validators and sanitizers between these two will only run if the email address contains the substring 'company.com':

validatorJSChain
  .setValue('email', 'johndoe@company.com')
  .if(value => value.includes('company.com'))
  .toLowercase()
  .isEmail()
  .isIn(authorizedEmails)
  .endif()

It is also possible to compare the current value to other values in the validation chain. For example, you may want to validate an address. A US address requires a state to be specified, but a European address doesn't. Therefore a European address must have a null value for state, while an US address should have a string. Here is how to do it:

validatorJSChain
  .clearResults()
  
  //  Validate country - it should be a 2 character code
  .setValue('country', selectedCountry)
  .isIn(['us', 'fr', 'gr', 'hu', 'cz', 'ru', 'it', 'es', 'uk'])
  .withMessage('This is not a country we know')
  .bail()

  //  Validate state
  .setValue('state', selectedState)
  
  // Country is US
  .if((value, sanitized) => sanitized.country === 'us')
    .isIn['AL', 'AK', 'AZ', 'AR' ... ]
    .withMessage('Invalid state!')
    .bail()
  .endif()

  //  Country is not US
  .if((value, sanitized) => sanitized.country !== 'us')
    .isEmpty()
    .withMessage('This country has no states!')
    .bail()
  .endif()

Note that sanitized will only contain values that have been validated before. If you moved the state validator section before the country validators, sanitized would not have a .country node. If you want to validate your value against the user's raw input, you don't need sanitized.

Conditionals cannot be nested. An .endif() clears all conditions set previously.

Custom validators and sanitizers

User-defined validators and sanitizers can be created using the .custom() and .customSanitizer() methods.

A custom validator is a function that takes value as a parameter, representing the currently validated value, and returns a boolean value.

A custom sanitizer also takes value as parameter, and returns a string value.

validatorJSChain()
  .setValue('test', 'hahaha')
  .customSanitizer(value => value.replace(/ha/igm, 'he'))
  .custom(value => value.includes('he'))

Important: Built-in sanitizers always stringify your value. Custom sanitizers never do. The function you pass as a custom sanitizer always receives the value as it is when it gets there in the validation chain.

Also important: If you're working with non-primitive values, such as arrays or records, it's recommended to only use custom validators and sanitizers on them. Built-in validators and sanitizers always stringify their output.

Object reference

Properties

Methods