Skip to content

validation-usage.md

Latest commit

 

History

History
1352 lines (1044 loc) · 28.5 KB

validation-usage.md

File metadata and controls

1352 lines (1044 loc) · 28.5 KB

Validation Module - Руководство пользователя

Обзор

The om-data-mapper валидация module provides a высокопроизводительный, class-валидатор-compatible API for validating objects using декораторs. It's разработан как прямая замена for class-validator with 10x better performance through JIT-компиляция.

Установка

npm install om-data-mapper
# or
pnpm add om-data-mapper
# or
yarn add om-data-mapper

Не требуются дополнительные зависимости - unlike class-валидатор, you don't need reflect-metadata.

Быстрый старт

Базовый пример

import { IsString, IsEmail, MinLength, validate } from 'om-data-mapper/class-validator-compat';

class UserDto {
  @IsString()
  @MinLength(3)
  name: string;

  @IsEmail()
  email: string;
}

const user = new UserDto();
user.name = 'Jo';  // Too short
user.email = 'invalid-email';

const errors = await validate(user);
console.log(errors);
// [
// {
// property: 'name',
// constraints: { minLength: 'name должно быть at least 3 characters' }
// },
// {
// property: 'email',
// constraints: { isEmail: 'email должно быть a valid email' }
// }
// ]

Путь импорта

// Import from class-валидатор-compat submodule
import {
  validate,
  validateSync,
  IsString,
  IsNumber,
  MinLength,
  // ... other валидаторs
} from 'om-data-mapper/class-validator-compat';

Функции валидации

validate(object, options?)

Асинхронно валидирует an object. Supports async custom валидаторs.

const errors = await validate(userDto);
if (errors.length > 0) {
  console.log('Validation failed:', errors);
}

validateSync(object, options?)

Синхронно валидирует an object. Не поддерживает async валидаторs.

const errors = validateSync(userDto);
if (errors.length > 0) {
  console.log('Validation failed:', errors);
}

validateOrReject(object, options?)

Валидирует и выбрасывает an error if валидация fails.

try {
  await validateOrReject(userDto);
  console.log('Validation passed!');
} catch (errors) {
  console.log('Validation failed:', errors);
}

validateOrRejectSync(object, options?)

Synchronous Версия of validateOrReject.

try {
  validateOrRejectSync(userDto);
  console.log('Validation passed!');
} catch (errors) {
  console.log('Validation failed:', errors);
}

validateMany(objects, options?)

Валидирует массив of objects.

const users = [user1, user2, user3];
const allErrors = await validateMany(users);
// Возвращает: ValidationError[][]

validateManySync(objects, options?)

Synchronous Версия of validateMany.

const allErrors = validateManySync(users);

Опции валидации

interface ValidatorOptions {
  skipMissingProperties?: boolean;      // Skip undefined properties
  skipNullProperties?: boolean;         // Skip null properties
  skipUndefinedProperties?: boolean;    // Skip undefined properties
  groups?: string[];                    // Validation groups
  always?: boolean;                     // Always validate
  stopAtFirstError?: boolean;           // Stop at first error
  forbidUnknownValues?: boolean;        // Forbid unknown values
  whitelist?: boolean;                  // Remove unknown properties
  forbidNonWhitelisted?: boolean;       // Throw on unknown properties
}

Пример with Опции:

const errors = await validate(user, {
  skipMissingProperties: true,
  groups: ['create'],
  stopAtFirstError: true
});

Доступные декораторы

Общие валидаторы

@IsOptional()

Помечает свойство как необязательное - skips валидация if unОпределитьd.

class UserDto {
  @IsOptional()
  @IsString()
  middleName?: string;
}

@IsDefined()

Проверяет, является ли значение Определитьd (not unОпределитьd).

class UserDto {
  @IsDefined()
  name: string;
}

@IsNotEmpty()

Проверяет, является ли значение not empty.

class UserDto {
  @IsNotEmpty()
  name: string;
}

@Equals(value)

Проверяет, является ли значение equals the specified value.

class ConfigDto {
  @Equals('production')
  environment: string;
}

@NotEquals(value)

Проверяет, является ли значение does not equal the specified value.

class UserDto {
  @NotEquals('admin')
  role: string;
}

@IsIn(values)

Проверяет, является ли значение in an array of allowed values.

class UserDto {
  @IsIn(['admin', 'user', 'guest'])
  role: string;
}

@IsNotIn(values)

Проверяет, является ли значение not in an array of disallowed values.

class UserDto {
  @IsNotIn(['root', 'administrator'])
  username: string;
}

Валидаторы строк

@IsString()

Проверяет, является ли значение a string.

class UserDto {
  @IsString()
  name: string;
}

@MinLength(min)

Checks if string length is at least min.

class UserDto {
  @MinLength(3)
  username: string;
}

@MaxLength(max)

Checks if string length is at most max.

class UserDto {
  @MaxLength(50)
  name: string;
}

@Length(min, max)

Checks if string length is between min and max.

class UserDto {
  @Length(3, 20)
  username: string;
}

@IsEmail()

Проверяет, является ли значение a valid email.

class UserDto {
  @IsEmail()
  email: string;
}

@IsURL()

Проверяет, является ли значение a valid URL.

class UserDto {
  @IsURL()
  website: string;
}

@IsUUID()

Проверяет, является ли значение a valid UUID.

class UserDto {
  @IsUUID()
  id: string;
}

@IsJSON()

Проверяет, является ли значение valid JSON.

class ConfigDto {
  @IsJSON()
  settings: string;
}

@IsAlpha()

Checks if string contains only letters.

class UserDto {
  @IsAlpha()
  firstName: string;
}

@IsAlphanumeric()

Checks if string contains only letters and numbers.

class UserDto {
  @IsAlphanumeric()
  username: string;
}

@IsHexColor()

Проверяет, является ли значение a valid hex color.

class ThemeDto {
  @IsHexColor()
  primaryColor: string;
}

@IsIP()

Проверяет, является ли значение a valid IP address.

class ServerDto {
  @IsIP()
  ipAddress: string;
}

@IsCreditCard()

Проверяет, является ли значение a valid credit card number.

class PaymentDto {
  @IsCreditCard()
  cardNumber: string;
}

@IsISBN()

Проверяет, является ли значение a valid ISBN.

class BookDto {
  @IsISBN()
  isbn: string;
}

@IsPhoneNumber(region?)

Проверяет, является ли значение a valid phone number.

class UserDto {
  @IsPhoneNumber('US')
  phone: string;
}

@Contains(seed)

Checks if string contains the seed.

class UserDto {
  @Contains('@')
  email: string;
}

@NotContains(seed)

Checks if string does not contain the seed.

class UserDto {
  @NotContains('admin')
  username: string;
}

@IsLowercase()

Checks if string is lowercase.

class UserDto {
  @IsLowercase()
  username: string;
}

@IsUppercase()

Checks if string is uppercase.

class CodeDto {
  @IsUppercase()
  countryCode: string;
}

@Matches(pattern)

Checks if string matches a regex pattern.

class UserDto {
  @Matches(/^[a-zA-Z0-9]+$/)
  username: string;
}

@IsFQDN()

Проверяет, является ли значение полным доменным именем (FQDN).

class WebsiteDto {
  @IsFQDN()
  domain: string; // 'example.com', 'subdomain.example.com'
}

@IsISO8601()

Проверяет, является ли значение валидной датой в формате ISO 8601.

class EventDto {
  @IsISO8601()
  startDate: string; // '2024-01-15T10:30:00Z', '2024-01-15'
}

@IsDateString()

Алиас для @IsISO8601(). Проверяет, является ли значение валидной датой в формате ISO 8601.

class EventDto {
  @IsDateString()
  createdAt: string; // '2024-01-15T10:30:00Z'
}

@IsMobilePhone(locale?)

Проверяет, является ли значение валидным номером мобильного телефона. Поддерживает валидацию для конкретных локалей.

class UserDto {
  @IsMobilePhone('en-US')
  phone: string; // '+1-555-123-4567', '555-123-4567'
}

// Без указания локали (принимает различные форматы)
class ContactDto {
  @IsMobilePhone()
  mobile: string;
}

@IsPostalCode(locale?)

Проверяет, является ли значение валидным почтовым индексом. Поддерживает локали US, RU и GB.

class AddressDto {
  @IsPostalCode('US')
  zipCode: string; // '12345', '12345-6789'
}

class RussianAddressDto {
  @IsPostalCode('RU')
  postalCode: string; // '123456'
}

@IsMongoId()

Проверяет, является ли значение валидным MongoDB ObjectId (24-символьная шестнадцатеричная строка).

class DocumentDto {
  @IsMongoId()
  id: string; // '507f1f77bcf86cd799439011'
}

@IsJWT()

Проверяет, является ли значение валидным JWT токеном.

class AuthDto {
  @IsJWT()
  token: string; // 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U'
}

@IsStrongPassword()

Проверяет, является ли значение надежным паролем (минимум 8 символов, заглавные и строчные буквы, цифры, спецсимволы).

class UserDto {
  @IsStrongPassword()
  password: string; // 'MyP@ssw0rd123'
}

@IsPort()

Проверяет, является ли значение валидным номером порта (0-65535).

class ServerDto {
  @IsPort()
  port: string; // '8080', '3000', '443'
}

@IsMACAddress()

Проверяет, является ли значение валидным MAC-адресом.

class DeviceDto {
  @IsMACAddress()
  macAddress: string; // '00:1B:44:11:3A:B7', '00-1B-44-11-3A-B7'
}

@IsBase64()

Проверяет, является ли значение валидной строкой в кодировке base64.

class FileDto {
  @IsBase64()
  content: string; // 'SGVsbG8gV29ybGQ=', 'SGVsbG8gV29ybGQ'
}

@IsIBAN()

Проверяет, является ли значение валидным международным номером банковского счета (IBAN).

class BankAccountDto {
  @IsIBAN()
  iban: string; // 'GB82WEST12345698765432', 'DE89370400440532013000'
}

@IsBIC()

Проверяет, является ли значение валидным банковским идентификационным кодом (BIC/SWIFT).

class BankDto {
  @IsBIC()
  swiftCode: string; // 'DEUTDEFF', 'DEUTDEFF500'
}

@IsCurrency()

Проверяет, является ли значение валидной денежной суммой.

class PaymentDto {
  @IsCurrency()
  amount: string; // '$100.00', '€50.99', '¥1000'
}

@IsISO4217CurrencyCode()

Проверяет, является ли значение валидным кодом валюты по стандарту ISO 4217.

class TransactionDto {
  @IsISO4217CurrencyCode()
  currency: string; // 'USD', 'EUR', 'RUB', 'GBP'
}

@IsEthereumAddress()

Проверяет, является ли значение валидным адресом Ethereum.

class WalletDto {
  @IsEthereumAddress()
  address: string; // '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
}

@IsBtcAddress()

Проверяет, является ли значение валидным адресом Bitcoin (legacy или SegWit).

class CryptoDto {
  @IsBtcAddress()
  btcAddress: string; // '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa', 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq'
}

@IsPassportNumber(locale?)

Проверяет, является ли значение валидным номером паспорта. Поддерживает валидацию для конкретных локалей.

class TravelDto {
  @IsPassportNumber('US')
  passport: string; // '123456789'
}

class InternationalDto {
  @IsPassportNumber()
  passportNumber: string; // Принимает различные форматы
}

@IsIdentityCard(locale?)

Проверяет, является ли значение валидным номером удостоверения личности.

class IdentityDto {
  @IsIdentityCard('ES')
  idCard: string; // 'AB12345678'
}

@IsEAN()

Проверяет, является ли значение валидным европейским артикульным номером (EAN-8 или EAN-13).

class ProductDto {
  @IsEAN()
  barcode: string; // '12345678' (EAN-8), '1234567890123' (EAN-13)
}

@IsISIN()

Проверяет, является ли значение валидным международным идентификационным номером ценной бумаги (ISIN).

class SecurityDto {
  @IsISIN()
  isin: string; // 'US0378331005'
}

@IsMagnetURI()

Проверяет, является ли значение валидным Magnet URI.

class TorrentDto {
  @IsMagnetURI()
  magnetLink: string; // 'magnet:?xt=urn:btih:c12fe1c06bba254a9dc9f519b335aa7c1367a88a'
}

@IsDataURI()

Проверяет, является ли значение валидным Data URI.

class ImageDto {
  @IsDataURI()
  dataUri: string; // 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA'
}

@IsISO31661Alpha2()

Проверяет, является ли значение валидным двухбуквенным кодом страны по стандарту ISO 3166-1 alpha-2.

class AddressDto {
  @IsISO31661Alpha2()
  countryCode: string; // 'US', 'RU', 'GB', 'FR'
}

@IsISO31661Alpha3()

Проверяет, является ли значение валидным трёхбуквенным кодом страны по стандарту ISO 3166-1 alpha-3.

class CountryDto {
  @IsISO31661Alpha3()
  code: string; // 'USA', 'RUS', 'GBR', 'FRA'
}

@IsLocale()

Проверяет, является ли значение валидным кодом локали.

class UserDto {
  @IsLocale()
  locale: string; // 'en-US', 'ru-RU', 'fr-FR', 'en'
}

@IsSemVer()

Проверяет, является ли значение валидной семантической версией.

class PackageDto {
  @IsSemVer()
  version: string; // '1.2.3', '2.0.0-beta.1', '1.0.0+20130313144700'
}

@IsMimeType()

Проверяет, является ли значение валидным MIME-типом.

class FileDto {
  @IsMimeType()
  contentType: string; // 'text/html', 'application/json', 'image/png'
}

@IsTimeZone()

Проверяет, является ли значение валидным часовым поясом.

class EventDto {
  @IsTimeZone()
  timezone: string; // 'America/New_York', 'Europe/Moscow', 'UTC'
}

@IsRFC3339()

Проверяет, является ли значение валидной датой в формате RFC 3339.

class TimestampDto {
  @IsRFC3339()
  timestamp: string; // '2024-01-15T10:30:00Z', '2024-01-15T10:30:00+03:00'
}

Валидаторы чисел

@IsNumber()

Проверяет, является ли значение a number.

class ProductDto {
  @IsNumber()
  price: number;
}

@IsInt()

Проверяет, является ли значение an integer.

class ProductDto {
  @IsInt()
  quantity: number;
}

@Min(min)

Checks if number is at least min.

class ProductDto {
  @Min(0)
  price: number;
}

@Max(max)

Checks if number is at most max.

class ProductDto {
  @Max(100)
  discount: number;
}

@IsPositive()

Checks if number is positive.

class ProductDto {
  @IsPositive()
  price: number;
}

@IsNegative()

Checks if number is negative.

class TransactionDto {
  @IsNegative()
  debit: number;
}

@IsDivisibleBy(num)

Checks if number is divisible by num.

class ProductDto {
  @IsDivisibleBy(5)
  quantity: number;
}

@IsDecimal()

Проверяет, является ли значение a decimal number.

class ProductDto {
  @IsDecimal()
  price: number;
}

Валидаторы дат

@MinDate(date)

Checks if date is after or equal to the specified date.

class EventDto {
  @MinDate(new Date('2024-01-01'))
  startDate: Date;
}

@MaxDate(date)

Checks if date is before or equal to the specified date.

class EventDto {
  @MaxDate(new Date('2024-12-31'))
  endDate: Date;
}

Валидаторы массивов

@IsArray()

Проверяет, является ли значение an array.

class ProductDto {
  @IsArray()
  tags: string[];
}

@ArrayNotEmpty()

Checks if array is not empty.

class ProductDto {
  @ArrayNotEmpty()
  tags: string[];
}

@ArrayMinSize(min)

Checks if array has at least min elements.

class ProductDto {
  @ArrayMinSize(1)
  images: string[];
}

@ArrayMaxSize(max)

Checks if array has at most max elements.

class ProductDto {
  @ArrayMaxSize(10)
  tags: string[];
}

@ArrayContains(values)

Checks if array contains all specified values.

class ProductDto {
  @ArrayContains(['featured'])
  tags: string[];
}

@ArrayNotContains(values)

Checks if array does not contain any of the specified values.

class ProductDto {
  @ArrayNotContains(['banned'])
  tags: string[];
}

@ArrayUnique()

Checks if all array elements are unique.

class ProductDto {
  @ArrayUnique()
  tags: string[];
}

Type Checker Validators

@IsBoolean()

Проверяет, является ли значение a boolean.

class UserDto {
  @IsBoolean()
  isActive: boolean;
}

@IsDate()

Проверяет, является ли значение a Date object.

class EventDto {
  @IsDate()
  startDate: Date;
}

@IsObject()

Проверяет, является ли значение an object.

class UserDto {
  @IsObject()
  metadata: object;
}

@IsEnum(enum)

Проверяет, является ли значение a valid enum value.

enum UserRole {
  Admin = 'admin',
  User = 'user',
  Guest = 'guest'
}

class UserDto {
  @IsEnum(UserRole)
  role: UserRole;
}

@IsInstance(class)

Проверяет, является ли значение an instance of a class.

class UserDto {
  @IsInstance(Date)
  createdAt: Date;
}

@IsNotEmptyObject()

Проверяет, является ли значение a non-empty object.

class UserDto {
  @IsNotEmptyObject()
  settings: object;
}

Geographic Validators

@IsLatLong()

Проверяет, является ли значение a valid latitude-longitude pair.

class LocationDto {
  @IsLatLong()
  coordinates: string;  // "40.7128,-74.0060"
}

@IsLatitude()

Проверяет, является ли значение a valid latitude.

class LocationDto {
  @IsLatitude()
  lat: string;
}

@IsLongitude()

Проверяет, является ли значение a valid longitude.

class LocationDto {
  @IsLongitude()
  lng: string;
}

Advanced Возможности

Вложенная валидация

Use @ValidateNested() to validate nested objects.

import { ValidateNested, IsString } from 'om-data-mapper/class-validator-compat';
import { Type } from 'om-data-mapper/class-transformer-compat';

class Address {
  @IsString()
  street: string;

  @IsString()
  city: string;
}

class UserDto {
  @IsString()
  name: string;

  @ValidateNested()
  @Type(() => Address)
  address: Address;
}

const user = new UserDto();
user.name = 'John';
user.address = new Address();
user.address.street = '';  // Invalid

const errors = await validate(user);
// Errors will include nested валидация errors

Conditional Validation

Use @ValidateIf() to conditionally validate properties.

import { ValidateIf, IsString } from 'om-data-mapper/class-validator-compat';

class UserDto {
  @IsString()
  accountType: string;

  @ValidateIf(o => o.accountType === 'premium')
  @IsString()
  premiumFeature?: string;
}

Группы валидации

Use groups to validate different scenarios.

class UserDto {
  @IsString({ groups: ['create', 'update'] })
  name: string;

  @IsString({ groups: ['create'] })
  password: string;

  @IsString({ groups: ['update'] })
  @IsOptional()
  newPassword?: string;
}

// Validate for Создать
const createErrors = await validate(user, { groups: ['create'] });

// Validate for update
const updateErrors = await validate(user, { groups: ['update'] });

Custom Сообщения об ошибках

Provide custom error messages for валидаторs.

class UserDto {
  @IsString({ message: 'Please provide a valid name' })
  @MinLength(3, { message: 'Name must be at least 3 characters long' })
  name: string;

  @IsEmail({ message: 'Please provide a valid email address' })
  email: string;
}

Dynamic Сообщения об ошибках

Use functions for dynamic error messages.

class UserDto {
  @MinLength(3, {
    message: (args) => `${args.property} is too short. Minimum length is ${args.constraints[0]}`
  })
  name: string;
}

Пользовательские валидаторы

Создать custom валидаторs for complex валидация logic.

import {
  ValidatorConstraint,
  ValidatorConstraintInterface,
  ValidationArguments,
  Validate
} from 'om-data-mapper/class-validator-compat';

@ValidatorConstraint({ name: 'isStrongPassword', async: false })
class IsStrongPasswordConstraint implements ValidatorConstraintInterface {
  validate(value: any, args: ValidationArguments): boolean {
    if (typeof value !== 'string') return false;
    
    const hasUpperCase = /[A-Z]/.test(value);
    const hasLowerCase = /[a-z]/.test(value);
    const hasNumber = /[0-9]/.test(value);
    const hasSpecialChar = /[!@#$%^&*]/.test(value);
    
    return hasUpperCase && hasLowerCase && hasNumber && hasSpecialChar && value.length >= 8;
  }

  defaultMessage(args: ValidationArguments): string {
    return 'Password must contain uppercase, lowercase, number, special character, and be at least 8 characters';
  }
}

class UserDto {
  @Validate(IsStrongPasswordConstraint)
  password: string;
}

Async Пользовательские валидаторы

@ValidatorConstraint({ name: 'isUserAlreadyExist', async: true })
class IsUserAlreadyExistConstraint implements ValidatorConstraintInterface {
  async validate(value: any, args: ValidationArguments): Promise<boolean> {
    // Check database
    const user = await database.findUserByEmail(value);
    return !user;  // Return false if user exists
  }

  defaultMessage(args: ValidationArguments): string {
    return 'User with this email already exists';
  }
}

class CreateUserDto {
  @Validate(IsUserAlreadyExistConstraint)
  email: string;
}

// Must use async validate
const errors = await validate(dto);

Лучшие практики

1. Use Synchronous Validation When Possible

// ✅ Faster
const errors = validateSync(dto);

// ❌ Slower (unless you have async валидаторs)
const errors = await validate(dto);

2. Combine Validators

class UserDto {
  @IsString()
  @MinLength(3)
  @MaxLength(20)
  @Matches(/^[a-zA-Z0-9]+$/)
  username: string;
}

3. Use Группы валидации

// Different валидация rules for different scenarios
class UserDto {
  @IsString({ groups: ['create'] })
  password: string;

  @IsString({ groups: ['update'] })
  @IsOptional()
  newPassword?: string;
}

4. Leverage @IsНеобязательно()

class UserDto {
  @IsString()
  name: string;

  @IsOptional()
  @IsString()
  middleName?: string;  // Only validated if provided
}

5. Use Пользовательские валидаторы for Complex Logic

// Instead of multiple декораторs, Создать a custom валидатор
@Validate(IsComplexBusinessRuleConstraint)
complexField: string;

Migration from class-валидатор

The API is 100% compatible with class-валидатор. Simply change the import:

// Before
import { validate, IsString } from 'class-validator';

// After
import { validate, IsString } from 'om-data-mapper/class-validator-compat';

No other changes needed! Your existing code will work with 10x better performance.

Производительность Советs

  1. Reuse DTOs: Создать DTO instances once and reuse them
  2. Use validateSync: When you don't need async валидаторs
  3. Limit Nested Depth: Deep nesting impacts performance
  4. Use Groups: Validate only what you need
  5. Cache Validators: The first валидация compiles the валидатор, subsequent calls are cached

Справочник API Summary

Functions

  • validate(object, options?) - Async валидация
  • validateSync(object, options?) - Sync валидация
  • validateOrReject(object, options?) - Async валидация with throw
  • validateOrRejectSync(object, options?) - Sync валидация with throw
  • validateMany(objects, options?) - Validate array async
  • validateManySync(objects, options?) - Validate array sync

Decorators

  • Common: @IsOptional(), @IsDefined(), @IsNotEmpty(), @Equals(), @NotEquals(), @IsIn(), @IsNotIn()
  • String: @IsString(), @MinLength(), @MaxLength(), @Length(), @IsEmail(), @IsURL(), @IsUUID(), @Matches()
  • Number: @IsNumber(), @IsInt(), @Min(), @Max(), @IsPositive(), @IsNegative()
  • Date: @MinDate(), @MaxDate()
  • Array: @IsArray(), @ArrayNotEmpty(), @ArrayMinSize(), @ArrayMaxSize(), @ArrayUnique()
  • Type: @IsBoolean(), @IsDate(), @IsObject(), @IsEnum(), @IsInstance()
  • Nested: @ValidateNested(), @ValidateIf(), @ValidatePromise()
  • Custom: @Validate(), @ValidateBy(), @ValidatorConstraint()

Conclusion

The валидация module provides:

  • ✅ 10x faster than class-валидатор
  • ✅ 100% API compatible - прямая замена
  • ✅ No dependencies - no reflect-metadata needed
  • ✅ Type-safe - full TypeScript support
  • ✅ Extensible - custom валидаторs supported

Start validating with confidence! 🚀