value-object-patterns

Primitive obsession occurs when domain concepts like email addresses or monetary amounts are represented as raw strings or numbers instead of dedicated types. Value Objects solve this by encapsulating primitives in immutable, self-validating types that enforce domain rules and improve type safety.

Create a Value Object with a private constructor, factory method for validated construction, and immutable fields. The factory method validates input before instantiation, ensuring only valid instances exist. Implement equality based on value semantics, not identity.

Yes. Composite Value Objects combine multiple related fields—street, city, postal code—into a single immutable type. Each field is validated individually and as a cohesive unit, encapsulating address domain logic and ensuring consistency across your model.

Use the included primitive obsession detection script on your domain code. It scans for string and number parameters representing domain concepts—email, amount, userId—highlighting candidates for Value Object refactoring.

Value Objects are immutable types defined by their values and lack identity; Entities have persistent identity and can change state. Use Value Objects for domain concepts like Money or DateRange; use Entities for domain objects requiring lifecycle tracking.

Implement serialization through factory methods or custom serializers that reconstruct Value Objects via validated construction. This preserves immutability and validation invariants during storage or API transmission.