Introduction

super-easy-validator a super simple npm package with zero dependency which helps in data validation in much simpler way. Its inspired by laravel validator, but even better. Its even more powerful than express-validator and zod.

Please write any issues on github if you found any. Don't hesitate to suggest any new features.

Useful Links

• How to install
• Usage
  • Basic usage step by step
    • Step 1: Creating Validation Rules
    • Step 2: Validating Data
    • Final Output
  • Data validation of request query in express GET API
• Guide
  • 1. Separators
  • 2. Data types
  • 3. Automatic String Check
  • 4. Automatic Number Check
  • 5. Optional and Nullable Values
  • 6. Argument based Validations
  • 7. Regular Expression Limitations
  • 8. Nested Object Validation
  • 9. Simple Array Validation
  • 10. Array Based Validation
  • 11. Error Options
  • 12. Strict Check
• API
  • Optional and Nullable Types
    • optional
    • nullable
    • $atleast
    • $atmost
  • Data Types
    • string
    • number
    • boolean
    • array
    • object
    • bigint
    • symbol
  • Specific String Types
    • email
    • url
    • domain
    • name
    • fullname
    • username
    • alpha
    • alphanumeric
    • phone
    • phonecode
    • mongoid
    • date
    • dateonly
    • time
    • lower
    • upper
    • ip
    • uuid
  • Specific Number Types
    • int
    • positive
    • negative
    • natural
    • whole
  • Argument Based Validations
    • equal
    • size
    • min
    • max
    • regex
    • decimalsize
    • decimalmin
    • decimalmax
    • enums
    • arrayof
  • Error Options
    • field
    • error
    • quotes config

How to install

Run this command in the root of your npm project

1npm i super-easy-validator

Usage

1. Basic Usage Step-By-Step

Suppose we need to validate the following data:

1const data = {

2  name: 'test123',

3  gender: 'Male',

4  adult: true,

5  id: '123e4567-e89b-12d3-a456-426655440000',

6  creditCard: '1987654312345678',

7  isMarried: 'no',

8  profile: 'example.com',

9  password: 'ab',

10  favoriteFoods: ['chicken', 'egg roll', 'french fries'],

11  rating: 4.5,

12  ratings: [3, 5, undefined, true, 5.67],

13  score: 234.5,

14  accountBalance: 100.345,

15  hash: 'a6g8d7Fkf9Du',

16  hash2: 'PDH78DI908g56',

17  serverIp: '8.45.23.0',

18  dob: '1996-01-10T23:50:00.0000+05:30',

19  time: '23:50',

20  address: {

21    pin: '829119',

22    city: 'Rock Port',

23    country: {

24      code: 'IN',
25    }
26  },

27  users: [
28    {

29      name: 'John Doe',

30      age: 20,

31      gender: 'male',
32    },
33    { }
34  ],

35  limit: '90',
36}

Here is the step by step guide to validate the above data using this package:

Step 1: Creating validations rules

At first we need to create the validation rules which is just a Record of key value pairs. This validation rules object will later be used for validating data.

1let rules = {
2  mail: 'optional|email',
3  phone: 'optional|phone',
4  $atleast: 'mail|phone',
5  $atmost: 'mail|phone|size:1',
6  name: 'name|field:person name',
7  gender: 'enums:male,female',
8  adult: 'enums:true,false',
9  id: 'uuid',
10  creditCard: 'string|regex:/^[0-9]{16}$/',
11  isMarried: 'boolean',
12  userId: 'mongoid',
13  profile: 'url',
14  password: 'string|min:3|max:15',
15  favoriteFoods: 'array|min:3|max:6',
16  rating: 'number|enums:1,2,3,4,5|error:rating is not correct, please fix it',
17  ratings: 'arrayof:optional|arrayof:natural|arrayof:max:5|field:ratingsList',
18  score: 'number|whole',
19  accountBalance: 'number|min:0|decimalsize:2',
20  hash: 'lower',
21  hash2: 'upper',
22  serverIp: 'ip',
23  dob: 'date',
24  time: 'time',
25  address: {
26    pin: 'string|natural|size:6',
27    city: 'name',
28    country: {
29      code: 'alpha|upper|size:2',
30    },
31  },
32  users: [
33    {
34      name: 'name',
35      age: 'natural',
36      gender: 'enums:male,female',
37    },
38  ],
39  person: 'object',
40  'person.address': 'string',
41  limit: 'optional|string|natural|min:100',
42}

Step 2: Validating data

Then, we can validate our data using the rules created in previous step:

1const Validator = require('super-easy-validator');
2
3let { errors } = Validator.validate(rules, data);
4if (errors) {
5  console.log(errors);
6}

Final output

This is how the final output should look like:

1[
2  'at least one of `mail` and `phone` is required',
3  '`person name` must be a valid name',
4  '`gender` is invalid',
5  '`isMarried` must be a valid boolean',
6  '`userId` is required',
7  '`profile` must be a valid url',
8  '`password` must have length of at least 3',
9  'rating is not correct, please fix it',
10  '`ratingsList[3]` must be a valid number',
11  '`ratingsList[4]` must be a valid natural number',
12  '`score` must be a valid whole number',
13  '`accountBalance` must have 2 decimal places',
14  '`hash` must not contains upper case letters',
15  '`hash2` must not contains lower case letters',
16  '`users[1].name` is required',
17  '`users[1].age` is required',
18  '`users[1].gender` is required',
19  '`person` is required',
20  '`person.address` is required',
21  '`limit` must be at least 100',
22]

NOTE: You could also have written:

1let { errors } = Validator.validate(rules, data, {quotes: 'backtick'});

If you want quotes to be added around each field names in error messages. For more info, see quotes API section.

2. Data Validation of request query in express

Suppose we need to validate some fields which are all present in req.query (request query) in express GET API. As you already know every fields in req.query is string. Also in most cases these fields are optional, so we have to make sure to consider these things before writing validation. Here is a proper example.

1const { validate } = require('super-easy-validator');
2
3function validateGetProducts(req, res, next) {
4  try {
5    let rules = {
6      limit: 'optional|string|natural|max:100',
7      page: 'optional|string|natural',
8      searchKey: 'optional|string|min:1',
9      productId: 'optional|mongoid',
10      withProduct: 'optional|string|boolean',
11      expiryMin: 'optional|date',
12      expiryMax: 'optional|date',
13      priceMin: 'optional|string|positive',
14      priceMax: 'optional|string|positive',
15      createdAtMin: 'optional|date',
16      createdAtMax: 'optional|date',
17      sortBy: 'optional|enums:expiry,price,createdAt',
18      sortOrder: 'optional|enums:ascending,descending',
19    }
20
21    const { errors } = validate(rules, req.query);
22    if(errors) {
23      return res.status(400).json({ message: errors[0] });
24    }
25
26    return next();
27  } catch (error) {
28    console.log(errors);
29    return res.status(500).json({ message: 'server error' })
30  }
31}

Here we have assumed every fields in request query to be optional and also we have added string check for each field.

You may have noticed that some fields like productId, expiryMin, createdAtMax, etc. don't have any string rule. This is because some rules like mongoid, date, enums: automatically checks for string. So you don't need to write string check explicitly there.

Guide

1. Separators

Validator.validate function requires the rules object having key-value pairs where keys are the names of the variables whose needs to be validated. Then the values are the rules in string format separated by pipe | operator without any spaces. You can give multiple rules for any value. e.g.

1let rules = {
2  name: `string|min:2|max:8`,
3};

In this example, we are giving 3 rules to the name field:

1. string: As the name says, it means, the name field must be string

2. min:2: The name field must be at least 2 characters long

3. max:8: The name field must be at most 8 characters long

Note: Instead of string validations with | separation you can also give validations in arrays. Here's an equivalent example for the same above rule

1let rules = {
2  name: ['string', 'min:2', 'max:8']
3}

Also note that array based rules works differently for $atleast and $atmost keyword. For more details see the API Section of $atleast and $atmost

2. Data Types

You can add the following data type check:

• string
• number
• boolean
• array
• object
• bigint
• symbol

NOTE: By using the combination of string and number you can check for numeric string validation. e.g. string|natural will check for natural number string. Same works for string and boolean as well.

3. Automatic String Check

In these cases, it will automatic check for string data type, and you don't need to explicitly add a string type check:

• name
• fullname
• phone
• phonecode
• email
• url
• domain
• username
• alpha
• alphanumeric
• mongoid
• uuid
• date
• dateonly
• time
• lower
• upper
• ip

4. Automatic Number Check

In these cases, it will automatic check for number data type, and you don't need to explicitly add a number type check:

• int
• positive
• negative
• natural
• whole

5. Optional and Nullable Values

Optional

By default, all the data validation is compulsory, if you want any data field to be optional (undefined or absent field), then make sure to add optional validation. e.g.

1let rules = {
2  phone: 'optional|phone',
3};

In this case, phone can be optional (means this field can be absent).

Nullable

If you want any field to be nullable , then use nullable validation, this make sure that the field can be null. e.g.

1let rules = {
2  spouse: 'nullable|name',
3};

Now, spouse can be null.

NOTE: In this above case spouse can't be undefined (its still required). If you want it to be both optional and nullable then use both:

1let rules = {
2  spouse: 'optional|nullable|name',
3};

Now, its not required and even can have null value.

Atleast

Some times it is required to have at least one field among the list of few optional fields. Let's say we have optional email and phone of a user but atleast one of them should always be present. In that case we can use $atleast, this will make sure we have atleast email or phone field. e.g.

1let rules = {
2  email: 'optional|email',
3  phone: 'optional|phone',
4  $atleast: 'email|phone'
5};

Suppose you want at least n number of fields to be present from a set of fields. You can achieve this using size: keyword. e.g.

1let rules = {
2  name: 'optional|name',
3  email: 'optional|email',
4  username: 'optional|username',
5  phone: 'optional|phone',
6  $atleast: 'name|email|username|phone|size:2'
7};

This example accepts 4 optional fields out of which any 2 is required.

See the API Section for the validation of more than one group of fields

Atmost

Some times it is required to have at most one field among the list of few optional fields. Let's say we have optional email and phone of a user but only one of them should be present not both. In that case we can use $atmost, this will make sure we have atmost one of email or phone field. e.g.

1let rules = {
2  email: 'optional|email',
3  phone: 'optional|phone',
4  $atmost: 'email|phone'
5};

Suppose you want at most n fields from a set of fields. You can achieve this using size: keyword. e.g.

1let rules = {
2  name: 'optional|name',
3  email: 'optional|email',
4  username: 'optional|username',
5  phone: 'optional|phone',
6  $atmost: 'name|email|username|phone|size:3'
7};

This example will accept only 3 fields from 4 optional fields. It will raise error if you try to give more than 3 fields among name, email, username, phone

See the API Section for the validation of more than one group of fields

6. Argument based Validations

It supports the following argument based validations (See API for more details):

• equal:<value>: equality check for string, number and boolean
• size:<int>: length check for strings and arrays and digits length check for numbers (or numeric strings)
• min:<value>: minimum length check for strings and arrays, minimum value check for numbers(or numeric strings) and date(date should be in ISO format)
• max:<value>: maximum length check for strings and arrays, maximum value check for numbers(or numeric strings) and date(date should be in ISO format)
• regex:<regex>: regular expressions check for strings
• decimalsize:<value>: check for exact number of digits after decimal points for numbers and numeric strings
• decimalmin:<value>: check for minimum number of digits after decimal points for numbers and numeric strings
• decimalmax:<value>: check for maximum number of digits after decimal points for numbers and numeric strings
• enums:<value>: check for enum values for strings, numbers and boolean
• arrayof:<validation>: check if each elements in the array follows the given <validation>. (It has its own separate section)

INFO: for more details and examples, see the API section.

LIMITATIONS: To know about the limitations of decimalsize:<value> , decimalmin:<value> and decimalmax:<value> , see the API section

7. Regular Expression Limitations

If string validations has regex which itself has | , then it will fail for validation. You can't use pipe operator | for regular expressions when using string based validation rules. In those cases, use array based rules instead. e.g.

ERROR: This will not work, as its regex has | operator:

1let rules = {
2  gender: 'string|regex:/^(male)|(female)$/',
3};

FIX: Instead use this:

1let rules = {
2  gender: ['string', 'regex:/^(male)|(female)$/'],
3};

8. Nested Object Validation

You can also pass object based rule to validate nested object. e.g.

1const { validate } = require('super-easy-validator');
2
3const rules = {

4  address: {

5    line1: 'string|min:10',

6    line2: 'optional|string|min:10',

7    city: 'name',

8    state: 'name',

9    pin: 'string|natural|size:6',

10    country: {

11      code: 'alpha|upper|size:2',

12      phoneCode: 'regex:/^\\+[0-9]{1,3}$/'
13    },
14  }
15}
16
17const data = {

18  address: {

19    line1: 800,

20    line2: false,

21    city: 'N/A',

22    state: 'N/A',

23    pin: 'ABC123',

24    country: {

25      phoneCode: '+9999'
26    }
27  }
28}
29
30let { errors } = validate(rules, data);
31if (errors) {
32  console.log(errors);
33}

Output

1[
2  'address.line1 must be string',
3  'address.line2 must be string',
4  'address.city must be a valid name',
5  'address.state must be a valid name',
6  'address.pin must be a valid numeric string',    
7  'address.country.code is required',
8  'address.country.phoneCode is invalid'
9]

There is no limit on the level of nesting.

9. Simple Array Validation

Sometimes it is required to validate each elements in an array. For this purpose we have arrayof: validation. It is an argument based validation where the argument itself is a validation rule. e.g.

1let rules = {
2  skills: 'array|min:2|arrayof:string|arrayof:max:10',
3};

The above example validate the skills field only when all these criteria meets:

• skills field should be of type array
• it should have at least 2 elements
• each element in the skills array should be string
• each element in the skills array should not exceed 10 characters.

Similarly, array of numeric strings can also be checked using this approach:

1let rules = {
2  emails: 'arrayof:string|arrayof:int'
3};

In the example above, it will check for array where each elements must be integer strings.

Here is one more example for validation of optional emails list (The list could have valid email string or undefined):

1let rules = {
2  emails: 'arrayof:optional|arrayof:email'
3};

NOTE: array validation is automatically applied when you use arrayof: validation rule.

10. Array Objects Validation

You can also validate objects inside an array if you know the objects structure. Here is an example of objects validation which are present inside an array field.

e.g. In this example, we will going to validate each product present in the products field:

1const { validate } = require('./index')
2
3const rules = {

4  products: [
5    {

6      title: 'string|min:5',

7      description: 'string|min:20',

8      price: 'positive',

9      category: 'enums:Electronics,Kitchen,Fashion,Others',
10    },
11  ],
12}
13
14const data = {

15  products: [
16    {

17      title: 'Smartphone',

18      description: 'High-performance smartphone with a stunning display and advanced features.',

19      price: 599.99,
20    },
21    {

22      title: 'Coffee Maker',

23      price: 'InvalidPrice',

24      category: 'Kitchen',
25    },
26    {

27      title: 'Designer Dress',

28      description: 'Elegant and stylish designer dress for special occasions.',

29      price: 149.99,

30      category: 'InvalidCategory',
31    },
32    {

33      title: 123,

34      description: 'Premium-quality notebook for all your creative and professional needs.',

35      price: '29.99',

36      category: 'Others',
37    },
38    {

39      title: 'Invalid',

40      description: 'Short desc',

41      price: -10,

42      category: 'Fashion',
43    },
44    {

45      title: 'Laptop',

46      description: 'Powerful laptop with cutting-edge technology.',

47      price: 999.99,

48      category: 'Electronics',
49    },
50  ],
51}
52
53let { errors } = validate(rules, data)
54if (errors) {
55  console.log(errors)
56}

Output

1[
2  'products[0].category is required',
3  'products[1].description is required',
4  'products[1].price must be a valid number',
5  'products[2].category is invalid',
6  'products[3].title must be string',
7  'products[3].price must be a valid number',
8  'products[4].description must have length of at least 20',
9  'products[4].price must be a valid positive number'
10]

There is no limit on the level of nesting. You can also use the combination of nested object and nested array objects validation rules.

11. Error Options

In case of errors, you can change field names to be shown in error messages and you can even set your own custom error message for each fields. You can also set(or hide) the quotes type in error message

• field:<value>: Using this you can set custom field name for a specific field. This field name will then be used in error message instead of the original field name. Make sure it is added at the end

e.g.

1let rules = {
2  age: 'natural|field:person age'
3}

This is will show the following error message (for age = 4.5)

1`person age` must be a valid natural number

• error:<value>: Using this you can set custom error message for any field. Make sure it is added at the end

e.g.

1let rules = {
2  age: 'natural|error:given age is not valid'
3}

This is will show the following error message (for age = 4.5)

1given age is not valid

• {quotes: <option>}: This option can be set in the validate function as 3rd parameter. It will set the quotes with either single quotes, double quotes, backtick or no quotes. Possible options are: none (default), single-quotes, double-quotes and backtick.

e.g.

1let rules = {
2  name: 'name',
3  age: 'natural',
4};
5
6let data = {
7  name: '...',
8  age: -7
9}
10
11const {errors} = Validator.validate(rules, data, {quotes: 'double-quotes'})
12
13console.log(errors)

This is will show the following error messages:

1[
2  '"name" must be a valid name',
3  '"age" must be a valid natural number'
4]

12. Strict Check

Sometimes you don't want to have any extra fields in the given data except those which are already defined in validation rules. To do this strict check, you can pass a strict option to true at the time of validation.

e.g. Suppose you want a user object should have 3 fields: name, age and gender. But at the same time you also don't want to have any extra fields in this user object. Here is how you add those checks:

1const { validate } = require('super-easy-validator')
2
3const rules = {
4  name: 'name',
5  age: 'natural|min:18',
6  gender: 'enums:male,female'
7}
8
9const user = {
10  name: 'john doe',
11  age: 30,
12  gender: 'male',
13  hobby: 'web development'
14}
15
16const { errors } = validate(rules, user, { strict: true })
17if(errors) {
18  console.log(errors)
19}

Final Output

1[ 'hobby is not required' ]

NOTE: When strict check is enabled, it strict checks for nested objects and nested array objects as well.

API

Optional and Nullable Types

1. optional

optional validation makes the variable optional means it can be undefined or missing field.

1let rules = {
2  organization: 'optional|string',
3};

In the example above, organization field can be absent or it must be string.

2. nullable

nullable validation makes the variable nullable means it can be null.

1let rules = {
2  organization: 'null|string',
3};

In the example above, organization field can be either null or string.

NOTE: If you want any field to support both undefined or null, then apply both validation. e.g.

1let rules = {
2  age: 'optional|null|number',
3};

In the example above, the age could be absent, null or even any number.

3. $atleast

Some times it is required to have at least one field among the list of few optional fields. Suppose we have optional otpUnlock, faceUnlock and pinUnlock fields, but atleast one of them is required. In that case we can use $atleast. e.g.

1let rules = {
2  otpUnlock: 'optional|boolean',
3  faceUnlock: 'optional|boolean',
4  pinUnlock: 'optional|boolean',
5  $atleast: 'otpUnlock|faceUnlock|pinUnlock'
6};

This will make sure at least one of the 3 is true.

Suppose you want at least n number of fields to be present from a set of fields. You can achieve this using size: keyword. e.g.

1let rules = {
2  name: 'optional|name',
3  email: 'optional|email',
4  username: 'optional|username',
5  phone: 'optional|phone',
6  $atleast: 'name|email|username|phone|size:2'
7};

This example accepts 4 optional fields out of which any 2 is required.

Now, suppose you need check from a group of fields multiple time. i.e. Lets say there is a situation where any 2 is required from a set of (name, age, gender), not only this any 1 is also required among (id, email, username). Then, you can use this array based validation rule as shown in this example:

1let rules = {
2  name: 'optional|name',
3  age: 'optional|natural|min:18',
4  gender: 'optional|enums:male,female',
5  id: 'optional|uuid',
6  email: 'optional|email',
7  username: 'optional|username',
8  $atleast: ['name|age|gender|size:2', 'id|email|username']
9}

This validation rule create separate errors for the group of (name, age, gender) and (id, email, username)

4. $atmost

Some times it is required to have at most one field among the list of few optional fields. Suppose we have optional otpUnlock, faceUnlock and pinUnlock fields, but atmost one of them is allowed at a time. In that case we can use $atmost. e.g.

1let rules = {
2  otpUnlock: 'optional|boolean',
3  faceUnlock: 'optional|boolean',
4  pinUnlock: 'optional|boolean',
5  $atmost: 'otpUnlock|faceUnlock|pinUnlock'
6};

This will make sure at most one of the 3 fields is given.

Suppose you want at most n number of fields to be present from a set of fields. You can achieve this using size: keyword. e.g.

1let rules = {
2  name: 'optional|name',
3  email: 'optional|email',
4  username: 'optional|username',
5  phone: 'optional|phone',
6  $atmost: 'name|email|username|phone|size:2'
7};

This example accepts 4 optional fields out of which only 2 can be given at a time.

Now, suppose you need check from a group of fields multiple time. i.e. Lets say there is a situation where only 2 is required from a set of (name, age, gender), also, only 1 is required among (id, email, username). Then, you can use this array based validation rule as shown in this example:

1let rules = {
2  name: 'optional|name',
3  age: 'optional|natural|min:18',
4  gender: 'optional|enums:male,female',
5  id: 'optional|uuid',
6  email: 'optional|email',
7  username: 'optional|username',
8  $atmost: ['name|age|gender|size:2', 'id|email|username']
9}

This validation rule create separate errors for the group of (name, age, gender) and (id, email, username)

Data Types

1. string

string validation is used to check if a field is string or not. e.g.

1let rules = {
2  fieldName: 'string',
3};

Note: This validation automatically applies in cases of: email , url , domain , name , username , alpha , alphanumeric , phone , mongoid , date , dateonly , time , lower , upper , ip , and regex:<value> .

2. number

number validation is used to check if a field is number or not. e.g.

1let rules = {
2  fieldName: 'number',
3};

Note: This validation automatically applies in cases of: int , positive , negative , natural , whole .

3. boolean

boolean validation is used to check if a field is boolean (true or false). e.g.

1let rules = {
2  fieldName: 'boolean',
3};

Note: You can use a combination of string and boolean to check if a field is boolean string. e.g.

1let rules = {
2  active: 'string|boolean',
3};

the above example will check if active is one of 'true' or 'false'

4. array

array validation is used to check if a field is an array. e.g.

1let rules = {
2  fieldName: 'array',
3};

5. object

object validation is used to check if a field is an object. e.g.

1let rules = {
2  address: 'object',
3  'address.pin': 'regex:/^[0-9]{6}$/',
4  'address.city': 'name',
5};

You can also write validation for nested properties of object using dot .

NOTE: In case if address is array, it will fail the validation. Although array in javascript is also an object but it will still fail, as array and object have completely different roles.

6. bigint

bigint validation is used to check if a field is a bigint type. e.g.

1let rules = {
2  field: 'bigint',
3};

7. symbol

symbol validation is used to check if a field is a symbol type. e.g.

1let rules = {
2  field: 'symbol',
3};

Specific String Types

NOTE: These validations automatically check if the field is a string data type.

1. email

email validation is used to check if a field is a valid email string. e.g.

1let rules = {
2  myEmail: 'email',
3};

2. url

url validation is used to check if a field is a valid URL string. e.g.

1let rules = {
2  profile: 'url',
3};

3. domain

domain validation is used to check if a field is a valid domain string. e.g.

1let rules = {
2  domain: 'domain',
3};

4. name

name validation is used to check if a field is a valid name (can be full name or short name) string. e.g.

1let rules = {
2  studentName: 'name',
3};

5. fullname

fullname validation is used to check if a field is a valid fullname (must be 2 or 3 words separated with spaces) string. e.g.

1let rules = {
2  studentName: 'fullname',
3};

6. username

username validation is used to check if a field is a valid username string. This is primarily used to generate a unique ID for each user for any particular site. e.g.

1let rules = {
2  username: 'username',
3};

7. alpha

alpha validation is used to check if a string contains only alphabets. This includes lowercase as well as uppercase alphabets. e.g.

1let rules = {
2  keyword: 'alpha',
3};

8. alphanumeric

alphanumeric validation is used to check if a string contains only alphabets and digits. This includes lowercase as well as uppercase alphabets. e.g.

1let rules = {
2  passwordHash: 'alphanumeric',
3};

9. phone

phone validation is used to check if a string contains valid phone number. This could also include a + or even a space . e.g.

1let rules = {
2  phone: 'optional|phone',
3};

10. phonecode

phonecode validation is used to check if a string contains valid phone country code. This includes the following examples (+1, +91, +963, etc). Here is code example for validation:

1let rules = {
2  phoneCode: 'phonecode',
3};

11. mongoid

mongoid validation is used to check if a string is valid mongodb ID. e.g.

1let rules = {
2  userId: 'mongoid',
3};

12. date

date validation is used to check if a string is valid ISO date. This may also include the time as well. e.g.

1let rules = {
2  dob: 'date',
3};

This will validate the following strings:

1'1996-01-10';
2'1996-01-10T23:50';
3'1996-01-10T23:50:34';
4'1996-01-10T23:50:34.6';
5'1996-01-10T23:50:34.6789';
6'1996-01-10T23:50:34.6789Z';
7'1996-01-10T23:50:34.6789+05:30';
8'1996-01-10T23:50:34.6789-03:00';

13. dateonly

dateonly validation is used to check if a string is valid ISO date. This must include date only without time. e.g.

1let rules = {
2  dob: 'dateonly',
3};

This will validate the following strings:

1'1996-01-10';
2'2023-12-30';
3'9999-04-01';

14. time

time validation is used to check if a string is valid ISO time. This must include time only. e.g.

1let rules = {
2  startedAt: 'time',
3};

This will validate the following time strings:

1'23:55:00';
2'23:55:00.34';
3'23:55:00.3400';

15. lower

lower validation is used to check if a string is all lowercase. This could include any character except uppercase letters. e.g.

1let rules = {
2  name: 'lower',
3};

16. upper

upper validation is used to check if a string is all uppercase. This could include any character except lowercase letters. e.g.

1let rules = {
2  name: 'upper',
3};

17. ip

ip validation is used to check if a string is a valid IP address. e.g.

1let rules = {
2  name: 'ip',
3};

18. uuid

uuid validation is used to check if a string is valid UUID (used in SQL Table IDs). e.g.

1let rules = {
2  userId: 'uuid',
3};

Specific Number Validation

NOTE: These validations automatically check if the field is a number data type.

1. int

int validation is used to check if a number is valid integer. e.g.

1let rules = {
2  temperature: 'int',
3};

NOTE: This can be used along with string to check for integer strings. e.g.

1let rules = {
2  temperature: 'string|int',
3};

The above validation will check if temperature is a valid integer string.

2. positive

positive validation is used to check if a number is a positive number (Can't be 0 or negative). e.g.

1let rules = {
2  price: 'positive',
3};

NOTE: This can be used along with string to check for positive numeric strings. e.g.

1let rules = {
2  price: 'string|positive',
3};

The above validation will check if price is a valid positive number in string format.

3. negative

negative validation is used to check if a number is a negative number (Can't be 0 or positive). e.g.

1let rules = {
2  concaveFocalLength: 'negative',
3};

NOTE: This can be used along with string to check for negative numeric strings. e.g.

1let rules = {
2  depth: 'string|negative',
3};

The above validation will check if depth is a valid negative number in string format.

4. natural

natural validation is used to check if a number is a valid natural number (must be positive integers). e.g.

1let rules = {
2  iq: 'natural',
3};

NOTE: This can be used along with string to check for natural numeric strings. e.g.

1let rules = {
2  iq: 'string|natural',
3};

The above validation will check if iq is a valid natural number in string format.

5. whole

whole validation is used to check if a number is a valid whole number (can be positive integers or 0). e.g.

1let rules = {
2  score: 'whole',
3};

NOTE: This can be used along with string to check for whole number strings. e.g.

1let rules = {
2  score: 'string|whole',
3};

The above validation will check if score is a valid whole number in string format.

Argument Based Validations

These validations require some argument(s).

1. equal

equal:<value> validation is used to check if a field has a specific value. It works for string, number and boolean data type

• For numbers, it will check if the number equals <value>
• For strings, it will check if the string equals <value>
• For boolean, it will check if the boolean equals <value>.

1let rules = {
2  marks: 'number|equal:100', // marks should be number with value 100
3  isTopper: 'boolean|equal:true', // isTopper should be boolean with value true
4  name: 'string|equal:sia', // name should be string with value 'sia'
5  status: 'equal:200', // auto detect
6};

In this case, if the status is a string type then it must be '200' , else if the status is number, then it must be 200 .

2. size

size:<value> validation is used to check if a field has a specific size.

• For numbers, it will check if the number size is of <value> digits.
• For strings, it will check if the string length is <value>.
• For arrays, it will check if the array length is <value>.

e.g.

1let rules = {

2  foods: 'array|size:3', // array should have 3 elements

3  otp: 'string|natural|size:6', // natural number string should have 6 digits

4  pinCode: 'number|size:5', // pinCode should be number and must have 5 digits

5  field: 'size:4', // Auto detect
6};

NOTE: In case if the data type is not defined as in previous case for field , then it will detect the data type of the field and then apply this validation but only if field is of type string , number or array .

3. min

min:<value> validation is used to check if a field has minimum of value <value> .

• For numbers & numeric strings, it will check if the number is more than or equal to <value>.
• For strings, it will check if the string length is more than or equal to <value>.
• For arrays, it will check if the array length is more than or equal to <value>.
• For date string, it will check if the date is more than or equal to <value>. Make sure that the date should be in ISO string format.

e.g.

1let rules = {
2  foods: 'array|min:3', // array should have minimum 3 elements
3  otp: 'string|natural|min:6', // natural number string with minimum value 6
4  pinCode: 'number|min:5', // pinCode should be >= 5
5  dob: 'date|min:2023-01:01T11:50:34.9876Z', // date should be >= '2023-01:01T11:50:34.9876Z'
6  field: 'min:4', // Auto detect
7};

NOTE: In case if the data type is not defined as in the previous case for field , then it will detect the data type of the field and then apply min: validation but only if field is of type string , number , array or date .

4. max

max:<value> validation is used to check if a field has maximum of value <value> .

• For numbers & numeric strings, it will check if the number is less than or equal to <value>.
• For strings, it will check if the string length is less than or equal to <value>.
• For arrays, it will check if the array length is less than or equal to <value>.
• For date string, it will check if the date is less than or equal to <value>. Make sure that the date should be in ISO string format.

e.g.

1let rules = {
2  foods: 'array|max:3', // array should have maximum 3 elements
3  otp: 'string|natural|max:6', // natural number string should with maximum value 6
4  pinCode: 'number|max:5', // pinCode should be <= 5
5  dob: 'date|max:2023-01:01T11:50:34.9876Z', // date should be <= '2023-01:01T11:50:34.9876Z'
6  field: 'max:4', // Auto detect
7};

NOTE: In case if the data type is not defined as in the previous case for field , then it will detect the data type of the field and then apply max: validation but only if field is of type string , number , array or date .

5. regex

regex:<value> validation is used to check if string matches a specific regular expression <value> . This will automatically apply string validation, as it only works for string data type.

e.g.

1let rules = {
2  hash: 'regex:/^[A-Z0-9]{128}$/i', // hash should match this regular expression
3};

ERROR: In case if the regular expression contains pipe | operator, then it will not work as expected as | is a special operator used for separation purpose. e.g. The following is incorrect validation:

e.g.

1let rules = {
2  gender: 'string|regex:/^(male)|(female)$/',
3};

FIX: To get rid of this issue, write validation using array instead of string. e.g.

1let rules = {
2  gender: ['string', 'regex:/^(male)|(female)$/i'],
3};

Now, it will work fine.

6. decimalsize

decimalsize:<value> validation is used to check if a field has <value> digits after decimal point.

• For numbers, it will check if the number has <value> digits after decimal point.
• For strings, it will check if the numeric string has <value> digits after decimal point. In this case it will automatically apply string|number validation.

e.g.

1let rules = {

2  price: 'string|number|decimalsize:2', // price should be a numeric string with 2 digits after decimal point

3  pi: 'number|decimalsize:6', // pi should be number with 6 digits after decimal point

4  rate: 'decimalsize:3', // Auto detect
5};

NOTE: In case if the data type is not defined as in the previous case for rate , then it will detect the data type of the rate and then apply decimalsize: validation but only if rate is of type string or number .

WARNING: In case if the data type is number , then it will trim the last zeroes after decimal point and then apply validation. So, The following example may not work as expected.

1let rules = {
2  score: 'number|decimalsize:3',
3};

This will fail the validation if score is 23.340 or 23.000 because the last zeroes after decimal point will be removed and then it will check for validation. But this only happens with number and not with string|number string.

7. decimalmin

decimalmin:<value> validation is used to check if a field has minimum <value> digits after decimal point.

• For numbers, it will check if the number has minimum <value> digits after decimal point.
• For strings, it will check if the numeric string has minimum <value> digits after decimal point. In this case it will automatically apply string|number validation.

e.g.

1let rules = {
2  price: 'string|number|decimalmin:2', // price should be a numeric string with minimum 2 digits after decimal point
3  pi: 'number|decimalmin:6', // pi should be number with minimum 6 digits after decimal point
4  rate: 'decimalmin:3', // Auto detect
5};

NOTE: In case if the data type is not defined as in the previous case for rate , then it will detect the data type of the rate and then apply decimalmin: validation but only if rate is of type string or number .

WARNING: In case if the data type is number , then it will trim the last zeroes after decimal point and then apply validation. So, The following example may not work as expected.

1let rules = {
2  score: 'number|decimalmin:3',
3};

This will fail the validation if score is 23.3400 or 23.000 because the last zeroes after decimal point will be removed and then it will check for validation. But this only happens with number and not with string|number string.

8. decimalmax

decimalmax:<value> validation is used to check if a field has maximum <value> digits after decimal point.

• For numbers, it will check if the number has maximum <value> digits after decimal point.
• For strings, it will check if the numeric string has maximum <value> digits after decimal point. In this case it will automatically apply string|number validation.

e.g.

1let rules = {

2  price: 'string|number|decimalmax:2', // price should be a numeric string with maximum 2 digits after decimal point

3  pi: 'number|decimalmax:6', // pi should be number with maximum 6 digits after decimal point

4  rate: 'decimalmax:3', // Auto detect
5};

NOTE: In case if the data type is not defined as in the previous case for rate , then it will detect the data type of the rate and then apply decimalmax: validation but only if rate is of type string or number .

WARNING: In case if the data type is number , then it will trim the last zeroes after decimal point and then apply validation. So, The following example may not work as expected.

1let rules = {
2  score: 'number|decimalmax:3',
3};

This will still pass the validation if score is 23.3400 or 23.00000 because the last zeroes after decimal point will be removed and then it will check for validation. But this only happens with number and not with string|number string.

9. enums

enums:<values> validation is used to check if a field has a value which lies in comma separated <values> . It works for string , number and boolean data type.

• For numbers, it will convert each enum <values> into number and then check if anyone of them matches with field value.
• For strings, it will convert each enum <values> into string and then check if anyone of them matches with field value.
• For boolean, it will convert each enum <values> into boolean and then check if anyone of them matches with field value. This will only check for boolean values (true/false and not any truthy / falsy values)

1let rules = {
2  rating: 'number|enums:1,2,3,4,5', // rating should be any one of these numbers: 1, 2, 3, 4, or 5
3  status: 'string|enums:pending,success,failed', // status should be string with anyone of: 'pending', 'success', or 'failed'
4  isMarried: 'boolean|enums:true,false', // isMarried should be boolean with value either true or false
5  subject: 'enums:english,maths,science', // auto detect
6};

NOTE: In case if the data type is not defined as in the previous case for subject , then it will detect the data type of the subject and then apply enums: validation but only if subject is of type string , number or boolean .

WARNING: Don't add spaces while writing enum values as it will then include spaces while doing validation. e.g.

1let rules = {
2  grade: 'string|enums: A+, A, B+, B, C, F',
3};

This will check if the grade contains anyone of ' A+' , ' A' , ' B+' , ' C' and ' F' , instead of checking 'A+' , 'A' , 'B+' , 'C' and 'F' . So make sure to put spaces only when required.

10. arrayof

Sometimes it is required to validate each elements in an array. For this purpose we have arrayof: validation. It is an argument based validation where the argument itself is a validation rule. e.g.

1let rules = {
2  skills: 'array|min:2|arrayof:string|arrayof:max:10',
3};

The above example validate the skills field only when all criteria meets:

• skills field is of type array
• it should have at least 2 elements
• each element in the skills array should be string
• each element in the skills array should not exceed 10 characters.

Similarly, to add array of numeric strings or boolean strings, you can use the combination of arrayof:string and arrayof: with other number validation like number, positive, negative, int, whole and natural. e.g.,

1let rules = {
2  ratings: 'arrayof:string|arrayof:natural|arrayof:max:5'
3}

The above validation makes sure that the ratings is an array of strings where each elements must be any natural number (in string format)

Here is one more example for validation of optional emails list (The list could have valid email string or undefined):

1let rules = {
2  emails: 'arrayof:optional|arrayof:email'
3};

NOTE: array validation automatically applied when you use arrayof: validation rule.

arrayof: supports the following validations:

Data Types

• arrayof:string
• arrayof:number
• arrayof:boolean
• arrayof:array
• arrayof:object
• arrayof:bigint
• arrayof:symbol

Specific String Types

• arrayof:email
• arrayof:url
• arrayof:domain
• arrayof:name
• arrayof:username
• arrayof:alpha
• arrayof:alphanumeric
• arrayof:phone
• arrayof:phonecode
• arrayof:mongoid
• arrayof:date
• arrayof:dateonly
• arrayof:time
• arrayof:lower
• arrayof:upper
• arrayof:ip

Specific Number Types

• arrayof:int
• arrayof:positive
• arrayof:negative
• arrayof:natural
• arrayof:whole

Argument Based Types

• arrayof:equal:${string}
• arrayof:size:${number}
• arrayof:min:${number}
• arrayof:max:${number}
• arrayof:regex:${string}
• arrayof:decimalsize:${number}
• arrayof:decimalmin:${number}
• arrayof:decimalmax:${number}
• arrayof:enums:${string}

NOTE: These validations follows the same rule as shown in their own sections but this time these will work for each elements in the array

Error Options

In case of errors, you can change field names to be shown in error messages and you can even set your own custom error message for each fields. You can also set(or hide) the quotes type in error message

field:

Using this you can set custom field name for a specific field in error message. It must be added at the end.

e.g.

1let rules = {
2  age: 'natural|field:person age'
3}

This is will show the following error message (for age = 4.5)

1'`person age` must be a valid natural number'

error

Using this you can set custom error message for any field. Make sure it is added at the end

e.g.

1let rules = {
2  age: 'natural|error:given age is not valid'
3}

This is will show the following error message (for age = 4.5)

1'given age is not valid'

Error: If your error message contains any pipe | operator, it will not work as expected. In that case, you can use array based validations. e.g.

1let rules = {
2  name: 'name|error:name is incorrect|please add different name'
3}

FIX: This will not work as its error message has pipe | operator, in that case you can use the example given below:

1let rules = {
2  name: ['name', 'error:name is incorrect | please add different name']
3}

Now it will work fine

{quotes: <value>}

This option can be set in the validate function as 3rd parameter. It will set the quotes with either single quotes, double quotes, backtick or no quotes. Possible options are: none (default), single-quotes, double-quotes and backtick.

e.g.

1let rules = {
2  name: 'name',
3  age: 'natural',
4};
5
6let data = {
7  name: '...',
8  age: -7
9}
10
11const {errors} = Validator.validate(rules, data, {quotes: 'double-quotes'})
12
13console.log(errors)

This is will show the following error messages:

1[
2  '"name" must be a valid name',
3  '"age" must be a valid natural number'
4]