Low-Level DesignEntities

Entities in Domain-Driven Design

LevelIntermediate

Duration60 mins

TopicEntities

4 / 4

Entity Lifecycle

The Living Entity

Entities are not static data structures—they're living objects with lifespans. A customer is born when they register, evolves as they update their profile and accumulate orders, and may eventually be deactivated or deleted. An order is created when placed, passes through payment and shipping, and either completes successfully or gets cancelled.

This lifecycle matters because different operations are valid at different stages. You can't ship an unpaid order. You can't modify a delivered order. You can't reactivate a permanently deleted account.

Understanding and managing entity lifecycle is essential for building systems that correctly model real-world processes. It's the bridge between the static structure of entities and the dynamic reality of business operations.

What You Will Learn

By the end of this page, you'll understand the complete entity lifecycle including creation, state transitions, persistence considerations, soft vs hard deletion, event sourcing basics, and temporal modeling. You'll be able to design entities that correctly reflect how domain objects evolve over time.

Entity Lifecycle Phases

Every entity passes through distinct lifecycle phases. Understanding these phases helps you design appropriate operations for each stage:

Entity Lifecycle Phases
Phase	Description	Key Characteristics	Common Operations
Transient	Entity created but not yet persisted	In-memory only, no persistence identity assigned by DB (if using sequences), fully mutable	Validation, setting initial state, preparing for first save
Persistent (New)	Just persisted for the first time	Has persistence identity, tracked by ORM, initial state recorded	First save, establishing relationships
Persistent (Managed)	Loaded from storage, actively managed	Changes tracked, can be modified, will be synchronized with storage	Business operations, state transitions, updates
Detached	Loaded previously, no longer managed by ORM session	Has identity, but changes aren't tracked automatically	Transfer between layers, serialization
Removed	Marked for deletion, pending commit	Still exists in memory, will be deleted on transaction commit	Cleanup operations, cascade handling
Archived/Soft-Deleted	Logically removed but data preserved	Hidden from normal queries, retrievable for audit/history	Audit trails, data retention compliance

Phase transitions in practice:

Lifecycle Phase Transitions
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
// Entity lifecycle demonstration
 
// 1. TRANSIENT: Created in memory
const order = Order.create(customerId, shippingAddress);
// order exists in memory, not in database
// Has application-generated ID (if using UUIDs)
 
// 2. PERSISTENT (NEW): First save
await orderRepository.save(order);
// order now exists in storage
// Changes from this point are tracked
 
// 3. PERSISTENT (MANAGED): Normal operations
order.addLine(product, quantity);
order.confirmPayment(transactionId);
await orderRepository.save(order);
// Changes are flushed to storage
 
// 4. DETACHED: Sent to another layer
const orderDTO = orderMapper.toDTO(order);
// orderDTO is just data, no longer tracked
// Modifications to orderDTO don't affect database
 
// 5. RE-ATTACHED: Loaded back for more work
const managedOrder = await orderRepository.findById(orderId);
managedOrder.ship(trackingNumber);
await orderRepository.save(managedOrder);
// Back in managed state, changes tracked
 
// 6. REMOVED: Deletion
await orderRepository.delete(managedOrder);
// Entity marked for removal, deleted on commit

ORM-Specific Details

The exact semantics of transient/managed/detached depend on your ORM (Hibernate, EF Core, Prisma, etc.). Pure DDD focuses on domain phases (created, active, archived), while ORM lifecycle phases (transient, managed, detached) are technical implementation details. Don't conflate them.

Entity Creation Patterns

Entity creation is a significant domain event. It's not just object construction—it's the birth of a domain concept. Several patterns help manage this effectively:

Creation Patterns

•Factory Methods on Entity: Order.create(customerId, address) — Simple, works well for straightforward creation.
•Dedicated Factory Class: OrderFactory.createStandardOrder(...) — Useful when creation logic is complex or needs dependencies.
•Builder Pattern: Order.builder().customerId(...).address(...).build() — Useful for entities with many optional parameters.
•Domain Service: OrderingService.placeOrder(...) — When creation involves multiple aggregates or external validation.

Creation Pattern Examples
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
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
// PATTERN 1: Factory Method on Entity
// Best for simple, self-contained creation
 
class Order {
    static create(
        customerId: CustomerId,
        shippingAddress: Address
    ): Order {
        const order = new Order(
            OrderId.generate(),
            customerId,
            shippingAddress
        );
        
        order.raise(new OrderCreated(order.id));
        return order;
    }
}
 
// Usage
const order = Order.create(customerId, address);
 
 
// PATTERN 2: Factory Class
// Best when creation needs external dependencies
 
class OrderFactory {
    constructor(
        private readonly pricingService: PricingService,
        private readonly inventoryChecker: InventoryChecker,
        private readonly taxCalculator: TaxCalculator
    ) {}
    
    async createOrder(
        customerId: CustomerId,
        items: OrderItemRequest[],
        shippingAddress: Address
    ): Promise<Order> {
        // Validate inventory availability
        await this.inventoryChecker.ensureAvailable(items);
        
        // Get current pricing
        const pricedItems = await this.pricingService
            .getPricing(items);
        
        // Calculate tax
        const tax = await this.taxCalculator
            .calculate(pricedItems, shippingAddress);
        
        // Create the order with all computed values
        const order = Order.createWithPricing(
            OrderId.generate(),
            customerId,
            shippingAddress,
            pricedItems,
            tax
        );
        
        order.raise(new OrderCreated(order.id, order.total));
        return order;
    }
}
 
 
// PATTERN 3: Builder Pattern
// Best for many optional parameters
 
class CustomerBuilder {
    private id: CustomerId = CustomerId.generate();
    private email?: Email;
    private name?: string;
    private address?: Address;
    private tier: CustomerTier = CustomerTier.STANDARD;
    
    withEmail(email: Email): this {
        this.email = email;
        return this;
    }
    
    withName(name: string): this {
        this.name = name;
        return this;
    }
    
    withAddress(address: Address): this {
        this.address = address;
        return this;
    }
    
    withTier(tier: CustomerTier): this {
        this.tier = tier;
        return this;
    }
    
    build(): Customer {
        // Validate required fields
        if (!this.email) {
            throw new ValidationError("Email is required");
        }
        if (!this.name) {
            throw new ValidationError("Name is required");
        }
        
        return new Customer(
            this.id,
            this.email,
            this.name,
            this.address ?? Address.empty(),
            this.tier
        );
    }
}
 
// Usage
const customer = new CustomerBuilder()
    .withEmail(new Email("alice@example.com"))
    .withName("Alice Smith")
    .withTier(CustomerTier.PREMIUM)
    .build();

Creation Events

Entity creation is often a significant business event. Consider raising domain events like OrderCreated, CustomerRegistered, AccountOpened. These events can trigger welcome emails, audit logging, or downstream workflows.

Managing State Transitions

After creation, entities evolve through state transitions. Managing these transitions correctly is crucial for maintaining consistency and expressing business rules.

State transition principles:

•Validate before transitioning: Check all preconditions. If any fail, reject the transition with a clear error.
•Transitions should be atomic: Either the whole transition succeeds or none of it happens. No partial state.
•Use domain events for side effects: The transition itself changes state. Events trigger reactions (notifications, downstream updates).
•Log significant transitions: For audit trails, record when, who, and why for important state changes.
•Consider reversibility: Can this transition be undone? If yes, implement the reverse transition. If no, make that explicit.

State Transition Implementation
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
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
class Order {
    private _status: OrderStatus;
    private _events: DomainEvent[] = [];
    private _history: StateChange[] = [];
    
    // Transition with full validation and event raising
    confirmPayment(
        transactionId: PaymentTransactionId,
        paidBy: UserId,
        timestamp: Date = new Date()
    ): void {
        // 1. VALIDATE PRECONDITIONS
        this.assertStatus(OrderStatus.PENDING_PAYMENT);
        this.assertHasItems();
        
        // 2. CAPTURE PREVIOUS STATE (for history/audit)
        const previousStatus = this._status;
        
        // 3. MAKE THE TRANSITION
        this._status = OrderStatus.PAID;
        this._paymentTransactionId = transactionId;
        this._paidAt = timestamp;
        
        // 4. RECORD HISTORY (for audit trail)
        this._history.push({
            from: previousStatus,
            to: OrderStatus.PAID,
            timestamp,
            actor: paidBy,
            reason: `Payment confirmed: ${transactionId}`
        });
        
        // 5. RAISE DOMAIN EVENT
        this.raise(new OrderPaid({
            orderId: this._id,
            transactionId,
            amount: this._total,
            paidAt: timestamp
        }));
    }
    
    // Transition that may fail
    tryShip(
        trackingNumber: TrackingNumber,
        shippedBy: UserId
    ): Result<void, ShipmentError> {
        // Some transitions might fail for business reasons
        // beyond simple precondition checks
        
        if (this._status !== OrderStatus.PAID) {
            return Result.failure(
                new ShipmentError.NotPaid(this._id)
            );
        }
        
        if (this._items.some(i => !i.isInStock)) {
            return Result.failure(
                new ShipmentError.ItemsNotInStock(
                    this._items.filter(i => !i.isInStock)
                )
            );
        }
        
        // Perform the transition
        this._status = OrderStatus.SHIPPED;
        this._trackingNumber = trackingNumber;
        this._shippedAt = new Date();
        
        this.raise(new OrderShipped({
            orderId: this._id,
            trackingNumber,
            shippedAt: this._shippedAt
        }));
        
        return Result.success(undefined);
    }
    
    // Helper for status validation
    private assertStatus(expected: OrderStatus): void {
        if (this._status !== expected) {
            throw new InvalidOrderStateError({
                orderId: this._id,
                currentStatus: this._status,
                expectedStatus: expected,
                operation: new Error().stack?.split('\n')[2] ?? 'unknown'
            });
        }
    }
    
    private assertHasItems(): void {
        if (this._items.length === 0) {
            throw new OrderHasNoItemsError(this._id);
        }
    }
    
    // For event handling
    private raise(event: DomainEvent): void {
        this._events.push(event);
    }
    
    // Repository calls this after save
    clearEvents(): DomainEvent[] {
        const events = [...this._events];
        this._events = [];
        return events;
    }
}
 
// StateChange interface for audit trail
interface StateChange {
    from: OrderStatus;
    to: OrderStatus;
    timestamp: Date;
    actor: UserId;
    reason: string;
}

Saga Pattern for Complex Transitions

When a transition spans multiple aggregates or services (e.g., order payment affects inventory, loyalty points, and shipping), use the Saga pattern. The entity transition is one step in a larger choreographed or orchestrated process.

Persistence and Identity Lifecycle

Entities must be persisted to survive beyond the current process. The relationship between entity identity and persistence identity requires careful consideration:

Identity Generation Strategies
Strategy	When Identity Assigned	Pros	Cons
Application UUID	Before persistence	Entity always has identity; works distributed; simple code	UUIDs larger than integers; less readable
Database Sequence	After INSERT	Compact IDs; readable (Order #1234)	Entity lacks identity until saved; requires DB roundtrip
Hi-Lo Algorithm	Application reserves range from DB	Compact IDs; batch-friendly; fewer roundtrips	Complex configuration; gaps in sequences
Natural Key	Inherent in data (SSN, email)	Meaningful IDs; matches business language	Can change; uniqueness issues; privacy concerns
Composite Key	Combination of fields	Natural for relationship entities	Complex equality; harder to reference

Persistence Identity Patterns
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
// PATTERN 1: Application-generated UUID (Recommended)
 
class OrderRepository {
    async save(order: Order): Promise<void> {
        // Order already has ID - simple upsert logic
        const exists = await this.db.order.findUnique({
            where: { id: order.id.value }
        });
        
        if (exists) {
            await this.db.order.update({
                where: { id: order.id.value },
                data: this.toPersistence(order)
            });
        } else {
            await this.db.order.create({
                data: this.toPersistence(order)
            });
        }
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        const row = await this.db.order.findUnique({
            where: { id: id.value },
            include: { lines: true }
        });
        
        if (!row) return null;
        return this.toDomain(row);
    }
}
 
 
// PATTERN 2: Database-generated IDs (Legacy/Special Cases)
 
interface TransientOrder {
    // No ID field - not yet persisted
    customerId: CustomerId;
    items: OrderItem[];
    shippingAddress: Address;
}
 
interface PersistedOrder extends TransientOrder {
    id: OrderId;  // Has ID after persistence
}
 
class LegacyOrderRepository {
    async create(order: TransientOrder): Promise<PersistedOrder> {
        // Database generates ID
        const row = await this.db.order.create({
            data: {
                // id is auto-generated
                customerId: order.customerId.value,
                shippingAddress: JSON.stringify(order.shippingAddress)
            }
        });
        
        // Now we have the ID
        return {
            ...order,
            id: OrderId.of(row.id.toString())
        };
    }
}
 
// Note: This pattern is more complex because the entity
// must handle having or not having an ID. Avoid if possible.

UUIDs vs Sequential IDs

UUIDs simplify code significantly and work in distributed systems. If you need human-readable identifiers (Order #1234), use a separate display ID that's generated from a sequence. Internal identity can still be a UUID.

Deletion Strategies: Soft vs Hard Delete

How do entities end their lifecycle? The choice between soft and hard deletion has significant implications for data integrity, compliance, and system behavior.

Soft Delete

•Set a deletedAt or isDeleted flag
•Data remains in database
•Can be restored if needed
•Audit trail preserved
•Referential integrity maintained
•Requires filtering in all queries
•Storage grows over time

Hard Delete

•Row removed from database
•Data permanently gone
•Cannot be restored (without backups)
•No audit trail (unless logged separately)
•May break referential integrity
•Simpler queries
•Storage reclaimed

Deletion Implementation
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
78
79
80
81
82
83
84
85
86
87
88
89
// SOFT DELETE IMPLEMENTATION
 
class Customer {
    private _id: CustomerId;
    private _status: CustomerStatus;
    private _deletedAt: Date | null = null;
    private _deletionReason: string | null = null;
    
    // Soft delete method
    deactivate(reason: string, deletedBy: UserId): void {
        if (this._status === CustomerStatus.DELETED) {
            throw new CustomerAlreadyDeletedError(this._id);
        }
        
        this._status = CustomerStatus.DELETED;
        this._deletedAt = new Date();
        this._deletionReason = reason;
        
        this.raise(new CustomerDeactivated({
            customerId: this._id,
            reason,
            deletedBy,
            deletedAt: this._deletedAt
        }));
    }
    
    // Restore method (undo soft delete)
    reactivate(reactivatedBy: UserId): void {
        if (this._status !== CustomerStatus.DELETED) {
            throw new CustomerNotDeletedError(this._id);
        }
        
        this._status = CustomerStatus.ACTIVE;
        this._deletedAt = null;
        this._deletionReason = null;
        
        this.raise(new CustomerReactivated({
            customerId: this._id,
            reactivatedBy,
            reactivatedAt: new Date()
        }));
    }
    
    get isDeleted(): boolean {
        return this._status === CustomerStatus.DELETED;
    }
}
 
// Repository handles filtering
class CustomerRepository {
    // Default: only active customers
    async findById(id: CustomerId): Promise<Customer | null> {
        const row = await this.db.customer.findFirst({
            where: {
                id: id.value,
                status: { not: 'DELETED' }  // Filter soft-deleted
            }
        });
        return row ? this.toDomain(row) : null;
    }
    
    // Explicit: include deleted (for admin/audit)
    async findByIdIncludingDeleted(
        id: CustomerId
    ): Promise<Customer | null> {
        const row = await this.db.customer.findUnique({
            where: { id: id.value }
        });
        return row ? this.toDomain(row) : null;
    }
    
    // Soft delete
    async softDelete(customer: Customer): Promise<void> {
        await this.db.customer.update({
            where: { id: customer.id.value },
            data: {
                status: 'DELETED',
                deletedAt: new Date()
            }
        });
    }
    
    // Hard delete (use with caution)
    async hardDelete(id: CustomerId): Promise<void> {
        await this.db.customer.delete({
            where: { id: id.value }
        });
    }
}

When to Use Each Deletion Strategy
Use Soft Delete When	Use Hard Delete When
Data retention is legally required (GDPR data portability)	Data must be permanently removed (GDPR right to erasure)
Entity is referenced by other entities	Self-contained data with no references
Undo/restore functionality is needed	No restoration requirement
Audit trail must be preserved	Audit logged separately
Historical reporting needed	No historical requirements
Accidental deletion is a concern	Deletion is a final, deliberate action

GDPR Considerations

GDPR requires both data portability (keeping data) and right to erasure (deleting data). You may need soft delete for some data and hard delete capabilities for others. Personal data especially may require true deletion. Consult legal and compliance teams.

Temporal Modeling and History

Sometimes knowing the current state isn't enough—you need to know what the state was at any point in time. This is temporal modeling, and it's essential for auditing, compliance, and business intelligence.

Temporal Modeling Patterns

•Audit Log: Separate table records each change. Entity stores current state only.
•Temporal Table: Database maintains history automatically (SQL Server, PostgreSQL).
•Event Sourcing: Store events, derive state. Full history is the primary storage.
•Snapshot + Events: Periodic snapshots plus recent events. Balance between history and performance.
•Versioned Entities: Each "save" creates a new version. All versions retrievable.

Temporal Modeling
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
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
// PATTERN: Audit Log (Most Common)
 
interface AuditEntry {
    id: string;
    entityType: string;
    entityId: string;
    action: 'CREATE' | 'UPDATE' | 'DELETE';
    timestamp: Date;
    userId: string;
    previousState: Record<string, any> | null;
    newState: Record<string, any>;
    changedFields: string[];
}
 
class AuditingRepository<T extends Entity> {
    constructor(
        private readonly innerRepository: Repository<T>,
        private readonly auditLog: AuditLogService
    ) {}
    
    async save(entity: T, userId: UserId): Promise<void> {
        const existing = await this.innerRepository.findById(entity.id);
        
        const action = existing ? 'UPDATE' : 'CREATE';
        const previousState = existing 
            ? this.toSnapshot(existing) 
            : null;
        const newState = this.toSnapshot(entity);
        
        // Save entity
        await this.innerRepository.save(entity);
        
        // Record audit
        await this.auditLog.record({
            id: crypto.randomUUID(),
            entityType: entity.constructor.name,
            entityId: entity.id.toString(),
            action,
            timestamp: new Date(),
            userId: userId.value,
            previousState,
            newState,
            changedFields: this.detectChanges(previousState, newState)
        });
    }
}
 
 
// PATTERN: Event Sourcing (Advanced)
 
interface DomainEvent {
    eventId: string;
    aggregateId: string;
    eventType: string;
    timestamp: Date;
    data: Record<string, any>;
    version: number;
}
 
class OrderEventSourced {
    private _id: OrderId;
    private _version: number = 0;
    private _status: OrderStatus;
    private _uncommittedEvents: DomainEvent[] = [];
    
    // Commands cause events
    confirmPayment(transactionId: string): void {
        this.applyEvent({
            eventType: 'OrderPaid',
            data: { transactionId, paidAt: new Date() }
        });
    }
    
    // Events change state
    private applyEvent(event: Omit<DomainEvent, 'eventId' | 'aggregateId' | 'timestamp' | 'version'>): void {
        const fullEvent: DomainEvent = {
            ...event,
            eventId: crypto.randomUUID(),
            aggregateId: this._id.value,
            timestamp: new Date(),
            version: this._version + 1
        };
        
        this.mutate(fullEvent);
        this._uncommittedEvents.push(fullEvent);
    }
    
    private mutate(event: DomainEvent): void {
        switch (event.eventType) {
            case 'OrderPaid':
                this._status = OrderStatus.PAID;
                break;
            case 'OrderShipped':
                this._status = OrderStatus.SHIPPED;
                break;
            // ... other events
        }
        this._version = event.version;
    }
    
    // Reconstitute from event history
    static fromHistory(events: DomainEvent[]): OrderEventSourced {
        const order = new OrderEventSourced();
        for (const event of events) {
            order.mutate(event);
        }
        return order;
    }
}
 
// Event-sourced repository
class EventSourcedOrderRepository {
    async save(order: OrderEventSourced): Promise<void> {
        const events = order.getUncommittedEvents();
        
        // Append events to event store
        await this.eventStore.append(
            order.id.value,
            events,
            order.version - events.length  // Expected version
        );
        
        order.markEventsAsCommitted();
    }
    
    async findById(id: OrderId): Promise<OrderEventSourced | null> {
        const events = await this.eventStore.getEvents(id.value);
        if (events.length === 0) return null;
        return OrderEventSourced.fromHistory(events);
    }
    
    // Time travel: get state at any point
    async findAtTime(id: OrderId, asOf: Date): Promise<OrderEventSourced | null> {
        const events = await this.eventStore.getEvents(
            id.value,
            { until: asOf }
        );
        if (events.length === 0) return null;
        return OrderEventSourced.fromHistory(events);
    }
}

Event Sourcing Trade-offs

Event sourcing provides complete history and powerful audit capabilities, but increases complexity. Querying current state requires replaying events (mitigated by projections). Use it when history is a first-class requirement, not just an afterthought.

Lifecycle Events and Integration

Entity lifecycle transitions often need to trigger reactions: send notifications, update read models, sync with external systems. Domain events are the clean way to handle this.

Lifecycle Event Handling
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
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
// Domain Events for Lifecycle Transitions
 
abstract class DomainEvent {
    readonly occurredAt: Date = new Date();
    abstract readonly eventType: string;
}
 
class CustomerRegistered extends DomainEvent {
    readonly eventType = 'CustomerRegistered';
    
    constructor(
        readonly customerId: CustomerId,
        readonly email: Email,
        readonly name: string
    ) { super(); }
}
 
class CustomerDeactivated extends DomainEvent {
    readonly eventType = 'CustomerDeactivated';
    
    constructor(
        readonly customerId: CustomerId,
        readonly reason: string,
        readonly deactivatedBy: UserId
    ) { super(); }
}
 
// Entity raises events
class Customer {
    private _domainEvents: DomainEvent[] = [];
    
    static register(email: Email, name: string): Customer {
        const customer = new Customer(
            CustomerId.generate(),
            email,
            name
        );
        
        // Raise lifecycle event
        customer.addEvent(new CustomerRegistered(
            customer.id,
            email,
            name
        ));
        
        return customer;
    }
    
    deactivate(reason: string, by: UserId): void {
        this._status = CustomerStatus.DEACTIVATED;
        
        this.addEvent(new CustomerDeactivated(
            this._id,
            reason,
            by
        ));
    }
    
    private addEvent(event: DomainEvent): void {
        this._domainEvents.push(event);
    }
    
    popEvents(): DomainEvent[] {
        const events = [...this._domainEvents];
        this._domainEvents = [];
        return events;
    }
}
 
// Event Handlers React to Lifecycle Events
 
class CustomerRegisteredHandler {
    constructor(
        private readonly emailService: EmailService,
        private readonly analyticsService: AnalyticsService
    ) {}
    
    async handle(event: CustomerRegistered): Promise<void> {
        // Send welcome email
        await this.emailService.sendWelcome(
            event.email,
            event.name
        );
        
        // Track in analytics
        await this.analyticsService.track({
            event: 'customer_registered',
            customerId: event.customerId.value,
            timestamp: event.occurredAt
        });
    }
}
 
class CustomerDeactivatedHandler {
    constructor(
        private readonly subscriptionService: SubscriptionService,
        private readonly notificationService: NotificationService
    ) {}
    
    async handle(event: CustomerDeactivated): Promise<void> {
        // Cancel subscriptions
        await this.subscriptionService.cancelAll(
            event.customerId
        );
        
        // Notify admin
        await this.notificationService.notifyAdmins({
            type: 'customer_deactivated',
            customerId: event.customerId.value,
            reason: event.reason,
            timestamp: event.occurredAt
        });
    }
}
 
// Dispatcher (in Application/Infrastructure layer)
class DomainEventDispatcher {
    private handlers = new Map<string, EventHandler[]>();
    
    register(eventType: string, handler: EventHandler): void {
        const handlers = this.handlers.get(eventType) ?? [];
        handlers.push(handler);
        this.handlers.set(eventType, handlers);
    }
    
    async dispatch(event: DomainEvent): Promise<void> {
        const handlers = this.handlers.get(event.eventType) ?? [];
        await Promise.all(
            handlers.map(h => h.handle(event))
        );
    }
}

Event Dispatch Timing

Dispatch domain events after the transaction commits successfully. If you dispatch before commit and the transaction rolls back, you've sent events for changes that didn't persist. Many frameworks provide hooks for post-commit event dispatch.

Summary: Entity Lifecycle Mastery

We've comprehensively covered the entity lifecycle from creation through archival. Let's consolidate the key insights:

Key Takeaways

•Entities have distinct lifecycle phases: Transient, persisted, detached, removed. Operations valid in one phase may not be in another.
•Creation is a domain event: Use factory methods, validate invariants, raise creation events. Separate create() from reconstitute().
•State transitions must be guarded: Validate preconditions, make transitions atomic, raise domain events for side effects.
•Identity should exist before persistence: Prefer application-generated UUIDs. Avoid complications of database-assigned IDs.
•Choose deletion strategy deliberately: Soft delete for audit/restore; hard delete for true removal. Consider compliance requirements.
•Temporal modeling enables time-travel: Audit logs, temporal tables, or event sourcing provide history when needed.
•Domain events integrate lifecycle with the world: Transitions raise events; handlers trigger notifications, sync, and downstream processes.

Module complete:

You've now mastered entities in Domain-Driven Design. You understand:

What entities are and why they exist
How identity differs from equality
Guidelines for designing robust entities
How to manage the complete entity lifecycle

This foundation prepares you for the next DDD building block: Value Objects, which complement entities by representing concepts defined by their attributes rather than identity.

Module Complete

Congratulations! You've completed the Entities module. You now have a comprehensive understanding of how to model, design, and manage entities in Domain-Driven Design. You're ready to continue your DDD journey with Value Objects and Aggregates.

4 / 4

Loading learning content...

Low-Level DesignEntities

Entities in Domain-Driven Design

LevelIntermediate

Duration60 mins

TopicEntities

4 / 4

Entity Lifecycle

The Living Entity

What You Will Learn

Entity Lifecycle Phases

Every entity passes through distinct lifecycle phases. Understanding these phases helps you design appropriate operations for each stage:

Entity Lifecycle Phases
Phase	Description	Key Characteristics	Common Operations
Transient	Entity created but not yet persisted	In-memory only, no persistence identity assigned by DB (if using sequences), fully mutable	Validation, setting initial state, preparing for first save
Persistent (New)	Just persisted for the first time	Has persistence identity, tracked by ORM, initial state recorded	First save, establishing relationships
Persistent (Managed)	Loaded from storage, actively managed	Changes tracked, can be modified, will be synchronized with storage	Business operations, state transitions, updates
Detached	Loaded previously, no longer managed by ORM session	Has identity, but changes aren't tracked automatically	Transfer between layers, serialization
Removed	Marked for deletion, pending commit	Still exists in memory, will be deleted on transaction commit	Cleanup operations, cascade handling
Archived/Soft-Deleted	Logically removed but data preserved	Hidden from normal queries, retrievable for audit/history	Audit trails, data retention compliance

Phase transitions in practice:

Lifecycle Phase Transitions
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
// Entity lifecycle demonstration
 
// 1. TRANSIENT: Created in memory
const order = Order.create(customerId, shippingAddress);
// order exists in memory, not in database
// Has application-generated ID (if using UUIDs)
 
// 2. PERSISTENT (NEW): First save
await orderRepository.save(order);
// order now exists in storage
// Changes from this point are tracked
 
// 3. PERSISTENT (MANAGED): Normal operations
order.addLine(product, quantity);
order.confirmPayment(transactionId);
await orderRepository.save(order);
// Changes are flushed to storage
 
// 4. DETACHED: Sent to another layer
const orderDTO = orderMapper.toDTO(order);
// orderDTO is just data, no longer tracked
// Modifications to orderDTO don't affect database
 
// 5. RE-ATTACHED: Loaded back for more work
const managedOrder = await orderRepository.findById(orderId);
managedOrder.ship(trackingNumber);
await orderRepository.save(managedOrder);
// Back in managed state, changes tracked
 
// 6. REMOVED: Deletion
await orderRepository.delete(managedOrder);
// Entity marked for removal, deleted on commit

ORM-Specific Details

Entity Creation Patterns

Entity creation is a significant domain event. It's not just object construction—it's the birth of a domain concept. Several patterns help manage this effectively:

Creation Patterns

•Factory Methods on Entity: Order.create(customerId, address) — Simple, works well for straightforward creation.
•Dedicated Factory Class: OrderFactory.createStandardOrder(...) — Useful when creation logic is complex or needs dependencies.
•Builder Pattern: Order.builder().customerId(...).address(...).build() — Useful for entities with many optional parameters.
•Domain Service: OrderingService.placeOrder(...) — When creation involves multiple aggregates or external validation.

Creation Pattern Examples
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
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
// PATTERN 1: Factory Method on Entity
// Best for simple, self-contained creation
 
class Order {
    static create(
        customerId: CustomerId,
        shippingAddress: Address
    ): Order {
        const order = new Order(
            OrderId.generate(),
            customerId,
            shippingAddress
        );
        
        order.raise(new OrderCreated(order.id));
        return order;
    }
}
 
// Usage
const order = Order.create(customerId, address);
 
 
// PATTERN 2: Factory Class
// Best when creation needs external dependencies
 
class OrderFactory {
    constructor(
        private readonly pricingService: PricingService,
        private readonly inventoryChecker: InventoryChecker,
        private readonly taxCalculator: TaxCalculator
    ) {}
    
    async createOrder(
        customerId: CustomerId,
        items: OrderItemRequest[],
        shippingAddress: Address
    ): Promise<Order> {
        // Validate inventory availability
        await this.inventoryChecker.ensureAvailable(items);
        
        // Get current pricing
        const pricedItems = await this.pricingService
            .getPricing(items);
        
        // Calculate tax
        const tax = await this.taxCalculator
            .calculate(pricedItems, shippingAddress);
        
        // Create the order with all computed values
        const order = Order.createWithPricing(
            OrderId.generate(),
            customerId,
            shippingAddress,
            pricedItems,
            tax
        );
        
        order.raise(new OrderCreated(order.id, order.total));
        return order;
    }
}
 
 
// PATTERN 3: Builder Pattern
// Best for many optional parameters
 
class CustomerBuilder {
    private id: CustomerId = CustomerId.generate();
    private email?: Email;
    private name?: string;
    private address?: Address;
    private tier: CustomerTier = CustomerTier.STANDARD;
    
    withEmail(email: Email): this {
        this.email = email;
        return this;
    }
    
    withName(name: string): this {
        this.name = name;
        return this;
    }
    
    withAddress(address: Address): this {
        this.address = address;
        return this;
    }
    
    withTier(tier: CustomerTier): this {
        this.tier = tier;
        return this;
    }
    
    build(): Customer {
        // Validate required fields
        if (!this.email) {
            throw new ValidationError("Email is required");
        }
        if (!this.name) {
            throw new ValidationError("Name is required");
        }
        
        return new Customer(
            this.id,
            this.email,
            this.name,
            this.address ?? Address.empty(),
            this.tier
        );
    }
}
 
// Usage
const customer = new CustomerBuilder()
    .withEmail(new Email("alice@example.com"))
    .withName("Alice Smith")
    .withTier(CustomerTier.PREMIUM)
    .build();

Creation Events

Managing State Transitions

After creation, entities evolve through state transitions. Managing these transitions correctly is crucial for maintaining consistency and expressing business rules.

State transition principles:

•Validate before transitioning: Check all preconditions. If any fail, reject the transition with a clear error.
•Transitions should be atomic: Either the whole transition succeeds or none of it happens. No partial state.
•Use domain events for side effects: The transition itself changes state. Events trigger reactions (notifications, downstream updates).
•Log significant transitions: For audit trails, record when, who, and why for important state changes.
•Consider reversibility: Can this transition be undone? If yes, implement the reverse transition. If no, make that explicit.

State Transition Implementation
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
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
class Order {
    private _status: OrderStatus;
    private _events: DomainEvent[] = [];
    private _history: StateChange[] = [];
    
    // Transition with full validation and event raising
    confirmPayment(
        transactionId: PaymentTransactionId,
        paidBy: UserId,
        timestamp: Date = new Date()
    ): void {
        // 1. VALIDATE PRECONDITIONS
        this.assertStatus(OrderStatus.PENDING_PAYMENT);
        this.assertHasItems();
        
        // 2. CAPTURE PREVIOUS STATE (for history/audit)
        const previousStatus = this._status;
        
        // 3. MAKE THE TRANSITION
        this._status = OrderStatus.PAID;
        this._paymentTransactionId = transactionId;
        this._paidAt = timestamp;
        
        // 4. RECORD HISTORY (for audit trail)
        this._history.push({
            from: previousStatus,
            to: OrderStatus.PAID,
            timestamp,
            actor: paidBy,
            reason: `Payment confirmed: ${transactionId}`
        });
        
        // 5. RAISE DOMAIN EVENT
        this.raise(new OrderPaid({
            orderId: this._id,
            transactionId,
            amount: this._total,
            paidAt: timestamp
        }));
    }
    
    // Transition that may fail
    tryShip(
        trackingNumber: TrackingNumber,
        shippedBy: UserId
    ): Result<void, ShipmentError> {
        // Some transitions might fail for business reasons
        // beyond simple precondition checks
        
        if (this._status !== OrderStatus.PAID) {
            return Result.failure(
                new ShipmentError.NotPaid(this._id)
            );
        }
        
        if (this._items.some(i => !i.isInStock)) {
            return Result.failure(
                new ShipmentError.ItemsNotInStock(
                    this._items.filter(i => !i.isInStock)
                )
            );
        }
        
        // Perform the transition
        this._status = OrderStatus.SHIPPED;
        this._trackingNumber = trackingNumber;
        this._shippedAt = new Date();
        
        this.raise(new OrderShipped({
            orderId: this._id,
            trackingNumber,
            shippedAt: this._shippedAt
        }));
        
        return Result.success(undefined);
    }
    
    // Helper for status validation
    private assertStatus(expected: OrderStatus): void {
        if (this._status !== expected) {
            throw new InvalidOrderStateError({
                orderId: this._id,
                currentStatus: this._status,
                expectedStatus: expected,
                operation: new Error().stack?.split('\n')[2] ?? 'unknown'
            });
        }
    }
    
    private assertHasItems(): void {
        if (this._items.length === 0) {
            throw new OrderHasNoItemsError(this._id);
        }
    }
    
    // For event handling
    private raise(event: DomainEvent): void {
        this._events.push(event);
    }
    
    // Repository calls this after save
    clearEvents(): DomainEvent[] {
        const events = [...this._events];
        this._events = [];
        return events;
    }
}
 
// StateChange interface for audit trail
interface StateChange {
    from: OrderStatus;
    to: OrderStatus;
    timestamp: Date;
    actor: UserId;
    reason: string;
}

Saga Pattern for Complex Transitions

Persistence and Identity Lifecycle

Entities must be persisted to survive beyond the current process. The relationship between entity identity and persistence identity requires careful consideration:

Identity Generation Strategies
Strategy	When Identity Assigned	Pros	Cons
Application UUID	Before persistence	Entity always has identity; works distributed; simple code	UUIDs larger than integers; less readable
Database Sequence	After INSERT	Compact IDs; readable (Order #1234)	Entity lacks identity until saved; requires DB roundtrip
Hi-Lo Algorithm	Application reserves range from DB	Compact IDs; batch-friendly; fewer roundtrips	Complex configuration; gaps in sequences
Natural Key	Inherent in data (SSN, email)	Meaningful IDs; matches business language	Can change; uniqueness issues; privacy concerns
Composite Key	Combination of fields	Natural for relationship entities	Complex equality; harder to reference

Persistence Identity Patterns
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
// PATTERN 1: Application-generated UUID (Recommended)
 
class OrderRepository {
    async save(order: Order): Promise<void> {
        // Order already has ID - simple upsert logic
        const exists = await this.db.order.findUnique({
            where: { id: order.id.value }
        });
        
        if (exists) {
            await this.db.order.update({
                where: { id: order.id.value },
                data: this.toPersistence(order)
            });
        } else {
            await this.db.order.create({
                data: this.toPersistence(order)
            });
        }
    }
    
    async findById(id: OrderId): Promise<Order | null> {
        const row = await this.db.order.findUnique({
            where: { id: id.value },
            include: { lines: true }
        });
        
        if (!row) return null;
        return this.toDomain(row);
    }
}
 
 
// PATTERN 2: Database-generated IDs (Legacy/Special Cases)
 
interface TransientOrder {
    // No ID field - not yet persisted
    customerId: CustomerId;
    items: OrderItem[];
    shippingAddress: Address;
}
 
interface PersistedOrder extends TransientOrder {
    id: OrderId;  // Has ID after persistence
}
 
class LegacyOrderRepository {
    async create(order: TransientOrder): Promise<PersistedOrder> {
        // Database generates ID
        const row = await this.db.order.create({
            data: {
                // id is auto-generated
                customerId: order.customerId.value,
                shippingAddress: JSON.stringify(order.shippingAddress)
            }
        });
        
        // Now we have the ID
        return {
            ...order,
            id: OrderId.of(row.id.toString())
        };
    }
}
 
// Note: This pattern is more complex because the entity
// must handle having or not having an ID. Avoid if possible.

UUIDs vs Sequential IDs

Deletion Strategies: Soft vs Hard Delete

How do entities end their lifecycle? The choice between soft and hard deletion has significant implications for data integrity, compliance, and system behavior.

Soft Delete

•Set a deletedAt or isDeleted flag
•Data remains in database
•Can be restored if needed
•Audit trail preserved
•Referential integrity maintained
•Requires filtering in all queries
•Storage grows over time

Hard Delete

•Row removed from database
•Data permanently gone
•Cannot be restored (without backups)
•No audit trail (unless logged separately)
•May break referential integrity
•Simpler queries
•Storage reclaimed

Deletion Implementation
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
78
79
80
81
82
83
84
85
86
87
88
89
// SOFT DELETE IMPLEMENTATION
 
class Customer {
    private _id: CustomerId;
    private _status: CustomerStatus;
    private _deletedAt: Date | null = null;
    private _deletionReason: string | null = null;
    
    // Soft delete method
    deactivate(reason: string, deletedBy: UserId): void {
        if (this._status === CustomerStatus.DELETED) {
            throw new CustomerAlreadyDeletedError(this._id);
        }
        
        this._status = CustomerStatus.DELETED;
        this._deletedAt = new Date();
        this._deletionReason = reason;
        
        this.raise(new CustomerDeactivated({
            customerId: this._id,
            reason,
            deletedBy,
            deletedAt: this._deletedAt
        }));
    }
    
    // Restore method (undo soft delete)
    reactivate(reactivatedBy: UserId): void {
        if (this._status !== CustomerStatus.DELETED) {
            throw new CustomerNotDeletedError(this._id);
        }
        
        this._status = CustomerStatus.ACTIVE;
        this._deletedAt = null;
        this._deletionReason = null;
        
        this.raise(new CustomerReactivated({
            customerId: this._id,
            reactivatedBy,
            reactivatedAt: new Date()
        }));
    }
    
    get isDeleted(): boolean {
        return this._status === CustomerStatus.DELETED;
    }
}
 
// Repository handles filtering
class CustomerRepository {
    // Default: only active customers
    async findById(id: CustomerId): Promise<Customer | null> {
        const row = await this.db.customer.findFirst({
            where: {
                id: id.value,
                status: { not: 'DELETED' }  // Filter soft-deleted
            }
        });
        return row ? this.toDomain(row) : null;
    }
    
    // Explicit: include deleted (for admin/audit)
    async findByIdIncludingDeleted(
        id: CustomerId
    ): Promise<Customer | null> {
        const row = await this.db.customer.findUnique({
            where: { id: id.value }
        });
        return row ? this.toDomain(row) : null;
    }
    
    // Soft delete
    async softDelete(customer: Customer): Promise<void> {
        await this.db.customer.update({
            where: { id: customer.id.value },
            data: {
                status: 'DELETED',
                deletedAt: new Date()
            }
        });
    }
    
    // Hard delete (use with caution)
    async hardDelete(id: CustomerId): Promise<void> {
        await this.db.customer.delete({
            where: { id: id.value }
        });
    }
}

When to Use Each Deletion Strategy
Use Soft Delete When	Use Hard Delete When
Data retention is legally required (GDPR data portability)	Data must be permanently removed (GDPR right to erasure)
Entity is referenced by other entities	Self-contained data with no references
Undo/restore functionality is needed	No restoration requirement
Audit trail must be preserved	Audit logged separately
Historical reporting needed	No historical requirements
Accidental deletion is a concern	Deletion is a final, deliberate action

GDPR Considerations

Temporal Modeling and History

Temporal Modeling Patterns

•Audit Log: Separate table records each change. Entity stores current state only.
•Temporal Table: Database maintains history automatically (SQL Server, PostgreSQL).
•Event Sourcing: Store events, derive state. Full history is the primary storage.
•Snapshot + Events: Periodic snapshots plus recent events. Balance between history and performance.
•Versioned Entities: Each "save" creates a new version. All versions retrievable.

Temporal Modeling
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
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
// PATTERN: Audit Log (Most Common)
 
interface AuditEntry {
    id: string;
    entityType: string;
    entityId: string;
    action: 'CREATE' | 'UPDATE' | 'DELETE';
    timestamp: Date;
    userId: string;
    previousState: Record<string, any> | null;
    newState: Record<string, any>;
    changedFields: string[];
}
 
class AuditingRepository<T extends Entity> {
    constructor(
        private readonly innerRepository: Repository<T>,
        private readonly auditLog: AuditLogService
    ) {}
    
    async save(entity: T, userId: UserId): Promise<void> {
        const existing = await this.innerRepository.findById(entity.id);
        
        const action = existing ? 'UPDATE' : 'CREATE';
        const previousState = existing 
            ? this.toSnapshot(existing) 
            : null;
        const newState = this.toSnapshot(entity);
        
        // Save entity
        await this.innerRepository.save(entity);
        
        // Record audit
        await this.auditLog.record({
            id: crypto.randomUUID(),
            entityType: entity.constructor.name,
            entityId: entity.id.toString(),
            action,
            timestamp: new Date(),
            userId: userId.value,
            previousState,
            newState,
            changedFields: this.detectChanges(previousState, newState)
        });
    }
}
 
 
// PATTERN: Event Sourcing (Advanced)
 
interface DomainEvent {
    eventId: string;
    aggregateId: string;
    eventType: string;
    timestamp: Date;
    data: Record<string, any>;
    version: number;
}
 
class OrderEventSourced {
    private _id: OrderId;
    private _version: number = 0;
    private _status: OrderStatus;
    private _uncommittedEvents: DomainEvent[] = [];
    
    // Commands cause events
    confirmPayment(transactionId: string): void {
        this.applyEvent({
            eventType: 'OrderPaid',
            data: { transactionId, paidAt: new Date() }
        });
    }
    
    // Events change state
    private applyEvent(event: Omit<DomainEvent, 'eventId' | 'aggregateId' | 'timestamp' | 'version'>): void {
        const fullEvent: DomainEvent = {
            ...event,
            eventId: crypto.randomUUID(),
            aggregateId: this._id.value,
            timestamp: new Date(),
            version: this._version + 1
        };
        
        this.mutate(fullEvent);
        this._uncommittedEvents.push(fullEvent);
    }
    
    private mutate(event: DomainEvent): void {
        switch (event.eventType) {
            case 'OrderPaid':
                this._status = OrderStatus.PAID;
                break;
            case 'OrderShipped':
                this._status = OrderStatus.SHIPPED;
                break;
            // ... other events
        }
        this._version = event.version;
    }
    
    // Reconstitute from event history
    static fromHistory(events: DomainEvent[]): OrderEventSourced {
        const order = new OrderEventSourced();
        for (const event of events) {
            order.mutate(event);
        }
        return order;
    }
}
 
// Event-sourced repository
class EventSourcedOrderRepository {
    async save(order: OrderEventSourced): Promise<void> {
        const events = order.getUncommittedEvents();
        
        // Append events to event store
        await this.eventStore.append(
            order.id.value,
            events,
            order.version - events.length  // Expected version
        );
        
        order.markEventsAsCommitted();
    }
    
    async findById(id: OrderId): Promise<OrderEventSourced | null> {
        const events = await this.eventStore.getEvents(id.value);
        if (events.length === 0) return null;
        return OrderEventSourced.fromHistory(events);
    }
    
    // Time travel: get state at any point
    async findAtTime(id: OrderId, asOf: Date): Promise<OrderEventSourced | null> {
        const events = await this.eventStore.getEvents(
            id.value,
            { until: asOf }
        );
        if (events.length === 0) return null;
        return OrderEventSourced.fromHistory(events);
    }
}

Event Sourcing Trade-offs

Lifecycle Events and Integration

Entity lifecycle transitions often need to trigger reactions: send notifications, update read models, sync with external systems. Domain events are the clean way to handle this.

Lifecycle Event Handling
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
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
// Domain Events for Lifecycle Transitions
 
abstract class DomainEvent {
    readonly occurredAt: Date = new Date();
    abstract readonly eventType: string;
}
 
class CustomerRegistered extends DomainEvent {
    readonly eventType = 'CustomerRegistered';
    
    constructor(
        readonly customerId: CustomerId,
        readonly email: Email,
        readonly name: string
    ) { super(); }
}
 
class CustomerDeactivated extends DomainEvent {
    readonly eventType = 'CustomerDeactivated';
    
    constructor(
        readonly customerId: CustomerId,
        readonly reason: string,
        readonly deactivatedBy: UserId
    ) { super(); }
}
 
// Entity raises events
class Customer {
    private _domainEvents: DomainEvent[] = [];
    
    static register(email: Email, name: string): Customer {
        const customer = new Customer(
            CustomerId.generate(),
            email,
            name
        );
        
        // Raise lifecycle event
        customer.addEvent(new CustomerRegistered(
            customer.id,
            email,
            name
        ));
        
        return customer;
    }
    
    deactivate(reason: string, by: UserId): void {
        this._status = CustomerStatus.DEACTIVATED;
        
        this.addEvent(new CustomerDeactivated(
            this._id,
            reason,
            by
        ));
    }
    
    private addEvent(event: DomainEvent): void {
        this._domainEvents.push(event);
    }
    
    popEvents(): DomainEvent[] {
        const events = [...this._domainEvents];
        this._domainEvents = [];
        return events;
    }
}
 
// Event Handlers React to Lifecycle Events
 
class CustomerRegisteredHandler {
    constructor(
        private readonly emailService: EmailService,
        private readonly analyticsService: AnalyticsService
    ) {}
    
    async handle(event: CustomerRegistered): Promise<void> {
        // Send welcome email
        await this.emailService.sendWelcome(
            event.email,
            event.name
        );
        
        // Track in analytics
        await this.analyticsService.track({
            event: 'customer_registered',
            customerId: event.customerId.value,
            timestamp: event.occurredAt
        });
    }
}
 
class CustomerDeactivatedHandler {
    constructor(
        private readonly subscriptionService: SubscriptionService,
        private readonly notificationService: NotificationService
    ) {}
    
    async handle(event: CustomerDeactivated): Promise<void> {
        // Cancel subscriptions
        await this.subscriptionService.cancelAll(
            event.customerId
        );
        
        // Notify admin
        await this.notificationService.notifyAdmins({
            type: 'customer_deactivated',
            customerId: event.customerId.value,
            reason: event.reason,
            timestamp: event.occurredAt
        });
    }
}
 
// Dispatcher (in Application/Infrastructure layer)
class DomainEventDispatcher {
    private handlers = new Map<string, EventHandler[]>();
    
    register(eventType: string, handler: EventHandler): void {
        const handlers = this.handlers.get(eventType) ?? [];
        handlers.push(handler);
        this.handlers.set(eventType, handlers);
    }
    
    async dispatch(event: DomainEvent): Promise<void> {
        const handlers = this.handlers.get(event.eventType) ?? [];
        await Promise.all(
            handlers.map(h => h.handle(event))
        );
    }
}

Event Dispatch Timing

Summary: Entity Lifecycle Mastery

We've comprehensively covered the entity lifecycle from creation through archival. Let's consolidate the key insights:

Key Takeaways

•Entities have distinct lifecycle phases: Transient, persisted, detached, removed. Operations valid in one phase may not be in another.
•Creation is a domain event: Use factory methods, validate invariants, raise creation events. Separate create() from reconstitute().
•State transitions must be guarded: Validate preconditions, make transitions atomic, raise domain events for side effects.
•Identity should exist before persistence: Prefer application-generated UUIDs. Avoid complications of database-assigned IDs.
•Choose deletion strategy deliberately: Soft delete for audit/restore; hard delete for true removal. Consider compliance requirements.
•Temporal modeling enables time-travel: Audit logs, temporal tables, or event sourcing provide history when needed.
•Domain events integrate lifecycle with the world: Transitions raise events; handlers trigger notifications, sync, and downstream processes.

Module complete:

You've now mastered entities in Domain-Driven Design. You understand:

What entities are and why they exist
How identity differs from equality
Guidelines for designing robust entities
How to manage the complete entity lifecycle

This foundation prepares you for the next DDD building block: Value Objects, which complement entities by representing concepts defined by their attributes rather than identity.

Module Complete

4 / 4