Entity Dto

STEP 1 — Gather field specification

Ask the user for missing information. Required:

• Domain name (singular PascalCase): e.g. Invoice, Lead, Conversation
• Fields: for each field provide:
  • name (camelCase)
  • TypeScript type: string | number | boolean | Date | Decimal | enum:EnumName | jsonb | uuid
  • nullable? (default: false)
  • unique? (default: false)
  • default value? (optional)
  • sensitive? — tokens, keys, passwords (will add EncryptionTransformer + @ApiHideProperty() + @Exclude())
  • in DTO? (default: true — set false for system-managed fields like agencyId)
• Relations: for each relation:
  • type: ManyToOne | OneToMany | OneToOne | ManyToMany
  • target entity (PascalCase)
  • owning side? (add @JoinColumn here)
  • cascade? onDelete behavior?
• Which service: tenant | platform | auth (default: tenant)
• Needs indices? Beyond the default ['id'] index — e.g. ['agencyId', 'status'] for frequent filters

Do NOT invent fields. If the description is vague, ask for clarification.

STEP 2 — Derive naming and paths

From domain name (e.g. Invoice):

• domainPlural → invoices
• tableName → invoice (snake_case singular)
• Entity path: libs/common/src/entities/tenant/<domainPlural>/<tableName>.entity.ts
• Create DTO path: libs/common/src/dto/tenant/<domainPlural>/create-<tableName>.dto.ts
• Update DTO path: libs/common/src/dto/tenant/<domainPlural>/update-<tableName>.dto.ts

STEP 3 — Generate the Entity

Rules — strictly follow these

Structure:

• Always extends BaseEntity (from @app/common/database) — never redefine id, createdAt, updatedAt, deletedAt
• @Entity('table_name') — singular snake_case
• Always add @Index(['id']) as minimum — add composite indices for fields used together in WHERE clauses
• Use @Unique([...]) for unique constraints across multiple columns (not just unique: true on column)

Columns:

• Always specify { name: 'snake_case_name' } explicitly — TypeORM does NOT auto-convert camelCase
• string → @Column({ name: 'field_name', nullable: false }) (default type is varchar)
• string with length → @Column({ name: 'field_name', length: 255 })
• text (no length limit) → @Column({ name: 'field_name', type: 'text' })
• number integer → @Column({ name: 'field_name', type: 'int' })
• number float → @Column({ name: 'field_name', type: 'float' })
• Decimal (money/precision) → @Column({ name: 'field_name', type: 'decimal', precision: 12, scale: 6, transformer: new DecimalColumnTransformer() })
• boolean → @Column({ name: 'field_name', type: 'boolean', default: false })
• Date timestamp → @Column({ name: 'field_name', type: 'timestamp', nullable: true })
• enum → @Column({ name: 'field_name', type: 'enum', enum: SomeEnum, default: SomeEnum.VALUE })
• jsonb → @Column({ name: 'field_name', type: 'jsonb', nullable: true, default: {} })
• uuid FK column → @Column({ name: 'related_id', type: 'uuid', nullable: false })
• Sensitive fields: add transformer: new EncryptionTransformer() + @ApiHideProperty() + @Exclude()

Swagger:

• @ApiProperty({ description: '...', example: ..., required: true/false, nullable: true/false }) on every public column
• @ApiHideProperty() on sensitive/internal fields (tokens, keys, internal IDs not exposed)
• Never expose FK UUID columns directly if there is a relation — annotate the relation instead

Relations:

• Always define both sides
• Owning side (FK column exists here): add @JoinColumn({ name: 'fk_name', referencedColumnName: 'id' })
• Composite FK: use array in @JoinColumn([{ name: 'fk1', referencedColumnName: 'field1' }, ...])
• Add onDelete: 'CASCADE' only when parent deletion should cascade
• For OneToMany: no @JoinColumn, the FK is on the other side
• Always declare FK column separately (e.g. agentId: string) alongside the relation object

toResponseDto():

• Always implement — returns a plain object matching the proto type <Domain>Data
• Use null-safe access for optional relations: this.relation ? this.relation.toResponseDto() : undefined
• Map Date fields as-is (not .toISOString())
• Never expose sensitive fields (@Exclude() fields must not appear in toResponseDto)
• Arrays: use .map() with null guard: this.items ? this.items.map(i => i.toResponseDto()) : []

import { ApiHideProperty, ApiProperty } from '@nestjs/swagger';
import { Exclude } from 'class-transformer';
import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
import { BaseEntity } from '@app/common/database';
import { EncryptionTransformer } from '@app/common/database/transformers/encryption.transformer';
import DecimalColumnTransformer from '@app/common/utils/decimal.util';
import { <Domain>Data } from '@app/common/types/proto/tenant/<domainPlural>/<tableName>-interface';
// import related entities...

@Entity('<tableName>')
@Index(['id'])
// Add composite indices for frequently filtered combinations:
// @Index(['agencyId', 'status'])
export class <Domain>Entity extends BaseEntity {

  // --- Public fields ---
  @ApiProperty({ description: 'Field description', example: 'example value', nullable: false })
  @Column({ name: 'field_name', nullable: false })
  fieldName: string;

  // --- Enum field ---
  @ApiProperty({ description: 'Status', enum: StatusEnum, example: StatusEnum.ACTIVE })
  @Column({ name: 'status', type: 'enum', enum: StatusEnum, default: StatusEnum.ACTIVE })
  status: StatusEnum;

  // --- Decimal (money/precision) field ---
  @ApiProperty({ description: 'Amount', example: 100.00 })
  @Column({ name: 'amount', type: 'decimal', precision: 12, scale: 6, default: 0,
    transformer: new DecimalColumnTransformer() })
  amount: Decimal;

  // --- Sensitive field (never in API response) ---
  @ApiHideProperty()
  @Exclude()
  @Column({ name: 'secret_token', nullable: true, transformer: new EncryptionTransformer() })
  secretToken: string | null;

  // --- FK column + relation ---
  @ApiProperty({ description: 'Parent agency ID' })
  @Column({ name: 'agency_id', type: 'uuid', nullable: false })
  agencyId: string;

  @ManyToOne(() => AgencyEntity, agency => agency.<domainPlural>, { onDelete: 'CASCADE' })
  @JoinColumn({ name: 'agency_id', referencedColumnName: 'id' })
  agency: AgencyEntity;

  // --- OneToMany (no @JoinColumn here, FK is on child) ---
  @OneToMany(() => Child<Domain>Entity, child => child.<domainSingular>)
  children: Child<Domain>Entity[];

  toResponseDto(): <Domain>Data {
    return {
      id: this.id,
      fieldName: this.fieldName,
      status: this.status,
      agencyId: this.agencyId,
      createdAt: this.createdAt,
      updatedAt: this.updatedAt,
      // Relations (null-safe):
      agency: this.agency ? this.agency.toResponseDto() : undefined,
      children: this.children ? this.children.map(c => c.toResponseDto()) : [],
      // NEVER include secretToken or other @Exclude() fields
    };
  }
}

STEP 4 — Generate the Create DTO

Rules

Imports:

• ApiProperty / ApiPropertyOptional from @nestjs/swagger
• Only import validators actually used — don't over-import

Per field type:

• Required string → @ApiProperty() + @IsString() + @IsNotEmpty()
• Required string with max length → add @MaxLength(N, { message: '...' })
• Optional string → @ApiPropertyOptional() + @IsOptional() + @IsString()
• uuid → @IsUUID() + @IsNotEmpty() (or @IsOptional())
• number integer → @IsInt(), float → @IsNumber()
• number with range → add @Min(N) + @Max(N) with messages
• boolean → @IsBoolean()
• enum → @IsEnum(EnumType, { message: '...' })
• URL string → @IsUrl()
• Nested DTO → @ValidateNested() + @Type(() => NestedDto)
• Array of nested → @IsArray() + @ValidateNested({ each: true }) + @Type(() => ItemDto)
• Complex proto/JSON field with string serialization → add @Transform() to parse JSON string → object

Rules:

• @IsOptional() must come BEFORE type validators — order matters
• Never stack @IsNotEmpty() on a field that also has @IsOptional()
• System-managed fields (agencyId, subAccountId, etc.) never go in the Create DTO — they come from context
• No duplicate validators (e.g. don't add @IsString() + @IsNotEmpty() + @IsUUID() — UUID already implies string)

import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { Type } from 'class-transformer';
import {
  IsEnum, IsInt, IsNotEmpty, IsOptional, IsString, IsUUID,
  Max, MaxLength, Min, ValidateNested,
} from 'class-validator';

export class Create<Domain>Dto {
  @ApiProperty({ description: 'Required string field', example: 'value' })
  @IsString()
  @IsNotEmpty()
  @MaxLength(100, { message: 'fieldName cannot exceed 100 characters' })
  fieldName: string;

  @ApiPropertyOptional({ description: 'Optional UUID reference' })
  @IsOptional()
  @IsUUID()
  relatedId?: string;

  @ApiPropertyOptional({ description: 'Optional enum', enum: StatusEnum })
  @IsOptional()
  @IsEnum(StatusEnum, { message: 'status must be a valid StatusEnum value' })
  status?: StatusEnum;

  @ApiProperty({ description: 'Integer in range', example: 10 })
  @IsInt({ message: 'limit must be an integer' })
  @Min(1, { message: 'limit must be at least 1' })
  @Max(100, { message: 'limit must be at most 100' })
  limit: number;
}

STEP 5 — Generate the Update DTO

Always use PartialType — never copy-paste validators from Create DTO:

import { PartialType } from '@nestjs/swagger';
import { Create<Domain>Dto } from './create-<tableName>.dto';

export class Update<Domain>Dto extends PartialType(Create<Domain>Dto) {}

STEP 6 — Flag any best-practice issues found

After generating, if the user's specification (or existing code they shared) contains any of these issues, flag them explicitly:

STEP 7 — Show draft and confirm

Present all 3 files with full paths and content. Ask:

"¿Todo correcto? ¿Quieres cambiar algo antes de crear los archivos?"

Wait for confirmation. Apply changes if requested.

STEP 8 — Write files

On confirmation, write the 3 files. Then show:

✅ Entity + DTOs created: <Domain>

  libs/common/src/entities/tenant/<domainPlural>/<tableName>.entity.ts
  libs/common/src/dto/tenant/<domainPlural>/create-<tableName>.dto.ts
  libs/common/src/dto/tenant/<domainPlural>/update-<tableName>.dto.ts

Next steps:
  - Register entity in the module: TypeOrmModule.forFeature([<Domain>Entity])
  - Add to database config if using a new schema
  - Generate migration: pnpm migration:generate:tenant Add<Domain>Table
  - Define proto type <Domain>Data in proto/tenant/<domainPlural>.proto

ABSOLUTE RULES

• BaseEntity provides id, createdAt, updatedAt, deletedAt — never redeclare these
• Every column MUST have explicit { name: 'snake_case' } — no exceptions
• toResponseDto() is required — serialization must be explicit
• Sensitive fields MUST have @ApiHideProperty() + @Exclude() + EncryptionTransformer
• Update DTO MUST use PartialType — never duplicate validators
• System-managed fields (agencyId, subAccountId, userId) never in Create DTO
• @IsOptional() must be first among validators
• Never use any type — use proper TypeScript interfaces or types
• Never use @IsNotEmpty() on an optional field