Repository files navigation

Allows use of decorator and non-decorator based validation.Internally usesvalidator.js to perform validation.Class-validator works on both browser and node.js platforms.

• class-validator
  • Table of Contents
  • Installation
  • Usage
    • Passing options
  • Validation errors
  • Validation messages
  • Validating arrays
  • Validating sets
  • Validating maps
  • Validating nested objects
  • Validating promises
  • Inheriting Validation decorators
  • Conditional validation
  • Whitelisting
  • Passing context to decorators
  • Skipping missing properties
  • Validation groups
  • Custom validation classes
  • Custom validation decorators
  • Using service container
  • Synchronous validation
  • Manual validation
  • Validation decorators
  • Defining validation schema without decorators
  • Validating plain objects
  • Samples
  • Extensions
  • Release notes
  • Contributing

npm install class-validator --save

Note: Please use at least npm@6 when using class-validator. From npm@6 the dependency tree is flattened, which is required byclass-validator to function properly.

Create your class and put some validation decorators on the properties you want to validate:

import{validate,validateOrReject,Contains,IsInt,Length,IsEmail,IsFQDN,IsDate,Min,Max,}from'class-validator';exportclassPost{  @Length(10,20)title:string;  @Contains('hello')text:string;  @IsInt()  @Min(0)  @Max(10)rating:number;  @IsEmail()email:string;  @IsFQDN()site:string;  @IsDate()createDate:Date;}letpost=newPost();post.title='Hello';// should not passpost.text='this is a great post about hell world';// should not passpost.rating=11;// should not passpost.email='google.com';// should not passpost.site='googlecom';// should not passvalidate(post).then(errors=>{// errors is an array of validation errorsif(errors.length>0){console.log('validation failed. errors: ',errors);}else{console.log('validation succeed');}});validateOrReject(post).catch(errors=>{console.log('Promise rejected (validation failed). Errors: ',errors);});// orasyncfunctionvalidateOrRejectExample(input){try{awaitvalidateOrReject(input);}catch(errors){console.log('Caught promise rejection (validation failed). Errors: ',errors);}}

Thevalidate function optionally expects aValidatorOptions object as a second parameter:

exportinterfaceValidatorOptions{skipMissingProperties?:boolean;whitelist?:boolean;forbidNonWhitelisted?:boolean;groups?:string[];dismissDefaultMessages?:boolean;validationError?:{target?:boolean;value?:boolean;};forbidUnknownValues?:boolean;stopAtFirstError?:boolean;}

IMPORTANTTheforbidUnknownValues value is set totrue by default andit is highly advised to keep the default.Setting it tofalse will result unknown objects passing the validation!

Thevalidate method returns an array ofValidationError objects. EachValidationError is:

{    target:Object;// Object that was validated.    property:string;// Object's property that haven't pass validation.    value:any;// Value that haven't pass a validation.    constraints?:{// Constraints that failed validation with error messages.[type:string]:string;};    children?:ValidationError[];// Contains all nested validation errors of the property}

In our case, when we validated a Post object, we have such an array ofValidationError objects:

[{target:/* post object */,property:"title",value:"Hello",constraints:{length:"$property must be longer than or equal to 10 characters"}},{target:/* post object */,property:"text",value:"this is a great post about hell world",constraints:{contains:"text must contain a hello string"}},// and other errors]

If you don't want atarget to be exposed in validation errors, there is a special option when you use validator:

validator.validate(post,{validationError:{target:false}});

This is especially useful when you send errors back over http, and you most probably don't want to exposethe whole target object.

You can specify validation message in the decorator options and that message will be returned in theValidationErrorreturned by thevalidate method (in the case that validation for this field fails).

import{MinLength,MaxLength}from'class-validator';exportclassPost{  @MinLength(10,{message:'Title is too short',})  @MaxLength(50,{message:'Title is too long',})title:string;}

There are few special tokens you can use in your messages:

• $value - the value that is being validated
• $property - name of the object's property being validated
• $target - name of the object's class being validated
• $constraint1,$constraint2, ...$constraintN - constraints defined by specific validation type

Example of usage:

import{MinLength,MaxLength}from'class-validator';exportclassPost{  @MinLength(10,{// here, $constraint1 will be replaced with "10", and $value with actual supplied valuemessage:'Title is too short. Minimal length is $constraint1 characters, but actual is $value',})  @MaxLength(50,{// here, $constraint1 will be replaced with "50", and $value with actual supplied valuemessage:'Title is too long. Maximal length is $constraint1 characters, but actual is $value',})title:string;}

Also you can provide a function, that returns a message. This allows you to create more granular messages:

import{MinLength,MaxLength,ValidationArguments}from'class-validator';exportclassPost{  @MinLength(10,{message:(args:ValidationArguments)=>{if(args.value.length===1){return'Too short, minimum length is 1 character';}else{return'Too short, minimum length is '+args.constraints[0]+' characters';}},})title:string;}

Message function acceptsValidationArguments which contains the following information:

• value - the value that is being validated
• constraints - array of constraints defined by specific validation type
• targetName - name of the object's class being validated
• object - object that is being validated
• property - name of the object's property being validated

If your field is an array and you want to perform validation of each item in the array you must specify aspecialeach: true decorator option:

import{MinLength,MaxLength}from'class-validator';exportclassPost{  @MaxLength(20,{each:true,})tags:string[];}

This will validate each item inpost.tags array.

If your field is a set and you want to perform validation of each item in the set you must specify aspecialeach: true decorator option:

import{MinLength,MaxLength}from'class-validator';exportclassPost{  @MaxLength(20,{each:true,})tags:Set<string>;}

This will validate each item inpost.tags set.

If your field is a map and you want to perform validation of each item in the map you must specify aspecialeach: true decorator option:

import{MinLength,MaxLength}from'class-validator';exportclassPost{  @MaxLength(20,{each:true,})tags:Map<string,string>;}

This will validate each item inpost.tags map.

If your object contains nested objects and you want the validator to perform their validation too, then you need touse the@ValidateNested() decorator:

import{ValidateNested}from'class-validator';exportclassPost{  @ValidateNested()user:User;}

Please note that nested objectmust be an instance of a class, otherwise@ValidateNested won't know what class is target of validation. Check alsoValidating plain objects.

It also works with multi-dimensional array, like :

import{ValidateNested}from'class-validator';exportclassPlan2D{  @ValidateNested()matrix:Point[][];}

If your object contains property withPromise-returned value that should be validated, then you need to use the@ValidatePromise() decorator:

import{ValidatePromise,Min}from'class-validator';exportclassPost{  @Min(0)  @ValidatePromise()userId:Promise<number>;}

It also works great with@ValidateNested decorator:

import{ValidateNested,ValidatePromise}from'class-validator';exportclassPost{  @ValidateNested()  @ValidatePromise()user:Promise<User>;}

When you define a subclass which extends from another one, the subclass will automatically inherit the parent's decorators. If a property is redefined in the descendant, class decorators will be applied on it from both its own class and the base class.

import{validate}from'class-validator';classBaseContent{  @IsEmail()email:string;  @IsString()password:string;}classUserextendsBaseContent{  @MinLength(10)  @MaxLength(20)name:string;  @Contains('hello')welcome:string;  @MinLength(20)password:string;}letuser=newUser();user.email='invalid email';// inherited propertyuser.password='too short';// password wil be validated not only against IsString, but against MinLength as welluser.name='not valid';user.welcome='helo';validate(user).then(errors=>{// ...});// it will return errors for email, password, name and welcome properties

The conditional validation decorator (@ValidateIf) can be used to ignore the validators on a property when the provided condition function returns false. The condition function takes the object being validated and must return aboolean.

import{ValidateIf,IsNotEmpty}from'class-validator';exportclassPost{otherProperty:string;  @ValidateIf(o=>o.otherProperty==='value')  @IsNotEmpty()example:string;}

In the example above, the validation rules applied toexample won't be run unless the object'sotherProperty is"value".

Note that when the condition is false all validation decorators are ignored, includingisDefined.

Even if your object is an instance of a validation class it can contain additional properties that are not defined.If you do not want to have such properties on your object, pass special flag tovalidate method:

import{validate}from'class-validator';// ...validate(post,{whitelist:true});

This will strip all properties that don't have any decorators. If no other decorator is suitable for your property,you can use @Allow decorator:

import{validate,Allow,Min}from"class-validator";exportclassPost{    @Allow()title:string;    @Min(0)views:number;nonWhitelistedProperty:number;}letpost=newPost();post.title='Hello world!';post.views=420;post.nonWhitelistedProperty=69;(postasany).anotherNonWhitelistedProperty="something";validate(post).then(errors=>{// post.nonWhitelistedProperty is not defined// (post as any).anotherNonWhitelistedProperty is not defined  ...});

If you would rather to have an error thrown when any non-whitelisted properties are present, pass another flag tovalidate method:

import{validate}from'class-validator';// ...validate(post,{whitelist:true,forbidNonWhitelisted:true});

It's possible to pass a custom object to decorators which will be accessible on theValidationError instance of the property if validation failed.

import{validate}from'class-validator';classMyClass{  @MinLength(32,{message:'EIC code must be at least 32 characters',context:{errorCode:1003,developerNote:'The validated string must contain 32 or more characters.',},})eicCode:string;}constmodel=newMyClass();validate(model).then(errors=>{//errors[0].contexts['minLength'].errorCode === 1003});

Sometimes you may want to skip validation of the properties that do not exist in the validating object. This isusually desirable when you want to update some parts of the object, and want to validate only updated parts,but skip everything else, e.g. skip missing properties.In such situations you will need to pass a special flag tovalidate method:

import{validate}from'class-validator';// ...validate(post,{skipMissingProperties:true});

When skipping missing properties, sometimes you want not to skip all missing properties, some of them maybe requiredfor you, even if skipMissingProperties is set to true. For such cases you should use@IsDefined() decorator.@IsDefined() is the only decorator that ignoresskipMissingProperties option.

In different situations you may want to use different validation schemas of the same object.In such cases you can use validation groups.

IMPORTANTCalling a validation with a group combination that would not result in a validation (eg: non existent group name)will result in a unknown value error. When validating with groups the provided group combination should match at least one decorator.

import{validate,Min,Length}from'class-validator';exportclassUser{  @Min(12,{groups:['registration'],})age:number;  @Length(2,20,{groups:['registration','admin'],})name:string;}letuser=newUser();user.age=10;user.name='Alex';validate(user,{groups:['registration'],});// this will not pass validationvalidate(user,{groups:['admin'],});// this will pass validationvalidate(user,{groups:['registration','admin'],});// this will not pass validationvalidate(user,{groups:undefined,// the default});// this will not pass validation since all properties get validated regardless of their groupsvalidate(user,{groups:[],});// this will not pass validation, (equivalent to 'groups: undefined', see above)

There is also a special flagalways: true in validation options that you can use. This flag says that this validationmust be applied always no matter which group is used.

If you have custom validation logic you can create aConstraint class:

1. First create a file, lets sayCustomTextLength.ts, and define a new class:

   import{ValidatorConstraint,ValidatorConstraintInterface,ValidationArguments}from'class-validator';@ValidatorConstraint({name:'customText',async:false})exportclassCustomTextLengthimplementsValidatorConstraintInterface{validate(text:string,args:ValidationArguments){returntext.length>1&&text.length<10;// for async validations you must return a Promise<boolean> here}defaultMessage(args:ValidationArguments){// here you can provide default error message if validation failedreturn'Text ($value) is too short or too long!';}}

   We marked our class with@ValidatorConstraint decorator.You can also supply a validation constraint name - this name will be used as "error type" in ValidationError.If you will not supply a constraint name - it will be auto-generated.

   Our class must implementValidatorConstraintInterface interface and itsvalidate method,which defines validation logic. If validation succeeds, method returns true, otherwise false.Custom validator can be asynchronous, if you want to perform validation after some asynchronousoperations, simply return a promise with boolean inside invalidate method.

   Also we defined optional methoddefaultMessage which defines a default error message,in the case that the decorator's implementation doesn't set an error message.

2. Then you can use your new validation constraint in your class:

   import{Validate}from'class-validator';import{CustomTextLength}from'./CustomTextLength';exportclassPost{  @Validate(CustomTextLength,{message:'Title is too short or long!',})title:string;}

   Here we set our newly createdCustomTextLength validation constraint forPost.title.

3. And use validator as usual:

   import{validate}from'class-validator';validate(post).then(errors=>{// ...});

You can also pass constraints to your validator, like this:

import{Validate}from'class-validator';import{CustomTextLength}from'./CustomTextLength';exportclassPost{  @Validate(CustomTextLength,[3,20],{message:'Wrong post title',})title:string;}

And use them fromvalidationArguments object:

import{ValidationArguments,ValidatorConstraint,ValidatorConstraintInterface}from'class-validator';@ValidatorConstraint()exportclassCustomTextLengthimplementsValidatorConstraintInterface{validate(text:string,validationArguments:ValidationArguments){returntext.length>validationArguments.constraints[0]&&text.length<validationArguments.constraints[1];}}

You can also create a custom decorators. Its the most elegant way of using a custom validations.Lets create a decorator called@IsLongerThan:

1. Create a decorator itself:

   import{registerDecorator,ValidationOptions,ValidationArguments}from'class-validator';exportfunctionIsLongerThan(property:string,validationOptions?:ValidationOptions){returnfunction(object:Object,propertyName:string){registerDecorator({name:'isLongerThan',target:object.constructor,propertyName:propertyName,constraints:[property],options:validationOptions,validator:{validate(value:any,args:ValidationArguments){const[relatedPropertyName]=args.constraints;constrelatedValue=(args.objectasany)[relatedPropertyName];returntypeofvalue==='string'&&typeofrelatedValue==='string'&&value.length>relatedValue.length;// you can return a Promise<boolean> here as well, if you want to make async validation},},});};}

2. Put it to use:

   import{IsLongerThan}from'./IsLongerThan';exportclassPost{title:string;  @IsLongerThan('title',{/* you can also use additional validation options, like "groups" in your custom validation decorators. "each" is not supported */message:'Text must be longer than the title',})text:string;}

In your custom decorators you can also useValidationConstraint.Lets create another custom validation decorator calledIsUserAlreadyExist:

1. Create a ValidationConstraint and decorator:

   import{registerDecorator,ValidationOptions,ValidatorConstraint,ValidatorConstraintInterface,ValidationArguments,}from'class-validator';@ValidatorConstraint({async:true})exportclassIsUserAlreadyExistConstraintimplementsValidatorConstraintInterface{validate(userName:any,args:ValidationArguments){returnUserRepository.findOneByName(userName).then(user=>{if(user)returnfalse;returntrue;});}}exportfunctionIsUserAlreadyExist(validationOptions?:ValidationOptions){returnfunction(object:Object,propertyName:string){registerDecorator({target:object.constructor,propertyName:propertyName,options:validationOptions,constraints:[],validator:IsUserAlreadyExistConstraint,});};}

   note that we marked our constraint that it will by async by adding{ async: true } in validation options.

2. And put it to use:

   import{IsUserAlreadyExist}from'./IsUserAlreadyExist';exportclassUser{  @IsUserAlreadyExist({message:'User $value already exists. Choose another name.',})name:string;}

Validator supports service container in the case if want to inject dependencies into your custom validator constraintclasses. Here is example how to integrate it withtypedi:

import{Container}from'typedi';import{useContainer,Validator}from'class-validator';// do this somewhere in the global application level:useContainer(Container);letvalidator=Container.get(Validator);// now everywhere you can inject Validator class which will go from the container// also you can inject classes using constructor injection into your custom ValidatorConstraint-s

If you want to perform a simple non async validation you can usevalidateSync method instead of regularvalidatemethod. It has the same arguments asvalidate method. But note, this methodignores all async validationsyou have.

There are several method exist in the Validator that allows to perform non-decorator based validation:

import{isEmpty,isBoolean}from'class-validator';isEmpty(value);isBoolean(value);

Schema-based validation without decorators is no longer supported byclass-validator. This feature was broken in version 0.12 and it will not be fixed. If you are interested in schema-based validation, you can find several such frameworks inthe zod readme's comparison section.

Due to nature of the decorators, the validated object has to be instantiated usingnew Class() syntax. If you have your class defined using class-validator decorators and you want to validate plain JS object (literal object or returned by JSON.parse), you need to transform it to the class instance via usingclass-transformer).

Take a look on samples in./sample for more examples ofusages.

There are several extensions that simplify class-validator integration with other modules or add additional validations:

• class-validator integration withclass-transformer
• class-validator-rule
• ngx-dynamic-form-builder
• abarghoud/ngx-reactive-form-class-validator
• class-validator-extended

See information about breaking changes and release noteshere.

For information about how to contribute to this project, seeTypeStack's general contribution guide.