ecto_state_machine
A finite state machine pattern implementation for Ecto schemas in Elixir applications.
What is ecto_state_machine?
EctoStateMachine is an Elixir library that implements the finite state machine pattern for Ecto schemas. It allows developers to define states, events, and transitions directly in their Ecto models, providing helper functions for state validation and changeset generation. The library solves the problem of managing complex state transitions in database-backed applications by making them explicit and testable.
Elixir developers building applications with Ecto who need to model stateful entities like users, orders, or documents with clear transition rules and validation.
Developers choose EctoStateMachine because it integrates seamlessly with Ecto's changeset workflow, requires minimal configuration, and allows custom callback logic for side effects during transitions. It avoids external dependencies while providing a clean, declarative API for state management.
Overview
State machine pattern for Ecto
Use Cases
Best For
- Modeling user lifecycle states (e.g., unconfirmed, confirmed, blocked, admin)
- Implementing order or payment workflow transitions in e-commerce applications
- Managing document states in content management systems
- Tracking issue or ticket states in project management tools
- Building stateful entities with complex transition rules in Elixir
- Adding audit-friendly state transition logic to Ecto schemas
Not Ideal For
- Systems requiring advanced finite state machine features like hierarchical or concurrent states
- Projects using other Elixir state machine libraries that prefer a more decoupled architecture
- Applications where state logic should be separated from Ecto models into service layers
Pros & Cons
Pros
Seamlessly integrates with Ecto changesets, allowing state transitions to be validated and persisted using familiar Repo.update calls, as shown in the example workflow.
Enables attaching Elixir functions to events for side effects, such as updating timestamps like confirmed_at, providing flexibility for business logic.
Automatically generates can_*? functions to check transition validity, ensuring state changes adhere to defined rules without manual checks.
Supports storing state in any database column with prefixed helper functions, allowing easy adaptation to existing schemas, as detailed in the custom column section.
Cons
At version 0.1.0 with pending roadmap items like custom error messages and dedicated modules, indicating it may lack stability and features for production use.
Injects all state machine logic directly into Ecto models, which can lead to bloated code and poor separation of concerns, as noted in the roadmap's plan for a dedicated module.
Only supports basic state transitions without advanced features like guards, history, or composite states, restricting use in complex workflow scenarios.
Frequently Asked Questions
Related Projects
flowComputational parallel flows on top of GenStage
witchcraftMonads and other dark magic for Elixir
machineryElixir State machine thin layer for structs
fuseA Circuit Breaker for Erlang
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.