statesman 7.4.0 → 10.2.3

data/README.md

@@ -1,4 +1,4 @@
-<p align="center"><img src="http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png" alt="Statesman"></p>
+<p align="center"><img src="https://user-images.githubusercontent.com/110275/106792848-96e4ee80-664e-11eb-8fd1-16ff24b41eb2.png" alt="Statesman" width="512"></p>
 
 A statesmanlike state machine library.
 
@@ -30,7 +30,7 @@ protection.
 To get started, just add Statesman to your `Gemfile`, and then run `bundle`:
 
 ```ruby
-gem 'statesman', '~> 7.1.0'
+gem 'statesman', '~> 10.0.0'
 ```
 
 ## Usage
@@ -109,11 +109,59 @@ Order.first.state_machine.allowed_transitions # => ["checking_out", "cancelled"]
 Order.first.state_machine.can_transition_to?(:cancelled) # => true/false
 Order.first.state_machine.transition_to(:cancelled, optional: :metadata) # => true/false
 Order.first.state_machine.transition_to!(:cancelled) # => true/exception
+Order.first.state_machine.last_transition # => transition model or nil
+Order.first.state_machine.last_transition_to(:pending) # => transition model or nil
 
 Order.in_state(:cancelled) # => [#<Order id: "123">]
 Order.not_in_state(:checking_out) # => [#<Order id: "123">]
 ```
 
+If you'd like, you can also define a template for a generic state machine, then alter classes which extend it as required:
+
+```ruby
+module Template
+  def define_states
+    state :a, initial: true
+    state :b
+    state :c
+  end
+
+  def define_transitions
+    transition from: :a, to: :b
+    transition from: :b, to: :c
+    transition from: :c, to: :a
+  end
+end
+
+class Circular
+  include Statesman::Machine
+  extend Template
+  
+  define_states
+  define_transitions
+end
+
+class Linear
+  include Statesman::Machine
+  extend Template
+  
+  define_states
+  define_transitions
+  
+  remove_transitions from: :c, to: :a
+end
+
+class Shorter
+  include Statesman::Machine
+  extend Template
+
+  define_states
+  define_transitions
+
+  remove_state :c
+end
+```
+
 ## Persistence
 
 By default Statesman stores transition history in memory only. It can be
@@ -159,7 +207,8 @@ class Order < ActiveRecord::Base
 
   # Optionally delegate some methods
 
-  delegate :can_transition_to?, :current_state, :history, :last_transition,
+  delegate :can_transition_to?,
+           :current_state, :history, :last_transition, :last_transition_to,
            :transition_to!, :transition_to, :in_state?, to: :state_machine
 end
 ```
@@ -322,6 +371,10 @@ Machine.successors
 #### `Machine#current_state`
 Returns the current state based on existing transition objects.
 
+Takes an optional keyword argument to force a reload of data from the
+database.
+e.g `current_state(force_reload: true)`
+
 #### `Machine#in_state?(:state_1, :state_2, ...)`
 Returns true if the machine is in any of the given states.
 
@@ -331,6 +384,9 @@ Returns a sorted array of all transition objects.
 #### `Machine#last_transition`
 Returns the most recent transition object.
 
+#### `Machine#last_transition_to(:state)`
+Returns the most recent transition object to a given state.
+
 #### `Machine#allowed_transitions`
 Returns an array of states you can `transition_to` from current state.
 
@@ -347,6 +403,66 @@ Transition to the passed state, returning `true` on success. Swallows all
 Statesman exceptions and returns false on failure. (NB. if your guard or
 callback code throws an exception, it will not be caught.)
 
+
+## Errors
+
+### Initialization errors
+These errors are raised when the Machine and/or Model is initialized. A simple spec like
+```ruby
+expect { OrderStateMachine.new(Order.new, transition_class: OrderTransition) }.to_not raise_error
+```
+will expose these errors as part of your test suite
+
+#### InvalidStateError
+Raised if:
+  * Attempting to define a transition without a `to` state.
+  * Attempting to define a transition with a non-existent state.
+  * Attempting to define multiple states as `initial`.
+
+#### InvalidTransitionError
+Raised if:
+  * Attempting to define a callback `from` a state that has no valid transitions (A terminal state).
+  * Attempting to define a callback `to` the `initial` state if that state has no transitions to it.
+  * Attempting to define a callback with `from` and `to` where any of the pairs have no transition between them.
+
+#### InvalidCallbackError
+Raised if:
+  * Attempting to define a callback without a block.
+
+#### UnserializedMetadataError
+Raised if:
+  * ActiveRecord is configured to not serialize the `metadata` attribute into
+    to Database column backing it. See the `Using PostgreSQL JSON column` section.
+
+#### IncompatibleSerializationError
+Raised if:
+  * There is a mismatch between the column type of the `metadata` in the
+    Database and the model. See the `Using PostgreSQL JSON column` section.
+
+#### MissingTransitionAssociation
+Raised if:
+  * The model that `Statesman::Adapters::ActiveRecordQueries` is included in
+    does not have a `has_many` association to the `transition_class`.
+
+### Runtime errors
+These errors are raised by `transition_to!`. Using `transition_to` will
+supress `GuardFailedError` and `TransitionFailedError` and return `false` instead.
+
+#### GuardFailedError
+Raised if:
+  * A guard callback between `from` and `to` state returned a falsey value.
+
+#### TransitionFailedError
+Raised if:
+  * A transition is attempted but `current_state -> new_state` is not a valid pair.
+
+#### TransitionConflictError
+Raised if:
+  * A database conflict affecting the `sort_key` or `most_recent` columns occurs
+    when attempting a transition.
+    Retried automatically if it occurs wrapped in `retry_conflicts`.
+
+
 ## Model scopes
 
 A mixin is provided for the ActiveRecord adapter which adds scopes to easily
@@ -404,10 +520,12 @@ Model.in_state(:state_1).or(
 #### Storing the state on the model object
 
 If you wish to store the model state on the model directly, you can keep it up
-to date using an `after_transition` hook:
+to date using an `after_transition` hook.
+Combine it with the `after_commit` option to ensure the model state will only be
+saved once the transition has made it irreversibly to the database:
 
 ```ruby
-after_transition do |model, transition|
+after_transition(after_commit: true) do |model, transition|
   model.state = transition.to_state
   model.save!
 end
@@ -493,6 +611,30 @@ describe "some callback" do
 end
 ```
 
+## Compatibility with type checkers
+
+Including ActiveRecordQueries to your model can cause issues with type checkers
+such as Sorbet, this is because this technically is using a dynamic include,
+which is not supported by Sorbet.
+
+To avoid these issues you can instead include the TypeSafeActiveRecordQueries
+module and pass in configuration.
+
+```ruby
+class Order < ActiveRecord::Base
+  has_many :order_transitions, autosave: false
+
+  include Statesman::Adapters::TypeSafeActiveRecordQueries
+
+  configure_state_machine transition_class: OrderTransition,
+                          initial_state: :pending
+
+  def state_machine
+    @state_machine ||= OrderStateMachine.new(self, transition_class: OrderTransition)
+  end
+end
+```
+
 # Third-party extensions
 
 [statesman-sequel](https://github.com/badosu/statesman-sequel) - An adapter to make Statesman work with [Sequel](https://github.com/jeremyevans/sequel)

data/lib/generators/statesman/active_record_transition_generator.rb

@@ -7,7 +7,7 @@ module Statesman
   class ActiveRecordTransitionGenerator < Rails::Generators::Base
     include Statesman::GeneratorHelpers
 
-    desc "Create an ActiveRecord-based transition model"\
+    desc "Create an ActiveRecord-based transition model" \
          "with the required attributes"
 
     argument :parent, type: :string, desc: "Your parent model name"

data/lib/generators/statesman/generator_helpers.rb

@@ -11,7 +11,7 @@ module Statesman
     end
 
     def migration_class_name
-      klass.gsub(/::/, "").pluralize
+      klass.gsub("::", "").pluralize
     end
 
     def next_migration_number
@@ -39,8 +39,16 @@ module Statesman
     end
 
     def mysql?
-      ActiveRecord::Base.configurations[Rails.env].
-        try(:[], "adapter").try(:match, /mysql/)
+      configuration.try(:[], "adapter").try(:match, /mysql/)
+    end
+
+    # [] is deprecated and will be removed in 6.2
+    def configuration
+      if ActiveRecord::Base.configurations.respond_to?(:configs_for)
+        ActiveRecord::Base.configurations.configs_for(env_name: Rails.env).first
+      else
+        ActiveRecord::Base.configurations[Rails.env]
+      end
     end
 
     def database_supports_partial_indexes?

data/lib/statesman/adapters/active_record.rb

@@ -42,11 +42,17 @@ module Statesman
       def create(from, to, metadata = {})
         create_transition(from.to_s, to.to_s, metadata)
       rescue ::ActiveRecord::RecordNotUnique => e
-        raise TransitionConflictError, e.message if transition_conflict_error? e
+        if transition_conflict_error? e
+          # The history has the invalid transition on the end of it, which means
+          # `current_state` would then be incorrect. We force a reload of the history to
+          # avoid this.
+          transitions_for_parent.reload
+          raise TransitionConflictError, e.message
+        end
 
         raise
       ensure
-        @last_transition = nil
+        reset
       end
 
       def history(force_reload: false)
@@ -62,14 +68,21 @@ module Statesman
       def last(force_reload: false)
         if force_reload
           @last_transition = history(force_reload: true).last
+        elsif instance_variable_defined?(:@last_transition)
+          @last_transition
         else
-          @last_transition ||= history.last
+          @last_transition = history.last
+        end
+      end
+
+      def reset
+        if instance_variable_defined?(:@last_transition)
+          remove_instance_variable(:@last_transition)
         end
       end
 
       private
 
-      # rubocop:disable Metrics/MethodLength
       def create_transition(from, to, metadata)
         transition = transitions_for_parent.build(
           default_transition_attributes(to, metadata),
@@ -106,7 +119,6 @@ module Statesman
 
         transition
       end
-      # rubocop:enable Metrics/MethodLength
 
       def default_transition_attributes(to, metadata)
         {
@@ -147,13 +159,24 @@ module Statesman
 
       def most_recent_transitions(most_recent_id = nil)
         if most_recent_id
-          transitions_of_parent.and(
+          concrete_transitions_of_parent.and(
             transition_table[:id].eq(most_recent_id).or(
               transition_table[:most_recent].eq(true),
             ),
           )
         else
-          transitions_of_parent.and(transition_table[:most_recent].eq(true))
+          concrete_transitions_of_parent.and(transition_table[:most_recent].eq(true))
+        end
+      end
+
+      def concrete_transitions_of_parent
+        if transition_sti?
+          transitions_of_parent.and(
+            transition_table[transition_class.inheritance_column].
+              eq(transition_class.name),
+          )
+        else
+          transitions_of_parent
         end
       end
 
@@ -219,7 +242,7 @@ module Statesman
       end
 
       def next_sort_key
-        (last && last.sort_key + 10) || 10
+        (last && (last.sort_key + 10)) || 10
       end
 
       def serialized?(transition_class)
@@ -252,13 +275,18 @@ module Statesman
           end
       end
 
-      def parent_join_foreign_key
-        association =
-          parent_model.class.
-            reflect_on_all_associations(:has_many).
-            find { |r| r.name.to_s == @association_name.to_s }
+      def transition_sti?
+        transition_class.column_names.include?(transition_class.inheritance_column)
+      end
+
+      def parent_association
+        parent_model.class.
+          reflect_on_all_associations(:has_many).
+          find { |r| r.name.to_s == @association_name.to_s }
+      end
 
-        association_join_primary_key(association)
+      def parent_join_foreign_key
+        association_join_primary_key(parent_association)
       end
 
       def association_join_primary_key(association)
@@ -292,34 +320,42 @@ module Statesman
         return nil if column.nil?
 
         [
-          column, ::ActiveRecord::Base.default_timezone == :utc ? Time.now.utc : Time.now
+          column, default_timezone == :utc ? Time.now.utc : Time.now
         ]
       end
 
+      def default_timezone
+        # Rails 7 deprecates ActiveRecord::Base.default_timezone
+        # in favour of ActiveRecord.default_timezone
+        if ::ActiveRecord.respond_to?(:default_timezone)
+          return ::ActiveRecord.default_timezone
+        end
+
+        ::ActiveRecord::Base.default_timezone
+      end
+
       def mysql_gaplock_protection?
         Statesman.mysql_gaplock_protection?
       end
 
       def db_true
-        value = ::ActiveRecord::Base.connection.type_cast(
-          true,
-          transition_class.columns_hash["most_recent"],
-        )
-        ::ActiveRecord::Base.connection.quote(value)
+        ::ActiveRecord::Base.connection.quote(type_cast(true))
       end
 
       def db_false
-        value = ::ActiveRecord::Base.connection.type_cast(
-          false,
-          transition_class.columns_hash["most_recent"],
-        )
-        ::ActiveRecord::Base.connection.quote(value)
+        ::ActiveRecord::Base.connection.quote(type_cast(false))
       end
 
       def db_null
         Arel::Nodes::SqlLiteral.new("NULL")
       end
 
+      # Type casting against a column is deprecated and will be removed in Rails 6.2.
+      # See https://github.com/rails/arel/commit/6160bfbda1d1781c3b08a33ec4955f170e95be11
+      def type_cast(value)
+        ::ActiveRecord::Base.connection.type_cast(value)
+      end
+
       # Check whether the `most_recent` column allows null values. If it doesn't, set old
       # records to `false`, otherwise, set them to `NULL`.
       #

data/lib/statesman/adapters/active_record_queries.rb

@@ -49,6 +49,14 @@ module Statesman
 
           define_in_state(base, query_builder)
           define_not_in_state(base, query_builder)
+
+          define_method(:reload) do |*a|
+            instance = super(*a)
+            if instance.respond_to?(:state_machine, true)
+              instance.send(:state_machine).reset
+            end
+            instance
+          end
         end
 
         private
@@ -95,18 +103,18 @@ module Statesman
         def states_where(states)
           if initial_state.to_s.in?(states.map(&:to_s))
             "#{most_recent_transition_alias}.to_state IN (?) OR " \
-            "#{most_recent_transition_alias}.to_state IS NULL"
+              "#{most_recent_transition_alias}.to_state IS NULL"
           else
             "#{most_recent_transition_alias}.to_state IN (?) AND " \
-            "#{most_recent_transition_alias}.to_state IS NOT NULL"
+              "#{most_recent_transition_alias}.to_state IS NOT NULL"
           end
         end
 
         def most_recent_transition_join
           "LEFT OUTER JOIN #{model_table} AS #{most_recent_transition_alias} " \
-             "ON #{model.table_name}.id = " \
-                  "#{most_recent_transition_alias}.#{model_foreign_key} " \
-             "AND #{most_recent_transition_alias}.most_recent = #{db_true}"
+            "ON #{model.table_name}.#{model_primary_key} = " \
+            "#{most_recent_transition_alias}.#{model_foreign_key} " \
+            "AND #{most_recent_transition_alias}.most_recent = #{db_true}"
         end
 
         private
@@ -127,6 +135,10 @@ module Statesman
                 "and #{transition_class}."
         end
 
+        def model_primary_key
+          transition_reflection.active_record_primary_key
+        end
+
         def model_foreign_key
           transition_reflection.foreign_key
         end

data/lib/statesman/adapters/memory.rb

@@ -37,10 +37,14 @@ module Statesman
         @history
       end
 
+      def reset
+        @history = []
+      end
+
       private
 
       def next_sort_key
-        (last && last.sort_key + 10) || 10
+        (last && (last.sort_key + 10)) || 10
       end
     end
   end

data/lib/statesman/adapters/type_safe_active_record_queries.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Statesman
+  module Adapters
+    module TypeSafeActiveRecordQueries
+      def configure_state_machine(args = {})
+        transition_class = args.fetch(:transition_class)
+        initial_state = args.fetch(:initial_state)
+
+        include(
+          ActiveRecordQueries::ClassMethods.new(
+            transition_class: transition_class,
+            initial_state: initial_state,
+            most_recent_transition_alias: try(:most_recent_transition_alias),
+            transition_name: try(:transition_name),
+          ),
+        )
+      end
+    end
+  end
+end

data/lib/statesman/exceptions.rb

@@ -2,9 +2,13 @@
 
 module Statesman
   class InvalidStateError < StandardError; end
+
   class InvalidTransitionError < StandardError; end
+
   class InvalidCallbackError < StandardError; end
+
   class TransitionConflictError < StandardError; end
+
   class MissingTransitionAssociation < StandardError; end
 
   class TransitionFailedError < StandardError
@@ -24,13 +28,15 @@ module Statesman
   end
 
   class GuardFailedError < StandardError
-    def initialize(from, to)
+    def initialize(from, to, callback)
       @from = from
       @to = to
+      @callback = callback
       super(_message)
+      set_backtrace(callback.source_location.join(":")) if callback&.source_location
     end
 
-    attr_reader :from, :to
+    attr_reader :from, :to, :callback
 
     private
 
@@ -48,8 +54,8 @@ module Statesman
 
     def _message(transition_class_name)
       "#{transition_class_name}#metadata is not serialized. If you " \
-      "are using a non-json column type, you should `include " \
-      "Statesman::Adapters::ActiveRecordTransition`"
+        "are using a non-json column type, you should `include " \
+        "Statesman::Adapters::ActiveRecordTransition`"
     end
   end
 
@@ -62,9 +68,9 @@ module Statesman
 
     def _message(transition_class_name)
       "#{transition_class_name}#metadata column type cannot be json " \
-      "and serialized simultaneously. If you are using a json " \
-      "column type, it is not necessary to `include " \
-      "Statesman::Adapters::ActiveRecordTransition`"
+        "and serialized simultaneously. If you are using a json " \
+        "column type, it is not necessary to `include " \
+        "Statesman::Adapters::ActiveRecordTransition`"
     end
   end
 end

data/lib/statesman/guard.rb

@@ -6,7 +6,7 @@ require_relative "exceptions"
 module Statesman
   class Guard < Callback
     def call(*args)
-      raise GuardFailedError.new(from, to) unless super(*args)
+      raise GuardFailedError.new(from, to, callback) unless super(*args)
     end
   end
 end

data/lib/statesman/machine.rb

@@ -42,6 +42,17 @@ module Statesman
         states << name
       end
 
+      def remove_state(state_name)
+        state_name = state_name.to_s
+
+        remove_transitions(from: state_name)
+        remove_transitions(to: state_name)
+        remove_callbacks(from: state_name)
+        remove_callbacks(to: state_name)
+
+        @states.delete(state_name.to_s)
+      end
+
       def successors
         @successors ||= {}
       end
@@ -70,6 +81,20 @@ module Statesman
         successors[from] += to
       end
 
+      def remove_transitions(from: nil, to: nil)
+        raise ArgumentError, "Both from and to can't be nil!" if from.nil? && to.nil?
+        return if successors.nil?
+
+        if from.present?
+          @successors[from.to_s].delete(to.to_s) if to.present?
+          @successors.delete(from.to_s) if to.nil? || successors[from.to_s].empty?
+        elsif to.present?
+          @successors.
+            transform_values! { |to_states| to_states - [to.to_s] }.
+            filter! { |_from_state, to_states| to_states.any? }
+        end
+      end
+
       def before_transition(options = {}, &block)
         add_callback(callback_type: :before, callback_class: Callback,
                      from: options[:from], to: options[:to], &block)
@@ -151,6 +176,33 @@ module Statesman
           callback_class.new(from: from, to: to, callback: block)
       end
 
+      def remove_callbacks(from: nil, to: nil)
+        raise ArgumentError, "Both from and to can't be nil!" if from.nil? && to.nil?
+        return if callbacks.nil?
+
+        @callbacks.transform_values! do |callbacks|
+          filter_callbacks(callbacks, from: from, to: to)
+        end
+      end
+
+      def filter_callbacks(callbacks, from: nil, to: nil)
+        callbacks.filter_map do |callback|
+          next if callback.from == from && to.nil?
+
+          if callback.to.include?(to) && (from.nil? || callback.from == from)
+            next if callback.to == [to]
+
+            callback = Statesman::Callback.new({
+              from: callback.from,
+              to: callback.to - [to],
+              callback: callback.callback,
+            })
+          end
+
+          callback
+        end
+      end
+
       def validate_callback_type_and_class(callback_type, callback_class)
         raise ArgumentError, "missing keyword: callback_type" if callback_type.nil?
         raise ArgumentError, "missing keyword: callback_class" if callback_class.nil?
@@ -209,6 +261,10 @@ module Statesman
       @storage_adapter.last(force_reload: force_reload)
     end
 
+    def last_transition_to(state)
+      history.reverse.find { |transition| transition.to_state.to_sym == state.to_sym }
+    end
+
     def can_transition_to?(new_state, metadata = {})
       validate_transition(from: current_state,
                           to: new_state,
@@ -257,6 +313,10 @@ module Statesman
       false
     end
 
+    def reset
+      @storage_adapter.reset
+    end
+
     private
 
     def adapter_class(transition_class)

data/lib/statesman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statesman
-  VERSION = "7.4.0"
+  VERSION = "10.2.3"
 end

data/lib/statesman.rb

@@ -14,6 +14,8 @@ module Statesman
              "statesman/adapters/active_record_transition"
     autoload :ActiveRecordQueries,
              "statesman/adapters/active_record_queries"
+    autoload :TypeSafeActiveRecordQueries,
+             "statesman/adapters/type_safe_active_record_queries"
   end
   require "statesman/railtie" if defined?(::Rails::Railtie)