Skip to content

nWave-ai/nWave / nWave/skills/nw-fp-domain-modeling

nw-fp-domain-modeling

Verified

Domain modeling with algebraic data types, smart constructors, and type-level error handling

FP Domain Modeling

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

Cross-references: fp-principles | code-craftsmanship: 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]

Wrap a primitive when a demonstrated invalid state or a mixing risk exists that no native type and no existing invariant owner already excludes. Keep the native type when it suffices (nw-code-craftsmanship owns this sufficiency rule).

What: A wrapper lets the compiler distinguish CustomerId from OrderId. When: Two same-typed domain values can be confused at a real call site, or the value carries a validation rule with no existing owner. Never for template conformance alone. Why: Prevents accidental mixing (compiler rejects comparing CustomerId with OrderId). Each such 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.

Normalize admitted optional wire forms once into Absent | Present Work; let operations consume that alternative rather than re-inspect raw keys. Setting absent work constructs it; clearing absent work returns its declared result. Every admitted form has a defined Result; malformed present work is an error, not absence. Missing/null/empty are equivalent only where the contract says so. Basis: Sandy Maguire, Thinking with Types, The Algebra Behind Types → Sum, Product and Exponential Types / Canonical Representations; Certainty by Construction, An Exploration of Numbers → Constructing Evidence.

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.

For mixed validation dependencies, load nw-fp-principles §5 rather than require whole-document success too early. For a zero-construction-on-refusal contract, load nw-certainty-by-construction: independently validate customer/items, price validated items, then allocate/render the ready order. A later invalid operation cannot follow an already-issued order ID. These examples apply those owners' composition and semantic-closure laws, not a new mandatory pipeline framework.


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 a declared side effect without changing value; under a zero-activity-on-refusal contract, keep protected effects after readiness.

Error Classification

CategoryExamplesStrategy
Domain ErrorsValidation failure, out of stockModel as types, return via Result
PanicsOut of memory, null referenceThrow exceptions, catch at top level
Infrastructure ErrorsNetwork timeout, auth failureCase-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 its dependent chain. For independent all-errors checks, select accumulating Validation; load nw-fp-principles section 5 for mixed dependencies rather than infer failure behavior from Applicative alone.

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 code-craftsmanship: FP Dependency Injection for the 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 --> Does a native type plus an existing invariant owner already exclude the invalid value or mixing risk?
            YES --> Keep the native type; call the existing owner (section 2)
            NO  --> 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 checked types for their stated proposition -- a typed price expression excludes adding a Boolean, not a faulty JSON decoder or renderer. Keep boundary correspondence tests/refinement and valid/invalid public paths; load nw-algebraic-design-protocol §5 when claiming runtime preservation. Basis: Sandy Maguire, Thinking with Types, Constraints and GADTs → GADTs; Certainty by Construction, Appendix: Ring Solving → Semantics; Algebra-Driven Design, Designing Algebras → Tiles → Observations.
  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
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall