aj-geddes/event-sourcing

Event Sourcing

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Store state changes as a sequence of events rather than the current state, enabling temporal queries, audit trails, and event replay.

When to Use

• Audit trail requirements
• Temporal queries (state at any point in time)
• Event-driven microservices
• CQRS implementations
• Financial systems
• Complex domain models
• Debugging and analysis
• Compliance and regulation

Quick Start

Minimal working example:

interface DomainEvent {
  id: string;
  aggregateId: string;
  aggregateType: string;
  eventType: string;
  data: any;
  metadata: {
    userId?: string;
    timestamp: number;
    version: number;
  };
}

interface Aggregate {
  id: string;
  version: number;
}

class EventStore {
  private events: DomainEvent[] = [];

  async appendEvents(
    aggregateId: string,
    expectedVersion: number,
    events: Omit<DomainEvent, "id" | "metadata">[],
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

| Guide | Contents | |---|---| | Event Store (TypeScript) | Event Store (TypeScript) | | Projections (Read Models) | Projections (Read Models) | | Event Store with PostgreSQL | Event Store with PostgreSQL | | Snapshots for Performance | Snapshots for Performance |

Best Practices

✅ DO

• Store events immutably
• Version your events
• Use optimistic concurrency
• Create snapshots for performance
• Use projections for queries
• Keep events small and focused
• Include metadata (timestamp, user, etc.)
• Handle event versioning/migration

❌ DON'T

• Mutate past events
• Store current state only
• Skip concurrency checks
• Query event store for reads
• Make events too large
• Forget about event schema evolution