Generates ConnectDTO
, CreateDTO
, UpdateDTO
, DTO
, and Entity
classes for models in your Prisma Schema. This is useful if you want to leverage OpenAPI in your NestJS application - but also helps with GraphQL resources as well). NestJS Swagger requires input parameters in controllers to be described through classes because it leverages TypeScript's emitted metadata and Reflection
to generate models/components for the OpenAPI spec. It does the same for response models/components on your controller methods.
These classes can also be used with the built-in ValidationPipe and Serialization.
This is a fork of @vegardit/prisma-generator-nestjs-dto and adds multiple features:
- enhance fields with additional schema information, e.g., description, to generate a
@ApiProperty()
decorator (see Schema Object annotations) - optionally add validation decorators
- support for composite types
- control output format with additional flags
flatResourceStructure
,noDependencies
, andoutputType
- optionally auto-format output with prettier
See CHANGELOG for all improvements and changes.
- fix
enum
handling
npm install --save-dev @brakebein/prisma-generator-nestjs-dto
generator nestjsDto {
provider = "prisma-generator-nestjs-dto"
output = "../src/generated/nestjs-dto"
outputToNestJsResourceStructure = "false"
flatResourceStructure = "false"
exportRelationModifierClasses = "true"
reExport = "false"
createDtoPrefix = "Create"
updateDtoPrefix = "Update"
dtoSuffix = "Dto"
entityPrefix = ""
entitySuffix = ""
classValidation = "false"
fileNamingStyle = "camel"
noDependencies = "false"
outputType = "class"
definiteAssignmentAssertion = "false"
requiredResponseApiProperty = "true"
prettier = "false"
}
All parameters are optional.
Parameter = default | Description |
---|---|
output = "../src/generated/nestjs-dto" |
output path relative to your schema.prisma file |
outputToNestJsResourceStructure = "false" |
writes dto s and entities to subfolders aligned with NestJS CRUD generator. Resource module name is derived from lower-cased model name in schema.prisma |
flatResourceStructure = "false" |
If outputToNestJsResourceStructure is true , subfolders dto s and entities are created within the resource folder. Setting this to true will flatten the hierarchy. |
exportRelationModifierClasses = "true" |
Should extra classes generated for relationship field operations on DTOs be exported? |
reExport = "false" |
Should an index.ts be created for every folder? |
createDtoPrefix = "Create" |
phrase to prefix every CreateDTO class with |
updateDtoPrefix = "Update" |
phrase to prefix every UpdateDTO class with |
dtoSuffix = "Dto" |
phrase to suffix every CreateDTO and UpdateDTO class with |
entityPrefix = "" |
phrase to prefix every Entity class with |
entitySuffix = "" |
phrase to suffix every Entity class with |
fileNamingStyle = "camel" |
How to name generated files. Valid choices are "camel" , "pascal" , "kebab" and "snake" . |
classValidation = "false" |
Add validation decorators from class-validator . Not compatible with noDependencies = "true" and outputType = "interface" . |
noDependencies = "false" |
Any imports and decorators that are specific to NestJS and Prisma are omitted, such that there are no references to external dependencies. This is useful if you want to generate appropriate DTOs for the frontend. |
outputType = "class" |
Output the DTOs as class or as interface . interface should only be used to generate DTOs for the frontend. |
definiteAssignmentAssertion = "false" |
Add a definite assignment assertion operator ! to required fields, which is required if strict and/or strictPropertyInitialization is set true in your tsconfig.json's compilerOptions . |
requiredResponseApiProperty = "true" |
If false , add @ApiRequired({ required: false }) to response DTO properties. Otherwise, use required defaults always to true unless field is optional. |
prettier = "false" |
Stylize output files with prettier. |
Annotations provide additional information to help this generator understand your intentions. They are applied as tripple slash comments to a field node in your Prisma Schema. You can apply multiple annotations to the same field.
model Post {
/// @DtoCreateOptional
/// @DtoUpdateHidden
createdAt DateTime @default(now())
/// @DtoCastType(DurationLike, luxon)
timeUntilExpires Json?
}
Annotation | Description |
---|---|
@DtoReadOnly |
omits field in CreateDTO and UpdateDTO |
@DtoCreateHidden |
omits field in CreateDTO |
@DtoUpdateHidden |
omits field in UpdateDTO |
@DtoEntityHidden |
omits field in Entity |
@DtoConnectHidden |
omits field in ConnectDto (applies to @id and @unique fields) |
@DtoApiHidden |
adds @ApiHideProperty decorator to hide field in documentation, class validation remains untouched |
@DtoCreateOptional |
adds field optionally to CreateDTO - useful for fields that would otherwise be omitted (e.g. @id , @updatedAt ) |
@DtoUpdateOptional |
adds field optionally to UpdateDTO - useful for fields that would otherwise be omitted (e.g. @id , @updatedAt ) |
@DtoUpdateRequired |
marks field required in UpdateDTO that is otherwise optional |
@DtoRelationRequired |
marks relation required in Entity although it's optional in PrismaSchema - useful when you don't want (SQL) ON DELETE CASCADE behavior - but your logical data schema sees this relation as required (Note: becomes obsolete once referentialActions are released and stable) |
@DtoRelationCanCreateOnCreate |
adds create option on a relation field in the generated CreateDTO - useful when you want to allow to create related model instances |
@DtoRelationCanConnectOnCreate |
adds connect option on a relation field in the generated CreateDTO - useful when you want/need to connect to an existing related instance |
@DtoRelationCanCreateOnUpdate |
adds create option on a relation field in the generated UpdateDTO - useful when you want to allow to create related model instances |
@DtoRelationCanConnectOnUpdate |
adds connect option on a relation field in the generated UpdateDTO - useful when you want/need to connect to an existing related instance |
@DtoRelationCanDisconnectOnUpdate |
adds disconnect option on a relation field in the generated UpdateDTO - useful when you want/need to disconnect to an existing related instance |
@DtoRelationIncludeId |
include ID of a relation field that is otherwise omitted (use instead of CanCreate /CanConnect annotations, if you just want to pass the IDs) |
@DtoTypeFullUpdate |
in the generated UpdateDTO , use the CreateDTO of the composite type to enforce a complete replacement the old values (see #2) |
@DtoCastType(...) |
in all the generated entities, forces a provided type for this field. Especially useful if you need to cast Json fields at read/write. Note, you must provide at least one and may provide up to 3 arguments in the (...) with this annotation - the first is the name of the type to force for this field, the second and third can be used to add an import for that type at the top of the entity file. For example:
|
@DtoCreateValidateIf(...) |
adds @ValidateIf(...) decorator for field in CreateDTO (for conditional validation by class-validator) |
@DtoUpdateValidateIf(...) |
adds @ValidateIf(...) decorator for field in UpdateDTO (for conditional validation by class-validator) |
With @nestjs/swagger
, you can generate an API specification from code.
Routes, request bodies, query parameters, etc., are annotated with special decorators.
Properties can be annotated with the @ApiProperty()
decorator to add schema object information.
They are partially added at runtime, which will then include type
, nullable
, etc.
But additional information, such as description, need to be added manually.
If using a generator like this, any custom @ApiProperty()
annotation would be overridden when updating the DTOs.
To enhance a field with additional schema information, add the schema property prefixed with @
to the comment section above the field.
Currently, following schema properties are supported:
description
minimum
maximum
exclusiveMinimum
exclusiveMaximum
minLength
maxLength
minItems
maxItems
example
Additionally, special data types are inferred and annotated as well:
Int: { type: 'integer', format: 'int32' }
BigInt: { type: 'integer', format: 'int64' }
Float: { type: 'number', format: 'float' }
Decimal: { type: 'number', format: 'double' }
DateTime: { type: 'string', format: 'date-time' }
This example using @description
and @minimum
tags
/// @description Number of reviews
/// @minimum 9
reviewCount Int @default(0)
will generate @ApiProperty()
decorator with description
and minimum
as properties as well as type
and format
to specify the data type.
@ApiProperty({
description: 'Number of reviews',
minimum: 9,
type: 'integer',
format: 'int32',
})
reviewCount: number;
Default values are added in CreateDTO
and UpdateDTO
.
However, a field with a @default()
attribute is hidden by default in CreateDTO
and UpdateDTO
,
hence requires @DtoCreateOptional
and/or @DtoUpdateOptional
to be present.
If classValidation = "true"
, the generator will add validation decorators from class-validator to each field of CreateDTO
and UpdateDTO
that can then be used in combination with the NestJS ValidationPipe
(see NestJS Auto-validation).
Some decorators will be inferred from the field's attributes.
If the field is optional, it will add @IsOptional()
, otherwise @IsNotEmpty()
.
If the field is a list, it will add @IsArray()
.
Type validators are inferred from the field's type:
String
→@IsString()
Boolean
→@IsBoolean()
Int
→@IsInt()
BigInt
→@IsInt()
Float:
→@IsNumber()
Decimal:
→@IsDecimal()
DateTime
→@IsDateString()
All remaining validation decorators can be added in the comment/documentation section above the field. The parentheses can be omitted if not passing a value.
Prisma Schema
/// @Contains('Product')
name String @db.VarChar(255)
reviewCount Int @default(0)
/// @ArrayNotEmpty
tags String[]
score Float?
Generated output
@IsNotEmpty()
@IsString()
@Contains('Product')
name: string;
@IsOptional()
@IsInt()
reviewCount?: number;
@IsNotEmpty()
@IsArray()
@ArrayNotEmpty()
tags: string[];
@IsOptional()
@IsNumber()
score?: number;
Prisma Schema
generator nestjsDto {
provider = "prisma-generator-nestjs-dto"
output = "../src"
outputToNestJsResourceStructure = "true"
}
model Question {
id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
/// @DtoReadOnly
createdAt DateTime @default(now())
/// @DtoRelationRequired
createdBy User? @relation("CreatedQuestions", fields: [createdById], references: [id])
createdById String? @db.Uuid
updatedAt DateTime @updatedAt
/// @DtoRelationRequired
updatedBy User? @relation("UpdatedQuestions", fields: [updatedById], references: [id])
updatedById String? @db.Uuid
/// @DtoRelationRequired
/// @DtoRelationCanConnectOnCreate
category Category? @relation(fields: [categoryId], references: [id])
categoryId String? @db.Uuid
/// @DtoCreateOptional
/// @DtoRelationCanCreateOnCreate
/// @DtoRelationCanConnectOnCreate
/// @DtoRelationCanCreateOnUpdate
/// @DtoRelationCanConnectOnUpdate
tags Tag[]
title String
content String
responses Response[]
}
Generated results
// src/question/dto/connect-question.dto.ts
export class ConnectQuestionDto {
id: string;
}
// src/question/dto/create-question.dto.ts
import { ApiExtraModels } from '@nestjs/swagger';
import { ConnectCategoryDto } from '../../category/dto/connect-category.dto';
import { CreateTagDto } from '../../tag/dto/create-tag.dto';
import { ConnectTagDto } from '../../tag/dto/connect-tag.dto';
export class CreateQuestionCategoryRelationInputDto {
connect: ConnectCategoryDto;
}
export class CreateQuestionTagsRelationInputDto {
create?: CreateTagDto[];
connect?: ConnectTagDto[];
}
@ApiExtraModels(
ConnectCategoryDto,
CreateQuestionCategoryRelationInputDto,
CreateTagDto,
ConnectTagDto,
CreateQuestionTagsRelationInputDto,
)
export class CreateQuestionDto {
category: CreateQuestionCategoryRelationInputDto;
tags?: CreateQuestionTagsRelationInputDto;
title: string;
content: string;
}
// src/question/dto/update-question.dto.ts
import { ApiExtraModels } from '@nestjs/swagger';
import { CreateTagDto } from '../../tag/dto/create-tag.dto';
import { ConnectTagDto } from '../../tag/dto/connect-tag.dto';
export class UpdateQuestionTagsRelationInputDto {
create?: CreateTagDto[];
connect?: ConnectTagDto[];
}
@ApiExtraModels(CreateTagDto, ConnectTagDto, UpdateQuestionTagsRelationInputDto)
export class UpdateQuestionDto {
tags?: UpdateQuestionTagsRelationInputDto;
title?: string;
content?: string;
}
// src/question/entities/question.entity.ts
import { User } from '../../user/entities/user.entity';
import { Category } from '../../category/entities/category.entity';
import { Tag } from '../../tag/entities/tag.entity';
import { Response } from '../../response/entities/response.entity';
export class Question {
id: string;
createdAt: Date;
createdBy?: User;
createdById: string;
updatedAt: Date;
updatedBy?: User;
updatedById: string;
category?: Category;
categoryId: string;
tags?: Tag[];
title: string;
content: string;
responses?: Response[];
}
Generally we read field properties from the DMMF.Field
information provided by @prisma/generator-helper
. Since a few scenarios don't become quite clear from that, we also check for additional annotations (or decorators
) in a field's documentation
(that is anything provided as a tripple slash comments for that field in your prisma.schema
).
Initially, we wanted DTO
classes to implement Prisma.<ModelName><(Create|Update)>Input
but that turned out to conflict with required relation fields.
This kind of DTO represents the structure of input-data to expect from 'outside' (e.g. REST API consumer) when attempting to connect
to a model through a relation field.
A Model
s ConnectDTO
class is composed from a unique'd list of isId
and isUnique
scalar fields. If the ConnectDTO
class has exactly one property, the property is marked as required. If there are more than one properties, all properties are optional (since setting a single one of them is already sufficient for a unique query) - you must however specify at least one property.
ConnectDTO
s are used for relation fields in CreateDTO
s and UpdateDTO
s.
This kind of DTO represents the structure of input-data to expect from 'outside' (e.g. REST API consumer) when attempting to create
a new instance of a Model
.
Typically the requirements for database schema differ from what we want to allow users to do.
As an example (and this is the opinion represented in this generator), we don't think that relation scalar fields should be exposed to users for create
, update
, or delete
activities (btw. TypeScript types generated in PrismaClient exclude these fields as well). If however, your schema defines a required relation, creating an entity of that Model would become quite difficult without the relation data.
In some cases you can derive information regarding related instances from context (e.g. HTTP path on the rest endpoint /api/post/:postid/comment
to create a Comment
with relation to a Post
). For all other cases, we have the
@DtoRelationCanCreateOnCreate
@DtoRelationCanConnectOnCreate
@DtoRelationCanCreateOnUpdate
@DtoRelationCanConnectOnUpdate
annotations that generate corresponding input properties on CreateDTO
and UpdateDTO
(optional or required - depending on the nature of the relation).
When generating a Model
s CreateDTO
class, field that meet any of the following conditions are omitted (order matters):
isReadOnly
OR is annotated with@DtoReadOnly
(Note: this apparently includes relation scalar fields)- field represents a relation (
field.kind === 'object'
) and is not annotated with@DtoRelationCanCreateOnCreate
or@DtoRelationCanConnectOnCreate
- field is a relation scalar
- field is not annotated with
@DtoCreateOptional
AND
When generating a Model
s UpdateDTO
class, field that meet any of the following conditions are omitted (order matters):
- field is annotated with
@DtoUpdateOptional
isReadOnly
OR is annotated with@DtoReadOnly
(Note: this apparently includes relation scalar fields)isId
(id fields are not supposed to be updated by the user)- field represents a relation (
field.kind === 'object'
) and is not annotated with@DtoRelationCanCreateOnUpdate
or@DtoRelationCanConnectOnUpdate
- field is a relation scalar
- field is not annotated with
@DtoUpdateOptional
AND
When generating a Model
s Entity
class, only fields annotated with @DtoEntityHidden
are omitted.
All other fields are only manipulated regarding their isRequired
and isNullable
flags.
By default, every scalar field in an entity is required
meaning it doesn't get the TypeScript "optional member flag" ?
next to it's name. Fields that are marked as optional in PrismaSchema are treated as nullable
- meaning their TypeScript type is a union of field.type
and null
(e.g. string | null
).
Relation and relation scalar fields are treated differently. If you don't specifically include
a relation in your query, those fields will not exist in the response.
- every relation field is always optional (
isRequired = false
) - relations are nullable except when
- the relation field is a one-to-many or many-to-many (i.e. list) type (would return empty array if no related records found)
- the relation was originally flagged as required (
isRequired = true
) - the relation field is annotated with
@DtoRelationRequired
(do this when you mark a relation as optional in PrismaSchema because you don't want (SQL)ON DELETE CASCADE
behavior - but your logical data schema sees this relation as required)
- default values are not added to the
@ApiProperty()
decorator
The plain DTO
class is almost the same as Entity
with the difference that all relation fields are omitted.
This is useful if your response is the plain entity without any (optional) relations.
All files are released under the Apache License 2.0.