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
78
79
80
81
82
83
84
85

// Product Aggregate - manages product catalog information
class Product {
    constructor(
        private readonly _productId: string,
        private _name: string,
        private _description: string,
        private _price: Money,
        private _categoryIds: Set<string>
    ) {}
    
    updateDetails(name: string, description: string): void {
        this._name = name;
        this._description = description;
        // No inventory impact
    }
    
    updatePrice(price: Money): void {
        if (price.amount < 0) throw new Error("Price cannot be negative");
        this._price = price;
        // Price change doesn't require inventory lock
    }
}
 
// InventoryItem Aggregate - manages stock for one product at one location
class InventoryItem {
    constructor(
        private readonly _productId: string,
        private readonly _locationId: string,
        private _quantityOnHand: number,
        private _reservedQuantity: number
    ) {}
    
    // Invariant: Available = OnHand - Reserved ≥ 0
    get availableQuantity(): number {
        return this._quantityOnHand - this._reservedQuantity;
    }
    
    reserve(quantity: number, orderId: string): Reservation {
        if (quantity > this.availableQuantity) {
            throw new InsufficientStockError(
                this._productId, 
                this.availableQuantity, 
                quantity
            );
        }
        
        this._reservedQuantity += quantity;
        return new Reservation(
            this._productId,
            this._locationId,
            orderId,
            quantity
        );
    }
    
    release(reservation: Reservation): void {
        this._reservedQuantity -= reservation.quantity;
    }
    
    confirmShipment(reservation: Reservation): void {
        this._quantityOnHand -= reservation.quantity;
        this._reservedQuantity -= reservation.quantity;
    }
    
    receiveStock(quantity: number, receivingId: string): void {
        if (quantity <= 0) throw new Error("Quantity must be positive");
        this._quantityOnHand += quantity;
    }
}
 
// Order references products by ID, not by object
class Order {
    private readonly _customerId: string;
    private readonly _lines: Map<string, OrderLine> = new Map();
    
    addLine(
        productId: string,      // Reference by ID
        productName: string,    // Snapshot for display
        productPrice: Money,    // Snapshot at time of order
        quantity: number
    ): void {
        // Order doesn't check inventory - that's handled by
        // coordination with InventoryItem aggregate
    }
}

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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

// ❌ WRONG: Everything in one aggregate
class MonolithicForum {
    private threads: Thread[] = [];  // Each has posts, each has reactions
    
    addReaction(threadId: string, postId: string, userId: string, type: string): void {
        // Must load entire forum to add one reaction!
        const thread = this.threads.find(t => t.id === threadId);
        const post = thread?.posts.find(p => p.id === postId);
        post?.addReaction(userId, type);
    }
}
 
// ✅ CORRECT: Multiple focused aggregates
 
// Forum Aggregate - manages forum metadata and rules
class Forum {
    constructor(
        private readonly _forumId: string,
        private _name: string,
        private _isLocked: boolean,
        private _moderatorIds: Set<string>
    ) {}
    
    // Invariant: Only moderators can lock
    lock(moderatorId: string): void {
        if (!this._moderatorIds.has(moderatorId)) {
            throw new Error("Only moderators can lock forum");
        }
        this._isLocked = true;
    }
}
 
// Thread Aggregate - manages thread and posting rules
class Thread {
    private _postCount: number = 0;
    
    constructor(
        private readonly _threadId: string,
        private readonly _forumId: string,       // Reference to forum
        private readonly _authorId: string,
        private _title: string,
        private _isLocked: boolean,
        private _isPinned: boolean
    ) {}
    
    // Thread tracks post count for queries, but doesn't contain posts
    incrementPostCount(): void {
        this._postCount++;
    }
    
    lock(): void {
        this._isLocked = true;
    }
}
 
// Post Aggregate - manages single post and its reactions
class Post {
    private readonly _reactions: Map<string, Reaction> = new Map();
    private static readonly MAX_REACTIONS = 1000;
    
    constructor(
        private readonly _postId: string,
        private readonly _threadId: string,      // Reference to thread
        private readonly _authorId: string,
        private _content: string,
        private readonly _createdAt: Date
    ) {}
    
    // Post is small: just content + reactions
    addReaction(userId: string, type: ReactionType): void {
        const reactionId = `${userId}-${type}`;
        
        // Invariant: One reaction per type per user
        if (this._reactions.has(reactionId)) {
            throw new Error("User already has this reaction");
        }
        
        // Invariant: Max reactions per post
        if (this._reactions.size >= Post.MAX_REACTIONS) {
            throw new Error("Maximum reactions reached");
        }
        
        this._reactions.set(reactionId, new Reaction(userId, type));
    }
    
    removeReaction(userId: string, type: ReactionType): void {
        const reactionId = `${userId}-${type}`;
        this._reactions.delete(reactionId);
    }
    
    edit(newContent: string, editorId: string): void {
        // Invariant: Only author can edit
        if (editorId !== this._authorId) {
            throw new Error("Only author can edit");
        }
        this._content = newContent;
    }
}
 
type ReactionType = 'like' | 'love' | 'laugh' | 'angry' | 'sad';
 
class Reaction {
    constructor(
        readonly userId: string,
        readonly type: ReactionType,
        readonly createdAt: Date = new Date()
    ) {}
}

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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

// ❌ WRONG: Direct object references
class BadOrder {
    private customer: Customer;        // Object reference
    private shippingAddress: Address;  // Object reference to Address aggregate
    private items: BadOrderItem[] = [];
    
    confirm(): void {
        // Tempting to reach into customer
        if (!this.customer.isVerified) {
            throw new Error("Customer not verified");
        }
        
        // Tempting to modify customer
        this.customer.setLastOrderDate(new Date());  // BAD!
        
        // This creates:
        // 1. Loading dependency on Customer
        // 2. Potential modification of Customer
        // 3. Unclear transaction boundary
    }
}
 
class BadOrderItem {
    private product: Product;  // Object reference to Product aggregate
    
    getPrice(): Money {
        // What if product price changed?
        // Should order reflect original or current price?
        return this.product.price;  // Ambiguous!
    }
}
 
// ✅ CORRECT: Reference by identity + snapshots
class GoodOrder {
    private readonly _customerId: string;              // ID reference
    private readonly _shippingAddressId: string;       // ID reference
    private _shippingAddressSnapshot: AddressSnapshot; // Snapshot at order time
    private readonly _items: Map<string, GoodOrderItem> = new Map();
    
    constructor(
        orderId: string,
        customerId: string,
        shippingAddress: AddressSnapshot  // Value object snapshot
    ) {
        this._customerId = customerId;
        this._shippingAddressSnapshot = shippingAddress;
    }
    
    // Order doesn't know about Customer aggregate - just its ID
    get customerId(): string {
        return this._customerId;
    }
    
    // Address is snapshotted - changes to customer's address don't affect order
    get shippingAddress(): AddressSnapshot {
        return this._shippingAddressSnapshot;
    }
}
 
class GoodOrderItem {
    // Snapshot of product details at time of order
    private readonly _productId: string;
    private readonly _productName: string;       // Snapshot
    private readonly _unitPrice: Money;          // Snapshot
    private _quantity: number;
    
    constructor(
        lineId: string,
        productId: string,
        productName: string,    // Snapshotted from Product
        unitPrice: Money,       // Snapshotted from Product
        quantity: number
    ) {
        this._productId = productId;
        this._productName = productName;
        this._unitPrice = unitPrice;
        this._quantity = quantity;
    }
    
    // Price is fixed at order time - product price changes don't affect order
    get unitPrice(): Money {
        return this._unitPrice;
    }
    
    get lineTotal(): Money {
        return this._unitPrice.multiply(this._quantity);
    }
}
 
// Value object for address snapshot
class AddressSnapshot {
    constructor(
        readonly street: string,
        readonly city: string,
        readonly postalCode: string,
        readonly country: string
    ) {}
    
    // Immutable - no setters
}

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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

// Aggregate publishes event as part of its transaction
class Order {
    private readonly _events: DomainEvent[] = [];
    
    confirm(): void {
        this.validateForConfirmation();
        this._status = 'confirmed';
        
        // Event added to aggregate, not published yet
        this._events.push(new OrderConfirmedEvent(
            this._orderId,
            this._customerId,
            this.calculateTotal(),
            this.getItemsSnapshot()
        ));
    }
    
    get pendingEvents(): DomainEvent[] {
        return [...this._events];
    }
    
    clearEvents(): void {
        this._events.length = 0;
    }
}
 
// Repository saves aggregate AND events in same transaction (outbox)
class OrderRepository {
    async save(order: Order): Promise<void> {
        await this.db.transaction(async (tx) => {
            // Save the aggregate
            await tx.query(`
                INSERT INTO orders (...) VALUES (...)
                ON CONFLICT (id) DO UPDATE SET ...
            `);
            
            // Save events to outbox (same transaction!)
            for (const event of order.pendingEvents) {
                await tx.query(`
                    INSERT INTO outbox_events (event_id, event_type, payload, created_at)
                    VALUES ($1, $2, $3, NOW())
                `, [event.eventId, event.type, JSON.stringify(event)]);
            }
            
            order.clearEvents();
        });
    }
}
 
// Background process publishes events from outbox
class OutboxProcessor {
    async processOutbox(): Promise<void> {
        const events = await this.db.query(`
            SELECT * FROM outbox_events
            WHERE published_at IS NULL
            ORDER BY created_at
            LIMIT 100
        `);
        
        for (const eventRow of events) {
            try {
                await this.eventPublisher.publish(eventRow.payload);
                await this.db.query(`
                    UPDATE outbox_events
                    SET published_at = NOW()
                    WHERE event_id = $1
                `, [eventRow.event_id]);
            } catch (error) {
                // Log and continue - will retry later
                console.error(`Failed to publish event ${eventRow.event_id}`, error);
            }
        }
    }
}
 
// Handlers update other aggregates eventually
class InventoryHandler {
    async handleOrderConfirmed(event: OrderConfirmedEvent): Promise<void> {
        for (const item of event.items) {
            const inventory = await this.inventoryRepo.findByProductId(item.productId);
            inventory.commitReservation(event.orderId);
            await this.inventoryRepo.save(inventory);
        }
    }
}
 
class CustomerHandler {
    async handleOrderConfirmed(event: OrderConfirmedEvent): Promise<void> {
        const customer = await this.customerRepo.findById(event.customerId);
        customer.addLoyaltyPoints(this.calculatePoints(event.totalAmount));
        await this.customerRepo.save(customer);
    }
}

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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

class Reservation {
    // ============================================
    // PRIVATE STATE - No public setters
    // ============================================
    private _status: ReservationStatus;
    private readonly _slots: TimeSlot[] = [];
    private _cancellation: Cancellation | null = null;
    
    // ============================================
    // FACTORY METHOD - Creation logic encapsulated
    // ============================================
    private constructor(
        private readonly _reservationId: string,
        private readonly _resourceId: string,
        private readonly _customerId: string,
        private readonly _createdAt: Date
    ) {
        this._status = ReservationStatus.Pending;
    }
    
    static create(
        reservationId: string,
        resourceId: string,
        customerId: string,
        slot: TimeSlot
    ): Reservation {
        const reservation = new Reservation(
            reservationId,
            resourceId,
            customerId,
            new Date()
        );
        
        // Invariant check during creation
        if (slot.duration.minutes < 30) {
            throw new ReservationError("Minimum reservation is 30 minutes");
        }
        if (slot.startTime < new Date()) {
            throw new ReservationError("Cannot reserve in the past");
        }
        
        reservation._slots.push(slot);
        return reservation;
    }
    
    // ============================================
    // STATE PATTERN - Explicit status transitions
    // ============================================
    confirm(): void {
        if (this._status !== ReservationStatus.Pending) {
            throw new ReservationError(
                `Cannot confirm reservation in ${this._status} status`
            );
        }
        this._status = ReservationStatus.Confirmed;
    }
    
    checkIn(): void {
        if (this._status !== ReservationStatus.Confirmed) {
            throw new ReservationError("Can only check in confirmed reservations");
        }
        
        // Business rule: Can only check in within time window
        const now = new Date();
        const firstSlot = this._slots[0];
        const checkInWindow = 15 * 60 * 1000; // 15 minutes
        
        if (now < new Date(firstSlot.startTime.getTime() - checkInWindow)) {
            throw new ReservationError("Too early to check in");
        }
        
        this._status = ReservationStatus.CheckedIn;
    }
    
    cancel(reason: string, cancelledBy: string): void {
        if (!this.canBeCancelled()) {
            throw new ReservationError(
                `Cannot cancel reservation in ${this._status} status`
            );
        }
        
        this._status = ReservationStatus.Cancelled;
        this._cancellation = {
            reason,
            cancelledBy,
            cancelledAt: new Date()
        };
    }
    
    private canBeCancelled(): boolean {
        return this._status === ReservationStatus.Pending ||
               this._status === ReservationStatus.Confirmed;
    }
    
    // ============================================
    // COMPUTED PROPERTY - Derived from state
    // ============================================
    get totalDuration(): Duration {
        return this._slots.reduce(
            (total, slot) => total.add(slot.duration),
            Duration.zero()
        );
    }
    
    get isPast(): boolean {
        const lastSlot = this._slots[this._slots.length - 1];
        return lastSlot.endTime < new Date();
    }
    
    // ============================================
    // COLLECTION ENCAPSULATION - Read-only access
    // ============================================
    get slots(): ReadonlyArray<TimeSlot> {
        return [...this._slots];  // Return copy
    }
    
    // ============================================
    // DOMAIN-SPECIFIC EXCEPTIONS
    // ============================================
    addSlot(slot: TimeSlot): void {
        // Business rule: Slots can't overlap
        for (const existing of this._slots) {
            if (slot.overlaps(existing)) {
                throw new ReservationError(
                    "New slot overlaps with existing reservation slot"
                );
            }
        }
        
        // Business rule: Max 4 hours total
        const newTotal = this.totalDuration.add(slot.duration);
        if (newTotal.hours > 4) {
            throw new ReservationError(
                "Total reservation cannot exceed 4 hours"
            );
        }
        
        this._slots.push(slot);
    }
}
 
enum ReservationStatus {
    Pending = 'pending',
    Confirmed = 'confirmed',
    CheckedIn = 'checked_in',
    Completed = 'completed',
    Cancelled = 'cancelled',
    NoShow = 'no_show'
}
 
class ReservationError extends Error {
    constructor(message: string) {
        super(message);
        this.name = 'ReservationError';
    }
}

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
78
79
80
81
82
83

// ❌ ANEMIC: Just data, no behavior
class AnemicOrder {
    orderId: string = '';
    customerId: string = '';
    status: string = 'draft';
    items: AnemicOrderItem[] = [];
    total: number = 0;
}
 
class OrderApplicationService {
    confirmOrder(order: AnemicOrder): void {
        // All logic in service, not aggregate
        if (order.items.length === 0) {
            throw new Error("Order must have items");
        }
        if (order.status !== 'draft') {
            throw new Error("Can only confirm draft orders");
        }
        
        order.status = 'confirmed';
        order.total = order.items.reduce((sum, i) => sum + i.price * i.qty, 0);
        
        // Order doesn't protect itself
    }
}
 
// ✅ RICH: Behavior lives with the data
class RichOrder {
    private readonly _items: Map<string, OrderItem> = new Map();
    private _status: OrderStatus = 'draft';
    
    private constructor(
        private readonly _orderId: string,
        private readonly _customerId: string
    ) {}
    
    static create(orderId: string, customerId: string): RichOrder {
        return new RichOrder(orderId, customerId);
    }
    
    // Behavior encapsulated in aggregate
    addItem(productId: string, name: string, price: Money, quantity: number): void {
        this.ensureModifiable();
        
        if (this._items.size >= 50) {
            throw new OrderError("Maximum 50 items per order");
        }
        
        const item = OrderItem.create(productId, name, price, quantity);
        this._items.set(productId, item);
    }
    
    confirm(): OrderConfirmation {
        // Invariants enforced by aggregate, not services
        if (this._items.size === 0) {
            throw new OrderError("Order must have at least one item");
        }
        if (this._status !== 'draft') {
            throw new OrderError(`Cannot confirm ${this._status} order`);
        }
        
        this._status = 'confirmed';
        
        return new OrderConfirmation(
            this._orderId,
            this._customerId,
            this.calculateTotal(),
            new Date()
        );
    }
    
    // Total is computed, never stored
    private calculateTotal(): Money {
        return Array.from(this._items.values())
            .reduce((sum, item) => sum.add(item.lineTotal), Money.zero('USD'));
    }
    
    private ensureModifiable(): void {
        if (this._status !== 'draft') {
            throw new OrderError(`Cannot modify ${this._status} order`);
        }
    }
}