validate-typescript

Extensible schema based validator that supports typescript typing.

This package strives to meet the following criteria:

lightweight
inline
simple
strongly typed
extensible
convertable

Getting Started

The example below represents a basic subset of the inline validations that can be applied.

Example

import { Email, ID, RegEx, Type, Options, Optional, Nullable, Alias, Any, All, validate } from 'validate-typescript';

function ZaPhoneNumber() {
    return Alias(RegEx(/^((\+27|0)\d{9})$/), ZaPhoneNumber.name);
}

class CustomMessage {
    constructor(public message: string) {}
}

const schema = {
    id: ID(),
    children: [ID()],
    username: Type(String),
    email: Email(),
    gmail: RegEx(/[email protected]/),
    phone: ZaPhoneNumber(),
    gender: Options(['m', 'f', 'o']),
    married: Type(Boolean),
    names: {
        first: Type(String),
        middle: Optional(Type(String)),
        last: Type(String)
    }
    message: Type(CustomMessage)
}

const input = {
    id: 17,
    children: [1,2,'3'],
    username: 'solomon',
    email: '[email protected]',
    gmail: '[email protected]',
    phone: '+27824392186'
    gender: 'm',
    married: true,
    names: {
        first: 'Solomon',
        last: 'Dube',
    }
    message: new CustomMessage('Sawubona Mhlaba')
}

try {
    const input = validate(schema, input);
    console.log(input); // no validation error
} catch (error) {
    console.log(error); // validation error
}

Installation

npm install validate-typescript

Imports

The default import provides validate, all the validators and all the extensions:

import { ... } from 'validate-typescript';

For additional (more specific) imports, use the following:

import { ... } from 'validate-typescript/validators';  // imported above
import { ... } from 'validate-typescript/extensions';  // imported above
import { ... } from 'validate-typescript/assertions';  // not imported above
import { ... } from 'validate-typescript/conversions'; // not imported above
import { ... } from 'validate-typescript/errors';      // not imported above

Validators

The following examples of validate-typescript schemas illustrate the different validation methods.

Note: the comment // type: TypeName following the validator explicitly specifies the resultant typescript type inferred by the typescipt transpiler. This relates back to the strongly typed criteria.

Type Validators

Expects an exact type match.

let schema = {
    myNumber: Type(Number),      // type: Number
    myString: Type(String),      // type: String
    myCustom: Type(CustomClass), // type: CustomClass
    // etc...
}

Primative Validators

Expects an exact primative type match.

let schema = {
    myNumber: Primative(Number),      // type: number
    myString: Primative(String),      // type: string
    // etc...
}

Literal Validators

Expects an exact type and value match.

let schema = {
    number49:    49,              // type: number
    myCountry:   'South Africa',  // type: string
    dontDefine:  undefined,       // type: undefined
    allwaysNull: null,            // type: null
    // etc...
}

Custom (Extension) Validators

Expects custom convertions and assertions to be valid.

let schema = {
    myEmail:  Email(),      // type: string
    sqlId:    ID(),         // type: number
    comeText: RegEx(/abc/), // type: string
    // etc...
}

Nested Object Validators

Expects a nested object that matches the nested schema.

let schema = {
    subObject: {
        a: ID(),
        b: Type(Date)
        c: {
            d: RegEx(/[email protected]/)
        }
    } // type: { a: number, b: Date, c: { d: string } }
}

Array Validators

Expects an array that matches the contents of the array schema.

Note: Multiple validators in the array are treated as boolean-or (any).

let schema = {
    // array validation
    emailArray: [Email()]             // type: string[]
    idArray: [ID()]                   // type: number[]

    // array with multiple options validation
    arrayOfEmailOrId: [Email(), ID()] // type: (string | number)[]
}

Options Validators

Expects any or all of the validation options to match.

let schema = {
    // options validation
    options: Options([Type(Number), Type(String)]) // type: number | string

    // optional validation (i.e. not required)
    optional: Optional(ID())                       // type: number | undefined
    alsoOptional: Options([ID(), undefined])       // type: number | undefined

    // nullable validation
    maybeNull: Nullable(Type(String)),             // type: String | null
    alsoMaybeNull: Options([Type(String, null)]),  // type: String | null

    // array options
    arrayOptions: Options([[Email()], [ID()]])     // type: string[] | number[]
}

Any or All Validators

Any represents boolean-or of the validation options while all represents boolean-and.

let schema = {

    // validate any options
    anyOptions: Options([Type(Number), Type(String)], ValidationOptions.any)     // type: number | string
    alsoAny: Any([Type(Number), Type(String)])                                   // type: number | string

    // validate all options
    allOptions: Options([RegEx(/[email protected]/), Email()], ValidationOptions.all) // type: number | string
    alsoAll: All([RegEx(/[email protected]/), Email()])                               // type: number | string
}

Validation

Note: the return of validate, in this case input, will inherit the typescript typing of the schema, thus strongly-typed.

try {
    const input = validate(schema, input);
    console.log(input); // no validation error
} catch (error) {
    console.log(error); // validation error
}

Assertions

Assertions allow enforcing of basic validation conditions and form the atomic building blocks of custom validators. Upon failure, assertions throw an AssertionError.

Note: All assertions take a flag allowing conditional inversion.

Assertions are intended to be extended.

Typed Assertions

Assertion	Description
isSameType	Assert type equality of two inputs.
isSameTypeName	Asserts type name equality of two inputs.
isSymbol	Asserts symbol type input.
isBoolean	Asserts boolean type input.
isString	Asserts string type input.
isNumber	Asserts number type input.
isArray	Asserts array type input.
isNull	Asserts null type input.
isObject	Asserts object type input.
isUndefined	Asserts undefined type input.

Numeric Assertions

Assertion	Description
isInt	Asserts integer input.
isFloat	Asserts float input.

Operational Assertions

Assertion	Description
isEqualTo	Asserts equality (==) of two inputs.
isGreaterThan	Asserts greater than relation (>) of two inputs.
isLessThan	Asserts less than relation (<) of two inputs.
isGreaterThanOrEqualTo	Asserts greater than or equal to relation (>=) of two inputs.
isLessThanOrEqualTo	Asserts less than or equal to relation (<=) of two inputs.

Misc Assertions

Assertion	Description
isEqual	Asserts typed equality (===) of two inputs.
isRegEx	Asserts RegExp matching input.

Converters

All converters attempt to convert the input to a specific type and throw a ConversionError if the conversion fails.

Converters are intended to be extended.

Conversion	Output Type	Input Types	Description
toInt	`number`	`number`, `string`	Converts only integers (needs updating)
toNumber	`number`	`number`, `string`	Converts any number
toBoolean	`boolean`	`boolean`, `string`	Converts 'true' and 'false' (needs updating)

Errors

Custom validation errors are implemented. It is ulikely that you will need to extend these but there may be future extensions.

ValidationError: Abstract base class for all validation errors.
ConversionError: Type of all the conversion errors.
AssertionError: Type of all the assertion errors.
ValidationError: Type of all the validation errors.
NotMatchAnyError: Type of error thrown when Any does not match any of the provided validation options.

For example, supporting JSON formatted validation errors for easier parsing and logging.

Custom Validators (Extensions)

Validators can be customized using converters, assertions as well as other custom validators (extensions). Upon failure, validators throw a ValidationError.

Alias

Aliasing is a method of aliasing a custom validator, possibly with inputs.

import { RegEx, Alias } from 'validate-typescript';

export function ZaPhoneNumber() {
    return Alias(RegEx(/^((\+27|0)\d{9})$/), ZaPhoneNumber.name);
}

ID

This example illustrates the use of both a converter and an assertion.

import { Validator } from 'validate-typescript';
import * as convert from 'validate-typescript/conversions';

export function ID() {
    return Validator((input: any): number => {
        const value = convert.toInt(input);
        assert.isGreaterThan(0, value);
        return value;
    }, ID.name);
}

RegEx

This example illustrates only the use of assertions.

import { Validator } from 'validate-typescript';
import * as assert from 'validate-typescript/assertions';

export function RegEx(regEx: RegExp) {
    return Validator((input: any): string => {
        assert.isString(input);
        assert.isRegEx(regEx, input);
        return input;
    }, RegEx.name);
}

Compatibility

This project targets ES5 (using libraries es2017 and dom).

Recommendations

TODO: complete

hirza-tango / validate-typescript Goto Github PK