state_machines 0.20.0 → 0.30.0

data/lib/state_machines/event.rb

@@ -7,7 +7,6 @@ module StateMachines
   # another.  The state that an attribute is transitioned to depends on the
   # branches configured for the event.
   class Event
-
     include MatcherHelpers
 
     # The state machine for which this event is defined
@@ -34,7 +33,7 @@ module StateMachines
     #
     # Configuration options:
     # * <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:
+    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)
         # Old style: initialize(machine, name, {human_name: 'Custom Name'})
@@ -43,6 +42,7 @@ module StateMachines
       else
         # 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?
       end
 
@@ -63,7 +63,7 @@ module StateMachines
 
     # Creates a copy of this event in addition to the list of associated
     # branches to prevent conflicts across events within a class hierarchy.
-    def initialize_copy(orig) #:nodoc:
+    def initialize_copy(orig) # :nodoc:
       super
       @branches = @branches.dup
       @known_states = @known_states.dup
@@ -77,8 +77,8 @@ module StateMachines
 
     # Evaluates the given block within the context of this event.  This simply
     # provides a DSL-like syntax for defining transitions.
-    def context(&block)
-      instance_eval(&block)
+    def context(&)
+      instance_eval(&)
     end
 
     # Creates a new transition that determines what to change the current state
@@ -102,9 +102,7 @@ module StateMachines
 
       # Only a certain subset of explicit options are allowed for transition
       # requirements
-      if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
-        StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless)
-      end
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless) if (options.keys - %i[from to on except_from except_to except_on if unless]).empty?
 
       branches << branch = Branch.new(options.merge(on: name))
       @known_states |= branch.known_states
@@ -138,19 +136,19 @@ module StateMachines
       requirements[:from] = machine.states.match!(object).name unless (custom_from_state = requirements.include?(:from))
 
       branches.each do |branch|
-        if (match = branch.match(object, requirements))
-          # Branch allows for the transition to occur
-          from = requirements[:from]
-          to = if match[:to].is_a?(LoopbackMatcher)
-                 from
-               else
-                 values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
-
-                 match[:to].filter(values).first
-               end
-
-          return Transition.new(object, machine, name, from, to, !custom_from_state)
-        end
+        next unless (match = branch.match(object, requirements))
+
+        # Branch allows for the transition to occur
+        from = requirements[:from]
+        to = if match[:to].is_a?(LoopbackMatcher)
+               from
+             else
+               values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.map { |state| state.name }
+
+               match[:to].filter(values).first
+             end
+
+        return Transition.new(object, machine, name, from, to, !custom_from_state)
       end
 
       # No transition matched
@@ -163,13 +161,13 @@ module StateMachines
     #
     # Any additional arguments are passed to the StateMachines::Transition#perform
     # instance method.
-    def fire(object, *args)
+    def fire(object, *)
       machine.reset(object)
 
       if (transition = transition_for(object))
-        transition.perform(*args)
+        transition.perform(*)
       else
-        on_failure(object, *args)
+        on_failure(object, *)
         false
       end
     end
@@ -194,7 +192,6 @@ module StateMachines
       @known_states = []
     end
 
-
     def draw(graph, options = {}, io = $stdout)
       machine.renderer.draw_event(self, graph, options, io)
     end
@@ -216,7 +213,7 @@ module StateMachines
       "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
     end
 
-  protected
+    protected
 
     # Add the various instance methods that can transition the object using
     # the current event

data/lib/state_machines/event_collection.rb

@@ -3,8 +3,8 @@
 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.
@@ -130,12 +130,11 @@ module StateMachines
                                                      false
                                                    end
                                                  end
-
     end
 
-  private
+    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

@@ -2,7 +2,7 @@
 
 module StateMachines
   module ClassMethods
-    def self.extended(base) #:nodoc:
+    def self.extended(base) # :nodoc:
       base.class_eval do
         @state_machines = MachineCollection.new
       end
@@ -138,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
+    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

@@ -3,7 +3,7 @@
 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

data/lib/state_machines/integrations/base.rb

@@ -35,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

@@ -26,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
 
@@ -47,12 +47,9 @@ 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
@@ -102,12 +99,12 @@ module StateMachines
         integrations.detect { |integration| integration.integration_name == name } || raise(IntegrationNotFound.new(name))
       end
 
-    private
+      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/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

@@ -14,14 +14,14 @@ module StateMachines
       # 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, &block)
+      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
+        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
@@ -33,10 +33,10 @@ module StateMachines
           end
 
           # Evaluate DSL
-          machine.instance_eval(&block) if block_given?
+          machine.instance_eval(&) if block_given?
         else
           # No existing machine: create a new one
-          machine = new(owner_class, name, options, &block)
+          machine = new(owner_class, name, options, &)
         end
 
         machine
@@ -47,6 +47,7 @@ module StateMachines
       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
@@ -54,17 +55,19 @@ module StateMachines
           invalid: 'is invalid',
           invalid_event: 'cannot transition when %s',
           invalid_transition: 'cannot transition via "%1$s"'
-        }
+        }.freeze
       end
 
       def default_messages=(messages)
-        @default_messages = messages
+        # Atomic replacement with frozen object
+        @default_messages = deep_freeze_hash(messages)
       end
 
       def replace_messages(message_hash)
-        message_hash.each do |key, value|
-          default_messages[key] = value
-        end
+        # 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
@@ -74,6 +77,17 @@ module StateMachines
 
         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

data/lib/state_machines/machine/configuration.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module Configuration
+      # 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)
+
+        # Find an integration that matches this machine's owner class
+        @integration = if options.include?(:integration)
+                         options[:integration] && StateMachines::Integrations.find_by_name(options[:integration])
+                       else
+                         StateMachines::Integrations.match(owner_class)
+                       end
+
+        if @integration
+          extend @integration
+          options = (@integration.defaults || {}).merge(options)
+        end
+
+        # Add machine-wide defaults
+        options = { use_transactions: true, initialize: true }.merge(options)
+
+        # Set machine configuration
+        @name = args.first || :state
+        @attribute = options[:attribute] || @name
+        @events = EventCollection.new(self)
+        @states = StateCollection.new(self)
+        @callbacks = { before: [], after: [], failure: [] }
+        @namespace = options[:namespace]
+        @messages = options[:messages] || {}
+        @action = options[:action]
+        @use_transactions = options[:use_transactions]
+        @initialize_state = options[:initialize]
+        @action_hook_defined = false
+        self.owner_class = owner_class
+
+        # Merge with sibling machine configurations
+        add_sibling_machine_configs
+
+        # Define class integration
+        define_helpers
+        define_scopes(options[:plural])
+        after_initialize
+
+        # Evaluate DSL
+        instance_eval(&) if block_given?
+        self.initial_state = options[:initial] unless sibling_machines.any?
+      end
+
+      # Creates a copy of this machine in addition to copies of each associated
+      # event/states/callback, so that the modifications to those collections do
+      # not affect the original machine.
+      def initialize_copy(orig) # :nodoc:
+        super
+
+        @events = @events.dup
+        @events.machine = self
+        @states = @states.dup
+        @states.machine = self
+        @callbacks = { before: @callbacks[:before].dup, after: @callbacks[:after].dup, failure: @callbacks[:failure].dup }
+      end
+
+      # Sets the class which is the owner of this state machine.  Any methods
+      # generated by states, events, or other parts of the machine will be defined
+      # on the given owner class.
+      def owner_class=(klass)
+        @owner_class = klass
+
+        # Create modules for extending the class with state/event-specific methods
+        @helper_modules = helper_modules = { instance: HelperModule.new(self, :instance), class: HelperModule.new(self, :class) }
+        owner_class.class_eval do
+          extend helper_modules[:class]
+          include helper_modules[:instance]
+        end
+
+        # Add class-/instance-level methods to the owner class for state initialization
+        unless owner_class < StateMachines::InstanceMethods
+          owner_class.class_eval do
+            extend StateMachines::ClassMethods
+            include StateMachines::InstanceMethods
+          end
+
+          define_state_initializer if @initialize_state
+        end
+
+        # Record this machine as matched to the name in the current owner class.
+        # This will override any machines mapped to the same name in any superclasses.
+        owner_class.state_machines[name] = self
+      end
+
+      # Sets the initial state of the machine.  This can be either the static name
+      # of a state or a lambda block which determines the initial state at
+      # creation time.
+      def initial_state=(new_initial_state)
+        @initial_state = new_initial_state
+        add_states([@initial_state]) unless dynamic_initial_state?
+
+        # Update all states to reflect the new initial state
+        states.each { |state| state.initial = (state.name == @initial_state) }
+
+        # Output a warning if there are conflicting initial states for the machine's
+        # attribute
+        initial_state = states.detect(&:initial)
+        has_owner_default = !owner_class_attribute_default.nil?
+        has_conflicting_default = dynamic_initial_state? || !owner_class_attribute_default_matches?(initial_state)
+        return unless has_owner_default && has_conflicting_default
+
+        warn(
+          "Both #{owner_class.name} and its #{name.inspect} machine have defined " \
+          "a different default for \"#{attribute}\". Use only one or the other for " \
+          'defining defaults to avoid unexpected behaviors.'
+        )
+      end
+
+      # Gets the attribute name for the given machine scope.
+      def attribute(name = :state)
+        name == :state ? @attribute : :"#{self.name}_#{name}"
+      end
+    end
+  end
+end

data/lib/state_machines/machine/event_methods.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module StateMachines
+  class Machine
+    module EventMethods
+      # Defines one or more events for the machine and the transitions that can
+      # be performed when those events are run.
+      def event(*names, &)
+        options = names.last.is_a?(Hash) ? names.pop : {}
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
+
+        # Store the context so that it can be used for / matched against any event
+        # that gets added
+        @events.context(names, &) if block_given?
+
+        if names.first.is_a?(Matcher)
+          # Add any events referenced in the matcher.  When matchers are used,
+          # events are not allowed to be configured.
+          raise ArgumentError, "Cannot configure events when using matchers (using #{options.inspect})" if options.any?
+
+          events = add_events(names.first.values)
+        else
+          events = add_events(names)
+
+          # Update the configuration for the event(s)
+          events.each do |event|
+            event.human_name = options[:human_name] if options.include?(:human_name)
+
+            # Add any states that may have been referenced within the event
+            add_states(event.known_states)
+          end
+        end
+
+        events.length == 1 ? events.first : events
+      end
+
+      alias on event
+
+      # Creates a new transition that determines what to change the current state
+      # to when an event fires.
+      def transition(options)
+        raise ArgumentError, 'Must specify :on event' unless options[:on]
+
+        branches = []
+        options = options.dup
+        event(*Array(options.delete(:on))) { branches << transition(options) }
+
+        branches.length == 1 ? branches.first : branches
+      end
+
+      # Gets the list of all possible transition paths from the current state to
+      # the given target state.  If multiple target states are provided, then
+      # this will return all possible paths to those states.
+      def paths_for(object, requirements = {})
+        PathCollection.new(object, self, requirements)
+      end
+    end
+  end
+end