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 = "[email protected]";
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:

| Identifier | Description | |-----------------|-------------------------------------------------------| | $propertyKey | The property key that is being validated | | $propertyValue | The value of the property that is being validated | | $option | Any options that are passed to the validator function |

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

| Decorator | Description | |--------------------------|-----------------------------------------------------------| | IsAlpha() | Only contains letters | | IsAlphanumeric() | Only contains letters or numbers | | IsBoolean() | Is of type boolean | | IsEmail() | Is a valid email address |
| IsEmpty() | Is null, undefined, an empty string or object |
| IsEqualTo() | Is equal to specified property |
| IsFqDn() | Is a fully qualified domain name (URL) |
| IsIp() | Is a valid v4 or v6 IP address |
| IsMaxLength() | Has a max length of x | | IsMinLength() | Has a minimum length of x |
| IsNested() | Also validate decorated child object | | IsNotEmpty() | Is not null, undefined, an empty string or object | | IsNotEqualTo() | Is not equal to specified property | | IsNumber() | Is of type number |
| IsRegEx() | Is of type Regex (regular expression) |
| IsString() | Is of type string |
| IsUrl() | Is a valid URL (uniform resource locator) |
| IsValid() | Property is always valid (useful for skipping validation) |