Domain Services in Domain-Driven Design

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

// ✅ STATELESS Domain Service
class TaxCalculationService {
    // No instance fields storing state
    
    constructor(
        private readonly taxRateRepository: TaxRateRepository,  // Dependency, not state
        private readonly taxRuleEngine: TaxRuleEngine           // Dependency, not state
    ) {}
    
    calculateTax(order: Order, customer: Customer): TaxResult {
        // All inputs come from parameters or dependencies
        // No instance state is read or modified
        
        const rates = this.taxRateRepository.getRatesFor(customer.jurisdiction);
        const rules = this.taxRuleEngine.getRulesFor(order.productCategories);
        
        return this.computeTax(order.lineItems, rates, rules);
    }
    
    private computeTax(items: OrderItem[], rates: TaxRate[], rules: TaxRule[]): TaxResult {
        // Pure calculation - same inputs always produce same outputs
    }
}
 
// ❌ STATEFUL Service - NOT a proper Domain Service
class StatefulCalculator {
    private lastCalculation: TaxResult;  // ❌ Instance state
    private calculationCount: number = 0; // ❌ Instance state
    
    calculateTax(order: Order, customer: Customer): TaxResult {
        this.calculationCount++;  // ❌ Modifying state
        this.lastCalculation = /* ... */;  // ❌ Storing state
        return this.lastCalculation;
    }
    
    getLastCalculation(): TaxResult {  // ❌ State-dependent method
        return this.lastCalculation;
    }
}

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

// Operation-centric Domain Service interface
// Note: Named after the OPERATION (verb), not the data (noun)
 
interface FundsTransferService {
    // Primary operation - the reason this service exists
    transfer(
        source: AccountId,
        destination: AccountId,
        amount: Money,
        reference: TransferReference
    ): TransferResult;
}
 
interface OrderMatchingService {
    // Primary operation
    matchOrder(
        incomingOrder: Order,
        orderBook: OrderBook
    ): MatchingResult;
}
 
interface ShippingCostCalculator {
    // Primary operation  
    calculateShippingCost(
        package_: Package,
        origin: Address,
        destination: Address,
        options: ShippingOptions
    ): ShippingQuote;
}
 
// Contrast with data-centric (anti-pattern) naming:
// ❌ AccountService - what operations? too vague
// ❌ OrderManager - generic, not domain-specific
// ❌ ShippingHelper - 'helper' is a code smell

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

// Domain Layer (domain/services/funds-transfer-service.ts)
// ============================================
// Interface is IN the domain layer
 
export interface FundsTransferService {
    /**
     * Transfers funds between accounts, applying all business rules
     * for transfer limits, overdraft protection, and compliance.
     */
    transfer(
        source: AccountId,
        destination: AccountId,
        amount: Money,
        reference: TransferReference
    ): TransferResult;
}
 
// Domain types used - no infrastructure leakage
export interface TransferResult {
    readonly transferId: TransferId;
    readonly status: TransferStatus;
    readonly executedAt: Timestamp;
    readonly fees: Money;
}
 
export type TransferStatus = 
    | 'COMPLETED'
    | 'PENDING_APPROVAL'
    | 'REJECTED'
    | 'REQUIRES_VERIFICATION';
 
// Infrastructure/Application Layer (infrastructure/services/...)
// ============================================
// Implementation MAY live outside domain layer
 
import { FundsTransferService, TransferResult } from '@domain/services';
 
export class FundsTransferServiceImpl implements FundsTransferService {
    constructor(
        private accountRepository: AccountRepository,
        private transferRulesEngine: TransferRulesEngine,
        private eventPublisher: DomainEventPublisher
    ) {}
    
    transfer(
        source: AccountId,
        destination: AccountId,
        amount: Money,
        reference: TransferReference
    ): TransferResult {
        // Implementation details...
        // May use infrastructure concerns internally
    }
}

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

// ❌ POOR: Technical/generic language
interface GenericService {
    process(data: ProcessData): ProcessResult;
    validate(input: string): boolean;
    updateStatus(id: number, status: number): void;
}
 
// ✅ GOOD: Ubiquitous Language from insurance domain
interface ClaimAdjudicationService {
    /**
     * Adjudicates a submitted insurance claim, applying coverage rules
     * and determining the payout.
     * 
     * @param claim - The submitted claim to adjudicate
     * @param policy - The policy under which the claim is made
     * @returns Adjudication decision including payout determination
     */
    adjudicateClaim(
        claim: InsuranceClaim,
        policy: InsurancePolicy
    ): AdjudicationDecision;
}
 
interface AdjudicationDecision {
    readonly claimId: ClaimId;
    readonly verdict: ClaimVerdict;       // 'APPROVED' | 'DENIED' | 'PENDING_REVIEW'
    readonly approvedAmount: Money | null;
    readonly denialReasons: DenialReason[];
    readonly requiredDocuments: DocumentType[];
    readonly adjudicatedBy: AdjudicatorId;
    readonly adjudicatedAt: Timestamp;
}
 
// Domain experts immediately recognize:
// - "Adjudication" is their term for claim evaluation
// - "Verdict" is how they describe decisions
// - "Denial Reasons" are a regulatory requirement
// - The process captures real business workflow

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

/**
 * Complete Domain Service Example: Trade Matching
 * 
 * ✅ Domain Concept: "Order matching" is how traders describe the core market mechanism
 * ✅ Stateless: No instance state, just operations
 * ✅ Operation-Centric: Named for what it does (matching), not what it is
 * ✅ Interface in Domain: Lives in domain/services/
 * ✅ Ubiquitous Language: Order, Trade, Fill, Match - all trader terminology
 */
 
// File: domain/services/order-matching-service.ts
 
export interface OrderMatchingService {
    /**
     * Matches an incoming order against resting orders in the book.
     * Uses price-time priority for matching determination.
     * 
     * @param incomingOrder - The new order to match
     * @param orderBook - Current state of resting orders
     * @returns Matching results including any trades executed
     */
    matchOrder(incomingOrder: Order, orderBook: OrderBook): MatchingResult;
    
    /**
     * Attempts to cross orders within the same participant (internal crossing).
     * Must apply fair pricing rules for internal matches.
     */
    attemptInternalCross(
        buyOrder: Order,
        sellOrder: Order,
        crossingRules: CrossingRules
    ): CrossResult;
}
 
export interface MatchingResult {
    readonly incomingOrderId: OrderId;
    readonly trades: Trade[];
    readonly fills: Fill[];
    readonly remainingQuantity: Quantity;
    readonly matchingType: 'FULL' | 'PARTIAL' | 'NONE';
}
 
export interface Trade {
    readonly tradeId: TradeId;
    readonly buyOrderId: OrderId;
    readonly sellOrderId: OrderId;
    readonly quantity: Quantity;
    readonly price: Price;
    readonly executedAt: Timestamp;
}
 
export interface Fill {
    readonly orderId: OrderId;
    readonly filledQuantity: Quantity;
    readonly averagePrice: Price;
}