state_machines-activerecord 0.8.0 → 0.200.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4d6c3db18b13bbece06c33f047109e49d17eb1b97e8d26d8e001ed02a554b7a
-  data.tar.gz: ebd085709c837eb3c76994e23780b884136a338f92b63eb77c8c64620bd1980e
+  metadata.gz: f022e63c2bfd6af186733c95cbfc19cb7f25dfff128c791e5199b1a3f4e6d760
+  data.tar.gz: '094b3a2befdd974fa1828e9237f75f0a5a38319b7e38b56b8a3dda376a1e797d'
 SHA512:
-  metadata.gz: febb1df5b304114be86875716fb620b7c1b7fe1d0d44bea3c52c92451345e2cf2fb57e11cbd87d9b277079a52ebb9f82734d4174ea6722e8c6d933d274f88f6d
-  data.tar.gz: 3ee22472203164647a9d65ef4a5df8edfeda3874144b57281b9dce79ae210006f171bc02fdcdd24d44afd08ed4b9dff409b61d443a61052a1baeee27d8f3ed16
+  metadata.gz: cfb9f8bca11c37eeaff38ff0a237c2cc241986bba88ee4a8859199ea05ee7d06b4449da73574e0125f678de3082f3ba4e472f491f0efe9100fc2b585cac5e818
+  data.tar.gz: 8fb449a5ead40d4cf43e92208d307bb34f557e9aae068cda123c968ded28aecfa7a97c416426b04f99afd2550a50b54f852bc6e04c5ab6dc4fef62199d5e615d

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,7 +68,173 @@ Vehicle.with_state(:parked)                         # also plural #with_states
 Vehicle.without_states(:first_gear, :second_gear)   # also singular #without_state
 ```
 
-### State driven validations
+#### 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)
+```
+
+## Rails Enum Integration
+
+When your ActiveRecord model uses Rails enums and defines a state machine on the same attribute, this gem automatically detects the conflict and provides seamless integration. This prevents method name collisions between Rails enum methods and state machine methods.
+
+### Auto-Detection and Conflict Resolution
+
+```ruby
+class Order < ApplicationRecord
+  # Rails enum definition
+  enum :status, { pending: 0, processing: 1, completed: 2, cancelled: 3 }
+  
+  # State machine on the same attribute
+  state_machine :status do
+    state :pending, :processing, :completed, :cancelled
+    
+    event :process do
+      transition pending: :processing
+    end
+    
+    event :complete do
+      transition processing: :completed
+    end
+    
+    event :cancel do
+      transition [:pending, :processing] => :cancelled
+    end
+  end
+end
+```
+
+When enum integration is detected, the gem automatically:
+- Preserves original Rails enum methods (`pending?`, `processing?`, etc.)
+- Generates prefixed state machine methods to avoid conflicts (`status_pending?`, `status_processing?`, etc.)
+- Creates prefixed scope methods (`Order.status_pending`, `Order.status_processing`, etc.)
+
+### Available Methods
+
+**Original Rails enum methods (preserved):**
+```ruby
+order = Order.create(status: :pending)
+order.pending?        # => true (Rails enum method)
+order.processing?     # => false (Rails enum method)
+order.processing!     # Sets status to :processing (Rails enum method)
+
+Order.pending         # Rails enum scope
+Order.processing      # Rails enum scope
+```
+
+**Generated state machine methods (prefixed):**
+```ruby
+# Predicate methods
+order.status_pending?     # => true (state machine method)
+order.status_processing?  # => false (state machine method)
+order.status_completed?   # => false (state machine method)
+
+# Bang methods (for conflict resolution only)
+# These are placeholders and raise runtime errors
+order.status_processing!  # => raises RuntimeError
+
+# Scope methods  
+Order.status_pending      # State machine scope
+Order.status_processing   # State machine scope
+Order.not_status_pending  # Negative state machine scope
+```
+
+### Introspection API
+
+The integration provides a comprehensive introspection API for advanced use cases:
+
+```ruby
+machine = Order.state_machine(:status)
+
+# Check if enum integration is enabled
+machine.enum_integrated?  # => true
+
+# Get the Rails enum mapping
+machine.enum_mapping     # => {"pending"=>0, "processing"=>1, "completed"=>2, "cancelled"=>3}
+
+# Get original Rails enum methods that were preserved
+machine.original_enum_methods
+# => ["pending?", "processing?", "completed?", "cancelled?", "pending!", "processing!", ...]
+
+# Get state machine methods that were generated
+machine.state_machine_methods  
+# => ["status_pending?", "status_processing?", "status_completed?", "status_cancelled?", ...]
+```
+
+## Integer-backed state attributes
+
+Integer columns whose states don't declare explicit values are converted
+transparently: application code reads state names while the database stores
+integers (mapped by definition order).
+
+```ruby
+class Order < ApplicationRecord
+  state_machine :status, initial: :pending do
+    state :pending
+    state :approved
+  end
+end
+
+order = Order.create!
+order.status = :approved
+order.status # => "approved"
+# The database stores 1.
+```
+
+Machines where every state declares an explicit integer value keep the classic
+raw-integer behavior automatically: reads return the integer and `status_name`
+returns the state name:
+
+```ruby
+class LegacyOrder < ApplicationRecord
+  self.table_name = "orders"
+
+  state_machine :status, initial: :pending do
+    state :pending, value: 0
+    state :approved, value: 1
+
+    event :approve do
+      transition pending: :approved
+    end
+  end
+end
+
+order = LegacyOrder.create!
+order.approve!
+order.status      # => 1
+order.status_name # => :approved
+# The database stores 1.
+```
+
+Applications that want no type conversion at all can disable it during boot,
+before defining affected state machines:
+
+```ruby
+# config/initializers/state_machines.rb
+
+StateMachines::Integrations::ActiveRecord.auto_convert_integer_state_attributes = false
+```
+
+With this setting disabled, integer-backed state attributes are left entirely
+to ActiveRecord's normal integer handling.
+
+### Requirements for Enum Integration
+
+- The state machine attribute must match an existing Rails enum attribute
+- Auto-detection is enabled by default when this condition is met
+
+### Configuration Options
+
+The enum integration supports several configuration options:
+
+- `prefix` (default: true) - Adds a prefix to generated methods to avoid conflicts
+- `suffix` (default: false) - Alternative naming strategy using suffixes instead of prefixes
+- `scopes` (default: true) - Controls whether state machine scopes are generated
+
+## State driven validations
 
 As mentioned in `StateMachines::Machine#state`, you can define behaviors,
 like validations, that only execute for certain states. One *important*
@@ -73,7 +243,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 +257,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/type/integer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module Type
+    # Custom ActiveRecord attribute type for state machine attributes backed by
+    # integer columns. Handles bidirectional conversion between state name strings
+    # (used internally by the state machine) and integer values (stored in the DB).
+    #
+    # States without explicit integer values are mapped by their index position
+    # in the states collection (0, 1, 2, …). States with an explicit integer
+    # value (e.g. state :pending, value: 2) use that value directly.
+    #
+    # When *every* named state has an explicit integer value, the column already
+    # stores the canonical state values and no name<->integer conversion is
+    # needed. In that case the type delegates to the column's original integer
+    # type, preserving the classic raw-integer behavior
+    # (e.g. record.status # => 1, record.status_name # => :approved).
+    class Integer < ::ActiveRecord::Type::Value
+      # The column's original attribute type, exposed so re-registration
+      # (e.g. for STI subclasses) can reuse it instead of wrapping this type.
+      #
+      # @return [ActiveModel::Type::Value]
+      attr_reader :raw_type
+
+      # @param states [StateMachines::StateCollection] live collection of the
+      #   machine's states; held by reference because states are defined after
+      #   the type is registered
+      # @param raw_type [ActiveModel::Type::Value, nil] the column's original
+      #   attribute type, used verbatim in passthrough mode so adapter-specific
+      #   integer behavior (limits, range checks) is preserved
+      def initialize(states, raw_type: nil)
+        @states = states
+        @raw_type = raw_type || ::ActiveModel::Type::Integer.new
+        super()
+      end
+
+      # Converts an integer from the database to a state name string.
+      #
+      # @param value [Integer, String, nil] raw database value
+      # @return [String, Integer, nil] state name, or the original type's value
+      #   in passthrough mode, or the raw value when no state matches
+      def deserialize(value)
+        states = named_states
+        return @raw_type.deserialize(value) if passthrough?(states)
+        return nil if value.nil?
+
+        int_val = value.to_i
+        state = states.detect { |s| state_integer(s, states) == int_val }
+        state ? state.name.to_s : value
+      end
+
+      # Converts an assigned value (symbol, string, or integer) to the in-memory
+      # state name string.
+      #
+      # @param value [Symbol, String, Integer, nil] assigned value
+      # @return [String, Integer, nil] state name, or the original type's cast
+      #   in passthrough mode
+      def cast(value)
+        states = named_states
+        return @raw_type.cast(value) if passthrough?(states)
+        return nil if value.nil?
+
+        state = states.detect { |s| s.name.to_s == value.to_s }
+        state ||= states.detect { |s| state_integer(s, states) == value.to_i } if value.respond_to?(:to_i)
+        state ? state.name.to_s : value.to_s
+      end
+
+      # Converts a state name string to its integer for the database write.
+      #
+      # @param value [String, Symbol, Integer, nil] in-memory value
+      # @return [Integer, nil] integer to store
+      def serialize(value)
+        states = named_states
+        return @raw_type.serialize(value) if passthrough?(states)
+        return nil if value.nil?
+
+        state = states.detect { |s| s.name.to_s == value.to_s }
+        state ? state_integer(state, states) : value
+      end
+
+      # @return [Symbol] the ActiveModel type identifier
+      def type
+        :integer
+      end
+
+      private
+
+      # All non-nil states in definition order, not memoized because states are
+      # added to the collection after the type is instantiated.
+      #
+      # @return [Array<StateMachines::State>]
+      def named_states
+        @states.reject { |s| s.name.nil? }
+      end
+
+      # Whether the machine was defined for raw integer storage, in which case
+      # conversion would change documented behavior. True when every named state
+      # declares an explicit integer value. Evaluated lazily on every call
+      # because states (and their values) are defined after the type is
+      # registered. Uses value(false) so dynamic (Proc) state values are never
+      # evaluated for this metadata decision.
+      #
+      # @param states [Array<StateMachines::State>] pre-computed named states
+      # @return [Boolean]
+      def passthrough?(states)
+        states.any? && states.all? { |s| s.value(false).is_a?(::Integer) }
+      end
+
+      # The integer to use for storage: the explicit state value if set
+      # (e.g. state :pending, value: 2), otherwise the index position among
+      # named states.
+      #
+      # @param state [StateMachines::State]
+      # @param states [Array<StateMachines::State>] pre-computed named states
+      # @return [Integer]
+      def state_integer(state, states)
+        value = state.value(false)
+        value.is_a?(::Integer) ? value : states.index(state)
+      end
+    end
+  end
+end

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.200.0'
     end
   end
 end