validator-fns v1.10.1

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.

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.

Validation error message

The message argument in the validation tests must be a static string, a template string, or a function returning a string.

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.

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.

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.

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.

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.

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.

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.

integer(message)

Ensures value is an integer number. Works with numbers.

matches(pattern, message)

Ensures value matches the specified pattern. Works with strings. pattern is provided to the 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.

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.

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.

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.

oneOf(values, message)

Ensures value is one of the specified values. Works with strings, arrays, booleans, and dates. values is provided to the message.

required(message, nullable?)

Ensures value is not one of: undefined, null, NaN, an empty string, or an invalid date. Works with all types.

url(message, protocols?)

Ensures value is a valid URL. Works with strings. protocols is provided to the message.

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