# @suaveplan/event-sourcing - Event sourcing patterns: aggregate root, typed event store, snapshot support, projections, upcasting, and OTel instrumentation

## Summary

Event sourcing patterns for Suaveplan: typed aggregate root, in-memory event store with optimistic concurrency, snapshot support, projections, upcasting, and OTel instrumentation.

<!-- begin:auto-docs -->
## Documentation tree

- [aggregate](./src/core/aggregate/aggregate.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [aggregate](./src/core/aggregate/aggregate.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [memory-event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [event-sourcing-error](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [event-sourcing.schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [aggregate](./src/core/aggregate/aggregate.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-sourcing-error](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-sourcing.schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate](./src/core/aggregate/aggregate.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-sourcing-error](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-sourcing.schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate](./src/core/aggregate/aggregate.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-sourcing-error](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-sourcing.schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate](./src/core/aggregate/aggregate.md) — <!-- begin:auto-docs --> _(no submodules)_- [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_  - [aggregate-repository](./src/core/aggregate-repository/aggregate-repository.md) — <!-- begin:auto-docs --> _(no submodules)_- [event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_  - [memory-event-store](./src/core/event-store/memory-event-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [event-sourcing-error](./src/errors/event-sourcing-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_  - [builder](./src/projection/builder/builder.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_  - [event-sourcing.schemas](./src/schemas/event-sourcing.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_  - [upcaster](./src/upcasting/upcaster/upcaster.md) — <!-- begin:auto-docs --> _(no submodules)_
## Modules

- [Aggregate](src/core/aggregate/aggregate.md) — abstract base class for event-sourced aggregates
- [MemoryEventStore](src/core/event-store/memory-event-store.md) — in-memory EventStore with concurrency control
- [AggregateRepository](src/core/aggregate-repository/aggregate-repository.md) — load/save orchestrator with snapshot support
- [ProjectionBuilder](src/projection/projection-builder/projection-builder.md) — declarative read-model projections
- [Upcaster](src/upcasting/upcaster/upcaster.md) — event schema migration registry
- [EventSourcingError](src/errors/event-sourcing-error.md) — structured errors with stable codes
- [Schemas](src/schemas/event-sourcing.schemas.md) — Zod schemas for all wire types
- [Types](src/types/event-sourcing.types.md) — shared TypeScript interfaces

## Quick Start

```ts
import {
  Aggregate,
  createMemoryEventStore,
  createAggregateRepository,
  createProjection,
} from "@suaveplan/event-sourcing";
import type { DomainEvent } from "@suaveplan/event-sourcing";

class OrderAggregate extends Aggregate<{ total: number }> {
  constructor(id: string) { super(id, { total: 0 }); }
  place(total: number) { this.raise("OrderPlaced", { total }); }
  protected applyEvent(e: DomainEvent) {
    if (e.type === "OrderPlaced") {
      this.state = { total: (e.payload as { total: number }).total };
    }
  }
  get total() { return this.state.total; }
}

const store = createMemoryEventStore();
const repo = createAggregateRepository({ store, factory: (id) => new OrderAggregate(id) });

const order = new OrderAggregate("order-1");
order.place(250);
await repo.save(order);

const loaded = await repo.load("order-1");
console.log(loaded.total); // 250
```