Rolster Validators

Utility lightweight simple for apply data validations.

Installation

npm i @rolster/validators

Configuration

You must install the @rolster/types to define package data types, which are configured by adding them to the files property of the tsconfig.json file.

{
  "files": ["node_modules/@rolster/types/index.d.ts"]
}

Concepts

A validator is a function that receives a value and returns either undefined (the value is valid) or a ValidatorError describing the problem:

interface ValidatorError<T = any> {
  id: string; // unique error identifier, e.g. 'required'
  message: string; // human readable message (i18n, es/en)
  data?: T; // extra context about the failure
}

The library ships with three entry points:

• @rolster/validators — the validate function to validate whole objects.
• @rolster/validators/helpers — the catalog of ready-to-use validators.
• @rolster/validators/expressions — the underlying regular expressions.

Features

Built-in validators

Import them from @rolster/validators/helpers. Each returns a ValidatorError when the value is invalid, or undefined when it is valid.

Presence

| Validator | Valid when… | | ---------------------- | ------------------------------------ | | defined(value) | value is not null/undefined | | required(value) | value is truthy | | checked(value) | boolean value is true |

Text format

| Validator | Valid when… | | ----------------------- | ------------------------------------------------- | | textonly(value) | only letters, no spaces | | alphabetic(value) | only letters and spaces | | alphanumber(value) | only letters and numbers | | onlyNumber(value) | only digits | | email(value) | valid email address | | hexColor(value) | hexadecimal color (#RRGGBB / #RRGGBBAA) | | nickname(value) | valid username (letters, numbers, . _ - @) | | password(value) | only the allowed password characters | | decimal(value) | decimal number |

Length (factory validators)

| Validator | Valid when… | | ------------------------- | ------------------------------------ | | strReqlength(n) | string length is exactly n | | strMinlength(n) | string length is at least n | | strMaxlength(n) | string length is at most n |

Numeric range (factory validators)

| Validator | Valid when… | | ------------------------------ | ------------------------ | | minValue(n) | value >= n | | maxValue(n) | value <= n | | greaterThanValue(n) | value > n | | greaterOrEqualsThanValue(n) | value >= n | | lessThanValue(n) | value < n | | lessOrEqualsThanValue(n) | value <= n |

import { required, email, strMinlength } from '@rolster/validators/helpers';

required(''); // { id: 'required', message: 'Field is required', ... }
required('Daniel'); // undefined

email('not-an-email'); // { id: 'email', message: 'Field must be email', ... }
email('[email protected]'); // undefined

const min = strMinlength(8);
min('123'); // { id: 'strMinlength', ... }
min('12345678'); // undefined

Validating an object

Use validate to run several validators against the fields of an object. It returns whether the object is valid plus the collected errors per field.

import { validate } from '@rolster/validators';
import { required, email, strMinlength } from '@rolster/validators/helpers';

const form = { name: '', email: '[email protected]', password: '123' };

const result = validate(form, {
  name: [required],
  email: [required, email],
  password: [required, strMinlength(8)]
});

result.valid; // false
result.errors;
// {
//   name: [{ id: 'required', message: 'Field is required', ... }],
//   password: [{ id: 'strMinlength', message: 'Field must have minimum 8 characters', ... }]
// }

Internationalized messages

Error messages are localized through @rolster/i18n and ship with Spanish (es) and English (en) translations out of the box.

Regular expressions

If you only need the raw patterns (for inputs, masks, etc.) import them from @rolster/validators/expressions:

import { REGEX_EMAIL, REGEX_HEX_COLOR } from '@rolster/validators/expressions';

REGEX_EMAIL.test('[email protected]'); // true

Contributing

• Daniel Andrés Castillo Pedroza :rocket: