nWave-ai/nWave / nWave/skills/nw-fp-domain-modeling
nw-fp-domain-modeling
VerifiedDomain modeling with algebraic data types, smart constructors, and type-level error handling
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.3 KB |
SKILL.md
View on GitHub---
name: nw-fp-domain-modeling
agent: nw-functional-software-crafter
description: Domain modeling with algebraic data types, smart constructors, and type-level error handling
user-invocable: false
disable-model-invocation: true
---
# FP Domain Modeling
Domain modeling with types. Make illegal states unrepresentable, workflows as pipelines, error handling at the type level.
Cross-references: [fp-principles](../nw-fp-principles/SKILL.md) | [code-craftsmanship: FP Hexagonal Architecture](../nw-code-craftsmanship/SKILL.md) | [fp-algebra-driven-design](../nw-fp-algebra-driven-design/SKILL.md)
---
## 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
| 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 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](../nw-code-craftsmanship/SKILL.md) 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |