State Machines

In state_machine, events can be triggered in two ways:

1. Explicit Transitions: Calling the instance method generated by the event name (e.g., vehicle.ignite). This is the standard approach.
2. Implicit Transitions: Setting a special state event attribute (e.g., vehicle.state_event = 'ignite') and then invoking the action associated with the state machine (e.g., vehicle.save). This is particularly useful for integrations like ActiveRecord or when driving transitions via a web API.

Note: For implicit transitions, check your specific integration's API documentation for the exact attribute name used.

# Explicit
vehicle.ignite

# Implicit (ActiveRecord example)
vehicle.state_event = 'ignite'
vehicle.save

Transitions can be defined in three different contexts:

1. Event Context: Defining transitions inside an event block (most common).
2. State Context: Defining transitions inside a state block. In this context, the from state is inferred automatically.
3. Global Context: Defining transitions directly within the state_machine block, outside of any specific state or event. This is useful for building machines from external data stores.

# State Context
state :parked do
  transition to: :idling, :on => [:ignite, :shift_up], if: :seatbelt_on?
end

# Global Context
state_machine initial: :parked do
  transition parked: :idling, :on => [:ignite, :shift_up]
  transition [:idling, :first_gear] => :parked, on: :park
  transition all - [:parked, :stalled]: :stalled, unless: :auto_shop_busy?
end

To use state machines in your Ruby application, add the gem to your Gemfile:

gem 'state_machines'

Then run bundle to install, or install it directly via the CLI:

gem install state_machines

Note: If you need to persist state in a database (e.g., using Rails, Active Record, or Mongoid), you must install the specific integration gem for your framework from the State Machines organisation.

To use asynchronous state machine features, you must include the async and concurrent-ruby gems in your Gemfile. These are scoped to the ruby platform to avoid installation issues on JRuby or TruffleRuby.

# Gemfile
platform :ruby do
  gem 'async', '>= 2.25.0'
  gem 'concurrent-ruby', '>= 1.3.5'
end

The StateMachines::TestHelper provides expressive assertions for testing state transitions. It is not included by default and must be explicitly required and included in your test classes.

For Minitest:

require 'state_machines/test_helper'
class MyTest < Minitest::Test
  include StateMachines::TestHelper
  # ...
end

For RSpec:

require 'state_machines/test_helper'
RSpec.describe MyClass do
  include StateMachines::TestHelper
  # ...
end

For I/O-bound tasks, you can enable asynchronous mode by adding async: true to the state_machine declaration. This is powered by the async gem and concurrent-ruby.

Supported Platforms:

• MRI Ruby (CRuby) 3.2+
• Other Ruby engines with full Fiber scheduler support.

Note: JRuby and TruffleRuby will fall back to synchronous mode with warnings.

When async: true is enabled, the state machine automatically generates async versions of the event methods.

class AutonomousDrone
  state_machine :status, async: true, initial: :docked do
    event :launch do
      transition docked: :flying
    end
  end
end

Depending on your needs, you may want to install additional gems to extend state_machines functionality:

• Graphing: Use state_machines-graphviz to generate visual diagrams.
• Documentation: Use state_machines-yard for YARD documentation.
• Testing: Use state_machines-rspec to access custom RSpec matchers for testing state transitions.

If your states, events, or transitions are not known until runtime (e.g., they are stored in a database), you can define a machine dynamically using Machine.new. This involves creating a generic class that uses state_machine inside a block to iterate over your external transition definitions.

# Example of a dynamic machine setup
class Vehicle
  attr_accessor :state

  def transitions
    [{parked: :idling, on: :ignite}]
  end

  def machine
    @machine ||= Machine.new(self, initial: :parked, action: :save) do |m|
      transitions.each { |attrs| m.transition(attrs) }
    end
  end
end

# The Machine helper class
class Machine
  def self.new(object, *args, &block)
    machine_class = Class.new
    machine = machine_class.state_machine(*args, &block)
    # ... (logic to delegate attributes and actions to the object) ...
    machine_class.new
  end
end

State Machines supports asynchronous event firing using the async gem. Async methods must be called within an Async block; calling them outside will raise a RuntimeError.

Key patterns:

• event_name_async: Returns an Async::Task. Use .wait to retrieve the result.
• event_name_async!: A 'bang' method that returns an Async::Task but raises an error if the transition fails.
• fire_event_async(:event_name): A generic way to fire an async event by symbol.

Async do
  # Returns Async::Task
  task = drone.launch_async
  result = task.wait  # => true

  # Raises on failure
  drone.power_up_async!  

  # Generic async firing
  drone.fire_event_async(:teleport)
end