meta-validator v2.0.2

What is meta-validator?

meta-validator is a lightweight (3k gzipped), tree-shakable, zero dependency validation library that uses TypeScript decorators to define validation rules on your classes. It is isomorphic and can be used with NodeJs or in a browser.

Installation

Install the meta-validator package from npm. npm install meta-validator

Usage

Define validation rules using the available decorators. Multiple decorators can be used on each property.

export class Widget {
    @IsNotEmpty()
    @IsAlphanumeric()
    name: string;

    @IsEmail()
    email: string;
}

const myWidget = new Widget();
widget.name = "abc1234";
widget.email = "myemail@test.com";
const validationErrors = await new MetaValidator().validate(myWidget);

You can also validate arrays of objects in the same way.

const widgetArray: Widget[] = [];
const validationErrorArray = await new MetaValidator().validate(widgetArray);

Validation Errors

If an object fails validation then meta-validator returns a ValidationError object with the following structure.: <property>:[<array of validation error messages>] Example: { email: [ 'email must be a valid email address.' ] }

Custom Validation Error Messages

You can provide custom error messages by using the customErrorMessages option.

const validationErrors = await new MetaValidator().validate(widget, {
    customErrorMessages: {
        "IsEqualTo": "$propertyKey must be equal to $option0"
    }
});

When using custom error messages the following text replacement codes are available:

Custom Message Formatter

If you require total control over validation error messages you can supply a custom message formatter.

const validationErrors = await new MetaValidator().validate(widget, {
    customErrorMessageFormatter: (data: FormatterData) => {
        let errorMessage = data.message;
        errorMessage = errorMessage.replace("$propertyKey", sentenceCase(data.propertyKey));
        errorMessage = errorMessage.replace("$propertyValue", data.propertyValue);
    
        if (data.options) {
            for (let i = 0; i < data.options.length; i++) {
                errorMessage = errorMessage.replace(`$option${i}`, data.options[i]);
            }
        }
    
        return errorMessage;
    }
});

A custom formatter receives a parameter that has the following values:

interface FormatterData {
    decoratorName: string;   // The decorator name e.g. IsBoolean()
    message: string;         // The default validation error message
    propertyKey: string;     // The key of the property being validated
    propertyValue: string;   // The value of the property being validated
    options?: any[];         // Any options passed to the validator function
}

Skip Undefined Values

If you wish to validate an object but skip any properties with values that are undefined you can use the isSkipUndefinedValues option.

const validationErrors = await new MetaValidator().validate(widget, {isSkipUndefinedValues: true});

Custom Decorators

You can also create your own validation decorators. Use the existing decorators as examples.

export function IsIp(options?: IsIpOptions): PropertyDecorator {
    return (target, propertyKey) => {
        MetaValidator.addMetadata({
            // Metadata
            target: target,
            propertyKey: propertyKey.toString(),
            // Context
            className: target.constructor.name,
            validator: {
                decoratorName: IsIp.name,
                message: "$propertyKey must be a valid ip address.",
                method: (input: any) => {
                    return Promise.resolve(isIp(input, options));
                }
            }
        });
    };
}

Decorator Reference