Skip to content

wkelly1/Valigators

BranchesTags

Repository files navigation

Valigator

Valigators

NPM version Licence NPM downloads Code coverage

Valigators is a simple library for validating that data matches a specific 'shape'

Usage

Install

npm i valigators --save
# or
yarn add valigators

In Node.js

const { Valigator } = require("valigators");

ESM

import Valigator from "valigators";

Browser

<script src="valigators.min.js"></script>

CDN

<script src="https://cdnjs.cloudflare.com/ajax/libs/valigators/1.3.1/valigators.min.js" integrity="sha512-xmQDNVmIKZZSVSeuJzUi5o+VwhVPQCGBK27om2EqhXH7wWFQeLUPBOVPjZ49rt4NRvUTsMI64zURKzy8wx107Q==" crossorigin="anonymous"></script>

Example

import Valigator, { minLength } from "valigators";

const valigator = new Valigator();

const valid_data = {
    name: "bob",
    age: 12,
    example: {
        foo: "bar",
    },
};

const invalid_data = {
    // name: "bob" <- removed this value
    age: 12,
    example: {
        foo: "bar",
    },
};

const shape = {
    name: {
        type: "text", // Required attribute
        validators: [minLength(2)], // Optional list is extra validators to run
    },
    age: {
        type: "number",
        onError: (error) => {
            console.log("Error: ", error);
        }, // <== you can optionally add a onError method that runs if this value is an error
    },
    example: {
        // Works with nested objects
        foo: {
            type: "text",
            required: false,
        },
    },
};

valigator.validate(valid_data, shape); // Returns true

valigator.validate(invalid_data, shape); // Returns false

valigator.validate_more(valid_data, shape);
// => {
//     success: true,
//     values: {
//         name: { success: true },
//         age: { success: true },
//         example: { foo: { success: true } },
//     },
// };

valigator.validate_more(invalid_data, shape);
// => {
//     success: false,
//     values: {
//         age: { success: true },
//         example: { foo: { success: true } },
//         name: {
//             success: false,
//             message: "Value is required but is missing",
//         },
//     },
// };

The shape object

This is where we define what the data should look like.

Attributes

  • type - this is the type that the data should be (required attribute)
  • required - Is the value required in the data structure

Types

A type is the expected data type. It consists of a set of validators that will run when checking if some data matches

For example the text type runs the validators

[isString];

Available default types:

Type Validations
text [isString]
number [isNumber]
array [isArray]
boolean [isBoolean]
email [isString, containsRegex(emailRegex)]
phone [isString, containsRegex(phoneRegex)]
date [isInstanceOf(Date)]
date_string [isString, containsRegex(dateRegex)]
time_hhmm_12h [isString, containsRegex(time_hhmm_12h)]
time_hhmm_24h [isString, containsRegex(time_hhmm_24h)]
time_hhmmss_24h [isString, containsRegex(time_hhmmss_24h)]
time_hhmmss_24h [isString, containsRegex(time_hhmmss_24h)]
password [isString,containsUpper,containsLower,containsSymbol,containsNumber,minLength(8)]
longitude_latitude [isString, containsRegex(longitude_latitude)]
credit_card_number [isString, containsRegex(credit_card_number)]
ipv4_address [isString, containsRegex(ipv4_address)]
ipv6_address [isString, containsRegex(ipv6_address)]
url [isString, containsRegex(url)]

See here for raw regex

If you have additional types you want supported please add a feature request.

Extending default types

If you have a specific type you want to use you can specify it as an option

const valigator = new Valigator({
    types: {
        your_new_type: {
            validators: [myValidator],
        },
    },
});

Now you can use this type

const type = {
    type: "your_new_type"
}

const data = ... // Some valid data

valigator.validate(data, type);

Validators

The back bone of the library are validator functions. These are functions that you can use to check your data.

The library has a set of pre-written validators for you to use:

Validator Description
isString If the value is a string
isNumber If the value is a number
isArray If the value is an array
isBoolean If the value is a boolean
isNull If the value is null
minLength(min) If length of value is greater or equal to the min value
maxLength(max) If length of value is less than or equal to the max value
minMaxLength(min, max) If length of value is greater or equal to than the min value and less than or equal to the max value
length(n) If the length of the value is equal to n
substring(inner) If the string converted value contains substring inner
maxDecimalPoint(max) If the value is a number and has less than or equal to max decimal places
minDecimalPoint(min) If the value is a number and greater than or equal to min decimal places
decimalPoints(n) If the value is a number and has exactly n decimal places
oneOf(elems) If the value is equal to one of the elements in the array elems (e.g. ["one", "two"])
containsNumber() If the string converted value contains a number
containsUpper() If the string converted value contains an upper case character
containsLower() If the string converted value contains a lower case character
containsSymbol() If the string converted value contains one of the symbols [[\]|\\/~^:,;?!&%$@*+\-_#}{<>.=_)(£]
containsRegex(reg) If the string converted value contains matches the regular expression reg (e.g. /[A-Z]/)
or(validators) Takes an array of validators and runs each one and returns true if any of the validators return true, false otherwise (e.g. validators([isNumber, isString]) will only be true if the value is a number or a string)
isInstanceOf(func) Checks if the value instanceof func
isEven Checks if the value is a number and even
isOdd Checks if the value is a number and odd
isPrime Checks if the value is a number and prime
isSquare Checks if the value is a number and a square number
isCube Checks if the value is a number and is a cube number
isNegative Checks if the value is a number and negative (0 is not negative)
isPositive Checks if the value is a number and positive (0 is not positive)
equals(to) Checks if the value is equal to to. It does more than === and compares the value. This means you can compare an arrays contents as well as objects with this

These can be used on their own as well as in validate()

import { minLength } from "./Valigators";

minLength(5, "example"); // True
minLength(5, "foo"); // False

The last parameter is the value.

Custom validator

If you want to specify your own validator then we have a function called customValidator which can be used as follows:

const my_validator = customValidator((a, b, value) = {
    return (value % a) === b;
})

const type = {
    type: "number",
    validators: [my_validator(2,4)]
}

const data = ...// Some valid data

valigator.validate(data, type);

The last parameter of the function must be the data value. You can specify as many other parameters as you need.

Arrays

It is possible to validate arrays as well as nested arrays. To do this use the array type.

Example with array on its own:

const data = [1, 2, 3];
const shape = {
    type: "array",
    validators: [],
};
val.validate_more(data, shape);
// => { success: true }

Example with nested array:

const data = { example: [1, 2, 3] };
const shape = {
    example: {
        type: "array",
        validators: [],
    },
};
val.validate_more(data, shape);
// => { example: { success: true } }

To actually check the contents of the array you can use any of the array validators.

Validator Description
all(shape) Checks that every element in the array matches the shape
some(shape) Checks that one or more elements in the array match the shape
fromN(start, shape) Checks that every element from the start index start (inclusive) match the shape
between(start, end, shape) Checks that every element between the start (inclusive) index and end (inclusive) index match the shape
upto(end, shape) Checks that every element up to end (inclusive) matches the shape
exact(array) Checks that the value matches the array exactly

Note: you can also perform other checks such as maxLength on arrays using the validators

Messages

By default valigators will display a message detailing what went wrong when you call validate_more. If any of the validators fail then you will get details about that in the validationErrors key:

const valigator = new Valigator();

const invalid_data = {
    example: "bar",
};

const shape = {
    example: {
        type: "text",
        validators: [minLength(4)],
    },
};

valigator.validate_more(invalid_data, shape);
// => {
//     success: false, // Overall success
//     values: {
//         example: {
//             success: false, // Individual success
//             message: "Invalid value for data", // Individual error message
//             validationErrors: [
//                 {
//                     validator: "minLength",
//                     message: "Invalid value for data",
//                 },
//             ], // List of which validators failed
//         },
//     },
// };

When a validator failed you will get the default error message "Invalid value for data" (Default can be overwritten see here). However you may want individual custom messages for each validator. To do this:

const valigator = new Valigator();

const invalid_data = {
    example: "bar",
};

const shape = {
    example: {
        type: "text",
        validators: [minLength(4)],
        messages: {
            minLength: "Oh no, minLength failed", // New message
        },
    },
};

valigator.validate_more(invalid_data, shape);
// => {
//     success: false, // Overall success
//     values: {
//         example: {
//             success: false, // Individual success
//             message: "Invalid value for data", // Individual error message
//             validationErrors: [
//                 {
//                     validator: "minLength",
//                     message: "Oh no, minLength failed", // <- now showing your message
//                 },
//             ], // List of which validators failed
//         },
//     },
// };

The key in the messages field matches the validator function name.

Custom messages with custom validators

If you have written your own validator then to be able to provide a custom message you need to make sure you provide an id to the validator.

const my_validator = customValidator((a, b, value) = {
    return (value % a) === b;
}, "myValidator") // <- make sure you define the identifier

Now when adding custom messages you can reference it via the identifer (e.g. myValidator)

const shape = {
    example: {
        type: "text",
        validators: [my_validator],
        messages: {
            myValidator: "myValidator failed",
        },
    },
};

onError callback

If you want a function to run when an error is found (for example to update some state to an error state) you can do it with the onError key in the shape object.

const shape = {
    example: {
        type: "text",
        validators: [minLength(2)],
        onError: (error) => {
            console.log("Error:", error);
        }, // <== This is that call back function
    },
};

The onError function gives you access to the error which will like similar to the errors from validate_more. Here is an example:

// error =>
{
    message: "Invalid value for data", // Overall error message
    validationErrors: [
        {
            validator: "minLength",
            message: "Invalid value for data",
        },
    ], // More details about which validators failed
};

Also note that the validationErrors field will not always be present as sometimes an error occurs thats not to do with a validation function failing.

Here is an example if your writing React code

const [error, setError] = useState(false);
const [errorMsg, setErrorMsg] = useState("");

const shape = {
    example: {
        type: "text",
        validators: [minLength(2)],
        onError: (error) => {
            setError(true);
            setErrorMsg(error.message);
        },
    },
};

Options

You can specify a set of options for the Valigator

const options = {
  messages?: {
    invalidValue?: string;
    unexpectedValue?: string;
    required?: string;
  };
  keys?: {
    success?: string;
    message?: string;
    type?: string;
    required?: string;
    validators?: string;
    messages?: string;
    validationErrors?: string;
    validator?: string;
    onError?: string;
  };
  types?: object
  requiredValues?: any[]
}

Overriding the requiredValues

This field defines what should be caught when a value in the shape is set to required.

By default you will get a require error when the value does not exist in the data or when the value is just an empty string.

If you don't want it to check for empty string you can overwrite it.

requiredValues: [];

Or if you want to add to it:

requiredValues: [null, "foo"];

This will throw a value is required error whenever the value:

  • Does not exist in the data
  • Exists but is null
  • Exists but is equal to "foo"

Custom default error messages

To update the default error message:

const options = {
    messages: {
        invalidValue: "New message"
        unexpectedValue: "New message"
        unexpectedValue: "New message"
    }
}

new Valigator(options);

Naming conflicts

Sometimes your data will match the keys we use in the shape as well as in the output. You can change any of the values using the keys option.

const options = {
    keys: {
        success: "newKey1",
        message: "newKey2",
        type: "newKey3",
        required: "newKey4",
        validators: "newKey5",
        messages: "newKey6",
        validationErrors: "newKey7",
        validator: "newKey8",
        onError: "newKey9",
    },
};

new Valigator(options);

Default type overriding

If you don't like the way we validate our default types you can override them. You can also add new types in the same way.

const options = {
    types: {
        string: {
            validators: [someValidator, someOtherValidator],
        },
    },
};

new Valigator(options);

API

Table of Contents

arraysEqual

Checks that two values are both arrays and that they are equal

Parameters

  • a any Value to check
  • b any Other value to check

all

Checks that every value in an array matches some shape

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether they all match

between

Checks that every value in an array between a start and end index matches some shape

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether they all match

containsLower

Checks whether the value converted to string contains an lower case character

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether contains an lower case character

containsNumber

Checks whether the value converted to string contains a number

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether contains a number

containsRegex

Checks whether the value converted to string contains a specified regex With arrays it will check that any of the values match the regex

Type: TValidator

Parameters

  • reg Regex to test
  • value Value to check

Returns boolean Boolean value representing whether contains a specified regex

containsSymbol

Checks whether the value converted to string contains a symbol With arrays it will check that any of the values contain a symbol

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether contains a symbol

containsUpper

Checks whether the value converted to string contains an upper case character

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether contains an upper case character

decimalPoints

Checks whether a number has exactly the specified number of decimal points

Type: TValidator

Parameters

  • n Value
  • value Value to check

Returns boolean Boolean value representing has correct decimal points

equals

Checks whether the value is equal to a specified value using ===

Type: TValidator

Parameters

  • equal Value to check equals to
  • value Value to check

Returns boolean {boolean} Boolean representing if they are equal

exact

Checks that the value exactly matches the array

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether they match

fromN

Checks that values from a start index in an array matches some shape

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether values from start index match

isArray

Checks if value is an array

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether array or not

isBoolean

Checks if value is a boolean

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether boolean or not

isCube

Checks whether a value is a number and whether that number is a cube number

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a cube or not

isDateString

Checks whether a value is a string in the format of a date

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a date string or not

isEven

Checks whether a value is a number and whether that number is even

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a even or not

isInstanceOf

Tests the presence of constructor.prototype in object's prototype chain

Type: TValidator

Parameters

  • typeClass function to test against
  • value Object to test

Returns boolean Boolean

isNegative

Checks whether a value is a number and whether that number is a negative number

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a negative number or not

isNull

Checks if value is null

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether null or not

isNumber

Checks if value is a number

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether number or not

isOdd

Checks whether a value is a number and whether that number is odd

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a odd or not

isPositive

Checks whether a value is a number and whether that number is a positive number

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a positive number or not

isPrime

Checks whether a value is a number and whether that number is prime

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a prime or not

isSquare

Checks whether a value is a number and whether that number is a square number

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean representing whether is a prime or not

isString

Checks if value is a string

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether string or not

length

Checks whether a value converted to a string has a specific length

Type: TValidator

Parameters

  • n Length
  • value Value to check

Returns boolean Boolean value representing whether right length or not

maxDecimalPoint

Checks whether a number has less than or equal to a specified number of decimal points

Type: TValidator

Parameters

  • max Max value
  • value Value to check

Returns boolean Boolean value representing has correct decimal points

maxLength

Checks that a value has length less than max value inclusive

Type: TValidator

Parameters

  • max Max value
  • value Value to check

Returns boolean Boolean value representing whether right length or not

minDecimalPoint

Checks whether a number has greater than or equal to a specified number of decimal points

Type: TValidator

Parameters

  • min Min value
  • value Value to check

Returns boolean Boolean value representing has correct decimal points

minLength

Checks that a value has length greater than min value inclusive

Type: TValidator

Parameters

  • min Min value
  • value Value to check

Returns boolean Boolean value representing whether right length or not

minMaxLength

Checks whether a value has length between min and max value inclusive

Type: TValidator

Parameters

  • min Min value
  • max Max value
  • value Value to check

Returns boolean Boolean value representing whether right length or not

oneOf

Takes an array and checks that the value matches on of the elements in the array

Type: TValidator

Parameters

  • elems Elements value could be
  • value Value to check

Returns boolean Boolean representing whether the value matches one of the elems

or

Used if you you don't mind if some of the validators fail as long as one passes

Type: TValidator

Parameters

  • validators Functions to run
  • value Value to check

Returns boolean Boolean value if one of the functions passes

some

Checks that some values in an array matches some shape

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether some match

substring

Checks whether a value converted to a string contains a specific substring inner

Type: TValidator

Parameters

  • inner Substring to check for (converted to string)
  • value Value to check

Returns boolean Boolean value representing whether it contains substring

upto

Checks that values up to an index value in an array matches some shape

Type: TValidator

Parameters

  • value Value to check

Returns boolean Boolean value representing whether they all match

Valigator

Valigator class is used to check that some data matches some specified shape

Parameters

  • options TOptions? Optional settings

validate

Checks whether some data matches a specified shape and just returns a boolean value as a result

Parameters

  • data any Data to check
  • shape TShape Shape the data is supposed to match
  • stopAtError boolean?

Examples

const valigator = new Valigator();
valigator.validate(10, {type: "number"});
// => true

const valigator = new Valigator();
valigator.validate({names: {first: "Dinesh", last: "Chugtai" }, {names: {first: {type: "text"}, last: {type: "text"}}});
// => true

const valigator = new Valigator();
valigator.validate({names: {first: "Dinesh" }, {names: {first: {type: "text"}, last: {type: "text", required: false}}});
// => true

Returns Boolean representing if data is valid or not

validate_more

Checks whether some data matches a specified shape and returns an object containing all the places where it failed and their corresponding messages

Parameters

  • data any Data to check
  • shape TShape Shape the data is supposed to match

Examples

const valigator = new Valigator();
valigator.validate_more(10, {type: "number"});
// => {success: true, values: {success: true}}

const valigator = new Valigator();
valigator.validate_more({names: {first: "Dinesh", last: "Chugtai" }, {names: {first: {type: "text"}, last: {type: "text"}}});
// => {success: true, values: { names: { first: { success: true }, last: { success: true } } }}

const valigator = new Valigator();
valigator.validate_more({names: {first: "Dinesh" }, {names: {first: {type: "text"}, last: {type: "text", required: false}}});
// => {success: true, values: { names: { first: { success: true }, last: { success: true } } }}

const valigator = new Valigator();
valigator.validate_more({names: {first: "Dinesh" }}, {names: {first: {type: "number"}}});
// => {success: false, values: { names: { first: { success: false, message: 'Invalid value for data' } } }}

Returns {success: boolean, values: TMsg} Object representing what passed and what failed

Contributing

Build

To build the project

yarn build
# or
npm run build

Code of Conduct

Please see full code of conduct

Contributing Guide

To contribute to the project please see the contributing guide

Licence

Valigators is MIT licensed

About

Javascript validation library

Resources

Readme

License

MIT license

Code of conduct

Code of conduct
Activity

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases 2

v1.2.0: Merge pull request #5 from wkelly1/development Latest
Feb 9, 2021
+ 1 release

Packages

No packages published

Languages