state_machinable 2.0.0 → 3.0.0.pre.rc0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 14cbdf576bdb9760f0da81d5b53accb8c73a048e
-  data.tar.gz: fca5149485432751a7ecd18c4f21ab1ccf633f69
+  metadata.gz: 41405511bd178326737846d59454cefb6727cf71
+  data.tar.gz: d5d40aadb0a86ec6a1120a1ddf398c1c2a1fbfa7
 SHA512:
-  metadata.gz: 016b0c5f2b755cc4e89328b118e7b01152b6b83d5330bdb8474166a2c8e20587359bab329a2f7de23d17608f2a86006cf3d77af52947654642ced2afbc895bbc
-  data.tar.gz: a0df1e3bac12a44e72d3d7d3b1bad100b66936d9013202b3f3a3defce63a10ee083467b09c6e717c4176b8ac00ad604570aa75a788efc678259b41638d2ff792
+  metadata.gz: a88628febd7d3ed64216b5fc864ebca770ca1576e728d09c95d038865ba8174c294a533f214c5b41afcae86059ddf5edc1ef611d295c9e0c41981773d047df87
+  data.tar.gz: 5fdba8bc745a51f3c12db9b05142c323a97dd2fb433d066d18a4180751d36c76a216bad4c0c5c666bc9e82bd4b22f32024685831407ca7f5d11fb6437bce4df3

data/README.md

@@ -4,10 +4,11 @@ Adds state machine functionality to `statesman`
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add these lines to your application's Gemfile:
 
 ```ruby
 gem 'state_machinable'
+gem 'statesman'
 ```
 
 And then execute:
@@ -16,11 +17,129 @@ And then execute:
 
 Or install it yourself as:
 
+    $ gem install statesman
     $ gem install state_machinable
 
+## Setup
+
+Generate the transitions for a model, e.g. `Order`
+
+    $ rails g migration CreateOrderTransitions
+
+The migration will look very similar to if you had generated it with Statesman, but with a `current_state` added
+    
+    `rails g statesman:active_record_transition Order OrderTransition`
+
+```ruby
+class CreateOrderTransitions < ActiveRecord::Migration
+  def change
+    add_column :orders, :current_state, :string # <- ADD THIS LINE
+    create_table :order_transitions do |t|
+      t.string :to_state, null: false
+      t.text :metadata
+      t.integer :sort_key, null: false
+      t.integer :order_id, null: false
+      t.boolean :most_recent
+      t.timestamps null: false
+    end
+
+    add_index(:order_transitions, [:order_id, :sort_key], unique: true, name: "index_order_transitions_parent_sort")
+    add_index(:order_transitions, [:order_id, :most_recent], unique: true, name: "index_order_transitions_parent_most_recent")
+  end
+end
+```
+
+In your model, include this library and transitions:
+
+```ruby
+class Order < ActiveRecord::Base
+    include StateMachinable::Model
+    has_many :order_transitions, :dependent => :destroy
+```
+
+Then set up your state transitions:
+```ruby
+# app/state_machines/order_state_machine.rb
+
+class OrderStateMachine
+  include StateMachinable::Base
+
+  # define your states
+  state :open
+  state :processing
+  state :shipped
+  state :delivered
+  state :cancelled
+
+  # define transitions
+  transition :from => :initial, :to => :open
+  transition :from => :open, :to => [:processing, :cancelled]
+  transition :from => :processing, :to => [:shipped, :cancelled]
+  transition :from => :shipped, :to => [:delivered]
+
+  # define events that may occur
+  EVENTS = [
+    :event_processing,
+    :event_shipped,
+    :event_cancelled,
+    :event_delivered
+  ].freeze
+
+  # define a class for each state, with methods for event that may occur within that state
+  class Open
+    def self.event_processing(order)
+      order.transition_to!(:processing)
+      # TODO: send order confirmation email to customer
+    end
+    def self.event_cancelled(order)
+      order.transition_to!(:cancelled)
+      # ...
+    end
+  end
+  
+  class Shipped
+    def self.event_delivered(order)
+      order.transition_to!(:delivered)
+      # ...
+    end
+  end
+end
+
+```
+
+There are also hooks for the state changes that could be used instead of duplicating logic in multiple events that transition to the same state
+
+```ruby
+class Cancelled
+  def self.enter(order)
+    # TODO: send email to customer that order is cancelled
+  end
+end
+
+```
+
 ## Usage
+When you want to transition from one state to another, call an event:
+
+```ruby
+order.state_machine.event_shipped
+```
 
-TODO
+You may want to use a transaction around the event to ensure that both the current_state and transitions are committed, or to prevent invalid states
+
+```ruby
+ActiveRecord::Base.transaction do
+  # without a transaction here then an invoice could be created without the order's state succeeding in transitioning to shipped
+  Order.create_invoice_for_order!(order)
+  order.state_machine.event_shipped
+end
+```
+
+You can check the model's state with `#current_state`
+
+```ruby
+order.current_state
+```
 
 ## Development
 

data/lib/state_machinable/base.rb

@@ -38,7 +38,6 @@ module StateMachinable
           events = []
         end
 
-        events.concat([:ev_before_save, :ev_after_save]).uniq
         clean_name = name.to_s.chomp('!').to_sym
 
         if events.include?(clean_name)

data/lib/state_machinable/model.rb

@@ -13,8 +13,6 @@ module StateMachinable
     end
 
     included do
-      before_save :send_ev_before_save, :if => Proc.new { |obj| obj.changed? }
-      after_save :send_ev_after_save, :if => Proc.new { |obj| !obj.id_changed? && obj.changed? }
       after_save :transition_to_initial_state, :if => Proc.new { |obj| obj.id_changed? }
       delegate :can_transition_to?, :transition_to!, :transition_to, :to => :state_machine
 
@@ -22,14 +20,6 @@ module StateMachinable
         @state_machine ||= self.class.state_machine_class.new(self, :transition_class => self.class.transition_class)
       end
 
-      def send_ev_before_save
-        self.state_machine.send('ev_before_save')
-      end
-
-      def send_ev_after_save
-        self.state_machine.send('ev_after_save')
-      end
-
       private def transition_to_initial_state
         initial_state = self.state_machine.class.successors['initial'].first
         if (!self.respond_to?(:skip_state_machine?) || !self.skip_state_machine?) && (self.current_state != initial_state)

data/lib/state_machinable/version.rb

@@ -1,3 +1,3 @@
 module StateMachinable
-  VERSION = "2.0.0"
+  VERSION = "3.0.0-rc0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: state_machinable
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0.pre.rc0
 platform: ruby
 authors:
 - Santiago Herrera
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-18 00:00:00.000000000 Z
+date: 2018-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -125,9 +125,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.8