state_machines
A Ruby library for adding state machines to any class with support for async operations, coordinated state management, and comprehensive testing.
What is state_machines?
State Machines is a Ruby library that adds support for creating state machines for attributes on any Ruby class. It solves the problem of managing complex state transitions in Ruby applications by providing a declarative syntax for defining states, events, and transitions with callbacks and conditions. The library supports both synchronous and asynchronous operations, making it suitable for a wide range of applications.
Ruby developers building applications that require modeling stateful behavior, such as workflows, order processing, or system status management. It is particularly useful for those using frameworks like Rails, Sinatra, or Hanami who need robust state management.
Developers choose State Machines for its flexibility, comprehensive feature set, and strong integration with popular Ruby frameworks. Its support for async operations, coordinated state management, and extensive testing utilities make it a powerful tool for building maintainable and scalable state-driven applications.
Overview
Adds support for creating state machines for attributes on any Ruby class
Use Cases
Best For
- Modeling complex workflows with multiple interdependent states
- Building async-enabled state machines for high-performance Ruby applications
- Adding state management to ActiveRecord models with database persistence
- Testing state transitions and callbacks with Minitest or RSpec
- Creating coordinated state systems where transitions depend on other state machines
- Visualizing state machines with built-in drawing utilities for debugging
Not Ideal For
- Projects using JRuby or TruffleRuby that require async state transitions, as async support falls back to synchronous mode with warnings.
- Simple applications with basic state logic that don't need callbacks, conditions, or coordinated state management, where a lighter solution like aasm might suffice.
- Teams wanting a single-gem solution with built-in database persistence, since you need separate gems for ActiveRecord or other ORM integrations.
- Projects requiring zero-configuration or visual state machine builders, as this is a code-first library without GUI tools.
Pros & Cons
Pros
Supports asynchronous transitions using Ruby's Fiber scheduler, ideal for high-performance, I/O-bound applications like web servers without blocking threads.
Provides guards like if_state and unless_state for coordinating multiple state machines, enabling complex interdependent systems such as safety-critical workflows.
Includes a TestHelper module with assertions for Minitest and RSpec, simplifying testing of state transitions, callbacks, and event triggering.
Offers multiple syntax options and separate gems for frameworks like ActiveRecord and Mongoid, allowing adaptation to different coding styles and migration needs.
Cons
Requires calling super() in the initialize method to properly set up states, which is easy to forget and can lead to subtle bugs if omitted.
For database persistence, you must install separate integration gems, adding setup complexity and maintenance overhead compared to all-in-one solutions.
Async functionality only works fully on MRI Ruby 3.2+, with fallbacks on JRuby and TruffleRuby, limiting compatibility for teams using alternative Ruby engines.
Frequently Asked Questions
Related Projects
AASMAASM - State machines for Ruby classes (plain Ruby, ActiveRecord, Mongoid, NoBrainer, Dynamoid)
StatesmanA statesmanlike state machine library.
FiniteMachineA minimal finite state machine with a straightforward syntax.
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.