• :technologist: Minimal model-based javascript validation library
• :bricks: Can be used with any javascript framework
• :green_heart: Offers 30+ built-in validation rules
• :children_crossing: Easy to use api, inspired from the Laravel validation syntax
• :test_tube: High test coverage

Installation

npm install @elieandraos/clockwork --save

Usage

import Clockwork from '@elieandraos/clockwork'
const validator = new Clockwork()

Basic validation

Clockwork validates a given data object against a given rules object

// define the data and rules objects
validator
   .setData({
      name: '',
      email: ''
   })
   .setRules({
        name: 'required',
        email: 'required'
    })

if ( validator.passes() ) {
    // ... do something when input data are valid
}

// alternately, you could do the inverse
if (validator.fails() ) {
    // ... do something when input data are not valid
}

Complex model validation

• "dot annotations" for nested object properties validation
• multiple rules are separated with a pipe
• rules that accept an additional paramter are suffixed with a semi column followed by the parameter
• rule paramter can be static or from the data object itself

validator
   .setData({
      person: {
         name: null,
         age: null,
         email: null
      },
      domain: 'leadwithprimitive.com'
   })
    .setRules({
        'person.name': 'required | alpha',
        'person.age': 'required | integer | min:18',
        'person.email': 'required | email | ends_with:domain' // here domain will be evaluated as 'leadwithprimitive.com'
    })

Accessing the error bag

Clockwork provides 4 helper methods to access any validation error:

validator
   .setData({ name: null, age: 10 })
   .setRules({ name: 'required', age: 'min:12' })

if(validator.fails()) {
    validator.hasErrors() // checks if there is any error
    validator.hasErrors('name') // checks if there is any error for the 'name' field
    
    validator.getErrors() // returns all the error messages
    validator.getErrors('name') // returns all the error messages of the 'name' field

    validator.getFirstError() // returns the first error message found
    validator.getFirstError('name') // returns the first error message found of the 'name' field
    
    validator.getErrorBag() // returns the error bag object as it is
}

Custom error messages

Custom error message can be defined with setCustomErrorMesssages() method. This method accepts an object of key/value pairs:

• The key is the data property concatenated with the rule name
• The value is the custom message

validator
   .setData({ name: null })
   .setRules({ name: 'required' })
   .setCustomErrorMessages({ 'name.required' : 'You must enter your name' })

For rules with parameters, add {param} to into the error message and it will be parsed.

validator
   .setData({ age: null })
   .setRules({ age: 'min:18' })
   .setCustomErrorMessages({ 'age.min' : 'You must be at least {param} years old' }) // returns: You must be at least 18 years old

Custom rules

Custom rules can be created with the extend() method. This method accepts three parameters:

• The first, is the name of the rule name
• The second, is the closure (should return a boolean) that should be executed when calling the rule
• The third (optional), is the rule's error message (default: 'Invalid')

validator
   .setData({ age: null })
   .setRules({ age: 'greater_than:18' })
   .extend( 'greated_than', (value, arg) => {
      return value > arg
   }, 'Age must be greater than {param}')

Built-in rules

| Rules | Description | |-----------------------------|-----------------------------------------------------------------------------------------------------------------------------| | after:date | The field under validation must be a value after a given date | | after_or_equal:date | The field under validation must be a value after or equal a given date | | alpha | The field under validation must be entirely alphabetic characters | | alpha_dash | The field under validation may have alpha characters, as well as dashes and underscores | | alpha_numeric | The field under validation may have alpha-numeric characters | | array | The field under validation must be an array | | before:date | The field under validation must be a value before a given date | | before_or_equal:date | The field under validation must be a value before or equal a given date | | boolean | The field under validation must be able to be cast as a boolean | | date | The field under validation must be a valid javascript date | | date_format:string | The field under validation must match the given format | | different:value | The field under validation must not match the given value | | email | The field under validation must be formatted as an email address | | ends_with:string | The field under validation must end with the given value | | is_in:value | The field under validation must be included in the given value. Accepted values are comma seperated string or array | | integer | The field under validation must be an integer | | json | The field under validation must be a valid JSON object | | leap_year | The field under validation must be a leap year date | | max:value | The field under validation must be less than or equal to a maximum value. Accepted values are string, numerics and array | | matches_regex:pattern | The field under validation must not match the given regular expression | | multiple_of:number | The field under validation must a be multiple of the given number | | min:value | The field under validation must be greater than or equal to a minimum value. Accepted values are string, numerics and array | | not_in:value | The field under validation must not be included in the given value. Accepted values are comma seperated string or array | | numberic | The field under validation must be a numeric (integer or decimal) | | required | The field under validation must be present in the input data and not empty | | same:value | The field under validation must match the given value | | size:value | The field under validation must have a length matching the given value. Accepted value are string and array | | sometimes | The field will only ve validated if present | | starts_with:string | The field under validation must end with the given value | | string | The field under validation must be a string | | today | The field under validation must be a date equal to today | | tomorrow | The field under validation must be a date equal to tomorrow | | url | The field under validation must be a valid url | | uuid | The field under validation must be a valid RFC 4122 (version 1, 3, 4, or 5) universally unique identifier (UUID) | | yesterday | The field under validation must be a date equal to yesterday |

Frameworks wrapper

• Vue: clockwork-vue https://github.com/elieandraos/clockwork-vue