state_machines-activerecord 0.8.0 → 0.100.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4d6c3db18b13bbece06c33f047109e49d17eb1b97e8d26d8e001ed02a554b7a
-  data.tar.gz: ebd085709c837eb3c76994e23780b884136a338f92b63eb77c8c64620bd1980e
+  metadata.gz: 8da92c0d0872bf79ae81017dd5d16459e5222d10ee304390ddff3af14f1e1e05
+  data.tar.gz: c7ebd9fbdff4ee5bd2b0cca81b5daad186bb92157eddcb912829685571aa84eb
 SHA512:
-  metadata.gz: febb1df5b304114be86875716fb620b7c1b7fe1d0d44bea3c52c92451345e2cf2fb57e11cbd87d9b277079a52ebb9f82734d4174ea6722e8c6d933d274f88f6d
-  data.tar.gz: 3ee22472203164647a9d65ef4a5df8edfeda3874144b57281b9dce79ae210006f171bc02fdcdd24d44afd08ed4b9dff409b61d443a61052a1baeee27d8f3ed16
+  metadata.gz: 66d176f9efbc9d44ac2d5a5786f078e593d3590a99d855804ff4775649b18abae64264781f4ddc36a60ac253366aea0a9c02d3d1712d680d78fe443fffd437e7
+  data.tar.gz: f5e7a924679499d596439009b9bad2633af5389069959016595d31c44243f7551893cd2e53769e5e1b3a99b979f8d6ad1fa24d86caaa9134f0aa63528739b108

data/LICENSE.txt

@@ -1,5 +1,5 @@
 Copyright (c) 2006-2012 Aaron Pfeifer
-Copyright (c) 2014-2021 Abdelkader Boudih
+Copyright (c) 2014-2025 Abdelkader Boudih
 
 MIT License
 

data/README.md

@@ -1,11 +1,15 @@
-[![Build Status](https://travis-ci.com/state-machines/state_machines-activerecord.svg?branch=master)](https://travis-ci.com/state-machines/state_machines-activerecord)
-[![Code Climate](https://codeclimate.com/github/state-machines/state_machines-activerecord.svg)](https://codeclimate.com/github/state-machines/state_machines-activerecord)
+[![Build Status](https://github.com/state-machines/state_machines-activerecord/actions/workflows/ruby.yml/badge.svg)](https://github.com/state-machines/state_machines-activerecord/actions/workflows/ruby.yml)
 
 # StateMachines Active Record Integration
 
-The Active Record 5.1+ integration adds support for database transactions, automatically
+The Active Record 7.2+ integration adds support for database transactions, automatically
 saving the record, named scopes, validation errors.
 
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.2+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -27,7 +31,7 @@ For the complete usage guide, see http://www.rubydoc.info/github/state-machines/
 ### Example
 
 ```ruby
-class Vehicle < ActiveRecord::Base
+class Vehicle < ApplicationRecord
   state_machine :initial => :parked do
     before_transition :parked => any - :parked, :do => :put_on_seatbelt
     after_transition any => :parked do |vehicle, transition|
@@ -40,7 +44,7 @@ class Vehicle < ActiveRecord::Base
     end
 
     state :first_gear, :second_gear do
-      validates_presence_of :seatbelt_on
+      validates :seatbelt_on, presence: true
     end
   end
 
@@ -64,6 +68,15 @@ Vehicle.with_state(:parked)                         # also plural #with_states
 Vehicle.without_states(:first_gear, :second_gear)   # also singular #without_state
 ```
 
+#### Transparent Scopes
+State scopes will return all records when `nil` is passed, making them perfect for search filters:
+
+```ruby
+Vehicle.with_state(nil)                            # Returns all vehicles
+Vehicle.with_state(params[:state])                 # Returns all vehicles if params[:state] is nil
+Vehicle.where(color: 'red').with_state(nil)        # Returns all red vehicles (chainable)
+```
+
 ### State driven validations
 
 As mentioned in `StateMachines::Machine#state`, you can define behaviors,
@@ -73,7 +86,7 @@ framework, custom validators will not work as expected when defined to run
 in multiple states. For example:
 
 ```ruby
-class Vehicle < ActiveRecord::Base
+class Vehicle < ApplicationRecord
   state_machine do
     state :first_gear, :second_gear do
       validate :speed_is_legal
@@ -87,7 +100,7 @@ for the <tt>:second_gear</tt> state.  To avoid this, you can define your
 custom validation like so:
 
 ```ruby
-class Vehicle < ActiveRecord::Base
+class Vehicle < ApplicationRecord
   state_machine do
     state :first_gear, :second_gear do
       validate {|vehicle| vehicle.speed_is_legal}

data/lib/state_machines/integrations/active_record/locale.rb

@@ -1,12 +1,15 @@
+# frozen_string_literal: true
+
+# Use lazy evaluation to avoid circular dependencies with frozen default_messages
+# This ensures messages can be updated after gem loading while maintaining thread safety
 { en: {
-    activerecord: {
-        errors: {
-            messages: {
-                invalid: StateMachines::Machine.default_messages[:invalid],
-                invalid_event: StateMachines::Machine.default_messages[:invalid_event] % ['%{state}'],
-                invalid_transition: StateMachines::Machine.default_messages[:invalid_transition] % ['%{event}']
-            }
-        }
+  activerecord: {
+    errors: {
+      messages: {
+        invalid: ->(*) { StateMachines::Machine.default_messages[:invalid] },
+        invalid_event: ->(*) { format(StateMachines::Machine.default_messages[:invalid_event], '%<state>s') },
+        invalid_transition: ->(*) { format(StateMachines::Machine.default_messages[:invalid_transition], '%<event>s') }
+      }
     }
+  }
 } }
-

data/lib/state_machines/integrations/active_record/version.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module StateMachines
   module Integrations
     module ActiveRecord
-      VERSION = '0.8.0'
+      VERSION = '0.100.0'
     end
   end
 end

data/lib/state_machines/integrations/active_record.rb

@@ -3,7 +3,7 @@ require 'active_record'
 require 'state_machines/integrations/active_record/version'
 
 module StateMachines
-  module Integrations #:nodoc:
+  module Integrations # :nodoc:
     # Adds support for integrating state machines with ActiveRecord models.
     #
     # == Examples
@@ -11,7 +11,7 @@ module StateMachines
     # Below is an example of a simple state machine defined within an
     # ActiveRecord model:
     #
-    #   class Vehicle < ActiveRecord::Base
+    #   class Vehicle < ApplicationRecord
     #     state_machine :initial => :parked do
     #       event :ignite do
     #         transition :parked => :idling
@@ -78,25 +78,22 @@ module StateMachines
     # === Security implications
     #
     # Beware that public event attributes mean that events can be fired
-    # whenever mass-assignment is being used.  If you want to prevent malicious
-    # users from tampering with events through URLs / forms, the attribute
-    # should be protected like so:
-    #
-    #   class Vehicle < ActiveRecord::Base
-    #     attr_protected :state_event
-    #     # attr_accessible ... # Alternative technique
-    #
-    #     state_machine do
-    #       ...
+    # whenever mass-assignment is being used. If you want to prevent malicious
+    # users from tampering with events through URLs / forms, you should use
+    # Rails' strong parameters to control which attributes are permitted:
+    #
+    #   class VehiclesController < ApplicationController
+    #     def vehicle_params
+    #       params.require(:vehicle).permit(:color, :make, :model)
+    #       # Exclude state_event to prevent tampering
     #     end
     #   end
     #
     # If you want to only have *some* events be able to fire via mass-assignment,
     # you can build two state machines (one public and one protected) like so:
     #
-    #   class Vehicle < ActiveRecord::Base
-    #     attr_protected :state_event # Prevent access to events in the first machine
-    #
+    #   class Vehicle < ApplicationRecord
+    #     # Define private machine
     #     state_machine do
     #       # Define private events here
     #     end
@@ -105,6 +102,8 @@ module StateMachines
     #     state_machine :public_state, :attribute => :state do
     #       # Define public events here
     #     end
+    #
+    #     # Control access via strong parameters in your controller
     #   end
     #
     # == Transactions
@@ -115,7 +114,7 @@ module StateMachines
     #
     # For example,
     #
-    #   class Message < ActiveRecord::Base
+    #   class Message < ApplicationRecord
     #   end
     #
     #   Vehicle.state_machine do
@@ -136,7 +135,7 @@ module StateMachines
     #
     # To turn off transactions:
     #
-    #   class Vehicle < ActiveRecord::Base
+    #   class Vehicle < ApplicationRecord
     #     state_machine :initial => :parked, :use_transactions => false do
     #       ...
     #     end
@@ -150,7 +149,7 @@ module StateMachines
     # framework, custom validators will not work as expected when defined to run
     # in multiple states.  For example:
     #
-    #   class Vehicle < ActiveRecord::Base
+    #   class Vehicle < ApplicationRecord
     #     state_machine do
     #       ...
     #       state :first_gear, :second_gear do
@@ -163,7 +162,7 @@ module StateMachines
     # for the <tt>:second_gear</tt> state.  To avoid this, you can define your
     # custom validation like so:
     #
-    #   class Vehicle < ActiveRecord::Base
+    #   class Vehicle < ApplicationRecord
     #     state_machine do
     #       ...
     #       state :first_gear, :second_gear do
@@ -199,34 +198,43 @@ module StateMachines
     #
     # == Scopes
     #
-    # To assist in filtering models with specific states, a series of named
-    # scopes are defined on the model for finding records with or without a
+    # To assist in filtering models with specific states, a series of scopes
+    # are defined on the model for finding records with or without a
     # particular set of states.
     #
-    # These named scopes are essentially the functional equivalent of the
+    # These scopes are essentially the functional equivalent of the
     # following definitions:
     #
-    #   class Vehicle < ActiveRecord::Base
-    #     named_scope :with_states, lambda {|*states| {:conditions => {:state => states}}}
+    #   class Vehicle < ApplicationRecord
     #     # with_states also aliased to with_state
+    #     scope :with_states, ->(states) { states.present? ? where(state: states) : all }
     #
-    #     named_scope :without_states, lambda {|*states| {:conditions => ['state NOT IN (?)', states]}}
     #     # without_states also aliased to without_state
+    #     scope :without_states, ->(states) { states.present? ? where.not(state: states) : all }
     #   end
     #
     # *Note*, however, that the states are converted to their stored values
     # before being passed into the query.
     #
-    # Because of the way named scopes work in ActiveRecord, they can be
+    # Because of the way scopes work in ActiveRecord, they can be
     # chained like so:
     #
-    #   Vehicle.with_state(:parked).all(:order => 'id DESC')
+    #   Vehicle.with_state(:parked).order(id: :desc)
     #
     # Note that states can also be referenced by the string version of their
     # name:
     #
     #   Vehicle.with_state('parked')
     #
+    # === Transparent Scopes
+    #
+    # When `nil` is passed to any of the state scopes, they return `all` records
+    # without applying any filters. This allows for more flexible scope chaining
+    # in search interfaces:
+    #
+    #   Vehicle.with_state(params[:state])  # Returns all vehicles if params[:state] is nil
+    #   Vehicle.where(color: 'red').with_state(nil)  # Returns all red vehicles
+    #
     # == Callbacks
     #
     # All before/after transition callbacks defined for ActiveRecord models
@@ -235,7 +243,7 @@ module StateMachines
     #
     # For example,
     #
-    #   class Vehicle < ActiveRecord::Base
+    #   class Vehicle < ApplicationRecord
     #     state_machine :initial => :parked do
     #       before_transition any => :idling do |vehicle|
     #         vehicle.put_on_seatbelt
@@ -266,11 +274,11 @@ module StateMachines
     # ActiveRecord, a save failure will cause any records that get created in
     # your callback to roll back.  You can work around this issue like so:
     #
-    #   class TransitionLog < ActiveRecord::Base
-    #     establish_connection Rails.env.to_sym
+    #   class TransitionLog < ApplicationRecord
+    #     connects_to database: { writing: :primary, reading: :primary }
     #   end
     #
-    #   class Vehicle < ActiveRecord::Base
+    #   class Vehicle < ApplicationRecord
     #     state_machine do
     #       after_failure do |vehicle, transition|
     #         TransitionLog.create(:vehicle => vehicle, :transition => transition)
@@ -280,7 +288,7 @@ module StateMachines
     #     end
     #   end
     #
-    # The +TransitionLog+ model establishes a second connection to the database
+    # The +TransitionLog+ model establishes a separate connection to the database
     # that allows new records to be saved without being affected by rollbacks
     # in the +Vehicle+ model's transaction.
     #
@@ -305,65 +313,9 @@ module StateMachines
     # * (-) end transaction (if enabled)
     # * (9) after_commit
     #
-    # == Observers
-    #
-    # In addition to support for ActiveRecord-like hooks, there is additional
-    # support for ActiveRecord observers.  Because of the way ActiveRecord
-    # observers are designed, there is less flexibility around the specific
-    # transitions that can be hooked in.  However, a large number of hooks
-    # *are* supported.  For example, if a transition for a record's +state+
-    # attribute changes the state from +parked+ to +idling+ via the +ignite+
-    # event, the following observer methods are supported:
-    # * before/after/after_failure_to-_ignite_from_parked_to_idling
-    # * before/after/after_failure_to-_ignite_from_parked
-    # * before/after/after_failure_to-_ignite_to_idling
-    # * before/after/after_failure_to-_ignite
-    # * before/after/after_failure_to-_transition_state_from_parked_to_idling
-    # * before/after/after_failure_to-_transition_state_from_parked
-    # * before/after/after_failure_to-_transition_state_to_idling
-    # * before/after/after_failure_to-_transition_state
-    # * before/after/after_failure_to-_transition
-    #
-    # The following class shows an example of some of these hooks:
-    #
-    #   class VehicleObserver < ActiveRecord::Observer
-    #     def before_save(vehicle)
-    #       # log message
-    #     end
-    #
-    #     # Callback for :ignite event *before* the transition is performed
-    #     def before_ignite(vehicle, transition)
-    #       # log message
-    #     end
-    #
-    #     # Callback for :ignite event *after* the transition has been performed
-    #     def after_ignite(vehicle, transition)
-    #       # put on seatbelt
-    #     end
-    #
-    #     # Generic transition callback *before* the transition is performed
-    #     def after_transition(vehicle, transition)
-    #       Audit.log(vehicle, transition)
-    #     end
-    #   end
-    #
-    # More flexible transition callbacks can be defined directly within the
-    # model as described in StateMachines::Machine#before_transition
-    # and StateMachines::Machine#after_transition.
-    #
-    # To define a single observer for multiple state machines:
-    #
-    #   class StateMachineObserver < ActiveRecord::Observer
-    #     observe Vehicle, Switch, Project
-    #
-    #     def after_transition(record, transition)
-    #       Audit.log(record, transition)
-    #     end
-    #   end
-    #
     # == Internationalization
     #
-    # In Rails 2.2+, any error message that is generated from performing invalid
+    # Any error message that is generated from performing invalid
     # transitions can be localized.  The following default translations are used:
     #
     #   en:
@@ -376,9 +328,6 @@ module StateMachines
     #           # %{value} = attribute value, %{event} = Human event name, %{state} = Human current state name
     #           invalid_transition: "cannot transition via %{event}"
     #
-    # Notice that the interpolation syntax is %{key} in Rails 3+.  In Rails 2.x,
-    # the appropriate syntax is {{key}}.
-    #
     # You can override these for a specific model like so:
     #
     #   en:
@@ -418,7 +367,7 @@ module StateMachines
       include ActiveModel
 
       # The default options to use for state machines using this integration
-      @defaults = {:action => :save, use_transactions: true}
+      @defaults = { action: :save, use_transactions: true }
       class << self
         # Classes that inherit from ActiveRecord::Base will automatically use
         # the ActiveRecord integration.
@@ -435,78 +384,30 @@ module StateMachines
       end
 
       # Gets the db default for the machine's attribute
-      if ::ActiveRecord.gem_version >= Gem::Version.new('4.2.0')
-        def owner_class_attribute_default
-          if owner_class.connected? && owner_class.table_exists?
-            owner_class.column_defaults[attribute.to_s]
-          end
-        end
-      else
-        def owner_class_attribute_default
-          if owner_class.connected? && owner_class.table_exists?
-            if column = owner_class.columns_hash[attribute.to_s]
-              column.default
-            end
-          end
-        end
+      def owner_class_attribute_default
+        return unless owner_class.connected? && owner_class.table_exists?
+
+        owner_class.column_defaults[attribute.to_s]
       end
 
       def define_state_initializer
-        if ::ActiveRecord.gem_version >= Gem::Version.new('5.0.0.alpha')
-          define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
-            def initialize(attributes = nil, *)
-              super(attributes) do |*args|
-                scoped_attributes = (attributes || {}).merge(self.class.scope_attributes)
-
-                self.class.state_machines.initialize_states(self, {}, scoped_attributes)
-                yield(*args) if block_given?
-              end
-            end
-          end_eval
-        elsif ::ActiveRecord.gem_version >= Gem::Version.new('4.2')
-          define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
-            def initialize(attributes = nil, options = {})
-              scoped_attributes = (attributes || {}).merge(self.class.scope_attributes)
-
-              super(attributes, options) do |*args|
-                self.class.state_machines.initialize_states(self, {}, scoped_attributes)
-                yield(*args) if block_given?
-              end
-            end
-          end_eval
-        else
-          # Initializes static states
-          #
-          # This is the only available hook where the default set of attributes
-          # can be overridden for a new object *prior* to the processing of the
-          # attributes passed into #initialize
-          define_helper :class, <<-end_eval, __FILE__, __LINE__ + 1
-            def column_defaults(*) #:nodoc:
-              result = super
-              # No need to pass in an object, since the overrides will be forced
-              self.state_machines.initialize_states(nil, :static => :force, :dynamic => false, :to => result)
-              result
-            end
-          end_eval
-
-          # Initializes dynamic states
-          define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
-            def initialize(attributes = nil, options = {})
-              scoped_attributes = (attributes || {}).merge(self.class.scope_attributes)
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
+          def initialize(attributes = nil, *)
+            super(attributes) do |*args|
+              attributes = (attributes || {}).transform_keys { |key| self.class.attribute_aliases[key.to_s] || key }
+              scoped_attributes = attributes.merge(self.class.scope_attributes)
 
-              super(attributes, options) do |*args|
-                self.class.state_machines.initialize_states(self, {}, scoped_attributes)
-                yield(*args) if block_given?
-              end
+              self.class.state_machines.initialize_states(self, {}, scoped_attributes)
+              yield(*args) if block_given?
             end
-          end_eval
-        end
+          end
+        END_EVAL
       end
 
       # Uses around callbacks to run state events if using the :save hook
       def define_action_hook
         if action_hook == :save
-          define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
+          define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
               def save(*, **)
                 self.class.state_machine(#{name.inspect}).send(:around_save, self) { super }
               end
@@ -519,34 +420,44 @@ module StateMachines
               def changed_for_autosave?
                 super || self.class.state_machines.any? {|name, machine| machine.action == :save && machine.read(self, :event)}
               end
-          end_eval
+          END_EVAL
         else
           super
         end
       end
 
       # Runs state events around the machine's :save action
-      def around_save(object)
-        object.class.state_machines.transitions(object, action).perform { yield }
+      def around_save(object, &)
+        # Pass fiber: false to avoid deadlocks with ActiveRecord's LoadInterlockAwareMonitor
+        object.class.state_machines.transitions(object, action, fiber: false).perform(&)
       end
 
       # Creates a scope for finding records *with* a particular state or
       # states for the attribute
       def create_with_scope(name)
-        create_scope(name, ->(values) { ["#{attribute_column} IN (?)", values] })
+        attr_name = attribute
+        lambda do |klass, values|
+          if values.present?
+            klass.where(attr_name => values)
+          else
+            klass.all
+          end
+        end
       end
 
       # Creates a scope for finding records *without* a particular state or
       # states for the attribute
       def create_without_scope(name)
-        create_scope(name, ->(values) { ["#{attribute_column} NOT IN (?)", values] })
+        attr_name = attribute
+        lambda do |klass, values|
+          if values.present?
+            klass.where.not(attr_name => values)
+          else
+            klass.all
+          end
+        end
       end
 
-      # Generates the fully-qualifed column name for this machine's attribute
-      def attribute_column
-        connection = owner_class.connection
-        "#{connection.quote_table_name(owner_class.table_name)}.#{connection.quote_column_name(attribute)}"
-      end
 
       # Runs a new database transaction, rolling back any changes by raising
       # an ActiveRecord::Rollback exception if the yielded block fails
@@ -565,17 +476,19 @@ module StateMachines
 
       private
 
-        # Defines a new named scope with the given name
-        def create_scope(name, scope)
-          lambda { |model, values| model.where(scope.call(values)) }
-        end
 
-        # ActiveModel's use of method_missing / respond_to for attribute methods
-        # breaks both ancestor lookups and defined?(super).  Need to special-case
-        # the existence of query attribute methods.
-        def owner_class_ancestor_has_method?(scope, method)
-          scope == :instance && method == "#{attribute}?" ? owner_class : super
-        end
+      # Generates the results for the given scope based on one or more states to filter by
+      def run_scope(scope, machine, klass, states)
+        values = states.flatten.compact.map { |state| machine.states.fetch(state).value }
+        scope.call(klass, values)
+      end
+
+      # ActiveModel's use of method_missing / respond_to for attribute methods
+      # breaks both ancestor lookups and defined?(super).  Need to special-case
+      # the existence of query attribute methods.
+      def owner_class_ancestor_has_method?(scope, method)
+        scope == :instance && method == "#{attribute}?" ? owner_class : super
+      end
     end
     register(ActiveRecord)
   end

data/lib/state_machines-activerecord.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support'
 require 'state_machines/integrations/active_record'