@elieandraos/clockwork v1.0.21

• :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

Frameworks wrapper

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