SKILL.md
Event Sourcing
Table of Contents
- [Overview](#overview)
- [When to Use](#when-to-use)
- [Quick Start](#quick-start)
- [Reference Guides](#reference-guides)
- [Best Practices](#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)
Projections (Read Models)
Event Store with PostgreSQL
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