statesman 1.3.1 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24961b58213c1edf11c804f50ef70a0eb690d0b8
-  data.tar.gz: 9817e2fb565978efbeb6f0a90c01f01b8541548a
+  metadata.gz: 13d0c38a0446c311aa3db3796688736d190a5643
+  data.tar.gz: e13b4b046fe10b8f5dbf07234145b9d75c0b74b0
 SHA512:
-  metadata.gz: 0f120a2a604f7e8cdad2927790d59eeb81dbd0459107601fe76f871bbf201dba53f5c5b1c4c15e90472a5a32d9ed3cd9aaed88f93e6d6cb1576bfb4cae594c0e
-  data.tar.gz: e387129df4c7ac6acb87bf5c7885b16548be3367bcf58f3480d702216c745ac997407548c654eb82eb2ed761cff212711966dd882daafb688638a74737003de9
+  metadata.gz: 5ff647a35fe9d98698eae14af6ea89af302d0766da3e6cc7c0a7d920be59fce95782524f19eb58f534f50d8ce4b734c26213642372b02770984454c85f799d43
+  data.tar.gz: 082b90d40ea27a482654bfd4d57d48ee089d6f26bd92633b594678bfa75ed9e2024e57ed8213714a2a255d3ec231a29e9326d05e2f94013f4b58a881273403dd

data/.travis.yml

@@ -4,7 +4,6 @@ rvm:
   - 2.2
   - 2.1
   - 2.0.0
-  - 1.9.3
 
 sudo: false
 

data/CHANGELOG.md

@@ -1,33 +1,59 @@
-## v1.3.1 2 July 2015
+## v2.0.0.rc1, 23 December 2015
+
+*Breaking changes*
+
+- Unset most_recent after before transitions
+  - TL;DR: set `autosave: false` on the `has_many` association between your parent and transition model and this change will almost certainly not affect your integration
+  - Previously the `most_recent` flag would be set to `false` on all transitions during any `before_transition` callbacks
+  - After this change, the `most_recent` flag will still be `true` for the previous transition during these callbacks
+  - Whilst this behaviour is almost certainly what your integration already expected, as a result of it any attempt to save the new, as yet unpersisted, transition during a `before_transition` callback will result in a uniqueness error. In particular, if you have not set `autosave: false` on the `has_many` association between your parent and transition model then any attempt to save the parent model during a `before_transition` will result in an error
+- Require a most_recent column on transition tables
+  - The `most_recent` column, added in v1.2.0, is now required on all transition tables
+  - This greatly speeds up queries on large tables
+  - A zero-downtime migration path is outlined in the changelog for v1.2.0. You should use that migration path **before** upgrading to v2.0.0
+- Increase default initial sort key to 10
+- Drop support for Ruby 1.9.3, which reached end-of-life in February 2015
+- Move support for events to a companion gem
+  - Previously, Statesman supported the use of "events" to trigger transitions
+  - To keep Statesman lightweight we've moved event functionality into the `statesman-events` gem
+  - If you are using events, add `statesman-events` to your gemfile and include `Statesman::Events` in your state machines
+
+*Changes*
+
+- Add after_destroy hook to ActiveRecord transition model templates
+- Add `in_state?` instance method to `Statesman::Machine`
+- Add `force_reload` option to `Statesman::Machine#last_transition`
+
+## v1.3.1, 2 July 2015
 
 - Fix `in_state` queries with a custom `transition_name` (patch by [0tsuki](https://github.com/0tsuki))
-- Fix `backfill_most_recent` rake tast for databases that support partial indexes (patch by [greysteil](https://github.com/greysteil))
+- Fix `backfill_most_recent` rake task for databases that support partial indexes (patch by [greysteil](https://github.com/greysteil))
 
-## v1.3.0 20 June 2015
+## v1.3.0, 20 June 2015
 
 - Rename `last_transition` alias in `ActiveRecordQueries` to `most_recent_#{model_name}`, to allow merging of two such queries (patch by [@isaacseymour](https://github.com/isaacseymour))
 
-## v1.2.5 17 June 2015
+## v1.2.5, 17 June 2015
 
 - Make `backfill_most_recent` rake task db-agnostic (patch by [@timothyp](https://github.com/timothyp))
 
-## v1.2.4 16 June 2015
+## v1.2.4, 16 June 2015
 
 - Clarify error messages when misusing `Statesman::Adapters::ActiveRecordTransition` (patch by [@isaacseymour](https://github.com/isaacseymour))
 
-## v1.2.3 14 April 2015
+## v1.2.3, 14 April 2015
 
 - Fix use of most_recent column in MySQL (partial indexes aren't supported) (patch by [@greysteil](https://github.com/greysteil))
 
-## v1.2.2 24 March 2015
+## v1.2.2, 24 March 2015
 
 - Add support for namespaced transition models (patch by [@DanielWright](https://github.com/DanielWright))
 
-## v1.2.1 24 March 2015
+## v1.2.1, 24 March 2015
 
 - Add support for Postgres 9.4's `jsonb` column type (patch by [@isaacseymour](https://github.com/isaacseymour))
 
-## v1.2.0 18 March 2015
+## v1.2.0, 18 March 2015
 
 *Changes*
 
@@ -41,7 +67,7 @@
 - `ActiveRecordQueries.{not_,}in_state` now accepts an array of states.
 
 
-## v1.1.0 9 December 2014
+## v1.1.0, 9 December 2014
 *Fixes*
 
 - Support for Rails 4.2.0.rc2:
@@ -53,16 +79,16 @@
 
 - Transition metadata now defaults to `{}` rather than `nil`. (patch by [@greysteil](https://github.com/greysteil))
 
-## v1.0.0 21 November 2014
+## v1.0.0, 21 November 2014
 
 No changes from v1.0.0.beta2
 
-## v1.0.0.beta2 10 October 2014
+## v1.0.0.beta2, 10 October 2014
 *Breaking changes*
 
 - Rename `ActiveRecordModel` to `ActiveRecordQueries`, to reflect the fact that it mixes in some helpful scopes, but is not required.
 
-## v1.0.0.beta1 9 October 2014
+## v1.0.0.beta1, 9 October 2014
 *Breaking changes*
 
 - Classes which include `ActiveRecordModel` must define an `initial_state` class method.
@@ -76,33 +102,33 @@ No changes from v1.0.0.beta2
 - Transition tables created by generated migrations have `NOT NULL` constraints on `to_state`, `sort_key` and foreign key columns (patch by [@greysteil](https://github.com/greysteil))
 - `before_transition` and `after_transition` allow an array of to states (patch by [@isaacseymour](https://github.com/isaacseymour))
 
-## v0.8.3 2 September 2014
+## v0.8.3, 2 September 2014
 *Fixes*
 
 - Optimisation for Machine#available_events (patch by [@pacso](https://github.com/pacso))
 
-## v0.8.2 2 September 2014
+## v0.8.2, 2 September 2014
 *Fixes*
 
 - Stop generating a default value for the metadata column if using MySQL.
 
-## v0.8.1 19 August 2014
+## v0.8.1, 19 August 2014
 *Fixes*
 
 - Adds check in Machine#transition to make sure the 'to' state is not an empty array (patch by [@barisbalic](https://github.com/barisbalic))
 
-## v0.8.0 29 June 2014
+## v0.8.0, 29 June 2014
 *Additions*
 
 - Events. Machines can now define events as a logical grouping of transitions (patch by [@iurimatias](https://github.com/iurimatias))
 - Retries. Individual transitions can be executed with a retry policy by wrapping the method call in a `Machine.retry_conflicts {}` block (patch by [@greysteil](https://github.com/greysteil))
 
-## v0.7.0 25 June 2014
+## v0.7.0, 25 June 2014
 *Additions*
 
 - `Adapters::ActiveRecord` now handles `ActiveRecord::RecordNotUnique` errors explicitly and re-raises with a `Statesman::TransitionConflictError` if it is due to duplicate sort_keys (patch by [@greysteil](https://github.com/greysteil))
 
-## v0.6.1 21 May 2014
+## v0.6.1, 21 May 2014
 *Fixes*
 - Fixes an issue where the wrong transition was passed to after_transition callbacks for the second and subsequent transition of a given state machine (patch by [@alan](https://github.com/alan))
 

data/README.md

@@ -1,6 +1,6 @@
 ![Statesman](http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png)
 
-A statesmanlike state machine library for Ruby 1.9.3 and up.
+A statesmanlike state machine library for Ruby 2.0.0 and up.
 
 [![Gem Version](https://badge.fury.io/rb/statesman.png)](http://badge.fury.io/rb/statesman)
 [![Build Status](https://travis-ci.org/gocardless/statesman.png?branch=master)](https://travis-ci.org/gocardless/statesman)
@@ -68,7 +68,7 @@ end
 class Order < ActiveRecord::Base
   include Statesman::Adapters::ActiveRecordQueries
 
-  has_many :order_transitions
+  has_many :order_transitions, autosave: false
 
   def state_machine
     @state_machine ||= OrderStateMachine.new(self, transition_class: OrderTransition)
@@ -134,7 +134,7 @@ And add an association from the parent model:
 
 ```ruby
 class Order < ActiveRecord::Base
-  has_many :transitions, class_name: "OrderTransition"
+  has_many :transitions, class_name: "OrderTransition", autosave: false
 
   # Initialize the state machine
   def state_machine
@@ -255,6 +255,9 @@ number of retry attempts (defaults to 1).
 #### `Machine#current_state`
 Returns the current state based on existing transition objects.
 
+### `Machine#in_state?(:state_1, :state_2, ...)`
+Returns true if the machine is in any of the given states.
+
 #### `Machine#history`
 Returns a sorted array of all transition objects.
 
@@ -304,7 +307,7 @@ need to define a corresponding `transition_name` class method:
 
 ```ruby
 class Order < ActiveRecord::Base
-  has_many :transitions, class_name: "OrderTransition"
+  has_many :transitions, class_name: "OrderTransition", autosave: false
 
   private
 
@@ -352,15 +355,21 @@ Given a field `foo` that was stored in the metadata, you can access it like so:
 model_instance.last_transition.metadata["foo"]
 ```
 
-#### Upgrading from 1.1 to 1.2
+#### Events
 
-Statesman 1.2.0 introduced a new `most_recent` column on the transition model,
-which is used to speed up queries.
+Used to using a state machine with "events"? Support for events is provided by
+the [statesman-events](https://github.com/gocardless/statesman-events) gem. Once
+that's included in your Gemfile you can include event functionality in your
+state machine as follows:
 
-The change is entirely backwards compatible, but if you'd like the performance
-improvements just follow
-[this guide](https://github.com/gocardless/statesman/wiki/Adding-a-%60most_recent%60-column-to-an-existing-model)
-to add a `most_recent` column to an existing model.
+```ruby
+class OrderStateMachine
+  include Statesman::Machine
+  include Statesman::Events
+
+  ...
+end
+```
 
 ## Testing Statesman Implementations
 

data/lib/generators/statesman/templates/active_record_transition_model.rb.erb

@@ -5,4 +5,14 @@ class <%= klass %> < ActiveRecord::Base
   attr_accessible :to_state, :metadata, :sort_key
 <% end %>
   belongs_to :<%= parent_name %><%= class_name_option %>, inverse_of: :<%= table_name %>
+
+  after_destroy :update_most_recent, if: :most_recent?
+
+  private
+
+  def update_most_recent
+    last_transition = <%= parent_name %>.<%= table_name %>.order(:sort_key).last
+    return unless last_transition.present?
+    last_transition.update_column(:most_recent, true)
+  end
 end

data/lib/statesman/adapters/active_record.rb

@@ -51,8 +51,12 @@ module Statesman
         end
       end
 
-      def last
-        @last_transition ||= history.last
+      def last(force_reload: false)
+        if force_reload
+          @last_transition = history.last
+        else
+          @last_transition ||= history.last
+        end
       end
 
       private
@@ -62,13 +66,13 @@ module Statesman
                                   sort_key: next_sort_key,
                                   metadata: metadata }
 
-        transition_attributes.merge!(most_recent: true) if most_recent_column?
+        transition_attributes.merge!(most_recent: true)
 
         transition = transitions_for_parent.build(transition_attributes)
 
         ::ActiveRecord::Base.transaction do
-          unset_old_most_recent
           @observer.execute(:before, from, to, transition)
+          unset_old_most_recent
           transition.save!
           @last_transition = transition
           @observer.execute(:after, from, to, transition)
@@ -83,7 +87,6 @@ module Statesman
       end
 
       def unset_old_most_recent
-        return unless most_recent_column?
         # Check whether the `most_recent` column allows null values. If it
         # doesn't, set old records to `false`, otherwise, set them to `NULL`.
         #
@@ -98,12 +101,8 @@ module Statesman
         end
       end
 
-      def most_recent_column?
-        transition_class.columns_hash.include?("most_recent")
-      end
-
       def next_sort_key
-        (last && last.sort_key + 10) || 0
+        (last && last.sort_key + 10) || 10
       end
 
       def serialized?(transition_class)

data/lib/statesman/adapters/active_record_queries.rb

@@ -9,50 +9,19 @@ module Statesman
         def in_state(*states)
           states = states.flatten.map(&:to_s)
 
-          if use_most_recent_column?
-            in_state_with_most_recent(states)
-          else
-            in_state_without_most_recent(states)
-          end
+          joins(most_recent_transition_join).
+            where(states_where(most_recent_transition_alias, states), states)
         end
 
         def not_in_state(*states)
           states = states.flatten.map(&:to_s)
 
-          if use_most_recent_column?
-            not_in_state_with_most_recent(states)
-          else
-            not_in_state_without_most_recent(states)
-          end
-        end
-
-        private
-
-        def in_state_with_most_recent(states)
-          joins(most_recent_transition_join).
-            where(states_where(most_recent_transition_alias, states), states)
-        end
-
-        def not_in_state_with_most_recent(states)
           joins(most_recent_transition_join).
             where("NOT (#{states_where(most_recent_transition_alias, states)})",
                   states)
         end
 
-        def in_state_without_most_recent(states)
-          joins(transition1_join).
-            joins(transition2_join).
-            where(states_where(most_recent_transition_alias, states), states).
-            where("#{other_transition_alias}.id" => nil)
-        end
-
-        def not_in_state_without_most_recent(states)
-          joins(transition1_join).
-            joins(transition2_join).
-            where("NOT (#{states_where(most_recent_transition_alias, states)})",
-                  states).
-            where("#{other_transition_alias}.id" => nil)
-        end
+        private
 
         def transition_class
           raise NotImplementedError, "A transition_class method should be " \
@@ -80,20 +49,6 @@ module Statesman
           transition_reflection.table_name
         end
 
-        def transition1_join
-          "LEFT OUTER JOIN #{model_table} #{most_recent_transition_alias}
-             ON #{most_recent_transition_alias}.#{model_foreign_key} =
-                  #{table_name}.id"
-        end
-
-        def transition2_join
-          "LEFT OUTER JOIN #{model_table} #{other_transition_alias}
-             ON #{other_transition_alias}.#{model_foreign_key} =
-                  #{table_name}.id
-             AND #{other_transition_alias}.sort_key >
-                   #{most_recent_transition_alias}.sort_key"
-        end
-
         def most_recent_transition_join
           "LEFT OUTER JOIN #{model_table} AS #{most_recent_transition_alias}
              ON #{table_name}.id =
@@ -115,24 +70,9 @@ module Statesman
           "most_recent_#{transition_name.to_s.singularize}"
         end
 
-        def other_transition_alias
-          "other_#{transition_name.to_s.singularize}"
-        end
-
         def db_true
           ::ActiveRecord::Base.connection.quote(true)
         end
-
-        # Only use the most_recent column if it has a unique index guaranteeing
-        # it has good data
-        def use_most_recent_column?
-          ::ActiveRecord::Base.connection.index_exists?(
-            transition_class.table_name,
-            [model_foreign_key, :most_recent],
-            unique: true,
-            name: "index_#{transition_class.table_name}_parent_most_recent"
-          )
-        end
       end
     end
   end

data/lib/statesman/adapters/memory.rb

@@ -28,14 +28,14 @@ module Statesman
         transition
       end
 
-      def last
+      def last(*)
         @history.sort_by(&:sort_key).last
       end
 
       private
 
       def next_sort_key
-        (last && last.sort_key + 10) || 0
+        (last && last.sort_key + 10) || 10
       end
     end
   end

data/lib/statesman/adapters/mongoid.rb

@@ -36,8 +36,12 @@ module Statesman
         transitions_for_parent.asc(:sort_key)
       end
 
-      def last
-        @last_transition ||= history.last
+      def last(force_reload: false)
+        if force_reload
+          @last_transition = history.last
+        else
+          @last_transition ||= history.last
+        end
       end
 
       private
@@ -55,7 +59,7 @@ module Statesman
       end
 
       def next_sort_key
-        (last && last.sort_key + 10) || 0
+        (last && last.sort_key + 10) || 10
       end
     end
   end

data/lib/statesman/machine.rb

@@ -2,7 +2,6 @@ require_relative "version"
 require_relative "exceptions"
 require_relative "guard"
 require_relative "callback"
-require_relative "event_transitions"
 require_relative "adapters/memory_transition"
 
 module Statesman
@@ -32,10 +31,6 @@ module Statesman
         @states ||= []
       end
 
-      def events
-        @events ||= {}
-      end
-
       def state(name, options = { initial: false })
         name = name.to_s
         if options[:initial]
@@ -45,10 +40,6 @@ module Statesman
         states << name
       end
 
-      def event(name, &block)
-        EventTransitions.new(self, name, &block)
-      end
-
       def successors
         @successors ||= {}
       end
@@ -62,9 +53,9 @@ module Statesman
         }
       end
 
-      def transition(options = { from: nil, to: nil }, event = nil)
-        from = to_s_or_nil(options[:from])
-        to = array_to_s_or_nil(options[:to])
+      def transition(from: nil, to: nil)
+        from = to_s_or_nil(from)
+        to = array_to_s_or_nil(to)
 
         raise InvalidStateError, "No to states provided." if to.empty?
 
@@ -73,12 +64,6 @@ module Statesman
         ([from] + to).each { |state| validate_state(state) }
 
         successors[from] += to
-
-        if event
-          events[event] ||= {}
-          events[event][from] ||= []
-          events[event][from] += to
-        end
       end
 
       def before_transition(options = { from: nil, to: nil }, &block)
@@ -177,9 +162,9 @@ module Statesman
     end
 
     def initialize(object,
-                      options = {
-                        transition_class: Statesman::Adapters::MemoryTransition
-                      })
+                   options = {
+                     transition_class: Statesman::Adapters::MemoryTransition
+                   })
       @object = object
       @transition_class = options[:transition_class]
       @storage_adapter = adapter_class(@transition_class).new(
@@ -187,19 +172,23 @@ module Statesman
       send(:after_initialize) if respond_to? :after_initialize
     end
 
-    def current_state
-      last_action = last_transition
+    def current_state(force_reload: false)
+      last_action = last_transition(force_reload: force_reload)
       last_action ? last_action.to_state : self.class.initial_state
     end
 
+    def in_state?(*states)
+      states.flatten.any? { |state| current_state == state.to_s }
+    end
+
     def allowed_transitions
       successors_for(current_state).select do |state|
         can_transition_to?(state)
       end
     end
 
-    def last_transition
-      @storage_adapter.last
+    def last_transition(force_reload: false)
+      @storage_adapter.last(force_reload: force_reload)
     end
 
     def can_transition_to?(new_state, metadata = {})
@@ -228,21 +217,6 @@ module Statesman
       true
     end
 
-    def trigger!(event_name, metadata = {})
-      transitions = self.class.events.fetch(event_name) do
-        raise Statesman::TransitionFailedError,
-              "Event #{event_name} not found"
-      end
-
-      new_state = transitions.fetch(current_state) do
-        raise Statesman::TransitionFailedError,
-              "State #{current_state} not found for Event #{event_name}"
-      end
-
-      transition_to!(new_state.first, metadata)
-      true
-    end
-
     def execute(phase, initial_state, new_state, transition)
       callbacks = callbacks_for(phase, from: initial_state, to: new_state)
       callbacks.each { |cb| cb.call(@object, transition) }
@@ -254,19 +228,6 @@ module Statesman
       false
     end
 
-    def trigger(event_name, metadata = {})
-      self.trigger!(event_name, metadata)
-    rescue TransitionFailedError, GuardFailedError
-      false
-    end
-
-    def available_events
-      state = current_state
-      self.class.events.select do |_, transitions|
-        transitions.key?(state)
-      end.map(&:first)
-    end
-
     private
 
     def adapter_class(transition_class)