state_machines 0.20.0 → 0.100.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aa5d105c78cb53f15f42e8662dd7f8e0d0d5f8807b88dcbd8b4201f13718384
-  data.tar.gz: d761cedbe052c5c8829626e0875f54dce064f7156162119b4a040594b439068c
+  metadata.gz: 7b5d883e6f3259de8981a9855e50d6f2d859bbd7e9e10a4cc5b4d91ae3fec65f
+  data.tar.gz: 9185125133d36eeed7ae95875a825e0e9a2e4d73b7de286c65be589965d2613d
 SHA512:
-  metadata.gz: 37398c9ca5f2de7413dfb7a8a467984d0fc4d47f8367ea0747fec6d9c1eaca5a7c3439f37988c02dd8ce27622a9a9e54cf5cc0b2d84404f00f92a862c168bb23
-  data.tar.gz: 159022534eb3c308bc2f2c8e960f111053631d3e10adafc9ae8156c95a26165f48690c682229a577bdfecf918b335ebe5b6d57e82e095c924585ad8d11b9d1ee
+  metadata.gz: 4786a92acf6011cc49c6e9f8daa0505d7bfcd26da0d244e351830aed0972ac12656ab39df4f9cf7b35fa4892c7afa02830b7ec0b33876a8624076e60fb273f21
+  data.tar.gz: e87573373f971cea02ebba3dcca45124f49d8ca6354c34756e55fd101deab5649ee349e62b05a3abb7d0fdde9ead78075984a089f7f3070fb4b4768c7af8fcc8

data/README.md

@@ -1,4 +1,5 @@
 ![Build Status](https://github.com/state-machines/state_machines/actions/workflows/ruby.yml/badge.svg)
+
 # State Machines
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
@@ -9,15 +10,21 @@ State Machines adds support for creating state machines for attributes on any Ru
 
 Add this line to your application's Gemfile:
 
-    gem 'state_machines'
+```ruby
+gem 'state_machines'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install state_machines
+```sh
+gem install state_machines
+```
 
 ## Usage
 
@@ -29,6 +36,8 @@ Below is an example of many of the features offered by this plugin, including:
 * Namespaced states
 * Transition callbacks
 * Conditional transitions
+* Coordinated state management guards
+* Asynchronous state machines (async: true)
 * State-driven instance behavior
 * Customized state values
 * Parallel events
@@ -38,11 +47,11 @@ Class definition:
 
 ```ruby
 class Vehicle
-  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy
+  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy, :parking_meter_number
 
   state_machine :state, initial: :parked do
     before_transition parked: any - :parked, do: :put_on_seatbelt
-    
+
     after_transition on: :crash, do: :tow
     after_transition on: :repair, do: :fix
     after_transition any => :parked do |vehicle, transition|
@@ -61,6 +70,18 @@ class Vehicle
       transition [:idling, :first_gear] => :parked
     end
 
+    before_transition on: :park do |vehicle, transition|
+      # If using Rails:
+      # options = transition.args.extract_options!
+
+      options = transition.args.last.is_a?(Hash) ? transition.args.pop : {}
+      meter_number = options[:meter_number]
+
+      unless meter_number.nil?
+        vehicle.parking_meter_number = meter_number
+      end
+    end
+
     event :ignite do
       transition stalled: same, parked: :idling
     end
@@ -130,6 +151,7 @@ class Vehicle
     @seatbelt_on = false
     @time_used = 0
     @auto_shop_busy = true
+    @parking_meter_number = nil
     super() # NOTE: This *must* be called, otherwise states won't get initialized
   end
 
@@ -200,6 +222,11 @@ vehicle.park!                   # => StateMachines:InvalidTransition: Cannot tra
 vehicle.state?(:parked)         # => false
 vehicle.state?(:invalid)        # => IndexError: :invalid is an invalid name
 
+# Transition callbacks can receive arguments
+vehicle.park(meter_number: '12345') # => true
+vehicle.parked?                     # => true
+vehicle.parking_meter_number        # => "12345"
+
 # Namespaced machines have uniquely-generated methods
 vehicle.alarm_state             # => 1
 vehicle.alarm_state_name        # => :active
@@ -220,6 +247,206 @@ vehicle.alarm_state_name                        # => :active
 
 vehicle.fire_events!(:ignite, :enable_alarm)    # => StateMachines:InvalidParallelTransition: Cannot run events in parallel: ignite, enable_alarm
 
+# Coordinated State Management
+
+State machines can coordinate with each other using state guards, allowing transitions to depend on the state of other state machines within the same object. This enables complex system modeling where components are interdependent.
+
+## State Guard Options
+
+### Single State Guards
+
+* `:if_state` - Transition only if another state machine is in a specific state.
+* `:unless_state` - Transition only if another state machine is NOT in a specific state.
+
+```ruby
+class TorpedoSystem
+  state_machine :bay_doors, initial: :closed do
+    event :open do
+      transition closed: :open
+    end
+
+    event :close do
+      transition open: :closed
+    end
+  end
+
+  state_machine :torpedo_status, initial: :loaded do
+    event :fire_torpedo do
+      # Can only fire torpedo if bay doors are open
+      transition loaded: :fired, if_state: { bay_doors: :open }
+    end
+
+    event :reload do
+      # Can only reload if bay doors are closed (for safety)
+      transition fired: :loaded, unless_state: { bay_doors: :open }
+    end
+  end
+end
+
+system = TorpedoSystem.new
+system.fire_torpedo  # => false (bay doors are closed)
+
+system.open_bay_doors!
+system.fire_torpedo  # => true (bay doors are now open)
+```
+
+### Multiple State Guards
+
+* `:if_all_states` - Transition only if ALL specified state machines are in their respective states.
+* `:unless_all_states` - Transition only if NOT ALL specified state machines are in their respective states.
+* `:if_any_state` - Transition only if ANY of the specified state machines are in their respective states.
+* `:unless_any_state` - Transition only if NONE of the specified state machines are in their respective states.
+
+```ruby
+class StarshipBridge
+  state_machine :shields, initial: :down
+  state_machine :weapons, initial: :offline
+  state_machine :warp_core, initial: :stable
+
+  state_machine :alert_status, initial: :green do
+    event :red_alert do
+      # Red alert if ANY critical system needs attention
+      transition green: :red, if_any_state: { warp_core: :critical, shields: :down }
+    end
+
+    event :battle_stations do
+      # Battle stations only if ALL combat systems are ready
+      transition green: :battle, if_all_states: { shields: :up, weapons: :armed }
+    end
+  end
+end
+```
+
+## Error Handling
+
+State guards provide comprehensive error checking:
+
+```ruby
+# Referencing a non-existent state machine
+event :invalid, if_state: { nonexistent_machine: :some_state }
+# => ArgumentError: State machine 'nonexistent_machine' is not defined for StarshipBridge
+
+# Referencing a non-existent state
+event :another_invalid, if_state: { shields: :nonexistent_state }
+# => ArgumentError: State 'nonexistent_state' is not defined in state machine 'shields'
+```
+
+# Asynchronous State Machines
+
+State machines can operate asynchronously for high-performance applications. This is ideal for I/O-bound tasks, such as in web servers or other concurrent environments, where you don't want a long-running state transition (like one involving a network call) to block the entire thread.
+
+This feature is powered by the [async](https://github.com/socketry/async) gem and uses `concurrent-ruby` for enterprise-grade thread safety.
+
+## Platform Compatibility
+
+**Supported Platforms:**
+* MRI Ruby (CRuby) 3.2+
+* Other Ruby engines with full Fiber scheduler support
+
+**Unsupported Platforms:**
+* JRuby - Falls back to synchronous mode with warnings
+* TruffleRuby - Falls back to synchronous mode with warnings
+
+## Basic Async Usage
+
+Enable async mode by adding `async: true` to your state machine declaration:
+
+```ruby
+class AutonomousDrone < StarfleetShip
+  # Async-enabled state machine for autonomous operation
+  state_machine :status, async: true, initial: :docked do
+    event :launch do
+      transition docked: :flying
+    end
+
+    event :land do
+      transition flying: :docked
+    end
+  end
+
+  # Mixed configuration: some machines async, others sync
+  state_machine :teleporter_status, async: true, initial: :offline do
+    event :power_up do
+      transition offline: :charging
+    end
+
+    event :teleport do
+      transition ready: :teleporting
+    end
+  end
+
+  # Weapons remain synchronous for safety
+  state_machine :weapons, initial: :disarmed do
+    event :arm do
+      transition disarmed: :armed
+    end
+  end
+end
+```
+
+## Async Event Methods
+
+Async-enabled machines automatically generate async versions of event methods:
+
+```ruby
+drone = AutonomousDrone.new
+
+# Within an Async context
+Async do
+  # Async event firing - returns Async::Task
+  task = drone.launch_async
+  result = task.wait  # => true
+
+  # Bang methods for strict error handling
+  drone.power_up_async!  # => Async::Task (raises on failure)
+
+  # Generic async event firing
+  drone.fire_event_async(:teleport)  # => Async::Task
+end
+
+# Outside Async context - raises error
+drone.launch_async  # => RuntimeError: launch_async must be called within an Async context
+```
+
+## Thread Safety
+
+Async state machines use enterprise-grade thread safety with `concurrent-ruby`:
+
+```ruby
+# Concurrent operations are automatically thread-safe
+threads = []
+10.times do
+  threads << Thread.new do
+    Async do
+      drone.launch_async.wait
+      drone.land_async.wait
+    end
+  end
+end
+threads.each(&:join)
+```
+
+## Performance Considerations
+
+* **Thread Safety**: Uses `Concurrent::ReentrantReadWriteLock` for optimal read/write performance.
+* **Memory**: Each async-enabled object gets its own mutex (lazy-loaded).
+* **Marshalling**: Objects with async state machines can be serialized (mutex excluded/recreated).
+* **Mixed Mode**: You can mix async and sync state machines in the same class.
+
+## Dependencies
+
+Async functionality requires:
+
+```ruby
+# Gemfile (automatically scoped to MRI Ruby)
+platform :ruby do
+  gem 'async', '>= 2.25.0'
+  gem 'concurrent-ruby', '>= 1.3.5'
+end
+```
+
+*Note: These gems are only installed on supported platforms. JRuby/TruffleRuby won't attempt installation.*
+
 # Human-friendly names can be accessed for states/events
 Vehicle.human_state_name(:first_gear)               # => "first gear"
 Vehicle.human_alarm_state_name(:active)             # => "active"
@@ -256,30 +483,36 @@ vehicle.state_name              # => :parked
 
 ## Testing
 
-State Machines provides a `TestHelper` module with assertion methods to make testing state machines easier and more expressive.
+State Machines provides an optional `TestHelper` module with assertion methods to make testing state machines easier and more expressive.
+
+**Note: TestHelper is not required by default** - you must explicitly require it in your test files.
 
 ### Setup
 
-Include the test helper in your test class:
+First, require the test helper module, then include it in your test class:
 
 ```ruby
 # For Minitest
+require 'state_machines/test_helper'
+
 class VehicleTest < Minitest::Test
   include StateMachines::TestHelper
-  
+
   def test_initial_state
     vehicle = Vehicle.new
-    assert_state vehicle, :state, :parked
+    assert_sm_state vehicle, :parked
   end
 end
 
-# For RSpec  
+# For RSpec
+require 'state_machines/test_helper'
+
 RSpec.describe Vehicle do
   include StateMachines::TestHelper
-  
+
   it "starts in parked state" do
     vehicle = Vehicle.new
-    assert_state vehicle, :state, :parked
+    assert_sm_state vehicle, :parked
   end
 end
 ```
@@ -292,10 +525,17 @@ The TestHelper provides both basic assertions and comprehensive state machine-sp
 
 ```ruby
 vehicle = Vehicle.new
-assert_state vehicle, :state, :parked
-assert_can_transition vehicle, :ignite
-assert_cannot_transition vehicle, :shift_up
-assert_transition vehicle, :ignite, :state, :idling
+
+# New standardized API (all methods prefixed with assert_sm_)
+assert_sm_state(vehicle, :parked)                                    # Uses default :state machine
+assert_sm_state(vehicle, :parked, machine_name: :status)             # Specify machine explicitly
+assert_sm_can_transition(vehicle, :ignite)                           # Test transition capability
+assert_sm_cannot_transition(vehicle, :shift_up)                      # Test transition restriction
+assert_sm_transition(vehicle, :ignite, :idling)                      # Test actual transition
+
+# Multi-FSM examples
+assert_sm_state(vehicle, :inactive, machine_name: :insurance_state)  # Test insurance state
+assert_sm_can_transition(vehicle, :buy_insurance, machine_name: :insurance_state)
 ```
 
 #### Extended State Machine Assertions
@@ -308,7 +548,7 @@ vehicle = Vehicle.new
 assert_sm_states_list machine, [:parked, :idling, :stalled]
 assert_sm_initial_state machine, :parked
 
-# Event behavior  
+# Event behavior
 assert_sm_event_triggers vehicle, :ignite
 refute_sm_event_triggers vehicle, :shift_up
 assert_sm_event_raises_error vehicle, :invalid_event, StateMachines::InvalidTransition
@@ -317,8 +557,106 @@ assert_sm_event_raises_error vehicle, :invalid_event, StateMachines::InvalidTran
 assert_sm_state_persisted record, expected: :active
 ```
 
+#### Indirect Event Testing
+
+Test that methods trigger state machine events indirectly:
+
+```ruby
+# Minitest style
+vehicle = Vehicle.new
+vehicle.ignite  # Put in idling state
+
+# Test that a custom method triggers a specific event
+assert_sm_triggers_event(vehicle, :crash) do
+  vehicle.redline  # Custom method that calls crash! internally
+end
+
+# Test multiple events
+assert_sm_triggers_event(vehicle, [:crash, :emergency]) do
+  vehicle.emergency_stop
+end
+
+# Test on specific state machine (multi-FSM support)
+assert_sm_triggers_event(vehicle, :disable, machine_name: :alarm) do
+  vehicle.turn_off_alarm
+end
+```
+
+```ruby
+# RSpec style (coming soon with proper matcher support)
+RSpec.describe Vehicle do
+  include StateMachines::TestHelper
+
+  it "triggers crash when redlining" do
+    vehicle = Vehicle.new
+    vehicle.ignite
+
+    expect_to_trigger_event(vehicle, :crash) do
+      vehicle.redline
+    end
+  end
+end
+```
+
+#### Callback Definition Testing (TDD Support)
+
+Verify that callbacks are properly defined in your state machine:
+
+```ruby
+# Test after_transition callbacks
+assert_after_transition(Vehicle, on: :crash, do: :tow)
+assert_after_transition(Vehicle, from: :stalled, to: :parked, do: :log_repair)
+
+# Test before_transition callbacks
+assert_before_transition(Vehicle, from: :parked, do: :put_on_seatbelt)
+assert_before_transition(Vehicle, on: :ignite, if: :seatbelt_on?)
+
+# Works with machine instances too
+machine = Vehicle.state_machine(:state)
+assert_after_transition(machine, on: :crash, do: :tow)
+```
+
+#### Multiple State Machine Support
+
+The TestHelper fully supports objects with multiple state machines:
+
+```ruby
+# Example: StarfleetShip with 3 state machines
+ship = StarfleetShip.new
+
+# Test states on different machines
+assert_sm_state(ship, :docked, machine_name: :status)       # Main ship status
+assert_sm_state(ship, :down, machine_name: :shields)        # Shield system
+assert_sm_state(ship, :standby, machine_name: :weapons)     # Weapons system
+
+# Test transitions on specific machines
+assert_sm_transition(ship, :undock, :impulse, machine_name: :status)
+assert_sm_transition(ship, :raise_shields, :up, machine_name: :shields)
+assert_sm_transition(ship, :arm_weapons, :armed, machine_name: :weapons)
+
+# Test event triggering across multiple machines
+assert_sm_triggers_event(ship, :red_alert, machine_name: :status) do
+  ship.engage_combat_mode  # Custom method affecting multiple systems
+end
+
+assert_sm_triggers_event(ship, :raise_shields, machine_name: :shields) do
+  ship.engage_combat_mode
+end
+
+# Test callback definitions on specific machines
+shields_machine = StarfleetShip.state_machine(:shields)
+assert_before_transition(shields_machine, from: :down, to: :up, do: :power_up_shields)
+
+# Test persistence across multiple machines
+assert_sm_state_persisted(ship, "impulse", :status)
+assert_sm_state_persisted(ship, "up", :shields)
+assert_sm_state_persisted(ship, "armed", :weapons)
+```
+
 The test helper works with both Minitest and RSpec, automatically detecting your testing framework.
 
+**Note:** All methods use consistent keyword arguments with `machine_name:` as the last parameter, making the API intuitive and Grep-friendly.
+
 ## Additional Topics
 
 ### Explicit vs. Implicit Event Transitions
@@ -679,7 +1017,7 @@ For RSpec testing, use the custom RSpec matchers:
 
 ## Contributing
 
-1. Fork it ( https://github.com/state-machines/state_machines/fork )
+1. Fork it ( <https://github.com/state-machines/state_machines/fork> )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/state_machines/async_mode/async_event_extensions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Extensions to Event class for async bang methods
+    module AsyncEventExtensions
+      # Generate async bang methods for events when async mode is enabled
+      def define_helper(scope, method, *args, &block)
+        result = super
+
+        # If this is an async-enabled machine and we're defining an event method
+        if scope == :instance && method !~ /_async[!]?$/ && machine.async_mode_enabled?
+          qualified_name = method.to_s
+
+          # Create async version that returns a task
+          machine.define_helper(scope, "#{qualified_name}_async") do |machine, object, *method_args, **kwargs|
+            # Find the machine that has this event
+            target_machine = object.class.state_machines.values.find { |m| m.events[name] }
+
+            unless defined?(::Async::Task) && ::Async::Task.current?
+              raise RuntimeError, "#{qualified_name}_async must be called within an Async context"
+            end
+
+            Async do
+              target_machine.events[name].fire(object, *method_args, **kwargs)
+            end
+          end
+
+          # Create async bang version that raises exceptions when awaited
+          machine.define_helper(scope, "#{qualified_name}_async!") do |machine, object, *method_args, **kwargs|
+            # Find the machine that has this event
+            target_machine = object.class.state_machines.values.find { |m| m.events[name] }
+
+            unless defined?(::Async::Task) && ::Async::Task.current?
+              raise RuntimeError, "#{qualified_name}_async! must be called within an Async context"
+            end
+
+            Async do
+              # Use fire method which will raise exceptions on invalid transitions
+              target_machine.events[name].fire(object, *method_args, **kwargs) || raise(StateMachines::InvalidTransition.new(object, target_machine, name))
+            end
+          end
+        end
+
+        result
+      end
+    end
+  end
+end