event-sourcing

name	event-sourcing
description	Implement event sourcing and CQRS patterns using event stores, aggregates, and projections. Use when building audit trails, temporal queries, or systems requiring full history.

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