Validation Decorators

AxilJS validation decorators declare input constraints directly on DTO properties.

They describe the expected shape and constraints of incoming data as semantic metadata. A validation consumer can use this metadata to validate request payloads at runtime, while an OpenAPI consumer can use the same declarations to generate API schemas.

String Validators#

Use string decorators to declare type, length, format, and pattern constraints.

import {
  tString,
  tEmail,
  tUrl,
  tUuid,
  tMinLength,
  tMaxLength,
  tPattern
} from '@axiljs/decorator'
 
class CreateUserDto {
  @tString()
  @tMinLength(2)
  @tMaxLength(100)
  name: string
 
  @tEmail()
  email: string
 
  @tUrl()
  website: string
 
  @tUuid()
  externalId: string
 
  @tPattern(/^[a-z0-9-]+$/)
  slug: string
}

These decorators allow a DTO to express common string requirements such as minimum length, maximum length, email format, URL format, UUID format, and regular-expression constraints.

Number Validators#

Use numeric decorators to define numeric types and value boundaries.

import {
  tNumber,
  tMin,
  tMax
} from '@axiljs/decorator'
 
class ProductDto {
  @tNumber()
  @tMin(0)
  price: number
 
  @tNumber()
  @tMin(0)
  @tMax(10000)
  stock: number
}

For example, tMin(0) prevents values below zero, while tMax(10000) defines an upper boundary.

Type Validators#

AxilJS also provides decorators for booleans, enumerations, optional properties, arrays, and nested DTOs.

import {
  tBoolean,
  tEnum,
  tOptional,
  tArray,
  tNested
} from '@axiljs/decorator'
 
class OrderDto {
  @tBoolean()
  express: boolean
 
  @tEnum(['pending', 'shipped', 'delivered'])
  status: string
 
  @tOptional()
  @tString()
  notes?: string
 
  @tArray()
  @tNested(() => OrderItemDto)
  items: OrderItemDto[]
}

These declarations make the expected DTO structure explicit and provide metadata that validation and schema-generation consumers can interpret.

Custom Validators#

Use tCustom when a validation rule does not fit the built-in validators.

import { tCustom } from '@axiljs/decorator'
 
class ApiKeyDto {
  @tCustom(
    (value) =>
      typeof value === 'string' &&
      value.startsWith('ax_')
  )
  key: string
}

Custom validators let you express application-specific constraints while keeping the validation rule attached to the DTO property.

Full DTO Example#

The decorators can be composed to describe a complete request payload.

class RegisterDto {
  @tString()
  @tMinLength(2)
  @tMaxLength(100)
  name: string
 
  @tEmail()
  email: string
 
  @tString()
  @tMinLength(8)
  @tPattern(/^(?=.*[A-Z])(?=.*\d).+$/)
  password: string
 
  @tOptional()
  @tEnum(['admin', 'user'])
  role?: string
 
  @tOptional()
  @tNumber()
  @tMin(0)
  @tMax(150)
  age?: number
}

This approach keeps validation requirements close to the data contract rather than scattering them across request handlers or infrastructure-specific validation configuration.

Runtime Validation and API Schemas#

AxilJS uses the same decorator metadata for multiple consumers.

A validation consumer can read the declarations at runtime and validate incoming request bodies. An OpenAPI generator can consume the same metadata to produce API schemas.

This provides a single source of truth for DTO validation and API documentation:

DTO Properties
      |
      v
Validation Decorators
      |
      v
Semantic Metadata
      |
      +------------------+
      |                  |
      v                  v
Validation Consumer   OpenAPI Generator
      |                  |
      v                  v
Runtime Validation   API Schema

The important distinction is that the decorators declare constraints; consumers determine how those constraints are enforced or represented.

Reference#

AxilJS validation decorators turn DTO constraints into reusable semantic metadata, allowing runtime validation and API schema generation to operate from the same declarations.