A comprehensive event sourcing library built on Effect for TypeScript applications.
This library prioritizes leveraging Effect's existing APIs and patterns rather than creating new abstractions. We aim to expose event sourcing capabilities through familiar Effect constructs like Stream, Effect, Layer, and Schema - ensuring developers who know Effect can immediately be productive without learning proprietary APIs.
This monorepo contains the following packages:
Core event sourcing types, interfaces, and in-memory storage implementation. This is the foundation package that defines the EventStore interface and provides an in-memory implementation for development and testing.
PostgreSQL implementation of the EventStore interface. Includes SQL migrations, connection management, and LISTEN/NOTIFY support for real-time event streaming.
Aggregate root patterns for domain-driven design with event sourcing. Focuses purely on write-side concerns and command handling.
Read-side projection building from event streams. Handles the transformation of events into read models.
CQRS command types and schemas for event sourcing. Provides type-safe command and result definitions with Effect Schema validation.
Transport layer contracts and interfaces for message delivery systems. Provides protocol-agnostic abstractions for event streaming.
In-memory transport implementation for testing and development. Provides immediate message delivery without network overhead.
WebSocket transport implementation for real-time event streaming over WebSocket connections.
Protocol implementation for event sourcing messages. Handles message formatting, serialization, and routing.
High-level WebSocket integration combining transport and protocol layers for complete real-time event streaming functionality.
Testing contracts and utilities for verifying event sourcing implementations. Provides standard test suites for compliance testing.
# Core packages
npm install @codeforbreakfast/eventsourcing-store
npm install @codeforbreakfast/eventsourcing-store-postgres # PostgreSQL implementation (optional)
npm install @codeforbreakfast/eventsourcing-commands # CQRS command types and schemas
npm install @codeforbreakfast/eventsourcing-aggregates # Aggregate patterns for write-side
npm install @codeforbreakfast/eventsourcing-projections # Projection patterns for read-side
# Transport layer (choose one or more)
npm install @codeforbreakfast/eventsourcing-transport # Transport contracts
npm install @codeforbreakfast/eventsourcing-transport-inmemory # In-memory transport for testing
npm install @codeforbreakfast/eventsourcing-transport-websocket # WebSocket transport
# Protocol layer
npm install @codeforbreakfast/eventsourcing-protocol # Message protocol
# WebSocket integration (high-level)
npm install @codeforbreakfast/eventsourcing-websocket # Complete WebSocket functionality
# Testing utilities
npm install @codeforbreakfast/eventsourcing-testing-contracts # Testing contractsAll packages require:
- Effect ^3.17.0 as a peer dependency
- TypeScript 5.x
- Bun
- Docker (for running tests with PostgreSQL)
# Install dependencies
bun installThe test suite includes both in-memory and PostgreSQL tests. To run tests:
- Start the PostgreSQL database:
docker-compose up -d- Run tests with environment variables:
TEST_PG_USERNAME=postgres TEST_PG_PASSWORD=postgres TEST_PG_DATABASE=test TEST_PG_HOST=localhost TEST_PG_PORT=5432 bun run test# Build all packages
bun run build
# Lint code
bun run lint
# Type check
bun run checkMIT