Domain-Driven Design, Part 2: Entities, Value Objects and Aggregates

// WHAT: Issue is an Entity because it has a lifecycle
// WHY: We need to track "this specific issue" across all its state changes

class Issue {
  constructor(
    public readonly issueId: string,   // ← identity — never changes
    public title: string,              // ← can change (user edits it)
    public status: IssueStatus,        // ← can change (workflow progresses)
    public priority: Priority,         // ← can change (reprioritized)
  ) {}

  equals(other: Issue): boolean {
    return this.issueId === other.issueId
    // WHY: Two issues with the same title are NOT the same issue.
    // Identity is what matters, not attribute equality.
  }
}

// WHAT: IssueStatus is a Value Object — it wraps a string
//       and adds validation + domain behavior
// WHY: A raw string "status" can hold any value.
//      IssueStatus can only hold valid statuses.
//      It also knows the valid transitions — a string cannot.

class IssueStatus {
  private constructor(public readonly value: string) {}
  //      ↑ private constructor — the only way to create one
  //        is through the static factory methods below

  static readonly TODO        = new IssueStatus("todo")
  static readonly IN_PROGRESS = new IssueStatus("in_progress")
  static readonly IN_REVIEW   = new IssueStatus("in_review")
  static readonly DONE        = new IssueStatus("done")
  static readonly CANCELLED   = new IssueStatus("cancelled")

  static from(value: string): IssueStatus {
    const valid = ["todo", "in_progress", "in_review", "done", "cancelled"]
    if (!valid.includes(value)) {
      throw new DomainError(`Invalid status: ${value}`)
      // WHY: Invalid state is rejected at construction time,
      //      not discovered later when it causes a bug
    }
    return new IssueStatus(value)
  }

  canTransitionTo(next: IssueStatus): boolean {
    // WHY THIS LIVES HERE: The rule "todo can go to in_progress"
    // is a domain rule. It belongs on the domain object that
    // represents status — not in a Use Case or a handler.
    const transitions: Record<string, string[]> = {
      todo:        ["in_progress", "cancelled"],
      in_progress: ["in_review", "todo", "cancelled"],
      in_review:   ["done", "in_progress"],
      done:        [],
      cancelled:   []
    }
    return transitions[this.value].includes(next.value)
  }
}

// ❌ Without a value object — bug waiting to happen
issue.status = "compelted"   // typo — compiler says nothing, bug ships

// ✅ With a value object — caught immediately
issue.status = IssueStatus.from("compelted")  // throws DomainError at runtime
issue.status = IssueStatus.DONE               // only valid values exist

┌─────────────────────────────────────────────┐
│  Project Aggregate                          │
│                                             │
│  Project (Root) ← only entry point         │
│    ├── Member[]    ← child entity           │
│    ├── Milestone[] ← child entity           │
│    ├── Comment[]   ← child entity           │
│    └── Log[]       ← child entity           │
└─────────────────────────────────────────────┘