README
validate-core
A set of data validation utilities.
Features
Single data validation: check validity in an atomic way.
Validate against a set of constraints.
Lightweight
- Bundled:
~9.7 KB - min/gzip:
~3.5 KB
- Bundled:
Available validators:
Yet another validation library? Why?
This library is based on the robust validate.js. Even when validate.js will work just fine in most scenarios, sometimes you just need its core or part of it:
- ES6 Modules: call specific modules in your project, only what you need.
- No legacy code: don't care about jQuery and old stuff.
Install
yarn add validate-core
or
npm install validate-core
Basic Usage
Examples:
import { validate } from 'validate-core'
validate('email@test.com', { email: true, presence: true })
// => undefined
validate('email@test', { email: true, presence: true })
// => ["is not a valid email"]
validate('', { email: true, presence: true })
// => ["can't be blank"]
Using a specific validator
It's possible to import calling a specific validator module.
Syntax:
import <validatorName> from 'validate-core/validators/<validatorName>'
Examples:
import presence from 'validate-core/validators/presence'
presence('something') // => undefined
presence('') // => ["can't be blank"]
import date from 'validate-core/validators/email'
email('email@test.com') // => undefined
email('email@test') // => ["is not a valid email"]
API
General concepts
The validate() function
The library default export is a function that accepts a value as first parameter (the one you want to validate), and an object with a set of constraints as the second one:
Syntax:
import { validate } from 'validate-core'
validate(value, { ...constraints })
Example:
import { validate } from 'validate-core'
validate('email@test.com', {
email: true,
presence: true,
})
// => undefined
Constraints and options
The validate() function accepts as second parameter an object with the constraints (or rules) the value should match. This object should have the following syntax:
{
validatorX: { ...optionsForValidatorX },
validatorY: { ...optionsForValidatorY },
/// ...
}
Some validators have "shortcuts" that override the constraints object with a single value.
Example with the format validator:
// With a constraint object
validate('myusername', {
format: {
pattern: /^@?(\w){1,15}$/,
message: 'is not a valid Twitter account',
},
})
// => ["is not a valid Twitter account"]
// With a shortcut
validate('myusername', {
format: /^@?(\w){1,15}$/,
})
// => ["format is invalid"]
Note that in the shortcut version you cannot customize the error message.
Return values
validate() will return:
undefinedwhen there is no error.- an
arraywith one or more strings that explain what failed.
Individual validators will return almost the same output, except in some cases when they can return a string instead.
Custom formatMessage function
Some validators support providing a custom string formatter function using the formatMessage option.
The validators that support this are: datetime, equality, exclusion, inclusion, length, numericality and type.
The function has two parameters:
- a
message, with placeholders to replace. - an
objectwithreplacers: keys used to replace the placeholders with their values.
NOTE:
formatMessagerequires a custommessagein the options.
Example for a custom message formatter for length():
import { validate } from 'validate-core'
// Using hashes for placeholders
const myCustomMesage = 'length is not exactly #is#'
// Note: length() provides the following replacers:
// - is
// - minimum
// - maximum
const myFormatter = (message = '', replacers = {}) => {
return message.replace(/#(\w+)#/g, (match, placeholder) => {
// console.log({ match, placeholder })
return replacers[placeholder] || placeholder
})
}
validate('123456', {
length: {
is: 5,
message: myCustomMesage,
formatMessage: myFormatter,
},
})
// => ["length is not exactly 5"]
Validators
date
The date validator is just a shorthand for the datetime validator with the dateOnly option set to true.
Examples:
import { validate } from 'validate-core'
validate(new Date('2010-10-01'), {
date: true,
})
// => undefined
validate(new Date('2010-10-01 12:34:56'), {
date: true,
})
// => ["must be a date (not a datetime)"]
datetime
This validator can be used to validate dates and times. Since date parsing in javascript is very poor, some additional work is required to make this work.
Before this validator can be used, the parse and format functions need to be set. The parse function should take the value to parse (non null but otherwise untouched) and return the unix timestamp (in milliseconds) for that date or NaN if it's invalid.
It's important to mention that the constraints (laterThan, earlierThan) will also be parsed using this method. These arguments will be parsed using the parse function, just like the value.
The format function should take a unix timestamp (in milliseconds) and format it in a user friendly way.
You can specify the follow constraints:
laterThan: The date cannot be before this time.earlierThan: The date cannot be after this time.dateOnly: Iftrue, only dates (not datetimes) will be allowed. Default:false.
You can change the messages by setting any of these settings the options for the validator:
notValid(default:must be a valid date).dateOnlyMessage: (default:must be a date (not a datetime)).tooEarly(default:must be later than %{date}).tooLate(default:must be earlier than %{date}).
You can use the placeholders %{value} and %{date} in the messages.
Examples:
import { validate } from 'validate-core'
validate(new Date('2010-10-01 12:34:56'), {
datetime: true,
})
// => undefined
validate(new Date('2010-10-01'), {
datetime: {
dateOnly: true,
},
})
// => undefined
validate(new Date('2010-09-15'), {
datetime: {
laterThan: new Date('2010-10-01'),
tooEarly: 'choose a date after %{date}',
earlierThan: new Date('2010-10-31'),
tooLate: 'choose a date before %{date}',
},
})
// => ["choose a date after 2010-10-01"]
email
The email validator attempts to make sure that the input is a valid email. Validating emails is tricky business due to the complex rules of email address formatting.
For example john.doe@gmail is a perfectly valid email but it's most likely just the case that John has forgotten to write .com at the end.
validate-core (as is based on validate.js) tries to be pragmatic and allows most valid emails, but tries to catch common typos such as forgetting the TLD.
If you want to know more about email validation the Wikipedia article and the email page on regular-expressions.info are good places to start.
You can customize the regexp used by setting the pattern option to a regexp of your choosing. Just remember that javascript regexp does substring matching.
The default message is is not a valid email and as usual you can override it using the message option.
Examples:
import { validate } from 'validate-core'
validate('nice@email.com', { email: true })
// => undefined
validate('bad@email', { email: true })
// => ["is not a valid email"]
validate('bad@email', { email: { message: 'wrong e-mail format' } })
// => ["wrong e-mail format"]
equality
The equality validator can be used to verify that one attribute is always equal to another.
This is useful when having a "confirm password" input, for example.
You specify which attribute by simply passing its value as the options for the validator or by giving the option attribute with the value inside.
By default === is used to check the quality, it you need to validate more complex objects you can give a function using the comparator option which should be a function that accepts two arguments and returns true if they objects are equal and false if they are not.
The default message is is not equal to %{attribute}
Examples:
import { validate } from 'validate-core'
validate(123, { equals: 123 })
// => undefined
validate('foo', { equals: { attribute: 'foo' } })
// => undefined
validate('foo', { equals: 'bar' })
// => ["is not equal to bar"]
format
The format validator will check a value against a regular expression of your choosing. The default message if the value doesn't match is is invalid so you'll likely want to customize it by setting message to something in the options.
The pattern option can either be a javascript regexp or string that will be passed to the RegExp constructor. If the pattern is a string and you want to specify flags, you may use the flags option.
Please note that the whole string must match the regexp, not just a part of the value.
Examples:
import { validate } from 'validate-core'
validate('(123) 456-7890', {
format: /^\D?(\d{3})\D?\D?(\d{3})\D?(\d{4})$/, // US Phone format
})
// => undefined
validate('(123) 456-7890', {
format: {
pattern: '^D?(d{3})D?D?(d{3})D?(d{4})