Dto

Create Dto

For example, we create a Dto studentCreate in the module demo-student

1. Cli command

$ vona :create:bean dto studentCreate --module=demo-student

2. Menu command

TIP

Context Menu - [Module Path]: Vona Create/Dto

Dto Definition

@Dto<IDtoOptionsStudentCreate>()
export class DtoStudentCreate {}

• Use Dto decorator

@Api.field

Generally speaking, when defining a field, you need to specify the field type, validation rules, and Swagger/Openapi metadata

The usage of @Api.field in Dto is the same as that of Entity

• See: Entity

Example

• name: string, min(3), title: 'Name'(supports I18n)

• description: string, optional, title: 'Description'(supports I18n)

class DtoStudentCreate {
  @Api.field(v.openapi({ title: $locale('Name') }), v.min(3))
  name: string;

  @Api.field(v.openapi({ title: $locale('Description') }), v.optional())
  description?: string;
}

Dto Options

Name	Description
independent	Whether to display independently in Swagger/Openapi, default is false
openapi	Metadata related to Swagger/Openapi
fields	Define Fields options

• independent: If the Controller Action references an dto, the dto will be automatically output to Swagger/Openapi. If independent: true is specified, the dto will always be output to Swagger/Openapi

1. Example: openapi

Provide description metadata for dto so that it can be displayed in Swagger/Openapi

@Dto({
  openapi: { description: 'Create Student' },
})
class DtoStudentCreate {}

• Support I18n

Create language resources:

src/module/demo-student/src/config/locale/en-us.ts

export default {
  CreateStudent: 'Create Student',
};

src/module/demo-student/src/config/locale/zh-cn.ts

export default {
  CreateStudent: '创建学生',
};

Use $locale function for language translation

import { $locale } from '../.metadata/index.ts';

@Dto({
  openapi: { description: $locale('CreateStudent') },
})
class DtoStudentCreate {}

2. Example: fields

Change the openapi metadata of the field name to: title: 'Student Name'

@Dto({
  fields: {
    name: { title: 'Student Name' },
  },
})
class DtoStudentCreate {}

Or:

import z from 'zod';

@Dto({
  fields: {
    name: z.string().openapi({ title: 'Student Name' }),
  },
})
class DtoStudentCreate {}

App config configuration

Dto options can be configured in App config

src/backend/config/config/config.dev.ts

// onions
config.onions = {
  dto: {
    'demo-student:studentCreate': {
      openapi: {
        description: 'Create Student',
      },
      fields: {
        name: { title: 'Student Name' },
      },
    },
  },
};

Mapped Class

In the above, we define two fields for DtoStudentCreate: name and description. In fact, these two fields are also defined in EntityStudent. In order to achieve code reuse and improve development efficiency, Vona provides 4 Mapped tool functions to derive the target class from the existing class

1. $Class.pick

Extract the two fields name and description from EntityStudent to generate Dto DtoStudentCreate

class DtoStudentCreate extends $Class.pick(EntityStudent, ['name', 'description']) {}

2. $Class.partial

Change all fields in DtoStudentCreate to optional and generate Dto DtoStudentUpdate

class DtoStudentUpdate extends $Class.partial(DtoStudentCreate) {}

Change the field name in DtoStudentCreate to optional and generate Dto DtoStudentUpdate

class DtoStudentUpdate extends $Class.partial(DtoStudentCreate, ['name']) {}

3. $Class.omit

Exclude the field id in EntityStudent and generate Dto DtoStudentOther

class DtoStudentOther extends $Class.omit(EntityStudent, ['id']) {}

4. $Class.mixin

Merge the fields in multiple classes to generate a new Dto DtoStudentOther

class DtoStudentOther extends $Class.mixin(EntityStudent, DtoStudentCreate, DtoStudentUpdate) {}

5. Combination

You can combine multiple Mapped tool functions

class DtoStudentUpdate
  extends $Class.partial($Class.pick(EntityStudent, ['name', 'description'])) {}

$Dto tools

Vona also provides commonly used $Dto tools to further simplify the code

1. $Dto.create

Take DtoStudentCreate as an example. As mentioned earlier, $Class.pick(EntityStudent, ['name', 'description']) picks the specified fields from EntityStudent. Then, we can change the idea and omit some built-in fields from EntityStudent, and the remaining fields are the required fields

class DtoStudentCreate extends $Dto.create(() => ModelStudent) {}

2. $Dto.update

Similarly, omit some built-in fields from EntityStudent and convert them to optional fields to get DtoStudentUpdate

class DtoStudentUpdate extends $Dto.update(() => ModelStudent) {}