Prisma Generator NestJS DTO

1. What is it?
2. Usage
3. Annotations
4. Example
5. Principles
6. License

What is it?

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, and outputType
• optionally auto-format output with prettier

See CHANGELOG for all improvements and changes.

Usage?

npm install --save-dev @brakebein/prisma-generator-nestjs-dto

generator nestjsDto {
  provider                        = "prisma-generator-nestjs-dto"
  output                          = "../src/generated/nestjs-dto"
  prismaClientImportPath          = ""
  outputToNestJsResourceStructure = "false"
  flatResourceStructure           = "false"
  exportRelationModifierClasses   = "true"
  reExport                        = "false"
  generateFileTypes               = "all"
  createDtoPrefix                 = "Create"
  updateDtoPrefix                 = "Update"
  dtoSuffix                       = "Dto"
  entityPrefix                    = ""
  entitySuffix                    = ""
  classValidation                 = "false"
  fileNamingStyle                 = "camel"
  noDependencies                  = "false"
  outputType                      = "class"
  definiteAssignmentAssertion     = "false"
  requiredResponseApiProperty     = "true"
  jsdoc                           = "false"
  prettier                        = "false"
  wrapRelationsAsType             = "false"
  showDefaultValues               = "false"
}

Parameters

All parameters are optional.

Annotations

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())
  /// @DtoOverrideType(DurationLike, luxon)
  timeUntilExpires Json?
}

Schema Object annotations

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' }

Example

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.

Validation decorators

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.

Example

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;

Example

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[]
}

// 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[];
}

Principles

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.

ConnectDTO

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 Models 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.

ConnectDTOs are used for relation fields in CreateDTOs and UpdateDTOs.

CreateDTO

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 Models 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
  • isId && hasDefaultValue (id fields are not supposed to be provided by the user)
  • isUpdatedAt (Prisma will inject value)
  • isRequired && hasDefaultValue (for schema-required fields that fallback to a default value when empty. Think: createdAt timestamps with @default(now()) (see now()))

UpdateDTO

When generating a Models 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
  • isId (id fields are not supposed to be updated by the user)
  • isUpdatedAt (Prisma will inject value)
  • isRequired && hasDefaultValue (for schema-required fields that fallback to a default value when empty. Think: createdAt timestamps with @default(now()) (see now()))

Entity

When generating a Models 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

DTO

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.

License

All files are released under the Apache License 2.0.