Small asynchronous validation library. Tries to be as small as possible and use no external dependencies. Note that this library does not include localized error messages. API inspired by yup. Built using TypeScript and includes definition files. This library targets modern browsers only--configure your build accordingly.
npm install validator-fns
# or
yarn add validator-fnsThis is a fairly exhaustive example of what's possible with validator-fns.
example
import {
array,
boolean,
date,
email,
exact,
integer,
matches,
max,
maxDate,
min,
minDate,
number,
object,
oneOf,
required,
string,
url,
valid,
invalid,
} from 'validator-fns';
// optionally, you can do
// import * as validatorFns from 'validator-fns';
const ONE_DAY = 1000 * 60 * 60 * 24;
const TEN_DAYS = ONE_DAY * 10;
const now = new Date();
const tenDaysFromNow = new Date(now.getTime() + TEN_DAYS);
function customValidator(value, field) {
if (value === 'hello') {
return valid({ value, field });
}
return invalid({
message: 'Must be "hello".',
value,
field,
});
}
const validate = object({
firstName: string(
{ default: '', trim: true },
required('First name is required.'),
),
emailAddress: string(
required('Email address is required.'),
email('Must be a valid email address.'),
),
age: number(
{ round: 'floor' },
required('Age is required.'),
integer('Age must be a whole number.'),
min(18, 'Must be at least {min} years old.'),
),
homepage: string(url('Must be a valid URL.', ['http:', 'https:'])),
fruit: string(
{ default: 'apple' },
oneOf(
['apple', 'orange', 'banana'],
({ values }) => `Must be ${values[0]}, ${values[1]} or ${values[2]}.`,
),
),
favoriteCarMakers: array(
{ default: [] },
string(
required('Car brand is required.'),
oneOf(
[
'BMW',
'Ferrari',
'Fiat',
'Ford',
'Honda',
'Kia',
'Mercedes',
'Subaru',
'Tesla',
'Toyota',
'Volvo',
],
'Must be a known car brand.',
),
),
min(2, 'Must pick at least two.'),
max(4, 'Must pick at most four.'),
),
startDate: date(
minDate(now, 'Must be on or after today.'),
maxDate(tenDaysFromNow, 'Must be at most ten days from now.'),
),
optIn: boolean(required('Must decide to opt in or out.')),
notRobot: number(
required('Must enter the correct answer.'),
exact(42, 'This is the answer.'),
),
postalCode: string(matches(/^[0-9]{5}$/, 'Must be a five-digit number.')),
custom: customValidator,
});
// later...
const result = await validate({
age: 20,
custom: 'hello',
emailAddress: '[email protected]',
favoriteCarMakers: ['Ferrari', 'Tesla'],
firstName: 'Bob',
fruit: 'apple',
homepage: 'https://www.example.com',
notRobot: 42,
optIn: false,
postalCode: '12345',
startDate: new Date(),
});
if (result.state === 'valid') {
// do something with the parsed values
console.log(result.value);
} else {
// handle and display errors
console.error(result.errors);
}All validation tests yield one of two results: valid and invalid. Both are objects.
| property | type | description |
|---|---|---|
state |
string | Either valid or invalid. |
field |
string | Either the field name or undefined. |
value |
any | The parsed value. |
message |
string | The error message unless state is valid. |
errors |
any | Only if state is invalid and using the object or array validators. |
isValid |
boolean | Deprecated. Use state instead. |
The message argument in the validation tests must be a static string, a template string, or a function returning a string.
| type | example |
|---|---|
| static string | 'Username is required.' |
| template string | 'Password must be at least {min} characters.' |
| function | ({ value, field, max }) => `${field} must be less than ${max} but was ${value}.` |
The parsed value is always provided. If available, field is also provided. Depending on the validator, additional fields may be available.
A validation type is expected to parse and prepare the value for the provided validation tests. For example, the string validation type ensures the provided value is a string, null or undefined. It must be a function that takes a value of any type and returns a promise which resolves to a validation result (see above).
- array(config?, itemTest, ...tests)
- boolean(config?, ...tests)
- date(config?, ...tests)
- number(config?, ...tests)
- object(schema)
- string(config?, ...tests)
Casts value to an array, null or undefined if using the default date parser. config is optional. itemTest is the validation type or test to be applied on each value within the array value. All remaining tests are applied to the array as a whole.
Supported validation tests: max, min, and required.
For invalid results, errors are in the errors property. It is an array of type:
type ArrayErrors = Array<string | null>;Where valid entries are represented as null and invalid entries with the error message as a string.
config
| option | type | description |
|---|---|---|
default |
string | Optional. Value used if the parser returns undefined, null, or an empty array []. |
parser |
function | Optional. Used to customize how a value is converted into a string. |
Casts value to a boolean, null or undefined if using the default boolean parser. config is optional.
Supported validation tests: oneOf and required.
config
| option | type | description |
|---|---|---|
default |
boolean | Optional. Value used if the parser returns undefined or null. |
parser |
function | Optional. Used to customize how a value is converted into a boolean. |
Casts value to a date, null or undefined if using the default date parser. config is optional.
Supported validation tests: maxDate, minDate, oneOf, and required.
config
| option | type | description |
|---|---|---|
default |
date | Optional. Value used if the parser returns undefined, null, or an invalid date. |
parser |
function | Optional. Used to customize how a value is converted into a date. |
The default parser only accepts dates, numbers, and a subset of ISO 8601 formatted strings (excludes week formats). If you want to allow other or more complex formats you should use a third-party library such as date-fns.
Casts value to a number, null or undefined if using the default number parser. config is optional.
Supported validation tests: exact, integer, max, min, oneOf, and required.
config
| option | type | description |
|---|---|---|
round |
string | Optional. Rounding method to use, one of nearest, ceil, floor |
default |
number | Optional. Value used if the parser returns undefined, null or an invalid number NaN. |
parser |
function | Optional. Used to customize how a value is converted into a number. |
The only validation type that does not cast the entered value, meaning it does not use a parser. There's also no default fallback value option here. Instead, the schema is an object where its properties are validation types such as string, array, number, etc. Nested object validators are allowed, but not recommended due to their complexity and potential performance hit.
For invalid results, errors are in the errors property. It matches the provided object with the same keys and strings or string records as values that contain the error messages.
Unlike yup, this API does not (yet at least) have a ref option.
To use this with a library such as Formik, you can use the resulting errors property. It is a key-value structure with the schema property keys and their validation errors if any. Besides that, the object validation results are the same as described above.
Casts value to a string, null or undefined if using the default string parser. config is optional.
Supported validation tests: email, exact, matches, max, min, oneOf, required, and url.
config
| option | type | description |
|---|---|---|
trim |
boolean | Optional. If true, clears whitespace from the start and end of the string. |
default |
string | Optional. Value used if the parser returns undefined, null, or an empty string ''. |
parser |
function | Optional. Used to customize how a value is converted into a string. |
A validation test is a simplified version of a validation type. It accepts a value of a specific type including null and undefined and then returns a promise that resolves to a validation result. You can use a validation test directly without the validation type, but it's not recommended as you lose the parsing step and you can't apply multiple tests to the same field as easily.
- email(message)
- exact(limit, message)
- integer(message)
- matches(pattern, message)
- max(limit, message, exclusive?)
- maxDate(limit, message, exclusive?)
- min(limit, message, exclusive?)
- minDate(limit, message, exclusive?)
- oneOf(values, message)
- required(message, nullable?)
- url(message, protocols?)
Ensures the value follows an email address format. Wraps the matches validation test. Works with strings.
arguments
| name | type | description |
|---|---|---|
message |
string or function | The validation error message. |
Ensures value is of an exact amount. Works with strings, arrays, and numbers. limit (aliased as exact) and amount (the string length, array length, or numeric value) are provided to the message.
arguments
| name | type | description |
|---|---|---|
limit |
number | The exact string length, array length, or numeric value allowed. |
message |
string or function | The validation error message. |
Ensures value is an integer number. Works with numbers.
arguments
| name | type | description |
|---|---|---|
message |
string or function | The validation error message. |
Ensures value matches the specified pattern. Works with strings. pattern is provided to the message.
arguments
| name | type | description |
|---|---|---|
pattern |
regular expression | The regular expression to match against. |
message |
string or function | The validation error message. |
Ensures value is of at most limit. Works with strings, arrays, and numbers. limit (aliased as min), amount (string length, array length, or numeric value), and exclusive are provided to the message.
arguments
| name | type | description |
|---|---|---|
limit |
number | The maximum string length, array length, or numeric value allowed. |
message |
string or function | The validation error message. |
exclusive |
boolean | Optional. If true, makes comparison exclusive instead of the default, inclusive. |
Ensures value is on or before the specified date. Works with dates. limit (aliased as max) and exclusive are provided to the message.
arguments
| name | type | description |
|---|---|---|
limit |
date, number, or string | The maximum date allowed. Uses the internal date parser. |
message |
string or function | The validation error message. |
exclusive |
boolean | Optional. If true, makes comparison exclusive instead of the default, inclusive. |
Ensures value is of at least limit. Works with strings, arrays, and numbers. limit (aliased as min), amount (string length, array length, or numeric value), and exclusive are provided to the message.
arguments
| name | type | description |
|---|---|---|
limit |
number | The minimum string length, array length, or numeric value allowed. |
message |
string or function | The validation error message. |
exclusive |
boolean | Optional. If true, makes comparison exclusive instead of the default, inclusive. |
Ensures value is on or after the specified date. Works with dates. limit (aliased as min) and exclusive are provided to the message.
arguments
| name | type | description |
|---|---|---|
limit |
date, number, or string | The minimum date allowed. Uses the internal date parser. |
message |
string or function | The validation error message. |
exclusive |
boolean | Optional. If true, makes comparison exclusive instead of the default, inclusive. |
Ensures value is one of the specified values. Works with strings, arrays, booleans, and dates. values is provided to the message.
arguments
| name | type | description |
|---|---|---|
values |
array | List of allowed values. May be strings, numbers, booleans, or dates. |
message |
string or function | The validation error message. |
Ensures value is not one of: undefined, null, NaN, an empty string, or an invalid date. Works with all types.
arguments
| name | type | description |
|---|---|---|
message |
string or function | The validation error message. |
nullable |
boolean | Optional. If true, allows null. |
Ensures value is a valid URL. Works with strings. protocols is provided to the message.
arguments
| name | type | description |
|---|---|---|
message |
string or function | The validation error message. |
protocols |
array | List of allowed URL protocols, e.g. https:, mailto:. |
Custom validation types and validators can be created and used as needed. There are some helpers that, while used internally, are considered part of the public API.
- formatMessage(template, params)
- createTypeValidatorTest(defaultConfig, applyConfig)
- valid(value, field)
- invalid(message, value, field, extras)
Formats a string for use as an error message. template can be a plain string with {keys} replaced by the params or a function that returns a string and accepts params as a parameter.
Useful helper for simple validation types such as strings, numbers, etc. defaultConfig is the configuration object that the applyConfig function will use when parsing the value being validated. At least this should include a parser function.
Formats a successful validation result. value is the parsed value and field is the name of the object schema property.
Formats a failed validation result. message is the same as the formatMessage's template. value and field is the same as above, errors is additional error details used by array and object validators, and extras are optional extra parameters that can be used in the message.
- Node.js 12+, but may work in older Node.js versions.
- ES2019 compatible browsers, which essentially is all modern evergreen browsers and Safari 13.1+. If you need to target IE11, for example, ensure you use a compiler such as Babel.js.
Older environments may require polyfill or transpile for the following:
Promiseasync,awaitArray.prototype.findURL- Rest (
...) parameters - Object spread (
...) operators - Optional catch binding
- And possibly others