@tybalt/validator

Installation

Bundlers

You can install the package from npm. For example, using the npm cli

npm install --save @tybalt/validator

Alternatively, you can install using pnpm or yarn.

Once you've installed the package you'll need to include it in your bundle. See the documentation from your bundler (webpack, swc, browserify, etc.) for details.

CDN

You can include Tybalt on your page directly by fetching it from a CDN. For example, using unpkg

import { compose, required, string, url } from 'https://unpkg.com/@tybalt/validator@0.0.10/dist/mjs/index.js';

Alternatively, you can use cdnjs, or jsDelivr.

Concepts

Validators

Validators are asynchronous functions that return a blob of data.

A fully functioned validator might look like

const myValidator = {
    async validate(value) {
        return value.includes('foo');
    },
    logLevel: 'warning',
    message: 'must include substring "foo"',
};

Validator Factories

Functions that return validators. Many exports from @tybalt/validator are factories that you use as follows:

import { required } from '@tybalt/validator';

const myIsRequiredValidator = required();

export default function myFunction(myArgument) {
    myIsRequiredValidator(myArgument);
}

To create your own validator factory, create a function that returns a validator

export default function myValidatorFactory(substring) {
    return {
        async validate(value) {
            return value.includes(substring);
        },
        logLevel: 'warning',
        message: `must include substring ${substring}`,
    };
}

Validation Results

Validators return an object that includes information about whether a validator passed or not. The most important of the keys is passed, which is true when the input is valid and false when it is not.

import { oneOf } from '@tybalt/validator';

const validator = oneOf(['foo', 'bar']);
validator.validate('foo'); // returns { passed: true }
validator.validate('quux'); // returns { passed: false }

API

array

array creates a validator that checks whether a value is an array. It will return true if the object is either an array or a string that parses to an array.

import { array } from '@tybalt/validator';

const validator = array();

compose

compose is a method for connecting multiple validators into a single validator.

If you want to validate that a single value exists, and is a string that is a valid url, you can compose those validators into a single validator as follows:

import { compose, required, string, url } from '@tybalt/validator';

const validator = compose(required(), string(), url());
const result = await validator.validate(value);

Note that compose will ignore falsey validators, to make it easier to make dynamic validators

const validator = compose(required(), string(), isUrl ? url() : null);

integer

integer creates a validator that checks whether a value is an integer.

import { integer } from '@tybalt/validator';

const validator = integer();

matchesPattern

matchesPattern creates a validator that checks that a value matches a regex.

import { matchesPattern } from '@tybalt/validator';

const validator = matchesPattern({ pattern: \foo\ });

number

number creates a validator that checks whether a value is a number.

import { number } from '@tybalt/validator';

const validator = number();

oneOf

oneOf creates a validator that checks if a value is member of values.

import { oneOf } from '@tybalt/validator';

const validator = oneOf(['foo', 'bar']);

required

required creates a validator that checks that a value is defined.

import { required } from '@tybalt/validator';

const validator = required();

shape

shape creates a validator that checks that a value is an object with a given set of keys.

import { compose, required, string, number } from '@tybalt/validator';

const validator = shape({
    foo: number(),
    bar: compose(required(), string()),
});

Note that shapes can always have more data than what is described by the shape validator.

shouldThrow

shouldThrow wraps a validator, and throws an error if the validator fails.

import { required, shouldThrow } from '@tybalt/validator';

const validator = shouldThrow(required());

string

string creates a validator that ensures a value is a string.

import { string } from '@tybalt/validator';

const validator = string();

url

url creates a validator that ensures a value is a valid url.

import { url } from '@tybalt/validator';

const validator = url();

validator

validator takes a callback that returns a ValidationResult or a boolean, and returns a callback. Use validator to create a custom validator.

import { validator } from '@tybalt/validator';

const customValidator = validator((value) => {
    value.includes('substring');
});

withLevel

withLevel adds a logging and error level to a validation result.

import { url, withLevel } from '@tybalt/validator';

const validator = withLevel(url(), 'warning');

withMessage

withMessage adds a custom message to a validation result.

import { oneOf, withMessage } from '@tybalt/validator';

const validator = withMessage(oneOf([true, false]), 'must be a boolean');