or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

array-object-validation.mdcommon-decorators.mdcore-validation.mdcustom-validation-schema.mdindex.mdnumber-date-validation.mdstring-validation.mdtype-validation.md
tile.json

index.mddocs/

Class-Validator

Class-validator is a comprehensive TypeScript/JavaScript validation library that enables developers to apply validation rules to class properties using decorators or programmatic schemas. Built on top of the proven validator.js library, it provides 110+ validation decorators organized into functional categories, supports both synchronous and asynchronous validation, and offers extensive customization options for error messages and validation behavior.

Package Information

  • Package Name: class-validator
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install class-validator reflect-metadata

Core Imports

import { validate, validateSync, ValidationError } from "class-validator";
import { IsEmail, IsNotEmpty, Length, IsOptional } from "class-validator";

For CommonJS:

const { validate, validateSync, ValidationError } = require("class-validator");
const { IsEmail, IsNotEmpty, Length, IsOptional } = require("class-validator");

Basic Usage

import { validate, ValidationError } from "class-validator";
import { IsEmail, IsNotEmpty, Length } from "class-validator";

class User {
  @IsNotEmpty()
  @Length(2, 20)
  name: string;

  @IsEmail()
  email: string;

  @IsOptional()
  @Length(10, 100)
  bio?: string;
}

// Validate an object
const user = new User();
user.name = "John";
user.email = "invalid-email";

const errors: ValidationError[] = await validate(user);
if (errors.length > 0) {
  console.log("Validation failed. Errors: ", errors);
} else {
  console.log("Validation succeed");
}

// Synchronous validation (ignores async validators)
const syncErrors: ValidationError[] = validateSync(user);

Architecture

Class-validator is built around several key components:

  • Decorator System: 110+ validation decorators organized by type (string, number, date, etc.)
  • Validation Engine: Core Validator class that processes decorated objects and schemas
  • Error Reporting: Detailed ValidationError objects with constraint information and nested error support
  • Schema System: Alternative programmatic validation approach using ValidationSchema
  • Container Integration: IoC container support for dependency injection in custom validators
  • Metadata Storage: Global metadata management for storing validation rules and constraints

Capabilities

Core Validation Functions

Primary validation functions for validating objects using decorators or schemas.

/**
 * Validates given object using decorators or named schema
 */
function validate(object: object, validatorOptions?: ValidatorOptions): Promise<ValidationError[]>;
function validate(schemaName: string, object: object, validatorOptions?: ValidatorOptions): Promise<ValidationError[]>;

/**
 * Validates and throws ValidationError on failure
 */
function validateOrReject(object: object, validatorOptions?: ValidatorOptions): Promise<void>;
function validateOrReject(schemaName: string, object: object, validatorOptions?: ValidatorOptions): Promise<void>;

/**
 * Synchronous validation (ignores async validators)
 */
function validateSync(object: object, validatorOptions?: ValidatorOptions): ValidationError[];
function validateSync(schemaName: string, object: object, validatorOptions?: ValidatorOptions): ValidationError[];

/**
 * Register a validation schema for schema-based validation
 */
function registerSchema(schema: ValidationSchema): void;

Core Validation

Common Validation Decorators

Essential decorators for conditional validation, value checking, and geographic validation. These form the foundation of most validation scenarios.

// Conditional/Flow Control
@IsOptional(validationOptions?: ValidationOptions): PropertyDecorator;
@ValidateIf(condition: (object: any, value: any) => boolean, validationOptions?: ValidationOptions): PropertyDecorator;
@ValidateNested(validationOptions?: ValidationOptions): PropertyDecorator;
@IsDefined(validationOptions?: ValidationOptions): PropertyDecorator;

// Value Validation
@IsNotEmpty(validationOptions?: ValidationOptions): PropertyDecorator;
@IsEmpty(validationOptions?: ValidationOptions): PropertyDecorator;
@IsIn(values: any[], validationOptions?: ValidationOptions): PropertyDecorator;
@Equals(comparison: any, validationOptions?: ValidationOptions): PropertyDecorator;

// Geographic
@IsLatitude(validationOptions?: ValidationOptions): PropertyDecorator;
@IsLongitude(validationOptions?: ValidationOptions): PropertyDecorator;
@IsLatLong(validationOptions?: ValidationOptions): PropertyDecorator;

Common Decorators

String Validation Decorators

Comprehensive string validation including format validation, length constraints, character type checking, encoding validation, and standards compliance. Covers emails, URLs, phone numbers, geographic identifiers, financial formats, and more.

// Format Validation
@IsEmail(options?: ValidatorJS.IsEmailOptions, validationOptions?: ValidationOptions): PropertyDecorator;
@IsUrl(options?: ValidatorJS.IsURLOptions, validationOptions?: ValidationOptions): PropertyDecorator;
@IsPhoneNumber(region?: string, validationOptions?: ValidationOptions): PropertyDecorator;
@IsUUID(version?: UUIDVersion, validationOptions?: ValidationOptions): PropertyDecorator;

// Length Validation
@Length(min: number, max?: number, validationOptions?: ValidationOptions): PropertyDecorator;
@MinLength(min: number, validationOptions?: ValidationOptions): PropertyDecorator;
@MaxLength(max: number, validationOptions?: ValidationOptions): PropertyDecorator;

// Character Type
@IsAlpha(locale?: ValidatorJS.AlphaLocale, validationOptions?: ValidationOptions): PropertyDecorator;
@IsAlphanumeric(locale?: ValidatorJS.AlphanumericLocale, validationOptions?: ValidationOptions): PropertyDecorator;

String Validation

Type Validation Decorators

Primitive type checking decorators for ensuring values are of the correct JavaScript/TypeScript type.

@IsString(validationOptions?: ValidationOptions): PropertyDecorator;
@IsNumber(options?: IsNumberOptions, validationOptions?: ValidationOptions): PropertyDecorator;
@IsBoolean(validationOptions?: ValidationOptions): PropertyDecorator;
@IsDate(validationOptions?: ValidationOptions): PropertyDecorator;
@IsArray(validationOptions?: ValidationOptions): PropertyDecorator;
@IsObject(validationOptions?: ValidationOptions): PropertyDecorator;
@IsInt(validationOptions?: ValidationOptions): PropertyDecorator;
@IsEnum(entity: object, validationOptions?: ValidationOptions): PropertyDecorator;

Type Validation

Number and Date Validation

Numeric constraints and date range validation for ensuring values fall within acceptable ranges.

// Number Validation
@Min(min: number, validationOptions?: ValidationOptions): PropertyDecorator;
@Max(max: number, validationOptions?: ValidationOptions): PropertyDecorator;
@IsPositive(validationOptions?: ValidationOptions): PropertyDecorator;
@IsNegative(validationOptions?: ValidationOptions): PropertyDecorator;
@IsDivisibleBy(num: number, validationOptions?: ValidationOptions): PropertyDecorator;

// Date Validation
@MinDate(date: Date | (() => Date), validationOptions?: ValidationOptions): PropertyDecorator;
@MaxDate(date: Date | (() => Date), validationOptions?: ValidationOptions): PropertyDecorator;

Number and Date Validation

Array and Object Validation

Collection validation for arrays and objects, including size constraints, content validation, and structural checking.

// Array Validation
@ArrayNotEmpty(validationOptions?: ValidationOptions): PropertyDecorator;
@ArrayMinSize(min: number, validationOptions?: ValidationOptions): PropertyDecorator;
@ArrayMaxSize(max: number, validationOptions?: ValidationOptions): PropertyDecorator;
@ArrayUnique(identifier?: (o: any) => any, validationOptions?: ValidationOptions): PropertyDecorator;
@ArrayContains(values: any[], validationOptions?: ValidationOptions): PropertyDecorator;
@ArrayNotContains(values: any[], validationOptions?: ValidationOptions): PropertyDecorator;

// Object Validation
@IsNotEmptyObject(options?: {nullable?: boolean}, validationOptions?: ValidationOptions): PropertyDecorator;
@IsInstance(targetType: new (...args: any[]) => any, validationOptions?: ValidationOptions): PropertyDecorator;

Array and Object Validation

Custom Validation and Schema System

Advanced features for creating custom validators, using schema-based validation, and extending the library's functionality.

/**
 * Create custom validation decorators
 */
@Validate(constraintClass: Function, constraints?: any[], validationOptions?: ValidationOptions): PropertyDecorator;
@ValidateBy(options: ValidateByOptions, validationOptions?: ValidationOptions): PropertyDecorator;

/**
 * Register custom validation decorators
 */
function registerDecorator(options: ValidationDecoratorOptions): void;

/**
 * Schema-based validation interface
 */
interface ValidationSchema {
  /** Schema name for registration */
  name: string;
  /** Property validation rules */
  properties: {
    [propertyName: string]: {
      /** Validation type name */
      type: string;
      /** Validator name (optional) */
      name?: string;
      /** Constraint values */
      constraints?: any[];
      /** Error message */
      message?: string | ((value?: any, constraint1?: any, constraint2?: any) => string);
      /** Apply to each array element */
      each?: boolean;
      /** Always validate regardless of groups */
      always?: boolean;
      /** Validation groups */
      groups?: string[];
      /** Type-specific options */
      options?: any;
    }[];
  };
}

Custom Validation and Schema

Core Types

/**
 * Validation error object containing details about validation failures
 */
class ValidationError {
  target?: object;
  property: string;
  value?: any;
  constraints?: {[type: string]: string};
  children?: ValidationError[];
  contexts?: {[type: string]: any};
  
  toString(shouldDecorate?: boolean, hasParent?: boolean, parentPath?: string, showConstraintMessages?: boolean): string;
}

/**
 * Options for configuring validation behavior
 */
interface ValidatorOptions {
  skipMissingProperties?: boolean;
  skipNullProperties?: boolean;
  skipUndefinedProperties?: boolean;
  whitelist?: boolean;
  forbidNonWhitelisted?: boolean;
  groups?: string[];
  strictGroups?: boolean;
  dismissDefaultMessages?: boolean;
  validationError?: {
    target?: boolean;
    value?: boolean;
  };
  forbidUnknownValues?: boolean;
  stopAtFirstError?: boolean;
  always?: boolean;
  enableDebugMessages?: boolean;
}

/**
 * Options for individual validation decorators
 */
interface ValidationOptions {
  each?: boolean;
  message?: string | ((args: ValidationArguments) => string);
  groups?: string[];
  always?: boolean;
  context?: any;
}

/**
 * Arguments passed to validation functions and message functions
 */
interface ValidationArguments {
  value: any;
  constraints: any[];
  targetName: string;
  object: object;
  property: string;
}