DTO - Odi

Odi
GitHub
Search…
Read Me
DTO
General
DTO(Data Transfer Object) is used for parsing and validating data from request. DTOs always used with Controllers.
Validation
It's a common scenario when web server should validate data before processing. DTO can optimize and automate this process.
Overview
Let's imagine that we need to implement this API.
Request
Response
Accepts application/json in following format:
1
{
2
  title: string,
3
  description: string
4
}
Copied!
With following limitations:
title - required, max length - 80 chars.

description - optional, max length - 255 chars.
Return id in response
1
10125
Copied!
Let's start from DTO class
1
import { Data, IsOptional, MaxLength } from "odi/dto";
2
​
3
@Data()
4
export class TodoDTO {
5
​
6
    @MaxLength(80)
7
    title: string;
8
​
9
    @IsOptional()
10
    @MaxLength(255)
11
    desctiption: string;
12
    
13
}
Copied!
And controller with some predefined service
1
import { Controller, IController, Post, Autowired } from "odi";
2
import TodoService from "./todo.service";
3
​
4
@Controller('todo')
5
export class TodoController extends IController {
6
    
7
    @Autowired()
8
    todoService: TodoService;   
9
         
10
    @Post async index(payload: TodoDTO) {
11
        const { id } = await this.todoService.create(payload);
12
                
13
        return id;
14
    }
15
​
16
}
Copied!
Data from request body will be automatically injected and validated. If validation failed - errors will be automatically sent to client.
DTO definition
Currently, there are two types of DTO, for querystring and body validation.
Decorators
@Data() - set DTO for handling body

@Query() - set DTO for handling querystring
Handler Injection
There are no additional actions required for including DTO in the handler (method of the controller). Just add DTO  (or multiple) as an argument.
1
@Post async index(body: BodyDTO, query: QueryDTO) {
2
   //..code
3
}
Copied!
Decorators for validation
There are set of decorators for convenient data validation. If you have special needs on validation, you can always implement your own decorator (read more in advanced). But custom decorators can be implemented. Read in Advanced about it.
Decorators can be grouped by data type
General
This decorators can be applied to any type of data.
@IsOptional() - set field optional (by default, all fields are required)

@Const(value: any) - field is valid if it is deeply equal to the passed value

@Deafault(value: any) - default value for field, if it not exists

@Enum(enumrable: any[]) - data is valid if it is deeply equal to one of items in the array

@Nested() - validate nested DTO class, otherwise field will be ignored

Decorator @Nested should be applied on field, which type is DTO class.
String
@MaxLength(maxLength: number) - data to be valid should have length satisfying this rule

@MinLength(minLength: number) - data to be valid should have length satisfying this rule

@Pattern(pattern: string | RegExp) - data to be valid should match the regular expression

@Format(format: ValidatorFormat) - data to be valid should match the format

@IsEmail()- data to be valid should be email (Format alias)

@IsUrl() - data to be valid should be url (Format alias)
Following formats for @Format decorator available:
1
"date"
2
"time"
3
"date-time"
4
"uri"
5
"uri-reference"
6
"uri-template"
7
"url"
8
"email"
9
"hostname"
10
"ipv4"
11
"ipv6"
12
"regex"
13
"uuid"
14
"json-pointer"
15
"relative-json-pointer"
Copied!
Number
@Maximum(maximum: number) -  data to be valid should be <= maximum

@Minimum(minimum: number) -  data to be valid should be >= minumum

@ExclusiveMaximum(exclusiveMaximum: number) -  data to be valid should be < maximum
​
@ExclusiveMinimum(exclusiveMinimum: number) -  data to be valid should be > minimum

@MultipleOf(multipleOf: number)-  data to be valid should be a multiple of the multipleOf 
Array
@ArrayOf(targetClass: any) -  sets type of array items

@UniqueItems()- array to be valid should have unique items

@MaxItems(maxItems: number)-  array to be valid should not have less items than the maxItems
​
@MinItems(minItems: number) - array to be valid should not have more items than the minItems
@ArraoyOf can be used only if array item type is another DTO class. As typescript does not provide reflection for complex types, type should be setted manually.
Others
@CustomValidation(validate: ValidateFunction, params: any = true) - define custom validation function for field. Validate function can be async.
Transformation
Data transformation from plain object to DTO instance applied automatically. But don't forget about @ArraoyOf decorator for DTOs arrays.
Inheritance
You can easily use inheritance (extends) for DTOs.
1
import { Data, Format, MaxLength, IsOptional } from "odi/dto";
2
​
3
@Data()
4
class BaseDTO {
5
    
6
    @Format('uuid')
7
    id: string;
8
    
9
}
10
​
11
@Data()
12
class TodoDTO extends BaseDTO {
13
​
14
    @MaxLength(80)
15
    title: string;
16
​
17
    @IsOptional()
18
    desctiption: string;
19
        
20
}
Copied!
TodoDTO will inherit all properties from base class for both transformation and validation purposes.
Flow
Every controller method that contains DTO class as argument will be automatically provided with validated and mapped data. Validation will be performed before controller method call.
Only after transformation, DTO will be injected into method call. Under the hood ajv is used. Decorators is used to build schema.
​
Controller
Service
Last modified 3yr ago
Copy link
Contents
Decorators for validation
Transformation
Inheritance
Flow