README

common-validators

Library with common validators. Base logic: any empty value is valid (except required-validator); values are converted to a suitable format

Note: This module works in browsers and Node.js >= 4.0

Installation

npm install common-validators

Usage

const validators = require('common-validators');

validators.maxLength('abc', 2); //or validators.maxLength('abc', {arg: 2})
/* returns:
{
    message: 'is too long (maximum is 2)',
    error: 'maxLength', //validator name by default
    arg: 2
}
*/

validators.range(7, {from: 1, to: 5, lessMessage: 'is too less', moreMessage: 'is too many'});
/* returns (except options which end in `Message`):
{
    message: 'is too many',
    error: 'range.more',
    from: 1,
    to: 5
}
*/

Many of validators have names common for js, like required, minLength, etc. But if you have some conflicts you can rename any validator:

validators.minLengthValidator = validators.minLength
delete validators.minLength

validators.util is uncountable field with object of utils. You can use them for own validators like this.utils.toArray. Common validators has following utils:

toDateTime
toDate
isNumber
isFunction
isInteger
isBoolean
isArray
isDateTime
isString
isObject
isPlainObject
isDefined
isUndefinedOrNull
isEmpty
exists
contains
toArray
toNumber
toString
toObject
byteLength

API

Validators.add

Use these methods for adding custom validators in simple format (see src/common-validators-library.js). See more in validators-constructor documentation. Also you can use Object.assign(commonValidators, customValidators) in other situations

Validators.validatorName(value, [arg], [options])

value (Any) - Validated value
arg (Any) - Value for comparison. Have to exist and can not be an object or true. User can set it as options.arg. If you use 'arg' in your validator you must be sure that user will specify this value
options (Object) - Options
- arg (Any) - Will be set if arg is specified
- message (Any) - Override error message
- parse (Function) - Can change input value before validation
- (Any) - Any custom options
(Any) - Any custom arguments
return (Any) - undefined if valid or object with error description. You can use %{template} syntax in message strings (validated value is enabled as value, compared value - as arg)

Validators:

custom - uses custom validator from options
- arg (Function) - Custom function which get value and options and return result of validation (message or undefined)
required | presence - validates that the value isn't undefined, null, NaN, empty or whitespace only string, empty array or object
notEmpty - like required but undefined is valid value. It is useful for PATCH-requests

Types (valid if value is undefined)

object - value is plain object
array - value is array
string - value is string
number - value is number
integer - value is integer
date - value is date
boolean - value is boolean
function - value is function
null - value is null

Equality (valid if value is empty)

equal - value is equal to comparable value (deep equal for objects)
- arg (Any) - comparable value. Notice! If you use 'arg' as argument it need to exist and not to be object or boolean
- strict (Boolean) - Use strict comparison (===). true by default
confirm - option in object is equal to other option in the same object. Value need to be an object
- key (String) - first key in value
- comparedKey (String) - second key in value
- strict (Boolean) - Use strict comparison (===). true by default
```
confirm({
  name: 'User', password: '123', confirmedPassword: '123'
}, {
  key: 'password', comparedKey: 'confirmedPassword'
}); //valid
```

Numbers (valid if value is empty, value is converted to the number)

max - value is less than maximum
- arg (Number) - maximum
- exclusive (Boolean) - doesn't include arg. false by default
min - value is greater than minimum
- arg (Number) - minimum
- exclusive (Boolean) - doesn't include arg. false by default
range - value is in the range from minimum to maximum
- from (Number) - minimum. Error: range.more
- to (Number) - maximum. Error: range.less
- exclusive (Boolean) - doesn't include from and to. false by default
- exclusiveFrom (Boolean) - doesn't include from. false by default
- exclusiveTo (Boolean) - doesn't include to. false by default
- lessMessage - Error message if less
- moreMessage - Error message if more
equal - see Equality section above
odd - value is odd
even - value is even
divisible - value is divided by the divisor without a remainder
- arg (Number) - divisor

Length (valid if value is empty, value is converted to the array)

maxLength - value's length is less than maximum
- arg (Number) - maximum
minLength - value's length is greater than minimum
- arg (Number) - minimum
rangeLength - value's length is in the range from minimum to maximum (including)
- from (Number) - minimum. Error: rangeLength.more
- to (Number) - maximum. Error: rangeLength.less
- lessMessage - Error message if less
- moreMessage - Error message if more
equalLength - value's length is equal to comparable value
- arg (Number) - comparable value

Size in bytes (valid if value is empty, value is converted to the string or JSON-string)

maxSize - value's size is less than maximum
- arg (Number) - maximum
- stringify (Function) - stringify non string values. JSON.stringify by default
minSize - value's size is greater than minimum
- arg (Number) - minimum
rangeSize - value's size is in the range from minimum to maximum (including)
- from (Number) - minimum. Error: rangeSize.more
- to (Number) - maximum. Error: rangeSize.less
- lessMessage - Error message if less
- moreMessage - Error message if more
equalSize - value's size is equal to comparable value
- arg (Number) - comparable value

RegExp (valid if value is empty, value is converted to the string)

pattern - value matches the pattern
- arg (String or RegExp) - pattern

White and black list (valid if value is empty, value is converted to the array)

inclusion - value is contained in white list. If value is an array or object - every item must to be in the list.
- arg (Array or Object) - white list

inclusion('a', ['a', 'b', 'c']); //valid
inclusion('a', {a: 'smth'}); //valid
inclusion(['a', 'b'], ['a', 'b', 'c']); //valid
inclusion({a: 1, b: 2}, {a: 1, b: 2, c: 3}); //valid

exclusion - value is not contained in black list. If value is an array or object - neither item must to be in the list.
- arg (Array or Object) - black list

Date and time (valid if value is empty, value is converted to the date)

maxDateTime - value is less than maximum date
- arg (Date, String, Number, Moment or Array) - maximum date
- exclusive (Boolean) - doesn't include arg. false by default
minDateTime - value is greater than minimum date
- arg (Date, String, Number, Moment, Array) - minimum date
- exclusive (Boolean) - doesn't include arg. false by default
rangeDateTime - value is in the range from minimum to maximum dates (including)
- from (Date, String, Number, Moment or Array) - minimum date. Error: rangeDateTime.more
- to (Date, String, Number, Moment or Array) - maximum date. Error: rangeDateTime.less
- exclusive (Boolean) - doesn't include from and to. false by default
- exclusiveFrom (Boolean) - doesn't include from. false by default
- exclusiveTo (Boolean) - doesn't include to. false by default
- lessMessage - Error message if less
- moreMessage - Error message if more
equalDateTime - value is equal comparable date
- arg (Date, String, Number, Moment or Array) - comparable date
maxDate - value is less than maximum date (time is ignored)
- arg (Date, String, Number, Moment or Array) - maximum date
- exclusive (Boolean) - doesn't include arg. false by default
minDate - value is greater than minimum date (time is ignored)
- arg (Date, String, Number, Moment or Array) - minimum date
- exclusive (Boolean) - doesn't include arg. false by default
rangeDate - value is in the range from minimum to maximum dates (including, time is ignored)
- from (Date, String, Number, Moment or Array) - minimum date. Error: rangeDate.more
- to (Date,String, Number, Moment or Array) - maximum date. Error: rangeDate.less
- exclusive (Boolean) - doesn't include from and to. false by default
- exclusiveFrom (Boolean) - doesn't include from. false by default
- exclusiveTo (Boolean) - doesn't include to. false by default
- lessMessage - Error message if less
- moreMessage - Error message if more
equalDate - value is equal comparable date (time is ignored)
- arg (Date, String, Number, Moment or Array) - comparable date

Web (valid if value is empty, value is converted to the string)

email - value is email address
url - value is URL
- allowLocal (Boolean) - allows local hostnames such as 10.0.1.1 or localhost
- protocols (Array) - allows to use different protocols. Default: ['http', 'https']
ipAddress - value is IP address or hostname
- ipv4 (Boolean) - value is IPv4 address. true by default
- ipv6 (Boolean) - value is IPv6 address. true by default
- hostname (Boolean) - value is hostname (RFC 1123). true by default

Files (valid if value is empty, value is converted to the array)

You also can set fileList to options.files. It is useful for input with type="file" validation, when you have file path in event.target.value (set it as value) and fileList in event.target.files (set it as options.files)

accept - every file hase allowed type (accept="image/jpeg,image/png,.webp,video/*"). You can use mime types or extensions
minFileSize - size of every file is more then minimum

arg (Number) - minimum in bytes

maxFileSize - size of every file is less then maximum

arg (Number) - maximum in bytes

equalFileSize - size of every file equal then comparable value

arg (Number) - comparable value in bytes

minFileSizeAll - size of all files is more then minimum

arg (Number) - minimum in bytes

maxFileSizeAll - size of all files is less then maximum

arg (Number) - maximum in bytes

equalFileSizeAll - size of all files equal then comparable value

arg (Number) - comparable value in bytes

minFileNameLength - name of every file is more then minimum

arg (Number) - minimum in bytes

maxFileNameLength - name of every file is less then maximum

arg (Number) - maximum in bytes

Tests (for debugging)

alwaysValid - every value is valid
alwaysInvalid - every value is invalid

Tests

npm install
npm test

License

MIT

Usage no npm install needed!