nest-dto

NestJS DTO decorator composition.

What Problem Does This Project Solve?

Data transfer objects (DTOs) in the NestJS ecosystem typically rely on decorators from several libraries, including:

• class-transformer
• class-validator
• @nestjs/swagger

As a result, a single DTO property often needs to be decorated several times and needs each of these decorators to be defined consistently. Over the course of a large project with many DTOs, a large amount of code will be dedicated to these definitions and small inconsistencies often creep into the definitions.

nest-dto provides a simplified set of decorators that compose over the library decorators.

An Example

A DTO for an HTTP API that generates an OpenAPI spec might need all of the following decorators for a single property:

1import { ApiProperty } from '@nestjs/swagger';
2import { Type } from 'class-transformer';
3import { IsDefined, IsInt } from 'class-validator';
4
5export class ExampleDTO {
6
7    @Type(() => Number)
8    @IsDefined()
9    @IsInt()
10    @ApiProperty({
11        description: 'An example value',
12        type: integer,
13    })
14    public value!: number;
15}

With nest-dto, this declaration becomes:

1import { IsInteger } from '@hippo-oss/nest-dto/openapi';
2
3
4export class ExampleDTO {
5
6    @IsInteger({
7        description: 'An example value',
8    })
9    public value!: number;
10}

Flavors

Different combinations of the library decorators produce different behaviors. nest-dto defines collections of foundational decorators (e.g. IsString or IsNumber) in "flavors" that use specific combination of these libraries.

Flavor	Description
strict	Integrates class-transformer and class-validator and always uses @Expose()
openapi	Integrates class-transformer, class-validator, and @nestjs/swagger

Decorators

The following decorators are supported:

Decorator	Description
IsArray	Declares an array of a nested type.
IsBoolean	Declares a boolean value.
IsDate	Declares a Date value.
IsDateString	Declares an ISO 8601 date string.
IsEnum	Declares an enumerated value.
IsInteger	Declares an integer number.
IsNested	Declares a nested object type.
IsNumber	Declares a floating point number.
IsString	Declares a string.
IsUUID	Declares a UUID string.

Decorator Options

Decorators may be passed various options, depending on their type.

All options are optional expect where indicated.

Option	Decorator	Description
description	all	Description of the field; exposed in OpenAPI.
expose	all	Enables alternate name to be set for the field.
isArray	all	Designates an array of values.
name	all	Alternate name of the field; exposed in OpenAPI.
nullable	all	Whether the field can be set to null.
optional	all	Whether the field be set to undefined or omitted.
deprecated	all	Whether the field appears as deprecated
-----------------	--------------	---------------------------------------------------
type (required)	IsArray	The type of the array's items.
maxItems	IsArray	The maximum number of array items.
minItems	IsArray	The minimum number of array items.
-----------------	--------------	---------------------------------------------------
format	IsDate	The OpenaPI date format; defaults to date-time.
-----------------	--------------	---------------------------------------------------
format	IsDateString	The OpenAPI date format; defaults to date.
-----------------	--------------	---------------------------------------------------
enum (required)	IsEnum	The enum type.
enumName	IsEnum	The enum name; required to correctly export OpenAPI
-----------------	--------------	---------------------------------------------------
maxValue	IsInteger	The maximum value of the field.
minValue	IsInteger	The minimum value of the field.
-----------------	--------------	---------------------------------------------------
type (required)	IsNested	The nested type.
-----------------	--------------	---------------------------------------------------
maxValue	IsNumber	The maximum value of the field.
minValue	IsNumber	The minimum value of the field.
-----------------	--------------	---------------------------------------------------
maxLength	IsString	The maximum length of the string.
minLength	IsString	The minimum length of the string.
pattern	IsString	A regex pattern for validating the string.
-----------------	--------------	---------------------------------------------------
version	IsUUID	The type of UUID.

Arrays

The easiest (and preferred) way to define arrays is to add the isArray argument to another decorator:

1class Example {
2   @IsString({
3       isArray: true,
4   })
5   values!: string[];
6}

The isArray option may be supplied as either the literal true or as ArraySizeOptions:

1class Example {
2   @IsString({
3       isArray: {
4           maxSize: 30,
5           minSize: 0,
6       },
7   })
8   values!: string[];
9}

Note that while the IsArray decorator is also supported, it is less well-suited for defining arrays of value types using a consistent interface and may be deprecated in the future.

Enums

Enumerated types work pretty much as expected:

1enum Color {
2  Red = 'Red',
3  Blue = 'Blue',
4  Green = 'Green',
5}
6
7class Example {
8   @IsEnum({
9      enum: Color,
10      enumName: 'Color',
11   })
12   color!: Color;
13}

The enumName value is optional, but if omitted causes OpenAPI generation to treat the enum as a value type rather than as $ref to a shared type. This choice may matters when generating code from an OpenAPI spec because most code generators will produce different types for every enum value, even if they share the same enumerated values. Defining an enumName (and therefore a $ref declaration) ensures that generated code sees each use of the same enum as the same type.

Nested Types

Decorator values that use another object type should be decorated with IsNested:

1class Child {
2    @IsString()
3    value!: string;
4}
5
6class Parent {
7     @IsNested({
8         type: Child,
9     })
10     child!: Child;
11}

Every child type is expected to define at least one decorator field. Failure to do so may result in errors from class-transformer.