statesman 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 76cf9c150c6ff65db2ce679c9894d577a97d0d1a
+  data.tar.gz: 9b5726a9af39ca123b63acea82970286debd2dd2
+SHA512:
+  metadata.gz: 23f5b5f680675e7b58f573295c9fc30aa00a150df0190afcbd0392b4b56cf0ebe90cef0405f07dc30b9d9c7ab574f5533e88a382d4d5548486906252356620f3
+  data.tar.gz: 6869fd521815f23be8e74575e57c83dba70b5b4c5d036c2d0ba0321463c2e27ff6dd46f13f4e524f9e18219b80f95623aab50089a5194a36b901723b5eb65426

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rubocop.yml

@@ -0,0 +1,20 @@
+# For all options see https://github.com/bbatsov/rubocop/tree/master/config
+
+AllCops:
+  Includes:
+    - Rakefile
+    - statesman.gemfile
+  Excludes:
+    - vendor/**
+
+StringLiterals:
+  Enabled: false
+
+Documentation:
+  Enabled: false
+
+# Avoid methods longer than 30 lines of code
+MethodLength:
+  CountComments: false  # count full line comments?
+  Max: 15
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in statesman.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,14 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cli: "--color", all_on_start: true do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+guard :rubocop, all_on_start: true, cli: ['--format', 'clang'] do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+  watch(%r{(?:.+/)?\rubocop-todo\.yml$}) { |m| File.dirname(m[0]) }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Harry Marr
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+![Statesman](http://f.cl.ly/items/410n2A0S3l1W0i3i0o2K/statesman.png)
+
+A statesmanlike state machine library for Ruby 2.0.
+
+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.
+
+## TL;DR Usage
+
+```ruby
+class OrderStateMachine
+  include Statesman::Machine
+
+  state :pending, initial: true
+  state :checking_out
+  state :purchased
+  state :shipped
+  state :cancelled
+  state :failed
+  state :refunded
+
+  transition from: :created,      to: [:checking_out, :cancelled]
+  transition from: :checking_out, to: [:purchased, :cancelled]
+  transition from: :purchased,    to: [:shipped, :failed]
+  transition from: :shipped,      to: :refunded
+
+  guard_transition(to: :checking_out) do |order|
+    order.products_in_stock?
+  end
+
+  before_transition(from: :checking_out, to: :cancelled) do |order, transition|
+    order.reallocate_stock
+  end
+
+  before_transition(to: :purchased) do |order, transition|
+    PaymentService.new(order).submit
+  end
+
+  after_transition(to: :purchased) do |order, transition|
+    MailerService.order_confirmation(order).deliver
+  end
+end
+
+class Order < ActiveRecord::Base
+  has_many :order_transitions
+
+  def state_machine
+    OrderStateMachine.new(self, transition_class: OrderTransition)
+  end
+end
+
+class OrderTransition < ActiveRecord::Base
+  belongs_to :order, inverse_of: :order_transitions
+end
+
+Order.first.state_machine.current_state
+# => "created"
+
+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
+```
+
+## Persistence
+
+By default Statesman stores transition history in memory only. It can be
+persisted by configuring Statesman to use a different adapter. For example,
+ActiveRecord within Rails:
+  
+`config/initializers/statesman.rb`:
+
+```ruby
+Statesman.configure do
+  storage_adapter(Statesman::Adapters::ActiveRecord)
+  transition_class(OrderTransition)
+end
+```
+
+Generate the transition model:
+
+```bash
+$ rails g statesman:transition Order OrderTransition
+```
+
+And add an association from the parent model:
+
+`app/models/order.rb`:
+
+```ruby
+class Order < ActiveRecord::Base
+  has_many :order_transitions
+
+  # Initialize the state machine
+  def state_machine
+    @state_machine ||= OrderStateMachine.new(self, transition_class: OrderTransition)
+  end
+
+  # Optionally delegate some methods
+  delegate :can_transition_to?, :transition_to!, :transition_to, :current_state,
+           to: :state_machine
+end
+```
+
+## Configuration
+
+#### `storage_adapter`
+
+```ruby
+Statesman.configure do
+  storage_adapter(Statesman::Adapters::ActiveRecord)
+end
+```
+Statesman defaults to storing transitions in memory. If you're using rails, you can instead configure it to persist transitions to the database by using the ActiveRecord adapter.
+
+#### `transition_class`
+```ruby
+Statesman.configure do
+  transition_class(OrderTransition)
+end
+```
+Configure the transition model. For now that means serializing metadata to JSON.
+
+
+## Class methods
+
+#### `Machine.state`
+```ruby
+Machine.state(:some_state, initial: true)
+Machine.state(:another_state)
+```
+Define a new state and optionally mark as the initial state.
+
+#### `Machine.transition`
+```ruby
+Machine.transition(from: :some_state, to: :another_state)
+```
+Define a transition rule. Both method parameters are required, `to` can also be an array of states (`.transition(from: :some_state, to: [:another_state, :some_other_state])`).
+
+#### `Machine.guard_transition`
+```ruby
+Machine.guard_transition(from: :some_state, to: another_state) do |object|
+  object.some_boolean?
+end
+```
+Define a guard. `to` and `from` parameters are optional, a nil parameter means guard all transitions. The passed block should evaluate to a boolean and must be idempotent as it could be called many times.
+
+#### `Machine.before_transition`
+```ruby
+Machine.before_transition(from: :some_state, to: another_state) do |object| 
+  object.side_effect
+end
+```
+Define a callback to run before a transition. `to` and `from` parameters are optional, a nil parameter means run before all transitions. This callback can have side-effects as it will only be run once immediately before the transition.
+
+#### `Machine.after_transition`
+```ruby
+Machine.after_transition(from: :some_state, to: another_state) do |object, transition|
+  object.side_effect
+end
+```
+Define a callback to run after a successful transition. `to` and `from` parameters are optional, a nil parameter means run after all transitions. The model object and transition object are passed as arguments to the callback. This callback can have side-effects as it will only be run once immediately after the transition.
+
+#### `Machine.new`
+```ruby
+my_machine = Machine.new(my_model, transition_class: MyTransitionModel)
+```
+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`.
+
+## Instance methods
+
+#### `Machine#current_state`
+Returns the current state based on existing transition objects.
+
+#### `Machine#history`
+Returns a sorted array of all transition objects.
+
+#### `Machine#last_transition`
+Returns the most recent transition object.
+
+#### `Machine#can_transition_to?(:state)`
+Returns true if the current state can transition to the passed state and all applicable guards pass.
+
+#### `Machine#transition_to!(:state)`
+Transition to the passed state, returning `true` on success. Raises `Statesman::GuardFailedError` or `Statesman::TransitionFailedError` on failure.
+
+#### `Machine#transition_to(:state)`
+Transition to the passed state, returning `true` on success. Swallows all exceptions and returns false on failure.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/circle.yml

@@ -0,0 +1,9 @@
+machine:
+  ruby:
+    version: 2.0.0-p247
+test:
+  pre:
+    - bundle exec rubocop
+database:
+  override:
+    - echo "no database step needed"

data/lib/generators/statesman/migration_generator.rb

@@ -0,0 +1,35 @@
+require "rails/generators"
+
+# Add statesman attributes to a pre-existing transition class
+module Statesman
+  class MigrationGenerator < Rails::Generators::Base
+    desc "Add the required Statesman attributes to your transition model"
+
+    argument :parent, type: :string, desc: "Your parent model name"
+    argument :klass, type: :string, desc: "Your transition model name"
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    def create_model_file
+      template("update_migration.rb.erb", file_name)
+    end
+
+    private
+
+    def next_migration_number
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+
+    def file_name
+      "db/migrate/#{next_migration_number}_add_statesman_to_#{table_name}.rb"
+    end
+
+    def table_name
+      klass.underscore.pluralize
+    end
+
+    def parent_id
+      parent.underscore + "_id"
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+class Create<%= klass.pluralize %> < ActiveRecord::Migration
+  def change
+    create_table :<%= table_name %> do |t|
+      t.string :to_state
+      t.text :metadata, default: "{}"
+      t.integer :sort_key
+      t.integer :<%= parent_id %>
+    end
+
+    add_index :<%= table_name %>, :<%= parent_id %>
+    add_index :<%= table_name %>, [:sort_key, :<%= parent_id %>], unique: true
+  end
+end

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

@@ -0,0 +1,4 @@
+class <%= klass %> < ActiveRecord::Base
+  attr_accessible :to_state, :metadata, :sort_key
+  belongs_to :<%= parent.underscore %>, inverse_of: :<%= table_name %>
+end

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

@@ -0,0 +1,11 @@
+class AddStatesmanTo<%= klass.pluralize %> < ActiveRecord::Migration
+  def change
+    add_column :<%= table_name %>, :to_state, :string
+    add_column :<%= table_name %>, :metadata, :text, default: "{}"
+    add_column :<%= table_name %>, :sort_key, :integer
+    add_column :<%= table_name %>, :<%= parent_id %>, :integer
+
+    add_index :<%= table_name %>, :<%= parent_id %>
+    add_index :<%= table_name %>, [:sort_key, :<%= parent_id %>], unique: true
+  end
+end

data/lib/generators/statesman/transition_generator.rb

@@ -0,0 +1,39 @@
+require "rails/generators"
+
+module Statesman
+  class TransitionGenerator < Rails::Generators::Base
+    desc "Create a transition model with the required attributes"
+
+    argument :parent, type: :string, desc: "Your parent model name"
+    argument :klass, type: :string, desc: "Your transition model name"
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    def create_model_file
+      template("create_migration.rb.erb", migration_file_name)
+      template("transition_model.rb.erb", model_file_name)
+    end
+
+    private
+
+    def next_migration_number
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+
+    def migration_file_name
+      "db/migrate/#{next_migration_number}_create_#{table_name}.rb"
+    end
+
+    def model_file_name
+      "app/models/#{klass.underscore}.rb"
+    end
+
+    def table_name
+      klass.underscore.pluralize
+    end
+
+    def parent_id
+      parent.underscore + "_id"
+    end
+  end
+end

data/lib/statesman.rb

@@ -0,0 +1,24 @@
+module Statesman
+  autoload :Config,     'statesman/config'
+  autoload :Machine,    'statesman/machine'
+  autoload :Callback,   'statesman/callback'
+  autoload :Guard,      'statesman/guard'
+  autoload :Transition, 'statesman/transition'
+  autoload :Version,    'statesman/version'
+  require "statesman/adapters/memory"
+  require "statesman/adapters/active_record"
+
+  # Example:
+  #   Statesman.configure do
+  #     storage_adapter Statesman::ActiveRecordAdapter
+  #   end
+  #
+  def self.configure(&block)
+    config = Config.new(block)
+    @storage_adapter = config.adapter_class
+  end
+
+  def self.storage_adapter
+    @storage_adapter || Adapters::Memory
+  end
+end

data/lib/statesman/adapters/active_record.rb

@@ -0,0 +1,53 @@
+require "active_record"
+require "statesman/exceptions"
+
+module Statesman
+  module Adapters
+    class ActiveRecord
+      attr_reader :transition_class
+      attr_reader :parent_model
+
+      def initialize(transition_class, parent_model)
+        unless transition_class.serialized_attributes.include?("metadata")
+          raise UnserializedMetadataError,
+                "#{transition_class.name}#metadata is not serialized"
+        end
+        @transition_class = transition_class
+        @parent_model = parent_model
+      end
+
+      def create(to, before_cbs, after_cbs, metadata = {})
+        transition = transitions_for_parent.build(to_state: to,
+                                                  sort_key: next_sort_key,
+                                                  metadata: metadata)
+
+        ::ActiveRecord::Base.transaction do
+          before_cbs.each { |cb| cb.call(@parent_model, transition) }
+          transition.save!
+          after_cbs.each { |cb| cb.call(@parent_model, transition) }
+          @last_transition = nil
+        end
+
+        transition
+      end
+
+      def history
+        transitions_for_parent.order(:sort_key)
+      end
+
+      def last
+        @last_transition ||= transitions_for_parent.order(:sort_key).last
+      end
+
+      private
+
+      def transitions_for_parent
+        @parent_model.send(@transition_class.table_name)
+      end
+
+      def next_sort_key
+        (last && last.sort_key + 10) || 0
+      end
+    end
+  end
+end