Idiomatic Elixir client for the Chronicle event-sourcing platform.

Chronicle is an event-sourcing kernel that stores domain events and projects them into read models. This library provides an idiomatic Elixir interface built on top of the Chronicle gRPC API.

Quick Start

Add the dependency to your mix.exs:

{:cratis_chronicle, "~> 0.1"}

Start Chronicle.Client in your application supervision tree:

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      {Chronicle.Client,
        connection_string: "chronicle://localhost:35000?disableTls=true",
        event_store: "my-app",
        event_types: [MyApp.Events.AccountOpened, MyApp.Events.FundsDeposited],
        migrations: [MyApp.Migrations.AccountOpenedV2Migration],
        reactors: [MyApp.Reactors.NotificationReactor],
        reducers: [MyApp.Reducers.AccountReducer],
        seeders: [MyApp.Seeders.InitialDataSeeder],
        event_store_subscriptions: [
          MyApp.EventStoreSubscriptions.DefaultAccountEvents
        ]}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

Or rely on artifact auto-discovery:

{Chronicle.Client,
  connection_string: "chronicle://localhost:35000?disableTls=true",
  event_store: "my-app",
  otp_app: :my_app}

Defining Event Types

defmodule MyApp.Events.AccountOpened do
  use Chronicle.Events.EventType, id: "account-opened-v1"
  defstruct [:account_id, :owner_name, :initial_balance]
end

Appending Events

Chronicle.append("account-42", %MyApp.Events.AccountOpened{
  account_id: "account-42",
  owner_name: "Alice",
  initial_balance: 1000
})

Reading Read Models

{:ok, account} = Chronicle.read_model(MyApp.ReadModels.Account, "account-42")

Defining Reactors

defmodule MyApp.Reactors.NotificationReactor do
  use Chronicle.Reactors.Reactor

  @handles MyApp.Events.AccountOpened

  @impl true
  def handle(%MyApp.Events.AccountOpened{} = event, _context) do
    MyApp.Mailer.welcome(event.owner_name)
    :ok
  end
end

Defining Reducers

defmodule MyApp.Reducers.AccountReducer do
  use Chronicle.Reducers.Reducer, model: MyApp.ReadModels.Account

  @handles MyApp.Events.AccountOpened

  @impl true
  def reduce(%MyApp.Events.AccountOpened{} = event, _model, _context) do
    %MyApp.ReadModels.Account{
      account_id: event.account_id,
      owner_name: event.owner_name,
      balance: event.initial_balance
    }
  end
end

Defining Seeders

defmodule MyApp.Seeders.InitialDataSeeder do
  use Chronicle.Seeding.Seeder

  @impl true
  def seed(builder) do
    builder
    |> Chronicle.Seeding.for(
      MyApp.Events.AccountOpened,
      "seed-account-1",
      [%MyApp.Events.AccountOpened{
        account_id: "seed-account-1",
        owner_name: "Initial User",
        initial_balance: 10_000
      }]
    )
  end
end

Modules

• Chronicle.Client — the main supervisor; start it in your supervision tree
• Chronicle.Correlation.CorrelationId / Chronicle.Correlation.CorrelationIdManager — correlate operations
• Chronicle.Identity / Chronicle.Identity.IdentityProvider — track who caused state changes
• Chronicle.Auditing.CausationType, Chronicle.Auditing.CausationEntry, Chronicle.Auditing.CausationManager — audit causation chains
• Chronicle.Events.EventType — macro for defining event types
• Chronicle.Events.Migration — macro for defining event migrations
• Chronicle.Events.MigrationBuilder — fluent API for migration transforms
• Chronicle.Events.Migrators — migration discovery and registration support
• Chronicle.Events.ConcurrencyScope — scope optimistic concurrency checks for appends
• Chronicle.Reactors.Reactor — behaviour for event reactors
• Chronicle.Reducers.Reducer — behaviour for read model reducers
• Chronicle.Seeding.Seeder — behaviour for event seeders
• Chronicle.EventStoreSubscriptions — register event store subscriptions
• Chronicle.EventStoreSubscriptions.Subscription — define discoverable event store subscriptions
• Chronicle.ReadModels.ReadModel — macro for read model structs with embedded projection DSL
• Chronicle.EventSequences.EventLog — append and query events
• Chronicle.EventSequences.EventSequence — work with custom event sequences
• Chronicle.Transactions.UnitOfWork — buffer and commit transactional appends
• Chronicle.EventStores — list event stores and namespaces
• Chronicle.ReadModels — query read model instances
• Chronicle.Jobs — inspect and control Chronicle jobs
• Chronicle.WebHooks — inspect and register webhooks
• Chronicle.Connections.ConnectionString — parse and format connection strings
• Chronicle.Connections.Connection — resilient gRPC channel management