Eparch
![[Nix] Build & Test](https://img.hex.pm/fetch/63f4172ae11a9ac5b517800349e038d09c8e170e/68747470733a2f2f6769746875622e636f6d2f62797a616e74696e652d73797374656d732f6570617263682f616374696f6e732f776f726b666c6f77732f6275696c642e796d6c2f62616467652e737667)
EPARCH OF THE CITY (ἔπαρχος τῆς πόλεως), successor of the late Roman URBAN PREFECT, the governor of Constantinople. 1
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.
Looking for session types? The experimental session-types layer (the protocol grammar, duality witnesses, the specification/projection/codegen toolchain and the
gen_statemprotocol driver) now lives inpacta, which depends on this package. Eparch is the OTP wrapper, and nothing more.
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 .
The Erlang implementation is also a standalone rebar3 library under src/eparch/ffi. Gleam compiles the nested Erlang sources directly when it builds or publishes eparch, while these commands check the Erlang project on its own:
# Compile, run EUnit, and then Dialyzer
make ffi-check
# Regenerate src/eparch/ffi/deps.nix with rebar3_nix
make ffi-deps-nix
nix build .#eparch-ffi
The Oxford Dictionary of Byzantium, Vol II. ↩