@primitivesocial/clockwork

Clockwork

Clockwork is a client-side validation utilities library. It can be used natively or as part of any javascript framework, and offers 25+ validation rules out of out the box.

Installation

Pull it via npm

npm i @primitivesocial/clockwork --save

Usage

import {_v} from "@primitivesocial/clockwork";

let name = 'primitive';

if(_v.is_string(name) && _v.min(name, 3))
    window.alert('name is valid');

Available Rules

:warning: All date values must be of format YYYY-MM-DD (example: '2020-01-15')

• after Validates if a given value (date string) is after another value (date string)

let d = '2020-5-1';
after(d, '2020-1-1'); // returns true

• after_or_equal Validates if a given value (date string) is after or equal to another value (date string)

let d = '2020-5-1';
after_or_equal(d, '2020-1-1'); // returns true

• alpha Validates if a given value (string) contains only letters

let str = 'clockwork';
alpha(str); // returns true

• alpha_dash Validates if a given value (string) contains only letters, dashes and underscores

let str = 'primtivesocial-clock_work';
alpha_dash(str); // returns true

• alpha_numeric Validates if a given value (string) contains only letters and numbers

let str = 'clockwork123';
alpha_numeric(str); // returns true

• before Validates if a given date value (date string) is before another value (date string)

let d = '2020-5-1';
before(d, '2020-5-5'); // returns true

• before_or_equal Validates if a given value (date string) is before or equal to another value (date string)

let d = '2020-5-1';
before_or_equal(d, '2020-1-1'); // returns true

• boolean Validates that a given value is boolean

let str = 'clockwork';
let isValid = false;
boolean(str); // returns false
boolean(isValid); // returns true

• date Validates if a given value (date string) is a valid date

let d = '2020-5-1';
date(d); // returns true

• different Validates if a given value (numbers, strings, array and objects) is different from another value

let str = 'clockwork';
let str2 = 'primitive'
different(str, str2); // returns true

• ends_with Validates that a given value (string) ends with a specific string

let str = 'clockwork';
ends_with(str, 'work'); // returns true

• integer Validates if a given value is an integer

let str = 'clockwork';
let amount = 100;
integer(str); // returns false
integer(amount); // returns true

• is_array Validates if a given value is an array

let arr = [ 'foo', 'bar'];
let amount = 100;
is_array(arr); // returns true
is_array(amount); // returns false

• is_in Validates if a given value (string) is exists in an array, or a comma separated string

let str = 'foo';
is_in(str, ['foo', 'bar']); // returns true
is_in(str, 'foo,bar') // returns true

• is_string Validates if a given value is a string

let str = 'foo';
is_string(str); // returns true

• json Validates if a given value is a json object

let obj = { foo: 'bar'};
json(obj); // returns true

• length Validates the length of a given value (string and arrays)

length('foo', 3); // returns true
length(['foo', 'bar'], 2); // returns true

• matches_regex Validates if a given value matches a specific regex

let email = "[e-mail]";
matches_regex(email, "^\\S+@\\S+[\\.][0-9a-z]+$"); // return true

• max Validates if a given value (number and string) is less than the maximum specified

let amount = 100;
max(amount, 200); // returns true

let str='foobar';
max(str, 10); // returns true

• min Validates if a given value (number and string) is more than the maximum specified

let amount = 100;
min(amount, 10); // returns true

let str='foobar';
min(str, 3); // returns true

• not_in Validates if a given value (string) does not exist in an array, or a comma separated string

let str = 'foo';
not_in(str, ['clockwork', 'primitive']); // returns true
not_in(str, 'clockwork,primitive') // returns true

• numeric Validates if a given value is numeric

let amount = 100.75;
numeric(amount); // returns true

• required Validates if a given value is present

let str = 'primitive';
let word = '';
required(str); // returns true;
required(word); // returns false;

• same Validates if a given value (numbers, strings, array and objects) is the same as another value

let str = 'clockwork';
let str2 = 'primitive'
same(str, str2); // returns false

• starts_with Validates that a given value (string) starts with a specific string

let str = 'clockwork';
starts_with(str, 'clock'); // returns true

• url Validates if a given value (string) is valid url

let str = 'https://example.com';
url(str); // returns true

• uuid Validates if a given value (string) is a valid uuid

let str = '9034dfa4-49d9-4e3f-9c6d-bc6a0e2233d1';
uuid(str); // returns true

Vue Integration

All the rules the package provides, can be used within the vue component validations option.

• Configuration

import {VueClockwork} from "@primitivesocial/clockwork";
Vue.use(VueClockwork);

• Usage

export default {
    data: () => {
        return {
            username: null,
            email: null,
            registration: {
                date: null,
                type: null,
            },        
            types: [ 'student', 'individual', 'company'],
            registration_ends: '2020-12-31'
        }   
    },
    validations: {
        'username': 'required | alpha_dash',
        'email': 'required | email',
        'registration.date': 'required | date | before_or_equal:registration_ends',
        'registration.type': 'when_present | is_in:types',
    },
    methods: {
        save() {
            if(this.validator.passes()) {
                // ...
            }
        }   
    },
    created() {
        this.initValidator();
    }
}

• Displaying errors

<span v-if="hasError('username')" class="text-red-900">{{ showError('username') }}</span>

• Customizing error message

created() {
    this.initValidator();
    this.validator.setCustomErrorMessages({
        'username.alpha_dash' : 'The username must only contain letters and dashes.',
        'username.required' : 'The username must not be empty.',
    })    
}

• Creating custom rule

created() {
    this.initValidator();
    this.validator.extend('greater_than_ten', function(value) {
        return value > 10;
    })    
}

Author & Contribution

Hey, I'm Elie Andraos, a web developer at Primitive. Pull requests are always welcome. For major changes, please open an issue first to discuss what you would like to change. You can also reach me out on twitter for any question!