Core module for eventium.

Eventium-core provides the core abstractions and utilities for building event sourcing systems in Haskell. It includes event store interfaces, command handlers, projections, read models, process managers, and Template Haskell utilities for generating boilerplate code. This is the foundational package that all other Eventium modules build upon.

Eventium Core

Core abstractions and utilities for building event sourcing systems in Haskell.

Overview

eventium-core is the foundational package of the Eventium event sourcing framework. It provides all the essential abstractions, interfaces, and utilities needed to build event-sourced applications with CQRS patterns.

Key Components

Event Store (Eventium.Store.Class)

• EventStoreReader - Read events from streams (versioned and global)
• EventStoreWriter - Append events with optimistic concurrency control
• StreamEvent - Event metadata wrapper with stream keys and positions

Projection (Eventium.Projection)

Pure event fold for rebuilding state from events. Used for both domain aggregates (write model) and read models (query side).

data Projection state event = Projection
  { projectionSeed :: state
  , projectionEventHandler :: state -> event -> state
  }

Command Handler (Eventium.CommandHandler)

Implements the aggregate pattern from DDD/Event Sourcing. Processes commands, validates against current state, and emits events.

data CommandHandler state event command = CommandHandler
  { commandHandlerHandler :: state -> command -> [event]
  , commandHandlerProjection :: Projection state event
  }

Process Manager (Eventium.ProcessManager)

Coordinates long-running business processes across multiple aggregates. Implements the Saga pattern for complex workflows.

Read Model (Eventium.ReadModel.Class)

Builds denormalized views optimized for queries. Tracks processed events for eventual consistency with the write side.

Serializer (Eventium.Serializer)

Type-safe event serialization/deserialization with JSON support and Template Haskell utilities for automatic boilerplate generation.

Template Haskell Utilities (Eventium.TH)

• deriveJSON - Generate JSON instances
• deriveSumTypeSerializer - Generate serializers for sum types (event polymorphism)
• makeProjection - Generate projection boilerplate

Features

• ✅ Type-safe event sourcing abstractions
• ✅ Optimistic concurrency control with ExpectedPosition
• ✅ CQRS pattern support (command/query separation)
• ✅ Process Manager (Saga) pattern
• ✅ Projection caching for performance
• ✅ Template Haskell for reducing boilerplate
• ✅ Storage backend agnostic (memory, SQL, NoSQL)

Usage

Add eventium-core to your package dependencies:

dependencies:
  - eventium-core

Then choose a storage backend:

• eventium-memory - In-memory (development/testing)
• eventium-sqlite - SQLite (single-process apps)
• eventium-postgresql - PostgreSQL (production systems)

Design Principles

1. Type Safety - Phantom types prevent mixing concerns
2. Functional Purity - Projections are pure folds
3. Abstraction - Backend-agnostic core types
4. CQRS - Clear command/query separation
5. Standard Patterns - Aggregates, Sagas, Read Models

Documentation

• Main README - Project overview
• Design Documentation - Detailed architecture
• Examples - Working applications

License

MIT - see LICENSE.md.