Aggregates: Modeling Consistency Boundaries

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

// ❌ Without aggregates: Direct manipulation of internal objects
class OrderItem {
    constructor(
        public productId: string,
        public quantity: number,
        public unitPrice: number
    ) {}
    
    // Anyone can change quantity directly
    setQuantity(quantity: number) {
        this.quantity = quantity;
        // But who updates the order total?
        // Who checks if we exceeded 10 items?
        // Who verifies the credit limit?
    }
}
 
class Order {
    public items: OrderItem[] = [];  // Exposed for direct modification!
    public total: number = 0;
    
    // Total can become stale if items are modified externally
    recalculateTotal() {
        this.total = this.items.reduce(
            (sum, item) => sum + item.quantity * item.unitPrice, 0
        );
    }
}
 
// Problem: External code can modify items directly
function dangerousOperation(order: Order) {
    // Nothing stops us from doing this:
    order.items.push(new OrderItem("prod-1", 100, 99.99));
    // Order total is now stale
    // Item limit invariant is bypassed
    // Credit limit check is skipped
}

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

// ✅ With aggregates: All modifications through the root
class OrderItem {
    private constructor(
        private readonly _productId: string,
        private _quantity: number,
        private readonly _unitPrice: number
    ) {}
    
    static create(productId: string, quantity: number, unitPrice: number): OrderItem {
        if (quantity <= 0) throw new Error("Quantity must be positive");
        if (unitPrice < 0) throw new Error("Price cannot be negative");
        return new OrderItem(productId, quantity, unitPrice);
    }
    
    get productId(): string { return this._productId; }
    get quantity(): number { return this._quantity; }
    get unitPrice(): number { return this._unitPrice; }
    get total(): number { return this._quantity * this._unitPrice; }
    
    // Package-private: Only Order can call this
    _updateQuantity(quantity: number): void {
        if (quantity <= 0) throw new Error("Quantity must be positive");
        this._quantity = quantity;
    }
}
 
class Order {
    private readonly _items: Map<string, OrderItem> = new Map();
    private readonly MAX_ITEMS = 10;
    
    private constructor(
        private readonly _id: string,
        private readonly _customerId: string,
        private readonly _creditLimit: number
    ) {}
    
    static create(id: string, customerId: string, creditLimit: number): Order {
        return new Order(id, customerId, creditLimit);
    }
    
    // All invariants enforced through this single entry point
    addItem(productId: string, quantity: number, unitPrice: number): void {
        // Invariant: Max 10 items
        if (this._items.size >= this.MAX_ITEMS) {
            throw new Error(`Order cannot have more than ${this.MAX_ITEMS} items`);
        }
        
        // Invariant: No duplicate products (combine instead)
        if (this._items.has(productId)) {
            throw new Error("Product already in order. Use updateItemQuantity instead.");
        }
        
        const item = OrderItem.create(productId, quantity, unitPrice);
        
        // Invariant: Total cannot exceed credit limit
        const newTotal = this.total + item.total;
        if (newTotal > this._creditLimit) {
            throw new Error(`Order total ${newTotal} exceeds credit limit ${this._creditLimit}`);
        }
        
        this._items.set(productId, item);
    }
    
    updateItemQuantity(productId: string, newQuantity: number): void {
        const item = this._items.get(productId);
        if (!item) throw new Error(`Product ${productId} not in order`);
        
        const oldTotal = item.total;
        const newItemTotal = newQuantity * item.unitPrice;
        const projectedTotal = this.total - oldTotal + newItemTotal;
        
        // Invariant: Total cannot exceed credit limit
        if (projectedTotal > this._creditLimit) {
            throw new Error(`Updated total ${projectedTotal} exceeds credit limit`);
        }
        
        item._updateQuantity(newQuantity);
    }
    
    removeItem(productId: string): void {
        if (!this._items.has(productId)) {
            throw new Error(`Product ${productId} not in order`);
        }
        this._items.delete(productId);
    }
    
    // Invariant: Total always equals sum of items (computed property)
    get total(): number {
        let sum = 0;
        for (const item of this._items.values()) {
            sum += item.total;
        }
        return sum;
    }
    
    get itemCount(): number { return this._items.size; }
    
    // Read-only view of items
    get items(): ReadonlyArray<OrderItem> {
        return Array.from(this._items.values());
    }
}

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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256

// ============================================
// VALUE OBJECTS - Immutable, no identity
// ============================================
 
class Money {
    private constructor(
        private readonly _amount: number,
        private readonly _currency: string
    ) {}
    
    static create(amount: number, currency: string): Money {
        if (amount < 0) throw new Error("Money cannot be negative");
        return new Money(amount, currency);
    }
    
    get amount(): number { return this._amount; }
    get currency(): string { return this._currency; }
    
    add(other: Money): Money {
        if (this._currency !== other._currency) {
            throw new Error("Cannot add different currencies");
        }
        return new Money(this._amount + other._amount, this._currency);
    }
    
    multiply(factor: number): Money {
        return new Money(this._amount * factor, this._currency);
    }
    
    equals(other: Money): boolean {
        return this._amount === other._amount && 
               this._currency === other._currency;
    }
}
 
class Address {
    private constructor(
        private readonly _street: string,
        private readonly _city: string,
        private readonly _postalCode: string,
        private readonly _country: string
    ) {}
    
    static create(street: string, city: string, postalCode: string, country: string): Address {
        if (!street || !city || !postalCode || !country) {
            throw new Error("All address fields are required");
        }
        return new Address(street, city, postalCode, country);
    }
    
    // Getters...
    get street(): string { return this._street; }
    get city(): string { return this._city; }
    get postalCode(): string { return this._postalCode; }
    get country(): string { return this._country; }
    
    equals(other: Address): boolean {
        return this._street === other._street &&
               this._city === other._city &&
               this._postalCode === other._postalCode &&
               this._country === other._country;
    }
}
 
// ============================================
// INTERNAL ENTITY - Local identity only
// ============================================
 
class OrderLine {
    private _quantity: number;
    
    private constructor(
        private readonly _lineId: string,  // Local identity
        private readonly _productId: string,
        private readonly _productName: string,
        private readonly _unitPrice: Money,
        quantity: number
    ) {
        this._quantity = quantity;
    }
    
    static create(
        lineId: string,
        productId: string,
        productName: string,
        unitPrice: Money,
        quantity: number
    ): OrderLine {
        if (quantity <= 0) throw new Error("Quantity must be positive");
        return new OrderLine(lineId, productId, productName, unitPrice, quantity);
    }
    
    get lineId(): string { return this._lineId; }
    get productId(): string { return this._productId; }
    get productName(): string { return this._productName; }
    get quantity(): number { return this._quantity; }
    get unitPrice(): Money { return this._unitPrice; }
    
    get lineTotal(): Money {
        return this._unitPrice.multiply(this._quantity);
    }
    
    // Package-private for root to call
    _adjustQuantity(newQuantity: number): void {
        if (newQuantity <= 0) throw new Error("Quantity must be positive");
        this._quantity = newQuantity;
    }
}
 
// ============================================
// AGGREGATE ROOT - Global identity, controls access
// ============================================
 
type OrderStatus = 'draft' | 'confirmed' | 'shipped' | 'delivered' | 'cancelled';
 
class Order {
    private readonly _lines: Map<string, OrderLine> = new Map();
    private _shippingAddress: Address | null = null;
    private _status: OrderStatus = 'draft';
    private _lineIdCounter = 0;
    
    private static readonly MAX_LINES = 20;
    private static readonly MAX_ORDER_TOTAL = Money.create(10000, 'USD');
    
    private constructor(
        private readonly _orderId: string,          // Global identity
        private readonly _customerId: string,       // Reference to another aggregate
        private readonly _createdAt: Date
    ) {}
    
    static create(orderId: string, customerId: string): Order {
        return new Order(orderId, customerId, new Date());
    }
    
    // ============================================
    // INVARIANT-PROTECTING OPERATIONS
    // ============================================
    
    addLine(productId: string, productName: string, unitPrice: Money, quantity: number): string {
        this.ensureModifiable();
        
        // Invariant: Max 20 lines
        if (this._lines.size >= Order.MAX_LINES) {
            throw new Error(`Order cannot have more than ${Order.MAX_LINES} lines`);
        }
        
        // Create line
        const lineId = `line-${++this._lineIdCounter}`;
        const line = OrderLine.create(lineId, productId, productName, unitPrice, quantity);
        
        // Invariant: Total cannot exceed maximum
        const projectedTotal = this.calculateTotal().add(line.lineTotal);
        if (projectedTotal.amount > Order.MAX_ORDER_TOTAL.amount) {
            throw new Error(`Order total cannot exceed ${Order.MAX_ORDER_TOTAL.amount}`);
        }
        
        this._lines.set(lineId, line);
        return lineId;
    }
    
    updateLineQuantity(lineId: string, newQuantity: number): void {
        this.ensureModifiable();
        
        const line = this._lines.get(lineId);
        if (!line) throw new Error(`Line ${lineId} not found`);
        
        // Calculate projected total
        const currentLineTotal = line.lineTotal;
        const newLineTotal = line.unitPrice.multiply(newQuantity);
        const projectedTotal = this.calculateTotal()
            .add(newLineTotal)
            .add(Money.create(-currentLineTotal.amount, currentLineTotal.currency));
        
        // Invariant: Total cannot exceed maximum
        if (projectedTotal.amount > Order.MAX_ORDER_TOTAL.amount) {
            throw new Error(`Order total cannot exceed ${Order.MAX_ORDER_TOTAL.amount}`);
        }
        
        line._adjustQuantity(newQuantity);
    }
    
    removeLine(lineId: string): void {
        this.ensureModifiable();
        
        if (!this._lines.has(lineId)) {
            throw new Error(`Line ${lineId} not found`);
        }
        this._lines.delete(lineId);
    }
    
    setShippingAddress(address: Address): void {
        this.ensureModifiable();
        this._shippingAddress = address;
    }
    
    confirm(): void {
        // Invariant: Must have at least one line
        if (this._lines.size === 0) {
            throw new Error("Cannot confirm order with no items");
        }
        
        // Invariant: Must have shipping address
        if (!this._shippingAddress) {
            throw new Error("Cannot confirm order without shipping address");
        }
        
        // Invariant: Can only confirm from draft
        if (this._status !== 'draft') {
            throw new Error(`Cannot confirm order in ${this._status} status`);
        }
        
        this._status = 'confirmed';
    }
    
    cancel(): void {
        // Invariant: Can only cancel draft or confirmed orders
        if (this._status === 'shipped' || this._status === 'delivered') {
            throw new Error(`Cannot cancel order in ${this._status} status`);
        }
        this._status = 'cancelled';
    }
    
    // ============================================
    // QUERY METHODS (read-only)
    // ============================================
    
    get orderId(): string { return this._orderId; }
    get customerId(): string { return this._customerId; }
    get status(): OrderStatus { return this._status; }
    get shippingAddress(): Address | null { return this._shippingAddress; }
    get createdAt(): Date { return new Date(this._createdAt.getTime()); }
    
    get lines(): ReadonlyArray<OrderLine> {
        return Array.from(this._lines.values());
    }
    
    get lineCount(): number { return this._lines.size; }
    
    calculateTotal(): Money {
        let total = Money.create(0, 'USD');
        for (const line of this._lines.values()) {
            total = total.add(line.lineTotal);
        }
        return total;
    }
    
    // ============================================
    // PRIVATE HELPERS
    // ============================================
    
    private ensureModifiable(): void {
        if (this._status !== 'draft') {
            throw new Error(`Cannot modify order in ${this._status} status`);
        }
    }
}

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

// ❌ WRONG: Direct object references between aggregates
class Order {
    private customer: Customer;  // Direct reference - BAD!
    private items: OrderItem[];
    
    getCustomerAddress(): Address {
        // This creates coupling and loading issues
        return this.customer.getShippingAddress();
    }
    
    confirmOrder(): void {
        // What happens if we accidentally modify customer?
        // Should this save the customer too?
        this.customer.updateLastOrderDate(new Date());  // Inappropriate!
    }
}
 
// ✅ CORRECT: Reference by identity
class Order {
    private readonly _customerId: string;  // ID reference only - GOOD!
    private readonly _lines: Map<string, OrderLine> = new Map();
    
    // To get customer details, we go through a service or query
    // This is explicit, not hidden behind object navigation
    get customerId(): string {
        return this._customerId;
    }
    
    confirmOrder(): void {
        // Order only updates its own state
        // If customer needs updating, that's a separate operation
        // handled by an application service
        this._status = 'confirmed';
    }
}
 
// Application service coordinates across aggregates
class OrderConfirmationService {
    constructor(
        private orderRepository: OrderRepository,
        private customerRepository: CustomerRepository,
        private eventPublisher: EventPublisher
    ) {}
    
    async confirmOrder(orderId: string): Promise<void> {
        const order = await this.orderRepository.findById(orderId);
        
        // Order only manages its own state
        order.confirm();
        
        await this.orderRepository.save(order);
        
        // Customer update is a separate concern, if needed
        // Could be eventually consistent via events
        this.eventPublisher.publish(new OrderConfirmedEvent(
            order.orderId,
            order.customerId,
            order.calculateTotal()
        ));
    }
}

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

// ✅ CORRECT: Repository for aggregate root only
interface OrderRepository {
    findById(orderId: string): Promise<Order | null>;
    save(order: Order): Promise<void>;
    delete(orderId: string): Promise<void>;
    
    // Query methods return aggregate roots
    findByCustomerId(customerId: string): Promise<Order[]>;
    findPendingOrders(): Promise<Order[]>;
}
 
// ❌ WRONG: No repository for internal entities
// This would bypass the aggregate root!
interface OrderItemRepository {  // DON'T DO THIS
    findById(itemId: string): Promise<OrderItem>;
    save(item: OrderItem): Promise<void>;
}
 
// ✅ Implementation loads/saves entire aggregate atomically
class SqlOrderRepository implements OrderRepository {
    async findById(orderId: string): Promise<Order | null> {
        // Single query or optimized joins to load entire aggregate
        const orderData = await this.db.query(`
            SELECT o.*, ol.*
            FROM orders o
            LEFT JOIN order_lines ol ON o.id = ol.order_id
            WHERE o.id = $1
        `, [orderId]);
        
        if (!orderData.length) return null;
        
        // Reconstitute the complete aggregate
        return this.mapToAggregate(orderData);
    }
    
    async save(order: Order): Promise<void> {
        await this.db.transaction(async (tx) => {
            // Save order root
            await tx.query(`
                INSERT INTO orders (id, customer_id, status, shipping_address, created_at)
                VALUES ($1, $2, $3, $4, $5)
                ON CONFLICT (id) DO UPDATE SET
                    status = $3,
                    shipping_address = $4
            `, [order.orderId, order.customerId, order.status, 
                order.shippingAddress, order.createdAt]);
            
            // Delete existing lines and re-insert (simple approach)
            await tx.query('DELETE FROM order_lines WHERE order_id = $1', [order.orderId]);
            
            for (const line of order.lines) {
                await tx.query(`
                    INSERT INTO order_lines (id, order_id, product_id, product_name, unit_price, quantity)
                    VALUES ($1, $2, $3, $4, $5, $6)
                `, [line.lineId, order.orderId, line.productId, 
                    line.productName, line.unitPrice.amount, line.quantity]);
            }
        });
    }
}