Introduction

In Domain-Driven Design (DDD), repositories play a crucial role—they represent a boundary between the domain model and the underlying infrastructure. But in event-sourced systems, developers often fall into one of two traps: either oversimplifying the repository to the point of uselessness, or overengineering it to the point of confusion.

This article builds up a production-grade event-sourced repository step-by-step, evolving it as new needs and insights emerge. Each design choice is carefully justified. By the end, you'll have a flexible, cleanly layered, and testable repository structure built in TypeScript that embraces the nuances of event sourcing.

Why Repositories Matter in DDD

A repository isn’t a fancy name for a database access class. It’s a semantic boundary. In DDD, a repository is a contract that provides access to aggregates, and its purpose is to abstract away how aggregates are persisted and reconstructed.

A general repository contract starts simple:

interface Repository<A> {
  getById(id: Identifier): Promise<A | undefined>;
  save(aggregate: A): Promise<void>;
}

Then, we define aggregate-specific repositories:

interface UserRepository extends Repository<User> {}

This makes the domain model dependent on what a repository does—not how it does it. Whether you're using a relational database, a document store, or an event store is irrelevant at this level. That abstraction is intentional.

But when you do use event sourcing, things get more interesting.

Why Event Sourcing Requires More Structure

In an event-sourced system, aggregates are rehydrated from event streams. The repository must:

• Reconstruct an aggregate from a sequence of past events

• Store newly produced events

• Track versions to ensure optimistic concurrency

• Translate between domain events and serialized forms

These are nontrivial concerns, and they repeat for every aggregate. That’s why it makes sense to create an abstract base class that handles this boilerplate while leaving domain-specific behavior to concrete implementations.

We call this base class EventSourcedRepository:

abstract class EventSourcedRepository<A extends AggregateRoot<E>, E extends Event> {
  constructor(private readonly eventStore: EventStore) {}

  protected abstract getStreamId(id: Identifier): string;
  protected abstract rehydrate(events: E[]): A;
  protected abstract toESEvent(event: E): ESEvent;
  protected abstract fromESEvent(es: ESEvent): E;

  async getById(id: Identifier): Promise<AggregateEnvelope<A> | undefined> {
    const streamId = this.getStreamId(id);
    const esEvents = await this.eventStore.getEventsByStreamId(streamId);
    if (esEvents.length === 0) return undefined;

    const domainEvents = esEvents.map(this.fromESEvent.bind(this));
    const aggregate = this.rehydrate(domainEvents);

    return { aggregate, version: esEvents.length };
  }

  async save(envelope: AggregateEnvelope<A>): Promise<void> {
    const { aggregate, version } = envelope;
    const events = aggregate.events.map(this.toESEvent.bind(this));
    await this.eventStore.save(this.getStreamId(aggregate.id), version, events);
    aggregate.clearEvents();
  }
}

Let’s unpack why each of these responsibilities is handled here.

Why the AggregateEnvelope Matters

At first glance, you might wonder why we don't just return the aggregate from getById. But remember: event-sourced systems use optimistic concurrency. That means the stream version at the time of loading is crucial when saving back later.

Instead of tracking that version inside the aggregate—which pollutes the domain with infrastructure—we wrap the aggregate in an envelope:

interface AggregateEnvelope<A extends AggregateRoot> {
  aggregate: A;
  version: number;
}

This design keeps the domain pure while still giving the repository the data it needs to safely persist changes.

In the Application Layer

class RenameUserHandler {
  constructor(private readonly userRepo: UserRepository) {}

  async execute(id: Identifier, newName: string) {
    const envelope = await this.userRepo.getById(id);
    if (!envelope) throw new Error("User not found");

    envelope.aggregate.rename(newName);
    await this.userRepo.save(envelope);
  }
}

Note that the application code doesn’t care about event sourcing or stream versions—it just performs business logic.

Why Event Translation Must Be Explicit

You might be tempted to serialize domain events directly into the store, but this introduces long-term risks:

• You can’t evolve the schema easily

• Value objects may not serialize correctly

• Refactoring becomes brittle

Instead, we define translation methods:

Flatten events for storage:

protected toESEvent(event: UserEvent): ESEvent {
  switch (event.constructor) {
    case UserCreated:
      return {
        type: "UserCreated",
        data: { id: event.id.value, name: event.name.value },
      };
    case UserNameUpdated:
      return {
        type: "UserNameUpdated",
        data: { name: event.name.value },
      };
  }
}

Reconstruct events for rehydration:

protected fromESEvent(es: ESEvent): UserEvent {
  switch (es.type) {
    case "UserCreated":
      return new UserCreated(new Identifier(es.data.id), new Name(es.data.name));
    case "UserNameUpdated":
      return new UserNameUpdated(new Name(es.data.name));
    default:
      throw new Error(`Unknown event: ${es.type}`);
  }
}

This makes versioning, refactoring, and interoperability explicit and safe.

Stream ID Namespacing

In real-world systems, the same conceptual entity—like a user—might be represented across multiple aggregate boundaries. For example, you might have one aggregate modeling user identity, another modeling account preferences, and another modeling user activity. All of these aggregates might share the same user ID value.

In a traditional database, this is typically not a problem—tables differentiate data implicitly. But in an event store, stream IDs must be globally unique. That’s where namespacing comes in.

protected getStreamId(id: Identifier): string {
  return `user:${id.value}`;
}

Here, we use user: as a namespace to differentiate the aggregate stream from others that may use the same ID. This prevents collisions, respects the autonomy of bounded contexts, and reinforces that stream ID construction is a responsibility of the repository—not the domain.

Capability of Testing at Every Layer (and Why It's Powerful)

Thanks to the clean separation of concerns, testing is now straightforward:

Unit test the aggregate

const user = User.create(new Identifier("1"), "Alice");
user.rename("Bob");
expect(user.events[0]).toBeInstanceOf(UserNameUpdated);

Test the repository with a mock store

const store = new InMemoryEventStore();
const repo = new UserEventSourcedRepository(store);

const user = User.create(new Identifier("1"), "Alice");
await repo.save({ aggregate: user, version: 0 });

const result = await repo.getById(user.id);
expect(result?.aggregate.name).toBe("Alice");

Test the application layer

const store = new InMemoryEventStore();
const repo = new UserEventSourcedRepository(store);
const handler = new RenameUserHandler(repo);

await handler.execute(new Identifier("1"), "Charlie");
const result = await repo.getById(new Identifier("1"));
expect(result?.aggregate.name).toBe("Charlie");

You can mock just the event store or the entire repository—it’s up to you. Because each piece is clearly separated, you can even swap the whole repository out for an in-memory implementation if that better suits your test needs. This allows you to bypass event serialization, concurrency logic, or store-specific behavior when testing higher-level workflows or application services. The composability of this design means you can tune your test setup to match your context.

Final Output: A Complete User Repository

class UserEventSourcedRepository extends EventSourcedRepository<User, UserEvent> {
  constructor(eventStore: EventStore) {
    super(eventStore);
  }

  protected getStreamId(id: Identifier): string {
    return `user:${id.value}`;
  }

  protected rehydrate(events: UserEvent[]): User {
    return User.rehydrate(events);
  }

  protected toESEvent(event: UserEvent): ESEvent {
    switch (event.constructor) {
      case UserCreated:
        return {
          type: "UserCreated",
          data: { id: event.id.value, name: event.name.value },
        };
      case UserNameUpdated:
        return {
          type: "UserNameUpdated",
          data: { name: event.name.value },
        };
    }
  }

  protected fromESEvent(es: ESEvent): UserEvent {
    switch (es.type) {
      case "UserCreated":
        return new UserCreated(new Identifier(es.data.id), new Name(es.data.name));
      case "UserNameUpdated":
        return new UserNameUpdated(new Name(es.data.name));
      default:
        throw new Error(`Unknown event type: ${es.type}`);
    }
  }
}

Conclusion

A great event-sourced repository isn’t just about reading and writing events. It’s about aligning your technical model with your business domain, keeping responsibilities clear, and making your system a pleasure to work with.

Throughout this article, we built a repository layer that:

• Starts from a clean, behavioral contract with the domain

• Introduces a flexible and reusable abstract base class for event-sourced concerns

• Keeps persistence details out of aggregates by using envelopes

• Explicitly translates events between the domain and the event store

• Namespaces stream IDs to reflect aggregate context boundaries

• Makes every layer—from aggregate to application—easy to test

The result is a well-structured repository pattern that scales with your system’s complexity, supports evolving business needs, and resists rot over time.

This is more than just an implementation—it’s a mental model for building robust systems.

This really is the last event-sourced repository you'll ever need.

You’ll also see it as type, size, or kind. It's a simple enum-style prop that lets consumers select from a predefined set of styles or behaviors. But here's the catch: while it seems harmless, it often leads to deeply flawed component design. Worse, it pushes responsibility onto the application layer—right where consistency is hardest to enforce.

What’s the Problem With variant Props?

They seem like a great idea at first. After all, enums are simple! Consider this typical usage:

<Text size="big">Hello, world</Text>

Looks fine, right? But this component doesn’t encapsulate the design rule—it defers it. It means the app must always remember that size="big" is what should be used for titles, across every context. The system isn’t enforcing a design decision; it’s offering a styling toolkit. And now, your app code is responsible for maintaining design consistency.

If your design system exports primitives like this, then the design system isn’t a system. It’s just a set of styled components. The actual design is happening in the app layer.

Design Systems Should Make Decisions, Not Defer Them

Design systems exist to encode constraints. When we expose a variant, we ask the application to choose what the design system should’ve already decided.

Let’s say we need a Thumbnail component that displays user avatars at different sizes. Instead of this:

<Thumbnail size="small" url={url} />

You could offer purpose-driven components:

<CommentAvatar url={url} />
<HeaderAvatar url={url} />

Now the design system owns the sizing logic. The application simply says what it wants to display, not how it should look. This creates a more declarative API, one that carries semantic meaning and removes styling decisions from the application layer.

God Components and Leaky Abstractions

The moment you introduce a variant prop, your component is at risk of becoming a God Component.

Let’s look at a common example:

type ButtonProps = {
  variant: 'primary' | 'secondary' | 'danger' | 'link';
  size: 'small' | 'medium' | 'large';
  isDisabled?: boolean;
  onClick?: () => void;
};

Already, this component is branching internally:

• Only danger needs confirmation logic

• Only link ignores size

• Only primary and secondary share color styles

These props are not always meaningful together. This is a red flag: the component is non-cohesive. Props are only used conditionally, based on the variant. This violates the Single Responsibility Principle—a foundational idea in maintainable system design.

Like the God Class anti-pattern, this component tries to do everything. It becomes hard to reason about, harder to test, and almost impossible to extend without side effects.

A Better Approach: Small, Purposeful Components

Instead of:

<Button variant="primary" size="large">Submit</Button>

Split your design intent into meaningful components:

<PrimaryActionButton onClick={save}>Submit</PrimaryActionButton>
<DestructiveButton onClick={deleteItem}>Delete</DestructiveButton>

This removes branching, improves readability, and strengthens alignment between design and code. The app doesn’t need to know which styles to apply—it just picks the component that represents the action.

Bonus: It's Easier to Refactor

Let’s say you want to change the padding on all DestructiveButtons. With purpose-built components, you can do that in one place. With a God Component, you'd have to branch inside Button and hope no other variant breaks.

This is Open-Closed Principle in action: your system is open for extension (add a new component), but closed for modification (no need to touch shared internals).

But What About Shared Visual Consistency?

A common concern with this approach is: how do we maintain consistency across all these small components? For example, how do we ensure that all buttons still share the same border radius, font size, or padding?

The answer is: through shared design tokens or private base component primitives.

You don’t need to centralize behavior into a God Component to share styling. You can define a private BaseButton that encapsulates common styles:

// private to the component library
const BaseButton = ({ className, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
  <button className={`rounded-md font-semibold ${className}`} {...props} />
);

Then you build on top of it:

const PrimaryActionButton = (props) => (
  <BaseButton className="bg-blue-600 text-white px-4 py-2" {...props} />
);

const DestructiveButton = (props) => (
  <BaseButton className="bg-red-600 text-white px-4 py-2" {...props} />
);

This lets you preserve internal consistency without sacrificing cohesion or introducing bloated variant logic.

Better yet, you can define your border radius, colors, and spacing in design tokens—either via a theme, a CSS-in-JS solution, or even utility classes like Tailwind.

That way, the system ensures consistency, while each component remains focused and readable.

Key Takeaways

• Avoid generic variant, type, or size props in design system components

• Expose semantic, intention-driven components that map directly to use cases

• Watch for conditional prop relevance—it's a sign your component is doing too much

• Lean on composition and specialization to enforce constraints in the system layer, not the app layer

• Use base components and design tokens to coordinate shared styling without centralizing logic

• Design APIs that describe what to show, not how it should look

Exporting flexible primitives might seem powerful—but design systems are most powerful when they encode decisions, not defer them. Let your components be opinionated. Let them enforce constraints. Let them be the system.

Most of the complaints about enums aren’t about the feature itself—they’re about misuse.

I’d even go as far as to say that the majority of enum pitfalls in TypeScript are caused by a fundamental misunderstanding of what an enum is meant to be in the first place.

This article isn’t just a defense of enums. It’s a reminder of what enums are for—and why, when used correctly, they’re still a powerful and expressive tool in TypeScript.

Enums Are Meant To Be Symbolic

Let’s get one thing straight: enums are not meant to represent literal values. They’re meant to represent symbolic ones.

This distinction might sound pedantic, but it’s at the core of the misunderstanding. As Wikipedia puts it:

"An enumerated type has values that are different from each other, and that can be compared and assigned, but are not specified by the programmer."

That last part is key: not specified by the programmer. In other words, we shouldn’t care what the underlying value of an enum is. We only care about what it represents.

What Does "Symbolic" Really Mean?

Let’s make it concrete.

Imagine you're building a traffic light simulation. A traffic light can be red, yellow, or green. How should you represent those states in your code?

You could do:

const RED = "red";
const YELLOW = "yellow";
const GREEN = "green";

Or maybe you're feeling fancier and you use hex codes:

const RED = "#FF0000";
const YELLOW = "#FFFF00";
const GREEN = "#00FF00";

Or perhaps localized strings:

const RED = "rouge";
const YELLOW = "jaune";
const GREEN = "vert";

None of these are wrong—but none are ideal either. Because what you’re really trying to express is the concept of red, yellow, and green. Not a particular string or color code or translation. Just the idea.

That’s where symbolic values shine.

JavaScript Has a Built-in Symbolic Primitive

ES6 introduced the Symbol primitive, and it’s a perfect metaphor for this kind of use:

const RED = Symbol("Red");
const YELLOW = Symbol("Yellow");
const GREEN = Symbol("Green");

Each call to Symbol() returns a unique value, regardless of the label. That means Symbol("Red") !== Symbol("Red"), unless you store it and reuse the same reference. The value itself doesn’t matter—just the identity.

This gets to the heart of how enums should behave: they should stand for something abstract, not something concrete.

Where TypeScript Gets a Little Funky

Here’s where TypeScript throws a curveball: unlike many other statically typed languages, TypeScript allows you to assign actual string or number literal values to enum members.

enum TrafficLight {
  Red = "red",
  Yellow = "yellow",
  Green = "green"
}

This feels convenient at first. You can now log enum values, serialize them into JSON, and display them in UIs directly. But this is a trap.

Why? Because you’re no longer using enums symbolically. You’ve turned them into a tightly-coupled representation layer. The enum value is the thing you're going to display, transmit, and compare externally. And that opens the door to a few major risks:

1. Leaky Abstractions

By using a string value like "red" directly in your enum, you’re tying your logic to that representation. Now every part of your app—your UI, backend, tests—might start to depend on that "red" string. If you later need to localize, change the display name, or serialize differently, you’re stuck.

Example:

enum TrafficLight {
  Red = "red",
  Yellow = "yellow",
  Green = "green"
}

function renderLight(color: TrafficLight) {
  return `<div class="light-${color}"></div>`;
}

At first glance, this seems fine. But what happens when marketing wants the classes to change to "stop", "caution", and "go" instead of "red", "yellow", and "green"?

You're now forced to either:

• Rename your enum values (breaking everything),

• Or inject a weird indirection layer to undo the coupling you introduced in the first place.

You’ve tightly bound your logic layer and representation layer, which makes the system harder to evolve.

2. Fragile Equality

Using literal values opens up the door for subtle bugs due to implicit casting, loose comparisons, and typos.

For example:

if (color === "Red") {
  // oops – this will never be true if your enum is "red" (lowercase)
}

Or worse:

const userInput = req.body.color; // from frontend form input

if (userInput === TrafficLight.Red) {
  // works... until someone changes the frontend string casing or translation
}

Now your enum value is effectively part of a contract—and not a very safe one. There's no type safety guarding the string being passed around. A typo or localization mismatch breaks your logic silently.

3. Enum Values Become Public API

Once you serialize your enums as strings or numbers and expose them (e.g. in JSON APIs), they become part of your public contract. Now you're stuck maintaining these exact values forever, even if they were never intended to be meaningful.

Imagine this:

// Backend API
{
  "status": "Processing"
}

This might come from:

enum OrderStatus {
  Processing = "Processing",
  Shipped = "Shipped",
  Delivered = "Delivered",
}

Now Processing is in your API contract. What happens when you want to rename it to InProgress? You can't—at least not without a breaking change.

Instead, the enum should have stayed symbolic:

enum OrderStatus {
  Processing,
  Shipped,
  Delivered
}

And your serialization should happen in a dedicated mapping layer:

const statusToApi = new Map<OrderStatus, string>([
  [OrderStatus.Processing, "Processing"],
  [OrderStatus.Shipped, "Shipped"],
  [OrderStatus.Delivered, "Delivered"],
]);

return {
  status: statusToApi.get(currentStatus)
};

This lets you keep your internal logic clean and symbolic, while exposing only the necessary representation at the edge of your system.

Enums Should Be for Internal Logic Only

When used correctly, enums are great for internal logic and branching:

enum TrafficLight {
  Red,
  Yellow,
  Green
}

const currentLight: TrafficLight = TrafficLight.Red;

const instructions = new Map<TrafficLight, string>([
  [TrafficLight.Red, "Stop"],
  [TrafficLight.Yellow, "Slow down"],
  [TrafficLight.Green, "Go"],
]);

console.log(instructions.get(currentLight));

Here, the enum values themselves are symbolic. They aren’t used directly in the UI, APIs, or persisted anywhere—they're just internal tags for logic flow. If you want to serialize the enum value or display it to a user, that should be an explicit translation step (like the Map above).

The Problem With Misunderstood Criticism

I once saw someone critique TypeScript enums in a video, complaining that enums were “unusable” because they “don’t serialize cleanly.” But that’s like complaining that a hammer doesn’t write well. Of course it doesn’t—it wasn’t designed for that.

If you’re using enums as if they’re just constant strings or serialized values, then yes, they’ll bite you. But if you use them as symbolic representations of domain ideas, then they’re incredibly powerful—and semantically rich.

Should You Use TypeScript Enums?

I’ll be honest: TypeScript enums are quirky. The enum keyword behaves differently than a lot of people expect, especially those coming from other languages. But abandoning them altogether is throwing the baby out with the bathwater.

The problem isn’t that TypeScript enums are bad. The problem is that we’ve forgotten what enums are for.

So let’s bring back proper enums—used symbolically, decoupled from implementation details, and grounded in good modeling.

Because sometimes, the best way to represent an idea… is with a symbol.

The Controversial Question

When designing a system with multiple related aggregates—say, a CustomerAggregate, OrderAggregate, and CustomerPreferencesAggregate—the instinct is to assign each a unique ID. After all, isn’t each aggregate supposed to be an independent consistency boundary?

But what if these aggregates share the same ID, such as a customer ID? Would this violate the sacred principles of DDD, or could it be a pragmatic decision?

Designing Aggregates: Consistency Boundaries, Not Relationships

A common misconception when designing aggregates is to organize them around relationships, hierarchy, or real-world manifestations rather than consistency boundaries. Aggregates are about managing invariants—rules that must always hold true—not about representing relational data structures.

For example, consider a retail domain:

• An OrderAggregate enforces consistency around orders—items, payment status, and shipping details.

• A CustomerAggregate manages identity and personal details, but not orders or preferences.

• A CustomerPreferencesAggregate handles marketing subscriptions and notifications.

Designing aggregates based on relationships often results in bloated objects and inconsistent states. Instead, aggregates should isolate rules and invariants, ensuring consistency within their boundary.

Why Sharing IDs Can Be OK

Using the same ID across multiple aggregates is acceptable—if done correctly:

✅ 1. Distinct Responsibilities

When aggregates encapsulate separate, independent behaviors, sharing an ID can make sense. For instance:

• CustomerAggregate manages identity and personal information.

• OrderAggregate handles orders and purchases.

• CustomerPreferencesAggregate manages notification and marketing preferences.

If each aggregate enforces its own rules, they can coexist peacefully, even with the same ID.

✅ 2. Clear Consistency Boundaries

When consistency boundaries are truly independent, you can safely use shared IDs. For example, changes to CustomerPreferencesAggregate should never require an immediate update to OrderAggregate.

✅ 3. Identity vs. State Management

An ID can represent a common identity without implying ownership. Each aggregate manages its own data and state, avoiding tight coupling.

Expanded Example: A Food Delivery Domain

Let’s consider a food delivery service with three aggregates:

1. CustomerAggregate tracks user identity and contact details.

2. OrderAggregate handles order details, payment status, and delivery logistics.

3. LoyaltyPointsAggregate manages customer rewards.

// CustomerAggregate.js
class CustomerAggregate {
  constructor(customerId, name, address) {
    this.customerId = customerId;
    this.name = name;
    this.address = address;
  }

  updateAddress(newAddress) {
    this.address = newAddress;
  }
}

// OrderAggregate.js
class OrderAggregate {
  constructor(customerId, orderId, items) {
    this.customerId = customerId;
    this.orderId = orderId;
    this.items = items;
    this.status = "Pending";
  }

  markAsDelivered() {
    this.status = "Delivered";
  }
}

// LoyaltyPointsAggregate.js
class LoyaltyPointsAggregate {
  constructor(customerId) {
    this.customerId = customerId;
    this.points = 0;
  }

  addPoints(points) {
    this.points += points;
  }
}

This approach aligns aggregates with consistency boundaries—each handles its own invariants. We can use the customer ID across all aggregates because their state and behavior remain independent.

When It’s a Problem

Sharing IDs becomes problematic if:

• Aggregates frequently rely on each other’s state.

• Consistency across aggregates is required in a single transaction.

• You’re modeling the same entity in different places.

If these conditions exist, consider merging aggregates or using domain events to ensure consistency.

Final Thoughts

In DDD, aggregates are about managing business rules, not reflecting real-world hierarchies. Sharing IDs isn’t heretical—it’s a pragmatic choice when aggregates have distinct responsibilities and consistency boundaries. Avoid dogmatic thinking; focus on designing aggregates around consistency, invariants, and behaviors. The goal is a model that fits the business problem, not one that rigidly follows patterns. Embrace trade-offs; DDD is about practical solutions, not absolute rules.

And remember—It's acceptable to share IDs across different aggregate types, but an individual aggregate instance must always have a unique identity within its own type. This ensures each instance maintains a unique identity and consistency boundary, reinforcing the core principles of DDD while remaining pragmatic.

Purpose behind DRY

Let's start the article by taking a second to talk about the motivation behind the DRY principle. When the author's of "The Programmatic Programmer" introduced the concept, the following was used to describe the DRY principle:

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

That's it! It's short, succinct and to the point. So how do people use this simple principle incorrectly? An innocent mistake we generally commit is thinking that the objective of this principle is to minimize the overall lines of code. This is false. If you noticed, this definition does not emphasize on code duplication at all. It just states that any rule or information about your business/app is deserving of an abstraction (i.e. function) and should have a single reference point in your application. These rules would be written once but potentially referenced multiple times. By abiding by this principle, you will also naturally notice a decrease in duplications in the code most times.

Incidental Duplication

So when we mention the term "incidental duplication" we are referring to duplication that has occurred in different places by mere chance (or "incidentally" if you will). It is code that looks the same but represents different behaviours/fact/knowledge in the system. DRY is generally misapplied when incidentally duplicated code is abstracted away. This tends to deliver negative outcomes in our system which we colloquially refer to as spaghetti code.

Example: The What Not To Do

Let's take a look at a practical example to illustrate how abstracting incidental duplication minimizes lines of code but also contributes to worse code quality. The following is hypothetical code that could possibly live in a restaurant's codebase. Let's imagine a restaurant serves pizzas and sandwiches.

const makePizza = () => {
  grateCheese();
  sliceTomatoes();
  sliceOnions();
  sliceBellPeppers();
  sliceOlives();
  putIngredientsOnDough();
  bakeDough();
}

const makeSandwich = () => {
  grateCheese();
  sliceTomatoes();
  sliceOnions();
  sliceBellPeppers();
  squirtMayonnaise();
  putIngredientsBetweenBread();
  toastBread();
}

At first glance, you will notice some commonality between making a pizza and making a sandwich. They both have similar ingredients such as cheese, tomatoes, onions, and bell peppers. One might be tempted to abstract this commonality for the sole purpose of reducing the number of lines of code.

const prepareIngredients = () => {
  grateCheese();
  sliceTomatoes();
  sliceOnions();
  sliceBellPeppers();
}

const makePizza = () => {
  prepareIngredients();
  sliceOlives();
  putIngredientsOnDough();
  bakeDough();
}

const makeSandwich = () => {
  prepareIngredients();
  squirtMayonnaise();
  putIngredientsBetweenBread();
}

The above refactoring has indeed reduced duplication in the code but there are a set of questions that we should ask ourselves. Is code now better? What does prepareIngredients represent? Is this DRY? Are there any new benefits gained from this? Have you seen code in your code base that has undergone this sort of "refactoring"?

Let's take a second to assess the prepareIngredients function and ask ourselves "what knowledge is being captured by this abstraction". It doesn't represent how to make a sandwich. It doesn't represent how to make a pizza. Instead, it represents the overlapping ingredients between how to make a pizza and a sandwich. If you think critically, you may come to realize that this information is most likely not significant to any person in the business and carries no real semantic value. Although truthful, its is considered to be arbitrary information. To put it in terms used by the DRY authors, it is not an authoritative representation of any significant piece of knowledge.

If you do not see the issue so far, consider what would happen if we introduce another item on the menu that also has overlaps with the sandwich and the pizza. Let's assume we need to introduce a burger to the menu and that a burger is simply tomatoes, cheese, a beef patty in a bun. If you are adamant about maintaining the prepareIngredients function, you would like experience the following updates.

const prepareIngredients = () => {
  grateCheese();
  sliceTomatoes();
}

const makeBurger = () => {
  prepareIngredients();
  cookBeefPatty();
  putInbuns();
}

const makePizza = () => {
  prepareIngredients();
  sliceOnions();
  sliceBellPeppers(); 
  sliceOlives();
  putIngredientsOnDough();
  bakeDough();
}

const makeSandwich = () => {
  prepareIngredients();
  sliceOnions();
  sliceBellPeppers();
  squirtMayonnaise();
  putIngredientsBetweenBread();
}

The prepareIngredients function has been minimized to only capture the overlap between all three menu items. In addition makeSandwich and makePizza has been updated to compensate for the changes done in prepareIngredients since it's a dependency to both these functions. To put it in other words, introducing a new item in the menu, which seemingly has nothing to do with the current items, will cause more updates in the code base due to this wrongful abstractions. Although this is a simple example, it implicitly is becoming a little harder to understand what ingredients are involved in a menu item.

The Fix

Although there is less code written in our example above, the quality of our code is clearly worse. Rather than do all this, you could have simply kept your code as follows:

const makeBurger = () => {
  grateCheese();
  sliceTomatoes();
  cookBeefPatty();
  putInbuns();
}

const makePizza = () => {
  grateCheese();
  sliceTomatoes();
  sliceOnions();
  sliceBellPeppers(); 
  sliceOlives();
  putIngredientsOnDough();
  bakeDough();
}

const makeSandwich = () => {
  grateCheese();
  sliceTomatoes();
  sliceOnions();
  sliceBellPeppers();
  squirtMayonnaise();
  putIngredientsBetweenBread();
}

Although longer, this code is linearly simple to understand, involves one less function, and has no interdependencies. This funnily just means that it was correct and better to have done nothing in the first place. There was not issue to begin with.

Last words

The examples I have written above are meant to easily demonstrate that aiming for less lines of code does not necessarily contribute to an increase in code quality. Unfortunately, I have seen signs of this misunderstanding in numerous code bases that I have been involved in. I would also be ballsy enough to say that I think all instances of what we call "spaghetti code" includes a similar misunderstanding of the DRY principle to that included in this article. If I can leave you with 1 simple message, I would leave you with this: Before creating a function, always ask yourself whether or not you are capturing knowledge that the business and other developers are interested in. If not, remove the abstraction!

Based on how an application has been put together, it is entirely possible for a developer to find themself in an unfortunate position where creating isolated unit tests is not frequently possible. As a result, they would resort to more integration tests and utilize heavy mocks and patches to assert correct functionality. In my experience, I have come to realize that this situation is a result of less than optimal code design. In this article, I would like to present how one can utilize dependency injection to shift from relying on integration tests to more isolated unit tests instead. We will go through an example, written in typescript, that starts off in the situation I have described that would then be refactored into a more modular piece of software that is easily testable.

Example

import { average } from "./utils";
import examHttpRepository from "./student-repository";

const calculateAverageGrade = (exams: Exam[]) => {
  const grades = exams.map(exam => exam.grade);
  return average(grades);
}

const getStudentAverageGrade = async (studentId: string) => {
  // This will get exams via an HTTP call. This makes our function impure
  const exams = await examHttpRepository.getByStudentId(studentId);
  return calculateAverageGrade(exams);
}

export default getStudentAverageGrade

Let's focus on the getStudentAverageGrade function in the code snippet above. The function is quite simple and has an intuitive signature. It takes in a student ID and returns the student's average grade. The implementation uses a repository to retrieve an array of exams which is then transformed into the student's average grade. Easy peasy. This type of code is rather typical in most JavaScript projects.

Although common, this pattern is not necessarily the best and may present challenges in maintaining a modular and testable codebase. In particular, the presence of the examHttpRepository inside getStudentAverageGrade introduces side-effects and a form of coupling within getStudentAverageGrade. Let's demonstrate these difficulties by writing out what this current function's test would look like.

import nock from "nock";
import getStudentAverageGrade from "./get-student-average-grade";

describe("getStudentAverageGrade", () => {
  it("should get a student's average grade", async () => {
    const mockExams = [
      { name: 'math', grade: 90 },
      { name: 'history', grade: 80 }
    ];

    // intercept HTTP request to to endpoint and return mock
    nock('https://api.mysite.com')
      .get('/exams')
      .query({ studentid: 'abc' })
      .reply(200, { exams: mockExams });

    const averageGrade = await getStudentAverageGrade('abc');
    expect(averageGrade).toBe(85);
  });
});

This test by definition is an integration test since getStudentAverageGrade has an integration dependency with the execution environment. We had to override Node's HTTP functionality to return our mock list of exams to accommodate examHttpRepository.getByStudentId(:studentID) in this test.

At this point, you might be fairly asking yourself "Meh, this works. What's the big deal with having this type of testing?". The biggest disadvantage is that the test is slightly implementation aware. It knows that it must provide a certain environment due to the underlying HTTP implementation detail. If we decided to change the protocol or the location of the exam resource, the test must be changed accordingly as well. In other words, our test would be coupled to the "how" rather than the "what" of the function.

Dependency Injection To The Rescue

This is where dependency injection comes into play. Rather than explicitly coupling the getStudentAverageGrade function to the examHttpRepository directly, we can instead expect the repository to be "injected" instead. This is just a fancy way of saying that the repository will be passed in as a parameter making the getStudentAverageGrade function coupled to the interface of the ExamRepository rather than the concretion. Take a look at the following amendments.

import { average } from "./utils";
import { IExamRepository } from "./student-repository";

const calculateAverageGrade = (exams: Exam[]) => {
  const grades = exams.map(exam => exam.grade);
  return average(grades);
}

const getStudentAverageGrade = (examRepository: IExamRepository, studentId: string) => {
  const exams = examRepository.getByStudentId(studentId);
  return calculateAverageGrade(exams);
}

export default getStudentAverageGrade

Although this is a minor change to the previous implementation, it presents huge advantages to the modularity and testability of the getStudentAverageGrade function.

import getStudentAverageGrade from "./get-student-average-grade";

describe("getStudentAverageGrade", () => {
  it("should get a student's average grade", async () => { 
    const mockExams = [
      { name: 'math', grade: 90 },
      { name: 'history', grade: 80 }
    ];

    const mockExamRepo: IExamRepository = {
      getByStudentId: (id: string) => Promise.resolve(mockExams)
    }

    const averageGrade = await getStudentAverageGrade(mockExamRepo, 'abc');
    expect(averageGrade).toBe(85);
  });
});

This test is no longer coupled to the getStudentAverageGrade nor is it implementation aware anymore. This enables it to be driven by the function's public API and be explicitly converted into a fully isolated unit test. As for the point on modularity, getStudentAverageGrade is now able to use alternative variants of the exam repository that abide by the IExamRepository interface and not care about the implementation details behind those variants. It shouldn't matter if the repository uses HTTP, web sockets, or the browser's local storage. The test would still pass.

You can take this example one step further. I personally would like to preserve the initial intuitive signature of getStudentAverageGrade such that it still takes in a student ID only and returns back the average grade. We can do so by creating a higher-order function, a factory, that would return our desired signature.

import { average } from "./utils";
import { IExamRepository, examRepositoryHttp } from "./student-repository";

interface IGetStudentAverageGrade {
  (studentID: string) => number;
}

const calculateAverageGrade = (exams: Exam[]) => {
  const grades = exams.map(exam => exam.grade);
  return average(grades);
}

// This is the higher-order function
const makeGetStudentAverageGrade = (examRepository: IExamRepository) => (
  studentId: string
) => {
  const exams = examRepository.getByStudentId(studentId);
  return calculateAverageGrade(exams);
}

export default makeGetStudentAverageGrade

// Generally the injection would occur in a separate place. for example:
// const getStudentAverageGrade = makeGetStudentAverageGrade(examRepositoryHttp);

With this setup, you are able to inject the variant of the examRepository that you need only once upon booting the application. This factory method would return a version of the getStudentAverageGrade function with the chosen repository variant preloaded in. We have preserved the simple contract that we started off with, (studentId: string) => number, increased code modularity, and simplified testing as you will see below.

import makeGetStudentAverageGrade from "./get-student-average-grade";

describe("getStudentAverageGrade", () => {
  it("should get a student's average grade", async () => { 
    const mockExams = [
      { name: 'math', grade: 90 },
      { name: 'history', grade: 80 }
    ];

    const mockExamRepo: IExamRepository = {
      getByStudentId: (id: string) => Promise.resolve(mockExams)
    }

    const getStudentAverageGrade = makeGetStudentAverageGrade(mockExamRepo);
    const averageGrade = await getStudentAverageGrade('abc');
    expect(averageGrade).toBe(85);
  });
});

Pretty neat!

Are Integration Tests Necessary?

In short, yes. Integration tests definitely provide value to the code base. But if we take a look at the example we went through, an integration test is not necessary to test the getStudentAverageGrade function. Thinking critically about this, it's only our HTTP variant of the exam repository, not the mock variant, that produces a side-effect. It's only this variant that should be tested with integration test techniques. This means that integration test coverages can be minimized to the smallest side-effect producing units within the application.

Conclusion

I hope this example was able to demonstrate that it is highly possible to reduce the number of integration tests by amending your application's architecture and design. By promoting dependency injection, you enable your codebase to be more modular which inherently increases the number of unit tests as well. There is nothing wrong with having integration tests in your application as they are still valuable. But a high number of them may be an indicator that an improvement could be made to the software.