statesman 4.1.2 → 4.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a4d4aa46f593b25a40fdb2ce22c437d06edf7ec4
-  data.tar.gz: 9b734682ee2d770977863fff48db0e0606fea028
+  metadata.gz: ad6e72cd43e5b54c25a618524a51aa2029d50a60
+  data.tar.gz: dd974b992be7e1a764f1b0b58613fe1dbf2951f9
 SHA512:
-  metadata.gz: 890add9a875cfa4bda6a926059b57bdc03c64c8aa3d525d0ee7ff3530a0d2c4c6b0230acfebd2079e89e4eafb655b368acc7d64492650fce6464bcb5958e29ae
-  data.tar.gz: 289d75e87a6a8ba34493fde16d24b3747840b3c865bae67b0bf9fbb991de86e2f0006e9cf48679c89a6bcbbe66deaec19bfaf1e4023b60918ce4088c9ab43e2c
+  metadata.gz: ac91aa0a9d34410eda08fab8eded5fba9efc280617dad18eb93c6ed91c8ca46f8a34c3e13f5c7d5ca3797053551e4a514b9bcb1d6433cf7fb9ca2d29bf3da423
+  data.tar.gz: 6223d5ca89126a28905943f0b9e91bef5d5c1c2090e3effb6e78b3849a2c7c01c24069f1171307ae0fb4d3c2757dede80f6a04239f21c0bba7f50af1e6c80fe3

data/.circleci/config.yml

@@ -37,7 +37,6 @@ jobs:
         environment:
           - RAILS_VERSION=4.2.9
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -52,7 +51,6 @@ jobs:
         environment:
           - RAILS_VERSION=4.2.9
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -65,7 +63,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.0.5
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -80,7 +77,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.0.5
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -93,7 +89,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.1.3
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -108,7 +103,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.1.3
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -121,7 +115,6 @@ jobs:
         environment:
           - RAILS_VERSION=6.0.0
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -136,7 +129,6 @@ jobs:
         environment:
           - RAILS_VERSION=6.0.0
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -149,7 +141,6 @@ jobs:
         environment:
           - RAILS_VERSION=master
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -177,7 +168,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.2.3
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -192,7 +182,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.2.3
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -205,7 +194,6 @@ jobs:
         environment:
           - RAILS_VERSION=4.2.9
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -220,7 +208,6 @@ jobs:
         environment:
           - RAILS_VERSION=4.2.9
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -233,7 +220,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.0.5
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -248,7 +234,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.0.5
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -261,7 +246,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.1.3
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -276,7 +260,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.1.3
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -289,7 +272,6 @@ jobs:
         environment:
           - RAILS_VERSION=4.2.9
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -304,7 +286,6 @@ jobs:
         environment:
           - RAILS_VERSION=4.2.9
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -317,7 +298,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.0.5
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -332,7 +312,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.0.5
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:
@@ -345,7 +324,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.1.3
           - DATABASE_URL=mysql2://root@127.0.0.1/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=3306
       - image: circleci/mysql:5.7.18
         environment:
@@ -360,7 +338,6 @@ jobs:
         environment:
           - RAILS_VERSION=5.1.3
           - DATABASE_URL=postgres://postgres@localhost/statesman_test
-          - EXCLUDE_MONGOID=true
           - DATABASE_DEPENDENCY_PORT=5432
       - image: circleci/postgres:9.6
         environment:

data/.rubocop_todo.yml

@@ -85,7 +85,6 @@ RSpec/NestedGroups:
 RSpec/ScatteredSetup:
   Exclude:
     - 'spec/statesman/adapters/active_record_spec.rb'
-    - 'spec/statesman/adapters/mongoid_spec.rb'
     - 'spec/statesman/adapters/shared_examples.rb'
     - 'spec/statesman/machine_spec.rb'
 
@@ -96,5 +95,4 @@ RSpec/VerifiedDoubles:
     - 'spec/generators/statesman/active_record_transition_generator_spec.rb'
     - 'spec/generators/statesman/migration_generator_spec.rb'
     - 'spec/statesman/adapters/active_record_spec.rb'
-    - 'spec/statesman/adapters/mongoid_spec.rb'
     - 'spec/statesman/adapters/shared_examples.rb'

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## v4.1.3, 6th November 2019
+
+- Add accessible from / to state attributes on the `TransitionFailedError` to avoid parsing strings [@ahjmorton](https://github.com/gocardless/statesman/pull/367)
+- Add `after_transition_failure` mechanism [@credric-cordenier](https://github.com/gocardless/statesman/pull/366)
+
 ## v4.1.2, 17th August 2019
 
 - Add support for Rails 6 [@greysteil](https://github.com/gocardless/statesman/pull/360)

data/Gemfile

@@ -11,8 +11,6 @@ end
 # rubocop:enable Bundler/DuplicatedGem
 
 group :development do
-  gem "mongoid", ">= 3.1" unless ENV["EXCLUDE_MONGOID"]
-
   # test/unit is no longer bundled with Ruby 2.2, but required by Rails
   gem "test-unit", "~> 3.0" if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.2.0")
 end

data/README.md

@@ -76,22 +76,16 @@ Then, link it to your model:
 
 ```ruby
 class Order < ActiveRecord::Base
-  include Statesman::Adapters::ActiveRecordQueries
-
   has_many :order_transitions, autosave: false
 
+  include Statesman::Adapters::ActiveRecordQueries[
+    transition_class: OrderTransition,
+    initial_state: :pending
+  ]
+
   def state_machine
     @state_machine ||= OrderStateMachine.new(self, transition_class: OrderTransition)
   end
-
-  def self.transition_class
-    OrderTransition
-  end
-
-  def self.initial_state
-    :pending
-  end
-  private_class_method :initial_state
 end
 ```
 
@@ -164,8 +158,9 @@ class Order < ActiveRecord::Base
   end
 
   # Optionally delegate some methods
-  delegate :can_transition_to?, :transition_to!, :transition_to, :current_state,
-           to: :state_machine
+
+  delegate :can_transition_to?, :current_state, :history, :last_transition,
+           :transition_to!, :transition_to, :in_state?, to: :state_machine
 end
 ```
 #### Using PostgreSQL JSON column
@@ -199,13 +194,11 @@ or 5. To do that
 ```ruby
 Statesman.configure do
   storage_adapter(Statesman::Adapters::ActiveRecord)
-  # ...or
-  storage_adapter(Statesman::Adapters::Mongoid)
 end
 ```
 Statesman defaults to storing transitions in memory. If you're using rails, you
 can instead configure it to persist transitions to the database by using the
-ActiveRecord or Mongoid adapter.
+ActiveRecord adapter.
 
 Statesman will fallback to memory unless you specify a transition_class when instantiating your state machine. This allows you to only persist transitions on certain state machines in your app.
 
@@ -234,7 +227,8 @@ end
 ```
 Define a guard. `to` and `from` parameters are optional, a nil parameter means
 guard all transitions. The passed block should evaluate to a boolean and must
-be idempotent as it could be called many times.
+be idempotent as it could be called many times. The guard will pass when it
+evaluates to a truthy value and fail when it evaluates to a falsey value (`nil` or `false`).
 
 #### `Machine.before_transition`
 ```ruby
@@ -261,6 +255,35 @@ after the transition.
 If you specify `after_commit: true`, the callback will be executed once the
 transition has been committed to the database.
 
+#### `Machine.after_transition_failure`
+```ruby
+Machine.after_transition_failure(from: :some_state, to: :another_state) do |object|
+  Logger.info("transition failed for #{object.id}")
+end
+```
+Define a callback to run if `Statesman::TransitionFailedError` is raised
+during the execution of transition callbacks. `to` and `from`
+parameters are optional, a nil parameter means run after all transitions.
+The model object is passed as an argument to the callback.
+This is executed outside of the transaction wrapping other callbacks.
+If using `transition!` the exception is re-raised after these callbacks are
+executed.
+
+#### `Machine.after_guard_failure`
+```ruby
+Machine.after_guard_failure(from: :some_state, to: :another_state) do |object|
+  Logger.info("guard failed for #{object.id}")
+end
+```
+Define a callback to run if `Statesman::GuardFailedError` is raised
+during the execution of guard callbacks. `to` and `from`
+parameters are optional, a nil parameter means run after all transitions.
+The model object is passed as an argument to the callback.
+This is executed outside of the transaction wrapping other callbacks.
+If using `transition!` the exception is re-raised after these callbacks are
+executed.
+
+
 #### `Machine.new`
 ```ruby
 my_machine = Machine.new(my_model, transition_class: MyTransitionModel)
@@ -328,43 +351,34 @@ callback code throws an exception, it will not be caught.)
 
 A mixin is provided for the ActiveRecord adapter which adds scopes to easily
 find all models currently in (or not in) a given state. Include it into your
-model and define `transition_class` and `initial_state` class methods:
+model and passing in `transition_class` and `initial_state` as options.
+
+In 4.1.1 and below, these two options had to be defined as methods on the model,
+but 4.2.0 and above allow this style of configuration as well. The old method
+pollutes the model with extra class methods, and is deprecated, to be removed
+in 5.0.0.
 
 ```ruby
 class Order < ActiveRecord::Base
-  include Statesman::Adapters::ActiveRecordQueries
-
-  def self.transition_class
-    OrderTransition
-  end
-  private_class_method :transition_class
-
-  def self.initial_state
-    OrderStateMachine.initial_state
-  end
-  private_class_method :initial_state
+  has_many :order_transitions, autosave: false
+  include Statesman::Adapters::ActiveRecordQueries[
+    transition_class: OrderTransition,
+    initial_state: OrderStateMachine.initial_state
+  ]
 end
 ```
 
 If the transition class-name differs from the association name, you will also
-need to define a corresponding `transition_name` class method:
+need to pass `transition_name` as an option:
 
 ```ruby
 class Order < ActiveRecord::Base
   has_many :transitions, class_name: "OrderTransition", autosave: false
-
-  def self.transition_name
-    :transitions
-  end
-
-  def self.transition_class
-    OrderTransition
-  end
-
-  def self.initial_state
-    OrderStateMachine.initial_state
-  end
-  private_class_method :initial_state
+  include Statesman::Adapters::ActiveRecordQueries[
+    transition_class: OrderTransition,
+    initial_state: OrderStateMachine.initial_state,
+    transition_name: :transitions
+  ]
 end
 ```
 
@@ -375,7 +389,7 @@ Returns all models currently in any of the supplied states.
 Returns all models not currently in any of the supplied states.
 
 
-### `Model.most_recent_transition_join`
+#### `Model.most_recent_transition_join`
 This joins the model to its most recent transition whatever that may be.
 We expose this method to ease use of ActiveRecord's `or` e.g
 
@@ -425,6 +439,22 @@ class OrderStateMachine
 end
 ```
 
+#### Deleting records.
+
+If you need to delete the Parent model regularly you will need to change
+either the association deletion behaviour or add a `DELETE CASCADE` condition
+to foreign key in your database.
+
+E.g
+```
+has_many :order_transitions, autosave: false, dependent: :destroy
+```
+or when migrating the transition model
+```
+add_foreign_key :order_transitions, :orders, on_delete: :cascade
+```
+
+
 ## Testing Statesman Implementations
 
 This answer was abstracted from [this issue](https://github.com/gocardless/statesman/issues/77).

data/Rakefile

@@ -4,10 +4,6 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec) do |task|
   task.rspec_opts = []
 
-  if ENV["EXCLUDE_MONGOID"]
-    task.rspec_opts += ["--tag ~mongo", "--exclude-pattern **/*mongo*"]
-  end
-
   if ENV["CIRCLECI"]
     task.rspec_opts += ["--format RspecJunitFormatter",
                         "--out /tmp/test-results/rspec.xml",

data/lib/statesman.rb

@@ -12,9 +12,6 @@ module Statesman
              "statesman/adapters/active_record_transition"
     autoload :ActiveRecordQueries,
              "statesman/adapters/active_record_queries"
-    autoload :Mongoid, "statesman/adapters/mongoid"
-    autoload :MongoidTransition,
-             "statesman/adapters/mongoid_transition"
   end
   require "statesman/railtie" if defined?(::Rails::Railtie)
 

data/lib/statesman/adapters/active_record_queries.rb

@@ -1,51 +1,122 @@
 module Statesman
   module Adapters
     module ActiveRecordQueries
+      def self.check_missing_methods!(base)
+        missing_methods = %i[transition_class initial_state].
+          reject { |_method| base.respond_to?(:method) }
+        return if missing_methods.none?
+
+        raise NotImplementedError,
+              "#{missing_methods.join(', ')} method(s) should be defined on " \
+              "the model. Alternatively, use the new form of `extend " \
+              "Statesman::Adapters::ActiveRecordQueries[" \
+              "transition_class: MyTransition, " \
+              "initial_state: :some_state]`"
+      end
+
       def self.included(base)
-        base.extend(ClassMethods)
+        check_missing_methods!(base)
+
+        base.include(
+          ClassMethods.new(
+            transition_class: base.transition_class,
+            initial_state: base.initial_state,
+            most_recent_transition_alias: base.try(:most_recent_transition_alias),
+            transition_name: base.try(:transition_name),
+          ),
+        )
       end
 
-      module ClassMethods
-        def in_state(*states)
-          states = states.flatten.map(&:to_s)
+      def self.[](**args)
+        ClassMethods.new(**args)
+      end
+
+      class ClassMethods < Module
+        def initialize(**args)
+          @args = args
+        end
+
+        def included(base)
+          ensure_inheritance(base)
+
+          query_builder = QueryBuilder.new(base, **@args)
+
+          base.define_singleton_method(:most_recent_transition_join) do
+            query_builder.most_recent_transition_join
+          end
+
+          define_in_state(base, query_builder)
+          define_not_in_state(base, query_builder)
+        end
 
-          joins(most_recent_transition_join).
-            where(states_where(most_recent_transition_alias, states), states)
+        private
+
+        def ensure_inheritance(base)
+          klass = self
+          existing_inherited = base.method(:inherited)
+          base.define_singleton_method(:inherited) do |subclass|
+            existing_inherited.call(subclass)
+            subclass.send(:include, klass)
+          end
         end
 
-        def not_in_state(*states)
-          states = states.flatten.map(&:to_s)
+        def define_in_state(base, query_builder)
+          base.define_singleton_method(:in_state) do |*states|
+            states = states.flatten.map(&:to_s)
 
-          joins(most_recent_transition_join).
-            where("NOT (#{states_where(most_recent_transition_alias, states)})",
-                  states)
+            joins(most_recent_transition_join).
+              where(query_builder.states_where(states), states)
+          end
+        end
+
+        def define_not_in_state(base, query_builder)
+          base.define_singleton_method(:not_in_state) do |*states|
+            states = states.flatten.map(&:to_s)
+
+            joins(most_recent_transition_join).
+              where("NOT (#{query_builder.states_where(states)})", states)
+          end
+        end
+      end
+
+      class QueryBuilder
+        def initialize(model, transition_class:, initial_state:,
+                       most_recent_transition_alias: nil,
+                       transition_name: nil)
+          @model = model
+          @transition_class = transition_class
+          @initial_state = initial_state
+          @most_recent_transition_alias = most_recent_transition_alias
+          @transition_name = transition_name
+        end
+
+        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"
+          else
+            "#{most_recent_transition_alias}.to_state IN (?) AND " \
+            "#{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 #{table_name}.id =
+             ON #{model.table_name}.id =
                   #{most_recent_transition_alias}.#{model_foreign_key}
              AND #{most_recent_transition_alias}.most_recent = #{db_true}"
         end
 
         private
 
-        def transition_class
-          raise NotImplementedError, "A transition_class method should be " \
-                                     "defined on the model"
-        end
-
-        def initial_state
-          raise NotImplementedError, "An initial_state method should be " \
-                                     "defined on the model"
-        end
+        attr_reader :model, :transition_class, :initial_state
 
         def transition_name
-          transition_class.table_name.to_sym
+          @transition_name || transition_class.table_name.to_sym
         end
 
         def transition_reflection
-          reflect_on_all_associations(:has_many).each do |value|
+          model.reflect_on_all_associations(:has_many).each do |value|
             return value if value.klass == transition_class
           end
 
@@ -62,18 +133,9 @@ module Statesman
           transition_reflection.table_name
         end
 
-        def states_where(temporary_table_name, states)
-          if initial_state.to_s.in?(states.map(&:to_s))
-            "#{temporary_table_name}.to_state IN (?) OR " \
-            "#{temporary_table_name}.to_state IS NULL"
-          else
-            "#{temporary_table_name}.to_state IN (?) AND " \
-            "#{temporary_table_name}.to_state IS NOT NULL"
-          end
-        end
-
         def most_recent_transition_alias
-          "most_recent_#{transition_name.to_s.singularize}"
+          @most_recent_transition_alias ||
+            "most_recent_#{transition_name.to_s.singularize}"
         end
 
         def db_true