68 lines
9.3 KiB
Markdown
68 lines
9.3 KiB
Markdown
# @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
|
|
```
|