checkeasy

checkeasy

Light, expressive and type-safe data validation in typescript.

As you can see, you DON'T NEED to write your schema twice (for validation and for typescript). Just use validator functions, which return well typed results. So typescript is acknowledged about shape of your data and checks its usages on compilation stage.

Why I need one more type validator?

Because I wanted to have type validation which:

• Super light and easy

  Library is small. No core with tons of unnecessary functionality. Each validator is exported separately. So if you use tree shaking in your project, only validators used by you will be in your bundle.

• Written with typescript in mind

  It always returns typed results

• Support of transformations

  E.g. I can convert strings to numbers on the fly, if I want to do so

• Easy extensible with custom validators

  Validator is a function. Adding new one is as simple, as writing new function.

Documentation

• Validators
  • int
  • strToInt
  • float
  • strToFloat
  • string
  • boolean
  • strToBoolean
  • object
  • arrayOf
  • exact
  • oneOf
  • alternatives
  • optional
  • nullable
  • defaultValue
  • uuid
  • email
  • any
  • transform
• Custom validators

Validators

Although, it's really easy to create your own validators, library exports few ready to go ones.

int

Checks if value is an integer.

Possible options:

• min
• max

const validator1 = int() 
validator1(5, 'myValue'); // returns: 5 

const validator2 = int() // returns: 5
validator2('5', 'myValue'); // throws: [myValue] should be an integer

const validator3 = int({min: 0, max: 4});
validator3(5, 'myValue'); // throws: [myValue] is larger than the allowed maximum (4)

strToInt

The same as int but also tries to convert string to integer, if value is string.

It's convenient for validating/parsing url params, which initially are strings.

float

Checks if value is a finite number.

Possible options:

• min
• max

const validator1 = float() 
validator1(5.2, 'myValue'); // returns: 5 

const validator2 = float();
validator2('5.2', 'myValue'); // throws: [myValue] should be a float

const validator3 = float({min: 0, max: 4});
validator3(5.2, 'myValue'); // throws: [myValue] is larger than the allowed maximum (4)

strToFloat

The same as float but also tries to convert string to float, if value is string.

It's convenient for validating/parsing url params, which initially are strings.

string

Checks if value is a string.

Possible options:

• min - min length of string
• max - max length of string
• pattern - regex to test with

const validator1 = string()
validator1('aaa', 'myValue'); // returns: "aaa"

const validator2 = string()
validator2({}, 'myValue'); // throws: [myValue] should be a string

const validator3 = string({max: 3});
validator3('aaaa', 'myValue'); // throws: [length(myValue)] is larger than the allowed maximum (4)

const validator4 = string({patten: /^[a-z]{3}$/i});
validator4('aaaa', 'myValue'); // throws: [myValue] doesn't match the pattern

boolean

Checks if value is a boolean.

const validator1 = boolean()
validator1(true, 'myValue'); // returns: true

const validator2 = boolean()
validator2('true', 'myValue'); // throws: [myValue] should be a boolean

strToBoolean

The same as boolean but also converts strings ("1", "true", "yes") to true, and ("0", "false", "no") to false.

It's convenient for validating/parsing url params, which initially are strings.

object

Check if a value is an object and runs validation on all of its properties by given shape.

Receives 1 or 2 parameters.

First one should be an object. Values of this object should be validators, which will be called to check properties.

const validator = object({
    a: int(),
    b: optional(string({max: 3})),
    c: v => v,
});

validator({a: 5, c: 'anystring'}, 'myValue'); // returns: {a: 5, b: undefined, c: 'anystring'}

validator({a: 5, b: 25, c: 'anystring'}, 'myValue'); // throws: [myValue.b] should be a string

validator('something totally different', 'myValue'); // throws: [myValue] should be an object

There are additional options can be passed with second param:

• ignoreUnknown - ignore properties which are not described in first param (by default: false)
• min - min amount of object properties
• max - max amount of object properties

const validator = object({
    a: int(),
    b: optional(string({max: 3})),
    c: v => v,
}, {
  ignoreUnknown: true,
  min: 2,
  max: 3,
});

arrayOf

Checks if value is an array and checks each of its elements with given validator.

You can also pass options in second parameter:

• min - min length of array
• max - max length of array

const validator1 = arrayOf(string());
validator1(['1', '2', '3'], 'myValue').toEqual(['1', '2', '3']); // returns: ['1', '2', '3']

const validator2 = arrayOf(int());
validator2({a: 2}, 'myValue'); // throws: [myValue] should be an array

const validator3 = arrayOf(int());
validator3([1, 2, '3'], 'myValue'); // throws: [myValue[3]] should be an integer

const validator4 = arrayOf(int(), {max: 2});
validator4([1, 2, 3, 'abc'], 'myValue'); // throws: [length(myValue)] is larger than the allowed maximum (2)

const validator5 = arrayOf(
    object({
        a: string(),
    }),
);
validator5([{a: 'aa'}], 'myValue'); // returns: [{a: 'aa'}]
validator5([{a: 2}], 'myValue'); // throws: [myValue[0].a] should be a string

exact

Checks if value strictly equals one of the given values.

const validator1 = exact(1);
validator1(1, 'myValue'); // returns: 1

const validator2 = exact(1)
validator2('1', 'myValue'); // throws: [myValue] isn't equal to the expected value

const validator3 = exact({a: 1});
validator3({a: 1}, 'myValue'); // throws: [myValue] isn't equal to the expected value
    // it's because it doesn't call deepEqual, but uses with strict equality

oneOf

Checks if value strictly equals one of the given values.

const validator1 = oneOf([1, 2, '3'] as const);
validator1('3', 'myValue'); // returns: 3

const validator2 = oneOf([1, 2, '3'] as const)
validator2(3, 'myValue'); // throws: [myValue] isn't equal to any of the expected values

const validator3 = oneOf([1, 2, {a: 1}] as const);
validator3({a: 1}, 'myValue'); // throws: [myValue] isn't equal to any of the expected values
// it's because it doesn't call deepEqual, but uses with strict equality

If you want typescript to make a type with exactly your values, add "as const" after array, to let typescript know - your array is readonly:

const validator1 = oneOf([1, 2, '3'] as const);
const value1 = validator1(1, 'myValue');
// here type of value1 = 1 | 2 | "3"

const validator2 = oneOf([1, 2, '3']);
const value2 = validator1(1, 'myValue');
// but here type of value2 = number | string
// as typescript recognizes type of your values array as Array<string | number> in this case

alternatives

Checks a value with the help of every of passed validators, one by one. Returns value from first validator, which doesn't fail.

If all validators failed, throws an error.

const validator = alternatives([
    string(),
    object({
        a: string(),
    }),
]);
validator({a: '5'}, 'myValue'); // returns: {a: '5'}

validator({a: 5}, 'myValue');
//  throws: [myValue] doesn't match any of allowed alternatives:
//    0: [*] should be a string
//    1: [*.a] should be a string

optional

Add undefined as a possible value to given validator. Although, it can be used itself, it's very helpful for optional values in objects.

const validator = object({
    a: optional(string()),
});
validator({}, 'myValue'); // returns: {a: undefined}
validator({a: '123'}, 'myValue'); // returns {a: '123'}
validator({a: 456}, 'myValue'); // throws: [myValue.a] should be a string
validator({a: null}, 'myValue'); // throws: [myValue.a] should be a string
  // (null is not the same as undefined)

Don't forget to enable typescript strictNullChecks config, if you want typescript to check null and undefined in resulting types.

nullable

Similar to optional. But instead of undefined, it allows value be null.

Don't forget to enable typescript strictNullChecks config, if you want typescript to check null and undefined in resulting types.

If you want to have optional and nullable value (so null and undefined will be allowed), you can make a composition of optional(nullable(...)).

defaultValue

If value is undefined, returns some default value passed as first parameter.

Otherwise, runs validator given in second parameter.

const validator = object({
    a: defaultValue('123', string()),
});
validator({}, 'myValue'); // returns: {a: '123'}
validator({a: 'uuu'}, 'myValue'); // retunrs: {a: 'uuu'}
validator({a: ''}, 'myValue'); // returns: {a: ''}
validator({a: null}, 'myValue'); // throws: [myValue.a] should be a string

uuid

Checks if value is a valid uuid string.

email

Checks if value is a valid email string.

any

There isn't "any" type, but you can easily emulate it using v => v.

const validator = object({
    stringProp: strint(),
    anyProp: v => v,
});

transform

Sometimes you may want to transform value after some validation and pass it to next validator.

// Let's imagine we want to validate some id, which can be represented by string like "user:1" or by object
// like {type: 'user', id: '1'}
// we can make one validator for that, which returns a string for both cases

const validator = alternatives([
    string({pattern: /^[a-z0-9]+\:[a-z0-9]+$/}),
    transform(
        object({
            id: string({min: 1}),
            type: string({min: 1}),
        }),
        obj => `${obj.type}:${obj.id}`,
    ),
]);

validator('user:1', 'myValue'); // returns: "user:1"
validator({type: 'user', id: '1'}, 'myValue'); // returns "user:1"
validator({type: 'user'}, 'myValue');
//    throws: [myValue] doesn't match any of allowed alternatives:
//      0: [*] should be a string
//      1: [*.id] should be a string
validator('asd', 'myValue');
//    throws: [myValue] doesn't match any of allowed alternatives:
//      0: [*] doesn't match the pattern
//      1: [*] should be an object

Error handling

In the case of validation failed, validator throws instance of ValidationError. So, it's easy to catch it.

import {ValidationError, int} from './index';

const validator = int();

try {
    
    validator('a', 'myValue');
    
} catch (err) {
      
    if (err instanceof ValidationError) {
        //...  
    }
  
    // OR
  
    if (err.name === 'ValidationError') {
        //...  
    }
    
}

Custom validators

The idea here is simple. To check any type of value you should to create a validator.

Validator is a function which receives 2 parameters: value to validate and a path.

type Validator<T> = (v: any, path: string) => T;

In case of validation error, validator should throw a ValidationError, using path to point at a place of shape, where validation failed.

In case of success validator should return a value. Validator can return the same value which was received. Or some another value, if it should be modified on the fly.

You can make inline validators. E.g.:

const myValidator = object({
  id: string(),
  type: (v, path): string => {
      if (typeof v !== 'string' || !v.startsWith('TYPE__')) {
          throw new ValidationError(`[${path}] is not correct type`);
      }
      return v;
  }
});

If you want to crate reusable validator, the convention is to wrap it into one more function, which can additionally receive options as parameters. E.g. int validator can look like:

export const int = ({min, max}: {min?: number; max?: number} = {}): Validator<number> => (v, path) => {
    if (!Number.isInteger(v)) {
        throw new ValidationError(`[${path}] should be an integer`);
    }
    if ((min !== undefined && v < min) || (max !== undefined && v > max)) {
        throw new ValidationError(`[${path}] isn\'t in allowed range`);
    }
    return v;
};

Let's create one more validator, which checks, does value exactly match given example:

const exactMatch = <T>(exactValue: T): Validator<T> => (v, path) => {
    if (v !== exactValue) {
        throw new Error(`[${path}] isn't the same as allowed value`);
    }
    return v;
};

We can use it itself:

// let's check value 
const validator = exactMatch(5);
validator(10, 'myValue'); // throws: [myValue] isn't the same as allowed value

... or let's combine it with other validators

import {object, optional} from 'checkeasy';
const validator = object({
    a: exactMatch(5),
    b: optional(exactMatch(7)),
    c: exactMatch(10),
});
validator({a: 5, c: 10}, 'myValue'); // returns: { a: 5, b: undefined, c: 10 }
validator({a: 5, c: 12}, 'myValue'); // throws: [myValue.c] isn't the same as allowed value

Changelog

[1.1.0] - 2022-05-20

• Added ValidationError, improved error messages.
• Changed some error messages
• Changes in README

Thank you joshuafcole for some changes here

[1.2.0] - 2024-08-02

• Fixed regular expression for email and uuid checks

License

ISC

Copyright 2021 Roman Ditchuk

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.