statesman 3.0.0 → 3.1.0

data/CONTRIBUTING.md

@@ -1,13 +1,6 @@
 Thanks for taking an interest in contributing to Statesman, here are a few
 ways you can help make this project better!
 
-# Contribute.md
-
-## Team members
-
-- [Andy Appleton](https://twitter.com/appltn)
-- [Harry Marr](https://twitter.com/harrymarr)
-
 ## Contributing
 
 - Generally we welcome new features but please first open an issue where we 

data/Gemfile

@@ -2,7 +2,7 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem "rails", "~> #{ENV["RAILS_VERSION"]}" if ENV["RAILS_VERSION"]
+gem "rails", "~> #{ENV['RAILS_VERSION']}" if ENV["RAILS_VERSION"]
 
 group :development do
   gem "mongoid", ">= 3.1" unless ENV["EXCLUDE_MONGOID"]

data/Guardfile

@@ -4,11 +4,11 @@
 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" }
+  watch('spec/spec_helper.rb') { "spec" }
 end
 
 guard :rubocop, all_on_start: true, cli: ['--format', 'clang'] do
-  watch(%r{.+\.rb$})
+  watch(/.+\.rb$/)
   watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
   watch(%r{(?:.+/)?\rubocop-todo\.yml$}) { |m| File.dirname(m[0]) }
 end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Harry Marr
+Copyright (c) 2013-2017 GoCardless
 
 MIT License
 

data/README.md

@@ -5,7 +5,7 @@ A statesmanlike state machine library.
 For our policy on compatibility with Ruby and Rails versions, see [COMPATIBILITY.md](docs/COMPATIBILITY.md).
 
 [![Gem Version](https://badge.fury.io/rb/statesman.svg)](http://badge.fury.io/rb/statesman)
-[![Build Status](https://travis-ci.org/gocardless/statesman.svg?branch=master)](https://travis-ci.org/gocardless/statesman)
+[![CircleCI](https://circleci.com/gh/gocardless/statesman.svg?style=svg)](https://circleci.com/gh/gocardless/statesman)
 [![Code Climate](https://codeclimate.com/github/gocardless/statesman.svg)](https://codeclimate.com/github/gocardless/statesman)
 [![Gitter](https://badges.gitter.im/join.svg)](https://gitter.im/gocardless/statesman?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
@@ -24,13 +24,19 @@ include JSON metadata set during a transition.
 - Database indices are used to offer database-level transaction duplication
 protection.
 
-## TL;DR Usage
+## Installation
+
+To get started, just add Statesman to your `Gemfile`, and then run `bundle`:
 
 ```ruby
+gem 'statesman', '~> 3.1.0'
+```
+
+## Usage
 
-#######################
-# State Machine Class #
-#######################
+First, create a state machine based on `Statesman::Machine`:
+
+```ruby
 class OrderStateMachine
   include Statesman::Machine
 
@@ -63,10 +69,11 @@ class OrderStateMachine
     MailerService.order_confirmation(order).deliver
   end
 end
+```
+
+Then, link it to your model:
 
-##############
-# Your Model #
-##############
+```ruby
 class Order < ActiveRecord::Base
   include Statesman::Adapters::ActiveRecordQueries
 
@@ -85,19 +92,20 @@ class Order < ActiveRecord::Base
   end
   private_class_method :initial_state
 end
+```
 
-####################
-# Transition Model #
-####################
+Next, you'll need to create a further model to represent state transitions:
+
+```ruby
 class OrderTransition < ActiveRecord::Base
   include Statesman::Adapters::ActiveRecordTransition
 
   belongs_to :order, inverse_of: :order_transitions
 end
 
-########################
-# Example method calls #
-########################
+Now, you can start working with your state machine:
+
+```ruby
 Order.first.state_machine.current_state # => "pending"
 Order.first.state_machine.allowed_transitions # => ["checking_out", "cancelled"]
 Order.first.state_machine.can_transition_to?(:cancelled) # => true/false
@@ -106,7 +114,6 @@ Order.first.state_machine.transition_to!(:cancelled) # => true/exception
 
 Order.in_state(:cancelled) # => [#<Order id: "123">]
 Order.not_in_state(:checking_out) # => [#<Order id: "123">]
-
 ```
 
 ## Persistence
@@ -254,6 +261,22 @@ 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).
 
+#### `Machine.states`
+Returns an array of all possible state names as strings.
+
+#### `Machine.successors`
+Returns a hash of states and the states it is valid for them to transition to.
+```ruby
+Machine.successors
+
+{
+  "pending" => ["checking_out", "cancelled"],
+  "checking_out" => ["purchased", "cancelled"],
+  "purchased" => ["shipped", "failed"],
+  "shipped" => ["refunded"]
+}
+```
+
 ## Instance methods
 
 #### `Machine#current_state`

data/Rakefile

@@ -2,8 +2,16 @@ require "bundler/gem_tasks"
 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*"
+    task.rspec_opts += ["--tag ~mongo", "--exclude-pattern **/*mongo*"]
+  end
+
+  if ENV["CIRCLECI"]
+    task.rspec_opts += ["--format RspecJunitFormatter",
+                        "--out /tmp/test-results/rspec.xml",
+                        "--format progress"]
   end
 end
 

data/lib/generators/statesman/active_record_transition_generator.rb

@@ -23,9 +23,5 @@ module Statesman
     def migration_file_name
       "db/migrate/#{next_migration_number}_create_#{table_name}.rb"
     end
-
-    def rails_4_or_higher?
-      Rails.version.split(".").map(&:to_i).first >= 4
-    end
   end
 end

data/lib/generators/statesman/generator_helpers.rb

@@ -44,5 +44,9 @@ module Statesman
     def database_supports_partial_indexes?
       Statesman::Adapters::ActiveRecord.database_supports_partial_indexes?
     end
+
+    def metadata_default_value
+      Utils.rails_5_or_higher? ? "{}" : "{}".inspect
+    end
   end
 end

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

@@ -1,7 +1,7 @@
-class <%= klass %> < ActiveRecord::Base
+class <%= klass %> < <%= Statesman::Utils.rails_5_or_higher? ? 'ApplicationRecord' : 'ActiveRecord::Base' %>
   include Statesman::Adapters::ActiveRecordTransition
 
-<%- unless rails_4_or_higher? -%>
+<%- unless Statesman::Utils.rails_4_or_higher? -%>
   attr_accessible :to_state, :metadata, :sort_key
 
 <%- end -%>

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

@@ -1,8 +1,8 @@
-class Create<%= migration_class_name %> < ActiveRecord::Migration
+class Create<%= migration_class_name %> < ActiveRecord::Migration<%= "[#{ActiveRecord::Migration.current_version}]" if Statesman::Utils.rails_5_or_higher? %>
   def change
     create_table :<%= table_name %> do |t|
       t.string :to_state, null: false
-      t.text :metadata<%= ", default: \"{}\"" unless mysql? %>
+      t.text :metadata<%= ", default: #{metadata_default_value}" unless mysql? %>
       t.integer :sort_key, null: false
       t.integer :<%= parent_id %>, null: false
       t.boolean :most_recent<%= ", null: false" if database_supports_partial_indexes? %>

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

@@ -1,7 +1,7 @@
-class AddStatesmanTo<%= migration_class_name %> < ActiveRecord::Migration
+class AddStatesmanTo<%= migration_class_name %> < ActiveRecord::Migration<%= "[#{ActiveRecord::Migration.current_version}]" if Statesman::Utils.rails_5_or_higher? %>
   def change
     add_column :<%= table_name %>, :to_state, :string, null: false
-    add_column :<%= table_name %>, :metadata, :text<%= ", default: \"{}\"" unless mysql? %>
+    add_column :<%= table_name %>, :metadata, :text<%= ", default: #{metadata_default_value}" unless mysql? %>
     add_column :<%= table_name %>, :sort_key, :integer, null: false
     add_column :<%= table_name %>, :<%= parent_id %>, :integer, null: false
     add_column :<%= table_name %>, :most_recent, null: false

data/lib/statesman.rb

@@ -3,6 +3,7 @@ module Statesman
   autoload :Machine,    'statesman/machine'
   autoload :Callback,   'statesman/callback'
   autoload :Guard,      'statesman/guard'
+  autoload :Utils,      'statesman/utils'
   autoload :Version,    'statesman/version'
   module Adapters
     autoload :Memory,       "statesman/adapters/memory"
@@ -11,7 +12,7 @@ module Statesman
              "statesman/adapters/active_record_transition"
     autoload :ActiveRecordQueries,
              "statesman/adapters/active_record_queries"
-    autoload :Mongoid,      "statesman/adapters/mongoid"
+    autoload :Mongoid, "statesman/adapters/mongoid"
     autoload :MongoidTransition,
              "statesman/adapters/mongoid_transition"
   end

data/lib/statesman/adapters/active_record.rb

@@ -6,7 +6,7 @@ module Statesman
       attr_reader :transition_class
       attr_reader :parent_model
 
-      JSON_COLUMN_TYPES = %w(json jsonb).freeze
+      JSON_COLUMN_TYPES = %w[json jsonb].freeze
 
       def self.database_supports_partial_indexes?
         # Rails 3 doesn't implement `supports_partial_index?`
@@ -66,7 +66,7 @@ module Statesman
                                   sort_key: next_sort_key,
                                   metadata: metadata }
 
-        transition_attributes.merge!(most_recent: true)
+        transition_attributes[:most_recent] = true
 
         transition = transitions_for_parent.build(transition_attributes)
 

data/lib/statesman/config.rb

@@ -9,7 +9,6 @@ module Statesman
       instance_eval(&block) unless block.nil?
     end
 
-    # rubocop:disable TrivialAccessors
     def storage_adapter(adapter_class)
       @adapter_class = adapter_class
     end

data/lib/statesman/machine.rb

@@ -175,7 +175,8 @@ module Statesman
       @object = object
       @transition_class = options[:transition_class]
       @storage_adapter = adapter_class(@transition_class).new(
-        @transition_class, object, self, options)
+        @transition_class, object, self, options
+      )
       send(:after_initialize) if respond_to? :after_initialize
     end
 
@@ -230,7 +231,7 @@ module Statesman
     end
 
     def transition_to(new_state, metadata = {})
-      self.transition_to!(new_state, metadata)
+      transition_to!(new_state, metadata)
     rescue TransitionFailedError, GuardFailedError
       false
     end

data/lib/statesman/utils.rb

@@ -0,0 +1,15 @@
+module Statesman
+  module Utils
+    def self.rails_major_version
+      Rails.version.split(".").map(&:to_i).first
+    end
+
+    def self.rails_5_or_higher?
+      rails_major_version >= 5
+    end
+
+    def self.rails_4_or_higher?
+      rails_major_version >= 4
+    end
+  end
+end

data/lib/statesman/version.rb

@@ -1,3 +1,3 @@
 module Statesman
-  VERSION = "3.0.0"
+  VERSION = "3.1.0".freeze
 end

data/spec/generators/statesman/active_record_transition_generator_spec.rb

@@ -11,7 +11,7 @@ describe Statesman::ActiveRecordTransitionGenerator, type: :generator do
     subject { file("db/migrate/#{time}_create_bacon_transitions.rb") }
 
     before { allow(Time).to receive(:now).and_return(mock_time) }
-    before { run_generator %w(Yummy::Bacon Yummy::BaconTransition) }
+    before { run_generator %w[Yummy::Bacon Yummy::BaconTransition] }
 
     let(:mock_time) { double('Time', utc: double('UTCTime', strftime: time)) }
     let(:time) { '5678309' }
@@ -22,7 +22,7 @@ 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 { is_expected.to contain(/:bacon_transition/) }
@@ -31,7 +31,7 @@ describe Statesman::ActiveRecordTransitionGenerator, type: :generator do
   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 { is_expected.not_to contain(/class_name:/) }
@@ -39,7 +39,7 @@ describe Statesman::ActiveRecordTransitionGenerator, type: :generator do
   end
 
   describe "it doesn't create any double-spacing" 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 { is_expected.to_not contain(/\n\n\n/) }

data/spec/generators/statesman/migration_generator_spec.rb

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

data/spec/generators/statesman/mongoid_transition_generator_spec.rb

@@ -4,7 +4,7 @@ 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 { is_expected.not_to contain(%r{:yummy/bacon}) }
@@ -12,7 +12,7 @@ describe Statesman::MongoidTransitionGenerator, type: :generator do
   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 { is_expected.not_to contain(/class_name:/) }

data/spec/spec_helper.rb

@@ -67,14 +67,14 @@ RSpec.configure do |config|
   end
 
   config.before(:each, active_record: true) do
-    tables = %w(
+    tables = %w[
       my_active_record_models
       my_active_record_model_transitions
       my_namespace_my_active_record_models
       my_namespace_my_active_record_model_transitions
       other_active_record_models
       other_active_record_model_transitions
-    )
+    ]
     tables.each do |table_name|
       sql = "DROP TABLE IF EXISTS #{table_name};"
       ActiveRecord::Base.connection.execute(sql)

data/spec/statesman/adapters/active_record_queries_spec.rb

@@ -84,7 +84,7 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
     end
 
     context "given an array of states" do
-      subject { MyActiveRecordModel.in_state([:succeeded, :failed]) }
+      subject { MyActiveRecordModel.in_state(%i[succeeded failed]) }
 
       it { is_expected.to include model }
       it { is_expected.to include other_model }
@@ -117,7 +117,7 @@ describe Statesman::Adapters::ActiveRecordQueries, active_record: true do
     end
 
     context "given an array of states" do
-      subject { MyActiveRecordModel.not_in_state([:succeeded, :failed]) }
+      subject { MyActiveRecordModel.not_in_state(%i[succeeded failed]) }
       it do
         is_expected.to match_array([initial_state_model,
                                     returned_to_initial_model])

data/spec/statesman/adapters/active_record_spec.rb

@@ -123,7 +123,14 @@ describe Statesman::Adapters::ActiveRecord, active_record: true do
       end
 
       context "ActiveRecord::RecordNotUnique unrelated to this transition" do
-        let(:error) { ActiveRecord::RecordNotUnique.new("unrelated", nil) }
+        let(:error) do
+          if ::ActiveRecord.respond_to?(:gem_version) &&
+             ::ActiveRecord.gem_version >= Gem::Version.new('4.0.0')
+            ActiveRecord::RecordNotUnique.new("unrelated")
+          else
+            ActiveRecord::RecordNotUnique.new("unrelated", nil)
+          end
+        end
         it { is_expected.to raise_exception(ActiveRecord::RecordNotUnique) }
       end
 

data/spec/statesman/callback_spec.rb

@@ -70,7 +70,7 @@ describe Statesman::Callback do
 
     context "with any from value on the callback" do
       let(:callback) do
-        Statesman::Callback.new(to: [:y, :z], callback: cb_lambda)
+        Statesman::Callback.new(to: %i[y z], callback: cb_lambda)
       end
       let(:from) { :x }
 

data/spec/statesman/machine_spec.rb

@@ -7,7 +7,7 @@ describe Statesman::Machine do
   describe ".state" do
     before { machine.state(:x) }
     before { machine.state(:y) }
-    specify { expect(machine.states).to eq(%w(x y)) }
+    specify { expect(machine.states).to eq(%w[x y]) }
 
     context "initial" do
       before { machine.state(:x, initial: true) }
@@ -151,7 +151,7 @@ describe Statesman::Machine do
       it "records the transition" do
         machine.transition(from: :x, to: :y)
         machine.transition(from: :x, to: :z)
-        expect(machine.successors).to eq("x" => %w(y z))
+        expect(machine.successors).to eq("x" => %w[y z])
       end
     end
   end
@@ -208,7 +208,7 @@ describe Statesman::Machine do
         state :x, initial: true
         state :y
         state :z
-        transition from: :x, to: [:y, :z]
+        transition from: :x, to: %i[y z]
       end
     end
 
@@ -262,12 +262,12 @@ describe Statesman::Machine do
       end
 
       context "from a terminal state and to multiple states" do
-        let(:options) { { from: :y, to: [:x, :z] } }
+        let(:options) { { from: :y, to: %i[x z] } }
         it_behaves_like "fails", Statesman::InvalidTransitionError
       end
 
       context "to an initial state and other states" do
-        let(:options) { { from: nil, to: [:y, :x, :z] } }
+        let(:options) { { from: nil, to: %i[y x z] } }
         it_behaves_like "fails", Statesman::InvalidTransitionError
       end
     end
@@ -284,12 +284,12 @@ describe Statesman::Machine do
       end
 
       context "to several" do
-        let(:options) { { from: :x, to: [:y, :z] } }
+        let(:options) { { from: :x, to: %i[y z] } }
         it_behaves_like "adds callback"
       end
 
       context "from any to several" do
-        let(:options) { { from: nil, to: [:y, :z] } }
+        let(:options) { { from: nil, to: %i[y z] } }
         it_behaves_like "adds callback"
       end
     end
@@ -417,12 +417,12 @@ describe Statesman::Machine do
 
       context "when given an array" do
         context "when one of the states is the current state" do
-          subject { instance.in_state?([:x, :y]) }
+          subject { instance.in_state?(%i[x y]) }
           it { is_expected.to eq(true) }
         end
 
         context "when none of the states are the current state" do
-          subject { instance.in_state?([:x, :z]) }
+          subject { instance.in_state?(%i[x z]) }
           it { is_expected.to eq(false) }
         end
       end
@@ -435,7 +435,7 @@ describe Statesman::Machine do
         state :x, initial: true
         state :y
         state :z
-        transition from: :x, to: [:y, :z]
+        transition from: :x, to: %i[y z]
         transition from: :y, to: :z
       end
     end
@@ -444,7 +444,7 @@ describe Statesman::Machine do
     subject { instance.allowed_transitions }
 
     context "with multiple possible states" do
-      it { is_expected.to eq(%w(y z)) }
+      it { is_expected.to eq(%w[y z]) }
     end
 
     context "with one possible state" do