enum-driven-state-authoring

---

name: enum-driven-state-authoring description: When writing new code, model state as sum types from the start. Apply when creating entities with distinct modes, phases, or lifecycle states.

Enum-Driven State: Authoring Guide

When writing new code, model state as sum types from the start. Don't create optional fields that depend on other fields.

---

Before You Write

Ask these questions about your data:

1. What are the mutually exclusive states? (e.g., Loading, Success, Error)
2. For each state, what data is required? (e.g., Success needs data, Error needs error)
3. Is there any data shared across ALL states? (e.g., id, timestamp → keep on wrapper)

---

Decision Flow

CopyDoes this entity have distinct modes/phases/states?
  │
  ├─ YES → Define a sum type with one variant per state
  │         Each variant holds only its required data
  │
  └─ NO → A simple struct/class is fine
           But watch for optional fields creeping in later

---

Patterns to Apply

Async/Remote Data

Copy// Start here, not with optional fields
type RemoteData<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };

Polymorphic Entities

Copy// When type determines structure, use enum not optionals
enum Shape {
    Circle { radius: f64 },
    Rectangle { width: f64, height: f64 },
}

Workflow/Lifecycle States

Copy@dataclass
class Draft:
    content: str

@dataclass
class Published:
    content: str
    published_at: datetime
    url: str

@dataclass
class Archived:
    content: str
    archived_at: datetime
    reason: str

Article = Draft | Published | Archived

Connection/Session State

Copysealed interface ConnectionState {
    data object Disconnected : ConnectionState
    data class Connecting(val attempt: Int) : ConnectionState
    data class Connected(val socket: Socket) : ConnectionState
    data class Error(val reason: Throwable) : ConnectionState
}

---

Anti-Patterns to Avoid

❌ Don't start with this:

Copyinterface User {
  id: string;
  status: 'guest' | 'registered' | 'premium';
  email?: string;           // only if registered/premium
  subscriptionId?: string;  // only if premium
  expiresAt?: Date;         // only if premium
}

✅ Start with this:

Copytype User =
  | { status: 'guest'; id: string }
  | { status: 'registered'; id: string; email: string }
  | { status: 'premium'; id: string; email: string; subscriptionId: string; expiresAt: Date };

---

Shared Data Pattern

When some fields exist on ALL variants, wrap them:

Copystruct Event {
    id: Uuid,
    timestamp: DateTime,
    payload: EventPayload,  // The sum type
}

enum EventPayload {
    UserCreated { name: String },
    OrderPlaced { items: Vec<Item> },
    PaymentFailed { reason: String },
}

---

Checklist When Authoring

• Identified all mutually exclusive states
• Each state has a dedicated variant/case
• Data lives INSIDE its variant, not as optional sibling
• Shared fields are on a wrapper struct
• No optional field depends on another field's value