Eparch

License

EPARCH OF THE CITY (ἔπαρχος τῆς πόλεως), successor of the late Roman URBAN PREFECT, the governor of Constantinople. [^1]
[^1]: The Oxford Dictionary of Byzantium, Vol II.

Eparch is a Gleam library that wraps certain Erlang/OTP behaviours with a type-safe API, making your byzantine systems shine with a great type system.

Supported OTP Behaviours

Module	Wraps	Purpose
`eparch/state_machine`	`gen_statem`	Type-safe finite state machines
`eparch/event_manager`	`gen_event`	Broadcast event managers with dynamic handlers

Full API reference: https://hexdocs.pm/eparch.

Key Differences from `gen_statem`

Erlang's `gen_statem`	`eparch/state_machine`
Separate `handle_call`, `handle_cast`, `handle_info`	Single handler dispatching on a unified `Event` type
Raw action tuples	Type-safe `Action` values
`state_enter` always on	Opt-in via `with_state_enter()`
Multiple return tuple formats	Single `Step` type (`NextState`, `KeepState`, `Stop`)

Key Differences from `gen_event`

Erlang's `gen_event`	`eparch/event_manager`
Separate handler callback module per handler	Single `Handler` builder (`new_handler/2`, `on_terminate/2`)
Handler identified by `{Module, Id}` tuple	Opaque `HandlerRef` returned by `add_handler`
`handle_call` for per-handler queries	Embed `process.Subject(reply)` in your event type instead
`add_sup_handler`	`add_supervised_handler`

Installation

gleam add eparch

Usage

See the Quick Start guide for full walkthroughs, or run some of the example projects that live in the examples/ directory.

Development

The project uses devenv and Nix for a hermetic development environment:

nix develop

Or, if you are already using direnv:

direnv allow .