Repository and unit of work

When business logic directly constructs SQL queries or document database calls, domain rules become inextricably tangled with persistence libraries. Swapping from PostgreSQL to DynamoDB or writing fast in-memory unit tests becomes impossible without spinning up real database containers. Furthermore, without a transaction coordinator, partial database updates leave the database in an inconsistent state.

The problem

1 // Tangled business logic and raw SQL:
2 class OrderService {
3   async completeOrder(orderId) {
4     // Domain rules mixed with DB drivers
5     const [row] = await db.query("SELECT * FROM orders WHERE id = $1", [orderId]);
6     if (row.status !== "PENDING") throw new Error("Invalid state");
7     await db.query("UPDATE orders SET status = $1 WHERE id = $2", ["PAID", orderId]);
8     await db.query("UPDATE inventory SET stock = stock - 1 WHERE sku = $1", [row.sku]);
9     // If the 2nd query fails, orders is marked PAID but stock was not deducted!
10   }
11 }

The pattern

The Repository pattern provides an in-memory collection-like interface (findById, save, delete) for domain entities. Domain services interact with the repository without knowing whether data is backed by Postgres, MongoDB, or an in-memory mock.

The Unit of Work pattern keeps track of all dirty, new, and deleted entities within a business transaction, committing all changes in one atomic database operation.

In code

When to use it, and when not to

Use Repository and Unit of Work when:

• You are developing complex domain logic with Domain-Driven Design (DDD) where domain models should remain decoupled from persistence libraries.
• You need to mock data layers easily for unit tests without running real databases.
• You want to batch database writes or ensure transactional consistency across multiple mutated aggregate roots.

Don't use Repository and Unit of Work when:

• You are building a simple CRUD or reporting application: active record patterns (e.g. Prisma, TypeORM, Rails ActiveRecord) or direct query builders are simpler and faster.

Where you have already seen it

In Java, Hibernate / JPA's EntityManager is the quintessential Unit of Work and Repository implementation. In modern TypeScript, MikrORM and TypeORM provide explicit EntityManager.flush() and repository patterns. In Spring Data, JpaRepository and CrudRepository define repository interfaces implemented at runtime.

Related patterns

• Repository vs DAO: A Data Access Object maps closely to database tables. A Repository operates on domain aggregates.
• Unit of Work vs Memento: Unit of Work can use Mementos to track original entity states for dirty checking during commit.