Integration with Repositories — Unit of Work Pattern | OneNoughtOne

0/86

System Design (LLD)Persistence Layer Design

Unit of Work Pattern

LevelIntermediate

Duration60 mins

TopicPersistence Layer Design

4 / 4

Integration with Repositories

Two Patterns, One Architecture

The Unit of Work and Repository patterns are complementary—they work together to create a clean, testable, and maintainable persistence layer. While the previous pages focused on the Unit of Work in isolation, production applications require thoughtful integration between these two patterns. This page explores how to combine Unit of Work with Repository pattern effectively, examining ownership models, aggregate considerations, and practical integration strategies that scale from simple CRUD applications to complex domain-driven architectures.

What You Will Learn

By the end of this page, you will understand how to integrate Unit of Work with repositories, different repository access patterns, how aggregates influence repository design, testing strategies for the integrated persistence layer, and common pitfalls to avoid.

The Relationship Between Patterns

Before diving into integration strategies, let's clarify what each pattern is responsible for: Repository Pattern Responsibilities: Provides collection-like interface for domain objects Encapsulates query logic and data mapping Abstracts the underlying data store Returns domain entities, not database rows Unit of Work Responsibilities: Tracks changes across multiple entities Coordinates transaction boundaries Ensures atomicity of commits Manages entity identity and state The key insight is that these patterns address different concerns of the same problem:

Converting Mermaid diagram...

Complementary Responsibilities
Concern	Repository Handles	Unit of Work Handles
Finding entities	✅ Query logic, mapping	❌ Not involved
Adding new entities	✅ Registration interface	✅ Tracking state, commit
Updating entities	⚠️ May not have explicit API	✅ Detects changes, generates UPDATE
Deleting entities	✅ Removal interface	✅ Tracking deletion, commit
Transaction scope	❌ Not aware	✅ Owns transaction boundary
Multiple repositories	❌ Isolated per type	✅ Coordinates across all

Not Mutually Exclusive

Some developers wonder whether to use Repository OR Unit of Work. In most architectures, you use both: Repositories for data access abstraction and Unit of Work for change coordination. They serve different purposes and complement each other.

Repository Access Patterns

There are several architectural patterns for how application code accesses repositories in relation to the Unit of Work. Each has trade-offs: Pattern 1: Repositories as Properties of Unit of Work The most common pattern—repositories are accessed through the Unit of Work:

pattern-1-property-access.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
45
46
47
48
49
// Pattern 1: Repositories as UoW properties
interface IUnitOfWork {
    readonly orders: IOrderRepository;
    readonly products: IProductRepository;
    readonly customers: ICustomerRepository;
    
    commit(): Promise<void>;
    rollback(): Promise<void>;
}
 
class UnitOfWork implements IUnitOfWork {
    private _orders?: OrderRepository;
    private _products?: ProductRepository;
    private _customers?: CustomerRepository;
    private changeTracker: ChangeTracker;
    
    get orders(): IOrderRepository {
        return this._orders ??= new OrderRepository(this.changeTracker);
    }
    
    get products(): IProductRepository {
        return this._products ??= new ProductRepository(this.changeTracker);
    }
    
    get customers(): ICustomerRepository {
        return this._customers ??= new CustomerRepository(this.changeTracker);
    }
}
 
// Usage in application service:
class OrderService {
    constructor(private unitOfWork: IUnitOfWork) {}
    
    async placeOrder(command: PlaceOrderCommand): Promise<Order> {
        // Access repositories through UoW
        const customer = await this.unitOfWork.customers.findById(command.customerId);
        const products = await this.unitOfWork.products.findByIds(command.productIds);
        
        const order = Order.create(customer, products, command.quantities);
        this.unitOfWork.orders.add(order);
        
        await this.unitOfWork.commit();
        return order;
    }
}
 
// ✅ Guarantees all repositories share same change tracker
// ✅ Clear ownership hierarchy
// ⚠️ UoW interface grows with each new repository

Pattern 2: Repository Factory Use a factory to create repositories that share the same Unit of Work context:

pattern-2-factory.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
45
46
47
48
// Pattern 2: Repository Factory
interface IRepositoryFactory {
    createOrderRepository(): IOrderRepository;
    createProductRepository(): IProductRepository;
    createCustomerRepository(): ICustomerRepository;
}
 
class UnitOfWorkRepositoryFactory implements IRepositoryFactory {
    constructor(
        private changeTracker: ChangeTracker,
        private connection: DatabaseConnection
    ) {}
    
    createOrderRepository(): IOrderRepository {
        return new OrderRepository(this.changeTracker, this.connection);
    }
    
    createProductRepository(): IProductRepository {
        return new ProductRepository(this.changeTracker, this.connection);
    }
    
    createCustomerRepository(): ICustomerRepository {
        return new CustomerRepository(this.changeTracker, this.connection);
    }
}
 
// Unit of Work exposes factory
interface IUnitOfWork {
    readonly repositoryFactory: IRepositoryFactory;
    commit(): Promise<void>;
    rollback(): Promise<void>;
}
 
// Usage:
class OrderService {
    constructor(private unitOfWork: IUnitOfWork) {}
    
    async placeOrder(command: PlaceOrderCommand): Promise<Order> {
        const orderRepo = this.unitOfWork.repositoryFactory.createOrderRepository();
        const customerRepo = this.unitOfWork.repositoryFactory.createCustomerRepository();
        
        // ... rest of logic
    }
}
 
// ✅ More flexible - can create custom repositories
// ✅ UoW interface stays stable
// ⚠️ More verbose - need to call factory methods

Pattern 3: Generic Repository with Unit of Work For CRUD-heavy applications, a generic repository approach:

pattern-3-generic.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
45
46
47
48
49
50
51
52
53
54
// Pattern 3: Generic Repository Access
interface IUnitOfWork {
    getRepository<T extends Entity>(entityType: EntityType<T>): IRepository<T>;
    commit(): Promise<void>;
    rollback(): Promise<void>;
}
 
interface IRepository<T> {
    findById(id: string): Promise<T | null>;
    findAll(): Promise<T[]>;
    findBy(specification: Specification<T>): Promise<T[]>;
    add(entity: T): void;
    remove(entity: T): void;
}
 
class UnitOfWork implements IUnitOfWork {
    private repositoryCache: Map<string, IRepository<any>> = new Map();
    
    getRepository<T extends Entity>(entityType: EntityType<T>): IRepository<T> {
        const typeName = entityType.name;
        
        if (!this.repositoryCache.has(typeName)) {
            this.repositoryCache.set(
                typeName, 
                new GenericRepository<T>(entityType, this.changeTracker)
            );
        }
        
        return this.repositoryCache.get(typeName)!;
    }
}
 
// Usage:
class OrderService {
    async placeOrder(command: PlaceOrderCommand): Promise<Order> {
        const orderRepo = this.unitOfWork.getRepository(Order);
        const productRepo = this.unitOfWork.getRepository(Product);
        
        // Generic interface for common operations
        const products = await productRepo.findBy(
            new ProductIdSpecification(command.productIds)
        );
        
        const order = Order.create(/*...*/);
        orderRepo.add(order);
        
        await this.unitOfWork.commit();
        return order;
    }
}
 
// ✅ No explicit repository classes for simple CRUD
// ✅ Consistent interface across all entities
// ⚠️ Custom query methods require extending

Repository Access Pattern Comparison
Pattern	Best For	Trade-offs
Properties on UoW	Most applications, clear API	UoW interface grows with repositories
Factory Pattern	Large number of repositories	More verbose, extra indirection
Generic Repository	CRUD-heavy, uniform access	Less type safety, custom queries harder

Aggregates and Repository Design

In Domain-Driven Design, aggregates define consistency boundaries. This has profound implications for how repositories and the Unit of Work interact. The Aggregate Rule: Repositories should only exist for aggregate roots. Non-root entities within an aggregate should be accessed through their aggregate root. This rule affects both repository design and Unit of Work behavior:

Converting Mermaid diagram...

aggregate-repository.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
// ✅ CORRECT: Repository for aggregate root only
interface IOrderRepository {
    findById(id: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    add(order: Order): void;
    remove(order: Order): void;
}
 
// The Order aggregate root includes its items
class Order {
    private id: OrderId;
    private customerId: CustomerId;  // Reference by ID, not object
    private items: OrderItem[] = [];  // Owned by Order
    
    addItem(productId: ProductId, quantity: number, price: Money): void {
        const item = new OrderItem(this.id, productId, quantity, price);
        this.items.push(item);
    }
    
    removeItem(itemId: OrderItemId): void {
        this.items = this.items.filter(i => !i.id.equals(itemId));
    }
}
 
// ❌ INCORRECT: No separate repository for OrderItem
// interface IOrderItemRepository {} // Don't do this!
 
// Usage - Order controls its items
class OrderApplicationService {
    async addItemToOrder(orderId: string, productId: string, qty: number): Promise<void> {
        const order = await this.unitOfWork.orders.findById(new OrderId(orderId));
        if (!order) throw new OrderNotFoundError(orderId);
        
        const product = await this.unitOfWork.products.findById(new ProductId(productId));
        if (!product) throw new ProductNotFoundError(productId);
        
        // Order manages its own items
        order.addItem(product.id, qty, product.currentPrice);
        
        // Unit of Work tracks Order, which includes its items
        await this.unitOfWork.commit();
        // Commits: UPDATE orders, INSERT order_items (if new), etc.
    }
}

Unit of Work and Aggregate Persistence: When persisting aggregates, the Unit of Work must handle the entire object graph:

aggregate-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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// Change tracker must traverse aggregate relationships
class AggregateAwareChangeTracker extends ChangeTracker {
    /**
     * When tracking an aggregate root, also track its children
     */
    trackLoaded<T>(entity: T): void {
        super.trackLoaded(entity);
        
        const metadata = this.getMetadata(entity);
        
        // Recursively track owned entities (one-to-many, one-to-one owned)
        for (const relationship of metadata.relationships) {
            if (relationship.isOwned) {  // Part of aggregate, not just reference
                const children = this.getRelatedEntities(entity, relationship);
                for (const child of children) {
                    this.trackLoaded(child);
                }
            }
        }
    }
    
    /**
     * Detect changes in the entire aggregate
     */
    detectAggregateChanges<T>(root: T): AggregateChanges {
        const changes: AggregateChanges = {
            rootModified: this.hasChanges(root),
            addedChildren: [],
            modifiedChildren: [],
            deletedChildren: []
        };
        
        const metadata = this.getMetadata(root);
        
        for (const relationship of metadata.relationships) {
            if (relationship.isOwned) {
                const currentChildren = this.getRelatedEntities(root, relationship);
                const originalChildIds = this.getOriginalChildIds(root, relationship);
                
                for (const child of currentChildren) {
                    const childId = this.getId(child);
                    
                    if (!originalChildIds.has(childId)) {
                        changes.addedChildren.push(child);
                    } else if (this.hasChanges(child)) {
                        changes.modifiedChildren.push(child);
                    }
                }
                
                // Find deleted children
                for (const origId of originalChildIds) {
                    if (!currentChildren.some(c => this.getId(c) === origId)) {
                        changes.deletedChildren.push({ type: relationship.targetType, id: origId });
                    }
                }
            }
        }
        
        return changes;
    }
}

Aggregate Loading Strategies

When loading an aggregate, you have options: eager load the entire aggregate (simple but potentially heavy), lazy load children on access (risk of N+1 queries), or use explicit loading (caller decides what to include). Most ORMs support all three approaches.

Cross-Cutting Concerns

The integration point between Unit of Work and repositories is an excellent place to handle cross-cutting concerns like auditing, validation, and domain events. Audit Logging:

audit-integration.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
45
46
47
48
49
50
51
52
53
54
// Audit-aware Unit of Work
class AuditableUnitOfWork implements IUnitOfWork {
    private inner: IUnitOfWork;
    private auditLog: IAuditLog;
    private currentUser: User;
    
    constructor(inner: IUnitOfWork, auditLog: IAuditLog, currentUser: User) {
        this.inner = inner;
        this.auditLog = auditLog;
        this.currentUser = currentUser;
    }
    
    async commit(): Promise<void> {
        const changes = this.inner.getChanges();
        
        // Create audit entries for all changes
        for (const entry of changes.inserts) {
            await this.auditLog.log({
                entityType: entry.entityType.name,
                entityId: this.getId(entry.entity),
                action: 'CREATE',
                newValues: this.serializeEntity(entry.entity),
                userId: this.currentUser.id,
                timestamp: new Date()
            });
        }
        
        for (const entry of changes.updates) {
            await this.auditLog.log({
                entityType: entry.entityType.name,
                entityId: this.getId(entry.entity),
                action: 'UPDATE',
                oldValues: this.mapToObject(entry.originalValues),
                newValues: this.serializeEntity(entry.entity),
                userId: this.currentUser.id,
                timestamp: new Date()
            });
        }
        
        for (const entry of changes.deletes) {
            await this.auditLog.log({
                entityType: entry.entityType.name,
                entityId: this.getId(entry.entity),
                action: 'DELETE',
                oldValues: this.serializeEntity(entry.entity),
                userId: this.currentUser.id,
                timestamp: new Date()
            });
        }
        
        // Commit the actual changes
        await this.inner.commit();
    }
}

Domain Event Publishing:

domain-events-integration.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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
// Domain event-aware Unit of Work
class EventPublishingUnitOfWork implements IUnitOfWork {
    private inner: IUnitOfWork;
    private eventDispatcher: IDomainEventDispatcher;
    
    async commit(): Promise<void> {
        // Collect all domain events from entities
        const events: DomainEvent[] = [];
        
        for (const entry of this.inner.getTrackedEntities()) {
            if (entry.entity instanceof AggregateRoot) {
                events.push(...entry.entity.getDomainEvents());
            }
        }
        
        // Commit first (ensures all data is persisted)
        await this.inner.commit();
        
        // Then dispatch events (after successful commit)
        for (const event of events) {
            await this.eventDispatcher.dispatch(event);
        }
        
        // Clear events from entities
        for (const entry of this.inner.getTrackedEntities()) {
            if (entry.entity instanceof AggregateRoot) {
                entry.entity.clearDomainEvents();
            }
        }
    }
}
 
// Aggregate root base class with event support
abstract class AggregateRoot<TId> {
    private domainEvents: DomainEvent[] = [];
    
    protected addDomainEvent(event: DomainEvent): void {
        this.domainEvents.push(event);
    }
    
    getDomainEvents(): DomainEvent[] {
        return [...this.domainEvents];
    }
    
    clearDomainEvents(): void {
        this.domainEvents = [];
    }
}
 
// Usage in domain entity:
class Order extends AggregateRoot<OrderId> {
    place(): void {
        this.status = OrderStatus.Placed;
        this.placedAt = new Date();
        
        // Raise domain event
        this.addDomainEvent(new OrderPlacedEvent(this.id, this.customerId, this.total));
    }
}

Event Dispatch Timing

Events should be dispatched AFTER successful commit, not before. If commit fails, you don't want events that reference uncommitted data. Some architectures use outbox pattern: events are stored in the same transaction, then published asynchronously by a separate process.

Testing Strategies

One of the primary benefits of the Unit of Work and Repository patterns is improved testability. Here are strategies for testing at different levels: Unit Testing with In-Memory Implementations:

in-memory-uow.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
45
46
47
48
49
50
51
52
53
54
55
56
// In-memory Unit of Work for testing
class InMemoryUnitOfWork implements IUnitOfWork {
    private committed: boolean = false;
    public readonly orders: InMemoryOrderRepository;
    public readonly products: InMemoryProductRepository;
    public readonly customers: InMemoryCustomerRepository;
    
    constructor() {
        const tracker = new InMemoryChangeTracker();
        this.orders = new InMemoryOrderRepository(tracker);
        this.products = new InMemoryProductRepository(tracker);
        this.customers = new InMemoryCustomerRepository(tracker);
    }
    
    async commit(): Promise<void> {
        // In-memory: just mark as committed
        // Changes are already reflected in the collections
        this.committed = true;
    }
    
    async rollback(): Promise<void> {
        // Could implement actual rollback if needed
        this.committed = false;
    }
    
    wasCommitted(): boolean {
        return this.committed;
    }
}
 
class InMemoryOrderRepository implements IOrderRepository {
    private orders: Map<string, Order> = new Map();
    
    async findById(id: string): Promise<Order | null> {
        return this.orders.get(id) || null;
    }
    
    add(order: Order): void {
        this.orders.set(order.id, order);
    }
    
    remove(order: Order): void {
        this.orders.delete(order.id);
    }
    
    // Test helpers
    getAll(): Order[] {
        return Array.from(this.orders.values());
    }
    
    seed(orders: Order[]): void {
        for (const order of orders) {
            this.orders.set(order.id, order);
        }
    }
}

Writing Unit Tests:

unit-tests.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
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
// Unit test example
describe('OrderApplicationService', () => {
    let unitOfWork: InMemoryUnitOfWork;
    let service: OrderApplicationService;
    
    beforeEach(() => {
        unitOfWork = new InMemoryUnitOfWork();
        service = new OrderApplicationService(unitOfWork);
    });
    
    describe('placeOrder', () => {
        it('should create order with items and commit', async () => {
            // Arrange: Seed test data
            const customer = new Customer('cust-1', 'John Doe');
            const product = new Product('prod-1', 'Widget', Money.of(25));
            
            unitOfWork.customers.seed([customer]);
            unitOfWork.products.seed([product]);
            
            // Act
            const command = new PlaceOrderCommand({
                customerId: 'cust-1',
                items: [{ productId: 'prod-1', quantity: 2 }]
            });
            
            const result = await service.placeOrder(command);
            
            // Assert
            expect(result.isSuccess).toBe(true);
            expect(unitOfWork.wasCommitted()).toBe(true);
            
            const savedOrders = unitOfWork.orders.getAll();
            expect(savedOrders).toHaveLength(1);
            expect(savedOrders[0].items).toHaveLength(1);
            expect(savedOrders[0].items[0].quantity).toBe(2);
        });
        
        it('should not commit if customer not found', async () => {
            // Act
            const command = new PlaceOrderCommand({
                customerId: 'non-existent',
                items: [{ productId: 'prod-1', quantity: 1 }]
            });
            
            const result = await service.placeOrder(command);
            
            // Assert
            expect(result.isFailure).toBe(true);
            expect(result.error.code).toBe('CUSTOMER_NOT_FOUND');
            expect(unitOfWork.wasCommitted()).toBe(false);
            expect(unitOfWork.orders.getAll()).toHaveLength(0);
        });
        
        it('should rollback on inventory error', async () => {
            // Arrange: Product with insufficient inventory
            const customer = new Customer('cust-1', 'John Doe');
            const product = new Product('prod-1', 'Widget', Money.of(25));
            product.setInventory(1);  // Only 1 available
            
            unitOfWork.customers.seed([customer]);
            unitOfWork.products.seed([product]);
            
            // Act: Try to order 10
            const command = new PlaceOrderCommand({
                customerId: 'cust-1',
                items: [{ productId: 'prod-1', quantity: 10 }]
            });
            
            const result = await service.placeOrder(command);
            
            // Assert
            expect(result.isFailure).toBe(true);
            expect(result.error.code).toBe('INSUFFICIENT_INVENTORY');
            expect(unitOfWork.wasCommitted()).toBe(false);
        });
    });
});

Integration Testing with Real Database:

integration-tests.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
45
46
47
48
49
50
51
52
53
54
55
56
57
// Integration test with real database
describe('OrderApplicationService Integration', () => {
    let unitOfWorkFactory: () => IUnitOfWork;
    
    beforeAll(async () => {
        // Setup test database
        await TestDatabase.setup();
        unitOfWorkFactory = () => new UnitOfWork(TestDatabase.createConnection());
    });
    
    afterAll(async () => {
        await TestDatabase.teardown();
    });
    
    beforeEach(async () => {
        // Clean data between tests
        await TestDatabase.truncateAll();
    });
    
    it('should persist order across repository boundaries', async () => {
        const unitOfWork = unitOfWorkFactory();
        const service = new OrderApplicationService(unitOfWork);
        
        // Seed data using the same UoW
        const customer = new Customer('cust-1', 'Jane Doe');
        unitOfWork.customers.add(customer);
        
        const product = new Product('prod-1', 'Gadget', Money.of(99.99));
        product.setInventory(100);
        unitOfWork.products.add(product);
        
        await unitOfWork.commit();
        
        // Create order
        const freshUnitOfWork = unitOfWorkFactory();
        const freshService = new OrderApplicationService(freshUnitOfWork);
        
        const result = await freshService.placeOrder(new PlaceOrderCommand({
            customerId: 'cust-1',
            items: [{ productId: 'prod-1', quantity: 5 }]
        }));
        
        expect(result.isSuccess).toBe(true);
        
        // Verify with yet another UoW (different connection)
        const verifyUnitOfWork = unitOfWorkFactory();
        const savedOrder = await verifyUnitOfWork.orders.findById(result.value.id);
        
        expect(savedOrder).not.toBeNull();
        expect(savedOrder!.items).toHaveLength(1);
        expect(savedOrder!.items[0].quantity).toBe(5);
        
        // Verify inventory was decremented
        const product2 = await verifyUnitOfWork.products.findById('prod-1');
        expect(product2!.inventory).toBe(95);  // 100 - 5
    });
});

Test Pyramid

Use mostly unit tests with in-memory implementations (fast, isolated), fewer integration tests with real database (verify SQL/mapping), and minimal end-to-end tests (verify full stack). The abstraction provided by Unit of Work and Repository patterns enables this pyramid.

Common Pitfalls and Solutions

The integration of Unit of Work and Repository patterns can introduce subtle issues. Here are common pitfalls and how to avoid them:

Pitfall 1: Multiple Unit of Work Instances

•Problem: Different services or repositories get different UoW instances
•Symptom: Changes made in one service aren't visible to another; commit doesn't save all changes
•Solution: Use scoped DI lifetime; all services in a request share one UoW instance

pitfall-1-solution.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// ❌ WRONG: Creating new UoW per repository
class OrderService {
    async placeOrder(command: PlaceOrderCommand): Promise<void> {
        const orderUoW = new UnitOfWork();  // New instance
        const productUoW = new UnitOfWork(); // Different instance!
        
        // These don't share change tracker - disaster!
    }
}
 
// ✅ CORRECT: Injected scoped UoW
services.addScoped<IUnitOfWork, UnitOfWork>();
 
class OrderService {
    constructor(private unitOfWork: IUnitOfWork) {} // Injected, shared
    
    async placeOrder(command: PlaceOrderCommand): Promise<void> {
        // All repositories from unitOfWork share same context
    }
}

Pitfall 2: Forgetting to Commit

•Problem: Changes are tracked but never committed
•Symptom: Tests pass (in-memory), production loses data
•Solution: Use transaction decorator, or always commit in finally block

Pitfall 3: Leaking Entity References

•Problem: Returning tracked entities from service, then modifying outside UoW scope
•Symptom: Unexpected changes persisted, or changes lost
•Solution: Return DTOs from services, or detach entities before returning

Pitfall 4: Lazy Loading After Dispose

•Problem: Accessing navigation property after UoW is disposed
•Symptom: 'ObjectDisposedException' or null reference
•Solution: Eager load needed data, or ensure UoW lives long enough

Pitfall 5: Repository Bypassing Change Tracker

•Problem: Repository executes raw SQL that doesn't go through change tracker
•Symptom: Identity map is stale; changes overwritten
•Solution: Clear change tracker after raw SQL, or reload affected entities

Summary: Integration with Repositories

We've explored how to effectively integrate the Unit of Work and Repository patterns. Let's consolidate the key insights:

Key Takeaways

•UoW and Repository are complementary — Repository handles data access abstraction, Unit of Work handles change coordination
•Choose appropriate access pattern — Properties on UoW for most cases, Factory for many repositories, Generic for CRUD-heavy apps
•Aggregates define repository boundaries — Only aggregate roots get repositories; children are accessed through their root
•Leverage integration for cross-cutting concerns — Auditing, domain events, and validation fit naturally at the UoW commit boundary
•Embrace testability — In-memory implementations enable fast unit tests; integration tests verify database behavior
•Avoid common pitfalls — Shared UoW per request, always commit, don't leak tracked entities

Best Practices Summary

•Scoped DI lifetime for Unit of Work
•Access repositories through UoW
•Repository per aggregate root only
•Domain events dispatched after commit
•Return DTOs from application services

Anti-Patterns to Avoid

•Creating UoW per repository
•Repositories independent of UoW
•Repository for every entity type
•Events dispatched before commit
•Returning tracked entities outside UoW scope

Module Complete

Congratulations! You've completed the Unit of Work Pattern module. You now understand how to manage multiple database changes atomically, define appropriate transaction boundaries, implement a Unit of Work from scratch, and integrate it effectively with the Repository pattern. These skills are essential for building robust, maintainable persistence layers in enterprise applications.

System Design (LLD)Persistence Layer Design

Unit of Work Pattern

LevelIntermediate

Duration60 mins

TopicPersistence Layer Design

4 / 4

Integration with Repositories

Two Patterns, One Architecture

The Unit of Work and Repository patterns are complementary—they work together to create a clean, testable, and maintainable persistence layer. While the previous pages focused on the Unit of Work in isolation, production applications require thoughtful integration between these two patterns. This page explores how to combine Unit of Work with Repository pattern effectively, examining ownership models, aggregate considerations, and practical integration strategies that scale from simple CRUD applications to complex domain-driven architectures.

What You Will Learn

By the end of this page, you will understand how to integrate Unit of Work with repositories, different repository access patterns, how aggregates influence repository design, testing strategies for the integrated persistence layer, and common pitfalls to avoid.

The Relationship Between Patterns

Before diving into integration strategies, let's clarify what each pattern is responsible for: Repository Pattern Responsibilities: Provides collection-like interface for domain objects Encapsulates query logic and data mapping Abstracts the underlying data store Returns domain entities, not database rows Unit of Work Responsibilities: Tracks changes across multiple entities Coordinates transaction boundaries Ensures atomicity of commits Manages entity identity and state The key insight is that these patterns address different concerns of the same problem:

Converting Mermaid diagram...

Complementary Responsibilities
Concern	Repository Handles	Unit of Work Handles
Finding entities	✅ Query logic, mapping	❌ Not involved
Adding new entities	✅ Registration interface	✅ Tracking state, commit
Updating entities	⚠️ May not have explicit API	✅ Detects changes, generates UPDATE
Deleting entities	✅ Removal interface	✅ Tracking deletion, commit
Transaction scope	❌ Not aware	✅ Owns transaction boundary
Multiple repositories	❌ Isolated per type	✅ Coordinates across all

Not Mutually Exclusive

Some developers wonder whether to use Repository OR Unit of Work. In most architectures, you use both: Repositories for data access abstraction and Unit of Work for change coordination. They serve different purposes and complement each other.

Repository Access Patterns

There are several architectural patterns for how application code accesses repositories in relation to the Unit of Work. Each has trade-offs: Pattern 1: Repositories as Properties of Unit of Work The most common pattern—repositories are accessed through the Unit of Work:

pattern-1-property-access.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
45
46
47
48
49
// Pattern 1: Repositories as UoW properties
interface IUnitOfWork {
    readonly orders: IOrderRepository;
    readonly products: IProductRepository;
    readonly customers: ICustomerRepository;
    
    commit(): Promise<void>;
    rollback(): Promise<void>;
}
 
class UnitOfWork implements IUnitOfWork {
    private _orders?: OrderRepository;
    private _products?: ProductRepository;
    private _customers?: CustomerRepository;
    private changeTracker: ChangeTracker;
    
    get orders(): IOrderRepository {
        return this._orders ??= new OrderRepository(this.changeTracker);
    }
    
    get products(): IProductRepository {
        return this._products ??= new ProductRepository(this.changeTracker);
    }
    
    get customers(): ICustomerRepository {
        return this._customers ??= new CustomerRepository(this.changeTracker);
    }
}
 
// Usage in application service:
class OrderService {
    constructor(private unitOfWork: IUnitOfWork) {}
    
    async placeOrder(command: PlaceOrderCommand): Promise<Order> {
        // Access repositories through UoW
        const customer = await this.unitOfWork.customers.findById(command.customerId);
        const products = await this.unitOfWork.products.findByIds(command.productIds);
        
        const order = Order.create(customer, products, command.quantities);
        this.unitOfWork.orders.add(order);
        
        await this.unitOfWork.commit();
        return order;
    }
}
 
// ✅ Guarantees all repositories share same change tracker
// ✅ Clear ownership hierarchy
// ⚠️ UoW interface grows with each new repository

Pattern 2: Repository Factory Use a factory to create repositories that share the same Unit of Work context:

pattern-2-factory.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
45
46
47
48
// Pattern 2: Repository Factory
interface IRepositoryFactory {
    createOrderRepository(): IOrderRepository;
    createProductRepository(): IProductRepository;
    createCustomerRepository(): ICustomerRepository;
}
 
class UnitOfWorkRepositoryFactory implements IRepositoryFactory {
    constructor(
        private changeTracker: ChangeTracker,
        private connection: DatabaseConnection
    ) {}
    
    createOrderRepository(): IOrderRepository {
        return new OrderRepository(this.changeTracker, this.connection);
    }
    
    createProductRepository(): IProductRepository {
        return new ProductRepository(this.changeTracker, this.connection);
    }
    
    createCustomerRepository(): ICustomerRepository {
        return new CustomerRepository(this.changeTracker, this.connection);
    }
}
 
// Unit of Work exposes factory
interface IUnitOfWork {
    readonly repositoryFactory: IRepositoryFactory;
    commit(): Promise<void>;
    rollback(): Promise<void>;
}
 
// Usage:
class OrderService {
    constructor(private unitOfWork: IUnitOfWork) {}
    
    async placeOrder(command: PlaceOrderCommand): Promise<Order> {
        const orderRepo = this.unitOfWork.repositoryFactory.createOrderRepository();
        const customerRepo = this.unitOfWork.repositoryFactory.createCustomerRepository();
        
        // ... rest of logic
    }
}
 
// ✅ More flexible - can create custom repositories
// ✅ UoW interface stays stable
// ⚠️ More verbose - need to call factory methods

Pattern 3: Generic Repository with Unit of Work For CRUD-heavy applications, a generic repository approach:

pattern-3-generic.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
45
46
47
48
49
50
51
52
53
54
// Pattern 3: Generic Repository Access
interface IUnitOfWork {
    getRepository<T extends Entity>(entityType: EntityType<T>): IRepository<T>;
    commit(): Promise<void>;
    rollback(): Promise<void>;
}
 
interface IRepository<T> {
    findById(id: string): Promise<T | null>;
    findAll(): Promise<T[]>;
    findBy(specification: Specification<T>): Promise<T[]>;
    add(entity: T): void;
    remove(entity: T): void;
}
 
class UnitOfWork implements IUnitOfWork {
    private repositoryCache: Map<string, IRepository<any>> = new Map();
    
    getRepository<T extends Entity>(entityType: EntityType<T>): IRepository<T> {
        const typeName = entityType.name;
        
        if (!this.repositoryCache.has(typeName)) {
            this.repositoryCache.set(
                typeName, 
                new GenericRepository<T>(entityType, this.changeTracker)
            );
        }
        
        return this.repositoryCache.get(typeName)!;
    }
}
 
// Usage:
class OrderService {
    async placeOrder(command: PlaceOrderCommand): Promise<Order> {
        const orderRepo = this.unitOfWork.getRepository(Order);
        const productRepo = this.unitOfWork.getRepository(Product);
        
        // Generic interface for common operations
        const products = await productRepo.findBy(
            new ProductIdSpecification(command.productIds)
        );
        
        const order = Order.create(/*...*/);
        orderRepo.add(order);
        
        await this.unitOfWork.commit();
        return order;
    }
}
 
// ✅ No explicit repository classes for simple CRUD
// ✅ Consistent interface across all entities
// ⚠️ Custom query methods require extending

Repository Access Pattern Comparison
Pattern	Best For	Trade-offs
Properties on UoW	Most applications, clear API	UoW interface grows with repositories
Factory Pattern	Large number of repositories	More verbose, extra indirection
Generic Repository	CRUD-heavy, uniform access	Less type safety, custom queries harder

Aggregates and Repository Design

In Domain-Driven Design, aggregates define consistency boundaries. This has profound implications for how repositories and the Unit of Work interact. The Aggregate Rule: Repositories should only exist for aggregate roots. Non-root entities within an aggregate should be accessed through their aggregate root. This rule affects both repository design and Unit of Work behavior:

Converting Mermaid diagram...

aggregate-repository.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
// ✅ CORRECT: Repository for aggregate root only
interface IOrderRepository {
    findById(id: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    add(order: Order): void;
    remove(order: Order): void;
}
 
// The Order aggregate root includes its items
class Order {
    private id: OrderId;
    private customerId: CustomerId;  // Reference by ID, not object
    private items: OrderItem[] = [];  // Owned by Order
    
    addItem(productId: ProductId, quantity: number, price: Money): void {
        const item = new OrderItem(this.id, productId, quantity, price);
        this.items.push(item);
    }
    
    removeItem(itemId: OrderItemId): void {
        this.items = this.items.filter(i => !i.id.equals(itemId));
    }
}
 
// ❌ INCORRECT: No separate repository for OrderItem
// interface IOrderItemRepository {} // Don't do this!
 
// Usage - Order controls its items
class OrderApplicationService {
    async addItemToOrder(orderId: string, productId: string, qty: number): Promise<void> {
        const order = await this.unitOfWork.orders.findById(new OrderId(orderId));
        if (!order) throw new OrderNotFoundError(orderId);
        
        const product = await this.unitOfWork.products.findById(new ProductId(productId));
        if (!product) throw new ProductNotFoundError(productId);
        
        // Order manages its own items
        order.addItem(product.id, qty, product.currentPrice);
        
        // Unit of Work tracks Order, which includes its items
        await this.unitOfWork.commit();
        // Commits: UPDATE orders, INSERT order_items (if new), etc.
    }
}

Unit of Work and Aggregate Persistence: When persisting aggregates, the Unit of Work must handle the entire object graph:

aggregate-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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// Change tracker must traverse aggregate relationships
class AggregateAwareChangeTracker extends ChangeTracker {
    /**
     * When tracking an aggregate root, also track its children
     */
    trackLoaded<T>(entity: T): void {
        super.trackLoaded(entity);
        
        const metadata = this.getMetadata(entity);
        
        // Recursively track owned entities (one-to-many, one-to-one owned)
        for (const relationship of metadata.relationships) {
            if (relationship.isOwned) {  // Part of aggregate, not just reference
                const children = this.getRelatedEntities(entity, relationship);
                for (const child of children) {
                    this.trackLoaded(child);
                }
            }
        }
    }
    
    /**
     * Detect changes in the entire aggregate
     */
    detectAggregateChanges<T>(root: T): AggregateChanges {
        const changes: AggregateChanges = {
            rootModified: this.hasChanges(root),
            addedChildren: [],
            modifiedChildren: [],
            deletedChildren: []
        };
        
        const metadata = this.getMetadata(root);
        
        for (const relationship of metadata.relationships) {
            if (relationship.isOwned) {
                const currentChildren = this.getRelatedEntities(root, relationship);
                const originalChildIds = this.getOriginalChildIds(root, relationship);
                
                for (const child of currentChildren) {
                    const childId = this.getId(child);
                    
                    if (!originalChildIds.has(childId)) {
                        changes.addedChildren.push(child);
                    } else if (this.hasChanges(child)) {
                        changes.modifiedChildren.push(child);
                    }
                }
                
                // Find deleted children
                for (const origId of originalChildIds) {
                    if (!currentChildren.some(c => this.getId(c) === origId)) {
                        changes.deletedChildren.push({ type: relationship.targetType, id: origId });
                    }
                }
            }
        }
        
        return changes;
    }
}

Aggregate Loading Strategies

When loading an aggregate, you have options: eager load the entire aggregate (simple but potentially heavy), lazy load children on access (risk of N+1 queries), or use explicit loading (caller decides what to include). Most ORMs support all three approaches.

Cross-Cutting Concerns

The integration point between Unit of Work and repositories is an excellent place to handle cross-cutting concerns like auditing, validation, and domain events. Audit Logging:

audit-integration.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
45
46
47
48
49
50
51
52
53
54
// Audit-aware Unit of Work
class AuditableUnitOfWork implements IUnitOfWork {
    private inner: IUnitOfWork;
    private auditLog: IAuditLog;
    private currentUser: User;
    
    constructor(inner: IUnitOfWork, auditLog: IAuditLog, currentUser: User) {
        this.inner = inner;
        this.auditLog = auditLog;
        this.currentUser = currentUser;
    }
    
    async commit(): Promise<void> {
        const changes = this.inner.getChanges();
        
        // Create audit entries for all changes
        for (const entry of changes.inserts) {
            await this.auditLog.log({
                entityType: entry.entityType.name,
                entityId: this.getId(entry.entity),
                action: 'CREATE',
                newValues: this.serializeEntity(entry.entity),
                userId: this.currentUser.id,
                timestamp: new Date()
            });
        }
        
        for (const entry of changes.updates) {
            await this.auditLog.log({
                entityType: entry.entityType.name,
                entityId: this.getId(entry.entity),
                action: 'UPDATE',
                oldValues: this.mapToObject(entry.originalValues),
                newValues: this.serializeEntity(entry.entity),
                userId: this.currentUser.id,
                timestamp: new Date()
            });
        }
        
        for (const entry of changes.deletes) {
            await this.auditLog.log({
                entityType: entry.entityType.name,
                entityId: this.getId(entry.entity),
                action: 'DELETE',
                oldValues: this.serializeEntity(entry.entity),
                userId: this.currentUser.id,
                timestamp: new Date()
            });
        }
        
        // Commit the actual changes
        await this.inner.commit();
    }
}

Domain Event Publishing:

domain-events-integration.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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
// Domain event-aware Unit of Work
class EventPublishingUnitOfWork implements IUnitOfWork {
    private inner: IUnitOfWork;
    private eventDispatcher: IDomainEventDispatcher;
    
    async commit(): Promise<void> {
        // Collect all domain events from entities
        const events: DomainEvent[] = [];
        
        for (const entry of this.inner.getTrackedEntities()) {
            if (entry.entity instanceof AggregateRoot) {
                events.push(...entry.entity.getDomainEvents());
            }
        }
        
        // Commit first (ensures all data is persisted)
        await this.inner.commit();
        
        // Then dispatch events (after successful commit)
        for (const event of events) {
            await this.eventDispatcher.dispatch(event);
        }
        
        // Clear events from entities
        for (const entry of this.inner.getTrackedEntities()) {
            if (entry.entity instanceof AggregateRoot) {
                entry.entity.clearDomainEvents();
            }
        }
    }
}
 
// Aggregate root base class with event support
abstract class AggregateRoot<TId> {
    private domainEvents: DomainEvent[] = [];
    
    protected addDomainEvent(event: DomainEvent): void {
        this.domainEvents.push(event);
    }
    
    getDomainEvents(): DomainEvent[] {
        return [...this.domainEvents];
    }
    
    clearDomainEvents(): void {
        this.domainEvents = [];
    }
}
 
// Usage in domain entity:
class Order extends AggregateRoot<OrderId> {
    place(): void {
        this.status = OrderStatus.Placed;
        this.placedAt = new Date();
        
        // Raise domain event
        this.addDomainEvent(new OrderPlacedEvent(this.id, this.customerId, this.total));
    }
}

Event Dispatch Timing

Events should be dispatched AFTER successful commit, not before. If commit fails, you don't want events that reference uncommitted data. Some architectures use outbox pattern: events are stored in the same transaction, then published asynchronously by a separate process.

Testing Strategies

One of the primary benefits of the Unit of Work and Repository patterns is improved testability. Here are strategies for testing at different levels: Unit Testing with In-Memory Implementations:

in-memory-uow.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
45
46
47
48
49
50
51
52
53
54
55
56
// In-memory Unit of Work for testing
class InMemoryUnitOfWork implements IUnitOfWork {
    private committed: boolean = false;
    public readonly orders: InMemoryOrderRepository;
    public readonly products: InMemoryProductRepository;
    public readonly customers: InMemoryCustomerRepository;
    
    constructor() {
        const tracker = new InMemoryChangeTracker();
        this.orders = new InMemoryOrderRepository(tracker);
        this.products = new InMemoryProductRepository(tracker);
        this.customers = new InMemoryCustomerRepository(tracker);
    }
    
    async commit(): Promise<void> {
        // In-memory: just mark as committed
        // Changes are already reflected in the collections
        this.committed = true;
    }
    
    async rollback(): Promise<void> {
        // Could implement actual rollback if needed
        this.committed = false;
    }
    
    wasCommitted(): boolean {
        return this.committed;
    }
}
 
class InMemoryOrderRepository implements IOrderRepository {
    private orders: Map<string, Order> = new Map();
    
    async findById(id: string): Promise<Order | null> {
        return this.orders.get(id) || null;
    }
    
    add(order: Order): void {
        this.orders.set(order.id, order);
    }
    
    remove(order: Order): void {
        this.orders.delete(order.id);
    }
    
    // Test helpers
    getAll(): Order[] {
        return Array.from(this.orders.values());
    }
    
    seed(orders: Order[]): void {
        for (const order of orders) {
            this.orders.set(order.id, order);
        }
    }
}

Writing Unit Tests:

unit-tests.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
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
// Unit test example
describe('OrderApplicationService', () => {
    let unitOfWork: InMemoryUnitOfWork;
    let service: OrderApplicationService;
    
    beforeEach(() => {
        unitOfWork = new InMemoryUnitOfWork();
        service = new OrderApplicationService(unitOfWork);
    });
    
    describe('placeOrder', () => {
        it('should create order with items and commit', async () => {
            // Arrange: Seed test data
            const customer = new Customer('cust-1', 'John Doe');
            const product = new Product('prod-1', 'Widget', Money.of(25));
            
            unitOfWork.customers.seed([customer]);
            unitOfWork.products.seed([product]);
            
            // Act
            const command = new PlaceOrderCommand({
                customerId: 'cust-1',
                items: [{ productId: 'prod-1', quantity: 2 }]
            });
            
            const result = await service.placeOrder(command);
            
            // Assert
            expect(result.isSuccess).toBe(true);
            expect(unitOfWork.wasCommitted()).toBe(true);
            
            const savedOrders = unitOfWork.orders.getAll();
            expect(savedOrders).toHaveLength(1);
            expect(savedOrders[0].items).toHaveLength(1);
            expect(savedOrders[0].items[0].quantity).toBe(2);
        });
        
        it('should not commit if customer not found', async () => {
            // Act
            const command = new PlaceOrderCommand({
                customerId: 'non-existent',
                items: [{ productId: 'prod-1', quantity: 1 }]
            });
            
            const result = await service.placeOrder(command);
            
            // Assert
            expect(result.isFailure).toBe(true);
            expect(result.error.code).toBe('CUSTOMER_NOT_FOUND');
            expect(unitOfWork.wasCommitted()).toBe(false);
            expect(unitOfWork.orders.getAll()).toHaveLength(0);
        });
        
        it('should rollback on inventory error', async () => {
            // Arrange: Product with insufficient inventory
            const customer = new Customer('cust-1', 'John Doe');
            const product = new Product('prod-1', 'Widget', Money.of(25));
            product.setInventory(1);  // Only 1 available
            
            unitOfWork.customers.seed([customer]);
            unitOfWork.products.seed([product]);
            
            // Act: Try to order 10
            const command = new PlaceOrderCommand({
                customerId: 'cust-1',
                items: [{ productId: 'prod-1', quantity: 10 }]
            });
            
            const result = await service.placeOrder(command);
            
            // Assert
            expect(result.isFailure).toBe(true);
            expect(result.error.code).toBe('INSUFFICIENT_INVENTORY');
            expect(unitOfWork.wasCommitted()).toBe(false);
        });
    });
});

Integration Testing with Real Database:

integration-tests.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
45
46
47
48
49
50
51
52
53
54
55
56
57
// Integration test with real database
describe('OrderApplicationService Integration', () => {
    let unitOfWorkFactory: () => IUnitOfWork;
    
    beforeAll(async () => {
        // Setup test database
        await TestDatabase.setup();
        unitOfWorkFactory = () => new UnitOfWork(TestDatabase.createConnection());
    });
    
    afterAll(async () => {
        await TestDatabase.teardown();
    });
    
    beforeEach(async () => {
        // Clean data between tests
        await TestDatabase.truncateAll();
    });
    
    it('should persist order across repository boundaries', async () => {
        const unitOfWork = unitOfWorkFactory();
        const service = new OrderApplicationService(unitOfWork);
        
        // Seed data using the same UoW
        const customer = new Customer('cust-1', 'Jane Doe');
        unitOfWork.customers.add(customer);
        
        const product = new Product('prod-1', 'Gadget', Money.of(99.99));
        product.setInventory(100);
        unitOfWork.products.add(product);
        
        await unitOfWork.commit();
        
        // Create order
        const freshUnitOfWork = unitOfWorkFactory();
        const freshService = new OrderApplicationService(freshUnitOfWork);
        
        const result = await freshService.placeOrder(new PlaceOrderCommand({
            customerId: 'cust-1',
            items: [{ productId: 'prod-1', quantity: 5 }]
        }));
        
        expect(result.isSuccess).toBe(true);
        
        // Verify with yet another UoW (different connection)
        const verifyUnitOfWork = unitOfWorkFactory();
        const savedOrder = await verifyUnitOfWork.orders.findById(result.value.id);
        
        expect(savedOrder).not.toBeNull();
        expect(savedOrder!.items).toHaveLength(1);
        expect(savedOrder!.items[0].quantity).toBe(5);
        
        // Verify inventory was decremented
        const product2 = await verifyUnitOfWork.products.findById('prod-1');
        expect(product2!.inventory).toBe(95);  // 100 - 5
    });
});

Test Pyramid

Use mostly unit tests with in-memory implementations (fast, isolated), fewer integration tests with real database (verify SQL/mapping), and minimal end-to-end tests (verify full stack). The abstraction provided by Unit of Work and Repository patterns enables this pyramid.

Common Pitfalls and Solutions

The integration of Unit of Work and Repository patterns can introduce subtle issues. Here are common pitfalls and how to avoid them:

Pitfall 1: Multiple Unit of Work Instances

•Problem: Different services or repositories get different UoW instances
•Symptom: Changes made in one service aren't visible to another; commit doesn't save all changes
•Solution: Use scoped DI lifetime; all services in a request share one UoW instance

pitfall-1-solution.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// ❌ WRONG: Creating new UoW per repository
class OrderService {
    async placeOrder(command: PlaceOrderCommand): Promise<void> {
        const orderUoW = new UnitOfWork();  // New instance
        const productUoW = new UnitOfWork(); // Different instance!
        
        // These don't share change tracker - disaster!
    }
}
 
// ✅ CORRECT: Injected scoped UoW
services.addScoped<IUnitOfWork, UnitOfWork>();
 
class OrderService {
    constructor(private unitOfWork: IUnitOfWork) {} // Injected, shared
    
    async placeOrder(command: PlaceOrderCommand): Promise<void> {
        // All repositories from unitOfWork share same context
    }
}

Pitfall 2: Forgetting to Commit

•Problem: Changes are tracked but never committed
•Symptom: Tests pass (in-memory), production loses data
•Solution: Use transaction decorator, or always commit in finally block

Pitfall 3: Leaking Entity References

•Problem: Returning tracked entities from service, then modifying outside UoW scope
•Symptom: Unexpected changes persisted, or changes lost
•Solution: Return DTOs from services, or detach entities before returning

Pitfall 4: Lazy Loading After Dispose

•Problem: Accessing navigation property after UoW is disposed
•Symptom: 'ObjectDisposedException' or null reference
•Solution: Eager load needed data, or ensure UoW lives long enough

Pitfall 5: Repository Bypassing Change Tracker

•Problem: Repository executes raw SQL that doesn't go through change tracker
•Symptom: Identity map is stale; changes overwritten
•Solution: Clear change tracker after raw SQL, or reload affected entities

Summary: Integration with Repositories

We've explored how to effectively integrate the Unit of Work and Repository patterns. Let's consolidate the key insights:

Key Takeaways

•UoW and Repository are complementary — Repository handles data access abstraction, Unit of Work handles change coordination
•Choose appropriate access pattern — Properties on UoW for most cases, Factory for many repositories, Generic for CRUD-heavy apps
•Aggregates define repository boundaries — Only aggregate roots get repositories; children are accessed through their root
•Leverage integration for cross-cutting concerns — Auditing, domain events, and validation fit naturally at the UoW commit boundary
•Embrace testability — In-memory implementations enable fast unit tests; integration tests verify database behavior
•Avoid common pitfalls — Shared UoW per request, always commit, don't leak tracked entities

Best Practices Summary

•Scoped DI lifetime for Unit of Work
•Access repositories through UoW
•Repository per aggregate root only
•Domain events dispatched after commit
•Return DTOs from application services

Anti-Patterns to Avoid

•Creating UoW per repository
•Repositories independent of UoW
•Repository for every entity type
•Events dispatched before commit
•Returning tracked entities outside UoW scope

Module Complete

Congratulations! You've completed the Unit of Work Pattern module. You now understand how to manage multiple database changes atomically, define appropriate transaction boundaries, implement a Unit of Work from scratch, and integrate it effectively with the Repository pattern. These skills are essential for building robust, maintainable persistence layers in enterprise applications.

Integration with Repositories

Two Patterns, One Architecture

The Relationship Between Patterns

Repository Access Patterns

Aggregates and Repository Design

Cross-Cutting Concerns

Testing Strategies

Common Pitfalls and Solutions

Summary: Integration with Repositories

There’s more to understand.

Integration with Repositories

Two Patterns, One Architecture

The Relationship Between Patterns

Repository Access Patterns

Aggregates and Repository Design

Cross-Cutting Concerns

Testing Strategies

Common Pitfalls and Solutions

Summary: Integration with Repositories

There’s more to understand.