has_state_machine 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f9619070408aa690d1e8b70c31baf787c91d949c0e28665a42af8b17ff79955
-  data.tar.gz: '099784a11f816d49d75b18432a1497688838aac08a775d15fe5d29827eb7ac38'
+  metadata.gz: 94b18269b2a7ac5e0b6ca2aedf9591a78111e30089dfe8a000190bad02725d71
+  data.tar.gz: 93ce1793915219f7b00725c2faf977cdbd62f40d20fefa21b680b281378ed242
 SHA512:
-  metadata.gz: 749b711582fc925fd8efbfcb7dcdee7dfb3f9902e945d5cc26e1f7f3737ea77f646087a117ccf9e6675444a858acb2497ae52dba0a3c8b2777628ebae33297af
-  data.tar.gz: a8cbe864ada7ab74316c55c14704ea33fa18bae5050d3a728d2f5458cb16b561419643805af0824fd7bdcca10cf42e5023e708d84f88ed1e3478a9b24bad2d43
+  metadata.gz: 82344021e6dd63dde02dbfcb261b39b8773b51cff31ab37846441e655d420dfa9ba63128a893d9c7a11a83c15371320575871bd0e2f32f6c6061c84a8fe72984
+  data.tar.gz: a2cef6e05f4eb1c63fd2002478c0d2fc9a673cbc1b6be9ec2c13288eee5d0d12b7438514489fc6dc75e9fa257f7571f6f67b3694351be33fe041c5095b115dc3

data/README.md

@@ -202,6 +202,59 @@ post.status.transition_to(:published, skip_validations: true)
 
 ### Advanced Usage
 
+#### Multiple State Machines
+
+Call `has_state_machine` once per state column to give a model independent workflows:
+
+```ruby
+class Post < ApplicationRecord
+  has_state_machine states: %i[draft published archived]
+  has_state_machine states: %i[available removing removed],
+    state_attribute: :deletion_state,
+    workflow_namespace: "Workflow::PostDeletion",
+    prefix: :deletion
+end
+
+post.status.transition_to(:published)
+post.deletion_state.transition_to(:removing)
+
+Post.deletion_removing # Scope on deletion_state
+post.deletion_removing? # Predicate on deletion_state
+```
+
+Each machine needs its own state column and workflow namespace, with state classes
+inheriting from `HasStateMachine::State`. Each column defaults to its machine's
+first state. Transitions update their own column, and model validations run the
+state validations of every machine unless disabled with
+`state_validations_on_object: false` or `skip_state_validations`.
+
+Use `prefix:` and/or `suffix:` to distinguish generated scopes and predicates:
+
+| Options for `deletion_state` | Scope | Predicate |
+| --- | --- | --- |
+| `prefix: true` | `deletion_state_removing` | `deletion_state_removing?` |
+| `prefix: :deletion` | `deletion_removing` | `deletion_removing?` |
+| `suffix: true` | `removing_deletion_state` | `removing_deletion_state?` |
+| `suffix: "deletion"` | `removing_deletion` | `removing_deletion?` |
+| `prefix: :deletion, suffix: :workflow` | `deletion_removing_workflow` | `deletion_removing_workflow?` |
+
+Both options accept `true` (use the state attribute), a string or symbol (use a
+custom name), or `false`/`nil` (omit the affix). `scopes: false` disables scopes
+while retaining predicates. Additional machines raise `ArgumentError` if their
+generated helpers collide with existing methods or their namespace matches
+another machine's. An omitted or blank namespace defaults to
+`Workflow::<ModelClass>`.
+
+The first machine remains the primary machine for `workflow_states`,
+`state_attribute`, `workflow_namespace`, and `state_validations_on_object?`.
+Subclasses inherit all machine definitions and may add their own.
+
+For 1.x compatibility, redeclaring the same state attribute replaces its
+configuration in place. This supports concern and subclass overrides of namespace
+or state-validation settings. It does **not** regenerate the original default,
+inclusion validation, scopes, or predicates, so keep the states and helper-naming
+options consistent across redeclarations.
+
 #### Transactional Transitions
 
 There may be a situation where you want to manually rollback a state change in one of the provided transition callbacks. To do this, add the `transactional: true` option to the `state_options` declaration. This results in the transition being wrapped in a transaction. You can then use the `rollback_transition` method in your callback when you want to trigger a rollback of the transaction. This will allow you to prevent the transition from persisting if something further down the line fails.

data/lib/has_state_machine/definition.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "has_state_machine/definition_builder"
 require "has_state_machine/state"
 require "has_state_machine/state_helpers"
 
@@ -8,60 +9,29 @@ module HasStateMachine
     extend ActiveSupport::Concern
 
     class_methods do
-      ##
-      # Configures the state machine for the ActiveRecord object and adds some
-      # useful helper methods such as scopes, boolean checks, etc.
+      # Declares one machine per state attribute. The first machine is primary
+      # for the class and instance readers. Unknown options warn and are ignored.
       #
-      # @param states [Array<Symbol>] the list of possible states in a state machine
-      #   @note the first state is used as the initial state
-      # @param options [Hash] a hash of additional options for the state machine
+      # @param states [Array<String, Symbol>] allowed states; the first is the default
+      # @param options [Hash]
+      # @option options [String, Symbol] :state_attribute (:status) state column
+      # @option options [String, Symbol] :attribute alias for :state_attribute
+      # @option options [String] :workflow_namespace ("Workflow::<Model>") state-class namespace; unique per model
+      # @option options [Boolean] :state_validations_on_object (true) run state validations on the model
+      # @option options [Boolean, String, Symbol] :prefix scope/predicate prefix; true uses the state attribute
+      # @option options [Boolean, String, Symbol] :suffix scope/predicate suffix; true uses the state attribute
+      # @option options [Boolean] :scopes (true) generate scopes
       #
       # @example
       #   class Post < ApplicationRecord
       #     has_state_machine states: %i(draft published archived)
+      #     has_state_machine states: %i(available removing),
+      #       state_attribute: :deletion_state,
+      #       workflow_namespace: "Workflow::PostDeletion",
+      #       prefix: :deletion
       #   end
       def has_state_machine(states: [], **options)
-        raise ArgumentError, "Please define at least one state to use has_state_machine." if states.empty?
-
-        define_helper_methods(
-          states: states.map(&:to_s),
-          options: options.with_indifferent_access
-        )
-
-        include HasStateMachine::StateHelpers
-      end
-
-      private
-
-      def define_helper_methods(states:, options:)
-        ##
-        # The list of possible states in the state machine.
-        define_singleton_method :workflow_states do
-          states
-        end
-
-        ##
-        # Defines the column name for the attribute holding the current status.
-        # Can be overwritten to use a different column name.
-        define_singleton_method :state_attribute do
-          options[:state_attribute]&.to_sym || :status
-        end
-
-        ##
-        # Defines the namespace of the models possible states.
-        # Can be overwritten to use a different namespace.
-        define_singleton_method :workflow_namespace do
-          options[:workflow_namespace] || "Workflow::#{self}"
-        end
-
-        ##
-        # Determines whether or not the state validations should be run
-        # as part of the object validations; they are by default.
-        define_singleton_method :state_validations_on_object? do
-          return true unless options.key?(:state_validations_on_object)
-
-          options[:state_validations_on_object]
-        end
+        HasStateMachine::DefinitionBuilder.new(self, states: states, **options).call
       end
     end
   end

data/lib/has_state_machine/definition_builder.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "has_state_machine/deprecation"
+require "has_state_machine/machine"
+require "has_state_machine/state_helpers"
+
+module HasStateMachine
+  class DefinitionBuilder
+    OPTION_KEYS = %i[
+      state_attribute attribute workflow_namespace state_validations_on_object prefix suffix scopes
+    ].freeze
+
+    def initialize(model, states:, **options)
+      @model = model
+      @states = states
+      @options = options.symbolize_keys
+    end
+
+    def call
+      raise ArgumentError, "Please define at least one state to use has_state_machine." if states.empty?
+
+      @machine = HasStateMachine::Machine.new(states: states, **normalize_options)
+      redeclared = register_machine
+
+      model.include HasStateMachine::StateHelpers
+
+      # Preserve 1.x concern/subclass overrides: replace configuration without
+      # regenerating methods, defaults, validations, or callbacks.
+      model.send(:define_state_machine_methods, machine) unless redeclared
+    end
+
+    private
+
+    attr_reader :model, :states, :options, :machine
+
+    # Assign a new registry so subclass declarations cannot mutate the parent's.
+    # @return [Boolean] whether an existing definition was replaced
+    def register_machine
+      unless model.respond_to?(:state_machine_definitions)
+        model.class_attribute :state_machine_definitions, instance_accessor: false, instance_predicate: false,
+          default: {}.freeze
+      end
+
+      existing = model.state_machine_definitions
+      replaced = existing.key?(machine.state_attribute)
+      others = existing.except(machine.state_attribute)
+
+      ensure_unique_namespace!(others)
+      detect_conflicts! if !replaced && others.any?
+
+      model.state_machine_definitions = existing.merge(machine.state_attribute => machine).freeze
+      replaced
+    end
+
+    def normalize_options
+      warn_about_unknown_options
+
+      if options[:state_attribute] && options[:attribute] &&
+          options[:state_attribute].to_sym != options[:attribute].to_sym
+        HasStateMachine::Deprecation.warn(
+          "has_state_machine on #{model} received both state_attribute: #{options[:state_attribute].inspect} " \
+          "and attribute: #{options[:attribute].inspect}; attribute: is ignored."
+        )
+      end
+
+      options[:state_attribute] = (options[:state_attribute] || options[:attribute])&.to_sym || :status
+      options.slice(*OPTION_KEYS).except(:attribute)
+    end
+
+    def warn_about_unknown_options
+      unknown = options.keys - OPTION_KEYS
+      return if unknown.empty?
+
+      HasStateMachine::Deprecation.warn(
+        "has_state_machine on #{model} received unknown option(s) #{unknown.map(&:inspect).join(", ")}, " \
+        "which are ignored. Known options: #{OPTION_KEYS.map(&:inspect).join(", ")}."
+      )
+    end
+
+    def ensure_unique_namespace!(existing)
+      namespace = machine.workflow_namespace_for(model).to_s
+      clash = existing.each_value.find { |other| other.workflow_namespace_for(model).to_s == namespace }
+      return unless clash
+
+      raise ArgumentError,
+        "The state machines on #{clash.state_attribute.inspect} and #{machine.state_attribute.inspect} " \
+        "of #{model} would both use the workflow namespace #{namespace.inspect}. " \
+        "Pass a distinct workflow_namespace: to has_state_machine."
+    end
+
+    # The first machine may override existing methods for 1.x compatibility;
+    # additional machines must not overwrite scopes or predicates.
+    def detect_conflicts!
+      active_record = defined?(ActiveRecord::Base) && model < ActiveRecord::Base
+
+      machine.states.each do |state|
+        predicate = machine.predicate_name(state)
+        if model.method_defined?(predicate) || model.private_method_defined?(predicate)
+          raise_conflict("instance", predicate)
+        end
+
+        next unless active_record && machine.scopes?
+
+        scope_name = machine.scope_name(state)
+        raise_conflict("class", scope_name) if model.respond_to?(scope_name, true)
+      end
+    end
+
+    def raise_conflict(type, method_name)
+      advice = (type == "class") ? "prefix:, suffix:, or scopes: false" : "prefix: or suffix:"
+      raise ArgumentError,
+        "has_state_machine #{machine.state_attribute.inspect} on #{model} conflicts with existing " \
+        "#{type} method #{method_name.to_s.inspect}. Pass #{advice}."
+    end
+  end
+end

data/lib/has_state_machine/machine.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module HasStateMachine
+  class Machine
+    attr_reader :states, :state_attribute, :state_validations_on_object
+
+    alias_method :state_validations_on_object?, :state_validations_on_object
+
+    def initialize(states:, state_attribute: :status, workflow_namespace: nil, state_validations_on_object: true,
+      prefix: nil, suffix: nil, scopes: true)
+      @states = states.map(&:to_s).freeze
+      @state_attribute = state_attribute.to_sym
+      @workflow_namespace = workflow_namespace
+      @state_validations_on_object = state_validations_on_object
+      @prefix = prefix
+      @suffix = suffix
+      @scopes = scopes != false
+      freeze
+    end
+
+    def initial_state
+      states.first
+    end
+
+    # Resolve defaults against the concrete class so STI subclasses get their own namespace.
+    def workflow_namespace_for(model_class)
+      @workflow_namespace.presence || "Workflow::#{model_class}"
+    end
+
+    def state_class_for(state, model_class)
+      return if state.blank?
+
+      "#{workflow_namespace_for(model_class)}::#{state.to_s.classify}".safe_constantize
+    end
+
+    def scopes?
+      @scopes
+    end
+
+    def scope_name(state)
+      [method_affix(@prefix), state, method_affix(@suffix)].compact.join("_").to_sym
+    end
+
+    def predicate_name(state)
+      :"#{scope_name(state)}?"
+    end
+
+    private
+
+    def method_affix(value)
+      return unless value
+      return state_attribute if value == true
+
+      value
+    end
+  end
+end

data/lib/has_state_machine/state.rb

@@ -8,30 +8,16 @@ module HasStateMachine
     extend ActiveModel::Callbacks
     include ActiveModel::Validations
 
-    attr_reader :object, :state
+    attr_reader :object
 
-    ##
-    # Defines the before_transition and after_transition callbacks
-    # for use on a HasStateMachine::State instance.
     define_model_callbacks :transition, only: %i[before after]
 
-    ##
-    # Defines the after_transition_commit callback, which runs once a
-    # successful transition is committed to the database.
     define_model_callbacks :transition_commit, only: %i[after]
 
-    ##
-    # possible_transitions - Retrieves the next available transitions for a given state.
-    # transactional? - Determines whether or not the transition should happen with a transactional block.
-    # state - The underscored name of the state
-    # transients - Specified list of optional transient attributes on this state
-    delegate :possible_transitions, :transactional?, :state, :transients, to: "self.class"
+    delegate :possible_transitions, :transactional?, :state, :transients, to: :class
 
-    ##
-    # Initializes the HasStateMachine::State instance.
-    #
     # @example
-    #   state = Workflow::Post::Draft.new(post) #=> "draft"
+    #   Workflow::Post::Draft.new(post) #=> "draft"
     def initialize(object, transient_values = {})
       @object = object
 
@@ -42,25 +28,48 @@ module HasStateMachine
       super(state)
     end
 
-    ##
-    # Determines if the given desired state exists in the predetermined
-    # list of allowed transitions.
-    # @param desired_state [String, Symbol] the state to check if the object can transition to
-    # @return [Boolean] whether or not the object can transition to the desired state
+    # Bound by the model getter; direct instances resolve by namespace,
+    # falling back to the primary machine.
+    #
+    # @return [HasStateMachine::Machine, nil]
+    def state_machine
+      return @state_machine if @state_machine
+
+      model_class = object.class
+      definitions = model_class.try(:state_machine_definitions)
+      return unless definitions
+
+      machines = definitions.each_value
+      namespace = self.class.name&.deconstantize
+
+      @state_machine = machines.find do |machine|
+        machine.workflow_namespace_for(model_class).to_s == namespace
+      end || machines.first
+    end
+
+    # @return [Symbol]
+    def state_attribute
+      state_machine&.state_attribute || object.state_attribute
+    end
+
+    # @api private
+    def bind_state_machine(machine)
+      @state_machine = machine
+      self
+    end
+
+    # Checks the allowed transition list without running validations.
+    # @param desired_state [String, Symbol]
     def can_transition?(desired_state)
       possible_transitions.include? desired_state.to_s
     end
 
-    ##
-    # Checks to see if the desired state is valid and then gives
-    # responsibility to the desired state's instance to make the
-    # transition.
-    #
-    # @param desired_state [String] the state to transition to
-    # @param options [Hash] a hash of additional options for
-    #   transitioning the object
+    # Validates and transitions to the target state, copying its errors to the model.
     #
-    # @return [Boolean] whether or not the transition took place
+    # @param desired_state [String, Symbol]
+    # @param options [Hash] target-state transients and transition options
+    # @option options [Boolean] :skip_validations (false) bypass transition checks and state validations
+    # @return [Boolean] whether the transition succeeded
     def transition_to(desired_state, **options)
       transitioned = false
       options = options.symbolize_keys
@@ -83,36 +92,29 @@ module HasStateMachine
       end
     end
 
-    ##
-    # Makes the actual transition from one state to the next and
-    # runs the before and after transition callbacks.
-    #
-    # @return [Boolean] whether or not the transition succeeded
+    # Persists the target state and runs transition callbacks.
+    # @return [Boolean] whether the transition succeeded
     def perform_transition! # rubocop:disable Naming/PredicateMethod -- public API
       transitioned = run_callbacks :transition do
-        object.update("#{object.state_attribute}": state)
+        update_state_attribute
       end
+
       return false unless transitioned
 
-      @previous_state = previous_state
       enqueue_transition_commit_callbacks
       true
     end
 
-    ##
-    # Same as {#perform_transition!}, but wrapped in a transaction so
-    # callbacks can roll the transition back.
-    #
-    # @return [Boolean] whether or not the transition succeeded
+    # Wraps the transition in a transaction that callbacks can roll back.
+    # @return [Boolean] whether the transition succeeded
     def perform_transactional_transition! # rubocop:disable Naming/PredicateMethod -- public API
       ActiveRecord::Base.transaction(requires_new: true, joinable: false) do
         run_callbacks :transition do
-          rollback_transition unless object.update("#{object.state_attribute}": state)
+          rollback_transition unless update_state_attribute
         end
       end
 
-      @previous_state = previous_state
-      return false unless object.reload.public_send(object.state_attribute) == state
+      return false unless object.reload.public_send(state_attribute) == state
 
       enqueue_transition_commit_callbacks
       true
@@ -120,19 +122,20 @@ module HasStateMachine
 
     private
 
-    ##
-    # Runs the after_transition_commit callbacks once the outermost open
-    # transaction commits, discarding them on rollback.
-    #
-    # @note Registers on the connection's current transaction because
-    #   +ActiveRecord.after_all_transactions_commit+ ignores non-joinable
-    #   transactions (like the gem's own) and would fire immediately.
-    # @return [void]
+    # Capture the previous state before transition callbacks can save the model again.
+    def update_state_attribute # rubocop:disable Naming/PredicateMethod -- returns update's result
+      return false unless object.update(state_attribute => state)
+
+      @previous_state = previous_state
+      true
+    end
+
+    # Use the current transaction: after_all_transactions_commit ignores our
+    # non-joinable transactions and would run callbacks before commit.
     def enqueue_transition_commit_callbacks
       current_transaction = object.class.connection.current_transaction
 
-      # Rails < 7.2 has no Transaction#after_commit, so callbacks fire
-      # immediately with no deferral. Drop this guard at Rails 7.2+.
+      # Rails < 7.2 has no Transaction#after_commit; run callbacks immediately.
       return run_callbacks(:transition_commit) { true } unless current_transaction.respond_to?(:after_commit)
 
       current_transaction.after_commit { run_callbacks(:transition_commit) { true } }
@@ -142,17 +145,18 @@ module HasStateMachine
       raise ActiveRecord::Rollback
     end
 
-    ##
-    # Helper method for grabbing the previous state of the object after
-    # it has been transitioned to the new state. Useful in
-    # after_transition blocks
+    # Available in after_transition and after_transition_commit callbacks.
     def previous_state
-      @previous_state.presence || object.previous_changes[object.state_attribute]&.first
+      @previous_state.presence || object.previous_changes[state_attribute]&.first
     end
 
     def state_instance(desired_state, transient_values)
-      klass = "#{object.workflow_namespace}::#{desired_state.to_s.classify}".safe_constantize
-      klass&.new(object, transient_values)
+      klass = if state_machine
+        state_machine.state_class_for(desired_state, object.class)
+      else
+        "#{object.workflow_namespace}::#{desired_state.to_s.classify}".safe_constantize
+      end
+      klass&.new(object, transient_values)&.bind_state_machine(state_machine)
     end
 
     def valid_transition?(desired_state_instance)
@@ -186,20 +190,13 @@ module HasStateMachine
         @transients || []
       end
 
-      ##
-      # Set the options for the HasStateMachine::State classes to define the possible
-      # states the current state can transition to and whether or not transitioning
-      # to the state should be performed within a transaction.
+      # transitions_to applies when leaving this state; transactional and transients apply when entering it.
       def state_options(transitions_to: [], transactional: false, transients: [])
         @possible_transitions = transitions_to.map(&:to_s)
         @transactional = transactional
         @transients = transients.map(&:to_sym)
 
-        transients.each do |transient_name|
-          define_method(transient_name) do
-            instance_variable_get(:"@#{transient_name}")
-          end
-        end
+        attr_reader(*@transients)
       end
     end
   end

data/lib/has_state_machine/state_helpers.rb

@@ -5,10 +5,7 @@ module HasStateMachine
     extend ActiveSupport::Concern
 
     included do
-      ##
-      # Sometimes you may want to skip the validations defined on
-      # the state when validating your object; set this accessor
-      # to true to do so.
+      # Skips state-instance validations for every machine on this object.
       attr_accessor :skip_state_validations
 
       delegate \
@@ -16,121 +13,98 @@ module HasStateMachine
         :state_validations_on_object?,
         :workflow_namespace,
         :workflow_states,
-        to: "self.class"
-
-      ##
-      # Sets the default value of the state method to the initial state
-      # defined in the state machine.
-      attribute state_attribute, :string, default: initial_state
-
-      ##
-      # Validate that the current state is a possible state, that there is a
-      # state class defined for it, and run the validations from the state
-      # class instance if need be.
-      validates state_attribute, inclusion: {in: workflow_states}, presence: true
-      validate :state_class_defined?
-      validate :state_instance_validations, if: :should_validate_state?
-
-      ##
-      # Overwrites the default getter for the state attribute to
-      # instantiate a HasStateMachine::State instance instead. If the state
-      # class does not exist, it simply returns a string.
-      #
-      # @return [HasStateMachine::State] the current state represented by a instance
-      #
-      # @example
-      #   post = Post.new(status: "draft")
-      #   post.status.class #=> Workflow::Post::Draft
-      define_method state_attribute.to_s do
-        return state_class.new(self) if state_class.present?
-
-        current_state
-      end
+        to: :class
+    end
 
-      workflow_states.each do |state|
-        ##
-        # Defines scopes based on the state machine's possible states
-        #
-        # @return [ActiveRecord_Relation]
-        # @example Retreiving a users published posts
-        #   > Post.published.where(user: user)
-        #   #=> [#<Post>]
-        if defined?(ActiveRecord) && (self < ActiveRecord::Base)
-          scope state, -> { where("#{table_name}.#{state_attribute} = ?", state) }
-        end
+    private
 
-        ##
-        # Defines boolean helpers to determine if the active state matches
-        # the specified state.
-        #
-        # @return [Boolean] whether or not the active state matches the call
-        # @example Check if a post is published
-        #   > post.published?
-        #   #=> true
-        define_method :"#{state}?" do
-          current_state == state
-        end
-      end
+    # Resolve at call time so redeclarations take effect.
+    def state_machine_definition_for(attr)
+      self.class.state_machine_definitions.fetch(attr)
+    end
 
-      private
+    # Default to the primary machine for 1.x compatibility.
+    def current_state(machine = self.class.primary_state_machine_definition)
+      self[machine.state_attribute]
+    end
 
-      ##
-      # Getter for the current state of the model based on the configured state
-      # attribute.
-      def current_state
-        self[state_attribute]
-      end
+    def state_class(machine = self.class.primary_state_machine_definition)
+      machine.state_class_for(current_state(machine), self.class)
+    end
 
-      ##
-      # Predicate method for determining whether or not the state validations
-      # should be run as part of the object validations.
-      def should_validate_state?
-        return false unless state_validations_on_object?
+    def state_class_defined?(machine = self.class.primary_state_machine_definition)
+      return if state_class(machine)
 
-        !skip_state_validations
-      end
+      errors.add(machine.state_attribute, :not_implemented, message: "class must be implemented")
+    end
 
-      ##
-      # Gets the HasStateMachine::State class that represents the current state
-      # of the model.
-      def state_class
-        return unless current_state.present?
+    def should_validate_state?(machine = self.class.primary_state_machine_definition)
+      return false unless machine.state_validations_on_object?
 
-        "#{workflow_namespace}::#{current_state.classify}".safe_constantize
-      end
+      !skip_state_validations
+    end
 
-      ##
-      # True unless unable to find the HasStateMachine::State class for the current
-      # state.
-      def state_class_defined?
-        return if state_class.present?
+    def state_instance_validations(machine = self.class.primary_state_machine_definition)
+      return unless state_class(machine)
 
-        errors.add(state_attribute, :not_implemented, message: "class must be implemented")
+      current_state_instance = public_send(machine.state_attribute)
+      return if current_state_instance.valid?
+
+      current_state_instance.errors.each do |error|
+        errors.add(error.attribute, error.type)
       end
+    end
 
-      ##
-      # Run the validations defined on the current HasStateMachine::State. Errors found there
-      # should be added to this object.
-      def state_instance_validations
-        return unless state_class.present?
+    class_methods do
+      delegate :state_attribute, :state_validations_on_object?, to: :primary_state_machine_definition
+      delegate :states, to: :primary_state_machine_definition, prefix: :workflow
 
-        current_state_instance = public_send(state_attribute.to_s)
-        return if current_state_instance.valid?
+      def workflow_namespace
+        primary_state_machine_definition.workflow_namespace_for(self)
+      end
 
-        current_state_instance.errors.each do |error|
-          errors.add(error.attribute, error.type)
-        end
+      # First declaration, including inherited machines.
+      # @return [HasStateMachine::Machine]
+      def primary_state_machine_definition
+        state_machine_definitions.each_value.first
       end
-    end
 
-    class_methods do
       private
 
-      ##
-      # The initial state of the workflow based on the first state defined in the model
-      # has_state_machine states array.
-      def initial_state
-        workflow_states.first
+      def define_state_machine_methods(machine)
+        attr = machine.state_attribute
+
+        attribute attr, :string, default: machine.initial_state
+
+        validates attr, inclusion: {in: machine.states}, presence: true
+
+        if machine.equal?(primary_state_machine_definition)
+          validate :state_class_defined?
+          validate :state_instance_validations, if: :should_validate_state?
+        else
+          validate { state_class_defined?(state_machine_definition_for(attr)) }
+          validate(if: -> { should_validate_state?(state_machine_definition_for(attr)) }) do
+            state_instance_validations(state_machine_definition_for(attr))
+          end
+        end
+
+        define_method attr do
+          current_machine = state_machine_definition_for(attr)
+          klass = state_class(current_machine)
+          return klass.new(self).bind_state_machine(current_machine) if klass
+
+          current_state(current_machine)
+        end
+
+        machine.states.each do |state|
+          if machine.scopes? && defined?(ActiveRecord) && (self < ActiveRecord::Base)
+            scope machine.scope_name(state), -> { where(attr => state) }
+          end
+
+          define_method machine.predicate_name(state) do
+            self[attr] == state
+          end
+        end
       end
     end
   end

data/lib/has_state_machine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HasStateMachine
-  VERSION = "1.2.2"
+  VERSION = "1.3.0"
 end

data/lib/ruby_lsp/has_state_machine/rails_server_addon.rb

@@ -29,10 +29,7 @@ module RubyLsp
         {name: model.name}
       end
 
-      ##
-      # Fast path: for the default "Workflow::<Model>" namespace, autoload just
-      # that one constant instead of eager loading the whole application. Only
-      # custom workflow_namespace configurations need the full scan below.
+      # Resolve conventional namespaces without eager-loading the application.
       def conventional_model_for(workflow_namespace)
         workflow_namespace = workflow_namespace.to_s
         return unless workflow_namespace.start_with?("Workflow::")
@@ -43,12 +40,28 @@ module RubyLsp
 
       def models_by_workflow_namespace
         @models_by_workflow_namespace ||= active_record_models.each_with_object({}) do |model, index|
-          next unless model.respond_to?(:workflow_namespace)
+          workflow_namespaces_for(model).each { |namespace| index[namespace] = model }
+        end
+      end
+
+      # Keep inherited namespaces mapped to the model that declared them.
+      def workflow_namespaces_for(model)
+        return [] if model.name.nil?
 
-          index[model.workflow_namespace] = model
+        definitions = model.try(:state_machine_definitions)
+        return Array(model.try(:workflow_namespace)) unless definitions
+
+        definitions.each_value.filter_map do |machine|
+          namespace = machine.workflow_namespace_for(model).to_s
+          namespace unless inherited_namespace?(model.superclass, machine, namespace)
         end
       end
 
+      def inherited_namespace?(parent, machine, namespace)
+        parent.try(:state_machine_definitions)&.value?(machine) &&
+          machine.workflow_namespace_for(parent).to_s == namespace
+      end
+
       def active_record_models
         @active_record_models ||= begin
           ::Rails.application&.eager_load!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_state_machine
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Benjamin Hargett
@@ -136,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -263,7 +277,9 @@ files:
 - lib/has_state_machine.rb
 - lib/has_state_machine/core_ext/string.rb
 - lib/has_state_machine/definition.rb
+- lib/has_state_machine/definition_builder.rb
 - lib/has_state_machine/deprecation.rb
+- lib/has_state_machine/machine.rb
 - lib/has_state_machine/railtie.rb
 - lib/has_state_machine/state.rb
 - lib/has_state_machine/state_helpers.rb