statesman 4.1.4 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7445e509f7b9bafc381522bfbdbedac811430da81375bb767472f92386218140
-  data.tar.gz: 176143a22965d91c30957bfa7744089947e4269046fac188b89550d737b7cbb8
+  metadata.gz: 5f79354b244926e7be655b02df501cfed437ab2da6e869ec8db35097bb5ef372
+  data.tar.gz: 2b6ad54a68b6bca463c00c9e09a83d2d2d9d47d984fad212da77b0b0fd8a18a9
 SHA512:
-  metadata.gz: afec82cb24e537055105b34d1468f55b4fc220d7dffe49627910fdc7be7e61fbeb044b2e36f53bb111a9c7aeab23cc77b7828c0ac8b3bba167ac461246becc40
-  data.tar.gz: d98cf49966c4bb635b98798b44ecab0e5ad77714c794580eeb13939cbff7ab7dfd308de8041e6b95a0a1b56e5e364813896ade88b50422a87ecb00b7294745c0
+  metadata.gz: e66962ac0dd871627bdf6c53c5282e140bd109c3fcd0ba2ebd25504c490e3ddf2050132aabdf143c35aff09330e229afe8ec57c7d7fc43552bcff8140f8f0fa0
+  data.tar.gz: 9e3fa636071bcd530b177e80bf1014071d38601da2076e5258ffed22f41eec388255db2b03b79710130624c5fb6c60009af511b76d478be718f5fc69a6f0e933

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## v5.0.0, 11th November 2019
+
+- Adds new syntax and restrictions to ActiveRecordQueries [PR#358](https://github.com/gocardless/statesman/pull/358). With the introduction of this, defining `self.transition_class` or `self.initial_state` is deprecated and will be removed in the next major release.
+
 ## v4.1.4, 11th November 2019
 
 - Reverts the breaking changes from [PR#358](https://github.com/gocardless/statesman/pull/358) & `v4.1.3` that where included in the last minor release. If you have changed your code to work with these changes `v5.0.0` will be a copy of `v4.1.3` with a bugfix applied.

data/README.md

@@ -30,7 +30,7 @@ protection.
 To get started, just add Statesman to your `Gemfile`, and then run `bundle`:
 
 ```ruby
-gem 'statesman', '~> 4.1.4'
+gem 'statesman', '~> 5.0.0'
 ```
 
 ## Usage
@@ -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
 ```
 
@@ -357,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.2 and below, these two options had to be defined as methods on the model,
+but 5.0.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 6.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
 ```
 

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 { |m| base.respond_to?(m) }
+        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

data/lib/statesman/version.rb

@@ -1,3 +1,3 @@
 module Statesman
-  VERSION = "4.1.4".freeze
+  VERSION = "5.0.0".freeze
 end

data/spec/statesman/adapters/active_record_queries_spec.rb

@@ -1,6 +1,17 @@
 require "spec_helper"
 
 describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
+  def configure_old(klass, transition_class)
+    klass.define_singleton_method(:transition_class) { transition_class }
+    klass.define_singleton_method(:initial_state) { :initial }
+    klass.send(:include, described_class)
+  end
+
+  def configure_new(klass, transition_class)
+    klass.send(:include, described_class[transition_class: transition_class,
+                                         initial_state: :initial])
+  end
+
   before do
     prepare_model_table
     prepare_transitions_table
@@ -8,32 +19,6 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
     prepare_other_transitions_table
 
     Statesman.configure { storage_adapter(Statesman::Adapters::ActiveRecord) }
-
-    MyActiveRecordModel.send(:include, Statesman::Adapters::ActiveRecordQueries)
-    MyActiveRecordModel.class_eval do
-      def self.transition_class
-        MyActiveRecordModelTransition
-      end
-
-      def self.initial_state
-        :initial
-      end
-    end
-
-    OtherActiveRecordModel.send(:include,
-                                Statesman::Adapters::ActiveRecordQueries)
-    OtherActiveRecordModel.class_eval do
-      def self.transition_class
-        OtherActiveRecordModelTransition
-      end
-
-      def self.initial_state
-        :initial
-      end
-    end
-
-    MyActiveRecordModel.send(:has_one, :other_active_record_model)
-    OtherActiveRecordModel.send(:belongs_to, :my_active_record_model)
   end
 
   after { Statesman.configure { storage_adapter(Statesman::Adapters::Memory) } }
@@ -59,105 +44,164 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
     model
   end
 
-  describe ".in_state" do
-    context "given a single state" do
-      subject { MyActiveRecordModel.in_state(:succeeded) }
+  shared_examples "testing methods" do
+    before do
+      if config_type == :old
+        configure_old(MyActiveRecordModel, MyActiveRecordModelTransition)
+        configure_old(OtherActiveRecordModel, OtherActiveRecordModelTransition)
+      elsif config_type == :new
+        configure_new(MyActiveRecordModel, MyActiveRecordModelTransition)
+        configure_new(OtherActiveRecordModel, OtherActiveRecordModelTransition)
+      else
+        raise "Unknown config type #{config_type}"
+      end
 
-      it { is_expected.to include model }
-      it { is_expected.to_not include other_model }
+      MyActiveRecordModel.send(:has_one, :other_active_record_model)
+      OtherActiveRecordModel.send(:belongs_to, :my_active_record_model)
     end
 
-    context "given multiple states" do
-      subject { MyActiveRecordModel.in_state(:succeeded, :failed) }
+    describe ".in_state" do
+      context "given a single state" do
+        subject { MyActiveRecordModel.in_state(:succeeded) }
 
-      it { is_expected.to include model }
-      it { is_expected.to include other_model }
-    end
+        it { is_expected.to include model }
+        it { is_expected.to_not include other_model }
+      end
 
-    context "given the initial state" do
-      subject { MyActiveRecordModel.in_state(:initial) }
+      context "given multiple states" do
+        subject { MyActiveRecordModel.in_state(:succeeded, :failed) }
 
-      it { is_expected.to include initial_state_model }
-      it { is_expected.to include returned_to_initial_model }
-    end
+        it { is_expected.to include model }
+        it { is_expected.to include other_model }
+      end
 
-    context "given an array of states" do
-      subject { MyActiveRecordModel.in_state(%i[succeeded failed]) }
+      context "given the initial state" do
+        subject { MyActiveRecordModel.in_state(:initial) }
 
-      it { is_expected.to include model }
-      it { is_expected.to include other_model }
-    end
+        it { is_expected.to include initial_state_model }
+        it { is_expected.to include returned_to_initial_model }
+      end
+
+      context "given an array of states" do
+        subject { MyActiveRecordModel.in_state(%i[succeeded failed]) }
 
-    context "merging two queries" do
-      subject do
-        MyActiveRecordModel.in_state(:succeeded).
-          joins(:other_active_record_model).
-          merge(OtherActiveRecordModel.in_state(:initial))
+        it { is_expected.to include model }
+        it { is_expected.to include other_model }
       end
 
-      it { is_expected.to be_empty }
+      context "merging two queries" do
+        subject do
+          MyActiveRecordModel.in_state(:succeeded).
+            joins(:other_active_record_model).
+            merge(OtherActiveRecordModel.in_state(:initial))
+        end
+
+        it { is_expected.to be_empty }
+      end
     end
-  end
 
-  describe ".not_in_state" do
-    context "given a single state" do
-      subject { MyActiveRecordModel.not_in_state(:failed) }
+    describe ".not_in_state" do
+      context "given a single state" do
+        subject { MyActiveRecordModel.not_in_state(:failed) }
 
-      it { is_expected.to include model }
-      it { is_expected.to_not include other_model }
-    end
+        it { is_expected.to include model }
+        it { is_expected.to_not include other_model }
+      end
 
-    context "given multiple states" do
-      subject(:not_in_state) { MyActiveRecordModel.not_in_state(:succeeded, :failed) }
+      context "given multiple states" do
+        subject(:not_in_state) { MyActiveRecordModel.not_in_state(:succeeded, :failed) }
 
-      it do
-        expect(not_in_state).to match_array([initial_state_model,
-                                             returned_to_initial_model])
+        it do
+          expect(not_in_state).to match_array([initial_state_model,
+                                               returned_to_initial_model])
+        end
       end
-    end
 
-    context "given an array of states" do
-      subject(:not_in_state) { MyActiveRecordModel.not_in_state(%i[succeeded failed]) }
+      context "given an array of states" do
+        subject(:not_in_state) { MyActiveRecordModel.not_in_state(%i[succeeded failed]) }
 
-      it do
-        expect(not_in_state).to match_array([initial_state_model,
-                                             returned_to_initial_model])
+        it do
+          expect(not_in_state).to match_array([initial_state_model,
+                                               returned_to_initial_model])
+        end
       end
     end
-  end
 
-  context "with a custom name for the transition association" do
-    before do
-      # Switch to using OtherActiveRecordModelTransition, so the existing
-      # relation with MyActiveRecordModelTransition doesn't interfere with
-      # this spec.
-      MyActiveRecordModel.send(:has_many,
-                               :custom_name,
-                               class_name: "OtherActiveRecordModelTransition")
-
-      MyActiveRecordModel.class_eval do
-        def self.transition_class
-          OtherActiveRecordModelTransition
+    context "with a custom name for the transition association" do
+      before do
+        # Switch to using OtherActiveRecordModelTransition, so the existing
+        # relation with MyActiveRecordModelTransition doesn't interfere with
+        # this spec.
+        MyActiveRecordModel.send(:has_many,
+                                 :custom_name,
+                                 class_name: "OtherActiveRecordModelTransition")
+
+        MyActiveRecordModel.class_eval do
+          def self.transition_class
+            OtherActiveRecordModelTransition
+          end
         end
       end
+
+      describe ".in_state" do
+        subject(:query) { MyActiveRecordModel.in_state(:succeeded) }
+
+        specify { expect { query }.to_not raise_error }
+      end
     end
 
-    describe ".in_state" do
-      subject(:query) { MyActiveRecordModel.in_state(:succeeded) }
+    context "after_commit transactional integrity" do
+      before do
+        MyStateMachine.class_eval do
+          cattr_accessor(:after_commit_callback_executed) { false }
+
+          after_transition(from: :initial, to: :succeeded, after_commit: true) do
+            # This leaks state in a testable way if transactional integrity is broken.
+            MyStateMachine.after_commit_callback_executed = true
+          end
+        end
+      end
+
+      after do
+        MyStateMachine.class_eval do
+          callbacks[:after_commit] = []
+        end
+      end
+
+      let!(:model) do
+        MyActiveRecordModel.create
+      end
 
-      specify { expect { query }.to_not raise_error }
+      # rubocop:disable RSpec/ExampleLength
+      it do
+        expect do
+          ActiveRecord::Base.transaction do
+            model.state_machine.transition_to!(:succeeded)
+            raise ActiveRecord::Rollback
+          end
+        end.to_not change(MyStateMachine, :after_commit_callback_executed)
+      end
+      # rubocop:enable RSpec/ExampleLength
     end
   end
 
+  context "using old configuration method" do
+    let(:config_type) { :old }
+
+    include_examples "testing methods"
+  end
+
+  context "using new configuration method" do
+    let(:config_type) { :new }
+
+    include_examples "testing methods"
+  end
+
   context "with no association with the transition class" do
     before do
       class UnknownModelTransition < OtherActiveRecordModelTransition; end
 
-      MyActiveRecordModel.class_eval do
-        def self.transition_class
-          UnknownModelTransition
-        end
-      end
+      configure_old(MyActiveRecordModel, UnknownModelTransition)
     end
 
     describe ".in_state" do
@@ -169,37 +213,31 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
     end
   end
 
-  context "after_commit transactional integrity" do
-    before do
-      MyStateMachine.class_eval do
-        cattr_accessor(:after_commit_callback_executed) { false }
+  describe "check_missing_methods!" do
+    subject(:check_missing_methods!) { described_class.check_missing_methods!(base) }
 
-        after_transition(from: :initial, to: :succeeded, after_commit: true) do
-          # This leaks state in a testable way if transactional integrity is broken.
-          MyStateMachine.after_commit_callback_executed = true
+    context "when base has no missing methods" do
+      let(:base) do
+        Class.new do
+          def self.transition_class; end
+
+          def self.initial_state; end
         end
       end
-    end
 
-    after do
-      MyStateMachine.class_eval do
-        callbacks[:after_commit] = []
+      it "does not raise an error" do
+        expect { check_missing_methods! }.to_not raise_exception(NotImplementedError)
       end
     end
 
-    let!(:model) do
-      MyActiveRecordModel.create
-    end
+    context "when base has missing methods" do
+      let(:base) do
+        Class.new
+      end
 
-    # rubocop:disable RSpec/ExampleLength
-    it do
-      expect do
-        ActiveRecord::Base.transaction do
-          model.state_machine.transition_to!(:succeeded)
-          raise ActiveRecord::Rollback
-        end
-      end.to_not change(MyStateMachine, :after_commit_callback_executed)
+      it "raises an error" do
+        expect { check_missing_methods! }.to raise_exception(NotImplementedError)
+      end
     end
-    # rubocop:enable RSpec/ExampleLength
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 4.1.4
+  version: 5.0.0
 platform: ruby
 authors:
 - GoCardless