Value objects

Overview

A value object is a small immutable object defined entirely by its values rather than an identity: Money(100, USD), Email('[email protected]'), Coordinates(12.9, 77.6), DateRange. Two value objects with the same values are interchangeable and equal. They validate themselves on creation and contain behavior related to their values (Money.add, DateRange.overlaps).

Value objects cure 'primitive obsession', where doubles, strings, and ints represent domain concepts and the rules for them are scattered. Replacing primitives with value objects makes invalid values impossible, puts behavior next to data, and makes method signatures self-documenting.

When to use it

• Money, quantities, measurements, and units.
• Identifiers and formatted strings (email, phone, SKU).
• Ranges, coordinates, and addresses.

Where it shows up in interviews

Where it is used in real software

Key terms

Value equality

Equal if all values are equal.

Identity equality

Equal only if the same entity (entities).

Self-validation

Invalid values cannot be constructed.

Primitive obsession

Using primitives for domain concepts.

Minor units

Cents: integers avoid float rounding.

How it works, step by step

1. 1
   Find primitives with rules

   Amounts, emails, IDs, ranges.

2. 2
   Create an immutable type

   Record, data class, frozen object.

3. 3
   Validate and normalize in the constructor

   Lowercase email; non-negative cents.

4. 4
   Add domain behavior

   add, split, overlaps, format.

5. 5
   Implement value equality

   Records and data classes do this automatically.

Splitting a bill with Money

Split $100.00 among 3 people

Encapsulating money rules in a value object prevents rounding bugs everywhere it is used.

Implementation

1public record Money(long cents, String currency) implements Comparable<Money> {2    public Money {3        if (cents < 0) throw new IllegalArgumentException("Negative amount");4        if (currency == null || currency.length() != 3) throw new IllegalArgumentException("ISO currency required");5    }6 7    public static Money of(String amount, String currency) {8        return new Money(new BigDecimal(amount).movePointRight(2).longValueExact(), currency);9    }10 11    public Money plus(Money o) { requireSame(o); return new Money(cents + o.cents, currency); }12 13    public List<Money> split(int parts) {14        long base = cents / parts, remainder = cents % parts;15        List<Money> shares = new ArrayList<>();16        for (int i = 0; i < parts; i++) shares.add(new Money(base + (i < remainder ? 1 : 0), currency));17        return shares;18    }19 20    public int compareTo(Money o) { requireSame(o); return Long.compare(cents, o.cents); }21    private void requireSame(Money o) { if (!currency.equals(o.currency)) throw new IllegalArgumentException("Currency mismatch"); }22}23 24Money.of("100.00", "USD").split(3); // [33.34, 33.33, 33.33]25new Money(500, "USD").equals(new Money(500, "USD")); // true: value equality

Complexity and performance

Trade-offs

Variants and related techniques

Common mistakes

• Floating point for money.

  Fix: Use integer minor units or BigDecimal.

• Mutable value objects.

  Fix: Values must be immutable to be safely shared and compared.

• Giving value objects IDs.

  Fix: If identity matters, it is an entity.

Interview questions

Practice problems