Packages
cratis_chronicle
2.1.3
3.23.0
3.22.0
3.21.0
3.20.0
3.19.1
3.18.0
3.17.0
3.16.1
3.16.0
3.15.1
3.15.0
3.14.4
3.14.3
3.14.2
3.14.1
3.14.0
3.13.0
3.12.0
3.11.0
3.10.2
3.10.1
3.10.0
3.9.0
3.8.1
3.8.0
3.7.0
3.6.0
3.5.1
3.5.0
3.4.0
3.3.1
3.3.0
3.2.0
3.1.0
3.0.0
2.2.0
2.1.3
2.1.1
2.0.0
1.0.3
1.0.2
1.0.1
0.2.0
0.0.6
0.0.5
0.0.4
0.0.3
0.0.1
Idiomatic Elixir client for Cratis Chronicle, the open-source event-sourcing database and runtime
Current section
Files
Jump to
Current section
Files
cratis_chronicle
README.md
README.md
# Chronicle Elixir Client
An idiomatic Elixir client for [Cratis Chronicle](https://github.com/Cratis/Chronicle).
## Overview
`cratis_chronicle` provides a clean Elixir API for interacting with the Chronicle Kernel. It builds on the Chronicle gRPC API and exposes OTP-native constructs including:
- **`use Chronicle.EventType`** — annotate structs as event types with stable IDs
- **`use Chronicle.ReadModel`** — declare model-bound projections executed server-side
- **`use Chronicle.Reactor`** — react to events with side effects
- **`use Chronicle.Reducer`** — fold events into read models in your own process
- **`use Chronicle.Seeder`** — seed event stores with baseline events at startup
- **Model-bound constraints** — unique and unique-event-type constraints on event types
- **Context-aware appends** — process-scoped identity, correlation, and causation metadata
- **Optimistic concurrency** — guard appends with scoped tail-sequence checks
- **Transactions** — buffer and commit multi-event units of work
- **Jobs and webhooks** — inspect Chronicle jobs and manage webhook registrations
- **Resilient connection** — automatic reconnection with exponential backoff
## Structure
```text
Source/
chronicle/ ← cratis_chronicle Hex package
Documentation/ ← User-facing documentation
Samples/
console/ ← Runnable console example
```
## Prerequisite: Chronicle Running
You need a Chronicle Kernel available before running samples or application code.
The easiest local setup is the development Docker image:
```bash
docker run -p 35000:35000 cratis/chronicle:latest-development
```
## Getting Started
See [Documentation/getting-started.md](./Documentation/getting-started.md) for installation and usage instructions.
## Quick Example
```elixir
defmodule MyApp.Events.AccountOpened do
use Chronicle.EventType, id: "account-opened-v1"
defstruct [:account_id, :owner_name, :initial_balance]
end
defmodule MyApp.ReadModels.Account do
use Chronicle.ReadModel
alias MyApp.Events.AccountOpened
defstruct account_id: nil, owner_name: nil, balance: 0
from AccountOpened,
set: [
account_id: :event_source_id,
owner_name: :owner_name,
balance: :initial_balance
]
end
defmodule MyApp.Application do
use Application
def start(_type, _args) do
children = [
{Chronicle.Client,
connection_string: "chronicle://localhost:35000",
event_store: "my-app",
otp_app: :my_app}
]
Supervisor.start_link(children, strategy: :one_for_one)
end
end
# Append an event
:ok = Chronicle.append("account-42", %MyApp.Events.AccountOpened{
account_id: "account-42",
owner_name: "Alice",
initial_balance: 1000
})
# Read back the current read model
{:ok, account} = Chronicle.read_model(MyApp.ReadModels.Account, "account-42")
```
## Building
```bash
cd Source/chronicle
mix deps.get
mix compile
```
## Running the Console Sample
A working example is in the [`Samples/console`](Samples/console) directory.
**Prerequisites:** A Chronicle kernel running locally on port 35000.
```bash
cd Samples/console
mix deps.get
mix run --no-halt
```
Set `CHRONICLE_CONNECTION_STRING` to override the default connection:
```bash
CHRONICLE_CONNECTION_STRING="chronicle://myserver:35000?apiKey=secret" mix run --no-halt
```