statesman 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b7adec92ffe517ecf4227b1190dcf1289abce8fe
-  data.tar.gz: 2f5876f6d294df4f2d52272c473d5c4521884d1d
+  metadata.gz: dc520c4907fb1573b7682bd1db4affe787b1d036
+  data.tar.gz: 796e3a0482fc5814b9ae9da4ec870dc97d43b851
 SHA512:
-  metadata.gz: 9e9be2c9b771cbd4f2d19b7de27854f047659c33deb6907af3b38bb8130feda521f9faf22ffe7560dc01fed63390ab569aae6b8fe3469e1d4159efba430ba428
-  data.tar.gz: e4e509269a3fd7adcfc3cfa15be27cef5d5e36e8e04fea8acf3c1fb6cef213ed3d91174c0efee5985eb691ec15ab59d105579769e651b4e1ca1d6546eb2cdc99
+  metadata.gz: 3ae6ba2af2f37b4df09d025d2bdfce5849aba5ba3e23a3d7c341061db4ad8002547177302a155b29c2770bc58d5b0988c1df2854e186a36d0236f9d5f0ca96e9
+  data.tar.gz: 57d5ab47d228ae72de01cff8e9b03db86bdb755bb70b8231a5f7639d7d45320fc647587061c76053353c4d56004a3dbefa8a52045e4bbd6e6175bc58fbc69cc3

data/.travis.yml

@@ -1,6 +1,7 @@
 language: ruby
 
 rvm:
+  - 2.2
   - 2.1
   - 2.0.0
   - 1.9.3

data/CHANGELOG.md

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

data/Gemfile

@@ -3,3 +3,8 @@ source 'https://rubygems.org'
 gemspec
 
 gem "rails", "~> #{ENV["RAILS_VERSION"]}" if ENV["RAILS_VERSION"]
+
+# test/unit is no longer bundled with Ruby 2.2, but required by Rails
+if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.2.0")
+  gem "test-unit", "~> 3.0"
+end

data/README.md

@@ -1,26 +1,34 @@
 ![Statesman](http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png)
 
-A statesmanlike state machine library for Ruby 1.9.3 and 2.0.
+A statesmanlike state machine library for Ruby 1.9.3 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)
 [![Code Climate](https://codeclimate.com/github/gocardless/statesman.png)](https://codeclimate.com/github/gocardless/statesman)
 [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/gocardless/statesman?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-
-Statesman is a little different from other state machine libraries which tack
-state behaviour directly onto a model. A statesman state machine is defined as a
-separate class which is instantiated with the model to which it should
-apply. State transitions are also modelled as a class which can optionally be
-persisted to the database for a full audit history, including JSON metadata
-which can be set during a transition.
-
-This data model allows for interesting things like using a different state
-machine depending on the value of a model attribute.
+Statesman is an opinionated state machine library designed to provide a robust
+audit trail and data integrity. It decouples the state machine logic from the
+underlying model and allows for easy composition with one or more model classes.
+
+As such, the design of statesman is a little different from other state machine
+libraries:
+- State behaviour is defined in a separate, "state machine" class, rather than
+added directly onto a model. State machines are then instantiated with the model
+to which they should apply.
+- State transitions are also modelled as a class, which can optionally be
+persisted to the database for a full audit history. This audit history can
+include JSON metadata set during a transition.
+- Database indicies are used to offer database-level transaction duplication
+protection.
 
 ## TL;DR Usage
 
 ```ruby
+
+#######################
+# State Machine Class #
+#######################
 class OrderStateMachine
   include Statesman::Machine
 
@@ -54,6 +62,9 @@ class OrderStateMachine
   end
 end
 
+##############
+# Your Model #
+##############
 class Order < ActiveRecord::Base
   include Statesman::Adapters::ActiveRecordQueries
 
@@ -74,96 +85,26 @@ class Order < ActiveRecord::Base
   end
 end
 
+####################
+# Transition Model #
+####################
 class OrderTransition < ActiveRecord::Base
   include Statesman::Adapters::ActiveRecordTransition
 
   belongs_to :order, inverse_of: :order_transitions
 end
 
-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
-
-Order.first.state_machine.transition_to(:cancelled, optional: :metadata)
-# => true/false
+########################
+# Example method calls #
+########################
+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
+Order.first.state_machine.transition_to(:cancelled, optional: :metadata) # => true/false
+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">]
-
-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]
+Order.in_state(:cancelled) # => [#<Order id: "123">]
+Order.not_in_state(:checking_out) # => [#<Order id: "123">]
 
 ```
 
@@ -222,14 +163,6 @@ It is also possible to use the PostgreSQL JSON column if you are using Rails 4.
 * Remove `include Statesman::Adapters::ActiveRecordTransition` statement from your
   transition model
 
-#### Creating transitions without using `#transition_to` with ActiveRecord
-
-By default, Statesman will include a `most_recent` column on the transitions
-table, and update its value each time `#transition_to` is called. If you create
-transitions manually (for example to backfill for a new state) you will need to
-set the `most_recent` attribute manually.
-
-
 ## Configuration
 
 #### `storage_adapter`
@@ -366,16 +299,17 @@ end
 ```
 
 #### `Model.in_state(:state_1, :state_2, etc)`
-Returns all models currently in any of the supplied states. Prior to 1.0 this ignored all models in the initial state, and the `initial_state` class method was not required.
+Returns all models currently in any of the supplied states.
 
 #### `Model.not_in_state(:state_1, :state_2, etc)`
-Returns all models not currently in any of the supplied states. Prior to 1.0 this always excluded models in the initial state, and the `initial_state` class method was not required.
+Returns all models not currently in any of the supplied states.
 
 ## Frequently Asked Questions
 
 #### Storing the state on the model object
 
-If you wish to store the model state on the model directly, you can keep it up to date using an `after_transition` hook:
+If you wish to store the model state on the model directly, you can keep it up
+to date using an `after_transition` hook:
 
 ```ruby
 after_transition do |model, transition|
@@ -394,6 +328,16 @@ 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
+
+Statesman 1.2.0 introduced a new `most_recent` column on the transition model,
+which is used to speed up queries.
+
+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.
+
 ## Testing Statesman Implementations
 
 This answer was abstracted from [this issue](https://github.com/gocardless/statesman/issues/77).

data/lib/statesman/adapters/active_record.rb

@@ -6,13 +6,15 @@ module Statesman
       attr_reader :transition_class
       attr_reader :parent_model
 
+      JSON_COLUMN_TYPES = %w(json jsonb).freeze
+
       def initialize(transition_class, parent_model, observer)
         serialized = serialized?(transition_class)
         column_type = transition_class.columns_hash['metadata'].sql_type
-        if !serialized && column_type != 'json'
+        if !serialized && !JSON_COLUMN_TYPES.include?(column_type)
           raise UnserializedMetadataError,
                 "#{transition_class.name}#metadata is not serialized"
-        elsif serialized && column_type == 'json'
+        elsif serialized && JSON_COLUMN_TYPES.include?(column_type)
           raise IncompatibleSerializationError,
                 "#{transition_class.name}#metadata column type cannot be json
                   and serialized simultaneously"

data/lib/statesman/version.rb

@@ -1,3 +1,3 @@
 module Statesman
-  VERSION = "1.2.0"
+  VERSION = "1.2.1"
 end

data/spec/statesman/adapters/active_record_spec.rb

@@ -64,6 +64,34 @@ describe Statesman::Adapters::ActiveRecord, active_record: true do
         end.to raise_exception(Statesman::IncompatibleSerializationError)
       end
     end
+
+    context "with serialized metadata and jsonb column type" do
+      before do
+        metadata_column = double
+        allow(metadata_column).to receive_messages(sql_type: 'jsonb')
+        allow(MyActiveRecordModelTransition).to receive_messages(columns_hash:
+                                           { 'metadata' => metadata_column })
+        if ::ActiveRecord.respond_to?(:gem_version) &&
+           ::ActiveRecord.gem_version >= Gem::Version.new('4.2.0.a')
+          serialized_type = ::ActiveRecord::Type::Serialized.new(
+            '', ::ActiveRecord::Coders::JSON
+          )
+          expect(metadata_column).
+            to receive(:cast_type).
+            and_return(serialized_type)
+        else
+          expect(MyActiveRecordModelTransition).
+            to receive_messages(serialized_attributes: { 'metadata' => '' })
+        end
+      end
+
+      it "raises an exception" do
+        expect do
+          described_class.new(MyActiveRecordModelTransition,
+                              MyActiveRecordModel, observer)
+        end.to raise_exception(Statesman::IncompatibleSerializationError)
+      end
+    end
   end
 
   describe "#create" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: statesman
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Harry Marr
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-18 00:00:00.000000000 Z
+date: 2015-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -283,7 +283,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.2
+rubygems_version: 2.4.1
 signing_key: 
 specification_version: 4
 summary: A statesmanlike state machine library