An event store: an adapter, the options it runs with, and a middleware pipeline.

A store is a plain value built with new/1 and passed explicitly to every call:

store =
  Sourced.EventStore.new(
    adapter: Sourced.EventStore.Postgres,
    config: [repo: MyApp.Repo]
  )

:config is handed to the adapter when it starts, and :middleware builds the pipeline every operation runs through. Adapters name the process they register after themselves, so running more than one store on the same adapter means giving each a :name in its config.

Add the store to your supervision tree:

children = [{Sourced.EventStore, store}]

Then pass it to the store functions:

Sourced.EventStore.append(store, events, opts)
Sourced.EventStore.query(store, opts)
Sourced.EventStore.stream(store, opts)

Building a store runs each middleware's Sourced.Middleware.init/1, so it is worth doing once rather than per call. What comes back is plain data — keep it wherever suits the application. A module attribute moves the work to compile time:

defmodule MyApp.EventStore do
  @store Sourced.EventStore.new(
           adapter: Sourced.EventStore.Postgres,
           config: [repo: MyApp.Repo]
         )

  def store, do: @store
end

Middleware

The store itself is agnostic about how events are shaped — its only job is to hand event maps to the adapter and return Sourced.StoredEvents from reads. Everything else is a Sourced.Middleware: a composable transform wrapped around the adapter call. Pass a :middleware list to layer them on. The first entry is the outermost wrapper.

The most common middleware is Sourced.Middleware.Domain, which lets you append and query domain event structs directly instead of hand-built event maps. It takes the list of event modules it should know about:

store =
  Sourced.EventStore.new(
    adapter: Sourced.EventStore.Postgres,
    config: [repo: MyApp.Repo],
    middleware: [
      {Sourced.Middleware.Domain, [OrderPlaced, OrderShipped]}
    ]
  )

{:ok, _} = Sourced.EventStore.append(store, [%OrderPlaced{id: 123}])

{:ok, %{events: [%Sourced.StoredEvent{data: %OrderPlaced{id: 123}}]}} =
  Sourced.EventStore.query(store, query: [%{types: [OrderPlaced]}])

A bare struct is wrapped in an event map with its type taken from the event module's Sourced.Middleware.Domain.Event.to_type/0, its tags from Sourced.Middleware.Domain.Event.to_tags/1, occurred_at set to the current time, and empty metadata. To control those fields, write the event map yourself — structs and event maps can be mixed in one append:

Sourced.EventStore.append(store, [
  %OrderPlaced{id: 123},
  %{
    type: OrderShipped.to_type(),
    data: %OrderShipped{id: 123},
    tags: ["order:123"],
    metadata: %{"user" => "alice"},
    occurred_at: shipped_at
  }
])

On reads, the domain middleware decodes each stored event's data back into its domain struct (serializing adapters return plain maps; non-serializing adapters return the struct untouched). Events whose type is not registered in the domain keep their raw data and log a warning, so old event types never fail a query.

Serializing adapters also need domain events to be JSON-encodable; see Sourced.Middleware.Domain.Event and the adapter docs.