FP Domain Modeling

Domain modeling with types. Make illegal states unrepresentable, workflows as pipelines, error handling at the type level.

Cross-references: fp-principles | fp-hexagonal-architecture | fp-algebra-driven-design

---

1. The Two Building Blocks

[STARTER]

All domain types compose from two operations:

• AND (Record Types): Value has ALL of these fields. Order requires CustomerInfo AND ShippingAddress AND OrderLines.
• OR (Choice Types): Value is ONE OF these alternatives. ProductCode is either WidgetCode OR GizmoCode.

Combined recursively, these express virtually any domain structure.

---

2. Domain Wrappers for Primitives

[STARTER]

Never use primitives directly in the domain model. Each domain concept gets its own wrapper type.

What: Wrap primitives so the compiler distinguishes CustomerId from OrderId. When: Every primitive with domain meaning. Why: Prevents accidental mixing (compiler rejects comparing CustomerId with OrderId). Each wrapper carries its own validation rules. The type name IS the documentation.

---

3. Validated Construction (Smart Constructors)

[STARTER]

Raw constructor is private. A create function validates input and returns a Result type, making validation failure explicit.

Pattern: UnitQuantity must be between 1 and 1000. Its create function rejects values outside that range. A companion value function provides read access to the inner primitive.

When: Every domain wrapper with validation rules. Why: Once constructed, a value is guaranteed valid. No defensive checks deeper in the code.

---

4. Making Illegal States Unrepresentable

[STARTER]

The central design guideline. Instead of flags and runtime checks, model the domain so invalid states cannot be constructed.

Replace Flags with Distinct Types

Instead of { EmailAddress; IsVerified: bool }, create separate VerifiedEmailAddress and UnverifiedEmailAddress types. Functions requiring verification take VerifiedEmailAddress, making misuse a compile error.

Replace Optional Fields with Choice Types

Instead of { Email: option; Address: option } (where both could be None), create: EmailOnly | AddressOnly | EmailAndAddress. The "at least one required" rule becomes structurally enforced.

NonEmptyList for "At Least One" Rules

Define a type guaranteeing at least one element. Order with OrderLines: NonEmptyList<OrderLine> cannot have zero lines.

---

5. Workflows as Functions

[STARTER]

Every business workflow is a single function: Command in, Events out.

PlaceOrderWorkflow : PlaceOrderCommand -> AsyncResult<PlaceOrderEvent list>

Pipeline Composition

Workflows decompose into steps, each transforming one document type into the next:

UnvalidatedOrder -> ValidatedOrder -> PricedOrder -> Events

Each step is stateless, pure, has single input/output type, and is independently testable. The workflow assembles by piping steps together.

Why: Pipeline makes the business process visible. Each step name is a domain concept.

---

6. Document Lifecycle as State Types

[INTERMEDIATE]

Rather than one Order type with flags, create separate types for each lifecycle stage:

• UnvalidatedOrder (raw input, all fields strings)
• ValidatedOrder (all fields checked)
• PricedOrder (prices calculated)

A top-level Order choice type unifies all states. New states (e.g., Refunded) added without breaking existing code.

When: Domain entities with distinct lifecycle stages where different data is available at each stage.

---

7. State Machines with Types

[INTERMEDIATE]

When an entity has distinct states with different data and different allowed operations, model each state as a separate type.

ShoppingCart = EmptyCart | ActiveCart of ActiveCartData | PaidCart of PaidCartData

Transition functions take the choice type, pattern-match on current state, return new state.

Benefits: All states explicit | each state has own data | invalid transitions prevented by types | pattern matching warnings reveal unhandled edge cases.

---

8. Error-Track Pipelines (Railway Pattern)

[INTERMEDIATE]

Each function returns a Result type. Pipeline short-circuits on first failure.

rawInput
  |> validateOrder           -- Result<ValidOrder, Error>
  |> bind calculateTotal     -- Result<PricedOrder, Error>
  |> bind checkInventory     -- Result<ConfirmedOrder, Error>
  |> bind chargePayment      -- Result<PaidOrder, Error>
  |> map generateReceipt     -- Result<Receipt, Error>

Key combinators:

• map: Transform success value (one-track into two-track)
• bind: Chain a function that itself returns Result
• mapError: Transform error value
• tee: Perform side effect without changing value (logging)

Error Classification

Category	Examples	Strategy
Domain Errors	Validation failure, out of stock	Model as types, return via Result
Panics	Out of memory, null reference	Throw exceptions, catch at top level
Infrastructure Errors	Network timeout, auth failure	Case-by-case

Unifying Error Types

Each step may have its own error type. Define a common error choice type and use mapError to lift step errors before composing.

Collecting All Errors (Applicative Validation)

[ADVANCED]

Standard bind short-circuits on first error. For validation where you want ALL errors, use Applicative style -- runs all validations and accumulates errors into a list. See fp-principles section 5.

When: Form validation | batch input checking | any place user needs all errors at once.

---

9. Modeling Dependencies

[INTERMEDIATE]

Each workflow step declares exactly the functions it needs as parameters:

CheckProductCodeExists : ProductCode -> bool
GetProductPrice        : ProductCode -> Price

Convention: Dependencies first in parameter list, primary input last. Enables partial application (functional DI).

Public vs. internal: Top-level workflow hides dependencies from callers. Internal steps make them explicit.

See fp-hexagonal-architecture section 5 for full DI decision tree.

---

10. Persistence Ignorance

[INTERMEDIATE]

Domain model has no awareness of databases. Two distinct type hierarchies:

• Domain types: Rich, nested, use choice types, validated wrappers. Not serialization-friendly.
• DTO types: Flat, primitives, nullable, arrays. Designed for serialization.

Conversion Pattern

• fromDomain: Domain -> DTO. Always succeeds.
• toDomain: DTO -> Result<Domain, Error>. May fail (validation happens here).

Serialization as Pipeline Steps

JSON -> deserialize -> DTO -> toDomain -> [WORKFLOW] -> fromDomain -> DTO -> serialize -> JSON

Domain workflow never sees JSON or DTOs directly.

---

11. Bounded Contexts

[ADVANCED]

Each context has its own dialect of domain language. Contexts communicate only through events and DTOs. Design for autonomy.

Trust boundaries: Input gate validates and converts incoming DTOs to domain types. Output gate converts domain types to DTOs, deliberately dropping private information.

Inter-context relationships: Shared Kernel (shared design) | Customer/Supplier (downstream defines contract) | Anti-Corruption Layer (translator preventing external model from corrupting internal domain).

---

Decision Tree: How to Model This Domain Concept?

Is it a simple value with validation rules?
  YES --> Domain Wrapper + Smart Constructor
  NO -->
    Does it represent one of several alternatives?
      YES --> Choice Type (sum type)
      NO -->
        Does it group several values together?
          YES --> Record Type (product type)
          NO -->
            Does it have distinct lifecycle stages?
              YES --> State Machine with Types (section 7)
              NO -->
                Is it an operation that transforms data through stages?
                  YES --> Workflow Pipeline (section 5)
                  NO --> Evaluate whether it needs modeling at all

---

12. Key Design Heuristics

1. Start from events and workflows, not data structures
2. Let the domain expert drive naming -- their vocabulary, not technical jargon
3. Use types to enforce business rules at compile time -- every rule in the type system needs no unit test
4. Document effects in signatures -- Result for errors | Async for I/O | Option for missing data
5. Separate domain types from serialization types -- domain is pure; serialization is infrastructure
6. Prefer explicit over implicit -- every input and dependency is a function parameter

Naming Patterns

• Types as nouns: Order | ProductCode | CustomerInfo
• Workflows as verbs: ValidateOrder | PriceOrder | PlaceOrder
• Events in past tense: OrderPlaced | OrderShipped
• Commands in imperative: PlaceOrder | ShipOrder | CancelOrder
• Lifecycle prefixes: UnvalidatedOrder | ValidatedOrder | PricedOrder