System Design (LLD)Persistence Layer Design

Unit of Work Pattern

LevelIntermediate

Duration60 mins

TopicPersistence Layer Design

1 / 4

Managing Multiple Changes

The Coordination Challenge

In any non-trivial application, business operations rarely translate to a single database write. Consider what happens when a customer places an order in an e-commerce system:

Create a new Order record
Create multiple OrderItem records (one per product)
Update Product inventory levels for each item
Decrease the customer's loyalty points (if used)
Create a Payment record
Update the Customer's order history statistics

That's potentially six or more database operations for one business action. And here's the critical question: what happens if operation #4 fails after operations #1-3 have already been written to the database?

You're left with a partially completed order—an inventory that's been decremented for products that aren't actually sold, an order without payment, and a system in an inconsistent state. This is the coordination problem, and it's the reason the Unit of Work pattern exists.

What You Will Learn

By the end of this page, you will understand the fundamental challenges of managing multiple database changes, why naive approaches fail at scale, and how the Unit of Work pattern provides a principled solution to coordinate changes while maintaining data consistency.

The Nature of Multi-Change Operations

Business operations in real-world applications are inherently complex. They rarely map to a single database row or even a single table. Understanding this complexity is the first step toward solving it.

Why Business Operations Span Multiple Changes

Consider the domain model for a simple order:

An Order aggregates multiple OrderItems
Each OrderItem references a Product
The Order belongs to a Customer
A Payment is associated with the Order
The Customer may use LoyaltyPoints

When you think in objects (as domain-driven design encourages), a single method call like order.place() might touch all of these entities. But the persistence layer operates at a lower level—rows, columns, and transactions. This impedance mismatch is the source of our coordination challenge.

Business Operations and Their Database Impact
Business Operation	Domain Objects Affected	Database Tables Modified	Typical Change Count
Place Order	Order, OrderItems, Products, Customer, Payment	orders, order_items, products, customers, payments	5-15 operations
Transfer Funds	FromAccount, ToAccount, Transaction	accounts (2 rows), transactions	3 operations
Register User	User, Profile, Preferences, WelcomeEmail	users, profiles, user_preferences, email_queue	4+ operations
Process Refund	Order, OrderItems, Products, Payment, Customer	orders, order_items, products, payments, customers	5-10 operations
Archive Project	Project, Tasks, Comments, Attachments, Audit	projects, tasks, comments, attachments, audit_log	Hundreds of operations

The Object-Relational Impedance Mismatch

Object-oriented code thinks in terms of object graphs—interconnected entities with methods and behaviors. Databases think in terms of rows and foreign keys. This fundamental mismatch means that even simple object manipulations can translate to complex multi-table operations at the persistence layer.

Why Naive Approaches Fail

Before understanding the Unit of Work pattern, let's examine why simpler approaches to managing multiple changes are insufficient. Understanding these failure modes will illuminate why a more sophisticated pattern is necessary.

Approach 1: Independent Saves

The most naive approach is to save each entity independently:

naive-independent-saves.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// ❌ PROBLEMATIC: Each save is independent
async function placeOrder(orderData: OrderData) {
    // What if this fails?
    const order = await orderRepository.save(new Order(orderData));
    
    // We've already saved the order, but now items fail...
    for (const item of orderData.items) {
        await orderItemRepository.save(new OrderItem(order.id, item));
        // If this fails on item 3, we have partial data!
    }
    
    // What if inventory update fails after items are saved?
    for (const item of orderData.items) {
        await productRepository.decrementInventory(item.productId, item.quantity);
    }
    
    // Payment might fail after everything else succeeded
    await paymentRepository.save(new Payment(order.id, orderData.paymentDetails));
    
    // Customer update might fail too
    await customerRepository.updateOrderStats(orderData.customerId);
}

Failure Points and Consequences:

Failure Point	Data State After Failure
After order save	Empty order exists, no items, no payment
After 3rd order item	Order with partial items, wrong inventory
After inventory update	Order complete, no payment, inventory decremented
After payment	Everything except customer stats

Each of these leaves the database in an inconsistent state that violates business rules.

Approach 2: Manual Transaction Boundaries

A more sophisticated but still flawed approach is manual transaction management:

manual-transaction.ts
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
// ⚠️ BETTER BUT PROBLEMATIC: Manual transaction management
async function placeOrder(orderData: OrderData) {
    const connection = await database.getConnection();
    
    try {
        await connection.beginTransaction();
        
        // All operations use the same connection/transaction
        const order = await orderRepository.save(new Order(orderData), connection);
        
        for (const item of orderData.items) {
            await orderItemRepository.save(new OrderItem(order.id, item), connection);
        }
        
        for (const item of orderData.items) {
            await productRepository.decrementInventory(
                item.productId, 
                item.quantity, 
                connection
            );
        }
        
        await paymentRepository.save(
            new Payment(order.id, orderData.paymentDetails), 
            connection
        );
        
        await customerRepository.updateOrderStats(orderData.customerId, connection);
        
        await connection.commit();
        return order;
    } catch (error) {
        await connection.rollback();
        throw error;
    } finally {
        connection.release();
    }
}

This approach solves atomicity—if anything fails, everything rolls back. But it introduces new problems:

Problems with Manual Transaction Management

•Connection Passing: Every repository method needs a connection parameter, polluting interfaces with infrastructure concerns
•Scattered Transaction Logic: Transaction begin/commit/rollback code is duplicated across every use case
•Context Coupling: Repositories are now tightly coupled to transaction handling, making them harder to test
•No Change Tracking: We're persisting entities immediately—we can't optimize or batch operations
•Lifecycle Confusion: When exactly should we save? What if we modify an entity after first save?
•Concurrency Blindness: No detection of concurrent modifications to the same entities

The Core Issue

Both naive approaches conflate two distinct concerns: when to persist changes and how to persist them atomically. This conflation leads to scattered transaction logic, polluted interfaces, and brittle code. We need a pattern that separates these concerns while ensuring consistency.

The Persistence Problem in Depth

To truly understand why we need the Unit of Work pattern, let's examine the persistence problem from first principles. There are three fundamental questions every persistence strategy must answer:

Question 1: When Do Changes Get Persisted?

Consider this scenario:

when-to-persist.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Business logic operates on domain objects
function processOrder(order: Order) {
    order.markAsProcessing();           // Should this persist immediately?
    order.addNote("Beginning processing");
    
    for (const item of order.items) {
        item.allocateFromInventory();   // When should THIS persist?
    }
    
    order.calculateTotals();
    order.markAsReady();                // Only persist now? Or earlier?
}
 
// Three possible strategies:
// 1. Immediate: Each method call persists instantly (expensive, no atomicity)
// 2. Explicit: Caller manually saves (easy to forget, scattered logic)
// 3. Deferred: Something tracks changes and persists later (Unit of Work)

Question 2: What Gets Persisted?

When we modify an object, what constitutes a "change" that needs persistence?

Types of Changes to Track

•New Entities: Objects created during the business operation that don't exist in the database yet
•Modified Entities: Existing objects that have been retrieved and changed
•Deleted Entities: Objects that should be removed from the database
•Relationship Changes: Modified associations between entities (adding/removing children, changing references)
•Computed Values: Derived fields that need recalculation before persistence

Question 3: How Do We Ensure Atomicity?

All changes from a business operation must succeed or fail together. This requires:

Atomicity Requirements

•Single Transaction: All SQL statements execute within one database transaction
•Correct Ordering: INSERT parent before INSERT child (foreign key constraints)
•Rollback Capability: If any statement fails, rollback all previous statements
•Isolation: Other transactions shouldn't see our partial changes
•Durability: Once committed, changes survive system failures

atomicity-challenge.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// The ordering challenge: dependency graph determines SQL order
// 
// Domain model (objects reference each other freely):
//     Order ←──→ Customer
//       ↓
//     OrderItem ←──→ Product
//       ↓
//     Payment ←──→ Order
//
// Database (foreign keys enforce insertion order):
//     1. INSERT customers (if new)
//     2. INSERT orders (needs customer_id)
//     3. INSERT order_items (needs order_id, product_id)
//     4. UPDATE products (inventory)
//     5. INSERT payments (needs order_id)
//
// Who manages this ordering? The calling code? Every caller?
// That's error-prone and duplicative. We need something centralized.

The Three Pillars of Persistence

Understanding persistence problems requires thinking in three dimensions: Timing (when changes persist), Scope (what changes are included), and Atomicity (how changes are grouped). The Unit of Work pattern addresses all three by providing a centralized coordinator that tracks, orders, and commits changes as a single atomic unit.

Introducing the Unit of Work Pattern

The Unit of Work pattern, as defined by Martin Fowler in "Patterns of Enterprise Application Architecture," is:

"A Unit of Work keeps track of everything you do during a business transaction that can affect the database. When you're done, it figures out everything that needs to be done to alter the database as a result of your work."

In essence, the Unit of Work acts as a change tracker and transaction coordinator. Rather than persisting entities immediately when modified, changes are registered with the Unit of Work, which persists all changes together when the business operation completes.

Converting Mermaid diagram...

The Key Responsibilities of a Unit of Work:

The Unit of Work pattern centralizes several critical responsibilities that would otherwise be scattered across the codebase:

Unit of Work Responsibilities

•Change Tracking: Maintains lists of new, modified, and deleted entities
•Identity Management: Ensures each entity is only tracked once (Identity Map)
•Dependency Ordering: Determines the correct order for database operations
•Transaction Management: Wraps all changes in a single database transaction
•Commit Orchestration: Executes all accumulated changes when the business operation completes
•Rollback Coordination: Reverts in-memory state if database commit fails

unit-of-work-interface.ts
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
// Core Unit of Work interface
interface UnitOfWork {
    // Registration methods
    registerNew<T>(entity: T): void;
    registerDirty<T>(entity: T): void;
    registerDeleted<T>(entity: T): void;
    registerClean<T>(entity: T): void;
    
    // Commit/rollback
    commit(): Promise<void>;
    rollback(): void;
    
    // Query support (often through repositories)
    getRepository<T>(entityType: EntityType<T>): Repository<T>;
}
 
// Usage pattern
async function placeOrder(orderData: OrderData, unitOfWork: UnitOfWork) {
    const orderRepo = unitOfWork.getRepository(Order);
    const productRepo = unitOfWork.getRepository(Product);
    
    // Create new order (registers as NEW)
    const order = new Order(orderData);
    orderRepo.add(order);
    
    // Add items (each registers as NEW)
    for (const itemData of orderData.items) {
        const item = new OrderItem(order, itemData);
        order.addItem(item);
    }
    
    // Update inventory (each product registers as DIRTY)
    for (const item of order.items) {
        const product = await productRepo.findById(item.productId);
        product.decrementInventory(item.quantity);
    }
    
    // Create payment (registers as NEW)
    const payment = new Payment(order, orderData.paymentDetails);
    order.setPayment(payment);
    
    // All changes committed atomically
    await unitOfWork.commit();
}

Implicit vs. Explicit Registration

Some Unit of Work implementations require explicit registration (calling registerNew(), registerDirty()). More sophisticated implementations automatically detect changes through proxy objects, change detection algorithms, or identity map tracking. ORMs like Entity Framework and Hibernate use automatic detection, while simpler implementations often use explicit registration.

Benefits of Centralized Change Management

The Unit of Work pattern isn't just about transaction management—it provides architectural benefits that improve the entire persistence layer.

Without Unit of Work

•Transaction logic scattered across use cases
•Each repository manages its own persistence
•Connection parameters pollute interfaces
•No optimization opportunity—save immediately
•Difficult to test without database
•Concurrency conflicts undetected
•Object identity can be duplicated

With Unit of Work

•Transaction logic centralized in UoW
•Repositories focus on query/storage interface
•Clean domain interfaces, no infra leakage
•Batch operations, deferred optimization
•Easy to mock for unit testing
•Concurrency detection possible
•Identity Map ensures single instance

Performance Optimization Opportunities

Because the Unit of Work accumulates changes before committing, it can optimize operations that would be inefficient if done immediately:

optimization-opportunities.ts
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
// Without Unit of Work: N separate UPDATE statements
for (const product of products) {
    product.applyDiscount(0.1);
    await productRepository.save(product);  // UPDATE query each iteration
}
// Result: N round trips to database
 
// With Unit of Work: Single batch UPDATE or bulk operation
for (const product of products) {
    product.applyDiscount(0.1);
    unitOfWork.registerDirty(product);  // Just registers, no DB call
}
await unitOfWork.commit();  // Single optimized batch operation
// Result: 1 round trip to database
 
// Advanced optimization: Change analysis
class SmartUnitOfWork {
    async commit() {
        const changes = this.getAccumulatedChanges();
        
        // Collapse redundant changes
        // If entity was created then modified, just CREATE with final values
        const optimized = this.optimizeChanges(changes);
        
        // Batch similar operations
        // GROUP multiple INSERTs into single statement
        const batched = this.batchOperations(optimized);
        
        // Order by dependencies
        const ordered = this.topologicalSort(batched);
        
        await this.executeInTransaction(ordered);
    }
}

The Write-Behind Pattern

The Unit of Work's deferred persistence is sometimes called the 'write-behind' pattern. By accumulating changes and committing them together, we reduce database round-trips, enable batching, and can detect and eliminate redundant operations (like updating then deleting the same entity—just delete).

Change Tracking Strategies

A Unit of Work must know which entities have changed and how. There are several strategies for change tracking, each with different trade-offs:

Strategy 1: Caller Registration

The simplest approach requires the caller to explicitly register changes:

caller-registration.ts
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
// Caller explicitly registers each change
class ExplicitUnitOfWork {
    private newEntities: Set<Entity> = new Set();
    private dirtyEntities: Set<Entity> = new Set();
    private deletedEntities: Set<Entity> = new Set();
    
    registerNew(entity: Entity): void {
        this.newEntities.add(entity);
    }
    
    registerDirty(entity: Entity): void {
        if (!this.newEntities.has(entity)) {
            this.dirtyEntities.add(entity);
        }
        // If already registered as new, stays new
    }
    
    registerDeleted(entity: Entity): void {
        if (this.newEntities.has(entity)) {
            // New entity being deleted - just remove it
            this.newEntities.delete(entity);
        } else {
            this.dirtyEntities.delete(entity);
            this.deletedEntities.add(entity);
        }
    }
}
 
// Usage:
const order = new Order(data);
unitOfWork.registerNew(order);      // Caller must remember!
 
order.setStatus('confirmed');
unitOfWork.registerDirty(order);    // Caller must remember!
 
// ⚠️ Problem: Easy to forget, especially with nested objects

Strategy 2: Snapshot Comparison

Take a snapshot of entity state when loaded, compare on commit:

snapshot-comparison.ts
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
class SnapshotUnitOfWork {
    private snapshots: Map<string, EntitySnapshot> = new Map();
    private identityMap: Map<string, Entity> = new Map();
    
    // Called when entity is loaded from database
    registerClean(entity: Entity): void {
        const id = this.getEntityId(entity);
        this.identityMap.set(id, entity);
        this.snapshots.set(id, this.takeSnapshot(entity));
    }
    
    private takeSnapshot(entity: Entity): EntitySnapshot {
        return {
            state: JSON.parse(JSON.stringify(entity)),  // Deep clone
            timestamp: Date.now()
        };
    }
    
    private isDirty(entity: Entity): boolean {
        const id = this.getEntityId(entity);
        const snapshot = this.snapshots.get(id);
        if (!snapshot) return false;
        
        return !this.deepEquals(snapshot.state, entity);
    }
    
    async commit(): Promise<void> {
        const dirtyEntities = Array.from(this.identityMap.values())
            .filter(entity => this.isDirty(entity));
        
        // Now persist only the actually-changed entities
        for (const entity of dirtyEntities) {
            await this.persistChange(entity);
        }
    }
}
 
// ✅ Automatic: No caller registration needed
// ⚠️ Overhead: Snapshot creation and comparison costs memory/CPU

Strategy 3: Proxy-Based Tracking

Wrap entities in proxies that intercept property changes:

proxy-tracking.ts
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
class ProxyUnitOfWork {
    private dirtySet: Set<Entity> = new Set();
    
    track<T extends object>(entity: T): T {
        return new Proxy(entity, {
            set: (target, property, value) => {
                // Intercept property assignment
                const oldValue = (target as any)[property];
                
                if (oldValue !== value) {
                    this.dirtySet.add(target as Entity);
                }
                
                (target as any)[property] = value;
                return true;
            }
        });
    }
    
    wrapLoadedEntity<T extends object>(entity: T): T {
        // When loading from DB, wrap in tracking proxy
        return this.track(entity);
    }
}
 
// Usage:
async function getProduct(id: string): Promise<Product> {
    const product = await db.query('SELECT * FROM products WHERE id = ?', [id]);
    return unitOfWork.wrapLoadedEntity(product);  // Returns tracked proxy
}
 
// Now any modification is automatically tracked:
const product = await getProduct('123');
product.price = 99.99;  // Automatically registers as dirty!
 
// ✅ Transparent: Business code doesn't know about tracking
// ⚠️ Complexity: Proxies can have edge cases with certain operations

Change Tracking Strategy Comparison
Strategy	Automatic?	Memory Overhead	CPU Overhead	Complexity	Use Case
Caller Registration	No	None	None	Low	Simple apps, full control needed
Snapshot Comparison	Yes	High (copies)	Medium (comparison)	Medium	Read-heavy workloads
Proxy Interception	Yes	Low	Low (per-access)	High	Write-heavy, transparent tracking
Dirty Flag (manual)	Partial	None	None	Low	Controlled mutation points

Summary: Managing Multiple Changes

We've established the foundation for understanding the Unit of Work pattern. Let's consolidate the key insights:

Key Takeaways

•Business operations are inherently multi-step — Real applications modify multiple entities across multiple tables for a single business action
•Naive approaches create inconsistent data — Independent saves can leave the database in a partial, inconsistent state when failures occur
•Manual transaction management pollutes code — Passing connections around and managing try/catch/rollback everywhere violates separation of concerns
•The Unit of Work centralizes change coordination — It tracks new, modified, and deleted entities and commits them atomically
•Deferred persistence enables optimization — Accumulating changes before commit allows batching, redundancy elimination, and reduced round-trips
•Change tracking can be explicit or automatic — From simple caller registration to sophisticated proxy-based interception

What's Next:

Now that we understand why we need coordinated change management, the next page explores transaction boundaries—determining exactly what scope of changes constitutes a "unit of work" and how to define where transactions begin and end in a layered architecture.

Page Complete

You now understand the fundamental problem that the Unit of Work pattern solves: coordinating multiple database changes as a single atomic operation while keeping business logic clean and persistence concerns centralized. Next, we'll explore how to define appropriate transaction boundaries in your applications.

1 / 4

Loading learning content...

System Design (LLD)Persistence Layer Design

Unit of Work Pattern

LevelIntermediate

Duration60 mins

TopicPersistence Layer Design

1 / 4

Managing Multiple Changes

The Coordination Challenge

In any non-trivial application, business operations rarely translate to a single database write. Consider what happens when a customer places an order in an e-commerce system:

Create a new Order record
Create multiple OrderItem records (one per product)
Update Product inventory levels for each item
Decrease the customer's loyalty points (if used)
Create a Payment record
Update the Customer's order history statistics

What You Will Learn

The Nature of Multi-Change Operations

Why Business Operations Span Multiple Changes

Consider the domain model for a simple order:

An Order aggregates multiple OrderItems
Each OrderItem references a Product
The Order belongs to a Customer
A Payment is associated with the Order
The Customer may use LoyaltyPoints

Business Operations and Their Database Impact
Business Operation	Domain Objects Affected	Database Tables Modified	Typical Change Count
Place Order	Order, OrderItems, Products, Customer, Payment	orders, order_items, products, customers, payments	5-15 operations
Transfer Funds	FromAccount, ToAccount, Transaction	accounts (2 rows), transactions	3 operations
Register User	User, Profile, Preferences, WelcomeEmail	users, profiles, user_preferences, email_queue	4+ operations
Process Refund	Order, OrderItems, Products, Payment, Customer	orders, order_items, products, payments, customers	5-10 operations
Archive Project	Project, Tasks, Comments, Attachments, Audit	projects, tasks, comments, attachments, audit_log	Hundreds of operations

The Object-Relational Impedance Mismatch

Why Naive Approaches Fail

Approach 1: Independent Saves

The most naive approach is to save each entity independently:

naive-independent-saves.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// ❌ PROBLEMATIC: Each save is independent
async function placeOrder(orderData: OrderData) {
    // What if this fails?
    const order = await orderRepository.save(new Order(orderData));
    
    // We've already saved the order, but now items fail...
    for (const item of orderData.items) {
        await orderItemRepository.save(new OrderItem(order.id, item));
        // If this fails on item 3, we have partial data!
    }
    
    // What if inventory update fails after items are saved?
    for (const item of orderData.items) {
        await productRepository.decrementInventory(item.productId, item.quantity);
    }
    
    // Payment might fail after everything else succeeded
    await paymentRepository.save(new Payment(order.id, orderData.paymentDetails));
    
    // Customer update might fail too
    await customerRepository.updateOrderStats(orderData.customerId);
}

Failure Points and Consequences:

Failure Point	Data State After Failure
After order save	Empty order exists, no items, no payment
After 3rd order item	Order with partial items, wrong inventory
After inventory update	Order complete, no payment, inventory decremented
After payment	Everything except customer stats

Each of these leaves the database in an inconsistent state that violates business rules.

Approach 2: Manual Transaction Boundaries

A more sophisticated but still flawed approach is manual transaction management:

manual-transaction.ts
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
// ⚠️ BETTER BUT PROBLEMATIC: Manual transaction management
async function placeOrder(orderData: OrderData) {
    const connection = await database.getConnection();
    
    try {
        await connection.beginTransaction();
        
        // All operations use the same connection/transaction
        const order = await orderRepository.save(new Order(orderData), connection);
        
        for (const item of orderData.items) {
            await orderItemRepository.save(new OrderItem(order.id, item), connection);
        }
        
        for (const item of orderData.items) {
            await productRepository.decrementInventory(
                item.productId, 
                item.quantity, 
                connection
            );
        }
        
        await paymentRepository.save(
            new Payment(order.id, orderData.paymentDetails), 
            connection
        );
        
        await customerRepository.updateOrderStats(orderData.customerId, connection);
        
        await connection.commit();
        return order;
    } catch (error) {
        await connection.rollback();
        throw error;
    } finally {
        connection.release();
    }
}

This approach solves atomicity—if anything fails, everything rolls back. But it introduces new problems:

Problems with Manual Transaction Management

•Connection Passing: Every repository method needs a connection parameter, polluting interfaces with infrastructure concerns
•Scattered Transaction Logic: Transaction begin/commit/rollback code is duplicated across every use case
•Context Coupling: Repositories are now tightly coupled to transaction handling, making them harder to test
•No Change Tracking: We're persisting entities immediately—we can't optimize or batch operations
•Lifecycle Confusion: When exactly should we save? What if we modify an entity after first save?
•Concurrency Blindness: No detection of concurrent modifications to the same entities

The Core Issue

The Persistence Problem in Depth

To truly understand why we need the Unit of Work pattern, let's examine the persistence problem from first principles. There are three fundamental questions every persistence strategy must answer:

Question 1: When Do Changes Get Persisted?

Consider this scenario:

when-to-persist.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Business logic operates on domain objects
function processOrder(order: Order) {
    order.markAsProcessing();           // Should this persist immediately?
    order.addNote("Beginning processing");
    
    for (const item of order.items) {
        item.allocateFromInventory();   // When should THIS persist?
    }
    
    order.calculateTotals();
    order.markAsReady();                // Only persist now? Or earlier?
}
 
// Three possible strategies:
// 1. Immediate: Each method call persists instantly (expensive, no atomicity)
// 2. Explicit: Caller manually saves (easy to forget, scattered logic)
// 3. Deferred: Something tracks changes and persists later (Unit of Work)

Question 2: What Gets Persisted?

When we modify an object, what constitutes a "change" that needs persistence?

Types of Changes to Track

•New Entities: Objects created during the business operation that don't exist in the database yet
•Modified Entities: Existing objects that have been retrieved and changed
•Deleted Entities: Objects that should be removed from the database
•Relationship Changes: Modified associations between entities (adding/removing children, changing references)
•Computed Values: Derived fields that need recalculation before persistence

Question 3: How Do We Ensure Atomicity?

All changes from a business operation must succeed or fail together. This requires:

Atomicity Requirements

•Single Transaction: All SQL statements execute within one database transaction
•Correct Ordering: INSERT parent before INSERT child (foreign key constraints)
•Rollback Capability: If any statement fails, rollback all previous statements
•Isolation: Other transactions shouldn't see our partial changes
•Durability: Once committed, changes survive system failures

atomicity-challenge.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// The ordering challenge: dependency graph determines SQL order
// 
// Domain model (objects reference each other freely):
//     Order ←──→ Customer
//       ↓
//     OrderItem ←──→ Product
//       ↓
//     Payment ←──→ Order
//
// Database (foreign keys enforce insertion order):
//     1. INSERT customers (if new)
//     2. INSERT orders (needs customer_id)
//     3. INSERT order_items (needs order_id, product_id)
//     4. UPDATE products (inventory)
//     5. INSERT payments (needs order_id)
//
// Who manages this ordering? The calling code? Every caller?
// That's error-prone and duplicative. We need something centralized.

The Three Pillars of Persistence

Introducing the Unit of Work Pattern

The Unit of Work pattern, as defined by Martin Fowler in "Patterns of Enterprise Application Architecture," is:

"A Unit of Work keeps track of everything you do during a business transaction that can affect the database. When you're done, it figures out everything that needs to be done to alter the database as a result of your work."

Converting Mermaid diagram...

The Key Responsibilities of a Unit of Work:

The Unit of Work pattern centralizes several critical responsibilities that would otherwise be scattered across the codebase:

Unit of Work Responsibilities

•Change Tracking: Maintains lists of new, modified, and deleted entities
•Identity Management: Ensures each entity is only tracked once (Identity Map)
•Dependency Ordering: Determines the correct order for database operations
•Transaction Management: Wraps all changes in a single database transaction
•Commit Orchestration: Executes all accumulated changes when the business operation completes
•Rollback Coordination: Reverts in-memory state if database commit fails

unit-of-work-interface.ts
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
// Core Unit of Work interface
interface UnitOfWork {
    // Registration methods
    registerNew<T>(entity: T): void;
    registerDirty<T>(entity: T): void;
    registerDeleted<T>(entity: T): void;
    registerClean<T>(entity: T): void;
    
    // Commit/rollback
    commit(): Promise<void>;
    rollback(): void;
    
    // Query support (often through repositories)
    getRepository<T>(entityType: EntityType<T>): Repository<T>;
}
 
// Usage pattern
async function placeOrder(orderData: OrderData, unitOfWork: UnitOfWork) {
    const orderRepo = unitOfWork.getRepository(Order);
    const productRepo = unitOfWork.getRepository(Product);
    
    // Create new order (registers as NEW)
    const order = new Order(orderData);
    orderRepo.add(order);
    
    // Add items (each registers as NEW)
    for (const itemData of orderData.items) {
        const item = new OrderItem(order, itemData);
        order.addItem(item);
    }
    
    // Update inventory (each product registers as DIRTY)
    for (const item of order.items) {
        const product = await productRepo.findById(item.productId);
        product.decrementInventory(item.quantity);
    }
    
    // Create payment (registers as NEW)
    const payment = new Payment(order, orderData.paymentDetails);
    order.setPayment(payment);
    
    // All changes committed atomically
    await unitOfWork.commit();
}

Implicit vs. Explicit Registration

Benefits of Centralized Change Management

The Unit of Work pattern isn't just about transaction management—it provides architectural benefits that improve the entire persistence layer.

Without Unit of Work

•Transaction logic scattered across use cases
•Each repository manages its own persistence
•Connection parameters pollute interfaces
•No optimization opportunity—save immediately
•Difficult to test without database
•Concurrency conflicts undetected
•Object identity can be duplicated

With Unit of Work

•Transaction logic centralized in UoW
•Repositories focus on query/storage interface
•Clean domain interfaces, no infra leakage
•Batch operations, deferred optimization
•Easy to mock for unit testing
•Concurrency detection possible
•Identity Map ensures single instance

Performance Optimization Opportunities

Because the Unit of Work accumulates changes before committing, it can optimize operations that would be inefficient if done immediately:

optimization-opportunities.ts
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
// Without Unit of Work: N separate UPDATE statements
for (const product of products) {
    product.applyDiscount(0.1);
    await productRepository.save(product);  // UPDATE query each iteration
}
// Result: N round trips to database
 
// With Unit of Work: Single batch UPDATE or bulk operation
for (const product of products) {
    product.applyDiscount(0.1);
    unitOfWork.registerDirty(product);  // Just registers, no DB call
}
await unitOfWork.commit();  // Single optimized batch operation
// Result: 1 round trip to database
 
// Advanced optimization: Change analysis
class SmartUnitOfWork {
    async commit() {
        const changes = this.getAccumulatedChanges();
        
        // Collapse redundant changes
        // If entity was created then modified, just CREATE with final values
        const optimized = this.optimizeChanges(changes);
        
        // Batch similar operations
        // GROUP multiple INSERTs into single statement
        const batched = this.batchOperations(optimized);
        
        // Order by dependencies
        const ordered = this.topologicalSort(batched);
        
        await this.executeInTransaction(ordered);
    }
}

The Write-Behind Pattern

Change Tracking Strategies

A Unit of Work must know which entities have changed and how. There are several strategies for change tracking, each with different trade-offs:

Strategy 1: Caller Registration

The simplest approach requires the caller to explicitly register changes:

caller-registration.ts
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
// Caller explicitly registers each change
class ExplicitUnitOfWork {
    private newEntities: Set<Entity> = new Set();
    private dirtyEntities: Set<Entity> = new Set();
    private deletedEntities: Set<Entity> = new Set();
    
    registerNew(entity: Entity): void {
        this.newEntities.add(entity);
    }
    
    registerDirty(entity: Entity): void {
        if (!this.newEntities.has(entity)) {
            this.dirtyEntities.add(entity);
        }
        // If already registered as new, stays new
    }
    
    registerDeleted(entity: Entity): void {
        if (this.newEntities.has(entity)) {
            // New entity being deleted - just remove it
            this.newEntities.delete(entity);
        } else {
            this.dirtyEntities.delete(entity);
            this.deletedEntities.add(entity);
        }
    }
}
 
// Usage:
const order = new Order(data);
unitOfWork.registerNew(order);      // Caller must remember!
 
order.setStatus('confirmed');
unitOfWork.registerDirty(order);    // Caller must remember!
 
// ⚠️ Problem: Easy to forget, especially with nested objects

Strategy 2: Snapshot Comparison

Take a snapshot of entity state when loaded, compare on commit:

snapshot-comparison.ts
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
class SnapshotUnitOfWork {
    private snapshots: Map<string, EntitySnapshot> = new Map();
    private identityMap: Map<string, Entity> = new Map();
    
    // Called when entity is loaded from database
    registerClean(entity: Entity): void {
        const id = this.getEntityId(entity);
        this.identityMap.set(id, entity);
        this.snapshots.set(id, this.takeSnapshot(entity));
    }
    
    private takeSnapshot(entity: Entity): EntitySnapshot {
        return {
            state: JSON.parse(JSON.stringify(entity)),  // Deep clone
            timestamp: Date.now()
        };
    }
    
    private isDirty(entity: Entity): boolean {
        const id = this.getEntityId(entity);
        const snapshot = this.snapshots.get(id);
        if (!snapshot) return false;
        
        return !this.deepEquals(snapshot.state, entity);
    }
    
    async commit(): Promise<void> {
        const dirtyEntities = Array.from(this.identityMap.values())
            .filter(entity => this.isDirty(entity));
        
        // Now persist only the actually-changed entities
        for (const entity of dirtyEntities) {
            await this.persistChange(entity);
        }
    }
}
 
// ✅ Automatic: No caller registration needed
// ⚠️ Overhead: Snapshot creation and comparison costs memory/CPU

Strategy 3: Proxy-Based Tracking

Wrap entities in proxies that intercept property changes:

proxy-tracking.ts
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
class ProxyUnitOfWork {
    private dirtySet: Set<Entity> = new Set();
    
    track<T extends object>(entity: T): T {
        return new Proxy(entity, {
            set: (target, property, value) => {
                // Intercept property assignment
                const oldValue = (target as any)[property];
                
                if (oldValue !== value) {
                    this.dirtySet.add(target as Entity);
                }
                
                (target as any)[property] = value;
                return true;
            }
        });
    }
    
    wrapLoadedEntity<T extends object>(entity: T): T {
        // When loading from DB, wrap in tracking proxy
        return this.track(entity);
    }
}
 
// Usage:
async function getProduct(id: string): Promise<Product> {
    const product = await db.query('SELECT * FROM products WHERE id = ?', [id]);
    return unitOfWork.wrapLoadedEntity(product);  // Returns tracked proxy
}
 
// Now any modification is automatically tracked:
const product = await getProduct('123');
product.price = 99.99;  // Automatically registers as dirty!
 
// ✅ Transparent: Business code doesn't know about tracking
// ⚠️ Complexity: Proxies can have edge cases with certain operations

Change Tracking Strategy Comparison
Strategy	Automatic?	Memory Overhead	CPU Overhead	Complexity	Use Case
Caller Registration	No	None	None	Low	Simple apps, full control needed
Snapshot Comparison	Yes	High (copies)	Medium (comparison)	Medium	Read-heavy workloads
Proxy Interception	Yes	Low	Low (per-access)	High	Write-heavy, transparent tracking
Dirty Flag (manual)	Partial	None	None	Low	Controlled mutation points

Summary: Managing Multiple Changes

We've established the foundation for understanding the Unit of Work pattern. Let's consolidate the key insights:

Key Takeaways

•Business operations are inherently multi-step — Real applications modify multiple entities across multiple tables for a single business action
•Naive approaches create inconsistent data — Independent saves can leave the database in a partial, inconsistent state when failures occur
•Manual transaction management pollutes code — Passing connections around and managing try/catch/rollback everywhere violates separation of concerns
•The Unit of Work centralizes change coordination — It tracks new, modified, and deleted entities and commits them atomically
•Deferred persistence enables optimization — Accumulating changes before commit allows batching, redundancy elimination, and reduced round-trips
•Change tracking can be explicit or automatic — From simple caller registration to sophisticated proxy-based interception

What's Next:

Page Complete

1 / 4