Simple, flexible and types safe framework for validation, sanitization and transformation of JavaScript values.
- Zero dependencies
- Works in browser and NodeJS environments
- TypeScript support and complete types inference
- Support of scalar values, objects, arrays and tuples
Using npm npm install treat-like
Using yarn yarn install treat-like
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"}There are three validations of result object that is returnd from chain:
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.
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.
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;
}All this three types are united to single Result type.
type Result<CO, SO = never, E = never> = ContinueResult<CO> | StopResult<SO> | ErrorResult<E>;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("[email protected]")) // {ok: true, stop: false, output: '[email protected]' }
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' }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: "[email protected]",
password: "aqu6aopah7Voo8sa",
fullName: "Konstantin Alikhanov",
phone: "123 456 789"
})
console.log(vr);
// {
// ok: true,
// stop: false,
// output: {
// email: '[email protected]',
// 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: "[email protected]",
password: "1234",
fullName: "Konstantin Alikhanov",
phone: "123"
})
console.log(vr);
// {
// ok: false,
// stop: true,
// output: undefined,
// error: { password: 'to_simple', phone: 'invalid_format' }
// }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 }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", "[email protected]"])) // valid
// {
// ok: true,
// stop: false,
// output: [ '123 456 789', '[email protected]' ],
// error: undefined
// }
console.log(phoneEmailTuple(["123", "[email protected]"])) // 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", "[email protected]", 123])) // extra value in tuple
// {
// ok: false,
// stop: true,
// output: undefined,
// error: 'invalid_array_length'
// }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
You can join three steps (say A, B and C) to chain by folloing styles:
chain1 = A.and(B).and(C)chain2 = A.and(B.and(C))The final chains would be the same.
- promises support