event-sourcing

Event Sourcing

Event Sourcing ensures that all changes to application state are stored as a sequence of events. We don't just store the current state; we store "what happened".

When to Use

• Complete Audit & Compliance Trails: Financial ledgers, healthcare records, and legal systems where historical state cannot be overwritten.
• Temporal Queries & Time Travel: Reconstructing the exact state of an entity as of any specific timestamp in history.
• Complex Domain Debugging: Replaying production incident events in local environments to pinpoint exact logic flaws.
• High-Velocity Append-Only Ingestion: Maximizing write throughput by appending immutable events without updates or delete locks.

Quick Start

// Append-only domain event structure and aggregate reconstruction
interface DomainEvent {
  eventId: string;
  aggregateId: string;
  type: string;
  payload: Record<string, any>;
  timestamp: number;
}

class OrderAggregate {
  public id: string = "";
  public status: "PENDING" | "PAID" | "SHIPPED" = "PENDING";

  apply(event: DomainEvent): void {
    switch (event.type) {
      case "ORDER_CREATED":
        this.id = event.aggregateId;
        this.status = "PENDING";
        break;
      case "ORDER_PAID":
        this.status = "PAID";
        break;
      case "ORDER_SHIPPED":
        this.status = "SHIPPED";
        break;
    }
  }

  static reconstruct(events: DomainEvent[]): OrderAggregate {
    const aggregate = new OrderAggregate();
    for (const event of events) {
      aggregate.apply(event);
    }
    return aggregate;
  }
}

Core Concepts

Immutable Event Stream Architecture

State is derived purely by folding historical events sequentially over an initial empty state:

Stream: Account-42
Event 1: AccountOpened(initialDeposit: 100)  -> Balance = 100
Event 2: MoneyDeposited(amount: 50)          -> Balance = 150
Event 3: MoneyWithdrawn(amount: 30)          -> Balance = 120 (Current State)

State Reconstruction via Aggregate Replay