Validation

Validates objects, optionally coercing values into other types.

Usage

Validators and types are all exported from the root:

import { any, text } from '@fmtk/validation';

Validators are functions which return a function which actually does the validation.

// require a string
const validator = text();

const result = validator({ value: 'foo' });

Most likely, you'll want to validate whole objects:

const personValidator = properties({
  name: text(),
  age: optional(integer()),
  dateOfBirth: dateFormat('YYYY-MM-DD'),
});

personValidator({
  value: { name: 'Bob', age: '5', dateOfBirth: '2013-12-05' },
  mode: ValidationMode.String,
});
// ===> {
//    value: {
//      name: 'Bob',
//      age: 5,
//      dateOfBirth: new Date('2013-12-05T00:00:00.000')
//    },
//    ok: true
//  }

personValidator({ value: { name: 'Bob' } });
// ===> {
//    value: { name: 'Bob' },
//    errors: [
//      {
//        id: 'EXPECTED_DATE_FORMAT',
//        text: 'expected a date',
//        field: 'dateOfBirth'
//      }
//    ]
// }

Validators

The library defines validators for various data types and formats.

All validators return an implementation of ValueValidator, i.e., a function that takes a ValidationContext as its only parameter, and returns a ValidationResult.

ValidationContext

Properties:

field	description
value	the value to validate
field	the name of the field under validation (for properties or modelValidator)
mode	the validation mode

ValidationMode

enum ValidationMode {
  Strict = 'strict',
  JSON = 'json',
  Form = 'form',
  String = 'string',
}

ValidationResult

field	description
value	the value after validation - allows values to be coerced, e.g., integer() turns '1' into 1
errors	an array of ValidationError if there are any

ValidationError

field	description
id	the error ID
text	the error message
field	the field the error relates to, if applicable
extra	any extra info, if applicable

any()

Don't perform validation. This will accept any input and never return an error.

array(element: ValueValidator<T>, arraySplit?: string)

Expect the value to be an array.

Params:

field	description
elem	a validator to validate each element in the array
arraySplit	the character to split a string on (default ',')

If ValidationOptions.parse is true, the validator will first create an array from the input by splitting by arraySplit.

bool()

Require a boolean value.

If ValidationOptions.parse is true, the string values true and false are accepted.

or(...validators: ValueValidator<T>)

Creates a validator that requires at least one of the supplied validators to be valid.

and(...validators: ValueValidator<T>)

Creates a validator that requires all supplied validators to be valid.

dateFormat(format: string | moment.MomentBuiltinFormat)

Validates a date/time against the given format.

The format argument is only relevant if If ValidationOptions.parse is true, and the input is a string. In this case, it will parse the string with moment and the given format.

If the input is a Date it is always valid, regardless of the format.

email()

Require an email address.

Expects a string to match the following regex: /^[^@]+@[^@]+$/

integer(opts?: { minValue?: number, maxValue?: number })

Require an integer value. The options minValue and maxValue are inclusive.

is(...values: T[])

Require one of a list of values.

notProvided(opts: { string?: boolean })

Require a value not to be present.

optional(validator: ValueValiator<T>)

Make a value optional.

password(minScore = 3)

Validate a password against a complexity score.

minScore should be between 0 and 4 inclusive.

real()

Require a real value (floating point).

If ValidationOptions.parse is true, the number is parsed from a string if applicable.

text(maxLength?: number, minLength=1)

Require a text value.

ukmobile()

Validates a string as a UK mobile number, coercing it to E.164 format.

properties(model: ModelDefinition<T>, allowExtraFields=false)

Validates an object, taking a hash which describes the fields. E.g.:

properties({
  name: text(),
  age: optional(integer()),
});