Unique identifier for an event stream.

Streams are logical groupings of related events, typically representing the lifecycle of a single aggregate or entity.

Unique identifier for an individual event.

Correlation identifier for tracking related events across streams.

Used to trace causally-related events that span multiple streams or external system boundaries.

Local stream version - simple incrementing number per stream (1, 2, 3, ...)

Core interface for event store backends.

Provides methods for inserting events and subscribing to event streams. Each backend defines its own constraints via StoreConstraints.

Handle to interact with a specific storage backend.

Contains backend-specific configuration like connection pools, file handles, or in-memory storage references.

The type family is injective: knowing the handle type determines the backend, which helps with type inference.

Position marker within an event store, backend-specific.

For example, PostgreSQL uses a compound cursor of (transaction_no, seq_no), while a simple implementation might use a single sequence number.

The type family is injective: knowing the cursor type determines the backend which helps with type inference.

Write operation for inserting events into a single stream.

Groups events with their version expectation for atomic insertion. The event type e can be SomeLatestEvent for raw events or enriched with metadata.

A multi-stream transactional write operation.

Represents a set of writes to be inserted atomically across multiple streams. All version checks must pass for the entire transaction to succeed.

Ordering Guarantees

• Events within a single stream are totally ordered - they appear in the global event log in the order specified.
• Events across different streams within the same transaction have __no ordering guarantee__ relative to each other. They are inserted atomically but may appear in any interleaving in the global log.

Composition

Transactions form a Monoid, allowing easy composition:

transaction1 <> transaction2 <> transaction3

When combining transactions:

• Events for the same stream are concatenated (events from tx1, then tx2)
• Version expectations are left-biased (tx1's expectation wins)

Example

-- Simple single-event write
let tx = singleEvent streamId NoStream event
result <- insertEvents store Nothing tx

-- Multi-stream with composition
let tx = singleEvent userStreamId NoStream userCreated
      <> appendAfterAny auditLogId auditEntry
result <- insertEvents store Nothing tx

Result of an event insertion operation.

Success data from an event insertion operation.

Contains the global cursor position of the last event inserted and the per-stream cursor positions.

Create a transaction with a single event to a single stream.

This is the primary API - it forces explicit choice of version expectation.

-- Creating a new aggregate
singleEvent accountId NoStream accountCreated

-- Updating with optimistic locking
singleEvent accountId (ExactStreamVersion v) balanceUpdated

-- Append-only log
singleEvent logId Any logEntry

Create a transaction with multiple events to a single stream.

multiEvent streamId NoStream [event1, event2, event3]

Append an event to an existing stream without version checking.

Uses StreamExists for the version expectation - the stream must already exist, but any version is acceptable. Suitable for append-only scenarios where multiple processes may be writing concurrently.

Use Cases

• Audit logs where the log stream is pre-created
• Event logs with concurrent writers
• Not suitable for aggregates with business invariants

-- Audit log entry (stream must exist)
appendAfterAny auditLogId auditEntry

-- Multiple concurrent writers OK
tx1 = appendAfterAny logId event1
tx2 = appendAfterAny logId event2  -- No conflict

Append an event, creating the stream if it doesn't exist.

Uses Any for the version expectation - no version checking at all. This is the most permissive option.

Warning: This provides no concurrency control. Suitable for testing or truly append-only scenarios, but dangerous for aggregates with invariants.

Use Cases

• Testing where you don't care about stream state
• Idempotent appends where duplicates are handled elsewhere
• Not suitable for production aggregates

-- Test code
appendToOrCreateStream testStreamId testEvent

-- For production, prefer explicit version expectations
singleEvent streamId NoStream event  -- Better: explicit create

Create a transaction from a list of stream writes.

fromWrites
  [ (stream1, StreamWrite NoStream [e1])
  , (stream2, StreamWrite NoStream [e2])
  ]

Version expectation for optimistic concurrency control.

Used to prevent concurrent modifications by specifying what version a stream should be at before inserting new events.

This implements optimistic locking: instead of holding locks during a read-modify-write cycle, we check at write time that the stream hasn't changed since we read it.

See: https://en.wikipedia.org/wiki/Optimistic_concurrency_control

Common patterns:

• NoStream - Creating a new aggregate (ensure stream doesn't exist)
• ExactStreamVersion - Normal update (check we have latest version)
• Any - Append-only scenarios (no conflict prevention)

Possible errors when interacting with the event store.

General error information with optional exception details.

Consistency violation details containing all version mismatches.

Details of a version expectation failure.

Exception thrown when an event handler fails during subscription processing.

This exception wraps the original exception with rich event context to aid debugging. When a handler throws an exception, the subscription will die immediately (fail-fast), and this enriched exception will be available via the Async handle.

The handler exception represents a bug in event processing code. Higher-level code (such as projection managers) can implement retry logic if desired.

Criteria for selecting events in a subscription.

Stream selection criteria for subscriptions.

Starting position for event subscriptions.

Handle for managing a subscription lifecycle.

Control flow for event subscriptions.

Event with full metadata as retrieved from the store.

Handler function for processing events in a subscription.

Type-safe event matcher for handling different event types in subscriptions.

Constructed using the match helper with (:?) to build a chain of handlers:

matcher = match "user_created" handleUserCreated
       :? match "user_updated" handleUserUpdated
       :? MatchEnd

Helper to construct event handler pairs for EventMatcher.

Uses RequiredTypeArguments for better error messages when the type is omitted.

matcher = match "user_created" handleUser :? MatchEnd