state_gate 1.2.3

data/lib/state_gate/builder/transition_methods.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Builder
+    ##
+    # = Description
+    #
+    # Multiple private methods allowing StateGate::Builder to generate
+    # transition methods.
+    #
+    # * query the class for all allowed transitions:
+    #     Klass.status_transitions  # =>  { pending:   [:active],
+    #                               #       active:    [:suspended, :archived],
+    #                               #       suspended: [:active, :archived],
+    #                               #       archived:  [] }
+    #
+    # * query the class for the allowed transitions for the given state:
+    #     Klass.status_transitions_for(:pending)  # =>  [:active]
+    #     Klass.status_transitions_for(:active)   # =>  [:suspended, :archived]
+    #
+    # * list the allowed transitions from the current state:
+    #     .status_transitions  # =>  [:suspended, :archived]
+    #
+    # * query if a given transition is allowed from the current state:
+    #     .status_transitions_to?(:active)  # =>  true
+    #
+    module TransitionMethods
+
+      #  Private
+      # ======================================================================
+      private
+
+
+
+      # Add instance methods to the klass that query the allowed transitions
+      #
+      def generate_transition_methods
+        _add__klass__attr_transitions
+        _add__klass__attr_transitions_for
+
+        _add__instance__attr_transitions
+        _add__instance__attr_transitions_to
+
+        return unless @alias
+
+        _add__klass__attr_transitions(@alias)
+        _add__klass__attr_transitions_for(@alias)
+
+        _add__instance__attr_transitions(@alias)
+        _add__instance__attr_transitions_to(@alias)
+      end
+
+
+
+      # ======================================================================
+      #  Class methods
+      # ======================================================================
+
+      # Adds a Class method to return a Hash of the allowed transitions for the attribte
+      #   eg:
+      #       Klass.status_transitions  # =>  { pending:   [:active],
+      #                                         active:    [:suspended, :archived],
+      #                                         suspended: [:active, :archived],
+      #                                         archived:  [] }
+      #
+      def _add__klass__attr_transitions(method_name = @attribute)
+        method_name = "#{method_name}_transitions"
+
+        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}
+            stateables[:#{@attribute}].transitions
+          end
+        ))
+      end
+
+
+
+      # Adds a Class method to return an Array of the allowed attribute transitions for
+      # the provided state.
+      #   eg:
+      #       Klass.status_transitions_for(:pending) # =>  [:active]
+      #       Klass.status_transitions_for(:active)  # =>  [:suspended, :archived]
+      #       Klass.status_transitions_for(:dummy)   # =>  ArgumentError
+      #
+      def _add__klass__attr_transitions_for(method_name = @attribute)
+        method_name = "#{method_name}_transitions_for"
+
+        add__klass__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}(state)
+            stateables[:#{@attribute}].transitions_for_state(state)
+          end
+        ))
+      end
+
+
+
+      # ======================================================================
+      #  Instance methods
+      # ======================================================================
+
+
+      # Adds an instance method to return an Array of the allowed transitions from
+      # the current attribute state.
+      #   eg:
+      #       .status_transitions  # =>  [:active]
+      #       .status_transitions  # =>  [:suspended, :archived]
+      #       .status_transitions  # =>  []
+      #
+      def _add__instance__attr_transitions(method_name = @attribute)
+        method_name = "#{method_name}_transitions"
+
+        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}
+            stateables[:#{@attribute}].transitions_for_state(self[:#{@attribute}])
+          end
+        ))
+      end
+
+
+
+
+      # Adds an instance method to return TRUE if the current attribute state can
+      # transition to the queries status.
+      #   eg:
+      #       .status_transitions_to?(:active)    # =>  true
+      #       .status_transitions_to?(:archived)  # =>  false
+      #
+      def _add__instance__attr_transitions_to(method_name = @attribute)
+        method_name = "#{method_name}_transitions_to?"
+
+        add__instance__helper_method(method_name, __FILE__, __LINE__ - 2, %(
+          def #{method_name}(query_state)
+            test_state = StateGate.symbolize(query_state)
+            stateables[:#{@attribute}].transitions_for_state(self[:#{@attribute}])
+                                      .include?(test_state)
+          end
+        ))
+      end
+
+    end # TransitionMethods
+  end # Builder
+end # StateGate

data/lib/state_gate/builder/transition_validation_methods.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module StateGate
+  class Builder
+    ##
+    # = Description
+    #
+    # Multiple private methods allowing StateGate::Builder to generate
+    # attribute setter methods for transition validation.
+    #
+    # * initializing the attribute with +Class.new+ :
+    #     Klass.new(status: :active)  # => ArgumentError
+    #
+    # * initializing the attribute with +Class.create+ :
+    #     Klass.create(status: :active)  # => ArgumentError
+    #
+    # * initializing the attribute with <tt>Class.create!</tt> :
+    #     Klass.create!(status: :active)  # => ArgumentError
+    #
+    # * setting the attribute with +attr=+ :
+    #     .status = :active    # => :active
+    #     .status = :archived  # => ArgumentError
+    #
+    # * setting the attribute with <tt>[:attr]=</tt> :
+    #     [:status] = :active    # => :active
+    #     [:status] = :archived  # => ArgumentError
+    #
+    # * setting the attribute with <tt>attributes=</tt> :
+    #     .attrubutes = {status: :active}    # => :active
+    #     .attributes = {status: :archived } # => ArgumentError
+    #
+    # * setting the attribute with <tt>assign_attributes</tt> :
+    #     .assign_attrubutes(status: :active)    # => :active
+    #     .assign_attributes(status: :archived)  # => ArgumentError
+    #
+    # * updating the attribute with <tt>Class.update</tt> :
+    #     Klass.update(instance.id, status: :active)    # => :active
+    #     Klass.update(instance.id, status: :archived)  # => ArgumentError
+    #
+    # * updating the attribute with <tt>.update</tt> :
+    #     .update(status: :active)    # => :active
+    #     .update(status: :archived)  # => ArgumentError
+    #
+    # * updating the attribute with <tt>.update_column</tt> :
+    #     .update_column(:status, :active)    # => :active
+    #     .update_column(:status, :archived)  # => ArgumentError
+    #
+    # * updating the attribute with <tt>.update_columns</tt> :
+    #     .update_columns(status: :active)    # => :active
+    #     .update_columns(status: :archived)  # => ArgumentError
+    #
+    # * updating the attribute with <tt>.write_attribute</tt> :
+    #     .write_attribute(:status, :active)    # => :active
+    #     .write_attribute(:status, :archived)  # => ArgumentError
+    #
+    #
+    # === | Forcing a change
+    #
+    # To force a status change that would otherwise be prohibited, preceed the
+    # new state with +force_+ :
+    #   .status = :archived         # => ArgumentError
+    #   .status = :force_archived   # => :archived
+    #
+    module TransitionValidationMethods
+
+      #  Private
+      # ======================================================================
+      private
+
+
+
+      # Add prepended instance methods to the klass that catch all methods for
+      # updating the attribute and validated the new value is an allowed transition
+      #
+      # Note:
+      #       These methods are only added if the engine has an
+      #       include_transition_validations? status on initialisation
+      #
+      # Note:
+      #       The three methods "<atrr>=(val)", "write_attribute(<attr>, val)" and
+      #       "update_columns(<attr>: val)" cover all the possibilities of setting the
+      #       attribute through ActiveRecord.
+      #
+      def generate_transition_validation_methods
+        return if @engine.transitionless?
+
+        _prepend__attribute_equals
+        _prepend__write_attribute
+        _prepend__update_columns
+        _prepend__initialize
+      end
+
+
+
+      # ======================================================================
+      #  Prepend Module
+      # ======================================================================
+
+      # Dynamically generated module to hold the validation setter methods
+      # and is pre-pended to the class.
+      #
+      # A new module is create if it doesn't already exist.
+      #
+      # Note:
+      #       the module is named "StateGate::<klass>TranstionValidationMethods"
+      #
+      def _transition_validation_module # rubocop:disable Metrics/MethodLength
+        @_transition_validation_module ||= begin
+          mod_name = 'StateGate_ValidationMethods'
+
+          if @klass.const_defined?(mod_name)
+            "#{@klass}::#{mod_name}".constantize
+          else
+            @klass.const_set(mod_name, Module.new)
+            mod = "#{@klass}::#{mod_name}".constantize
+            @klass.prepend mod
+            mod
+          end
+        end
+      end
+
+
+
+      # ======================================================================
+      #  Instance methods
+      # ======================================================================
+
+      # Adds a method to overwrite the attribute :<attr>=(val) setter, raising an error
+      # if the supplied value is not a valid transition
+      #   eg:
+      #       .status = :archived  # => ArgumentError
+      #       .status - :active    # => :active
+      #
+      # ==== actions
+      #
+      # + assert it's a valid transition
+      # + call super
+      #
+      def _prepend__attribute_equals
+        attr_name = @attribute
+
+        _transition_validation_module.module_eval(%(
+          def #{attr_name}=(new_val)
+            stateables[StateGate.symbolize(:#{attr_name})] \
+                &.assert_valid_transition!(self[:#{attr_name}], new_val)
+            super(new_val)
+          end
+        ), __FILE__, __LINE__ - 6)
+      end
+
+
+
+      # Adds a method to overwrite the instance :write_attribute(attr, val) setter,
+      # raising an error if the supplied value is not a valid transition
+      #   eg:
+      #       .write_attribute(:status, :archived)  # => ArgumentError
+      #       .write_attribute(:status, :active)    # => :active
+      #
+      # ==== actions
+      #
+      # + loop through each attribute
+      # + get the base attribute name from any alias used
+      # + assert it's a valid transition
+      # + call super
+      #
+      def _prepend__write_attribute
+        return if _transition_validation_module.method_defined?(:write_attribute)
+
+        _transition_validation_module.module_eval(%(
+          def write_attribute(attrribute_name, new_val = nil)
+            name = attrribute_name.to_s.downcase
+            name = self.class.attribute_aliases[name] || name
+
+            stateables[StateGate.symbolize(name)] \
+                &.assert_valid_transition!(self[name], new_val)
+            super(attrribute_name, new_val)
+          end
+        ), __FILE__, __LINE__ - 9)
+      end
+
+
+
+      # Adds a method to overwrite the instance :update_columns(attr: val) setter,
+      # raising an error if the supplied value is not a valid transition
+      #   eg:
+      #       .update_columns(status: :archived)  # => ArgumentError
+      #       .update_columns(status: :active)    # => :active
+      #
+      # ==== actions
+      #
+      # + loop through each attribute
+      # + get the base attribute name from any alias used
+      # + assert it's a valid transition
+      # + call super
+      #
+      def _prepend__update_columns # rubocop:disable Metrics/MethodLength
+        return if _transition_validation_module.method_defined?(:update_columns)
+
+        _transition_validation_module.module_eval(%(
+          def update_columns(args)
+            super(args) and return if (new_record? || destroyed?)
+
+            args.each do |key, value|
+              name = key.to_s.downcase
+              name = self.class.attribute_aliases[name] || name
+
+              stateables[StateGate.symbolize(name)] \
+                  &.assert_valid_transition!(self[name], value)
+            end
+
+            super
+          end
+        ), __FILE__, __LINE__ - 14)
+      end
+
+
+
+      # Prepends an :itialize method to ensure the attribute is not set on initializing
+      # a new instance unless :forced.
+      #
+      #   Klass.new(status: :archived)  # => ArgumentError
+      #
+      def _prepend__initialize # rubocop:disable Metrics/MethodLength
+        return if _transition_validation_module.method_defined?(:initialize)
+
+        _transition_validation_module.module_eval(%(
+          def initialize(attributes = nil, &block)
+            attributes&.each do |attr_name, value|
+              key = self.class.attribute_aliases[attr_name.to_s] || attr_name
+              if self.stateables.keys.include?(key.to_sym)
+                unless value.to_s.start_with?('force_')
+                  msg = ":\#{attr_name} may not be included in the parameters for a new" \
+                  " \#{self.class.name}.  Create the new instance first, then transition" \
+                  " :\#{attr_name} as required."
+                  fail ArgumentError, msg
+                end
+              end
+            end
+
+            super
+          end
+        ), __FILE__, __LINE__ - 13)
+      end
+
+    end # LockingMethods
+  end # Builder
+end # StateGate

data/lib/state_gate/builder.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require_relative  'engine'
+require_relative  'type'
+Dir[File.join(__dir__, 'builder', '*.rb')].sort.each { |file| require file }
+
+module StateGate
+  ##
+  # = Description
+  #
+  # Responsible for generating the state gate engine, along
+  # with the Class and Instance helper methods for the submitted Klass. Everything is
+  # generated from +#initialize+ when a new instance is created.
+  #
+  # Both Class and Instance methods are generated for:
+  #
+  # * state interaction
+  # * state sequences
+  # * state scopes
+  # * transition interaction
+  # * transition validation
+  #
+  class Builder
+
+    include StateMethods
+    include ScopeMethods
+    include TransitionMethods
+    include ConflictDetectionMethods
+    include TransitionValidationMethods
+    include DynamicModuleCreationMethods
+
+
+
+    #  Private
+    # ======================================================================
+    private
+
+    # Initialize the Builder, creating the state gate and generating all the
+    # Class and Instace helper methods on the sumbitted klass.
+    #
+    # [:klass]
+    #   The class containing the attribute to be cast as a state gate
+    #   (Class | required)
+    #
+    # [:attribute_name]
+    #   The name of the klass attribute to use for the state gate
+    #   (Symbol | required)
+    #
+    # [:config]
+    #   The configuration block for the state gate.
+    #   (Block | required)
+    #
+    #  StateGate::Builder.new(Klass, :attribute_name) do
+    #       ... configuration ...
+    #  end
+    #
+    def initialize(klass = nil, attribute_name = nil, &config)
+      @klass     = klass
+      @attribute = attribute_name
+      @alias     = nil
+
+      # assert the input is valid
+      _assert_klass_is_valid_for_state_gate
+      _parse_atttribute_name_for_alias
+      _assert_no_existing_state_gate_for_attribute
+      _assert_attribute_name_is_a_database_string_column
+
+      # build the engine and cast the attribute
+      _build_state_gate_engine(&config)
+      _cast_attribute_as_state_gate
+
+      # generate the helper methods
+      generate_helper_methods
+    end
+
+
+
+    # Generate the helper methods
+    #
+    def generate_helper_methods
+      # add the helper methods
+      generate_scope_methods
+      generate_state_methods
+      generate_transition_methods
+      generate_transition_validation_methods
+
+      # warn if any state gate attribute methods are redefined
+      _generate_method_redefine_detection
+    end
+
+
+
+    # Validate the klass to ensure it is a 'Class' and derived from ActiveRecord,
+    # raising an error if not.
+    #
+    def _assert_klass_is_valid_for_state_gate
+      err(:non_class_err, klass: true) unless @klass.is_a?(Class)
+      err(:non_ar_err, klass: true) unless @klass.ancestors.include?(::ActiveRecord::Base)
+    end
+
+
+
+    # Parse the attribute name to ensure it is a valid input value and
+    # detect if it's an attribute_alias.
+    #
+    # = meta
+    #
+    # * ensure it exists
+    # * ensure it's a Symbol, to avoid string whitespace issues
+    # * check is it's a registere attribute
+    #   * update @attribute & @alias
+    #
+    def _parse_atttribute_name_for_alias
+      if @attribute.nil?
+        err :missing_attribute_err, klass: true
+
+      elsif !@attribute.is_a?(Symbol)
+        err :attribute_type_err
+
+      elsif @klass.attribute_aliases[@attribute.to_s]
+        @alias     = @attribute
+        @attribute = @klass.attribute_aliases[@attribute.to_s].to_sym
+      end
+    end
+
+
+
+    # Validate we don't already have a state gate defined for the attribute,
+    # raising an error if not.
+    #
+    def _assert_no_existing_state_gate_for_attribute
+      return unless @klass.methods(false).include?(:stateables)
+      return unless @klass.stateables.keys.include?(@attribute)
+
+      err :existing_state_gate_err, kattr: true
+    end # parse_attribute_name
+
+
+
+    # Validate the attribute is a database String attribute,
+    # raising an error if not.
+    #
+    # = meta
+    #
+    # * ensure it's mapped to a database column
+    # * ensure it's a :string databse type
+    #
+    def _assert_attribute_name_is_a_database_string_column
+      if @klass.column_names.exclude?(@attribute.to_s)
+        err :non_db_attr_err, kattr: true
+
+      elsif @klass.columns_hash[@attribute.to_s].type != :string
+        err :non_string_column_err, kattr:     true,
+                                    attr_type: @klass.columns_hash[@attribute.to_s].type
+      end
+    end # parse_attribute_name
+
+
+
+    # Builds a StateGate::Engine for the given attribute and add it to
+    # the :stateables repository.
+    #
+    # config - the user generated configuration for the engine, including states,
+    #           transitions and optional settings
+    #
+    def _build_state_gate_engine(&config)
+      _initialize_state_gate_repository
+      @engine = StateGate::Engine.new(@klass.name, @attribute, &config)
+      @klass.stateables[@attribute] = @engine # rubocop:disable Layout/ExtraSpacing
+    end
+
+
+
+    # Adds a :stateables class_attribute if it doesn't already exist and
+    # initializes it to an empty Hash.
+    #
+    # :stateables contains is a repository for the state gate engines
+    # created when generating state gates. The state gate attribute name is used
+    # as the key.
+    #
+    # Example
+    #     Klass.stateables # => {
+    #                                         status:   <StateGate::Engine>,
+    #                                         account:  <StateGate::Engine>
+    #                                       }
+    #
+    # Note
+    #
+    # The default empty Hash is set after the attribute is created to accommodate
+    # ActiveRecord 5.0, even though ActiveRecord 6.0 allows it to be set within
+    # the .class_attribute method.
+    #
+    def _initialize_state_gate_repository
+      return if @klass.methods(false).include?(:stateables)
+
+      @klass.class_attribute(:stateables, instance_writer: false)
+      @klass.stateables = {}
+    end
+
+
+
+    # Builds a StateGate::Type with the custom states for the attribute,
+    # then casts the attribute.
+    #
+    # This ensures that regardless of the setter method used to set a new state, even
+    # if transition validations are disabled, an invalid state should never reach the
+    # database.
+    #
+    # meta
+    #
+    # * retrieve the root attribute name if the supplied attribute is an alias.
+    # * create a StateGate::Type with attributes states.
+    # * overwrite the attribute, casting the type as the new StateGate::Type
+    #
+    def _cast_attribute_as_state_gate
+      states    = @engine.states
+      attr_type = StateGate::Type.new(@klass.name, @attribute, states)
+      @klass.attribute(@attribute, attr_type, default: @engine.default_state)
+    end
+
+
+
+    # Raise an ArgumentError for the given error, using I18n for the message.
+    #
+    # err - Symbol key for the I18n message
+    #
+    # args - Hash of attributes to pass to the message string.
+    #
+    #        [:klass] When true, args[:klass] will be updated with the 'KlassName'.
+    #        [:kattr] When true, args[:kattr] will be updated with 'KlassName#attribute'.
+    #
+    # Example
+    #
+    #     err(:invalid_attribute_type_err, kattr: true)
+    #
+    def err(err, **args)
+      args[:klass] = @klass                    if args.dig(:klass) == true
+      args[:kattr] = "#{@klass}##{@attribute}" if args.dig(:kattr) == true
+
+      fail ArgumentError, I18n.t("state_gate.builder.#{err}", **args)
+    end
+
+  end # class Builder
+end # module StateGate