it-validator

DISCLAIMER

I'm making this library because I needed a validation library that can grow and adapt to every project(something I couldn't really find online).Happy coding.

The it-validator is an async validation library designed to make request validations easier

• Installation
• The basics
• Available methods
• Errors
• Values
• Including values without validating
• Why a function returning an object?
• Custom validations?
• What is the rules parameter for?
• Extra functions exposed

Installation

The it-validator work both on Node and your browser.

npm i it-validator
#or
yarn add it-validator

The basics

To start using the library, you'll need 3 things:

• The object to validate
• The rules function that returns the rules to validate with
• The actual validator call

The object to validate

It's a simple object that needs validation

const obj = {
  requiredString: "I'm required",
  someNumberGreaterThan5: 6,
  onlyRequiredWithoutAnotherField: null
}

The rules

A function that accepts a parameter ( you can name it whatever you want, more on this later ) and returns the actual rules object

const rules = obj => ({
  requiredString: { required: true, type: String },
  someNumberGreaterThan5: { type: Number, min: 6 },
  onlyRequiredWithoutAnotherField: { requiredWithout: ["someNumberGreaterThan5"] }
})

The validator call

Now that you have your object and rules, let's validate them

First you need to import the validate method

import { validate } from "it-validator"

Then you call the validate function using async/await or .then. The validate function accepts 2 parameters: (the object, the rules). It will return an object containing the err and values properties

const { err, values } = await validate(obj, rules)

Errors

The error returned by the validator is an object containing all the failed rules as props. Every property in the error message is a property from the object you sent to validate that didn't pass your requirements

Custom error for every type of validation

Each error contains a default message, but you can override this. In the rules object you can provide a message property with a text for every failed validation for that specific rule. See the message section of the Available methods.

Values

Sometimes you may wish to continue with a valid values object even when you have errors. That's why the library still returns a values object containing every value that passed validations.

Why a function returning an object?

In order to allow the validate function to be asynchronous and to be able to access another values in the object you sent to validate, we need to initialize the rules as a function that accepts a parameter and returns an object with the actual rules.

Custom Validations

The library provides you a way of making your own custom validations inside the rules using the validate property. See the validate method in Available methods

What is the rules parameter for?

The misterious parameter you sent the rules function is not required, it's only for a special cases where one of your rules requires another of your rules value. One example would be using this parameter along with the validate property.

const rules = values => {
  const validateTheRequiredString = value => {
    if (!values.stringCompany) return "I'm missing my company"
    return undefined
  }
  return {
    stringCompany: { type: String },
    requiredString: { required: true, type: String, validate: validateTheRequiredString }
  }
}

Including values without validating

If you wish to include a field in the values result without validating it you just set a null to the rule.

const rules = values => ({
  includeWithoutvalidation: null
})

Available methods

• type
• required
• min and max
• email
• in
• regex
• requiredIf
• requiredUnless
• requiredWith
• requiredWithout
• requiredWithoutAll
• alpha
• validate
• default
• clean
• message
• children

type

Checks if the value corresponds with the specified type

const rules = values => ({
  stringField: { type: String }
})

Available types

• Boolean: true, false, 1 or 0
• String
• Number: not a strict validation, a string containing a posible number will evaluate to true
• Object
• Array
• Date

required

The field must be present, not null, not undefined and not an empty string ''

const rules = values => ({
  requiredField: { required: true }
})

min and max

Specify the min or max values of the field. For numbers will be the exact value of the number, for strings and arrays will be the length of it.

const rules = values => ({
  stringBetween3and6Length: { min: 3, max: 6 },
  numberBetween2and4: { min: 2, max: 4 }
})

email

A very simple validation for email, it's not perfect but it will validate a simple email.

const rules = values => ({
  simpleEmail: { email: true }
})

in

The value will only pass the validation if it's in the declared array.

const rules = values => ({
  numberOnlyBelow3: { type: Number, in: [1, 2, 3] },
  specificStrings: { type: String, in: ["one string", "or maybe this one"] }
})

regex

Specify a regex to validate against

const rules = values => ({
  regexValidation: { regex: /^[a-z]+$/ }
})

requiredIf

The field under validation is required only if the specified field has the declared value. You declare it with and array with the first item beeing the field, and the second item beeing the value of that field.

const rules = values => ({
  sometimesRequired: { requiredIf: ["otherField", 4] },
  otherField: { type: String }
})

The validation of the value is strict, it validates type too, so in this case 4 won't be the same as '4'.

requiredUnless

The inverse of requiredIf. The field under validation is required, unless the specified field has the declared value.

const rules = values => ({
  requiredUnlessOtherFieldIs4: { requiredUnless: ["otherField", 4] },
  otherField: { type: String }
})

requiredWith

The field under validation is required if any of the specified fields is present and has a value.

const rules = values => ({
  requiredWithCompany: { requiredWith: ["otherField", "someOther", "andOneMore"] },
  otherField: { type: String },
  someOther: { type: String },
  andOneMore: { type: String }
})

requiredWithout

The field under validation is required if any of the specified fields is not present or it doesn't have a value.

const rules = values => ({
  requiredWithoutCompany: { requiredWithout: ["otherField", "someOther", "andOneMore"] },
  otherField: { type: String },
  someOther: { type: String },
  andOneMore: { type: String }
})

requiredWithoutAll

The field under validation is required if any of the specified fields is not present or it doesn't have a value.

const rules = values => ({
  requiredWithoutAllCompany: { requiredWithoutAll: ["otherField", "someOther", "andOneMore"] },
  otherField: { type: String },
  someOther: { type: String },
  andOneMore: { type: String }
})

alpha

The field under validation must be contain alphabetic characters only. To be easier to validate inputs or request this also accepts spaces.

const rules = values => ({
  onlyAlpha: { alpha: true }
})

alphaNum

The field under validation must be contain alphanumeric characters only. To be easier to validate inputs or request this also accepts spaces.

const rules = values => ({
  onlyAlphaNum: { alphaNum: true }
})

alphaDash

The field under validation must be contain alphanumeric, dashes or undescores characters only. To be easier to validate inputs or request this also accepts spaces.

const rules = values => ({
  onlyAlphaDash: { alphaDash: true }
})

validate

It allows you to use a custom function to validate the field. If you want to generate an error just return the string you wish for your error, otherwise return undefined or don't return at all. When using this validate functions, you have the value available as the function parameter (you can call this parameter any way you want). You can declare it inside the object of the rule

const rules = values => ({
  requiredString: {
    required: true,
    type: String,
    validate: value => {
      if (value.length > 20) return "string can't be greater than 20"
      return undefined
    }
  }
})

Or you can make use of the rules beeing a function and declare another function inside

const rules = values => {
  const validateTheRequiredString = value => {
    if (value.length > 20) return "string can't be greater than 20"
    return undefined
  }
  return {
    requiredString: { required: true, type: String, validate: validateTheRequiredString }
  }
}

You can also make use of the validate beeing an async function to make a call to an APi for example.

const rules = values => {
  const validateTheRequiredString = async value => {
    const externalData = await axios.get("https://yourapi.com")
    if (!externalData) return "string can't be greater than 20"
    return undefined
  }
  return {
    requiredString: { required: true, type: String, validate: validateTheRequiredString }
  }
}

default

Sometimes you may wish to have some default value when non is sent in you values object. This default value, will be set before any validation, so be aware when using other rules like requiredWith.

const rules = values => ({
  withDefaultValue: { default: "I'm a default value" }
})

defaultAfterValidate

Because the [default] method is executed before validating, sometimes it may not be a good fit for you. The [defaultAfterValidate] will add a default value to your property after all validations.

const rules = values => ({
  withDefaultAfterValidate: { defaultAfterValidate: "I'm a default value after every validation" }
})

clean

[clean] is another method that modifies the value you are trying to validate. After every validation, the clean will "clean" your input. It has two sub-methods. First the trim method, that does exactly that, trim start and end of your input. Second the sanitize method, that will safely encode some characters for db manipulation.

  '&' => '&'
  '<' => '&lt;'
  '>' => '&gt;'
  '"' => '&quot;'
  "'" => '&#x27;'
  "/" => '&#x2F;'

The easiest way is to set a true value, it will execute both the trim and sanitize methods.

const rules = values => ({
  cleanWithTrue: { clean: true }
})

But if you just want one of the sub-methods, you can pass an object.

const rules = values => ({
  cleanWithSanitize: { clean: { sanitize: true } },
  cleanWithTrim: { clean: { trim: true } }
})

message

It let's you declare a custom error message for every type of validation in the rule or an specific one for each rule validation.

Single error message for every rule validation:

const rules = obj => ({
  requiredString: { required: true, type: String, message: "I'm required" },
  someNumberGreaterThan5: { type: Number, min: 6, message: "I must be greater than 5" },
  requiredWithoutAnotherField: { requiredWithout: ["someNumberGreaterThan5"], message: "Sometimes I'm required" }
})

Specific message for each validation:

const rules = obj => ({
  requiredString: { required: true, type: String, message: { required: "I'm required", type: "I must be a string" } }
})

children

[children] method is specific for the types Array and Object. The library allows you to validate nested objects or array (maybe of objects too).

Let's start with and easy object or array validation. If you omit the children method, the validator will allow everything inside the object/array to be a part of the valid values

const rules = obj => ({
  easyArray: { type: Array },
  easyObject: { type: Object }
})

If you'd like to validate an object properties, you can add the children method and specify the rules for each attribute you want to be included in the result values.

const rules = obj => ({
  validateObject: {
    type: Object,
    children: {
      firstNestedProperty: { required: true, type: String },
      secondNestedProperty: null
    }
  }
})

Note that, like every other rule, if you set the property to null, the validator will consider any value as a valid value. Also you can validate an array of objects. Just add the children property with the validation rules you wish your nested objects to have.

const rules = obj => ({
  validateArray: {
    type: Object,
    children: {
      firstNestedProperty: { required: true, type: String },
      secondNestedProperty: null
    }
  }
})

If one of the objects in the array fails to pass the rules, the whole array won't be added to the valid values. Also the err will show an object containing the failed children with the index as the key so you can quickly tell which one failed.

// err example
{ validateArray: { '1': { firstNestedProperty: 'is required' } } }

Extra functions exposed

Besides the main validate function the library exposes the sub-functions that are the engine of it-validator. You can start using them just like you did with the validate function.

import { sanitize, trim } from "it-validator"

Some functions will take a poetic license to make request validations easier. They'll be marked as "request friendly" and will have and explanation

Alert: most of these functions are negations.

• sanitize
• trim
• invalidEmail
• invalidType
• invalidBoolean
• invalidNumber
• invalidDate
• invalidArray
• invalidObject
• invalidString
• hasValue
• invalidMax
• invalidMin
• invalidIn
• invalidRegex
• invalidAlpha
• invalidAlphaNum
• invalidAlphaDash

invalidType

Validate the second parameter (the value) against the first parameter type within the available types. The function will return a string with the type if it's invalid or false if it's valid.

let res = invalidType(String, "MyName") // false
res = invalidType(String, 3) // String

invalidBoolean

"request friendly" The library will consider the following values as a boolean:

;[true, false, 1, 0, "true", "false", "1", "0"]

let res = invalidBoolean("MyName") // true
res = invalidBoolean(0) // false
res = invalidBoolean(false) // false
res = invalidBoolean("1") // false
res = invalidBoolean("false") // false

invalidNumber

"request friendly" The library will consider string that are numbers as numbers:

let res = invalidNumber("MyName") // true
res = invalidNumber(1) // false

invalidDate

let res = invalidDate("something") // true
res = invalidDate("2000/10/10") // false

invalidArray

let res = invalidArray("something") // true
res = invalidArray([1, 2, 3]) // false

invalidObject

let res = invalidObject("something") // true
res = invalidObject({ one: 1 }) // false

invalidString

let res = invalidString(1) // true
res = invalidObject("a string") // false

sanitize

const res = sanitize("someString&someOther") // someString&someOther

trim

const res = sanitize("   someString    ") // someString

hasValue

let res = hasValue("") // false
res = hasValue("value") // true
res = hasValue(null) // false
res = hasValue(undefined) // false
res = hasValue(0) // true
res = hasValue(false) // true

invalidEmail

Value needs to be a string.

let res = invalidEmail("some@email") // true
res = invalidEmail("[email protected]") // false
res = invalidEmail("some@em#ail.com") // true

invalidMax

let res = invalidMax("more") // true
res = invalidMax("mor") // false
res = invalidMax(90) // false
res = invalidMax(91) // true

invalidMin

let res = invalidMin("as") // true
res = invalidMin("asd") // false
res = invalidMin(18) // false
res = invalidMin(17) // true

invalidIn

let res = invalidIn([1, 2, 3], 4) // true
res = invalidIn([1, 2, 3], "3") // true
res = invalidIn([1, 2, 3], 3) // false

invalidRegex

const onlyNameInLowerRegex = /^[a-z]+$/
let res = invalidRegex(onlyNameInLowerRegex, "Joe") // true
res = invalidRegex(onlyNameInLowerRegex, "joe") // false

invalidAlpha

Value needs to be a string.

let res = invalidAlpha("Joe") // false
res = invalidAlpha("joe24") // true

invalidAlphaNum

Value needs to be a string.

let res = invalidAlphaNum("Joe") // false
res = invalidAlphaNum("joe24") // false
res = invalidAlphaNum("joe24-") // true

invalidAlphaDash

Value needs to be a string.

let res = invalidAlphaDash("Joe") // false
res = invalidAlphaDash("joe24") // false
res = invalidAlphaDash("joe24-") // false
res = invalidAlphaDash("joe24$") // true