state_machines 0.5.0 → 0.50.0

data/lib/state_machines/event_collection.rb

@@ -1,12 +1,14 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Represents a collection of events in a state machine
   class EventCollection < NodeCollection
-    def initialize(machine) #:nodoc:
-      super(machine, :index => [:name, :qualified_name])
+    def initialize(machine) # :nodoc:
+      super(machine, index: %i[name qualified_name])
     end
 
     # Gets the list of events that can be fired on the given object.
-    # 
+    #
     # Valid requirement options:
     # * <tt>:from</tt> - One or more states being transitioned from.  If none
     #   are specified, then this will be the object's current state.
@@ -16,26 +18,26 @@ module StateMachines
     #   are specified, then this will match any event.
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :park do
     #         transition :idling => :parked
     #       end
-    #       
+    #
     #       event :ignite do
     #         transition :parked => :idling
     #       end
     #     end
     #   end
-    #   
+    #
     #   events = Vehicle.state_machine(:state).events
-    #   
+    #
     #   vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">
     #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:ignite transitions=[:parked => :idling]>]
-    #   
+    #
     #   vehicle.state = 'idling'
     #   events.valid_for(vehicle)           # => [#<StateMachines::Event name=:park transitions=[:idling => :parked]>]
     def valid_for(object, requirements = {})
@@ -43,7 +45,7 @@ module StateMachines
     end
 
     # Gets the list of transitions that can be run on the given object.
-    # 
+    #
     # Valid requirement options:
     # * <tt>:from</tt> - One or more states being transitioned from.  If none
     #   are specified, then this will be the object's current state.
@@ -53,29 +55,29 @@ module StateMachines
     #   are specified, then this will match any event.
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :park do
     #         transition :idling => :parked
     #       end
-    #       
+    #
     #       event :ignite do
     #         transition :parked => :idling
     #       end
     #     end
     #   end
-    #   
+    #
     #   events = Vehicle.state_machine.events
-    #   
+    #
     #   vehicle = Vehicle.new                             # => #<Vehicle:0xb7c464b0 @state="parked">
     #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
-    #   
+    #
     #   vehicle.state = 'idling'
     #   events.transitions_for(vehicle)                   # => [#<StateMachines::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
-    #   
+    #
     #   # Search for explicit transitions regardless of the current state
     #   events.transitions_for(vehicle, :from => :parked) # => [#<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     def transitions_for(object, requirements = {})
@@ -86,12 +88,12 @@ module StateMachines
     # given object's event attribute.  This also takes an additional parameter
     # for automatically invalidating the object if the event or transition are
     # invalid.  By default, this is turned off.
-    # 
+    #
     # *Note* that if a transition has already been generated for the event, then
     # that transition will be used.
-    # 
+    #
     # == Examples
-    # 
+    #
     #   class Vehicle < ActiveRecord::Base
     #     state_machine :initial => :parked do
     #       event :ignite do
@@ -99,40 +101,48 @@ module StateMachines
     #       end
     #     end
     #   end
-    #   
+    #
     #   vehicle = Vehicle.new                       # => #<Vehicle id: nil, state: "parked">
     #   events = Vehicle.state_machine.events
-    #   
+    #
     #   vehicle.state_event = nil
     #   events.attribute_transition_for(vehicle)    # => nil # Event isn't defined
-    #   
+    #
     #   vehicle.state_event = 'invalid'
     #   events.attribute_transition_for(vehicle)    # => false # Event is invalid
-    #   
+    #
     #   vehicle.state_event = 'ignite'
     #   events.attribute_transition_for(vehicle)    # => #<StateMachines::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
     def attribute_transition_for(object, invalidate = false)
       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
-    def match(requirements) #:nodoc:
+
+    def match(requirements) # :nodoc:
       requirements && requirements[:on] ? [fetch(requirements.delete(:on))] : self
     end
   end

data/lib/state_machines/extensions.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module StateMachines
   module ClassMethods
-    def self.extended(base) #:nodoc:
+    def self.extended(base) # :nodoc:
       base.class_eval do
         @state_machines = MachineCollection.new
       end
@@ -136,13 +138,13 @@ module StateMachines
     #   vehicle.fire_events!(:ignite, :disable_alarm) # => StateMachines::InvalidParallelTransition: Cannot run events in parallel: ignite, disable_alarm
     def fire_events!(*events)
       run_action = [true, false].include?(events.last) ? events.pop : true
-      fire_events(*(events + [run_action])) || fail(StateMachines::InvalidParallelTransition.new(self, events))
+      fire_events(*(events + [run_action])) || raise(StateMachines::InvalidParallelTransition.new(self, events))
     end
 
     protected
 
-    def initialize_state_machines(options = {}, &block) #:nodoc:
-      self.class.state_machines.initialize_states(self, options, &block)
+    def initialize_state_machines(options = {}, &) # :nodoc:
+      self.class.state_machines.initialize_states(self, options, &)
     end
   end
 end

data/lib/state_machines/helper_module.rb

@@ -1,12 +1,14 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Represents a type of module that defines instance / class methods for a
   # state machine
-  class HelperModule < Module #:nodoc:
+  class HelperModule < Module # :nodoc:
     def initialize(machine, kind)
       @machine = machine
       @kind = kind
     end
-    
+
     # Provides a human-readable description of the module
     def to_s
       owner_class = @machine.owner_class

data/lib/state_machines/integrations/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   module Integrations
     # Provides a set of base helpers for managing individual integrations
@@ -33,7 +35,7 @@ module StateMachines
         end
       end
 
-      def self.included(base) #:nodoc:
+      def self.included(base) # :nodoc:
         base.extend ClassMethods
       end
     end

data/lib/state_machines/integrations.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module StateMachines
   # Integrations allow state machines to take advantage of features within the
   # context of a particular library.  This is currently most useful with
@@ -9,10 +11,10 @@ module StateMachines
   # * Scopes
   # * Callbacks
   # * Validation errors
-  # 
+  #
   # This type of integration allows the user to work with state machines in a
   # fashion similar to other object models in their application.
-  # 
+  #
   # The integration interface is loosely defined by various unimplemented
   # methods in the StateMachines::Machine class.  See that class or the various
   # built-in integrations for more information about how to define additional
@@ -24,15 +26,15 @@ module StateMachines
       #  Register integration
       def register(name_or_module)
         case name_or_module.class.to_s
-          when 'Module'
-            add(name_or_module)
-          else
-            fail IntegrationError
+        when 'Module'
+          add(name_or_module)
+        else
+          raise IntegrationError
         end
         true
       end
 
-      def reset #:nodoc:#
+      def reset # :nodoc:#
         @integrations = []
       end
 
@@ -45,30 +47,27 @@ module StateMachines
       #   StateMachines::Integrations.register(StateMachines::Integrations::ActiveModel)
       #   StateMachines::Integrations.integrations
       #   # => [StateMachines::Integrations::ActiveModel]
-      def integrations
-        # Register all namespaced integrations
-        @integrations
-      end
+      attr_reader :integrations
 
-      alias_method :list, :integrations
+      alias list integrations
 
       # Attempts to find an integration that matches the given class.  This will
       # look through all of the built-in integrations under the StateMachines::Integrations
       # namespace and find one that successfully matches the class.
-      # 
+      #
       # == Examples
-      # 
+      #
       #   class Vehicle
       #   end
-      #   
+      #
       #   class ActiveModelVehicle
       #     include ActiveModel::Observing
       #     include ActiveModel::Validations
       #   end
-      #   
+      #
       #   class ActiveRecordVehicle < ActiveRecord::Base
       #   end
-      #   
+      #
       #   StateMachines::Integrations.match(Vehicle)             # => nil
       #   StateMachines::Integrations.match(ActiveModelVehicle)  # => StateMachines::Integrations::ActiveModel
       #   StateMachines::Integrations.match(ActiveRecordVehicle) # => StateMachines::Integrations::ActiveRecord
@@ -103,9 +102,9 @@ module StateMachines
       private
 
       def add(integration)
-        if integration.respond_to?(:integration_name)
-          @integrations.insert(0, integration) unless @integrations.include?(integration)
-        end
+        return unless integration.respond_to?(:integration_name)
+
+        @integrations.insert(0, integration) unless @integrations.include?(integration)
       end
     end
   end

data/lib/state_machines/machine/action_hooks.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module ActionHooks
+      protected
+
+      # Determines whether action helpers should be defined for this machine.
+      # This is only true if there is an action configured and no other machines
+      # have process this same configuration already.
+      def define_action_helpers?
+        action && owner_class.state_machines.none? { |_name, machine| machine.action == action && machine != self }
+      end
+
+      # Adds helper methods for automatically firing events when an action
+      # is invoked
+      def define_action_helpers
+        return unless action_hook
+
+        @action_hook_defined = true
+        define_action_hook
+      end
+
+      # Hooks directly into actions by defining the same method in an included
+      # module.  As a result, when the action gets invoked, any state events
+      # defined for the object will get run.  Method visibility is preserved.
+      def define_action_hook
+        action_hook = self.action_hook
+        action = self.action
+        private_action_hook = owner_class.private_method_defined?(action_hook)
+
+        # Only define helper if it hasn't
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
+            def #{action_hook}(*)
+              self.class.state_machines.transitions(self, #{action.inspect}).perform { super }
+            end
+
+            private #{action_hook.inspect} if #{private_action_hook}
+        END_EVAL
+      end
+
+      # The method to hook into for triggering transitions when invoked.  By
+      # default, this is the action configured for the machine.
+      #
+      # Since the default hook technique relies on module inheritance, the
+      # action must be defined in an ancestor of the owner classs in order for
+      # it to be the action hook.
+      def action_hook
+        action && owner_class_ancestor_has_method?(:instance, action) ? action : nil
+      end
+    end
+  end
+end

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/callbacks.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Callbacks
+      # Creates a callback that will be invoked *before* a transition is
+      # performed so long as the given requirements match the transition.
+      def before_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:before, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked *after* a transition is
+      # performed so long as the given requirements match the transition.
+      def after_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:after, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked *around* a transition so long
+      # as the given requirements match the transition.
+      def around_transition(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:around, parsed_options, &)
+      end
+
+      # Creates a callback that will be invoked after a transition has failed
+      # to be performed.
+      def after_failure(*args, **options, &)
+        # Extract legacy positional arguments and merge with keyword options
+        parsed_options = parse_callback_arguments(args, options)
+
+        # Only validate callback-specific options, not state transition requirements
+        callback_options = parsed_options.slice(:do, :if, :unless, :bind_to_object, :terminator)
+        StateMachines::OptionsValidator.assert_valid_keys!(callback_options, :do, :if, :unless, :bind_to_object, :terminator)
+
+        add_callback(:failure, parsed_options, &)
+      end
+    end
+  end
+end

data/lib/state_machines/machine/class_methods.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module ClassMethods
+      # Attempts to find or create a state machine for the given class.  For
+      # example,
+      #
+      #   StateMachines::Machine.find_or_create(Vehicle)
+      #   StateMachines::Machine.find_or_create(Vehicle, :initial => :parked)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status)
+      #   StateMachines::Machine.find_or_create(Vehicle, :status, :initial => :parked)
+      #
+      # If a machine of the given name already exists in one of the class's
+      # superclasses, then a copy of that machine will be created and stored
+      # in the new owner class (the original will remain unchanged).
+      def find_or_create(owner_class, *args, &)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        name = args.first || :state
+
+        # Find an existing machine
+        machine = (owner_class.respond_to?(:state_machines) &&
+                  ((args.first && owner_class.state_machines[name]) || (!args.first &&
+                  owner_class.state_machines.values.first))) || nil
+
+        if machine
+          # Only create a new copy if changes are being made to the machine in
+          # a subclass
+          if machine.owner_class != owner_class && (options.any? || block_given?)
+            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
+          machine.instance_eval(&) if block_given?
+        else
+          # No existing machine: create a new one
+          machine = new(owner_class, name, options, &)
+        end
+
+        machine
+      end
+
+      def draw(*)
+        raise NotImplementedError
+      end
+
+      # Default messages to use for validation errors in ORM integrations
+      # Thread-safe access via atomic operations on simple values
+      attr_accessor :ignore_method_conflicts
+
+      def default_messages
+        @default_messages ||= {
+          invalid: 'is invalid',
+          invalid_event: 'cannot transition when %s',
+          invalid_transition: 'cannot transition via "%1$s"'
+        }.freeze
+      end
+
+      def default_messages=(messages)
+        # Atomic replacement with frozen object
+        @default_messages = deep_freeze_hash(messages)
+      end
+
+      def replace_messages(message_hash)
+        # Atomic replacement: read current messages, merge with new ones, replace atomically
+        current_messages = @default_messages || {}
+        merged_messages = current_messages.merge(message_hash)
+        @default_messages = deep_freeze_hash(merged_messages)
+      end
+
+      attr_writer :renderer
+
+      def renderer
+        return @renderer if @renderer
+
+        STDIORenderer
+      end
+
+      private
+
+      # Deep freezes a hash and all its string values for thread safety
+      def deep_freeze_hash(hash)
+        hash.each_with_object({}) do |(key, value), frozen_hash|
+          frozen_key = key.respond_to?(:freeze) ? key.freeze : key
+          frozen_value = value.respond_to?(:freeze) ? value.freeze : value
+          frozen_hash[frozen_key] = frozen_value
+        end.freeze
+      end
+    end
+  end
+end