validator-fns

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 | github

• Install
• Usage
• API Reference
  • Validation result
  • Validation error message
  • Validation types
  • Validation tests
  • Custom validation
• Supported environments

Install

npm install validator-fns
# or
yarn add validator-fns

Usage

This 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: 'foo@example.com',
  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);
}

API Reference

Validation result

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.

Validation error message

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.

Validation types

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)

array(config?, itemTest, ...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.

boolean(config?, ...tests)

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.

date(config?, ...tests)

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.

number(config?, ...tests)

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.

object(schema)

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.

string(config?, ...tests)

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.

Validation tests

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?)

email(message)

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.

exact(limit, 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.

integer(message)

Ensures value is an integer number. Works with numbers.

arguments

name	type	description
message	string or function	The validation error message.

matches(pattern, 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.

max(limit, message, exclusive?)

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.

maxDate(limit, message, exclusive?)

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.

min(limit, message, exclusive?)

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.

minDate(limit, message, exclusive?)

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.

oneOf(values, message)

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.

required(message, nullable?)

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.

url(message, protocols?)

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

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)

formatMessage(template, params)

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.

createTypeValidatorTest(defaultConfig, applyConfig)

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.

valid({ value, field })

Formats a successful validation result. value is the parsed value and field is the name of the object schema property.

invalid({ message, value, field, errors, extras })

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.

Supported environments

• 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:

• Promise
• async, await
• Array.prototype.find
• URL
• Rest (...) parameters
• Object spread (...) operators
• Optional catch binding
• And possibly others