treat-like

Simple, flexible and types safe framework for validation, sanitization and transformation of JavaScript values.

Primary features

• Zero dependencies
• Works in browser and NodeJS environments
• TypeScript support and complete types inference
• Support of scalar values, objects, arrays and tuples

Installation

Using npm npm install treat-like Using yarn yarn install treat-like

Introduction

Defining basic validation chains

treat-like package is very minimalistic so it provides only essential building blocks an leaves it up to you to define event simple validation chains.

So, let's define two basic chains to work with strings:

import {string, check, byDefault} from "treat-like";

const requiredString = string.and(check(s => s.length > 0, "required"));
const optionalString = byDefault("").and(string);

Why not to predefine this chains in package? Well, we think that in different cases the term "required string" can mean different things. Some time you may need a required string be a non zero length JavaScipt string object. Some times you need to avoid null/undefined values and zero length string is perfectly fine for you.

The same reasoning can be applied to "optional strings": if x is defined as optional string, will null be ok value to pass? Or I always need to pass typeof x === "string" values but it can be zero length?

In current example requiredString var contains a chain that is built from predefined string chain which checks incoming value is typeof string and returns error otherwice. Then it followed by step built with stepbuilding check function which accepts predicate and error value and returns a new chain.

optionalString in current example starts from byDefault chain, this is a function that takes a value (called default value) and returns such chain that takes an input value and if it is null or undefined returns default value and stops chain execution. Otherwise it returns prestine input value and chain continues execution to next step. The next step is string that as we already know checks input value is typeof string.

Ok. Now we can use these chains like regular funcitons. Pass value to it and thee return value will indicate validation status.

console.log(requiredString("Hello")); // {ok: true, stop: false, output: "Hello"}
console.log(requiredString("")); // {ok: false, stop: true, error: "required"}
console.log(requiredString(null)); // {ok: false, stop: true, error: "not_a_string"}
console.log(requiredString(123)); // {ok: false, stop: true, error: "not_a_string"}

console.log(optionalString("World")); // {ok: true, stop: false, output: "World"}
console.log(optionalString("")); // {ok: true, stop: false, output: ""}
console.log(optionalString(null)); // {ok: true, stop: true, output: ""}
console.log(optionalString(123)); // {ok: false, stop: true, error: "not_a_string"}

Talking about results

There are three validations of result object that is returnd from chain:

ContinueResult

Indicates that chain processed input value successfully and output value is stored in output field. Also this type means that output value can be passed to next step in chain.

export interface ContinueResult<CO> {
    ok: true;
    stop: false;
    output: CO;
    error: undefined;
}

This is a most common used result type.

StopResult

indicates that chain processed input value successfully and output value is stored in output field but execution but be halted and not continue to next chain.

export interface StopResult<SO> {
    ok: true;
    stop: true;
    output: SO;
    error: undefined;
}

This return type can be returned by already known byDefault step which wraps a default value in it. Look at example:

import {string, check, byDefault} from "treat-like";

function isPhoneValid(phone: string): boolean {
	// Do some validaiton here
}

const checkPhone = check(isPhoneValid, "invalid_format")

const optioinalPhone = byDefault("-").and(string).and(checkPhone);

optioinalPhone("444 222 444") // {ok: true, stop: false, output: "444 222 444"}
optioinalPhone(null) // {ok: true, stop: true, output: "-"}
optioinalPhone("123 432") // {ok: false, stop: true, error: "invalid_format"}

As you can see, the second call to optioinalPhone returns a StopResult than indicates that chain execution have to be stopped.

ErrorResult

Indicates that some error happened during chain execution. This result does not countain output value, instead it contains error.

export interface ErrorResult<E> {
    ok: false;
    stop: true;
    output: undefined;
    error: E;
}

United Result

All this three types are united to single Result type.

type Result<CO, SO = never, E = never> = ContinueResult<CO> | StopResult<SO> | ErrorResult<E>;

Defining chain using other validating libraries

treat-like perfectly comatible with other validating libraries. Let use a very popular https://www.npmjs.com/package/validator as examle and create a email validating chain:

import {check, string} from "treat-like";
import v from "validator";

const email = string.and(check(v.isEmail, "not_a_email"));

console.log(email("atomaltera@gmail.com")) // {ok: true, stop: false, output: 'atomaltera@gmail.com' }
console.log(email("atomaltera")) // { ok: false, stop: true, error: 'not_a_email' }
console.log(email("")) // { ok: false, stop: true, error: 'not_a_email' }
console.log(email(null)) // { ok: false, stop: true, error: 'not_a_string' }
console.log(email(123)) // { ok: false, stop: true, error: 'not_a_string' }

Validating objects

You can use shape functino to create an object validation chain from a sheme:

import {check, string, byDefault, shape} from "treat-like";
import v from "validator";

function isStrongPassword(pass: string): boolean {
    // some logic to validate password strength
    return pass.length >= 8;
}

const requiredString = string.and(check(s => s.length > 0, "required"));
const optionalString = byDefault("").and(string);
const requiredEmail = string.and(check(v.isEmail, "not_a_email"))
const strongPassword = string.and(check(isStrongPassword, "to_simple"));
const optionalPhone = optionalString.and(check(v.isMobilePhone, "invalid_format"))

const registrationForm = shape({
    email: requiredEmail,
    password: strongPassword,
    fullName: optionalString,
    phone: optionalPhone,
})

Here we define some isStrongPassword function to validate password strenght. Also here as an optional phone number validator.

Let's look at validation results:

For valid input the result is of type ContinueResult:

const vr = registrationForm({
    email: "atomaltera@gmail.com",
    password: "aqu6aopah7Voo8sa",
    fullName: "Konstantin Alikhanov",
    phone: "123 456 789"
})

console.log(vr);
// {
//   ok: true,
//   stop: false,
//   output: {
//     email: 'atomaltera@gmail.com',
//     password: 'aqu6aopah7Voo8sa',
//     fullName: 'Konstantin Alikhanov',
//     phone: '123 456 789'
//   },
//   error: undefined
// }

Let's check what happens with invalid phone number and to simple password:

const vr = registrationForm({
    email: "atomaltera@gmail.com",
    password: "1234",
    fullName: "Konstantin Alikhanov",
    phone: "123"
})

console.log(vr);
// {
//   ok: false,
//   stop: true,
//   output: undefined,
//   error: { password: 'to_simple', phone: 'invalid_format' }
// }

Validating arrays

There is an array chain builder to work with arrays:

import {check, string, array} from "treat-like";
import v from "validator";

const phone = string.and(check(v.isMobilePhone, "invalid_format"))

const phoneNumberList = array(phone.and(check(x => x.length > 0, "no_phones_provided"));

Let's see results

console.log(phoneNumberList(["123 456 789"])) // valid
// { ok: true, stop: false, output: [ '123 456 789' ], error: undefined }

console.log(phoneNumberList(["123 456 789", "987 654 321"])) // valid
// {
//   ok: true,
//   stop: false,
//   output: [ '123 456 789', '987 654 321' ],
//   error: undefined
// }

console.log(phoneNumberList(["123 456 789", "123"])) // second phone is invalid
// {
//   ok: false,
//   stop: true,
//   output: undefined,
//   error: [ undefined, 'invalid_format' ]
// }

console.log(phoneNumberList([])) // invalid: empty array
// {
//   ok: false,
//   stop: true,
//   output: undefined,
//   error: 'no_phones_provided'
// }

As you can see here, error field can be a string or an array of string | undefiend

If you ommit part .and(check(x => x.length > 0, "no_phones_provided")); then error type will be an array of string | undefiend:

import {check, string, array} from "treat-like";
import v from "validator";

const phone = string.and(check(v.isMobilePhone, "invalid_format"))

const phoneNumberList = array(phone)

console.log(phoneNumberList([]))
// { ok: true, stop: false, output: [], error: undefined }

Validating tuples

Tuples validation is supported too. Use tuple funciton to build tuple processing chain:

import {check, string, tuple} from "treat-like";
import v from "validator";

const phone = string.and(check(v.isMobilePhone, "invalid_phone"));
const email = string.and(check(v.isEmail, "invalid_email"));

const phoneEmailTuple = tuple(phone, email);

Here is how results look like:

console.log(phoneEmailTuple(["123 456 789", "atomaltera@gmail.com"])) // valid
// {
//   ok: true,
//   stop: false,
//   output: [ '123 456 789', 'atomaltera@gmail.com' ],
//   error: undefined
// }

console.log(phoneEmailTuple(["123", "atomaltera@gmail.com"])) // invalid phone
// {
//   ok: false,
//   stop: true,
//   output: undefined,
//   error: [ 'invalid_phone', undefined ]
// }

console.log(phoneEmailTuple(["123 456 789", "atomaltera"])) // invalid email
// {
//   ok: false,
//   stop: true,
//   output: undefined,
//   error: [ undefined, 'invalid_email' ]
// }

console.log(phoneEmailTuple(["123 456 789"])) // too short tuple
// {
//   ok: false,
//   stop: true,
//   output: undefined,
//   error: 'invalid_array_length'
// }

console.log(phoneEmailTuple(["123 456 789", "atomaltera@gmail.com", 123])) // extra value in tuple
// {
//   ok: false,
//   stop: true,
//   output: undefined,
//   error: 'invalid_array_length'
// }

Complex shape chains

Ofcource you can combine all chains together in any fashion you need (I'll ommit imports and definitions here as well as results):

const complexModel = shape({
    name: requiredString,
    description: optionalText,
    subModels: array(shape({
        point: tuple(number, number),
        active: byDefault(true).and(boolean),
    }))
})

number and boolean are provided by treat-like just like a string

Linking styles

You can join three steps (say A, B and C) to chain by folloing styles:

Flat style

chain1 = A.and(B).and(C)

Nested style

chain2 = A.and(B.and(C))

The final chains would be the same.

In plans

• promises support