Introduction

culpritjs   is JavaScript validation library inspired by Laravel Validation. After trying several validation libraries and spending some time on each, I just came to realise each library I used had its own thing or two that didn't align very well with my expectations, so they weren't good enough for me. And having interacted with Laravel and liked its validation methods, I decided to build one just like it and added all the features i thought I needed or will need, then decided to publish it to help folks out there who might have gone through what I have.

Installation

npm install culpritjs --save

Basic usage

culpritjs   allows typescript usage. The bare minimum usage of culpritjs   is initializing the validation schema and calling the validate function on the object or form data to be validated against the schema.

Schema declaration:

const schema = {
    firstName: 'required|string|max:50',
    lastName: 'required|string|max:50',
    email: 'required|string|email|max:50',
};

TypeScript import:

import { validate } from 'culpritjs';

JavaScript import:

const validate = require('culpritjs');

Validate function:

const result = validate(obj, schema);

Results returns an object with two properties i.e. value which is an object containing the properties which have been validated and errors which contains an array of errors or null if there are no errors

API

validate()

This function takes in four parameters:

  • object - The main object with properties to be validated against
  • schema - The object with schema to be used in validation
  • extraArgs - Extra arguments passed to be used in validation as extra restrictions
  • messages - Custom error messages to be used

Returns an object with two properties:

  • value - Object containing values that were validated. This properties contains only the properties that were in the schema but the initial passed object is not overridden, this will just be a copy. The values will be converted to their respective validation types rules e.g. if the value was originally a string in the initial object but being validated as a number, this object will contain the value in number.
  • errors - This is an array of all error messages from the validation, if there are none, this property is usually null.

object

This is the main object passed that has values to be validated. This object can be either a valid JSON object or a FormData object.

schema

This is an object schema containing all validation rules that will be used in validating. This constitutes of an object with property names same as object property names to be validated and property values of the rules to be used against the object values. The rules are separated by a pipe (|). There are no limits to the number of validation rules that can be passed. Order of rules is (general rules) which are purely optional, (type) which specifies type of the value to be validated against then rules related to that particular type. The returned value property contains properties specified in this object.

extraArgs

This is an object that contains property names same as schema property names and a specific validation rule separated by a period (.) and property values of values that should be used against the specific validation rule. This is an alternative to values or values passed inline in the schema object. Values passed inline takes precedence. Example of this: 

 // Schema
const schema = {
    dateOfBirth: 'required|date|before'
};

// extra arguments for the schema
const extraArgs = {
    'dateOfBirth.before': moment().subtract(18, 'years')
}

// This value will then be used during dateOfBirth validation

message

This works the same way as extraArgs. Its an object of messages to be used instead of the predefined messages. Example: 

 // Schema
const schema = {
    dateOfBirth: 'required|date|before'
};

// extra arguments for the schema
const extraArgs = {
    'dateOfBirth.before': moment().subtract(18, 'years')
}

// custom messages
const extraArgs = {
    'dateOfBirth.min': 'You should be at least 18 years of age to be able to register successfully!'
}

required (General)

The value of the field must be present and not empty (empty array or string), null or undefined.

required_if:anotherField,value,... (General)

The value of the field must be present and not empty (empty array or string), null or undefined if anotherField is equal to any of the value. These values can also be passed in the extraArgs object.

required_unless:anotherField,value,... (General)

The value of the field must be present and not empty (empty array or string), null or undefined unless anotherField is equal to any of the value. These values can also be passed in the extraArgs object.

required_with:field,... (General)

The value of the field must be present and not empty (empty array or string), null or undefined if any of field is present. This rule does not support values from extraArgs object.

required_with_all:field,... (General)

The value of the field must be present and not empty (empty array or string), null or undefined if all of field are present. This rule does not support values from extraArgs object.

required_without:field,... (General)

The value of the field must be present and not empty (empty array or string), null or undefined if any of field are not present. This rule does not support values from extraArgs object.

required_without_all:field,... (General)

The value of the field must be present and not empty (empty array or string), null or undefined if all of field are not present. This rule does not support values from extraArgs object.

between:min,max (Array)

The length of the array value of the field must be between min and max. This rule does not support values from extraArgs object.

distinct (Array)

The array value of the field must not have duplicate values.

gt:field (Array)

The array value of the field length must be greater than the array length of field. This rule does not support values from extraArgs object.

gte:field (Array)

The array value of the field length must be greater than or equal to the array length of field. This rule does not support values from extraArgs object.

lt:field (Array)

The array value of the field length must be less than the array length of field. This rule does not support values from extraArgs object.

lte:field (Array)

The array value of the field length must be less than or equal to the array length of field. This rule does not support values from extraArgs object.

max:value (Array)

The array value of the field length must have a maximum length of value. This rule does not support values from extraArgs object.

min:value (Array)

The array value of the field length must have a minimum length of value. This rule does not support values from extraArgs object.

size:value (Array)

The array value of the field length must have number of items specified in value. This rule does not support values from extraArgs object.

accepted (Boolean)

The value of the field must be either of yes, true, on or 1.

not_accepted (Boolean)

The value of the field must be either of no, false, off or 0.

after:date (Date)

The field date value must be a value after the date. This rule supports values from extraArgs in form of Date, Moment or even a valid date string.

after_or_equal:date (Date)

The field date value must be a value after or equal to the date. This rule supports values from extraArgs in form of Date, Moment or even a valid date string.

before:date (Date)

The field date value must be a value before the date. This rule supports values from extraArgs in form of Date, Moment or even a valid date string.

before_or_equal:date (Date)

The field date value must be a value before or equal to the date. This rule supports values from extraArgs in form of Date, Moment or even a valid date string.

equals:date (Date)

The field date value must be a value equal to the date. This rule supports values from extraArgs in form of Date, Moment or even a valid date string.

format:value (Date)

The field date value must be formatted as specified by value. Use moment.js specification for the value. This rule does not support values from extraArgs object.

between:min,max (Number)

The field number value must be between min and max. This rule does not support values from extraArgs object.

different:field (Number)

The field number value must be not be equal to value of field. This rule does not support values from extraArgs object.

digits:value (Number)

The field number value must have number of digits specified by value. This rule does not support values from extraArgs object.

digits_between:min,max (Number)

The field number value must have number of digits between min and max. This rule does not support values from extraArgs object.

gt:field (Number)

The field number value must be greater than value of field. This rule does not support values from extraArgs object.

gte:field (Number)

The field number value must be greater than or equal to value of field. This rule does not support values from extraArgs object.

in:value,... (Number)

The field number value must be equal to any of value. This supports values from extraArgs object in form of array.

in_array:field.* (Number)

The field number value must be one of the values array of field.*. The field value must be either an array or an object which has array value in one of its properties. This rule does not support values from extraArgs object.

integer (Number)

The field number value must an integer. This rule does not support values from extraArgs object.

lt:field (Number)

The field number value must be less than value of field. This rule does not support values from extraArgs object.

lte:field (Number)

The field number value must be less than or equal to value of field. This rule does not support values from extraArgs object.

max:value (Number)

The field number value must have a maximum value of value. This rule does not support values from extraArgs object.

min:value (Number)

The field number value must have a minimum value of value. This rule does not support values from extraArgs object.

not_in:value,... (Number)

The field number value must not be equal to any of value. This supports values from extraArgs object in form of array.

same:field (Number)

The field number value must be equal to value of field. This rule does not support values from extraArgs object.

size:value (Number)

The field number value must be equal to value. This rule does not support values from extraArgs object.

alpha (String)

The field string value must consist of only alphabetic characters. This rule does not support values from extraArgs object.

alpha_dash (String)

The field string value must consist of only alphabetic characters as well as dashes and underscores. This rule does not support values from extraArgs object.

alpha_num (String)

The field string value must consist of only alphanumeric characters. This rule does not support values from extraArgs object.

alpha_num_dash (String)

The field string value must consist of only alphanumeric characters as well as dashes and underscores. This rule does not support values from extraArgs object.

between:min,max (String)

The field string value must have a length between min and max. This rule does not support values from extraArgs object.

clean:args... (String)

This rule formats the string. This rule does not support values from extraArgs object. Arguments are as follows:

spaces This argument removes extra spaces of the string value of the field. This argument has sub-arguments as follows:
  • end - Removes trailing spaces of the string value of the field.
  • begin - Removes preceding spaces of the string value of the field.
  • between_single - Replaces multiple spaces, tabs or new lines inside of the string value of the field with a single space.
  • between_none - Removes multiple spaces, tabs or new lines inside of the string value of the field.
  • both - Removes both trailing and preceding spaces of the string value of the field.
These sub-arguments can be used upto a maximum of two arguments. Only one of end, begin or both can be used at a time and either of between_single or between_none can be used a time.
case This argument changes case of the string value of the field. This argument has sub-arguments as follows:
  • lower - Converts the string value of the field to lower case.
  • upper - Converts the string value of the field to upper case.
  • title - Converts the string value of the field to title case.
Only one of the sub-arguments can be used at a time.
rem This argument has one regex sub-argument. This removes the parts of the string value of the field that match the specific regex.
Usage All primary arguments of this rule can be used at a time and the sub-arguments of each primary argument are separated by a dot(.) while primary arguments are separated by a comma(,). Example: 
const schema = {
    firstName: 'required|string|clean:spaces.both.between_single,case.title,rem.\\d+|max:50',
    lastName: 'required|string|clean:spaces.both.between_single,case.title,rem.\\d+|max:50',
    email: 'required|string|email|clean:spaces.both.between_none,case.title|max:50',
};

confirmed (String)

The field string value must match with the value of a field with similar name but with a suffix of _confirmation. Mostly useful with passwords, e.g. in case of password, two fields must be present, password and password_confirmation. This rule does not support values from extraArgs object.

card (String)

The field string value must be a valid primary card number. This card number validation uses Luhn algorithm to validate the card number. This rule does not support values from extraArgs object.

different:field (String)

The field string value must not be equal to value of field. This rule does not support values from extraArgs object.

email (String)

The field string value must be a valid email address. NB: This only checks for valid email characters. This rule does not support values from extraArgs object.

ends_with:value,... (String)

The field string value must end with either of value. This rule supports values from extraArgs object in form of an array.

filled (String)

The field string value must not be an empty string if the field is present. This rule does not support values from extraArgs object.

gt:field (String)

The field string value must have a length of greater than string value of field This rule does not support values from extraArgs object.

gte:field (String)

The field string value must have a length of greater than or equal to string value of field. This rule does not support values from extraArgs object.

in:value,... (String)

The field string value must be any of value. This rule supports values from extraArgs object in form of an array.

in_array:field.* (String)

The field string value must be one of the values of field. The field value must be either an array or an object which has array value in one of its properties. This rule does not support values from extraArgs object.

ip_address (String)

The field string value must be a valid IPv4 or IPv6 address. This rule does not support values from extraArgs object.

ipv4 (String)

The field string value must be a valid IPv4 address. This rule does not support values from extraArgs object.

ipv6 (String)

The field string value must be a valid IPv6 address. This rule does not support values from extraArgs object.

json (String)

The field string value must be a valid JSON object or string. This rule does not support values from extraArgs object.

gt:field (String)

The field string value must have a length of less than string value of field This rule does not support values from extraArgs object.

gte:field (String)

The field string value must have a length of less than or equal to string value of field. This rule does not support values from extraArgs object.

max:value (String)

The field string value must have a maximum length of value. This rule does not support values from extraArgs object.

min:value (String)

The field string value must have a minimum length of value. This rule does not support values from extraArgs object.

not_in:value,... (String)

The field string value must not be any of value. This rule supports values from extraArgs object in form of an array.

not_regex:pattern (String)

The field string value must not match the regular expression pattern. This rule supports values from extraArgs object in form of an array.

not_regex (String)

The field string value must consist of only numeric characters. This rule supports values from extraArgs object in form of an array.

present (String)

The field must be present but the value can be empty. This rule supports values from extraArgs object in form of an array.

regex:pattern (String)

The field string value must match the regular expression pattern. This rule supports values from extraArgs object in form of an array.

same:field (String)

The field string value must be equal to the string value of field. This rule supports values from extraArgs object in form of an array.

size:value (String)

The field string value must have a length of value. This rule supports values from extraArgs object in form of an array.

starts_with:value,... (String)

The field string value must start with either of value. This rule supports values from extraArgs object in form of an array.

timezone (String)

The field string value must be a valid timezone identifier string. Refer to moment timezones. This rule supports values from extraArgs object in form of an array.

url (String)

The field string value must be a valid URL. This rule supports values from extraArgs object in form of an array.

uuid (String)

The field string value must be a valid UUID or GUID. This rule supports values from extraArgs object in form of an array.

Licence

MIT

Happy coding!