state_machines-activerecord 0.9.0 → 0.100.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 570d0e44cce8dade9ceb135c6e24cfcafb7dc0325ee8f40d99658d663072e234
-  data.tar.gz: 2195bc14693c748c3248c3ddd42bc0a26faccbdf78285c6d24f17e54bd3ec0fd
+  metadata.gz: 8da92c0d0872bf79ae81017dd5d16459e5222d10ee304390ddff3af14f1e1e05
+  data.tar.gz: c7ebd9fbdff4ee5bd2b0cca81b5daad186bb92157eddcb912829685571aa84eb
 SHA512:
-  metadata.gz: dde59866fccfe87fbd05658fd0f0b5d92c2129ff3e448c75983722e7a5468cc3201f63dfb319442a60e536e4774ecfd61429d0e979e454abba568e10a1b7cc15
-  data.tar.gz: f78734f5c798ae8f468d69d22e1983b95839dcf724e6b7c1e6563f81a3f1976930b6ff52d275163feaccd0419888a9d754f47d587a112df019a9c9804f21bd31
+  metadata.gz: 66d176f9efbc9d44ac2d5a5786f078e593d3590a99d855804ff4775649b18abae64264781f4ddc36a60ac253366aea0a9c02d3d1712d680d78fe443fffd437e7
+  data.tar.gz: f5e7a924679499d596439009b9bad2633af5389069959016595d31c44243f7551893cd2e53769e5e1b3a99b979f8d6ad1fa24d86caaa9134f0aa63528739b108

data/LICENSE.txt

@@ -1,5 +1,5 @@
 Copyright (c) 2006-2012 Aaron Pfeifer
-Copyright (c) 2014-2023 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:
@@ -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,

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.9.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
@@ -78,16 +78,14 @@ 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 < ApplicationRecord
-    #     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
     #
@@ -95,8 +93,7 @@ module StateMachines
     # you can build two state machines (one public and one protected) like so:
     #
     #   class Vehicle < ApplicationRecord
-    #     attr_protected :state_event # Prevent access to events in the first machine
-    #
+    #     # 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
@@ -199,33 +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 < 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
@@ -266,7 +275,7 @@ module StateMachines
     # your callback to roll back.  You can work around this issue like so:
     #
     #   class TransitionLog < ApplicationRecord
-    #     establish_connection Rails.env.to_sym
+    #     connects_to database: { writing: :primary, reading: :primary }
     #   end
     #
     #   class Vehicle < ApplicationRecord
@@ -279,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.
     #
@@ -304,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:
@@ -375,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:
@@ -417,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,28 +385,29 @@ module StateMachines
 
       # Gets the db default for the machine's attribute
       def owner_class_attribute_default
-        if owner_class.connected? && owner_class.table_exists?
-          owner_class.column_defaults[attribute.to_s]
-        end
+        return unless owner_class.connected? && owner_class.table_exists?
+
+        owner_class.column_defaults[attribute.to_s]
       end
 
       def define_state_initializer
-        define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
+        define_helper :instance, <<-END_EVAL, __FILE__, __LINE__ + 1
           def initialize(attributes = nil, *)
             super(attributes) do |*args|
-              scoped_attributes = (attributes || {}).merge(self.class.scope_attributes)
+              attributes = (attributes || {}).transform_keys { |key| self.class.attribute_aliases[key.to_s] || key }
+              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
+        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
@@ -469,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
@@ -515,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'