Shark-Validator

Overview

A light weight, powerful, tree shakable javascript schema validator which works on both Nodejs and Browser.

Features

• Light weight & tree shakable to reduce your JS bundle size.
• Works on both Nodejs & Browser.
• Easy to create complex schema validation.
• Supports array and array of object validation.

Comparison

Here we have created a validator schema in Shark Validator & Joi for a field users which will contain array of objects with name & email. And here is the final bundle size from both packages.

Shark Validator	Joi
12KB	146KB

This shows a huge 91.78% reduction in bundle size, which can be of a huge significant if you are trying to reduce your JS bundle size.

You can find the code for this test here.

Table of Contents

1. Installation
2. Importing
3. Quick start
4. More fetures
5. Reference and API Documentation

Installation

npm install shark-validator

Importing

Remeber to import everything from the shark-validator directly for tree shaking to work.

ES6

import {
  Validator,
  RuleSet,
  isRequired,
  isString,
  isLen,
} from "shark-validator";

CommonJS

const {
  Validator,
  RuleSet,
  isRequired,
  isString,
  isLen,
} = require("shark-validator/lib");

Quick start

There are 2 classes in shark-validator you need to know:

• Validator - The validation schema that will be used to validate a set of values.
• Rule - There are a lot of predefined Rules that you can use or create your own Rule by extending the Rule class.

Some predefined rules are isString, isRequired and isLen. You can lookup more predefined rules here https://shark.imirshad.com/.

Example usage

Here we'll create a validator schema to validate for name, email and password. We have to create a set of Rule(s) for each key in this schema.

The rules we'll use in this example are:

• isString: It makes sure that the value is a string.
• isRequired: It makes sure that the value is present.
• isEmail: It makes sure that the value is an email.
• isLen: It makes sure that the value is of a particular length.

const {
  Validator,
  isRequired,
  isString,
  isLen,
  isEmail,
} = require("shark-validator/lib");

const schema = new Validator({
  name: [isRequired(), isString()],
  email: [isRequired(), isString(), isEmail()],
  password: [isRequired(), isString(), isLen({ min: 8 })],
});

Now our validation schema is created which we can use to test any value. To test a particular object we can use the validate method of schema as shown below.

const valuesToCheck = {
  name: "Dan",
  email: "dandaninc.com",
  password: "123456",
};

const { values, errors } = schema.validate(valuesToCheck);

The validate methods returns an object with values and errros (if any otherwise undefined). The value of the variable values and errors will be.

Values

{
  "name": "Dan",
  "email": "[email protected]",
  "password": "123456"
}

Errors

{
  "email": [
    {
      "error": "'email' should be a valid email.",
      "validator": "isEmail",
      "value": "dandaninc.com",
      "path": ["email"]
    }
  ],

  "password": [
    {
      "error": "'password' should not be less than 8 characters.",
      "validator": "isLen",
      "value": "123456",
      "path": ["password"]
    }
  ]
}

The errors object contains all the data about which rule failed and where did it fail.

As in this example we can see that the email key failed to validate on isEmail rule and the password field failed to validate on isLen rule.

The errors object contains the following data:

• error: Error message.
• validator: Name of the Rule where the error occured.
• value: The value on which the rule failed.
• path: Path to the value.

More fetures

• Custom label
• Return early
• Custom error message
• Custom validation
• Validating objects
• Validating arrays
• Validating array of objects

Custom label

You can provide a custom name to a particular key which can be displayed on the error message if the test for that key fails.

Example

If in the above example we defined the email key as:

email: { rules: [isRequired(), isString(), isEmail()], label: "Business Email" }

Then the returned error message will use the name Business Email.

{
  "email":
    [
      { "error": "'Business Email' should be a valid email.",
        "validator": "isEmail",
        "value": "dandaninc.com",
        "path": ["email"]
      }
    ],

  ...
}

Return early

If you want to stop the check if one error is found, then you can pass in an additional parameters returnEarly and returnRuleSetEarly to the Validator constructor.

If set to true, then the functionality of the two parameters will be:

• returnEarly: Stops validating of other keys when one or more errors are found in a key.
• returnRuleSetEarly: Stops further validation of a particular key if an error is found on the same key.

You can use a combination of both the parameters to acheive different funtionalities.

Example

If the validator is defined as below.

const schema = new Validator(
  {
    name: [isRequired(), isString()],
    email: [isRequired(), isString(), isEmail()],
    password: [isRequired(), isString(), isLen({ min: 8 })],
  },
  {
    returnEarly: true,
  },
);

Then the errors object will be:

{
  "email": [
    {
      "error": "'Business Email' should be a valid email.",
      "validator": "isEmail",
      "value": "dandaninc.com",
      "path": ["email"]
    }
  ]
}

Notice that no password error is returned because the validation stopped when the email failed the test.

Custom error message

If you don't like the existing error messages, you can provide custom error messages if a particular rule fails just by adding a parameter message to the Rule constructor as:

[someRule({ message: "Please provide a valid input." })];

Additionally you can use some variable inside the message string like name of the field. To use a variable you just have to enclose the name of the variable between %, like this.

[someRule({ message: "Please provide a valid input for %name%." })];

Other then the name valriable, you can use any other variable that you provide in the Rule constructor along with the message.

Example

If in the above example we defined the password key as:

password: [
  isRequired(),
  isString(),
  isLen({
    min: 8,
    message: "%name% must be equal to or greater than %min% charecters.",
  }),
];

Then the returned error will use our custom message.

{
  "password":
    [
      { "error": "password must be equal to or greater than 8 charecters.",
        "validator": "isLen",
        "value": "123456",
        "path": ["password"]
      }
    ],

  ...
}

Custom validation

You can also set your custom validation rules with isCustom rule.

You just need to pass check function which takes the value and other options as a parameter and returns the error string if an error is to be thrown otherwise it should return false or undefined.

Example

Below is an example to show how we can add a custom validation for confirmPassword to check if it is equal to the password field.

const schema = new Validator({
  password: isString(),
  confirmPassword: isCustom({
    check: (value, { allValues }) => {
      if (value !== allValues.password) {
        return "Confirm password should be equal to password.";
      }
    },
  }),
});

If the schema is tested with the following values:

schema.validate({ password: "123456", confirmPassword: "12345" });

Then the errors object will be:

{
  "confirmPassword": [
    {
      "error": "Confirm password should be equal to password.",
      "validator": "isCustom",
      "value": "12345",
      "path": ["confirmPassword"]
    }
  ]
}

You can read more about isCustom in the API Documentation.

Validating objects

You can validate objects with isObject rule. You can also nest mustiple object with this rule.

To achieve this you need to create a seperate schema for the object you are validating and use it inside the isObject rule.

Example

const addressSchema = new Validator({
  city: [isRequired(), isString()],
  state: [isRequired(), isString()],
});

Now you can use this addressSchema in your main validation schema.

const schema = new Validator({
  name: [isRequired(), isString()],
  address: isObject({ schema: addressSchema }),
});

const { values, errors } = schema.validate(valuesToCheck);

You can check additional parameters in isObject documentation.

Validating arrays

You can validate arrays with isArray rule.

You have to define a set of rules to validate each array element and you can also specify the range of array length.

Example

const schema = new Validator({
  name: [isRequired(), isString()],
  emails: isArray({ rules: [isRequired(), isString(), isEmail()] }),
});

const { values, errors } = schema.validate(valuesToCheck);

You can check additional parameters in isArray documentation.

Validating array of objects

You can validate array of objects with isArrayOfObject rule. You can also nest mustiple object with this method.

To achieve this you need to create a seperate schema for the object you are validating and use it inside the isArrayOfObject rule.

Example

const addressSchema = new Validator({
  city: [isRequired(), isString()],
  state: [isRequired(), isString()],
});

Now you can use this addressSchema in your main validation schema.

const schema = new Validator({
  name: [isRequired(), isString()],
  addresses: isArrayOfObject({ schema: addressSchema }),
});

const { values, errors } = schema.validate(valuesToCheck);

You can check additional parameters in isArrayOfObject documentation.

Reference and API Documentation

Checkout the reference and API documentation for more features. https://shark.imirshad.com/