Value Objects - Learning Module

Loading content...

0/246

Immutability and Equality

The Twin Pillars of Value Objects

If there are two characteristics that define value objects above all others, they are immutability and value-based equality. These aren't merely implementation details—they are fundamental properties that derive directly from what value objects are.

Immutability means that once a value object is created, it never changes. A Money object representing $50.00 USD will always represent $50.00 USD. If you need $60.00, you create a new instance; you don't modify the existing one.

Value-based equality means that two value objects are considered equal if and only if all their attributes are equal. A $50.00 USD is equal to any other $50.00 USD, regardless of where or when those objects were created.

These properties aren't arbitrary design choices—they're logical necessities that flow from the very nature of value objects. Understanding why these properties matter is essential for implementing value objects correctly and avoiding subtle, hard-to-debug errors.

What You Will Learn

By the end of this page, you will understand why immutability is non-negotiable for value objects, how to implement proper value-based equality (including hashCode), and the dangerous bugs that emerge when these principles are violated. You'll also learn patterns for 'modification' operations on immutable objects.

Why Immutability is Non-Negotiable

Immutability isn't just a "nice to have" for value objects—it's a fundamental requirement that derives from their very definition. Let's examine why.

Conceptual Argument:

If a value object has no identity, what would it mean for it to change? Without identity, there's no sense in which a changed object is the "same object" that existed before the change. Entities can change because their identity persists across state changes. Value objects have no such persistent identity.

Consider the number 5. Can 5 change to become 6? No—5 is always 5. If you want 6, you have a different number, not a changed version of 5. Value objects work the same way.

The Number Analogy

Think of value objects like numbers. The number 42 doesn't change. If you want 43, you get a different number. Similarly, a Money object of $100 doesn't change. If you want $101, you create a new Money object. Numbers are the original value objects.

Practical Arguments for Immutability:

Benefits of Immutability

•Thread Safety for Free — Immutable objects can be shared across threads without synchronization. Multiple threads can read the same value object simultaneously without risk of one thread seeing an inconsistent intermediate state.
•No Aliasing Bugs — When two variables reference the same value object, changes through one reference can't surprise code holding the other reference. Immutability eliminates this entire class of bugs.
•Safe Caching and Hash Keys — Immutable objects can be safely used as hash map keys and cached indefinitely. Their hash codes never change (because their values never change).
•Predictable Behavior — Methods that receive value objects know those values won't change out from under them during execution. This simplifies reasoning about code.
•Natural Transactionality — Operations on immutable objects are inherently atomic—you either create a new object with new values or you don't. There's no partial update state.

The Danger of Mutable Value Objects

What happens when we violate immutability? Let's examine concrete examples of bugs that emerge from mutable value objects.

The Aliasing Bug

One of the most insidious bugs occurs when multiple references share a mutable value object:

aliasing-bug.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// ❌ BAD: Mutable value object creates aliasing bugs
class MutableMoney {
    private amount: number;
    private currency: Currency;
 
    constructor(amount: number, currency: Currency) {
        this.amount = amount;
        this.currency = currency;
    }
 
    // DANGER: Mutation method!
    addAmount(addition: number): void {
        this.amount += addition;
    }
 
    getAmount(): number {
        return this.amount;
    }
}
 
// The bug in action
const originalPrice = new MutableMoney(100, Currency.USD);
const order = new Order();
order.setPrice(originalPrice);
 
// Later, somewhere else in the code...
// Developer thinks they're creating a "discounted price"
const discountedPrice = originalPrice;
discountedPrice.addAmount(-20); // Oops!
 
// Surprise! The order's price also changed!
console.log(order.getPrice().getAmount()); // 80, not 100!
 
// The order was never explicitly modified, yet its price changed.
// This is an aliasing bug caused by mutable value objects.

Aliasing Bugs Are Hard to Find

Aliasing bugs are among the hardest to debug because the mutation happens far from where the effect is observed. You'll stare at the Order class for hours wondering how the price changed, never thinking to look at code that modified a 'discounted price' variable.

The HashMap Key Disaster

Mutable objects used as hash map keys cause catastrophic bugs:

hashmap-disaster.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// ❌ BAD: Mutable value object as Map key
class MutableCoordinates {
    private x: number;
    private y: number;
 
    constructor(x: number, y: number) {
        this.x = x;
        this.y = y;
    }
 
    setX(x: number): void {
        this.x = x;
    }
 
    // Hash code based on mutable state
    hashCode(): number {
        return this.x * 31 + this.y;
    }
 
    equals(other: MutableCoordinates): boolean {
        return this.x === other.x && this.y === other.y;
    }
}
 
// The disaster
const location = new MutableCoordinates(10, 20);
const locationMap = new Map<MutableCoordinates, string>();
 
locationMap.set(location, "Important data");
console.log(locationMap.get(location)); // "Important data" ✓
 
// Now mutate the key
location.setX(999);
 
// Data is LOST! The hash code changed, so lookup fails
console.log(locationMap.get(location)); // undefined! 😱
 
// Even worse: the data is still IN the map, but unreachable!
// This is a memory leak AND a logic bug.

Thread Safety Violation

Mutable value objects shared across threads create race conditions:

thread-safety-violation.ts
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// ❌ BAD: Mutable value object shared across threads
public class MutableDateRange {
    private LocalDate start;
    private LocalDate end;
 
    public MutableDateRange(LocalDate start, LocalDate end) {
        this.start = start;
        this.end = end;
    }
 
    public void setStart(LocalDate start) { this.start = start; }
    public void setEnd(LocalDate end) { this.end = end; }
 
    public boolean contains(LocalDate date) {
        // Race condition: another thread might change start/end
        // between these two comparisons!
        return !date.isBefore(start) && !date.isAfter(end);
    }
}
 
// Shared across threads
MutableDateRange activeWindow = new MutableDateRange(
    LocalDate.of(2024, 1, 1),
    LocalDate.of(2024, 12, 31)
);
 
// Thread 1: updating the window
executor.submit(() -> {
    activeWindow.setStart(LocalDate.of(2025, 1, 1));
    activeWindow.setEnd(LocalDate.of(2025, 12, 31));
});
 
// Thread 2: checking if date is in window
executor.submit(() -> {
    // May see start=2025-01-01 but end=2024-12-31 (inconsistent state!)
    // Or may see start=2024-01-01 and end=2025-12-31 (invalid range!)
    boolean isValid = activeWindow.contains(LocalDate.of(2024, 6, 15));
    // Result is unpredictable!
});

Implementing Immutability

Creating truly immutable value objects requires attention to several details. Here are the essential techniques:

Immutability Checklist

•Declare all fields as readonly/final — Prevents reassignment after construction.
•No setter methods — Eliminate any mutation methods entirely.
•Defensive copies on input — If constructor receives mutable objects, copy them.
•Defensive copies on output — If getters return mutable objects, return copies.
•Mark class as final/sealed — Prevent subclasses from adding mutability.
•Return new instances from operations — Methods that 'modify' return new objects.

immutable-implementation.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// ✅ CORRECT: Truly immutable value object
class DateRange {
    // 1. Readonly fields
    private readonly start: Date;
    private readonly end: Date;
 
    private constructor(start: Date, end: Date) {
        // Validation
        if (start > end) {
            throw new Error("Start must be before or equal to end");
        }
        
        // 2. Defensive copies on input
        // Date is mutable, so we copy it
        this.start = new Date(start.getTime());
        this.end = new Date(end.getTime());
    }
 
    static between(start: Date, end: Date): DateRange {
        return new DateRange(start, end);
    }
 
    // 3. NO setter methods - not even private ones
 
    // 4. Defensive copies on output
    getStart(): Date {
        return new Date(this.start.getTime());
    }
 
    getEnd(): Date {
        return new Date(this.end.getTime());
    }
 
    // 5. Operations return NEW instances
    extend(days: number): DateRange {
        const newEnd = new Date(this.end);
        newEnd.setDate(newEnd.getDate() + days);
        return new DateRange(this.start, newEnd);
    }
 
    shift(days: number): DateRange {
        const newStart = new Date(this.start);
        const newEnd = new Date(this.end);
        newStart.setDate(newStart.getDate() + days);
        newEnd.setDate(newEnd.getDate() + days);
        return new DateRange(newStart, newEnd);
    }
 
    // Query methods are always safe - they don't modify anything
    contains(date: Date): boolean {
        return date >= this.start && date <= this.end;
    }
 
    getDurationInDays(): number {
        const diffMs = this.end.getTime() - this.start.getTime();
        return Math.floor(diffMs / (1000 * 60 * 60 * 24)) + 1;
    }
}
 
// Usage
const q1 = DateRange.between(
    new Date('2024-01-01'),
    new Date('2024-03-31')
);
 
// "Modify" returns a new instance; original is unchanged
const q2 = q1.shift(91); // Q2
 
console.log(q1.getStart()); // Still Jan 1, 2024
console.log(q2.getStart()); // Apr 1, 2024

Watch Out for Mutable Field Types

The most common immutability mistake is storing references to mutable objects (Date, arrays, collections) without copying them. Always make defensive copies of mutable inputs and outputs. Better yet, use immutable types (LocalDate, immutable collections) to eliminate the need for copying.

Value-Based Equality

Value objects must implement equality based on their attribute values, not object identity. Two value objects are equal if and only if all their component values are equal.

This is fundamentally different from entities, which compare by identity (ID), and from default object equality, which compares by reference.

Equality Comparison Strategies
Type	Equality Based On	Example
Reference Equality	Same object in memory	`a === b` (same pointer)
Identity Equality	Same ID, ignoring other fields	`a.id === b.id`
Value Equality	All attributes equal	`a.amount === b.amount && a.currency === b.currency`

The Equality Contract

When implementing value equality, you must satisfy the equality contract. This contract ensures that equality behaves consistently and predictably:

The Equality Contract

•Reflexive — An object is always equal to itself: x.equals(x) must be true.
•Symmetric — If x.equals(y), then y.equals(x). Equality is bidirectional.
•Transitive — If x.equals(y) and y.equals(z), then x.equals(z).
•Consistent — Multiple calls to x.equals(y) return the same result (assuming no mutations, which we've prevented via immutability).
•Null handling — x.equals(null) must return false, never throw.

value-equality-contract.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
class Money {
    private readonly amount: number;
    private readonly currency: Currency;
 
    constructor(amount: number, currency: Currency) {
        this.amount = amount;
        this.currency = currency;
    }
 
    equals(other: unknown): boolean {
        // Handle null/undefined
        if (other === null || other === undefined) {
            return false;
        }
 
        // Handle type mismatch
        if (!(other instanceof Money)) {
            return false;
        }
 
        // Compare all value components
        return this.amount === other.amount &&
               this.currency === other.currency;
    }
 
    // Hash code must be consistent with equals
    hashCode(): number {
        let hash = 17;
        // Use same fields as equals()
        hash = hash * 31 + Math.floor(this.amount * 100);
        hash = hash * 31 + this.currency.hashCode();
        return hash;
    }
}
 
// Verifying the equality contract
const m1 = new Money(100, Currency.USD);
const m2 = new Money(100, Currency.USD);
const m3 = new Money(100, Currency.USD);
const m4 = new Money(50, Currency.USD);
 
// Reflexive
console.log(m1.equals(m1)); // true
 
// Symmetric
console.log(m1.equals(m2)); // true
console.log(m2.equals(m1)); // true
 
// Transitive
console.log(m1.equals(m2)); // true
console.log(m2.equals(m3)); // true
console.log(m1.equals(m3)); // true
 
// Consistent
console.log(m1.equals(m2)); // true
console.log(m1.equals(m2)); // true (same result)
 
// Null handling
console.log(m1.equals(null)); // false (no exception)
 
// Unequal values
console.log(m1.equals(m4)); // false

The hashCode Contract

Whenever you implement equals(), you must also implement hashCode() correctly. These two methods are bound by a strict contract, and violating it causes catastrophic bugs in hash-based collections (HashMap, HashSet, Dictionary, etc.).

The hashCode Contract

•Consistency — If an object doesn't change, its hash code must remain constant. (Immutability guarantees this!)
•equals → hashCode — If a.equals(b) is true, then a.hashCode() MUST equal b.hashCode().
•No reverse guarantee — If hash codes are equal, the objects might or might not be equal. (Hash collisions are allowed.)

The Critical Rule

If two objects are equal according to equals(), they MUST have the same hash code. Violating this rule breaks HashMap, HashSet, and any hash-based collection. Objects will be 'lost' in these collections just like we saw with mutable keys.

Implementing hashCode Correctly

Use the same fields in hashCode() that you use in equals():

hashcode-implementation.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class Address {
    private readonly street: string;
    private readonly city: string;
    private readonly postalCode: string;
    private readonly country: string;
 
    // ... constructor ...
 
    equals(other: Address): boolean {
        if (!(other instanceof Address)) return false;
        
        return this.street === other.street &&
               this.city === other.city &&
               this.postalCode === other.postalCode &&
               this.country === other.country;
    }
 
    // hashCode uses SAME fields as equals
    hashCode(): number {
        let hash = 17;
        hash = hash * 31 + this.stringHashCode(this.street);
        hash = hash * 31 + this.stringHashCode(this.city);
        hash = hash * 31 + this.stringHashCode(this.postalCode);
        hash = hash * 31 + this.stringHashCode(this.country);
        return hash;
    }
 
    private stringHashCode(str: string): number {
        let hash = 0;
        for (let i = 0; i < str.length; i++) {
            const char = str.charCodeAt(i);
            hash = ((hash << 5) - hash) + char;
            hash = hash & hash; // Convert to 32-bit integer
        }
        return hash;
    }
}
 
// ❌ BAD: Using subset of fields in hashCode
class BadAddress {
    equals(other: BadAddress): boolean {
        return this.street === other.street &&
               this.city === other.city &&
               this.postalCode === other.postalCode &&
               this.country === other.country;
    }
 
    hashCode(): number {
        // WRONG: Only uses street, not all fields!
        // Two addresses with same street but different cities
        // will have same hashCode but equals() returns false
        // This VIOLATES the contract (but in permissible direction)
        // However, it causes terrible hash table performance
        return this.stringHashCode(this.street);
    }
}
 
// ❌ WORSE: Using different fields in hashCode
class WrongAddress {
    private id: number; // NOT used in equals!
 
    equals(other: WrongAddress): boolean {
        // equals uses value fields
        return this.street === other.street &&
               this.city === other.city;
    }
 
    hashCode(): number {
        // WRONG: Uses id which is NOT part of equals!
        // Two equal addresses may have DIFFERENT hash codes
        // This VIOLATES the contract catastrophically!
        return this.id;
    }
}

Modification Through Copy

How do we "modify" immutable objects? We don't—we create new objects with the desired changes. This pattern is variously called copy-on-write, with methods, or the builder pattern for complex objects.

The 'With' Pattern

The most common approach uses methods prefixed with with that return new instances:

with-pattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class Person {
    private readonly firstName: string;
    private readonly lastName: string;
    private readonly email: Email;
 
    private constructor(
        firstName: string,
        lastName: string,
        email: Email
    ) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
    }
 
    static create(firstName: string, lastName: string, email: Email): Person {
        return new Person(firstName, lastName, email);
    }
 
    // "With" methods create new instances with one field changed
    withFirstName(firstName: string): Person {
        return new Person(firstName, this.lastName, this.email);
    }
 
    withLastName(lastName: string): Person {
        return new Person(this.firstName, lastName, this.email);
    }
 
    withEmail(email: Email): Person {
        return new Person(this.firstName, this.lastName, email);
    }
 
    // Multiple changes via chaining
    withName(firstName: string, lastName: string): Person {
        return new Person(firstName, lastName, this.email);
    }
}
 
// Usage - immutable updates through method chaining
const original = Person.create("Alice", "Smith", Email.of("alice@old.com"));
 
// Create a modified copy - original is unchanged
const updated = original
    .withLastName("Johnson")
    .withEmail(Email.of("alice@new.com"));
 
console.log(original.getLastName()); // "Smith" (unchanged)
console.log(updated.getLastName());  // "Johnson" (new instance)

Builder Pattern for Complex Value Objects

When value objects have many fields, consider a builder:

builder-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class Address {
    readonly street: string;
    readonly city: string;
    readonly state: string;
    readonly postalCode: string;
    readonly country: string;
    readonly apartment?: string;
    readonly buildingName?: string;
 
    private constructor(builder: AddressBuilder) {
        this.street = builder.street;
        this.city = builder.city;
        this.state = builder.state;
        this.postalCode = builder.postalCode;
        this.country = builder.country;
        this.apartment = builder.apartment;
        this.buildingName = builder.buildingName;
    }
 
    static builder(): AddressBuilder {
        return new AddressBuilder();
    }
 
    // Create a builder pre-populated with this address's values
    toBuilder(): AddressBuilder {
        return new AddressBuilder()
            .setStreet(this.street)
            .setCity(this.city)
            .setState(this.state)
            .setPostalCode(this.postalCode)
            .setCountry(this.country)
            .setApartment(this.apartment)
            .setBuildingName(this.buildingName);
    }
}
 
class AddressBuilder {
    street: string = '';
    city: string = '';
    state: string = '';
    postalCode: string = '';
    country: string = '';
    apartment?: string;
    buildingName?: string;
 
    setStreet(street: string): this { this.street = street; return this; }
    setCity(city: string): this { this.city = city; return this; }
    setState(state: string): this { this.state = state; return this; }
    setPostalCode(postalCode: string): this { this.postalCode = postalCode; return this; }
    setCountry(country: string): this { this.country = country; return this; }
    setApartment(apartment?: string): this { this.apartment = apartment; return this; }
    setBuildingName(buildingName?: string): this { this.buildingName = buildingName; return this; }
 
    build(): Address {
        // Validation
        if (!this.street || !this.city || !this.postalCode || !this.country) {
            throw new Error("Required fields missing");
        }
        return new Address(this);
    }
}
 
// Usage
const home = Address.builder()
    .setStreet("123 Main St")
    .setCity("New York")
    .setState("NY")
    .setPostalCode("10001")
    .setCountry("USA")
    .setApartment("4B")
    .build();
 
// Create modified copy using builder
const newHome = home.toBuilder()
    .setStreet("456 Oak Ave")
    .setApartment("7C")
    .build();

Common Equality Pitfalls

Even experienced developers make mistakes when implementing equality. Here are the most common pitfalls:

Pitfall 1: Forgetting Null and Type Checks

null-check-pitfall.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ❌ BAD: Missing null/type checks
class BadMoney {
    equals(other: BadMoney): boolean {
        // Crashes if other is null or wrong type!
        return this.amount === other.amount;
    }
}
 
// ✅ GOOD: Proper null and type handling
class GoodMoney {
    equals(other: unknown): boolean {
        if (other === null || other === undefined) return false;
        if (!(other instanceof GoodMoney)) return false;
        return this.amount === other.amount && 
               this.currency === other.currency;
    }
}

Pitfall 2: Floating Point Comparison

floating-point-pitfall.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// ❌ BAD: Direct floating point comparison
class BadMeasurement {
    constructor(private readonly value: number) {}
 
    equals(other: BadMeasurement): boolean {
        // Floating point imprecision causes false negatives!
        return this.value === other.value;
    }
}
 
const m1 = new BadMeasurement(0.1 + 0.2);
const m2 = new BadMeasurement(0.3);
console.log(m1.equals(m2)); // false! (0.30000000000000004 !== 0.3)
 
// ✅ GOOD: Use epsilon for floating point, or avoid floats for money
class GoodMeasurement {
    private static readonly EPSILON = 0.0000001;
 
    constructor(private readonly value: number) {}
 
    equals(other: GoodMeasurement): boolean {
        return Math.abs(this.value - other.value) < GoodMeasurement.EPSILON;
    }
}
 
// ✅ BETTER: Use integers for money (cents, not dollars)
class BetterMoney {
    constructor(private readonly cents: number) {} // Integer!
 
    equals(other: BetterMoney): boolean {
        return this.cents === other.cents; // Integer comparison is safe
    }
}

Pitfall 3: Inheritance and Equality

inheritance-pitfall.ts
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// ❌ BAD: instanceof allows subclass comparison
class Point {
    protected final int x, y;
 
    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof Point other)) return false;
        return x == other.x && y == other.y;
    }
}
 
class ColoredPoint extends Point {
    private final Color color;
 
    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof ColoredPoint other)) return false;
        return super.equals(obj) && color.equals(other.color);
    }
}
 
// The problem: symmetry is violated!
Point p = new Point(1, 2);
ColoredPoint cp = new ColoredPoint(1, 2, Color.RED);
 
p.equals(cp);  // true  (Point instanceof check passes)
cp.equals(p);  // false (ColoredPoint instanceof fails)
 
// This violates the symmetry requirement!
 
// ✅ SOLUTION: Use getClass() instead of instanceof
class CorrectPoint {
    @Override
    public boolean equals(Object obj) {
        if (obj == null || getClass() != obj.getClass()) return false;
        CorrectPoint other = (CorrectPoint) obj;
        return x == other.x && y == other.y;
    }
}
 
// ✅ BETTER: Make value objects final (prevent subclassing)
public final class Point { ... }

Summary: Immutability and Equality

We've explored the twin pillars that define value objects. Let's consolidate the key insights:

Key Takeaways

•Immutability is non-negotiable — Mutable value objects cause aliasing bugs, break hash collections, and create thread-safety issues.
•Use defensive copying — When receiving or returning mutable types, copy them to preserve immutability.
•Value equality compares all attributes — Two value objects are equal if and only if all their component values are equal.
•equals and hashCode are coupled — Always implement both, using the same fields in each.
•Modification creates new instances — Use 'with' methods or builders to create modified copies.
•Make value object classes final — Prevent subclassing to avoid equality contract violations.

What's next:

With a solid understanding of immutability and equality, we're ready to explore value object design in depth. The next page covers how to design value objects that are expressive, composable, and truly useful for modeling domain concepts.

Page Complete

You now understand why immutability and value-based equality are essential characteristics of value objects, how to implement them correctly, and the dangerous bugs that emerge when they're violated. Next, we'll learn how to design value objects that elegantly capture domain concepts.

Immutability and Equality

The Twin Pillars of Value Objects

What You Will Learn

Why Immutability is Non-Negotiable

Immutability isn't just a "nice to have" for value objects—it's a fundamental requirement that derives from their very definition. Let's examine why.

Conceptual Argument:

Consider the number 5. Can 5 change to become 6? No—5 is always 5. If you want 6, you have a different number, not a changed version of 5. Value objects work the same way.

The Number Analogy

Practical Arguments for Immutability:

Benefits of Immutability

•Thread Safety for Free — Immutable objects can be shared across threads without synchronization. Multiple threads can read the same value object simultaneously without risk of one thread seeing an inconsistent intermediate state.
•No Aliasing Bugs — When two variables reference the same value object, changes through one reference can't surprise code holding the other reference. Immutability eliminates this entire class of bugs.
•Safe Caching and Hash Keys — Immutable objects can be safely used as hash map keys and cached indefinitely. Their hash codes never change (because their values never change).
•Predictable Behavior — Methods that receive value objects know those values won't change out from under them during execution. This simplifies reasoning about code.
•Natural Transactionality — Operations on immutable objects are inherently atomic—you either create a new object with new values or you don't. There's no partial update state.

The Danger of Mutable Value Objects

What happens when we violate immutability? Let's examine concrete examples of bugs that emerge from mutable value objects.

The Aliasing Bug

One of the most insidious bugs occurs when multiple references share a mutable value object:

aliasing-bug.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// ❌ BAD: Mutable value object creates aliasing bugs
class MutableMoney {
    private amount: number;
    private currency: Currency;
 
    constructor(amount: number, currency: Currency) {
        this.amount = amount;
        this.currency = currency;
    }
 
    // DANGER: Mutation method!
    addAmount(addition: number): void {
        this.amount += addition;
    }
 
    getAmount(): number {
        return this.amount;
    }
}
 
// The bug in action
const originalPrice = new MutableMoney(100, Currency.USD);
const order = new Order();
order.setPrice(originalPrice);
 
// Later, somewhere else in the code...
// Developer thinks they're creating a "discounted price"
const discountedPrice = originalPrice;
discountedPrice.addAmount(-20); // Oops!
 
// Surprise! The order's price also changed!
console.log(order.getPrice().getAmount()); // 80, not 100!
 
// The order was never explicitly modified, yet its price changed.
// This is an aliasing bug caused by mutable value objects.

Aliasing Bugs Are Hard to Find

The HashMap Key Disaster

Mutable objects used as hash map keys cause catastrophic bugs:

hashmap-disaster.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// ❌ BAD: Mutable value object as Map key
class MutableCoordinates {
    private x: number;
    private y: number;
 
    constructor(x: number, y: number) {
        this.x = x;
        this.y = y;
    }
 
    setX(x: number): void {
        this.x = x;
    }
 
    // Hash code based on mutable state
    hashCode(): number {
        return this.x * 31 + this.y;
    }
 
    equals(other: MutableCoordinates): boolean {
        return this.x === other.x && this.y === other.y;
    }
}
 
// The disaster
const location = new MutableCoordinates(10, 20);
const locationMap = new Map<MutableCoordinates, string>();
 
locationMap.set(location, "Important data");
console.log(locationMap.get(location)); // "Important data" ✓
 
// Now mutate the key
location.setX(999);
 
// Data is LOST! The hash code changed, so lookup fails
console.log(locationMap.get(location)); // undefined! 😱
 
// Even worse: the data is still IN the map, but unreachable!
// This is a memory leak AND a logic bug.

Thread Safety Violation

Mutable value objects shared across threads create race conditions:

thread-safety-violation.ts
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// ❌ BAD: Mutable value object shared across threads
public class MutableDateRange {
    private LocalDate start;
    private LocalDate end;
 
    public MutableDateRange(LocalDate start, LocalDate end) {
        this.start = start;
        this.end = end;
    }
 
    public void setStart(LocalDate start) { this.start = start; }
    public void setEnd(LocalDate end) { this.end = end; }
 
    public boolean contains(LocalDate date) {
        // Race condition: another thread might change start/end
        // between these two comparisons!
        return !date.isBefore(start) && !date.isAfter(end);
    }
}
 
// Shared across threads
MutableDateRange activeWindow = new MutableDateRange(
    LocalDate.of(2024, 1, 1),
    LocalDate.of(2024, 12, 31)
);
 
// Thread 1: updating the window
executor.submit(() -> {
    activeWindow.setStart(LocalDate.of(2025, 1, 1));
    activeWindow.setEnd(LocalDate.of(2025, 12, 31));
});
 
// Thread 2: checking if date is in window
executor.submit(() -> {
    // May see start=2025-01-01 but end=2024-12-31 (inconsistent state!)
    // Or may see start=2024-01-01 and end=2025-12-31 (invalid range!)
    boolean isValid = activeWindow.contains(LocalDate.of(2024, 6, 15));
    // Result is unpredictable!
});

Implementing Immutability

Creating truly immutable value objects requires attention to several details. Here are the essential techniques:

Immutability Checklist

•Declare all fields as readonly/final — Prevents reassignment after construction.
•No setter methods — Eliminate any mutation methods entirely.
•Defensive copies on input — If constructor receives mutable objects, copy them.
•Defensive copies on output — If getters return mutable objects, return copies.
•Mark class as final/sealed — Prevent subclasses from adding mutability.
•Return new instances from operations — Methods that 'modify' return new objects.

immutable-implementation.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// ✅ CORRECT: Truly immutable value object
class DateRange {
    // 1. Readonly fields
    private readonly start: Date;
    private readonly end: Date;
 
    private constructor(start: Date, end: Date) {
        // Validation
        if (start > end) {
            throw new Error("Start must be before or equal to end");
        }
        
        // 2. Defensive copies on input
        // Date is mutable, so we copy it
        this.start = new Date(start.getTime());
        this.end = new Date(end.getTime());
    }
 
    static between(start: Date, end: Date): DateRange {
        return new DateRange(start, end);
    }
 
    // 3. NO setter methods - not even private ones
 
    // 4. Defensive copies on output
    getStart(): Date {
        return new Date(this.start.getTime());
    }
 
    getEnd(): Date {
        return new Date(this.end.getTime());
    }
 
    // 5. Operations return NEW instances
    extend(days: number): DateRange {
        const newEnd = new Date(this.end);
        newEnd.setDate(newEnd.getDate() + days);
        return new DateRange(this.start, newEnd);
    }
 
    shift(days: number): DateRange {
        const newStart = new Date(this.start);
        const newEnd = new Date(this.end);
        newStart.setDate(newStart.getDate() + days);
        newEnd.setDate(newEnd.getDate() + days);
        return new DateRange(newStart, newEnd);
    }
 
    // Query methods are always safe - they don't modify anything
    contains(date: Date): boolean {
        return date >= this.start && date <= this.end;
    }
 
    getDurationInDays(): number {
        const diffMs = this.end.getTime() - this.start.getTime();
        return Math.floor(diffMs / (1000 * 60 * 60 * 24)) + 1;
    }
}
 
// Usage
const q1 = DateRange.between(
    new Date('2024-01-01'),
    new Date('2024-03-31')
);
 
// "Modify" returns a new instance; original is unchanged
const q2 = q1.shift(91); // Q2
 
console.log(q1.getStart()); // Still Jan 1, 2024
console.log(q2.getStart()); // Apr 1, 2024

Watch Out for Mutable Field Types

Value-Based Equality

Value objects must implement equality based on their attribute values, not object identity. Two value objects are equal if and only if all their component values are equal.

This is fundamentally different from entities, which compare by identity (ID), and from default object equality, which compares by reference.

Equality Comparison Strategies
Type	Equality Based On	Example
Reference Equality	Same object in memory	`a === b` (same pointer)
Identity Equality	Same ID, ignoring other fields	`a.id === b.id`
Value Equality	All attributes equal	`a.amount === b.amount && a.currency === b.currency`

The Equality Contract

When implementing value equality, you must satisfy the equality contract. This contract ensures that equality behaves consistently and predictably:

The Equality Contract

•Reflexive — An object is always equal to itself: x.equals(x) must be true.
•Symmetric — If x.equals(y), then y.equals(x). Equality is bidirectional.
•Transitive — If x.equals(y) and y.equals(z), then x.equals(z).
•Consistent — Multiple calls to x.equals(y) return the same result (assuming no mutations, which we've prevented via immutability).
•Null handling — x.equals(null) must return false, never throw.

value-equality-contract.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
class Money {
    private readonly amount: number;
    private readonly currency: Currency;
 
    constructor(amount: number, currency: Currency) {
        this.amount = amount;
        this.currency = currency;
    }
 
    equals(other: unknown): boolean {
        // Handle null/undefined
        if (other === null || other === undefined) {
            return false;
        }
 
        // Handle type mismatch
        if (!(other instanceof Money)) {
            return false;
        }
 
        // Compare all value components
        return this.amount === other.amount &&
               this.currency === other.currency;
    }
 
    // Hash code must be consistent with equals
    hashCode(): number {
        let hash = 17;
        // Use same fields as equals()
        hash = hash * 31 + Math.floor(this.amount * 100);
        hash = hash * 31 + this.currency.hashCode();
        return hash;
    }
}
 
// Verifying the equality contract
const m1 = new Money(100, Currency.USD);
const m2 = new Money(100, Currency.USD);
const m3 = new Money(100, Currency.USD);
const m4 = new Money(50, Currency.USD);
 
// Reflexive
console.log(m1.equals(m1)); // true
 
// Symmetric
console.log(m1.equals(m2)); // true
console.log(m2.equals(m1)); // true
 
// Transitive
console.log(m1.equals(m2)); // true
console.log(m2.equals(m3)); // true
console.log(m1.equals(m3)); // true
 
// Consistent
console.log(m1.equals(m2)); // true
console.log(m1.equals(m2)); // true (same result)
 
// Null handling
console.log(m1.equals(null)); // false (no exception)
 
// Unequal values
console.log(m1.equals(m4)); // false

The hashCode Contract

•Consistency — If an object doesn't change, its hash code must remain constant. (Immutability guarantees this!)
•equals → hashCode — If a.equals(b) is true, then a.hashCode() MUST equal b.hashCode().
•No reverse guarantee — If hash codes are equal, the objects might or might not be equal. (Hash collisions are allowed.)

The Critical Rule

Implementing hashCode Correctly

Use the same fields in hashCode() that you use in equals():

hashcode-implementation.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class Address {
    private readonly street: string;
    private readonly city: string;
    private readonly postalCode: string;
    private readonly country: string;
 
    // ... constructor ...
 
    equals(other: Address): boolean {
        if (!(other instanceof Address)) return false;
        
        return this.street === other.street &&
               this.city === other.city &&
               this.postalCode === other.postalCode &&
               this.country === other.country;
    }
 
    // hashCode uses SAME fields as equals
    hashCode(): number {
        let hash = 17;
        hash = hash * 31 + this.stringHashCode(this.street);
        hash = hash * 31 + this.stringHashCode(this.city);
        hash = hash * 31 + this.stringHashCode(this.postalCode);
        hash = hash * 31 + this.stringHashCode(this.country);
        return hash;
    }
 
    private stringHashCode(str: string): number {
        let hash = 0;
        for (let i = 0; i < str.length; i++) {
            const char = str.charCodeAt(i);
            hash = ((hash << 5) - hash) + char;
            hash = hash & hash; // Convert to 32-bit integer
        }
        return hash;
    }
}
 
// ❌ BAD: Using subset of fields in hashCode
class BadAddress {
    equals(other: BadAddress): boolean {
        return this.street === other.street &&
               this.city === other.city &&
               this.postalCode === other.postalCode &&
               this.country === other.country;
    }
 
    hashCode(): number {
        // WRONG: Only uses street, not all fields!
        // Two addresses with same street but different cities
        // will have same hashCode but equals() returns false
        // This VIOLATES the contract (but in permissible direction)
        // However, it causes terrible hash table performance
        return this.stringHashCode(this.street);
    }
}
 
// ❌ WORSE: Using different fields in hashCode
class WrongAddress {
    private id: number; // NOT used in equals!
 
    equals(other: WrongAddress): boolean {
        // equals uses value fields
        return this.street === other.street &&
               this.city === other.city;
    }
 
    hashCode(): number {
        // WRONG: Uses id which is NOT part of equals!
        // Two equal addresses may have DIFFERENT hash codes
        // This VIOLATES the contract catastrophically!
        return this.id;
    }
}

Modification Through Copy

The 'With' Pattern

The most common approach uses methods prefixed with with that return new instances:

with-pattern.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
class Person {
    private readonly firstName: string;
    private readonly lastName: string;
    private readonly email: Email;
 
    private constructor(
        firstName: string,
        lastName: string,
        email: Email
    ) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
    }
 
    static create(firstName: string, lastName: string, email: Email): Person {
        return new Person(firstName, lastName, email);
    }
 
    // "With" methods create new instances with one field changed
    withFirstName(firstName: string): Person {
        return new Person(firstName, this.lastName, this.email);
    }
 
    withLastName(lastName: string): Person {
        return new Person(this.firstName, lastName, this.email);
    }
 
    withEmail(email: Email): Person {
        return new Person(this.firstName, this.lastName, email);
    }
 
    // Multiple changes via chaining
    withName(firstName: string, lastName: string): Person {
        return new Person(firstName, lastName, this.email);
    }
}
 
// Usage - immutable updates through method chaining
const original = Person.create("Alice", "Smith", Email.of("alice@old.com"));
 
// Create a modified copy - original is unchanged
const updated = original
    .withLastName("Johnson")
    .withEmail(Email.of("alice@new.com"));
 
console.log(original.getLastName()); // "Smith" (unchanged)
console.log(updated.getLastName());  // "Johnson" (new instance)

Builder Pattern for Complex Value Objects

When value objects have many fields, consider a builder:

builder-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class Address {
    readonly street: string;
    readonly city: string;
    readonly state: string;
    readonly postalCode: string;
    readonly country: string;
    readonly apartment?: string;
    readonly buildingName?: string;
 
    private constructor(builder: AddressBuilder) {
        this.street = builder.street;
        this.city = builder.city;
        this.state = builder.state;
        this.postalCode = builder.postalCode;
        this.country = builder.country;
        this.apartment = builder.apartment;
        this.buildingName = builder.buildingName;
    }
 
    static builder(): AddressBuilder {
        return new AddressBuilder();
    }
 
    // Create a builder pre-populated with this address's values
    toBuilder(): AddressBuilder {
        return new AddressBuilder()
            .setStreet(this.street)
            .setCity(this.city)
            .setState(this.state)
            .setPostalCode(this.postalCode)
            .setCountry(this.country)
            .setApartment(this.apartment)
            .setBuildingName(this.buildingName);
    }
}
 
class AddressBuilder {
    street: string = '';
    city: string = '';
    state: string = '';
    postalCode: string = '';
    country: string = '';
    apartment?: string;
    buildingName?: string;
 
    setStreet(street: string): this { this.street = street; return this; }
    setCity(city: string): this { this.city = city; return this; }
    setState(state: string): this { this.state = state; return this; }
    setPostalCode(postalCode: string): this { this.postalCode = postalCode; return this; }
    setCountry(country: string): this { this.country = country; return this; }
    setApartment(apartment?: string): this { this.apartment = apartment; return this; }
    setBuildingName(buildingName?: string): this { this.buildingName = buildingName; return this; }
 
    build(): Address {
        // Validation
        if (!this.street || !this.city || !this.postalCode || !this.country) {
            throw new Error("Required fields missing");
        }
        return new Address(this);
    }
}
 
// Usage
const home = Address.builder()
    .setStreet("123 Main St")
    .setCity("New York")
    .setState("NY")
    .setPostalCode("10001")
    .setCountry("USA")
    .setApartment("4B")
    .build();
 
// Create modified copy using builder
const newHome = home.toBuilder()
    .setStreet("456 Oak Ave")
    .setApartment("7C")
    .build();

Common Equality Pitfalls

Even experienced developers make mistakes when implementing equality. Here are the most common pitfalls:

Pitfall 1: Forgetting Null and Type Checks

null-check-pitfall.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ❌ BAD: Missing null/type checks
class BadMoney {
    equals(other: BadMoney): boolean {
        // Crashes if other is null or wrong type!
        return this.amount === other.amount;
    }
}
 
// ✅ GOOD: Proper null and type handling
class GoodMoney {
    equals(other: unknown): boolean {
        if (other === null || other === undefined) return false;
        if (!(other instanceof GoodMoney)) return false;
        return this.amount === other.amount && 
               this.currency === other.currency;
    }
}

Pitfall 2: Floating Point Comparison

floating-point-pitfall.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// ❌ BAD: Direct floating point comparison
class BadMeasurement {
    constructor(private readonly value: number) {}
 
    equals(other: BadMeasurement): boolean {
        // Floating point imprecision causes false negatives!
        return this.value === other.value;
    }
}
 
const m1 = new BadMeasurement(0.1 + 0.2);
const m2 = new BadMeasurement(0.3);
console.log(m1.equals(m2)); // false! (0.30000000000000004 !== 0.3)
 
// ✅ GOOD: Use epsilon for floating point, or avoid floats for money
class GoodMeasurement {
    private static readonly EPSILON = 0.0000001;
 
    constructor(private readonly value: number) {}
 
    equals(other: GoodMeasurement): boolean {
        return Math.abs(this.value - other.value) < GoodMeasurement.EPSILON;
    }
}
 
// ✅ BETTER: Use integers for money (cents, not dollars)
class BetterMoney {
    constructor(private readonly cents: number) {} // Integer!
 
    equals(other: BetterMoney): boolean {
        return this.cents === other.cents; // Integer comparison is safe
    }
}

Pitfall 3: Inheritance and Equality

inheritance-pitfall.ts
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// ❌ BAD: instanceof allows subclass comparison
class Point {
    protected final int x, y;
 
    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof Point other)) return false;
        return x == other.x && y == other.y;
    }
}
 
class ColoredPoint extends Point {
    private final Color color;
 
    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof ColoredPoint other)) return false;
        return super.equals(obj) && color.equals(other.color);
    }
}
 
// The problem: symmetry is violated!
Point p = new Point(1, 2);
ColoredPoint cp = new ColoredPoint(1, 2, Color.RED);
 
p.equals(cp);  // true  (Point instanceof check passes)
cp.equals(p);  // false (ColoredPoint instanceof fails)
 
// This violates the symmetry requirement!
 
// ✅ SOLUTION: Use getClass() instead of instanceof
class CorrectPoint {
    @Override
    public boolean equals(Object obj) {
        if (obj == null || getClass() != obj.getClass()) return false;
        CorrectPoint other = (CorrectPoint) obj;
        return x == other.x && y == other.y;
    }
}
 
// ✅ BETTER: Make value objects final (prevent subclassing)
public final class Point { ... }

Summary: Immutability and Equality

We've explored the twin pillars that define value objects. Let's consolidate the key insights:

Key Takeaways

•Immutability is non-negotiable — Mutable value objects cause aliasing bugs, break hash collections, and create thread-safety issues.
•Use defensive copying — When receiving or returning mutable types, copy them to preserve immutability.
•Value equality compares all attributes — Two value objects are equal if and only if all their component values are equal.
•equals and hashCode are coupled — Always implement both, using the same fields in each.
•Modification creates new instances — Use 'with' methods or builders to create modified copies.
•Make value object classes final — Prevent subclassing to avoid equality contract violations.

What's next:

Page Complete