Repository pattern in NestJS - Deep Dive

Overview - Repository pattern

What is it?

The Repository pattern is a way to organize how your application talks to the database. It acts like a middleman that handles data storage and retrieval, so your main code doesn't need to know the details of the database. In NestJS, repositories help keep your code clean and easy to maintain by separating data logic from business logic.

Why it matters

Without the Repository pattern, your application code would be tangled with database queries and details. This makes the code hard to read, test, and change. Using repositories means you can change the database or how you store data without breaking the rest of your app. It also makes teamwork easier because data access is in one place.

Where it fits

Before learning the Repository pattern, you should understand basic NestJS concepts like modules, services, and dependency injection. After mastering repositories, you can learn about advanced database topics like transactions, migrations, and query optimization.

Mental Model

Core Idea

A repository is a dedicated place where your app stores and fetches data, hiding all database details behind simple methods.

Think of it like...

Imagine a library where you ask a librarian for a book instead of searching the shelves yourself. The librarian knows exactly where to find it and handles all the details, so you just get the book you want.

┌─────────────┐       ┌───────────────┐       ┌───────────────┐
│ Controller  │──────▶│ Service       │──────▶│ Repository    │
└─────────────┘       └───────────────┘       └───────────────┘
                                              │
                                              ▼
                                       ┌───────────────┐
                                       │ Database      │
                                       └───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding Data Access Separation

Concept: Separating data access logic from business logic keeps code organized and easier to manage.

In a NestJS app, you usually have controllers handling requests and services containing business rules. Without separation, services might directly write database queries, mixing concerns. The Repository pattern introduces a dedicated layer just for data operations, so services call repository methods instead of writing queries themselves.

Result

Your app's business logic stays clean and focused, making it easier to read and maintain.

Understanding that separating concerns improves code clarity is the foundation for using repositories effectively.

2

Foundation

Basic Repository Structure in NestJS

Concept: A repository is a class with methods to create, read, update, and delete data entities.

In NestJS, a repository class typically has methods like findOne, find, save, and delete. These methods use an ORM like TypeORM or Prisma to interact with the database. The repository hides the ORM details from the rest of the app, providing simple method calls instead.

Result

You get a reusable, testable class that handles all database operations for a specific entity.

Knowing that repositories wrap ORM calls helps you write cleaner and more modular code.

3

Intermediate

Injecting Repositories with Dependency Injection

🤔Before reading on: Do you think repositories are created manually or provided automatically by NestJS? Commit to your answer.

Concept: NestJS uses dependency injection to provide repository instances where needed, avoiding manual creation.

Instead of creating repository objects yourself, you declare them as dependencies in your service constructor. NestJS injects the correct repository instance automatically. This makes your code easier to test and swap implementations if needed.

Result

Your services receive ready-to-use repository instances without extra setup code.

Understanding dependency injection with repositories unlocks powerful modularity and testability in NestJS apps.

4

Intermediate

Custom Repository Methods for Complex Queries

🤔Before reading on: Can repositories only have simple CRUD methods, or can they include complex queries? Commit to your answer.

Concept: Repositories can have custom methods to handle complex or specific data queries beyond basic CRUD.

You can add methods like findUsersByRole or getRecentOrders inside your repository class. These methods use ORM query builders or raw queries but keep the complexity hidden from services. This keeps your business logic simple and focused.

Result

Your app can handle complex data needs without cluttering service code.

Knowing that repositories can encapsulate complex queries helps maintain clean separation and scalability.

5

Advanced

Repository Pattern with Transactions

🤔Before reading on: Do you think transactions are managed inside services or repositories? Commit to your answer.

Concept: Repositories can manage database transactions to ensure multiple operations succeed or fail together.

When you need to update several tables at once, repositories can start a transaction, perform all operations, and commit or rollback if something fails. This keeps data consistent and error handling centralized.

Result

Your app safely handles complex data changes without partial updates or corruption.

Understanding transaction management inside repositories prevents common data consistency bugs.

6

Expert

Extending and Overriding Repository Behavior

🤔Before reading on: Can you customize built-in repository methods or only add new ones? Commit to your answer.

Concept: You can extend base repository classes to override or enhance default behavior for specific needs.

NestJS with TypeORM allows creating custom repository classes that inherit from base repositories. You can override methods like save or findOne to add logging, caching, or validation. This lets you tailor data access without changing service code.

Result

Your repositories become powerful, flexible tools that fit your app's unique requirements.

Knowing how to extend repositories unlocks advanced customization and optimization opportunities.

Under the Hood

Repositories in NestJS are classes that wrap ORM methods. When you inject a repository, NestJS provides an instance connected to the database context. The repository methods translate your calls into SQL or database commands behind the scenes. This abstraction means your app code never writes raw queries directly, relying on the ORM's query builder and connection pooling.

Why designed this way?

The Repository pattern was designed to separate concerns and improve testability. Early apps mixed database code with business logic, making changes risky and tests hard. By isolating data access, developers can swap databases or optimize queries without touching business rules. NestJS adopted this pattern to fit its modular, injectable architecture, promoting clean code and easier maintenance.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Service       │──────▶│ Repository    │──────▶│ ORM Layer     │
└───────────────┘       └───────────────┘       └───────────────┘
                                                      │
                                                      ▼
                                               ┌───────────────┐
                                               │ Database      │
                                               └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think repositories are only useful for big projects? Commit to yes or no.

Common Belief: Repositories are only needed in large or complex applications.

Reality: Even small apps benefit from repositories because they keep code organized and make future changes easier.

Why it matters: Skipping repositories early can lead to messy code that becomes hard to maintain as the app grows.

Quick: Do you think repositories replace services entirely? Commit to yes or no.

Common Belief: Repositories do all the work, so services are unnecessary.

Reality: Repositories handle data access only; services contain business logic and coordinate tasks.

Why it matters: Mixing business logic into repositories breaks separation of concerns and reduces code clarity.

Quick: Do you think repositories always improve performance? Commit to yes or no.

Common Belief: Using repositories automatically makes database operations faster.

Reality: Repositories organize code but do not guarantee performance; inefficient queries inside repositories can still slow apps.

Why it matters: Assuming repositories fix performance can lead to ignoring query optimization and profiling.

Quick: Do you think you must write raw SQL inside repositories? Commit to yes or no.

Common Belief: Repositories require writing raw SQL queries for all operations.

Reality: Most repositories use ORM methods or query builders, avoiding raw SQL unless necessary.

Why it matters: Believing raw SQL is mandatory can discourage beginners and lead to unsafe or complex code.

Expert Zone

1

Repositories can be designed as interfaces with multiple implementations, enabling easy swapping of data sources like databases or APIs.

2

Using repositories with Unit of Work patterns helps manage complex transactions and batch operations efficiently.

3

Custom repository decorators can add cross-cutting concerns like caching or logging without changing repository code.

When NOT to use

Avoid the Repository pattern when using simple data access needs with minimal business logic, or when your ORM already provides sufficient abstraction. In such cases, direct use of ORM services or query builders can be simpler and more efficient.

Production Patterns

In production NestJS apps, repositories are often combined with services that handle validation and authorization. Repositories focus solely on data queries, while services orchestrate workflows. Advanced apps use custom repositories for caching, soft deletes, and audit logging, ensuring clean separation and maintainability.

Connections

Dependency Injection

Repository pattern relies on dependency injection to provide repository instances to services.

Understanding dependency injection clarifies how repositories are managed and replaced in NestJS apps.

Single Responsibility Principle (SRP)

Repositories embody SRP by focusing only on data access, separating concerns cleanly.

Knowing SRP helps appreciate why repositories improve code organization and maintainability.

Database Transaction Management

Repositories often manage transactions to ensure data consistency during multiple related operations.

Understanding transactions helps grasp how repositories maintain data integrity in complex scenarios.

Common Pitfalls

#1 Mixing business logic inside repositories.

Wrong approach:

class UserRepository {
async createUserWithWelcomeEmail(userData) {
const user = await this.save(userData);
await sendWelcomeEmail(user.email); // business logic here
return user;
}
}

Correct approach:

class UserRepository {
async save(userData) {
// only save user data
}
}

class UserService {
constructor(private userRepository: UserRepository) {}

async createUserWithWelcomeEmail(userData) {
const user = await this.userRepository.save(userData);
await sendWelcomeEmail(user.email); // business logic here
return user;
}
}

Root cause:

Confusing responsibilities leads to harder-to-maintain code and breaks separation of concerns.

#2 Manually creating repository instances instead of injecting.

Wrong approach:

const userRepository = new UserRepository();
const userService = new UserService(userRepository);

Correct approach:

@Injectable()
class UserService {
constructor(private userRepository: UserRepository) {}
}

Root cause:

Not using NestJS dependency injection loses benefits like lifecycle management and testability.

#3 Writing raw SQL queries everywhere inside repositories.

Wrong approach:

async findAllUsers() {
return await this.entityManager.query('SELECT * FROM users');
}

Correct approach:

async findAllUsers() {
return await this.repository.find();
}

Root cause:

Overusing raw SQL reduces portability, safety, and readability.

Key Takeaways

The Repository pattern separates data access from business logic, making code cleaner and easier to maintain.

In NestJS, repositories are classes injected into services that handle all database operations for specific entities.

Repositories can have simple CRUD methods or complex custom queries, hiding database details from the rest of the app.

Using dependency injection with repositories improves modularity, testability, and flexibility.

Avoid mixing business logic into repositories and prefer ORM methods over raw SQL for safer, clearer code.