Repositories - Learning Module

Loading content...

0/246

Repository Interface Design

The Contract That Shapes Your Domain

The repository interface is perhaps the most important surface in your domain layer. It defines the contract between your domain logic and the outside world of persistence. A well-designed repository interface empowers domain services to express business operations cleanly. A poorly designed one leaks infrastructure concerns throughout your codebase.

This is not merely about method signatures—it's about creating an API that speaks the language of the domain. Every method name, every parameter type, every return value sends a message about what your domain cares about. The interface should be so expressive that someone reading it understands the domain's persistence needs without ever seeing the implementation.

What You Will Learn

This page covers the principles and practices of repository interface design. You'll learn how to name methods, choose parameter and return types, handle null/absent values, balance specificity with genericity, and avoid common design mistakes.

Interface Location and Structure

Before diving into method design, let's establish where repository interfaces live and how they're structured.

Location: Domain Layer

Repository interfaces are defined in the domain layer. This is non-negotiable in DDD. The interface represents what the domain needs from persistence, not what a database provides. By placing it in the domain layer, we achieve:

Dependency inversion — The domain defines the abstraction; infrastructure provides the implementation.
Domain purity — No infrastructure dependencies pollute the domain.
Testability — Domain code can be tested with simple in-memory implementations.

Interface Placement

Folder Structure

src/
├── domain/
│   ├── model/
│   │   └── order/
│   │       ├── Order.ts           # Aggregate root
│   │       ├── OrderId.ts         # Value object (identity)
│   │       ├── OrderItem.ts       # Entity within aggregate
│   │       └── OrderStatus.ts     # Value object (enum-like)
│   │
│   └── repository/                # Repository interfaces live here
│       ├── OrderRepository.ts     # Interface for Order aggregate
│       └── CustomerRepository.ts  # Interface for Customer aggregate
│
├── infrastructure/
│   └── persistence/
│       ├── OrderRepositoryImpl.ts # Implementation (SQL/ORM)
│       └── CustomerRepositoryImpl.ts
│
└── application/
    └── services/
        └── OrderApplicationService.ts  # Uses repository interfaces

Naming Conventions

The interface should clearly communicate its role:

Interface name: OrderRepository (not IOrderRepository or OrderRepositoryInterface)
Implementation name: PostgresOrderRepository, MongoOrderRepository, or simply OrderRepositoryImpl

The prefix/suffix conventions vary by language and team. The key point is that the domain code references the interface, never the implementation.

Repository Interface Template
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
// domain/repository/OrderRepository.ts
 
import { Order } from '../model/order/Order';
import { OrderId } from '../model/order/OrderId';
import { CustomerId } from '../model/customer/CustomerId';
 
/**
 * Repository for Order aggregates.
 * 
 * Provides collection-like access to all orders in the system.
 * Implementations handle actual persistence to various storage backends.
 */
export interface OrderRepository {
    // ---------- Identity-based retrieval ----------
    
    /**
     * Finds an order by its unique identifier.
     * @returns The order if found, null otherwise
     */
    findById(orderId: OrderId): Promise<Order | null>;
    
    // ---------- Domain query methods ----------
    
    /**
     * Finds all orders placed by a specific customer.
     */
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    
    /**
     * Finds all orders awaiting processing.
     */
    findPendingOrders(): Promise<Order[]>;
    
    // ---------- Existence checks ----------
    
    /**
     * Checks if an order with the given ID exists.
     */
    exists(orderId: OrderId): Promise<boolean>;
    
    // ---------- Collection operations ----------
    
    /**
     * Adds a new order to the repository.
     * @throws If an order with the same ID already exists
     */
    add(order: Order): Promise<void>;
    
    /**
     * Removes an order from the repository.
     */
    remove(order: Order): Promise<void>;
}

Method Naming Principles

Method names are the primary way repository interfaces communicate domain intent. Thoughtful naming elevates the interface from a data access tool to a domain-aligned contract.

Principle 1: Use Domain Language

Method names should use terminology from the ubiquitous language of your bounded context. If domain experts talk about "pending orders," your method is findPendingOrders(), not findByStatus('PENDING').

Domain-Aligned Names

•findPendingOrders()
•findOverdueInvoices()
•findActiveSubscriptions()
•findExpiredTrials()
•findOrdersAwaitingShipment()

Database-Aligned Names (Avoid)

•findByStatusEquals('PENDING')
•findByDueDateBefore(now)
•findByActiveTrue()
•findByTrialEndDateBefore(now)
•findByStatusAndShippedAtNull()

Principle 2: Prefer Specific Methods Over Generic Parameters

Rather than creating a generic findBy(criteria) method, create specific methods for each domain use case. Specific methods:

Document the actual use cases of the system
Are easier to optimize per-query
Prevent ad-hoc queries that might not be performant
Make the interface self-documenting

Specific vs Generic
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// ✅ GOOD: Specific methods for each use case
interface OrderRepository {
    findPendingOrders(): Promise<Order[]>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    findOrdersPlacedBetween(start: Date, end: Date): Promise<Order[]>;
    findHighValueOrders(minimumTotal: Money): Promise<Order[]>;
}
 
// ❌ AVOID: Generic query methods
interface OrderRepository {
    // This leaks query concerns into the domain
    findBy(criteria: QueryCriteria): Promise<Order[]>;
    
    // This exposes SQL concepts
    findBySpecification(spec: Specification<Order>): Promise<Order[]>;
    
    // This is too flexible - encourages unpredictable queries
    query(filter: Partial<OrderFilter>): Promise<Order[]>;
}

When Flexibility Is Needed

If your domain genuinely needs flexible querying (e.g., a search feature with many optional filters), consider the Specification pattern or a separate Query Service outside the repository. Keep the repository focused on aggregate persistence.

Principle 3: Use Consistent Verb Prefixes

Establish consistent naming conventions across all repositories:

Prefix	Meaning	Example
`findById`	Retrieve by identity	`findById(OrderId)`
`findXxx`	Query returning multiple	`findPendingOrders()`
`get`	Retrieve, throw if missing	`getById(OrderId)`
`exists`	Check existence	`exists(OrderId)`
`count`	Count aggregates	`countPendingOrders()`
`add`	Insert new aggregate	`add(Order)`
`remove`	Delete aggregate	`remove(Order)`
`save`	Persist changes (if used)	`save(Order)`

Parameter and Return Type Design

The types used in repository method signatures significantly impact interface quality. Every type choice should reinforce domain concepts and prevent programming errors.

Use Value Objects for Identities

Never use primitive types (string, number) for aggregate identities. Use typed value objects that prevent mix-ups and express domain meaning.

Typed Identities
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
// ❌ WEAK: Primitive identities
interface OrderRepository {
    findById(orderId: string): Promise<Order | null>;
    findByCustomer(customerId: string): Promise<Order[]>;
}
 
// Problems:
// - Easy to pass wrong ID type: findById(customerId) compiles fine
// - No domain meaning: it's just a string
// - No validation: any string is accepted
 
// ✅ STRONG: Value object identities
interface OrderRepository {
    findById(orderId: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
}
 
// Benefits:
// - Type safety: findById(customerId) won't compile
// - Domain clarity: OrderId expresses what it represents
// - Validation: OrderId constructor can validate format
 
// Value object implementation
class OrderId {
    private constructor(private readonly value: string) {}
    
    static create(value: string): OrderId {
        if (!value || value.trim() === '') {
            throw new InvalidOrderIdError(value);
        }
        return new OrderId(value);
    }
    
    get id(): string {
        return this.value;
    }
    
    equals(other: OrderId): boolean {
        return this.value === other.value;
    }
}

Return Complete Aggregates, Not Fragments

Repository methods that retrieve aggregates must return complete aggregates—the root plus all entities and value objects within the aggregate boundary. Returning partial aggregates violates aggregate invariants.

Complete Aggregate Returns
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ✅ CORRECT: Returns complete aggregate
interface OrderRepository {
    findById(orderId: OrderId): Promise<Order | null>;
    // Order includes OrderItems, ShippingAddress, PaymentInfo, etc.
}
 
// ❌ WRONG: Returns partial data
interface OrderRepository {
    // Don't do this - breaks aggregate boundaries
    findOrderWithoutItems(orderId: OrderId): Promise<PartialOrder | null>;
    
    // Don't do this - items should be accessed through the aggregate
    findItemsByOrder(orderId: OrderId): Promise<OrderItem[]>;
    
    // Don't do this - address is part of Order aggregate
    findShippingAddress(orderId: OrderId): Promise<ShippingAddress | null>;
}

Read Models for Projections

If you need partial or projected data for display purposes (e.g., an order summary without items), use CQRS read models or projection services—not repositories. Repositories are for command-side aggregate access.

Handle Absence Explicitly

When an aggregate might not exist, make the absence explicit in the return type. Different languages have different idioms:

TypeScript/JavaScript: T | null or T | undefined
Java: Optional<T>
C#: T? (nullable reference types)
Kotlin: T?

Explicit Absence Handling
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
interface OrderRepository {
    // Explicitly nullable - caller must handle absence
    findById(orderId: OrderId): Promise<Order | null>;
    
    // Throws if not found - use when absence is exceptional
    getById(orderId: OrderId): Promise<Order>;
}
 
// Usage patterns:
class OrderService {
    async cancelOrder(orderId: OrderId): Promise<void> {
        // Using findById - we handle the null case
        const order = await this.orderRepository.findById(orderId);
        if (!order) {
            throw new OrderNotFoundException(orderId);
        }
        order.cancel();
    }
    
    async processNextPendingOrder(): Promise<void> {
        // Using getById - absence would be a bug, not expected
        const order = await this.orderRepository.getById(this.queuedOrderId);
        order.process();
    }
}

Query Method Design Patterns

Beyond basic CRUD, repositories expose query methods tailored to domain needs. Here are proven patterns for designing these queries.

Pattern 1: Finder Methods

Finder methods return collections of aggregates matching specific criteria. They encapsulate filtering logic and return domain objects.

Finder Methods
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
interface OrderRepository {
    // Simple finders - return all matching
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    findPendingOrders(): Promise<Order[]>;
    
    // Parameterized finders
    findOrdersPlacedAfter(date: Date): Promise<Order[]>;
    findOrdersWithTotalAbove(minimum: Money): Promise<Order[]>;
    
    // Compound criteria
    findPendingOrdersForCustomer(customerId: CustomerId): Promise<Order[]>;
    
    // Ordering (when domain-relevant)
    findMostRecentOrders(limit: number): Promise<Order[]>;
}

Pattern 2: Existence Checks

When you only need to know if an aggregate exists—not retrieve it—use explicit existence methods. These are more efficient than retrieving and checking for null.

Existence Checks
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
interface OrderRepository {
    // Simple existence
    exists(orderId: OrderId): Promise<boolean>;
    
    // Domain-meaningful existence
    hasCustomerPlacedOrderBefore(customerId: CustomerId): Promise<boolean>;
    hasUnshippedOrders(customerId: CustomerId): Promise<boolean>;
}
 
// Usage
class CustomerService {
    async determineCustomerTier(customerId: CustomerId): Promise<CustomerTier> {
        // Efficient - doesn't load any orders
        const hasOrdered = await this.orderRepository
            .hasCustomerPlacedOrderBefore(customerId);
        
        return hasOrdered ? CustomerTier.RETURNING : CustomerTier.NEW;
    }
}

Pattern 3: Count Methods

Similar to existence, count methods return aggregate counts without loading data. Use when counts have domain meaning.

Count Methods
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
interface OrderRepository {
    // Simple counting
    countPendingOrders(): Promise<number>;
    countByCustomer(customerId: CustomerId): Promise<number>;
    
    // Domain-specific counting
    countUnfulfilledOrdersForDate(date: Date): Promise<number>;
}
 
// Usage - domain logic that needs counts
class FulfillmentCapacityService {
    async canAcceptNewOrders(): Promise<boolean> {
        const pending = await this.orderRepository.countPendingOrders();
        return pending < this.maxCapacity;
    }
}

Counts for Reporting

If you need counts primarily for dashboards or reporting, consider dedicated read models rather than repository methods. Repositories serve the command side; complex analytics belong in separate query services.

What NOT to Include

Knowing what to exclude from repository interfaces is as important as knowing what to include. Several common additions actually degrade interface quality.

Anti-Patterns to Avoid

•Generic query methods — findBy(criteria) or query(filter) leak query construction into domain code.
•Raw SQL exposure — executeQuery(sql) completely breaks the abstraction.
•Batch operations — updateAll(predicate, changes) bypasses aggregates and their invariants.
•Transaction methods — beginTransaction(), commit() belong to Unit of Work, not repository.
•Connection management — getConnection(), close() are infrastructure concerns.
•Pagination primitives — findAll(page, size) is database-centric; prefer domain-meaningful limits.

Anti-Pattern Examples
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// ❌ ANTI-PATTERNS - Don't include these
 
interface BadOrderRepository {
    // Exposes query language
    findByQuery(jpql: string): Promise<Order[]>;
    executeNativeQuery(sql: string): Promise<unknown>;
    
    // Bypasses aggregates
    updateStatus(orderId: OrderId, status: OrderStatus): Promise<void>;
    updateAllExpiredOrders(): Promise<number>;
    bulkDelete(orderIds: OrderId[]): Promise<void>;
    
    // Transaction management
    beginTransaction(): Promise<void>;
    commit(): Promise<void>;
    rollback(): Promise<void>;
    
    // Infrastructure leakage
    getConnection(): DatabaseConnection;
    setQueryTimeout(ms: number): void;
    enableCache(): void;
    
    // Over-generic operations
    findByCriteria(criteria: Record<string, unknown>): Promise<Order[]>;
    findByExample(example: Partial<Order>): Promise<Order[]>;
}

Why Batch Operations Are Problematic

Batch update/delete operations like updateAll() or deleteWhere() are tempting for performance, but they:

Bypass domain invariants — Aggregates enforce business rules during modification. Batch updates skip this.
Break event sourcing — If aggregates raise domain events, batch updates miss them.
Violate aggregate consistency — Optimistic locking and version checks are bypassed.
Indicate wrong aggregate boundaries — Needing batch updates often signals aggregates are too fine-grained.

If you genuinely need batch operations, implement them in the aggregate—loading each, modifying, and saving—or reconsider your aggregate design.

Performance vs. Correctness

Direct SQL updates are faster than loading aggregates. But correctness trumps performance. First, make it correct with proper aggregates. Then, profile. If specific bulk operations are bottlenecks, optimize surgically with explicit batch jobs—not by compromising the domain model.

Generic vs Specific Repositories

A common question in repository design: should you use a generic repository base type or craft specific repositories for each aggregate?

TL;DR: Prefer specific repositories, but consider generic bases for common infrastructure.

Specific Repositories (Preferred)

•Express domain-specific queries
•Self-documenting interfaces
•No unused CRUD methods
•Type-safe operations
•Can evolve independently

Generic Repositories (Use Carefully)

•Reduce boilerplate in implementations
•Provide consistent base operations
•Useful as implementation detail
•Should not be exposed directly
•Can encourage anemic design

Balanced Approach
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
// ✅ GOOD: Generic base as IMPLEMENTATION detail
 
// Domain layer - specific interfaces
interface OrderRepository {
    findById(orderId: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    findPendingOrders(): Promise<Order[]>;
    add(order: Order): Promise<void>;
    remove(order: Order): Promise<void>;
}
 
interface CustomerRepository {
    findById(customerId: CustomerId): Promise<Customer | null>;
    findByEmail(email: Email): Promise<Customer | null>;
    add(customer: Customer): Promise<void>;
    remove(customer: Customer): Promise<void>;
}
 
// Infrastructure layer - generic base for implementation reuse
abstract class BaseRepository<T extends AggregateRoot, TId> {
    constructor(protected readonly orm: ORM) {}
    
    protected async findByIdInternal(id: TId): Promise<T | null> {
        // Common ORM logic
    }
    
    protected async addInternal(entity: T): Promise<void> {
        // Common ORM logic
    }
    
    protected async removeInternal(entity: T): Promise<void> {
        // Common ORM logic
    }
}
 
// Specific implementation extends base
class OrderRepositoryImpl 
    extends BaseRepository<Order, OrderId> 
    implements OrderRepository {
    
    async findById(orderId: OrderId): Promise<Order | null> {
        return this.findByIdInternal(orderId);
    }
    
    // Domain-specific methods unique to OrderRepository
    async findByCustomer(customerId: CustomerId): Promise<Order[]> {
        return this.orm.orders.findMany({
            where: { customerId: customerId.value }
        });
    }
    
    async findPendingOrders(): Promise<Order[]> {
        return this.orm.orders.findMany({
            where: { status: 'PENDING' }
        });
    }
}

The Generic Repository Anti-Pattern

Exposing IRepository<T> directly to domain code is an anti-pattern. It provides CRUD operations that may not make sense for all aggregates and lacks domain-specific queries. Always define specific interfaces that expose only relevant operations.

Interface Evolution and Maintenance

Repository interfaces evolve as domain understanding deepens. Managing this evolution while maintaining system stability requires deliberate practices.

Evolution Guidelines

•Add methods for new use cases — When domain needs new queries, add specific methods rather than stretching existing ones.
•Deprecate before removing — Mark methods as deprecated, provide alternatives, then remove after migration.
•Review method usage — Periodically audit which repository methods are actually used; remove dead code.
•Align with aggregate evolution — When aggregates change, update repository interfaces to match.
•Document breaking changes — If interface changes break implementations, communicate clearly.

Interface Evolution Example
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
// Version 1: Initial interface
interface OrderRepository {
    findById(orderId: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    add(order: Order): Promise<void>;
}
 
// Version 2: New business requirement - find pending orders
interface OrderRepository {
    findById(orderId: OrderId): Promise<Order | null>;
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    findPendingOrders(): Promise<Order[]>;  // Added
    add(order: Order): Promise<void>;
}
 
// Version 3: Deprecation of broad query
interface OrderRepository {
    findById(orderId: OrderId): Promise<Order | null>;
    
    /**
     * @deprecated Use findRecentOrdersByCustomer instead
     * Returns ALL orders which has performance implications
     */
    findByCustomer(customerId: CustomerId): Promise<Order[]>;
    
    // New, more efficient method with limit
    findRecentOrdersByCustomer(
        customerId: CustomerId, 
        limit: number
    ): Promise<Order[]>;
    
    findPendingOrders(): Promise<Order[]>;
    add(order: Order): Promise<void>;
}
 
// Version 4: Deprecated method removed after migration complete

Summary: Repository Interface Design

Repository interface design is where domain language meets persistence abstraction. Let's consolidate the key principles:

Key Takeaways

•Interfaces live in the domain layer — They define what the domain needs, not what databases provide.
•Use domain language in method names — findPendingOrders() over findByStatus('PENDING').
•Prefer specific methods over generic queries — Each method documents a real use case.
•Use typed value objects — OrderId instead of string prevents errors and expresses intent.
•Return complete aggregates — Never partial data that would violate invariants.
•Handle absence explicitly — null, Optional, or throwing—be consistent.
•Exclude infrastructure concerns — No transactions, connections, or raw SQL in interfaces.

What's next:

With interface design principles established, the next page explores Repository Implementation Considerations—the infrastructure-side challenges of turning these clean interfaces into working persistence code.

Page Complete

You now have a comprehensive framework for designing repository interfaces. Remember: the interface is the contract your domain depends on. Design it with the same care you'd give to any public API.