uranus

Uranus is a wrapper validation utility over chriso's awesome validator.js with some extra extension methods.

Installation:

 $ npm install --save uranus

Note: 2.x is written in Node 4x so its not compatible with previous versions of Node. For previous versions, install 1.x:

 $ npm install --save uranus@1.x

Tests:

To execute tests:

 # clone the repo and change directory
 $ git clone https://github.com/umayr/uranus.git && cd $_
 
 # install local dependencies
 $ npm install
 
 # run tests
 $ npm test

Usage:

After installing uranus, you can simply use it as:

 const Uranus = require('uranus');
 let result = Uranus.validateAll([
 {
    value: '@foo.com',
    rules: {
      isEmail: true,
      len: [15, 100]
    }
 },{
    value: 'Neptune',
    rules: {
      isAlpha: true,
      isLowercase: true,
      notContains: 'Net'
    }
 }]);
 
 console.log(result.isValid()) // false

There are several ways to apply validations. For bulk validation you can use validateAll which supports both array and object.

 const Uranus = require('uranus');
 
 // For Arrays.
 let result = Uranus.validateAll([
 {
    value: '[e-mail]',
    rules: {
      isEmail: true
    }
 },{
    value: 'Neptune',
    rules: {
      isAlpha: true,
    }
 }]);
 console.log(result.isValid()) // true
 
 // For objects.
 let src = {
    name: 'Neptune',
    email: '[e-mail]'
  };
  
  let rules = {
    name: {
      isAlpha: true
    },
    email: {
      isEmail: true
    }
  }
let result = Uranus.validateAll(src, rules);
console.log(result.isValid()) // true
 

By default Uranus generates subject less error messages itself with the help of Cressida. For e.g:

let rules = {
   isEmail: true
};
Uranus.validateOne('foo@..!!.com', rules);
 
// ['should be a valid email address.']

By default these messages are subjectless. To specify a name, you can do something like this:

// For `validateOne()`:
 
let rules = {
   isEmail: true
};
Uranus.validateOne({value: 'foo@..!!.com', name: 'Foo'}, rules);
// ['Foo should be a valid email address.']
 
// For `validateAll()` with an array:
 
let result = Uranus.validateAll([
        {
          value: 'foo',
          name: 'Foo',
          rules: {
            isEmail: true
          }
        }
      ], {
        includeName: true
      });
// ['Foo should be a valid email address.']
 
// For `validateAll()` with an object:
 
let src = {
    email: {
       name: 'Foo',
       value: 'foo@!!!.com'
   }
  };
 
  let rules = {
    email: {
      isEmail: true
    }
  }
Uranus.validateAll(src, rules);
// ['Foo should be a valid email address.']

This feature can be turned off with includeName set to false in options moreover you can set your own error messages.

let result = Uranus.validateAll([
 {
    value: '@foo.com',
    rules: {
      isEmail: {
        args: true,
        msg: 'Boo! email is invalid'
      },
      len: {
        args: [15, 100],
        msg: 'You\'re either too large or too small.'
      }
    }
 },{
    value: 'Neptune',
    rules: {
      isAlpha: {
        args: true,
        msg: 'meh, only letters, k?'
      },
      isLowercase: {
        args: true,
        msg: 'only lowercase, babes.'
      },
      notContains: {
        args: 'Net',
        msg: 'No fishin\''
      }
    }
 }]);

For validating one single value, you can use validateOne as:

let value = '[e-mail]';
let rules = {
   isEmail: true,
   notNull: true
};
 
Uranus.validateOne(value, rules);

Both validateOne & validateAll methods can also be accessed by creating an instance of Uranus. For example:

 const Uranus = require('uranus');
 let validator = new Uranus();
 
 // validateAll
 let result = validator.validateAll([
 {
    value: '[e-mail]',
    rules: {
      isEmail: true
    }
 },{
    value: 'Neptune',
    rules: {
      isAlpha: true,
    }
 }]);
 console.log(result.isValid()) // true
 
 // validateOne
 let value = '[e-mail]';
 let rules = {
  isEmail: true,
  notNull: true
 };
  
 let result = validator.validateOne(value, rules);
 console.log(result.isValid()) // true
 

By default validateAll validates all the rules for all value sets but if you set progressive to true while creating Uranus instance, it will stop iterating through rules when one fails. In that way you can get only one error message for one value instead of getting all, for example:

let validator = new Uranus({ progressive: true });
let result = validator.validateAll([
 {
    value: '@foo.com',
    rules: {
      isEmail: {
        args: true,
        msg: 'Boo! email is invalid'
      },
      len: {
        args: [15, 100],
        msg: 'You\'re either too large or too small.'
      }
    }
 }]);
 
 console.log(result.getAllMessages())
 // ["Boo! email is invalid"]

Note: In case of static methods, options can be provided as the last argument.

Later you can get all of these messages by getAllMessages() method. For example,

  let msgs = result.getAllMessages();
  console.log(msgs)
  // ["Boo! email is invalid", "You're either too large or too small.", "meh, only letters, k?", "only lowercase, babes.", "No fishin'"]

You can also get message for one specific rule by:

  let msg = result.getMessage(0, 'isEmail'); // where 0 is the index of provided array.
  console.log(msg) // Boo! email is invalid

In order to get all rules for one value you can use getItem() method, like:

  let check = result.getItem(0);
  
  console.log(check.isEmail.isValid()) // false
  console.log(check.isEmail.getMessage()) // Boo! email is invalid
  
  console.log(check.len.isValid()) // false
  console.log(check.len.getMessage()) // You're either too large or too small.

Note: You can get whole ValidationItem by using getRule().

Supported Rules:

As mentioned above, Uranus acts like a wrapper to validator.js so it supports all validations currently provided by validator.js. In addition to that, there are several extra validations rules that Uranus provides out of the box. Some common validations along with their args are as follows:

  is: ["^[a-z]+$",'i'],       // will only allow letters
  is: /^[a-z]+$/i,            // same as the previous example using real RegExp
  not: ["[a-z]",'i'],         // will not allow letters
  isEmail: true,              // checks for email format ([e-mail])
  isUrl: true,                // checks for url format (http://foo.com)
  isIP: true,                 // checks for IPv4 (129.89.23.1) or IPv6 format
  isIPv4: true,               // checks for IPv4 (129.89.23.1)
  isIPv6: true,               // checks for IPv6 format
  isAlpha: true,              // will only allow letters
  isAlphanumeric: true        // will only allow alphanumeric characters, so "_abc" will fail
  isNumeric: true             // will only allow numbers
  isInt: true,                // checks for valid integers
  isFloat: true,              // checks for valid floating point numbers
  isDecimal: true,            // checks for any numbers
  isLowercase: true,          // checks for lowercase
  isUppercase: true,          // checks for uppercase
  notNull: true,              // won't allow null
  isNull: true,               // only allows null
  notEmpty: true,             // don't allow empty strings
  equals: 'specific value',   // only allow a specific value
  contains: 'foo',            // force specific substrings
  optional: ['isUrl']         // validate the rule provided in second parameter if first param is not null
  notIn: [['foo', 'bar']],    // check the value is not one of these
  isIn: [['foo', 'bar']],     // check the value is one of these
  notContains: 'bar',         // don't allow specific substrings
  len: [2,10],                // only allow values with length between 2 and 10
  isUUID: 4,                  // only allow uuids
  isDate: true,               // only allow date strings
  isAfter: "2011-11-05",      // only allow date strings after a specific date
  isBefore: "2011-11-05",     // only allow date strings before a specific date
  max: 23,                    // only allow values
  min: 23,                    // only allow values >= 23
  isArray: true,              // only allow arrays
  isCreditCard: true          // check for valid credit card numbers

Checkout Validator.js project for more details on supported validations.

Note: If a rule is supported by validator.js but it doesn't work properly in Uranus, please feel free to report an issue.

Custom Rules:

Additional rules can be added while instantiating Uranus, for e.g.

  let validator = new Uranus({
      extensions: {
        hasFoo(str) {
          return str.match(/foo/);
        }
      }
    });
  let response = validator.validateAll([{
      value: 'foo',
      rules: {
        hasFoo: true
      }
    }]);
        
  response.isValid() // true

If you want to use predefined rules in your custom rule, it can be done as:

  let validator = new Uranus({
      extensions: {
        isLowercaseAlpha(str) {
          // Here `this` refers to the validator instance.
          // Therefore, all built-in validators will be available here.
          
          return this.isAlpha(str) && this.isLowercase(str)
        }
      }
    });
  let response = validator.validateAll([{
      value: 'foobar1',
      rules: {
        isLowercaseAlpha: true
      }
    }]);
        
  response.isValid() // false

Parameters passed from a rule can be accessed as additional arguments in the extension method:

  let validator = new Uranus({
      extensions: {
        range(str, min, max) {
          return str.length > min && str.lenght < max;
        }
      }
    });
  let response = validator.validateAll([{
      value: 'cat',
      rules: {
        range: [1, 10]
      }
    }]);
        
  response.isValid() // true

License:

The MIT License (MIT)

Copyright (c) 2015 Umayr Shahid <[e-mail]>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.