Decorators

Validation Decorators

Define TypeScript input validation constraints for DTOs with AxilJS semantic decorators and generate consistent API validation metadata.

4 min readUpdated DocumentationEdit this page
On this page7

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.

TypeScript
TS
1import {
2  tString,
3  tEmail,
4  tUrl,
5  tUuid,
6  tMinLength,
7  tMaxLength,
8  tPattern
9} from '@axiljs/decorator'
10
11class CreateUserDto {
12  @tString()
13  @tMinLength(2)
14  @tMaxLength(100)
15  name: string
16
17  @tEmail()
18  email: string
19
20  @tUrl()
21  website: string
22
23  @tUuid()
24  externalId: string
25
26  @tPattern(/^[a-z0-9-]+$/)
27  slug: string
28}

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.

TypeScript
TS
1import {
2  tNumber,
3  tMin,
4  tMax
5} from '@axiljs/decorator'
6
7class ProductDto {
8  @tNumber()
9  @tMin(0)
10  price: number
11
12  @tNumber()
13  @tMin(0)
14  @tMax(10000)
15  stock: number
16}

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.

TypeScript
TS
1import {
2  tBoolean,
3  tEnum,
4  tOptional,
5  tArray,
6  tNested
7} from '@axiljs/decorator'
8
9class OrderDto {
10  @tBoolean()
11  express: boolean
12
13  @tEnum(['pending', 'shipped', 'delivered'])
14  status: string
15
16  @tOptional()
17  @tString()
18  notes?: string
19
20  @tArray()
21  @tNested(() => OrderItemDto)
22  items: OrderItemDto[]
23}

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.

TypeScript
TS
1import { tCustom } from '@axiljs/decorator'
2
3class ApiKeyDto {
4  @tCustom(
5    (value) =>
6      typeof value === 'string' &&
7      value.startsWith('ax_')
8  )
9  key: string
10}

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.

TypeScript
TS
1class RegisterDto {
2  @tString()
3  @tMinLength(2)
4  @tMaxLength(100)
5  name: string
6
7  @tEmail()
8  email: string
9
10  @tString()
11  @tMinLength(8)
12  @tPattern(/^(?=.*[A-Z])(?=.*\d).+$/)
13  password: string
14
15  @tOptional()
16  @tEnum(['admin', 'user'])
17  role?: string
18
19  @tOptional()
20  @tNumber()
21  @tMin(0)
22  @tMax(150)
23  age?: number
24}

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:

Output
TXT
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

DecoratorPurpose
tStringDeclare a string constraint
tNumberDeclare a numeric constraint
tBooleanDeclare a boolean constraint
tEmailValidate email-formatted strings
tUrlValidate URL-formatted strings
tUuidValidate UUID-formatted strings
tEnumRestrict a value to declared options
tPatternApply a regular-expression constraint
tMinDefine a minimum numeric value
tMaxDefine a maximum numeric value
tMinLengthDefine a minimum string length
tMaxLengthDefine a maximum string length
tOptionalMark a property as optional
tArrayDeclare an array value
tNestedDeclare a nested DTO
tCustomDefine a custom validation rule

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

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY