6c:T4b0,// ⚠️ 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(); } }6d:T568,// Core Unit of Work interface interface UnitOfWork { // Registration methods registerNew(entity: T): void; registerDirty(entity: T): void; registerDeleted(entity: T): void; registerClean(entity: T): void; // Commit/rollback commit(): Promise; rollback(): void; // Query support (often through repositories) getRepository(entityType: EntityType): Repository; } // 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(); }6e:T49a,// 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); } }6f:T44e,// Caller explicitly registers each change class ExplicitUnitOfWork { private newEntities: Set = new Set(); private dirtyEntities: Set = new Set(); private deletedEntities: Set = 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 objects70:T520,class SnapshotUnitOfWork { private snapshots: Map = new Map(); private identityMap: Map = 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 { 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/CPU71:T4e2,class ProxyUnitOfWork { private dirtySet: Set = new Set(); track(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(entity: T): T { // When loading from DB, wrap in tracking proxy return this.track(entity); } } // Usage: async function getProduct(id: string): Promise { 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 operations65:{"json":{"id":"seed_105307276000315fdc47f11845a6546d","slug":"unit-of-work-pattern","category":"System Design (LLD)","topic":"Persistence Layer Design","title":"Unit of Work Pattern","description":"Master the Unit of Work pattern for coordinating multiple database changes as a single atomic operation. Learn how to manage transaction boundaries, track entity changes, and integrate with the Repository pattern for clean, efficient persistence logic.","difficulty":"INTERMEDIATE","estimatedMinutes":60,"pages":[{"id":"seed_6a359b3afc83976262170462d493745d","title":"Managing Multiple Changes","order":0,"content":[{"id":"opening-hook","title":"The Coordination Challenge","content":[{"data":{"content":"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:\n\n1. Create a new Order record\n2. Create multiple OrderItem records (one per product)\n3. Update Product inventory levels for each item\n4. Decrease the customer's loyalty points (if used)\n5. Create a Payment record\n6. Update the Customer's order history statistics\n\nThat'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?**\n\nYou'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."},"type":"text"},{"data":{"icon":"Target","title":"What You Will Learn","content":"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.","variant":"info"},"type":"callout"}]},{"id":"nature-of-multi-change","title":"The Nature of Multi-Change Operations","content":[{"data":{"content":"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.\n\n**Why Business Operations Span Multiple Changes**\n\nConsider the domain model for a simple order:\n\n- An **Order** aggregates multiple **OrderItems**\n- Each **OrderItem** references a **Product** \n- The **Order** belongs to a **Customer**\n- A **Payment** is associated with the **Order**\n- The **Customer** may use **LoyaltyPoints**\n\nWhen 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."},"type":"text"},{"data":{"rows":[["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"]],"caption":"Business Operations and Their Database Impact","headers":["Business Operation","Domain Objects Affected","Database Tables Modified","Typical Change Count"]},"type":"table"},{"data":{"icon":"Info","title":"The Object-Relational Impedance Mismatch","content":"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.","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":1},{"id":"naive-approaches-fail","title":"Why Naive Approaches Fail","content":[{"data":{"content":"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.\n\n**Approach 1: Independent Saves**\n\nThe most naive approach is to save each entity independently:"},"type":"text"},{"data":{"fileName":"naive-independent-saves.ts","languages":[{"code":"// ❌ PROBLEMATIC: Each save is independent\nasync function placeOrder(orderData: OrderData) {\n // What if this fails?\n const order = await orderRepository.save(new Order(orderData));\n \n // We've already saved the order, but now items fail...\n for (const item of orderData.items) {\n await orderItemRepository.save(new OrderItem(order.id, item));\n // If this fails on item 3, we have partial data!\n }\n \n // What if inventory update fails after items are saved?\n for (const item of orderData.items) {\n await productRepository.decrementInventory(item.productId, item.quantity);\n }\n \n // Payment might fail after everything else succeeded\n await paymentRepository.save(new Payment(order.id, orderData.paymentDetails));\n \n // Customer update might fail too\n await customerRepository.updateOrderStats(orderData.customerId);\n}","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"content":"**Failure Points and Consequences:**"},"type":"text"},{"data":{"rows":[["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"]],"headers":["Failure Point","Data State After Failure"]},"type":"table"},{"data":{"content":"Each of these leaves the database in an **inconsistent state** that violates business rules."},"type":"text"},{"data":{"content":"**Approach 2: Manual Transaction Boundaries**\n\nA more sophisticated but still flawed approach is manual transaction management:"},"type":"text"},{"data":{"fileName":"manual-transaction.ts","languages":[{"code":"$6c","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"content":"This approach solves atomicity—if anything fails, everything rolls back. But it introduces new problems:"},"type":"text"},{"data":{"items":["**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"],"title":{"icon":"AlertCircle","text":"Problems with Manual Transaction Management","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"glass"},"type":"list"},{"data":{"icon":"AlertCircle","title":"The Core Issue","content":"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.","variant":"warning"},"type":"callout"}],"titleType":"number","titleNumber":2},{"id":"persistence-problem-depth","title":"The Persistence Problem in Depth","content":[{"data":{"content":"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:\n\n**Question 1: When Do Changes Get Persisted?**\n\nConsider this scenario:"},"type":"text"},{"data":{"fileName":"when-to-persist.ts","languages":[{"code":"// Business logic operates on domain objects\nfunction processOrder(order: Order) {\n order.markAsProcessing(); // Should this persist immediately?\n order.addNote(\"Beginning processing\");\n \n for (const item of order.items) {\n item.allocateFromInventory(); // When should THIS persist?\n }\n \n order.calculateTotals();\n order.markAsReady(); // Only persist now? Or earlier?\n}\n\n// Three possible strategies:\n// 1. Immediate: Each method call persists instantly (expensive, no atomicity)\n// 2. Explicit: Caller manually saves (easy to forget, scattered logic)\n// 3. Deferred: Something tracks changes and persists later (Unit of Work)","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"content":"**Question 2: What Gets Persisted?**\n\nWhen we modify an object, what constitutes a \"change\" that needs persistence?"},"type":"text"},{"data":{"items":["**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"],"title":"Types of Changes to Track","variant":"accent"},"type":"list"},{"data":{"content":"**Question 3: How Do We Ensure Atomicity?**\n\nAll changes from a business operation must succeed or fail together. This requires:"},"type":"text"},{"data":{"type":"ordered","items":["**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"],"title":"Atomicity Requirements","variant":"accent"},"type":"list"},{"data":{"fileName":"atomicity-challenge.ts","languages":[{"code":"// The ordering challenge: dependency graph determines SQL order\n// \n// Domain model (objects reference each other freely):\n// Order ←──→ Customer\n// ↓\n// OrderItem ←──→ Product\n// ↓\n// Payment ←──→ Order\n//\n// Database (foreign keys enforce insertion order):\n// 1. INSERT customers (if new)\n// 2. INSERT orders (needs customer_id)\n// 3. INSERT order_items (needs order_id, product_id)\n// 4. UPDATE products (inventory)\n// 5. INSERT payments (needs order_id)\n//\n// Who manages this ordering? The calling code? Every caller?\n// That's error-prone and duplicative. We need something centralized.","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"icon":"Lightbulb","title":"The Three Pillars of Persistence","content":"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.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":3},{"id":"introducing-unit-of-work","title":"Introducing the Unit of Work Pattern","content":[{"data":{"content":"The Unit of Work pattern, as defined by Martin Fowler in \"Patterns of Enterprise Application Architecture,\" is:\n\n> *\"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.\"*\n\nIn 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."},"type":"text"},{"data":{"height":"550px","className":"max-w-5xl mx-auto","mermaidSyntax":"flowchart TB\n subgraph Business[\"Business Operation\"]\n A[Load Order] --> B[Modify Order]\n B --> C[Create OrderItem]\n C --> D[Update Inventory]\n D --> E[Create Payment]\n end\n \n subgraph UoW[\"Unit of Work (Change Tracker)\"]\n F[Track: Order MODIFIED]\n G[Track: OrderItem NEW]\n H[Track: Product MODIFIED]\n I[Track: Payment NEW]\n end\n \n subgraph Commit[\"Commit Phase\"]\n J[Begin Transaction]\n J --> K[UPDATE orders]\n K --> L[INSERT order_items]\n L --> M[UPDATE products]\n M --> N[INSERT payments]\n N --> O[Commit Transaction]\n end\n \n B -.->|Register| F\n C -.->|Register| G\n D -.->|Register| H\n E -.->|Register| I\n \n F --> J\n G --> J\n H --> J\n I --> J"},"type":"mermaid-excalidraw"},{"data":{"content":"**The Key Responsibilities of a Unit of Work:**\n\nThe Unit of Work pattern centralizes several critical responsibilities that would otherwise be scattered across the codebase:"},"type":"text"},{"data":{"items":["**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"],"title":{"icon":"CheckCircle","text":"Unit of Work Responsibilities","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"fileName":"unit-of-work-interface.ts","languages":[{"code":"$6d","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"icon":"Info","title":"Implicit vs. Explicit Registration","content":"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.","variant":"note"},"type":"callout"}],"titleType":"number","titleNumber":4},{"id":"benefits-centralized","title":"Benefits of Centralized Change Management","content":[{"data":{"content":"The Unit of Work pattern isn't just about transaction management—it provides architectural benefits that improve the entire persistence layer."},"type":"text"},{"data":{"left":[{"data":{"items":["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"],"title":{"icon":"XCircle","text":"Without Unit of Work","type":"icon","color":"destructive","variant":"outline-circle"},"variant":"glass"},"type":"list"}],"right":[{"data":{"items":["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"],"title":{"icon":"CheckCircle","text":"With Unit of Work","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"}]},"type":"two-column"},{"data":{"content":"**Performance Optimization Opportunities**\n\nBecause the Unit of Work accumulates changes before committing, it can optimize operations that would be inefficient if done immediately:"},"type":"text"},{"data":{"fileName":"optimization-opportunities.ts","languages":[{"code":"$6e","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"icon":"Lightbulb","title":"The Write-Behind Pattern","content":"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).","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":5},{"id":"change-tracking-strategies","title":"Change Tracking Strategies","content":[{"data":{"content":"A Unit of Work must know which entities have changed and how. There are several strategies for change tracking, each with different trade-offs:\n\n**Strategy 1: Caller Registration**\n\nThe simplest approach requires the caller to explicitly register changes:"},"type":"text"},{"data":{"fileName":"caller-registration.ts","languages":[{"code":"$6f","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"content":"**Strategy 2: Snapshot Comparison**\n\nTake a snapshot of entity state when loaded, compare on commit:"},"type":"text"},{"data":{"fileName":"snapshot-comparison.ts","languages":[{"code":"$70","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"content":"**Strategy 3: Proxy-Based Tracking**\n\nWrap entities in proxies that intercept property changes:"},"type":"text"},{"data":{"fileName":"proxy-tracking.ts","languages":[{"code":"$71","label":"TypeScript","value":"typescript"}]},"type":"code"},{"data":{"rows":[["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"]],"caption":"Change Tracking Strategy Comparison","headers":["Strategy","Automatic?","Memory Overhead","CPU Overhead","Complexity","Use Case"]},"type":"table"}],"titleType":"number","titleNumber":6},{"id":"summary-key-takeaways","title":"Summary: Managing Multiple Changes","content":[{"data":{"content":"We've established the foundation for understanding the Unit of Work pattern. Let's consolidate the key insights:"},"type":"text"},{"data":{"type":"ordered","items":["**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"],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's Next:**\n\nNow 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."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"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.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":7}],"isLocked":false},{"id":"seed_c9b33d253566f3a2c03cd29e2c5b4f48","title":"Transaction Boundaries","order":1,"content":null,"isLocked":true},{"id":"seed_5698210cb5ce73e91032f53bcbcd6992","title":"Unit of Work Implementation","order":2,"content":null,"isLocked":true},{"id":"seed_7f02fe443f5c58a4b21cbf8f528f3654","title":"Integration with Repositories","order":3,"content":null,"isLocked":true}]}}