dto-patterns

Skill: dto-patterns

Cursor Agent-Requested Rule — applied when AI determines relevance.

---

DTO Patterns

Patterns for transferring data between layers, services, and boundaries.

When to Use This Skill

• Designing API request/response bodies
• Mapping between domain entities and external representations
• Implementing validation at system boundaries
• Building transformation pipelines between services

Core Principles

1. DTO at boundaries only — Never expose domain entities directly
2. Validate on entry — DTOs are the first line of defense
3. Map explicitly — No magic auto-mapping; be intentional
4. Version your contracts — DTOs are your API contract

DTO Types

Type	Purpose	Example
Request DTO	Incoming data validation	CreateUserRequest
Response DTO	Outgoing data shaping	UserResponse
Command DTO	Intent + data	PlaceOrderCommand
Event DTO	Notification payload	OrderCreatedEvent
Projection DTO	Read-optimized query result	UserListProjection

Pattern: Request/Response Pair

// Request — what the client sends
interface CreateUserRequest {
  email: string;       // validated: email format
  name: string;        // validated: 2-100 chars
  role?: UserRole;     // optional, default: 'member'
}

// Response — what the client receives
interface UserResponse {
  id: string;          // server-generated
  email: string;       // same
  name: string;        // same
  role: UserRole;      // same
  createdAt: string;   // server-generated
  // NEVER include: passwordHash, internalId, metadata
}

Pattern: Mapping Strategies

Manual Mapping (Recommended for clarity)

function toResponse(user: UserEntity): UserResponse {
  return {
    id: user.id,
    email: user.email,
    name: user.displayName,
    role: user.role,
    createdAt: user.createdAt.toISOString(),
  };
}

MapStruct / AutoMapper (For large codebases)

@Mapper
public interface UserMapper {
  UserResponse toResponse(UserEntity entity);
  UserEntity toEntity(CreateUserRequest request);
}