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

// Comprehensive attribute specification
class Order {
    // Identity - immutable after creation
    private readonly id: OrderId;
    
    // References - associations to other entities
    private readonly customerId: CustomerId;
    private shippingAddress: Address;  // mutable - can change before shipping
    
    // Collections - order contains items
    private readonly items: OrderItem[] = [];
    
    // State tracking - evolves over lifecycle
    private status: OrderStatus = OrderStatus.CREATED;
    private statusHistory: StatusTransition[] = [];
    
    // Timestamps - audit trail
    private readonly createdAt: Date;
    private updatedAt: Date;
    private shippedAt?: Date;  // optional - only set when shipped
    
    // Calculated values - derived from state
    get totalAmount(): Money {
        return this.items.reduce(
            (sum, item) => sum.add(item.subtotal),
            Money.zero(this.currency)
        );
    }
    
    // Constraints expressed through types and validation
    // OrderId, CustomerId, Money, Address are all strongly typed
    // Optional fields use ?: syntax
    // Readonly fields cannot change after construction
}

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

// BAD: Fat interface - not all implementations need all methods
interface IUserOperations {
    createUser(data: UserData): User;
    updateUser(id: string, data: Partial<UserData>): User;
    deleteUser(id: string): void;
    findById(id: string): User | null;
    findByEmail(email: string): User | null;
    searchUsers(query: string): User[];
    bulkImport(users: UserData[]): ImportResult;
    exportToCSV(): string;
    sendPasswordReset(email: string): void;
    validateCredentials(email: string, password: string): boolean;
}
 
// GOOD: Segregated interfaces - each focused on one capability
interface IUserRepository {
    findById(id: string): User | null;
    findByEmail(email: string): User | null; 
    save(user: User): void;
    delete(id: string): void;
}
 
interface IUserSearch {
    search(query: SearchQuery): PagedResult<User>;
    suggest(prefix: string): User[];
}
 
interface IUserAuthentication {
    validateCredentials(email: string, password: string): AuthResult;
    generateResetToken(email: string): ResetToken;
    resetPassword(token: ResetToken, newPassword: Password): void;
}
 
interface IUserDataExport {
    exportToCSV(criteria: ExportCriteria): Stream<string>;
    exportToJSON(criteria: ExportCriteria): Stream<object>;
}
 
// Now clients depend only on what they need
class LoginService {
    constructor(private auth: IUserAuthentication) {}
    // Only depends on authentication, not search or export
}
 
class UserSearchController {
    constructor(private search: IUserSearch) {}
    // Only depends on search, not authentication or repository
}

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

interface IOrderService {
    /**
     * Places a new order for a customer.
     * 
     * @param customerId - The customer placing the order (must exist)
     * @param items - Items to order (must be non-empty, all available)
     * @param shippingAddress - Delivery destination (must be valid)
     * 
     * @returns OrderResult - Success with Order, or Failure with reason
     * 
     * @precondition Customer exists and is active
     * @precondition All items are available in inventory
     * @precondition Shipping address is serviceable
     * 
     * @postcondition Order is persisted with PENDING status
     * @postcondition Inventory is reserved for items
     * @postcondition OrderPlaced event is published
     * 
     * @throws never - All errors returned in OrderResult
     */
    placeOrder(
        customerId: CustomerId,
        items: OrderItem[],
        shippingAddress: Address
    ): Promise<OrderResult>;
 
    /**
     * Cancels an existing order.
     * 
     * @param orderId - The order to cancel
     * @param reason - Cancellation reason for records
     * 
     * @precondition Order exists
     * @precondition Order is in cancellable state (PENDING, CONFIRMED)
     * 
     * @postcondition Order status is CANCELLED
     * @postcondition Inventory reservations are released
     * @postcondition Customer is notified
     * @postcondition Refund is initiated if payment was made
     */
    cancelOrder(
        orderId: OrderId,
        reason: CancellationReason
    ): Promise<CancellationResult>;
}
 
// Result types make success/failure explicit
type OrderResult = 
    | { success: true; order: Order }
    | { success: false; error: OrderError };
 
type OrderError = 
    | { code: 'CUSTOMER_NOT_FOUND'; customerId: string }
    | { code: 'ITEMS_UNAVAILABLE'; unavailable: OrderItem[] }
    | { code: 'INVALID_ADDRESS'; address: Address; reason: string }
    | { code: 'CREDIT_LIMIT_EXCEEDED'; limit: Money; requested: Money };

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

/**
 * Use Case: Place Order
 * 
 * Participants:
 * - OrderController (entry point)
 * - OrderValidator (business rules)
 * - InventoryService (stock management)
 * - PaymentService (payment processing)
 * - OrderRepository (persistence)
 * - NotificationService (customer communication)
 * - EventPublisher (system events)
 * 
 * Sequence:
 * 1. OrderController receives PlaceOrderRequest
 * 2. OrderController calls OrderValidator.validate(request)
 *    - If invalid: return validation errors, END
 * 3. OrderController calls InventoryService.reserve(items)
 *    - If insufficient: return availability errors, END
 * 4. OrderController creates Order domain object
 * 5. OrderController calls PaymentService.authorize(order, paymentDetails)
 *    - If declined: release inventory, return payment error, END
 * 6. OrderController calls OrderRepository.save(order)
 * 7. OrderController calls NotificationService.sendConfirmation(order)
 * 8. OrderController calls EventPublisher.publish(OrderPlacedEvent)
 * 9. Return success with Order details
 * 
 * Error Handling:
 * - Any exception after step 3: release inventory reservation
 * - Any exception after step 5: void payment authorization
 * - All operations are logged for audit
 */
 
class OrderController {
    constructor(
        private validator: IOrderValidator,
        private inventory: IInventoryService,
        private payment: IPaymentService,
        private repository: IOrderRepository,
        private notifications: INotificationService,
        private events: IEventPublisher
    ) {}
    
    async placeOrder(request: PlaceOrderRequest): Promise<PlaceOrderResponse> {
        // Step 2: Validate
        const validation = await this.validator.validate(request);
        if (!validation.isValid) {
            return PlaceOrderResponse.validationFailed(validation.errors);
        }
        
        // Step 3: Reserve inventory
        const reservation = await this.inventory.reserve(request.items);
        if (!reservation.success) {
            return PlaceOrderResponse.insufficientInventory(reservation.unavailable);
        }
        
        try {
            // Step 4: Create order
            const order = Order.create(request);
            
            // Step 5: Authorize payment
            const authorization = await this.payment.authorize(
                order.totalAmount,
                request.paymentDetails
            );
            if (!authorization.success) {
                await this.inventory.release(reservation.id);
                return PlaceOrderResponse.paymentFailed(authorization.error);
            }
            
            try {
                // Step 6: Persist
                await this.repository.save(order);
                
                // Step 7: Notify (async, best-effort)
                this.notifications.sendConfirmation(order).catch(this.logError);
                
                // Step 8: Publish event
                await this.events.publish(new OrderPlacedEvent(order));
                
                // Step 9: Success
                return PlaceOrderResponse.success(order);
                
            } catch (error) {
                // Rollback payment
                await this.payment.void(authorization.id);
                throw error;
            }
            
        } catch (error) {
            // Rollback inventory
            await this.inventory.release(reservation.id);
            throw error;
        }
    }
}