Flow

An event-sourcing library for Elixir: an append-only store, event reducers that fold events into values, and an application that dispatches commands and runs reactors.

The modules live under the Ariadne.Flow namespace. The Postgres store reads and writes ariadne_flow_store*. Those tables were named modac_flow_store* before schema version 3 renamed them, and the rename spans two releases so that a rolling deployment can run old and new code against the same rows — docs/store.md has the upgrade rule that follows from it.

The guides in docs/ cover events, event reducers, the application, the store, encoders and testing.

Open source, not open contribution — issues are welcome, pull requests are not. See CONTRIBUTING.md for why.

Local Development

devbox run setup installs the mix tooling and starts Postgres. Run it after cloning and whenever Postgres is not up — it is idempotent. Everything else runs as a plain mix task inside the devbox shell, which direnv activates on cd:

devbox run setup # Install the mix tooling and start Postgres
mix test.interactive # Run tests interactively in watch mode
mix ci # Run all tests and checks which are also performed in CI
devbox run docs # Build the HTML docs into doc/
devbox run test.stop # Stop the Postgres service

No Docker is involved: the cluster is created by the setup script and lives in .devbox/virtenv/postgresql/data.

The test database listens on port 5544, so it does not collide with other local Postgres instances.

Releases

release-please owns the version and the changelog. The commit-msg hook in .githooks/ rejects subjects that are not Conventional Commits:

feat(store): read events by tag
fix: derive advisory lock keys from SHA-256
feat!: drop the Modac.Flow wire-format shim

Every push to main refreshes a release pull request that bumps version: in mix.exs and writes CHANGELOG.md. Merging it tags vX.Y.Z and publishes a GitHub release. While the library is pre-1.0, feat/fix bump the patch and ! bumps the minor, so a breaking change goes to 0.2.0 rather than 1.0.0.

Cutting the release also publishes the package and its documentation to Hex: the workflow checks out the new tag and runs devbox run publish (MIX_ENV=dev mix hex.publish --yes). It does not re-run the suite — CI runs on the same push, against the very commit being tagged. It authenticates with the HEX_API_KEY repository secret, a Hex API key with write access — created on the hex.pm dashboard, since hex 2.5 no longer generates user keys from the CLI. If that job fails, the release is already tagged, so re-run Release Please via Run workflow and give it the tag to publish.

Dependency Selection

Especially in Elixir do not use/introduce copyleft licenses, e.g. GPL, AGPL, etc.

You can print the license of a dependency with:

sudo apt install xq \
&& mix archive.install --force hex sbom \
&& mix deps.get \
&& mix sbom.cyclonedx --force && cat bom.xml | yq -p xml '.bom.components.component[] | "\(.name) \(.licenses.license.id)"'