pvalidator

A Promise based validator

Usage no npm install needed!

<script type="module">
  import pvalidator from 'https://cdn.skypack.dev/pvalidator';
</script>

README

pvalidator

Promise based data validator for browser and nodejs, it is lightweight and flexible.

Installing

Use via npm:

$ npm install pvalidator
var Validator = require('pvalidator'),
    string = require('pvalidator/rules/string');

// Use es6 import
import Validator from 'pvalidator';
import { string, email } from 'pvalidator/rules';

Use in browser:

Scripts for browser is under build directory, use pvalidator.js and rules.js for development environment(contains inline source maps), use pvalidator.min.js and rules.min.js for production. The references in browser is window.PValidator and window.prules.

Problems to solve

  • Suppose you have a form with more than one fields, the strategy you want to validate is:

    Validate the field and show some tip when any field element is blur or selected.

    Validate all the fields and stop the submission if something wrong is happening when the form is going to be submitted.

    The pvalidator provides validateField and validate respectively.

  • Sometimes you may want to validate some field on the server via ajax, or with some very special rules. pvalidator provides some common rules and a simple way to write your own rules.

  • Finally, you may need a flexible validator for server side usage.

Example

Before you use a Promise, you may need to know the difference between promise.then(onFulfilled, onRejected) and promise.catch(onRejected).then(onFulfilled). For the first, only one of the callbacks will be executed. But for the second, onFulfilled will always be executed because the rejection will be caught first.

var Validator = require('pvalidator'),
  emailRule = require('pvalidator/rules/email'),
  alphaRule = require('pvalidator/rules/alpha'),
  stringRule = require('pvalidator/rules/string');

var fields = {
  username: function(){
    return "username";
  },
  email: 'bar.com'
};

var rules = {
  username: [stringRule(5, 25), alphaRule],
  email: emailRule
};

var errors = {
  username: ['用户名的长度必须在5到25个字符之间', '用户名只能包含字母'],
  email: '邮箱格式不正确'
};

var validator = new Validator(fields, rules, errors);

validator.validate().then(function(fields){
  // This callback will not be executed.
}, function(errors){
  // Do something with errors(the default type of errors is Array): ['邮箱格式不正确'].
});

validator.validateField('username').then(function(field){
  // Do something with the field: 'username'
}, function(error){
  // This callback will not be executed.
});

How the validator behave

When you call the validate method, all fields will be checked by their rules correspondingly.

For each field, the given rules will be applied one by one. If one rule is failed the whole field validation will stop, error message from customErrors or the failure rule will be recorded.

Notably, pvalidator provides a pseudo "empty" rule, "empty" will pass any field that is undefined, null or "". You can use this rule for a not required field. Usage: var rulesForUsername = {username: ["empty", ...]}.

Constructor and methods

PValidator(fields, rules, customErrors)

Params Description type default
fields The data you want to validate. Example: {name: "foo"} or {name: function(){ return "foo"; }}. Object undefined
rules Rules for fields, a rule will be applied to a field with the same key. Example: {name: anyRule} Object undefined
customErrors Replace the default error message from rule. Example: {name: "The given name is not acceptable"}. If the target field has more than one rules, the custom errors can be an array which has the same order of rules. Object undefined

If you want to get a field value dynamically, you can use a function as the value of that field.

validator.validate(options)

Option Description type default
fields If this option is provided, it will replace the initial fields provided in constructor Object undefined
objectErrors The default errors is returned by type of Array, if this option is provided as true, the type of errors is Object Boolean false

This method returns an instance of Promise.

Example:

validator.validate({objectErrors: true}).then(function(fields){
  // validation success
}, function(errors){
  // validation failed, the type of errors is Object
});

validator.validateField(fieldName)

Params Description type default
fieldName the name(key) of the field you want to validate String undefined

This method returns an instance of Promise.

Example:

validator.validateField("name").then(function(fieldValue){
  // Validation success
}, function(error){
  // Validation failed
});

Rules

The pvalidator provides a pseudo rule named "empty", if this rule is provided as the first item of rule array, the target field can pass rule validation when it it empty ignoring any other rules.

You can custom rule ( excepting "empty", string and number) error using the rule factory:

var Validator = require('pvalidator');
var factory = require('pvalidator/rules/factory'),
    emailRule = require('pvalidator/rules/email');

var validator = new Validator(
    {
        email: 'foo'
    },
    {
        email: factory(emailRule, 'bar')
    }
);

validator.validate().catch(function(err){
    console.log(err); // Output: ['bar']
});

Rules provided by pvalidator:

Rule Description
"empty" The "empty" pseudo rule
alpha The target can only contains alpha characters
alpha_dash The target can only contains alphanumeric characters, dashes or underscores.
alpha_num The target can only contains alphanumeric characters
email The target must be a email
equal target[0] == target[1]
number(min, max, error) The target must be a number whose value is between min and max
string(min, max, error) The target must be a string whose length is between min and max
url The target must be a url
array The target must be an array
boolean The target must be a boolean
integer The target must be an Integer

The string and number rules are factories.

Write your own rules

The rule used by pvalidator is a function, below is the equal rule:

function (judgement, success, failure, error) {
    if(judgement[0] == judgement[1]){
        success();
    }
    error = typeof error !== 'undefined' ? error : "The :field's value is not equal to given confirmation.";
    failure(error);
};

Explaination: When a rule is applied to a field, this field's value will be passed as the first param, success and failure callbacks as the second and third params, anytime you want this field pass the rule validation just call the success and vice versa.

The failure callback accepts a param of any type, and when a string param is passed the ":field" part of this param will be replaced with the name(key) of the target field when error message is produced.

Param error is optional, it will be used by rule factory to custom rule error if it's handled correctly.

Email server side validation rule example ( not rigorous ):

function(email, success, failure){
  jQuery.ajax({
    method: "POST",
    url: "email-exists.php",
    data: { email: email },
    success: function() {
      success();
    },
    error: function(){
      failure("This email is already exists");
    }
  });
}

License

MIT

Contribute

  • Welcome Issues.
  • Clone the repository -> npm install -> do something -> npm run build -> npm run test -> make a PR.
  • To be a contributor if necessary.