validators | @paychex/core

Contains Validator factories useful for verifying that values conform to desired specifications.

// esm
import { validators } from '@paychex/core';

// cjs
const { validators } = require('@paychex/core');

// iife
const { validators } = window['@paychex/core'];

// amd
require(['@paychex/core'], function({ validators }) { ... });
define(['@paychex/core'], function({ validators }) { ... });

Index

Interfaces

Functions

array

array(message: string): Validator<AggregateValidationError>
array(validator: Validator<ValidationError>, message: string): Validator<AggregateValidationError>

- Defined in validators/index.ts:315
Ensures the value is an array.
example
```
// if you do not specify a validator to apply, the
// value will still be validated as an array
const items = validators.array('items must be an array');

// invalid
items({}).catch(console.log);
> ValidationError: items must be an array
```
throws
An error message must be provided.
Parameters
- message: string
  
  The error message to use if the validation fails.
Returns Validator<AggregateValidationError>
A validation function

Ensures the value is an array and that each item in the array matches the specified validator.

example

const item = validators.object({
  sku: validators.string('sku is required'),
  amount: validators.number('amount is missing'),
}, 'invalid item');

const cart = validators.object({
  items: validators.array(item, 'invalid cart items'),
}, 'cart is invalid');

// non-conforming value
cart({
  items: [{ amount: 2 }], // missing sku
}).catch(console.error);
> ValidationError: cart is invalid
  - inner: [ValidationError: invalid cart items]
    - inner: [ValidationError: sku is required]

// conforming value
const valid = await cart({
  items: [{ sku: '123', amount: 2 }]
}).then(() => true, () => false);

throws

An error message must be provided.

Parameters

validator: Validator<ValidationError>

The validation function to apply to each element in the array.
message: string

The error message to use if the validation fails.

Returns Validator<AggregateValidationError>

A validation function

date

date(message: string): Validator<ValidationError>

Ensures a value is a date.

example

const timestamp = validators.date('timestamp is required');

// non-conforming value
timestamp('123').catch(console.error);
> ValidationError: timestamp is required

// conforming value
const valid = await timestamp(new Date())
  .then(() => true, () => false);

// as part of object schema
const record = validators.object({
  id: validators.string('id is required'),
  created: validators.date('creation date is missing'),
}, 'record is invalid');

throws

An error message must be provided.

Parameters

message: string

The error message to use if the validation fails.

Returns Validator<ValidationError>

A validation function

empty

empty(message: string): Validator<ValidationError>

Ensures the proposed value is empty. Empty values include null and undefined. Objects are considered empty if they have no own enumerable string keyed properties. Array-like values such as arguments objects, arrays, buffers, strings, or jQuery-like collections are considered empty if they have a length of 0. Similarly, maps and sets are considered empty if they have a size of 0.

throws

An error message must be provided.

example

const validResult = validators.object({
  data: validators.every('any value is allowed'),
  error: validators.empty('should not have an error'),
}, 'result is invalid');

example

// use not(empty(''), '...') to ensure a value is provided
const feedback = validators.object({
  timestamp: validators.date('valid timestamp required'),
  comments: validators.not(validators.empty(''), 'comments are required'),
}, 'invalid feedback');

example

// combine validators together to ensure a value of a specific
// type is provided _and_ is not empty
export const nonEmptyString = (name) => validators.every([
  validators.string(`${name} must be a string`),
  validators.not(validators.empty(''), `${name} is required`),
], `${name} must be a non-empty string`);

Parameters

message: string

The error message to use if the validation fails.

Returns Validator<ValidationError>

A validation function

every

every(validators: Validator<ValidationError>[], message: string): Validator<AggregateValidationError>
every(message: string): Validator<AggregateValidationError>

Ensures the proposed value passes all of the specified validators.

NOTE: You can use this validator to extend an existing set of validations with additional validation checks.

See the examples for details.

throws

An error message must be provided.

throws

A non-validator was provided.

example

// compose multiple validators together

export const nonEmptyString = (name) => validators.every([
  validators.string(`${name} must be a string`),
  validators.not(validators.empty(''), `${name} is required`),
], `${name} must be a non-empty string`);

// usage:
const user = validators.object({
  id: nonEmptyString('user id'),
}, 'user is invalid');

example

// extend an existing validation

const auditEntry = validators.object({
  timestamp: validators.date('timestamp is invalid'),
  message: validators.string('message must be a string'),
  allowed: validators.oneOf([true, false], 'allowed must be a boolean'),
}, 'invalid audit entry');

export const baseUser = validators.object({
  id: validators.string('user id is required'),
  access: validators.oneOf(['user', 'admin'], 'invalid access level'),
}, 'base user is invalid');

export const auditedUser = validators.every([
  baseUser, // all the validations of a base user, plus...
  validators.object({
    audits: validators.array(auditEntry, 'invalid audit trail'),
  }, 'audit trail missing'),
], 'audited user is invalid');

Parameters

validators: Validator<ValidationError>[]

Zero or more Validator functions to apply. You can specify an array or just pass the validators as direct arguments.
message: string

The error message to use if the validation fails.

Returns Validator<AggregateValidationError>

A validation function

Creates a validator where the value will always be valid. You can use this to indicate that any value is acceptable.

throws

An error message must be provided.

example

// data responses can have optional payloads
const validateResponse = validators.object({
  meta: validators.object({}, 'object expected'),
  data: validators.every('any value is allowed'),
}, 'response is invalid');

async function throwIfInvalid(response) {
  await validateResponse(response);
  return response.data;
}

export function loadData(arg1, arg2) {
  const params = { arg1, arg2 };
  const request = data.createRequest(operation, params);
  return fetch(request)
    .then(throwIfInvalid)
    .catch(errors.rethrow(params));
}

Parameters

message: string

The error message to use if the validation fails.

Returns Validator<AggregateValidationError>

A validation function

instanceOf

instanceOf(type: Function, message: string): Validator<ValidationError>

Ensures the proposed value is an instance of the specified type.

throws

An error message must be provided.

throws

A class type must be provided.

example

const regex = validators.instanceOf(RegExp, 'invalid regular expression');

// conforming
await regex(/rx/);

// non-conforming
regex('abc').catch(console.error);
> ValidationError: invalid regular expression

example

// utility validator
const error = (message) => validators.instanceOf(Error, message);

// usage
const bugReport = validators.object({
  failure: error('failure reason expected'),
  comments: validators.string('invalid user comments'),
}, 'invalid bug report');

Parameters

type: Function

The type function to check against.
message: string

The error message to use if the validation fails.

Returns Validator<ValidationError>

A validation function

matches

matches(rx: RegExp, message: string): Validator<ValidationError>

Matches the proposed value against a regular expression.

throws

An error message must be provided.

throws

A regular expression must be provided.

example

const rx = /^[\da-f]{8}-[\da-f]{4}-[0-5][\da-f]{3}-[089ab][\da-f]{3}-[\da-f]{12}$/i;
const uuid = validators.matches(rx, 'a uuid is required');

// conforming
const valid = await uuid('35543cdb-5ac3-477f-ac86-ce8796b68cc6')
  .then(() => true, () => false);

// non-conforming
uuid('abc').catch(console.error);
> ValidationError: a uuid is required

Parameters

rx: RegExp

The Regular Expression to match against.
message: string

The error message to use if the validation fails.

Returns Validator<ValidationError>

A validation function

not

not(validator: Validator<ValidationError>, message: string): Validator<ValidationError>

- Defined in validators/index.ts:549
Negates the specified validator. In other words, if the validator rejects, this validation will resolve. If the validator resolves, this validation will reject with the specified error message.
throws
An error message must be provided.

throws
A validator function must be provided.

example
```
const isEmpty = validators.empty('value is not empty');
const isNotEmpty = validators.not(isEmpty, 'value is empty');

// conforming
await isNotEmpty([1, 2, 3]);

// not conforming
isNotEmpty([]).catch(console.error);
> ValidationError: value is empty

isNotEmpty({}).catch(console.error);
> ValidationError: value is empty

isNotEmpty(null).catch(console.error);
> ValidationError: value is empty
```
Parameters
- validator: Validator<ValidationError>
  
  The validator to negate.
- message: string
  
  The error message to use if the validation fails.
Returns Validator<ValidationError>
A validation function

number

number(message: string): Validator<ValidationError>

Ensures a value is a number.

example

const age = validators.number('age is required');

// non-conforming value
age('123').catch(console.error);
> ValidationError: age is required

// conforming value
const valid = await age(29)
  .then(() => true, () => false);

// as part of object schema
const cartItem = validators.object({
  sku: validators.string('sku is required'),
  name: validators.string('item name is required'),
  amount: validators.number('amount is required'),
}, 'cart item is invalid');

throws

An error message must be provided.

Parameters

message: string

The error message to use if the validation fails.

Returns Validator<ValidationError>

A validation function

object

object(schema: {}, message: string): Validator<AggregateValidationError>

Ensures an object conforms to the specified schema, where each property is run against the associated Validator.

NOTE: The proposed object will only be checked against the property names specified in the schema. If the object has additional properties, it will still be considered conforming so long as the schema is satisfied. However, if the object has fewer properties than specified in the schema, it will be considered invalid.

example

// use an empty schema to allow _any_ object type
const isobject = validators.object({}, 'object expected');

// conforming
await isobject({ key: 'value' });

// non-conforming
isobject([]).catch(console.error);
> ValidationError: object expected

example

const user = validators.object({
  age: validators.number('age must be numeric'),
  name: validators.string('name must be a string'),
}, 'user is invalid');

// non-object provided
user([]).catch(console.error);
> ValidationError: user is invalid

// object is missing a `name` property,
// which was defined in the schema
user({ age: 41 }).catch(console.error);
> ValidationError: user is invalid

example

const user = validators.object({
  age: validators.number('age must be numeric'),
  name: validators.string('name must be a string'),
}, 'user is invalid');

// non-conforming value
user({
  age: 21,
  name: new Date(),
}).catch(console.error);
> ValidationError: user is invalid
  - inner: [ValidationError: name must be a string]

// conforming value
const valid = await user({
  age: 21,
  name: 'John',
  created: new Date(), // not in schema; ignored
}).then(() => true, () => false);

throws

An error message must be provided.

throws

Schema must be an object whose values are Validator functions.

Parameters

schema: {}

A map of property names to Validator functions. Each validator will be run for the value of the associated property on the proposed object.
- [key: string]: Validator<ValidationError>
message: string

The error message to use if the validation fails.

Returns Validator<AggregateValidationError>

A validation function

oneOf

oneOf(...args: [...any[], string]): Validator<ValidationError>

Ensures a value equals one of the given expected values.

example

// you can specify the expected values as an array or as parameters:
const bool = validators.oneOf(true, false, 'boolean expected');
const same = validators.oneOf([true, false], 'boolean expected');

example

const level = validators.oneOf(['admin', 'user', 'poweruser'], 'invalid level');

// non-conforming value
level('sudo').catch(console.error);
> ValidationError: invalid level

// conforming value
const valid = await level('user')
  .then(() => true, () => false);

// as part of object schema
const user = validators.object({
  username: validators.string('username is required'),
  level: validators.oneOf('admin', 'user', 'poweruser', 'invalid level'),
}, 'user is invalid');

throws

An error message must be provided.

throws

A non-empty array of expected values must be provided.

Parameters

Rest ...args: [...any[], string]

Returns Validator<ValidationError>

A validation function

range

range(min: any, max: any, message: string): Validator<ValidationError>

- Defined in validators/index.ts:592
Ensures the value is in the specified range. If no minimum value is specified, no lower limit will be applied. Same if no maximum value is specified. The bounds are inclusive, so think of it as [min, max], not (min, max).
throws
An error message must be provided.

example
```
const isAdult = validators.range(18, null, 'not an adult');
const isTodayOrEarlier = validators.range(null, new Date(), 'after today');

// conforming
await isAdult(31);

// not conforming
isAdult(4).catch(console.error);
> ValidationError: not an adult

// non-conforming date
const ONE_DAY = 24 * 60 * 60 * 1000;
const tomorrow = new Date(Date.now() + ONE_DAY);

isTodayOrEarlier(tomorrow).catch(console.error);
> ValidationError: after today
```
Parameters
- min: any
  
  The minimum value in the range, inclusive.
- max: any
  
  The maximum value in the range, inclusive.
- message: string
  
  The error message to use if the validation fails.
Returns Validator<ValidationError>
A validation function

some

some(validators: Validator<ValidationError>[], message: string): Validator<AggregateValidationError>
some(message: string): Validator<AggregateValidationError>

Ensures the proposed value passes at least one of the specified validators.

NOTE: You can use this validator to extend existing validations. For example, you can enable multiple versions of a schema until support for older versions can be removed.

See the examples for details.

throws

An error message must be provided.

throws

A non-validator was provided.

example

// if provided, feedback must be a string
const bugReport = validators.object({
  error: validators.instanceOf(Error, 'error is required'),
  feedback: validators.some([
    validators.empty(''),
    validators.string('feedback should be a string'),
  ],'invalid feedback'),
}, 'invalid bug report');

example

// allowing multiple versions of a schema

// compose validators for re-use
function isRequiredString(name) {
  return validators.every([
    validators.not(validators.empty(''), `${name} is required`),
    validators.string(`${name} must be a string`),
  ], `${name} is a required string`);
}

const version1 = validators.object({
  fullname: isRequiredString('fullname'),
}, 'version 1 is invalid');

// version 2 split fullname into firstname and lastname:
const version2 = validators.object({
  firstname: isRequiredString('firstname'),
  lastname: isRequiredString('lastname'),
}, 'version 2 is invalid');

const isKnownVersion = validators.some([
  version1, // single fullname field
  version2, // firstname and lastname fields
], 'invalid version provided');

export async function validatePerson(person) {
  await isKnownVersion(person);
}

Parameters

validators: Validator<ValidationError>[]

The Validator functions to apply. You can specify an array or just pass the validators as direct arguments.
message: string

The error message to use if the validation fails.

Returns Validator<AggregateValidationError>

A validation function

- Defined in validators/index.ts:709
Creates a validator that always considers the value to be invalid.
throws
An error message must be provided.

example
```
// always invalid
validators.some('this value is invalid')()
  .catch(console.log);
> ValidationError: this value is invalid
```
Parameters
- message: string
  
  The error message to use.
Returns Validator<AggregateValidationError>
A validation function

string

string(message: string): Validator<ValidationError>

Ensures a value is a string.

example

const name = validators.string('name must be a string');

// non-conforming value
name(123).catch(console.error);
> ValidationError: name must be a string

// conforming value
const valid = await name('John')
  .then(() => true, () => false);

// as part of object schema
const user = validators.object({
  firstname: validators.string('string firstname expected'),
  lastname: validators.string('string lastname expected'),
}, 'user is invalid');

throws

An error message must be provided.

Parameters

message: string

The error message to use if the validation fails.

Returns Validator<ValidationError>

A validation function

Index

Interfaces

Functions

Functions

array

Parameters

message: string

Returns Validator<AggregateValidationError>

Parameters

validator: Validator<ValidationError>

message: string

Returns Validator<AggregateValidationError>

date

Parameters

message: string

Returns Validator<ValidationError>

empty

Parameters

message: string

Returns Validator<ValidationError>

every

Parameters

validators: Validator<ValidationError>[]

message: string

Returns Validator<AggregateValidationError>

Parameters

message: string

Returns Validator<AggregateValidationError>

instanceOf

Parameters

type: Function

message: string

Returns Validator<ValidationError>

matches

Parameters

rx: RegExp

message: string

Returns Validator<ValidationError>

not

Parameters

validator: Validator<ValidationError>

message: string

Returns Validator<ValidationError>

number

Parameters

message: string

Returns Validator<ValidationError>

object

Parameters

schema: {}

[key: string]: Validator<ValidationError>

message: string

Returns Validator<AggregateValidationError>

oneOf

Parameters

Rest ...args: [...any[], string]

Returns Validator<ValidationError>

range

Parameters

min: any

max: any

message: string

Returns Validator<ValidationError>

some

Parameters

validators: Validator<ValidationError>[]

message: string

Returns Validator<AggregateValidationError>

Parameters

message: string

Returns Validator<AggregateValidationError>

string

Parameters

message: string

Returns Validator<ValidationError>