statesman 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 697717ea3c8a4b388c0b43a8777d9c1a18e147c1
-  data.tar.gz: 14051a4eacb2979013b8ff8e88698e9be6cff436
+  metadata.gz: 22f3c63fa8f737d3fbaef505d2329bd8e0ed1183
+  data.tar.gz: ef478f905d16dc128d8ddeaefbf52ccce0731938
 SHA512:
-  metadata.gz: 8fef4baf05db94227a2d3d9b2cbce8b7de0b0cc4eebacc6c3c04d879562b823c0903f8044ed36c2d0ba30443600ce7e04b1d109aa0fd4b501a85be51d2e640cc
-  data.tar.gz: 34deb50e48efc779d09ddff16b61afa90c7a36c263af58f8af8f1995ff8db1ca01a610e00182b9b11eed8d3a665b768c2d4c86dfeecd336e73e47efb90da53f0
+  metadata.gz: 810023ee4183eeb404a4ed5cee4d933d45590ab4eaf3a30864fb15181ac8d8de8e9ff0f7ed50a36ecad0e7414d303da750b824cd29d5984d95dfa3095eb93411
+  data.tar.gz: 0a83338cf2ab14661eef2fca42ee08511fc9e27538965e5b1213843492efd8bb24aa7bb442ae4b830917a87dba30dd581e434e5d70538054b08560ad6d41aac1

data/.rubocop.yml

@@ -1,10 +1,10 @@
 # For all options see https://github.com/bbatsov/rubocop/tree/master/config
 
 AllCops:
-  Includes:
+  Include:
     - Rakefile
     - statesman.gemfile
-  Excludes:
+  Exclude:
     - vendor/**
 
 StringLiterals:
@@ -30,3 +30,9 @@ Encoding:
 
 LineLength:
   Max: 80
+
+GuardClause:
+  Enabled: false
+
+SingleSpaceBeforeFirstArg:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 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
 *Additions*
 

data/Guardfile

@@ -1,7 +1,7 @@
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
-guard :rspec, cli: "--color", all_on_start: true do
+guard :rspec, all_on_start: true, cmd: 'bundle exec rspec --color' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec" }

data/README.md

@@ -96,6 +96,71 @@ Order.first.state_machine.transition_to!(:cancelled)
 # => true/exception
 ```
 
+## Events
+
+```ruby
+class TaskStateMachine
+  include Statesman::Machine
+
+  state :unstarted, initial: true
+  state :started
+  state :finished
+  state :delivered
+  state :accepted
+  state :rejected
+
+  event :start do
+    transition from: :unstarted,  to: :started
+  end
+
+  event :finish do
+    transition from: :started,    to: :finished
+  end
+
+  event :deliver do
+    transition from: :finished,   to: :delivered
+    transition from: :started,    to: :delivered
+  end
+
+  event :accept do
+    transition from: :delivered, to: :accepted
+  end
+
+  event :rejected do
+    transition from: :delivered, to: :rejected
+  end
+
+  event :restart do
+    transition from: :rejected,   to: :started
+  end
+
+end
+
+class Task < ActiveRecord::Base
+  delegate :current_state, :trigger!, :available_events, to: :state_machine
+
+  def state_machine
+    @state_machine ||= TaskStateMachine.new(self)
+  end
+
+end
+
+task = Task.new
+
+task.current_state
+# => "unstarted"
+
+task.trigger!(:start)
+# => true/exception
+
+task.current_state
+# => "started"
+
+task.available_events
+# => [:finish, :deliver]
+
+```
+
 ## Persistence
 
 By default Statesman stores transition history in memory only. It can be
@@ -209,6 +274,15 @@ Initialize a new state machine instance. `my_model` is required. If using the
 ActiveRecord adapter `my_model` should have a `has_many` association with
 `MyTransitionModel`.
 
+#### `Machine.retry_conflicts`
+```ruby
+Machine.retry_conflicts { instance.transition_to(:new_state) }
+```
+Automatically retry the given block if a `TransitionConflictError` is raised.
+If you know you want to retry a transition if it fails due to a race condition
+call it from within this block. Takes an (optional) argument for the maximum
+number of retry attempts (defaults to 1).
+
 ## Instance methods
 
 #### `Machine#current_state`
@@ -245,7 +319,7 @@ model and define a `transition_class` method.
 ```ruby
 class Order < ActiveRecord::Base
   include Statesman::Adapters::ActiveRecordModel
-  
+
   private
 
   def self.transition_class

data/circle.yml

@@ -1,6 +1,6 @@
 machine:
   ruby:
-    version: 2.0.0-p247
+    version: 2.0.0-p353
 test:
   pre:
     - bundle exec rubocop

data/lib/statesman/adapters/mongoid.rb

@@ -41,7 +41,7 @@ module Statesman
       private
 
       def transition_class_hash_fields
-        transition_class.fields.select { |k, v| v.type == Hash }.keys
+        transition_class.fields.select { |_, v| v.type == Hash }.keys
       end
 
       def metadata_field_error_message

data/lib/statesman/event_transitions.rb

@@ -0,0 +1,15 @@
+module Statesman
+  class EventTransitions
+    attr_reader :machine, :event_name
+
+    def initialize(machine, event_name, &block)
+      @machine    = machine
+      @event_name = event_name
+      instance_eval(&block)
+    end
+
+    def transition(options = { from: nil, to: nil })
+      machine.transition(options, event_name)
+    end
+  end
+end

data/lib/statesman/machine.rb

@@ -2,6 +2,7 @@ require_relative "version"
 require_relative "exceptions"
 require_relative "guard"
 require_relative "callback"
+require_relative "event_transitions"
 require_relative "adapters/memory_transition"
 
 module Statesman
@@ -12,6 +13,18 @@ module Statesman
       base.send(:attr_reader, :object)
     end
 
+    # Retry any transitions that fail due to a TransitionConflictError
+    def self.retry_conflicts(max_retries = 1)
+      retry_attempt = 0
+
+      begin
+        yield
+      rescue TransitionConflictError
+        retry_attempt += 1
+        retry_attempt <= max_retries ? retry : raise
+      end
+    end
+
     module ClassMethods
       attr_reader :initial_state
 
@@ -19,6 +32,10 @@ module Statesman
         @states ||= []
       end
 
+      def events
+        @events ||= {}
+      end
+
       def state(name, options = { initial: false })
         name = name.to_s
         if options[:initial]
@@ -28,6 +45,10 @@ module Statesman
         states << name
       end
 
+      def event(name, &block)
+        EventTransitions.new(self, name, &block)
+      end
+
       def successors
         @successors ||= {}
       end
@@ -41,7 +62,7 @@ module Statesman
         }
       end
 
-      def transition(options = { from: nil, to: nil })
+      def transition(options = { from: nil, to: nil }, event = nil)
         from = to_s_or_nil(options[:from])
         to = Array(options[:to]).map { |item| to_s_or_nil(item) }
 
@@ -50,6 +71,12 @@ 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)
@@ -189,6 +216,21 @@ module Statesman
       true
     end
 
+    def trigger!(event_name, metadata = nil)
+      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) }
@@ -200,6 +242,18 @@ module Statesman
       false
     end
 
+    def trigger(event_name, metadata = nil)
+      self.trigger!(event_name, metadata)
+    rescue TransitionFailedError, GuardFailedError
+      false
+    end
+
+    def available_events
+      self.class.events.select do |_, transitions|
+        transitions.key?(current_state)
+      end.map(&:first)
+    end
+
     private
 
     def adapter_class(transition_class)

data/lib/statesman/version.rb

@@ -1,3 +1,3 @@
 module Statesman
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/spec/generators/statesman/active_record_transition_generator_spec.rb

@@ -9,20 +9,20 @@ describe Statesman::ActiveRecordTransitionGenerator, type: :generator do
   end
 
   describe 'properly adds class names' do
-    before { run_generator %w[Yummy::Bacon Yummy::BaconTransition] }
+    before { run_generator %w(Yummy::Bacon Yummy::BaconTransition) }
     subject { file('app/models/yummy/bacon_transition.rb') }
 
-    it { should contain(/:bacon_transition/) }
-    it { should_not contain(/:yummy\/bacon/) }
-    it { should contain(/class_name: 'Yummy::Bacon'/) }
+    it { is_expected.to contain(/:bacon_transition/) }
+    it { is_expected.not_to contain(/:yummy\/bacon/) }
+    it { is_expected.to contain(/class_name: 'Yummy::Bacon'/) }
   end
 
   describe 'properly formats without class names' do
-    before { run_generator %w[Bacon BaconTransition] }
+    before { run_generator %w(Bacon BaconTransition) }
     subject { file('app/models/bacon_transition.rb') }
 
-    it { should_not contain(/class_name:/) }
-    it { should contain(/class BaconTransition/) }
+    it { is_expected.not_to contain(/class_name:/) }
+    it { is_expected.to contain(/class BaconTransition/) }
   end
 
 end

data/spec/generators/statesman/migration_generator_spec.rb

@@ -22,11 +22,11 @@ describe Statesman::MigrationGenerator, type: :generator do
     end
 
     before do
-      Time.stub(:now).and_return(mock_time)
-      run_generator %w[Yummy::Bacon Yummy::BaconTransition]
+      allow(Time).to receive(:now).and_return(mock_time)
+      run_generator %w(Yummy::Bacon Yummy::BaconTransition)
     end
 
-    it { should contain(/:bacon_transition/) }
-    it { should_not contain(/:yummy\/bacon/) }
+    it { is_expected.to contain(/:bacon_transition/) }
+    it { is_expected.not_to contain(/:yummy\/bacon/) }
   end
 end

data/spec/generators/statesman/mongoid_transition_generator_spec.rb

@@ -5,19 +5,19 @@ require "generators/statesman/mongoid_transition_generator"
 describe Statesman::MongoidTransitionGenerator, type: :generator do
 
   describe 'the model contains the correct words' do
-    before { run_generator %w[Yummy::Bacon Yummy::BaconTransition] }
+    before { run_generator %w(Yummy::Bacon Yummy::BaconTransition) }
     subject { file('app/models/yummy/bacon_transition.rb') }
 
-    it { should_not contain(/:yummy\/bacon/) }
-    it { should contain(/class_name: 'Yummy::Bacon'/) }
+    it { is_expected.not_to contain(/:yummy\/bacon/) }
+    it { is_expected.to contain(/class_name: 'Yummy::Bacon'/) }
   end
 
   describe 'the model contains the correct words' do
-    before { run_generator %w[Bacon BaconTransition] }
+    before { run_generator %w(Bacon BaconTransition) }
     subject { file('app/models/bacon_transition.rb') }
 
-    it { should_not contain(/class_name:/) }
-    it { should_not contain(/CreateYummy::Bacon/) }
+    it { is_expected.not_to contain(/class_name:/) }
+    it { is_expected.not_to contain(/CreateYummy::Bacon/) }
   end
 
 end

data/spec/spec_helper.rb

@@ -3,11 +3,11 @@ require "sqlite3"
 require "active_record"
 require "support/active_record"
 require "mongoid"
+require 'rspec/its'
 
 RSpec.configure do |config|
-  config.expect_with :rspec do |c|
-    c.syntax = :expect
-  end
+  config.raise_errors_for_deprecations!
+  config.mock_with(:rspec) { |mocks| mocks.verify_partial_doubles = true }
 
   config.order = "random"
 

data/spec/statesman/adapters/active_record_model_spec.rb

@@ -31,27 +31,27 @@ describe Statesman::Adapters::ActiveRecordModel do
     context "given a single state" do
       subject { MyActiveRecordModel.in_state(:state_a) }
 
-      it { should include model }
+      it { is_expected.to include model }
     end
 
     context "given multiple states" do
       subject { MyActiveRecordModel.in_state(:state_a, :state_b) }
 
-      it { should include model }
-      it { should include other_model }
+      it { is_expected.to include model }
+      it { is_expected.to include other_model }
     end
   end
 
   describe ".not_in_state" do
     context "given a single state" do
       subject { MyActiveRecordModel.not_in_state(:state_b) }
-      it { should include model }
-      it { should_not include other_model }
+      it { is_expected.to include model }
+      it { is_expected.not_to include other_model }
     end
 
     context "given multiple states" do
       subject { MyActiveRecordModel.not_in_state(:state_a, :state_b) }
-      it { should == [] }
+      it { is_expected.to eq([]) }
     end
   end
 end

data/spec/statesman/adapters/active_record_spec.rb

@@ -11,7 +11,7 @@ describe Statesman::Adapters::ActiveRecord do
   before { MyActiveRecordModelTransition.serialize(:metadata, JSON) }
   let(:observer) do
     result = double(Statesman::Machine)
-    result.stub(:execute)
+    allow(result).to receive(:execute)
     result
   end
   let(:model) { MyActiveRecordModel.create(current_state: :pending) }
@@ -21,10 +21,11 @@ describe Statesman::Adapters::ActiveRecord do
     context "with unserialized metadata and non json column type" do
       before do
         metadata_column = double
-        metadata_column.stub(sql_type: '')
-        MyActiveRecordModelTransition.stub(columns_hash:
+        allow(metadata_column).to receive_messages(sql_type: '')
+        allow(MyActiveRecordModelTransition).to receive_messages(columns_hash:
                                            { 'metadata' => metadata_column })
-        MyActiveRecordModelTransition.stub(serialized_attributes: {})
+        allow(MyActiveRecordModelTransition)
+          .to receive_messages(serialized_attributes: {})
       end
 
       it "raises an exception" do
@@ -38,11 +39,11 @@ describe Statesman::Adapters::ActiveRecord do
     context "with serialized metadata and json column type" do
       before do
         metadata_column = double
-        metadata_column.stub(sql_type: 'json')
-        MyActiveRecordModelTransition.stub(columns_hash:
+        allow(metadata_column).to receive_messages(sql_type: 'json')
+        allow(MyActiveRecordModelTransition).to receive_messages(columns_hash:
                                            { 'metadata' => metadata_column })
-        MyActiveRecordModelTransition.stub(serialized_attributes:
-                                           { 'metadata' => '' })
+        allow(MyActiveRecordModelTransition)
+          .to receive_messages(serialized_attributes: { 'metadata' => '' })
       end
 
       it "raises an exception" do
@@ -82,12 +83,12 @@ describe Statesman::Adapters::ActiveRecord do
 
       context "ActiveRecord::RecordNotUnique unrelated to this transition" do
         let(:error) { ActiveRecord::RecordNotUnique.new("unrelated", nil) }
-        it { should raise_exception(ActiveRecord::RecordNotUnique) }
+        it { is_expected.to raise_exception(ActiveRecord::RecordNotUnique) }
       end
 
       context "other errors" do
         let(:error) { StandardError }
-        it { should raise_exception(StandardError) }
+        it { is_expected.to raise_exception(StandardError) }
       end
     end
   end
@@ -107,8 +108,8 @@ describe Statesman::Adapters::ActiveRecord do
       end
 
       it "caches the transition" do
-        MyActiveRecordModel.any_instance
-          .should_receive(:my_active_record_model_transitions).never
+        expect_any_instance_of(MyActiveRecordModel)
+          .to receive(:my_active_record_model_transitions).never
         adapter.last
       end
 
@@ -127,7 +128,7 @@ describe Statesman::Adapters::ActiveRecord do
       end
 
       it "doesn't query the database" do
-        MyActiveRecordModelTransition.should_not_receive(:connection)
+        expect(MyActiveRecordModelTransition).not_to receive(:connection)
         expect(adapter.last.to_state).to eq("y")
       end
     end