state_machines 0.31.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcd04394640ccea1429d2e121a46e2c705f8c16b2987b142858ad2f151c9c287
-  data.tar.gz: 58cfb25ff972b1b2802730d9084d3c3b27c59a82e694646ce676e38fc661cbb9
+  metadata.gz: bc7dae3a88c68f1327da47debac2546fde7c4459346dbfefaabbc4bed5dc5554
+  data.tar.gz: 2fbfc7157580635bd546b9096138677d44b58a92578d6341667a1722c91ccb66
 SHA512:
-  metadata.gz: c9328eea4f9d8d9e57124571de54bb8f5160a044ef913d3e515bcaac933b7355ccf987c10699c71e94145f44bc1e2387342f350dcbff0100d76a5c1c06645321
-  data.tar.gz: 07c7bfad14f7ce103eec5d6dfa48a9117bc0a73cb5433447c4bf7b6cdea1b87b894a12ad6b85b5a0cb05d63dd68e291f980eeca40e60754c13d5b5c44a7fcf29
+  metadata.gz: 4b5ba6ecdeb4dd612c6865657e0a0b590d3fa67fed522359c7b388ab88401283d953d857fc73fab2fbeb97388c5bb71b5f4e125d70366a03547aea91b991ab35
+  data.tar.gz: 07c96c5556ae74d933de3cf1b132cfda9144404361cca87c24c14694e2158e5f0437d65a4ab08b857dca8ad0c453d7fdc674abeb770c528d7ec45e4b060c8ddd

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

data/lib/state_machines/async_mode/async_events.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Async-aware event firing capabilities using the async gem
+    module AsyncEvents
+      # Fires an event asynchronously using Async
+      # Returns an Async::Task that can be awaited for the result
+      #
+      # Example:
+      #   Async do
+      #     task = vehicle.async_fire_event(:ignite)
+      #     result = task.wait # => true/false
+      #   end
+      def async_fire_event(event_name, *args)
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        # Must be called within an Async context
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "async_fire_event must be called within an Async context. Use: Async { vehicle.async_fire_event(:event) }"
+        end
+
+        Async do
+          machine.events[event_name].fire(self, *args)
+        end
+      end
+
+      # Fires multiple events asynchronously across different state machines
+      # Returns an array of Async::Tasks for concurrent execution
+      #
+      # Example:
+      #   Async do
+      #     tasks = vehicle.async_fire_events(:ignite, :buy_insurance)
+      #     results = tasks.map(&:wait) # => [true, true]
+      #   end
+      def async_fire_events(*event_names)
+        event_names.map { |event_name| async_fire_event(event_name) }
+      end
+
+      # Fires an event asynchronously and waits for completion
+      # This is a convenience method that creates and waits for the task
+      #
+      # Example:
+      #   result = vehicle.fire_event_async(:ignite) # => true/false
+      def fire_event_async(event_name, *args)
+        raise NoMethodError, "undefined method `fire_event_async' for #{self}" unless has_async_machines?
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        if defined?(::Async::Task) && ::Async::Task.current?
+          # Already in async context, just fire directly
+          machine.events[event_name].fire(self, *args)
+        else
+          # Create async context and wait for result
+          Async do
+            machine.events[event_name].fire(self, *args)
+          end.wait
+        end
+      end
+
+      # Fires multiple events asynchronously and waits for all completions
+      # Returns results in the same order as the input events
+      #
+      # Example:
+      #   results = vehicle.fire_events_async(:ignite, :buy_insurance) # => [true, true]
+      def fire_events_async(*event_names)
+        raise NoMethodError, "undefined method `fire_events_async' for #{self}" unless has_async_machines?
+        if defined?(::Async::Task) && ::Async::Task.current?
+          # Already in async context, run concurrently
+          tasks = event_names.map { |event_name| async_fire_event(event_name) }
+          tasks.map(&:wait)
+        else
+          # Create async context and run concurrently
+          Async do
+            tasks = event_names.map { |event_name| async_fire_event(event_name) }
+            tasks.map(&:wait)
+          end.wait
+        end
+      end
+
+      # Fires an event asynchronously using Async and raises exception on failure
+      # Returns an Async::Task that raises StateMachines::InvalidTransition when awaited
+      #
+      # Example:
+      #   Async do
+      #     begin
+      #       task = vehicle.async_fire_event!(:ignite)
+      #       result = task.wait
+      #       puts "Event fired successfully!"
+      #     rescue StateMachines::InvalidTransition => e
+      #       puts "Transition failed: #{e.message}"
+      #     end
+      #   end
+      def async_fire_event!(event_name, *args)
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        # Must be called within an Async context
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "async_fire_event! must be called within an Async context. Use: Async { vehicle.async_fire_event!(:event) }"
+        end
+
+        Async do
+          # Use the bang version which raises exceptions on failure
+          machine.events[event_name].fire(self, *args) || raise(StateMachines::InvalidTransition.new(self, machine, event_name))
+        end
+      end
+
+      # Fires an event asynchronously and waits for result, raising exceptions on failure
+      # This is a convenience method that creates and waits for the task
+      #
+      # Example:
+      #   begin
+      #     result = vehicle.fire_event_async!(:ignite)
+      #     puts "Event fired successfully!"
+      #   rescue StateMachines::InvalidTransition => e
+      #     puts "Transition failed: #{e.message}"
+      #   end
+      def fire_event_async!(event_name, *args)
+        raise NoMethodError, "undefined method `fire_event_async!' for #{self}" unless has_async_machines?
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        if defined?(::Async::Task) && ::Async::Task.current?
+          # Already in async context, just fire directly with bang behavior
+          machine.events[event_name].fire(self, *args) || raise(StateMachines::InvalidTransition.new(self, machine, event_name))
+        else
+          # Create async context and wait for result (may raise exception)
+          Async do
+            machine.events[event_name].fire(self, *args) || raise(StateMachines::InvalidTransition.new(self, machine, event_name))
+          end.wait
+        end
+      end
+
+      # Dynamically handle individual event async methods
+      # This provides launch_async, launch_async!, arm_weapons_async, etc.
+      def method_missing(method_name, *args, **kwargs, &block)
+        method_str = method_name.to_s
+
+        # Check if this is an async event method
+        if method_str.end_with?('_async!')
+          # Remove the _async! suffix to get the base event method
+          base_method = method_str.chomp('_async!').to_sym
+
+          # Check if the base method exists and this machine is async-enabled
+          if respond_to?(base_method) && async_method_for_event?(base_method)
+            return handle_individual_event_async_bang(base_method, *args, **kwargs)
+          end
+        elsif method_str.end_with?('_async')
+          # Remove the _async suffix to get the base event method
+          base_method = method_str.chomp('_async').to_sym
+
+          # Check if the base method exists and this machine is async-enabled
+          if respond_to?(base_method) && async_method_for_event?(base_method)
+            return handle_individual_event_async(base_method, *args, **kwargs)
+          end
+        end
+
+        # If not an async method, call the original method_missing
+        super
+      end
+
+      # Check if we should respond to async methods for this event
+      def respond_to_missing?(method_name, include_private = false)
+        # Only provide async methods if this object has async-enabled machines
+        return super unless has_async_machines?
+
+        method_str = method_name.to_s
+
+        if method_str.end_with?('_async!') || method_str.end_with?('_async')
+          base_method = method_str.chomp('_async!').chomp('_async').to_sym
+          return respond_to?(base_method) && async_method_for_event?(base_method)
+        end
+
+        super
+      end
+
+      # Check if this object has any async-enabled state machines
+      def has_async_machines?
+        self.class.state_machines.any? { |name, machine| machine.async_mode_enabled? }
+      end
+
+      private
+
+      # Check if this event method should have async versions
+      def async_method_for_event?(event_method)
+        # Find which machine contains this event
+        self.class.state_machines.each do |name, machine|
+          if machine.async_mode_enabled?
+            # Check if this event method belongs to this machine
+            machine.events.each do |event|
+              qualified_name = event.qualified_name
+              if qualified_name.to_sym == event_method || "#{qualified_name}!".to_sym == event_method
+                return true
+              end
+            end
+          end
+        end
+        false
+      end
+
+      # Handle individual event async methods (returns task)
+      def handle_individual_event_async(event_method, *args, **kwargs)
+
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "#{event_method}_async must be called within an Async context"
+        end
+
+        Async do
+          send(event_method, *args, **kwargs)
+        end
+      end
+
+      # Handle individual event async bang methods (returns task, raises on failure)
+      def handle_individual_event_async_bang(event_method, *args, **kwargs)
+        # Extract event name from method and use bang version
+        bang_method = "#{event_method}!".to_sym
+
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "#{event_method}_async! must be called within an Async context"
+        end
+
+        Async do
+          send(bang_method, *args, **kwargs)
+        end
+      end
+
+      # Extract event name from method name, handling namespaced events
+      def extract_event_name(method_name)
+        method_str = method_name.to_s
+
+        # Find the machine and event for this method
+        self.class.state_machines.each do |name, machine|
+          machine.events.each do |event|
+            qualified_name = event.qualified_name
+            if qualified_name.to_s == method_str || "#{qualified_name}!".to_s == method_str
+              return event.name
+            end
+          end
+        end
+
+        # Fallback: assume the method name is the event name
+        method_str.chomp('!').to_sym
+      end
+
+      public
+
+      # Fires multiple events concurrently within an async context
+      # This method should be called from within an Async block
+      #
+      # Example:
+      #   Async do
+      #     results = vehicle.fire_events_concurrent(:ignite, :buy_insurance)
+      #   end
+      def fire_events_concurrent(*event_names)
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "fire_events_concurrent must be called within an Async context"
+        end
+
+        tasks = async_fire_events(*event_names)
+        tasks.map(&:wait)
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode/async_machine.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Enhanced machine class with async capabilities
+    module AsyncMachine
+      # Thread-safe state reading for machines
+      def read_safely(object, attribute, ivar = false)
+        if object.respond_to?(:read_state_safely)
+          object.read_state_safely(self, attribute, ivar)
+        else
+          read(object, attribute, ivar)
+        end
+      end
+
+      # Thread-safe state writing for machines
+      def write_safely(object, attribute, value, ivar = false)
+        if object.respond_to?(:write_state_safely)
+          object.write_state_safely(self, attribute, value, ivar)
+        else
+          write(object, attribute, value, ivar)
+        end
+      end
+
+      # Fires an event asynchronously on the given object
+      # Returns an Async::Task for concurrent execution
+      def async_fire_event(object, event_name, *args)
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "async_fire_event must be called within an Async context"
+        end
+
+        Async do
+          events[event_name].fire(object, *args)
+        end
+      end
+
+      # Creates an async-aware transition collection
+      # Supports concurrent transition execution with proper synchronization
+      def create_async_transition_collection(transitions, options = {})
+        if defined?(AsyncTransitionCollection)
+          AsyncTransitionCollection.new(transitions, options)
+        else
+          # Fallback to regular collection if async collection isn't available
+          TransitionCollection.new(transitions, options)
+        end
+      end
+
+      # Thread-safe callback execution for async operations
+      def run_callbacks_safely(type, object, context, transition)
+        if object.respond_to?(:state_machine_mutex)
+          object.state_machine_mutex.with_read_lock do
+            callbacks[type].each { |callback| callback.call(object, context, transition) }
+          end
+        else
+          callbacks[type].each { |callback| callback.call(object, context, transition) }
+        end
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode/async_transition_collection.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Error class for async-specific transition failures
+    class AsyncTransitionError < StateMachines::Error
+      def initialize(object, machines, failed_events)
+        @object = object
+        @machines = machines
+        @failed_events = failed_events
+        super("Failed to perform async transitions: #{failed_events.join(', ')}")
+      end
+
+      attr_reader :object, :machines, :failed_events
+    end
+
+    # Async-aware transition collection that can execute transitions concurrently
+    class AsyncTransitionCollection < TransitionCollection
+      # Performs transitions asynchronously using Async
+      # Provides better concurrency for I/O-bound operations
+      def perform_async(&block)
+        reset
+
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          return Async do
+            perform_async(&block)
+          end.wait
+        end
+
+        if valid?
+          # Create async tasks for each transition
+          tasks = map do |transition|
+            Async do
+              if use_event_attributes? && !block_given?
+                transition.transient = true
+                transition.machine.write_safely(object, :event_transition, transition)
+                run_actions
+                transition
+              else
+                within_transaction do
+                  catch(:halt) { run_callbacks(&block) }
+                  rollback unless success?
+                end
+                transition
+              end
+            end
+          end
+
+          # Wait for all tasks to complete
+          completed_transitions = []
+          tasks.each do |task|
+            begin
+              result = task.wait
+              completed_transitions << result if result
+            rescue StandardError => e
+              # Handle individual transition failures
+              rollback
+              raise AsyncTransitionError.new(object, map(&:machine), [e.message])
+            end
+          end
+
+          # Check if all transitions succeeded
+          @success = completed_transitions.length == length
+        end
+
+        success?
+      end
+
+      # Performs transitions concurrently using threads
+      # Better for CPU-bound operations but requires more careful synchronization
+      def perform_threaded(&block)
+        reset
+
+        if valid?
+          # Use basic thread approach
+          threads = []
+          results = []
+          results_mutex = Concurrent::ReentrantReadWriteLock.new
+
+          each do |transition|
+            threads << Thread.new do
+              begin
+                result = if use_event_attributes? && !block_given?
+                          transition.transient = true
+                          transition.machine.write_safely(object, :event_transition, transition)
+                          run_actions
+                          transition
+                        else
+                          within_transaction do
+                            catch(:halt) { run_callbacks(&block) }
+                            rollback unless success?
+                          end
+                          transition
+                        end
+
+                results_mutex.with_write_lock { results << result }
+              rescue StandardError => e
+                # Handle individual transition failures
+                rollback
+                raise AsyncTransitionError.new(object, [transition.machine], [e.message])
+              end
+            end
+          end
+
+          # Wait for all threads to complete
+          threads.each(&:join)
+          @success = results.length == length
+        end
+
+        success?
+      end
+
+      private
+
+      # Override run_actions to be thread-safe when needed
+      def run_actions(&block)
+        catch_exceptions do
+          @success = if block_given?
+                      result = yield
+                      actions.each { |action| results[action] = result }
+                      !!result
+                    else
+                      actions.compact.each do |action|
+                        next if skip_actions
+
+                        # Use thread-safe write for results
+                        if object.respond_to?(:state_machine_mutex)
+                          object.state_machine_mutex.with_write_lock do
+                            results[action] = object.send(action)
+                          end
+                        else
+                          results[action] = object.send(action)
+                        end
+                      end
+                      results.values.all?
+                    end
+        end
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode/thread_safe_state.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Thread-safe state operations for async-enabled state machines
+    # Uses concurrent-ruby for enterprise-grade thread safety
+    module ThreadSafeState
+      # Gets or creates a reentrant mutex for thread-safe state operations on an object
+      # Each object gets its own mutex to avoid global locking
+      # Uses Concurrent::ReentrantReadWriteLock for better performance
+      def state_machine_mutex
+        @_state_machine_mutex ||= Concurrent::ReentrantReadWriteLock.new
+      end
+
+      # Thread-safe version of state reading
+      # Ensures atomic read operations across concurrent threads
+      def read_state_safely(machine, attribute, ivar = false)
+        state_machine_mutex.with_read_lock do
+          machine.read(self, attribute, ivar)
+        end
+      end
+
+      # Thread-safe version of state writing
+      # Ensures atomic write operations across concurrent threads
+      def write_state_safely(machine, attribute, value, ivar = false)
+        state_machine_mutex.with_write_lock do
+          machine.write(self, attribute, value, ivar)
+        end
+      end
+
+      # Handle marshalling by excluding the mutex (will be recreated when needed)
+      def marshal_dump
+        # Get instance variables excluding the mutex
+        vars = instance_variables.reject { |var| var == :@_state_machine_mutex }
+        vars.map { |var| [var, instance_variable_get(var)] }
+      end
+
+      # Restore marshalled object, mutex will be lazily recreated when needed
+      def marshal_load(data)
+        data.each do |var, value|
+          instance_variable_set(var, value)
+        end
+        # Don't set @_state_machine_mutex - let it be lazily created
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Ruby Engine Compatibility Check
+# The async gem requires native extensions and Fiber scheduler support
+# which are not available on JRuby or TruffleRuby
+if RUBY_ENGINE == 'jruby' || RUBY_ENGINE == 'truffleruby'
+  raise LoadError, <<~ERROR
+    StateMachines::AsyncMode is not available on #{RUBY_ENGINE}.
+
+    The async gem requires native extensions (io-event) and Fiber scheduler support
+    which are not implemented in #{RUBY_ENGINE}. AsyncMode is only supported on:
+
+    • MRI Ruby (CRuby) 3.2+
+    • Other Ruby engines with full Fiber scheduler support
+
+    If you need async support on #{RUBY_ENGINE}, consider using:
+    • java.util.concurrent classes (JRuby)
+    • Native threading libraries for your platform
+    • Or stick with synchronous state machines
+  ERROR
+end
+
+# Load required gems with version constraints
+gem 'async', '>= 2.25.0'
+gem 'concurrent-ruby', '>= 1.3.5'  # Security is not negotiable - enterprise-grade thread safety required
+
+require 'async'
+require 'concurrent-ruby'
+
+# Load all async mode components
+require_relative 'async_mode/thread_safe_state'
+require_relative 'async_mode/async_events'
+require_relative 'async_mode/async_event_extensions'
+require_relative 'async_mode/async_machine'
+require_relative 'async_mode/async_transition_collection'
+
+module StateMachines
+  # AsyncMode provides asynchronous state machine capabilities using the async gem
+  # This module enables concurrent, thread-safe state operations for high-performance applications
+  #
+  # @example Basic usage
+  #   class AutonomousDrone < StarfleetShip
+  #     state_machine :teleporter_status, async: true do
+  #       event :power_up do
+  #         transition offline: :charging
+  #       end
+  #     end
+  #   end
+  #
+  #   drone = AutonomousDrone.new
+  #   Async do
+  #     result = drone.fire_event_async(:power_up)  # => true
+  #     task = drone.power_up_async!               # => Async::Task
+  #   end
+  #
+  module AsyncMode
+    # All components are loaded from separate files:
+    # - ThreadSafeState: Mutex-based thread safety
+    # - AsyncEvents: Async event firing methods
+    # - AsyncEventExtensions: Event method generation
+    # - AsyncMachine: Machine-level async capabilities
+    # - AsyncTransitionCollection: Concurrent transition execution
+  end
+end

data/lib/state_machines/callback.rb

@@ -177,7 +177,8 @@ module StateMachines
     # order.  The callback will only halt if the resulting value from the
     # method passes the terminator.
     def run_methods(object, context = {}, index = 0, *args, &block)
-      if type == :around
+      case type
+      when :around
         current_method = @methods[index]
         if current_method
           yielded = false

data/lib/state_machines/event.rb

@@ -35,15 +35,17 @@ module StateMachines
     # * <tt>:human_name</tt> - The human-readable version of this event's name
     def initialize(machine, name, options = nil, human_name: nil, **extra_options) # :nodoc:
       # Handle both old hash style and new kwargs style for backward compatibility
-      if options.is_a?(Hash)
+      case options
+      in Hash
         # Old style: initialize(machine, name, {human_name: 'Custom Name'})
         StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
         human_name = options[:human_name]
-      else
+      in nil
         # New style: initialize(machine, name, human_name: 'Custom Name')
-        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
-
         StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :human_name) unless extra_options.empty?
+      else
+        # Handle unexpected options
+        raise ArgumentError, "Unexpected positional argument in Event initialize: #{options.inspect}"
       end
 
       @machine = machine

data/lib/state_machines/event_collection.rb

@@ -117,19 +117,27 @@ module StateMachines
       return unless machine.action
 
       # TODO, simplify
-      machine.read(object, :event_transition) || if event_name = machine.read(object, :event)
-                                                   if event = self[event_name.to_sym, :name]
-                                                     event.transition_for(object) || begin
-                                                       # No valid transition: invalidate
-                                                       machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
-                                                       false
-                                                     end
-                                                   else
-                                                     # Event is unknown: invalidate
-                                                     machine.invalidate(object, :event, :invalid) if invalidate
-                                                     false
-                                                   end
-                                                 end
+      # First try the regular event_transition
+      transition = machine.read(object, :event_transition)
+      
+      # If not found and we have stored transitions by machine (issue #91)
+      if !transition && (transitions_by_machine = object.instance_variable_get(:@_state_machine_event_transitions))
+        transition = transitions_by_machine[machine.name]
+      end
+      
+      transition || if event_name = machine.read(object, :event)
+                      if event = self[event_name.to_sym, :name]
+                        event.transition_for(object) || begin
+                          # No valid transition: invalidate
+                          machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
+                          false
+                        end
+                      else
+                        # Event is unknown: invalidate
+                        machine.invalidate(object, :event, :invalid) if invalidate
+                        false
+                      end
+                    end
     end
 
     private

data/lib/state_machines/machine/async_extensions.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# This file provides optional async extensions for the Machine class.
+# It should only be loaded when async functionality is explicitly requested.
+
+module StateMachines
+  class Machine
+    # AsyncMode extensions for the Machine class
+    # Provides async-aware methods while maintaining backward compatibility
+    module AsyncExtensions
+      # Instance methods added to Machine for async support
+
+      # Configure this specific machine instance for async mode
+      #
+      # Example:
+      #   class Vehicle
+      #     state_machine initial: :parked do
+      #       configure_async_mode! # Enable async for this machine
+      #
+      #       event :ignite do
+      #         transition parked: :idling
+      #       end
+      #     end
+      #   end
+      def configure_async_mode!(enabled = true)
+        if enabled
+          begin
+            require 'state_machines/async_mode'
+            @async_mode_enabled = true
+
+            owner_class.include(StateMachines::AsyncMode::ThreadSafeState)
+            owner_class.include(StateMachines::AsyncMode::AsyncEvents)
+            self.extend(StateMachines::AsyncMode::AsyncMachine)
+
+            # Extend events to generate async versions
+            events.each do |event|
+              event.extend(StateMachines::AsyncMode::AsyncEventExtensions)
+            end
+          rescue LoadError => e
+            # Fallback to sync mode with warning (only once per class)
+            unless owner_class.instance_variable_get(:@async_fallback_warned)
+              warn <<~WARNING
+                ⚠️  #{owner_class.name}: Async mode requested but not available on #{RUBY_ENGINE}.
+
+                #{e.message}
+
+                ⚠️  Falling back to synchronous mode. Results may be unpredictable due to engine limitations.
+                For production async support, use MRI Ruby (CRuby) 3.2+
+              WARNING
+              owner_class.instance_variable_set(:@async_fallback_warned, true)
+            end
+
+            @async_mode_enabled = false
+          end
+        else
+          @async_mode_enabled = false
+        end
+
+        self
+      end
+
+      # Check if this specific machine instance has async mode enabled
+      def async_mode_enabled?
+        @async_mode_enabled || false
+      end
+
+      # Thread-safe version of state reading
+      def read_safely(object, attribute, ivar = false)
+        object.read_state_safely(self, attribute, ivar)
+      end
+
+      # Thread-safe version of state writing
+      def write_safely(object, attribute, value, ivar = false)
+        object.write_state_safely(self, attribute, value, ivar)
+      end
+
+      # Thread-safe callback execution for async operations
+      def run_callbacks_safely(type, object, context, transition)
+        object.state_machine_mutex.with_write_lock do
+          callbacks[type].each { |callback| callback.call(object, context, transition) }
+        end
+      end
+    end
+
+    # Include async extensions by default (but only load AsyncMode when requested)
+    include AsyncExtensions
+  end
+end

data/lib/state_machines/machine/class_methods.rb

@@ -30,6 +30,10 @@ module StateMachines
             machine = machine.clone
             machine.initial_state = options[:initial] if options.include?(:initial)
             machine.owner_class = owner_class
+            # Configure async mode if requested in options
+            if options.include?(:async)
+              machine.configure_async_mode!(options[:async])
+            end
           end
 
           # Evaluate DSL

data/lib/state_machines/machine/configuration.rb

@@ -6,7 +6,7 @@ module StateMachines
       # Initializes a new state machine with the given configuration.
       def initialize(owner_class, *args, &)
         options = args.last.is_a?(Hash) ? args.pop : {}
-        StateMachines::OptionsValidator.assert_valid_keys!(options, :attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions)
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions, :async)
 
         # Find an integration that matches this machine's owner class
         @integration = if options.include?(:integration)
@@ -35,6 +35,8 @@ module StateMachines
         @use_transactions = options[:use_transactions]
         @initialize_state = options[:initialize]
         @action_hook_defined = false
+        @async_requested = options[:async]
+
         self.owner_class = owner_class
 
         # Merge with sibling machine configurations
@@ -47,6 +49,12 @@ module StateMachines
 
         # Evaluate DSL
         instance_eval(&) if block_given?
+
+        # Configure async mode if requested, after owner_class is set and DSL is evaluated
+        if @async_requested
+          configure_async_mode!(true)
+        end
+
         self.initial_state = options[:initial] unless sibling_machines.any?
       end
 
@@ -61,6 +69,8 @@ module StateMachines
         @states = @states.dup
         @states.machine = self
         @callbacks = { before: @callbacks[:before].dup, after: @callbacks[:after].dup, failure: @callbacks[:failure].dup }
+        @async_requested = orig.instance_variable_get(:@async_requested)
+        @async_mode_enabled = orig.instance_variable_get(:@async_mode_enabled)
       end
 
       # Sets the class which is the owner of this state machine.  Any methods

data/lib/state_machines/machine.rb

@@ -14,6 +14,7 @@ require_relative 'machine/event_methods'
 require_relative 'machine/callbacks'
 require_relative 'machine/rendering'
 require_relative 'machine/integration'
+require_relative 'machine/async_extensions'
 require_relative 'syntax_validator'
 
 module StateMachines

data/lib/state_machines/state.rb

@@ -55,7 +55,8 @@ module StateMachines
     # * <tt>:human_name</tt> - The human-readable version of this state's name
     def initialize(machine, name, options = nil, initial: false, value: :__not_provided__, cache: nil, if: nil, human_name: nil, **extra_options) # :nodoc:
       # Handle both old hash style and new kwargs style for backward compatibility
-      if options.is_a?(Hash)
+      case options
+      in Hash
         # Old style: initialize(machine, name, {initial: true, value: 'foo'})
         StateMachines::OptionsValidator.assert_valid_keys!(options, :initial, :value, :cache, :if, :human_name)
         initial = options.fetch(:initial, false)
@@ -63,13 +64,13 @@ module StateMachines
         cache = options[:cache]
         if_condition = options[:if]
         human_name = options[:human_name]
-      else
+      in nil
         # New style: initialize(machine, name, initial: true, value: 'foo')
-        # options parameter should be nil in this case
-        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
-
         StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :initial, :value, :cache, :if, :human_name) unless extra_options.empty?
         if_condition = binding.local_variable_get(:if) # 'if' is a keyword, need special handling
+      else
+        # Handle unexpected options
+        raise ArgumentError, "Unexpected positional argument in State initialize: #{options.inspect}"
       end
 
       @machine = machine

data/lib/state_machines/test_helper.rb

@@ -460,6 +460,334 @@ module StateMachines
       _assert_transition_callback(:after, machine_or_class, options, message)
     end
 
+    # === Sync Mode Assertions ===
+
+    # Assert that a state machine is operating in synchronous mode
+    #
+    # @param object [Object] The object with state machines
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If the machine has async mode enabled
+    #
+    # @example
+    #   user = User.new
+    #   assert_sm_sync_mode(user)                           # Uses default :state machine
+    #   assert_sm_sync_mode(user, :status)                  # Uses :status machine
+    def assert_sm_sync_mode(object, machine_name = :state, message = nil)
+      machine = object.class.state_machines[machine_name]
+      raise ArgumentError, "No state machine '#{machine_name}' found" unless machine
+
+      async_enabled = machine.respond_to?(:async_mode_enabled?) && machine.async_mode_enabled?
+      default_message = "Expected state machine '#{machine_name}' to be in sync mode, but async mode is enabled"
+
+      if defined?(::Minitest)
+        refute async_enabled, message || default_message
+      elsif defined?(::RSpec)
+        expect(async_enabled).to be_falsy, message || default_message
+      elsif async_enabled
+        raise default_message
+      end
+    end
+
+    # Assert that async methods are not available on a sync-only object
+    #
+    # @param object [Object] The object with state machines
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If async methods are available
+    #
+    # @example
+    #   sync_only_car = Car.new  # Car has no async: true machines
+    #   assert_sm_no_async_methods(sync_only_car)
+    def assert_sm_no_async_methods(object, message = nil)
+      async_methods = %i[fire_event_async fire_events_async fire_event_async! async_fire_event]
+      available_async_methods = async_methods.select { |method| object.respond_to?(method) }
+
+      default_message = "Expected no async methods to be available, but found: #{available_async_methods.inspect}"
+
+      if defined?(::Minitest)
+        assert_empty available_async_methods, message || default_message
+      elsif defined?(::RSpec)
+        expect(available_async_methods).to be_empty, message || default_message
+      elsif available_async_methods.any?
+        raise default_message
+      end
+    end
+
+    # Assert that an object has no async-enabled state machines
+    #
+    # @param object [Object] The object with state machines
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If any machine has async mode enabled
+    #
+    # @example
+    #   sync_only_vehicle = Vehicle.new  # All machines are sync-only
+    #   assert_sm_all_sync(sync_only_vehicle)
+    def assert_sm_all_sync(object, message = nil)
+      async_machines = []
+
+      object.class.state_machines.each do |name, machine|
+        if machine.respond_to?(:async_mode_enabled?) && machine.async_mode_enabled?
+          async_machines << name
+        end
+      end
+
+      default_message = "Expected all state machines to be sync-only, but these have async enabled: #{async_machines.inspect}"
+
+      if defined?(::Minitest)
+        assert_empty async_machines, message || default_message
+      elsif defined?(::RSpec)
+        expect(async_machines).to be_empty, message || default_message
+      elsif async_machines.any?
+        raise default_message
+      end
+    end
+
+    # Assert that synchronous event execution works correctly
+    #
+    # @param object [Object] The object with state machines
+    # @param event [Symbol] The event to trigger
+    # @param expected_state [Symbol] The expected state after transition
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If sync execution fails
+    #
+    # @example
+    #   car = Car.new
+    #   assert_sm_sync_execution(car, :start, :running)
+    #   assert_sm_sync_execution(car, :turn_on, :active, :alarm)
+    def assert_sm_sync_execution(object, event, expected_state, machine_name = :state, message = nil)
+      # Store initial state
+      initial_state = object.send(machine_name)
+
+      # Execute event synchronously
+      result = object.send("#{event}!")
+
+      # Verify immediate state change (no async delay)
+      final_state = object.send(machine_name)
+
+      # Check that transition succeeded
+      state_changed = initial_state != final_state
+      correct_final_state = final_state.to_s == expected_state.to_s
+
+      default_message = "Expected sync execution of '#{event}' to change #{machine_name} from '#{initial_state}' to '#{expected_state}', but got '#{final_state}'"
+
+      if defined?(::Minitest)
+        assert result, "Event #{event} should return true on success"
+        assert state_changed, "State should change from #{initial_state}"
+        assert correct_final_state, message || default_message
+      elsif defined?(::RSpec)
+        expect(result).to be_truthy, "Event #{event} should return true on success"
+        expect(state_changed).to be_truthy, "State should change from #{initial_state}"
+        expect(correct_final_state).to be_truthy, message || default_message
+      else
+        raise "Event #{event} should return true on success" unless result
+        raise "State should change from #{initial_state}" unless state_changed
+        raise default_message unless correct_final_state
+      end
+    end
+
+    # Assert that event execution is immediate (no async delay)
+    #
+    # @param object [Object] The object with state machines
+    # @param event [Symbol] The event to trigger
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If execution appears to be async
+    #
+    # @example
+    #   car = Car.new
+    #   assert_sm_immediate_execution(car, :start)
+    def assert_sm_immediate_execution(object, event, machine_name = :state, message = nil)
+      initial_state = object.send(machine_name)
+
+      # Record start time and execute
+      start_time = Time.now
+      object.send("#{event}!")
+      execution_time = Time.now - start_time
+
+      final_state = object.send(machine_name)
+      state_changed = initial_state != final_state
+
+      # Should complete very quickly (under 10ms for sync operations)
+      is_immediate = execution_time < 0.01
+
+      default_message = "Expected immediate sync execution of '#{event}', but took #{execution_time}s (likely async)"
+
+      if defined?(::Minitest)
+        assert state_changed, "Event should trigger state change"
+        assert is_immediate, message || default_message
+      elsif defined?(::RSpec)
+        expect(state_changed).to be_truthy, "Event should trigger state change"
+        expect(is_immediate).to be_truthy, message || default_message
+      else
+        raise "Event should trigger state change" unless state_changed
+        raise default_message unless is_immediate
+      end
+    end
+
+    # === Async Mode Assertions ===
+
+    # Assert that a state machine is operating in asynchronous mode
+    #
+    # @param object [Object] The object with state machines
+    # @param machine_name [Symbol] The name of the state machine (defaults to :state)
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If the machine doesn't have async mode enabled
+    #
+    # @example
+    #   drone = AutonomousDrone.new
+    #   assert_sm_async_mode(drone)                         # Uses default :state machine
+    #   assert_sm_async_mode(drone, :teleporter_status)     # Uses :teleporter_status machine
+    def assert_sm_async_mode(object, machine_name = :state, message = nil)
+      machine = object.class.state_machines[machine_name]
+      raise ArgumentError, "No state machine '#{machine_name}' found" unless machine
+
+      async_enabled = machine.respond_to?(:async_mode_enabled?) && machine.async_mode_enabled?
+      default_message = "Expected state machine '#{machine_name}' to have async mode enabled, but it's in sync mode"
+
+      if defined?(::Minitest)
+        assert async_enabled, message || default_message
+      elsif defined?(::RSpec)
+        expect(async_enabled).to be_truthy, message || default_message
+      else
+        raise default_message unless async_enabled
+      end
+    end
+
+    # Assert that async methods are available on an async-enabled object
+    #
+    # @param object [Object] The object with state machines
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If async methods are not available
+    #
+    # @example
+    #   drone = AutonomousDrone.new  # Has async: true machines
+    #   assert_sm_async_methods(drone)
+    def assert_sm_async_methods(object, message = nil)
+      async_methods = %i[fire_event_async fire_events_async fire_event_async! async_fire_event]
+      available_async_methods = async_methods.select { |method| object.respond_to?(method) }
+
+      default_message = "Expected async methods to be available, but found none"
+
+      if defined?(::Minitest)
+        refute_empty available_async_methods, message || default_message
+      elsif defined?(::RSpec)
+        expect(available_async_methods).not_to be_empty, message || default_message
+      elsif available_async_methods.empty?
+        raise default_message
+      end
+    end
+
+    # Assert that an object has async-enabled state machines
+    #
+    # @param object [Object] The object with state machines
+    # @param machine_names [Array<Symbol>] Expected async machine names
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If expected machines don't have async mode
+    #
+    # @example
+    #   drone = AutonomousDrone.new
+    #   assert_sm_has_async(drone, [:status, :teleporter_status, :shields])
+    def assert_sm_has_async(object, machine_names = nil, message = nil)
+      if machine_names
+        # Check specific machines
+        non_async_machines = machine_names.reject do |name|
+          machine = object.class.state_machines[name]
+          machine&.respond_to?(:async_mode_enabled?) && machine.async_mode_enabled?
+        end
+
+        default_message = "Expected machines #{machine_names.inspect} to have async enabled, but these don't: #{non_async_machines.inspect}"
+
+        if defined?(::Minitest)
+          assert_empty non_async_machines, message || default_message
+        elsif defined?(::RSpec)
+          expect(non_async_machines).to be_empty, message || default_message
+        elsif non_async_machines.any?
+          raise default_message
+        end
+      else
+        # Check that at least one machine has async
+        async_machines = object.class.state_machines.select do |name, machine|
+          machine.respond_to?(:async_mode_enabled?) && machine.async_mode_enabled?
+        end
+
+        default_message = "Expected at least one state machine to have async enabled, but none found"
+
+        if defined?(::Minitest)
+          refute_empty async_machines, message || default_message
+        elsif defined?(::RSpec)
+          expect(async_machines).not_to be_empty, message || default_message
+        elsif async_machines.empty?
+          raise default_message
+        end
+      end
+    end
+
+    # Assert that individual async event methods are available
+    #
+    # @param object [Object] The object with state machines
+    # @param event [Symbol] The event name
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If async event methods are not available
+    #
+    # @example
+    #   drone = AutonomousDrone.new
+    #   assert_sm_async_event_methods(drone, :launch)  # Checks launch_async and launch_async!
+    def assert_sm_async_event_methods(object, event, message = nil)
+      async_method = "#{event}_async".to_sym
+      async_bang_method = "#{event}_async!".to_sym
+
+      has_async = object.respond_to?(async_method)
+      has_async_bang = object.respond_to?(async_bang_method)
+
+      default_message = "Expected async event methods #{async_method} and #{async_bang_method} to be available for event :#{event}"
+
+      if defined?(::Minitest)
+        assert has_async, "Missing #{async_method} method"
+        assert has_async_bang, "Missing #{async_bang_method} method"
+      elsif defined?(::RSpec)
+        expect(has_async).to be_truthy, "Missing #{async_method} method"
+        expect(has_async_bang).to be_truthy, "Missing #{async_bang_method} method"
+      else
+        raise "Missing #{async_method} method" unless has_async
+        raise "Missing #{async_bang_method} method" unless has_async_bang
+      end
+    end
+
+    # Assert that an object has thread-safe state methods when async is enabled
+    #
+    # @param object [Object] The object with state machines
+    # @param message [String, nil] Custom failure message
+    # @return [void]
+    # @raise [AssertionError] If thread-safe methods are not available
+    #
+    # @example
+    #   drone = AutonomousDrone.new
+    #   assert_sm_thread_safe_methods(drone)
+    def assert_sm_thread_safe_methods(object, message = nil)
+      thread_safe_methods = %i[state_machine_mutex read_state_safely write_state_safely]
+      missing_methods = thread_safe_methods.reject { |method| object.respond_to?(method) }
+
+      default_message = "Expected thread-safe methods to be available, but missing: #{missing_methods.inspect}"
+
+      if defined?(::Minitest)
+        assert_empty missing_methods, message || default_message
+      elsif defined?(::RSpec)
+        expect(missing_methods).to be_empty, message || default_message
+      elsif missing_methods.any?
+        raise default_message
+      end
+    end
+
     # RSpec-style aliases for event triggering (for consistency with RSpec expectations)
     alias expect_to_trigger_event assert_sm_triggers_event
     alias have_triggered_event assert_sm_triggers_event

data/lib/state_machines/transition.rb

@@ -160,12 +160,13 @@ module StateMachines
     #   transition.perform(Time.now, false)             # => Passes in additional arguments and only sets the state attribute
     #   transition.perform(Time.now, run_action: false) # => Passes in additional arguments and only sets the state attribute
     def perform(*args)
-      run_action = true
-
-      if [true, false].include?(args.last)
-        run_action = args.pop
-      elsif args.last.is_a?(Hash) && args.last.key?(:run_action)
-        run_action = args.last.delete(:run_action)
+      run_action = case args.last
+      in true | false
+        args.pop
+      in { run_action: }
+        args.last.delete(:run_action)
+      else
+        true
       end
 
       self.args = args

data/lib/state_machines/transition_collection.rb

@@ -209,6 +209,11 @@ module StateMachines
           transition.machine.write(object, :event, nil)
           transition.machine.write(object, :event_transition, nil)
         end
+        
+        # Clear stored transitions hash for new cycle (issue #91)
+        if !empty? && (obj = first.object)
+          obj.instance_variable_set(:@_state_machine_event_transitions, nil)
+        end
 
         # Rollback only if exceptions occur during before callbacks
         begin
@@ -222,7 +227,16 @@ module StateMachines
         # Persists transitions on the object if partial transition was successful.
         # This allows us to reference them later to complete the transition with
         # after callbacks.
-        each { |transition| transition.machine.write(object, :event_transition, transition) } if skip_after && success?
+        if skip_after && success?
+          each { |transition| transition.machine.write(object, :event_transition, transition) }
+          
+          # Store transitions in a hash by machine name to avoid overwriting (issue #91)
+          if !empty?
+            transitions_by_machine = object.instance_variable_get(:@_state_machine_event_transitions) || {}
+            each { |transition| transitions_by_machine[transition.machine.name] = transition }
+            object.instance_variable_set(:@_state_machine_event_transitions, transitions_by_machine)
+          end
+        end
       else
         super
       end

data/lib/state_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StateMachines
-  VERSION = '0.31.0'
+  VERSION = '0.40.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: state_machines
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -62,6 +62,12 @@ files:
 - LICENSE.txt
 - README.md
 - lib/state_machines.rb
+- lib/state_machines/async_mode.rb
+- lib/state_machines/async_mode/async_event_extensions.rb
+- lib/state_machines/async_mode/async_events.rb
+- lib/state_machines/async_mode/async_machine.rb
+- lib/state_machines/async_mode/async_transition_collection.rb
+- lib/state_machines/async_mode/thread_safe_state.rb
 - lib/state_machines/branch.rb
 - lib/state_machines/callback.rb
 - lib/state_machines/core.rb
@@ -77,6 +83,7 @@ files:
 - lib/state_machines/integrations/base.rb
 - lib/state_machines/machine.rb
 - lib/state_machines/machine/action_hooks.rb
+- lib/state_machines/machine/async_extensions.rb
 - lib/state_machines/machine/callbacks.rb
 - lib/state_machines/machine/class_methods.rb
 - lib/state_machines/machine/configuration.rb