I’ve been thinking a lot about how we build systems that not only perform well but also maintain a complete history of every change. In my work with complex applications, I’ve found that traditional databases often fall short when we need to understand why something happened or recover from unexpected states. This led me to explore event sourcing, and I want to share how you can build a robust system using Node.js, TypeScript, and EventStore.

Event sourcing fundamentally changes how we think about data. Instead of storing just the current state, we capture every change as an immutable event. This approach gives us a complete audit trail and the ability to reconstruct state at any point in time. Have you ever needed to debug why a user’s order total changed unexpectedly? With event sourcing, you can see exactly what happened and when.

Let me show you how to set up a project. We’ll start with a simple Node.js and TypeScript setup. First, create a new directory and initialize the project. I prefer using npm for package management.

mkdir event-sourcing-app
cd event-sourcing-app
npm init -y

Next, install the core dependencies. We’ll need Express for our API, the EventStore client, and some utilities.

npm install express @eventstore/db-client uuid
npm install -D typescript @types/node ts-node

Here’s a basic TypeScript configuration. I like to keep it strict to catch errors early.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

Now, let’s define our core event interface. This ensures all events in our system have a consistent structure.

interface DomainEvent {
  eventId: string;
  eventType: string;
  aggregateId: string;
  timestamp: Date;
  data: Record<string, any>;
}

Why is this important? Well, have you considered how you’d handle events from different parts of your system? A standardized interface makes it easier to process and store them.

Next, we create an aggregate root. This is the heart of our domain model. It manages state changes through events.

abstract class AggregateRoot {
  private uncommittedEvents: DomainEvent[] = [];

  protected applyEvent(event: DomainEvent): void {
    this.uncommittedEvents.push(event);
    // Apply the event to change state
  }

  getUncommittedEvents(): DomainEvent[] {
    return this.uncommittedEvents;
  }

  clearEvents(): void {
    this.uncommittedEvents = [];
  }
}

Let’s implement a concrete example: an order aggregate. Imagine you’re building an e-commerce system. How would you track every change to an order?

class Order extends AggregateRoot {
  private status: string = 'PENDING';
  private items: any[] = [];

  createOrder(customerId: string, items: any[]): void {
    const event: DomainEvent = {
      eventId: 'uuid-generated',
      eventType: 'OrderCreated',
      aggregateId: this.id,
      timestamp: new Date(),
      data: { customerId, items }
    };
    this.applyEvent(event);
  }

  private onOrderCreated(event: DomainEvent): void {
    this.status = 'CREATED';
    this.items = event.data.items;
  }
}

Connecting to EventStore is straightforward. Here’s how I set up a simple client.

import { EventStoreDBClient } from '@eventstore/db-client';

const client = EventStoreDBClient.connectionString('esdb://localhost:2113');

When saving events, we append them to a stream. Each aggregate has its own stream, identified by its ID.

async function saveEvents(aggregateId: string, events: DomainEvent[]): Promise<void> {
  for (const event of events) {
    await client.appendToStream(`order-${aggregateId}`, event);
  }
}

Reading events back is just as simple. We can replay them to rebuild an aggregate’s state.

async function loadOrder(orderId: string): Promise<Order> {
  const events = await client.readStream(`order-${orderId}`);
  const order = new Order(orderId);
  events.forEach(event => order.applyEvent(event));
  return order;
}

But what about performance when you have thousands of events? This is where snapshots come in. Periodically, we save the current state to avoid replaying all events.

class OrderSnapshot {
  constructor(
    public orderId: string,
    public status: string,
    public version: number
  ) {}
}

Error handling is crucial. I always wrap event operations in try-catch blocks and implement retry logic for concurrency issues.

async function safeAppend(stream: string, event: DomainEvent, expectedVersion: number) {
  try {
    await client.appendToStream(stream, event, { expectedRevision: expectedVersion });
  } catch (error) {
    // Handle concurrency conflicts
    if (error.type === 'wrong-expected-version') {
      // Retry or resolve conflict
    }
  }
}

Testing event-sourced systems requires a different approach. I focus on testing the behavior through events.

test('order creation emits OrderCreated event', () => {
  const order = new Order('order-123');
  order.createOrder('customer-1', []);
  const events = order.getUncommittedEvents();
  expect(events[0].eventType).toBe('OrderCreated');
});

In production, monitoring is key. I use logging to track event processing and set up alerts for failed appends.

Deploying this system involves ensuring EventStore is highly available and configuring proper backups. I’ve found that using Docker makes this easier.

Throughout this process, I’ve learned that event sourcing isn’t just about technology—it’s about designing systems that are resilient and understandable. It forces you to think carefully about your domain and how changes propagate.

What challenges have you faced with data consistency in your projects? Could event sourcing help you solve them?

I hope this guide gives you a solid foundation to start building your own event-sourced systems. If you found this helpful, please like, share, and comment with your thoughts or questions. I’d love to hear about your experiences and continue the conversation.