rails-workflow 1.4.1.2 → 1.4.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec4b025de0b47929f1e64a9315b8da9d282785ef
-  data.tar.gz: 2ffc02aae267a096d51c4d7c531f94f95abf87ab
+  metadata.gz: 8270a626780c254a58897c2cef2e0b162b5fbcae
+  data.tar.gz: 1a9e4480f3306fc8b10136d2dce4c92d3570b529
 SHA512:
-  metadata.gz: daabd4600fb5fbda2fc576b7cc520f411ac137baeeeae5e28248229b2e81c0554a6e97190c5f4b1e64413409cc713407c1fe0d27b897f2aacdc993579117c157
-  data.tar.gz: 58f77cc643f6418d91a43b07d89b253cacfca3cb872a033bb49417e6ed333faa9d14441b32e97e828485f6ec69a0365f2a5449cbeee442157eadeef46d4e7a22
+  metadata.gz: 70c376c21353280fbff28bac40ba2509581c681e2591788793d1031bf40923f21665c2e5285609e899e65a3b74acb4390d511cd14108beeb8b438ab861e82085
+  data.tar.gz: b79da68fd8e266ff0d1a55623a60db87c1499dfeb0ccfc0e551dd4ee77186b4ee57b5e5f8f26fdc6665db07c8caf0fac71419926b3b0fef9b1bcc42f37e5de1b

data/README.markdown

@@ -1,126 +1,223 @@
 What is workflow?
 -----------------
 
-This Gem is a fork of Vladimir Dobriakov's [Workflow Gem](http://github.com/geekq/workflow).  Credit goes to him for the core code.  Please read [the original README](http://github.com/geekq/workflow) for a full introduction,
-as this README skims through much of that content and focuses on new / changed features.
+This Gem is a fork of Vladimir Dobriakov's [Workflow Gem](http://github.com/geekq/workflow).  Credit goes to him for the inspiration, architecture and basic syntax.
 
 ## What's different in rails-workflow
 
-The primary difference here is the use of [ActiveSupport::Callbacks](http://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html)
+* Use of [ActiveSupport::Callbacks](http://api.rubyonrails.org/classes/ActiveSupport/Callbacks.html)
 to enable a more flexible application of callbacks.
-You now have access to the same DSL you're used to from [ActionController Callbacks](http://guides.rubyonrails.org/action_controller_overview.html#filters),
-including the ability to wrap state transitions in an `around_transition`, to place
-conditional logic on application of callbacks, or to have callbacks run for only
-a set of state-change events.
+* Slightly terser syntax for event definition.
+* Cleaner support for using conditional ActiveRecord validations to validate state transitions.
 
-I've made `ActiveRecord` and `ActiveSupport` into runtime dependencies.
 
-You can also take advantage of ActiveRecord's conditional validation syntax,
-to apply validations only to specific state transitions.
+## Installation
 
+    gem install rails-workflow
 
-Installation
-------------
+## Configuration
 
-    gem install rails-workflow
+No configuraion is required, but the following configurations can be placed inside an initializer:
 
+```ruby
+# config/initializers/workflow.rb
+Workflow.configure do |config|
+  #  Set false to avoid the extra call to the database, if you'll be saving the object after transition.
+  self.persist_workflow_state_immediately = true
+  #  Set true to also change the `:updated_at` during state transition.
+  self.touch_on_update_column = false
+end
+
+```
 
 Ruby Version
 --------
 
-I've only tested with Ruby 2.3.  ;)  Time to upgrade.
-
+I've only tested with Ruby 2.3.  ;)  
 
 # Basic workflow definition:
 
-    class Article
-      include Workflow
-      workflow do
-        state :new do
-          event :submit, :transitions_to => :awaiting_review
-        end
-        state :awaiting_review do
-          event :review, :transitions_to => :being_reviewed
-        end
-        state :being_reviewed do
-          event :accept, :transitions_to => :accepted
-          event :reject, :transitions_to => :rejected
-        end
-        state :accepted
-        state :rejected
-      end
+```ruby
+class Article
+  include Workflow
+  workflow do
+    state :new do
+      on :submit, to: :awaiting_review
+    end
+    state :awaiting_review do
+      on :review, to: :being_reviewed
+    end
+    state :being_reviewed do
+      on :accept, to: :accepted
+      on :reject, to: :rejected
     end
+    state :accepted
+    state :rejected
+  end
+end
+
+```
+
+## Invoking State Transitions
+
+You may call the method named for the event itself, or else the more generic `transition!` method
+
+```ruby
+a = Article.new
+a.current_state.name
+# => :new
+a.submit!
+a.current_state.name
+# => :awaiting_review
+# ... etc
+```
+
+```ruby
+a = Article.new
+a.transition! :submit
+a.current_state.name
+# => :awaiting_review
+```
+
+The transition will return a truthy value if it succeeds: either the return value
+of the event-specific callback, if one is defined, or else the name of the new state
+
+```ruby
+puts a.transition!(:submit)
+# => :awaiting_review
+```
+
+If the transition does not finish and no exception is raised, the method returns `false`.
+
+Generally this would be because of a validation failure, so checking the model for errors
+would be the next course of action.
+
+You can also pass arguments to the event, though nothing will happen with them except
+as you've defined in your callbacks (described below)
+
+```ruby
+a.submit!(author: 'Fanny Schmittenbauer', awesomeness: 29)
+```
 
 Access an object representing the current state of the entity,
 including available events and transitions:
 
-    article.current_state
-    => #<Workflow::State:0x7f1e3d6731f0 @events={
-      :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil,
-        @transitions_to=:awaiting_review, @name=:submit, @meta={}>},
-      name:new, meta{}
+```ruby
+article.current_state
+# => <State name=:new events(1)=[<Event name=:submit transitions(1)=[<to=<State name=:awaiting_review events(1)=[<Event name=:review transitions(1)=...
+```
 
 On Ruby 1.9 and above, you can check whether a state comes before or
 after another state (by the order they were defined):
 
-    article.current_state
-    => being_reviewed
-    article.current_state < :accepted
-    => true
-    article.current_state >= :accepted
-    => false
-    article.current_state.between? :awaiting_review, :rejected
-    => true
-
+```ruby
+article.current_state
+# => being_reviewed
+article.current_state < :accepted
+# => true
+article.current_state >= :accepted
+# => false
+article.current_state.between? :awaiting_review, :rejected
+# => true
+```
 Now we can call the submit event, which transitions to the
 <tt>:awaiting_review</tt> state:
 
     article.submit!
     article.awaiting_review? # => true
 
+# Multiple Possible Targets For A Given Event
+
+The first matching condition will determine the target state.
+An error will be raised if none match, so a catchall at the end is a good idea.
+
+```ruby
+class Article
+  include Workflow
+  workflow do
+    state :new do
+      on :submit do
+        to :awaiting_review, if: :today_is_wednesday?
+        to :being_reviewed, unless: "author.name == 'Foo Bar'"
+        to :accepted, if: -> {author.role == 'Admin'}
+        to :rejected, if: [:bad_hair_day?, :in_a_bad_mood?]
+        to :the_bad_place
+      end
+    end
+    state :awaiting_review do
+      on :review, to: :being_reviewed
+    end
+    state :being_reviewed do
+      on :accept, to: :accepted
+      on :reject, to: :rejected
+    end
+    state :accepted
+    state :rejected
+    state :the_bad_place
+  end
+end
+```
 
 Callbacks
 -------------------------
 
 The DSL syntax here is very much similar to ActionController or ActiveRecord callbacks.
 
-Callbacks with this strategy used the same as [ActionController Callbacks](http://guides.rubyonrails.org/action_controller_overview.html#filters).
+Three classes of callbacks:
 
-You can configure any number of `before`, `around`, or `after` transition callbacks.
+* :transition callbacks representing named events.
+  * `before_transition only: :submit`
+  * `after_transition except: :submit`
+* :exit callbacks that match on the state the transition leaves
+  * `before_exit only: :being_reviewed  #will run on the :accept or the :reject event`
+* :enter callbacks that match on the target state for the transition
+  * `before_enter only: :being_reviewed`  #will run on the :review event
 
-`before_transition` and `around_transition` are called in the order they are set,
-and `after_transition` callbacks are called in reverse order.
+Callbacks run in this order:
 
-## Around Transition
+* `before_transition`, `around_transition`
+  * `before_exit`, `around_exit`
+    * `before_enter`, `around_enter`
+      * **State Transition**
+    * `after_enter`
+  * `after_exit`
+* `after_transition`
 
-Allows you to run code surrounding the state transition.
+Within each group, the callbacks fire in the order they are set.
 
-    around_transition :wrap_in_transaction
+### Halting callbacks
+Inside any `:before` callback, you can halt the callback chain:
 
-    def wrap_in_transaction(&block)
-      Article.transaction(&block)
-    end
+```ruby
+before_enter do
+  throw :abort
+end
+```
 
-You can also define the callback using a block:
+Note that this will halt the callback chain without an error,
+so you won't get an exception in your `on_error` block, if you have one.
 
-    around_transition do |object, transition|
-      object.with_lock do
-        transition.call
-      end
-    end
+## Around Transition
 
-### Replacement for workflow's `on_error` proc:
+Allows you to run code surrounding the state transition.
 
-  around_transition :catch_errors
+```ruby
+around_transition :wrap_in_transaction
 
-  def catch_errors
-    begin
-      yield
-    rescue SomeApplicationError => ex
-      logger.error 'Oh noes!'
-    end
-  end
+def wrap_in_transaction(&block)
+  Article.transaction(&block)
+end
+```
 
+You can also define the callback using a block:
+
+```ruby
+around_transition do |object, transition|
+  object.with_lock do
+    transition.call
+  end
+end
+```
 
 ## before_transition
 
@@ -129,36 +226,44 @@ If you `halt` or `throw :abort` within a `before_transition`, the callback chain
 will be halted, the transition will be canceled and the event action
 will return false.
 
-    before_transition :check_title
+```ruby
+  before_transition :check_title
 
     def check_title
       halt('Title was bad.') unless title == "Good Title"
     end
+```
 
 Or again, in block expression:
 
+```ruby
     before_transition do |article|
       throw :abort unless article.title == "Good Title"
     end
-
+```
 ## After Transition
 
 Runs code after the transition.
 
+```ruby
     after_transition :check_title
-
+```
 
 ## Prepend Transitions
 
 To add a callback to the beginning of the sequence:
 
-    prepend_before_transition :some_before_transition
-    prepend_around_transition :some_around_transition
-    prepend_after_transition :some_after_transition
+```ruby
+prepend_before_transition :some_before_transition
+prepend_around_transition :some_around_transition
+prepend_after_transition :some_after_transition
+```
 
 ## Skip Transitions
 
+```ruby
     skip_before_transition :some_before_transition
+```
 
 
 ## Conditions
@@ -167,17 +272,114 @@ To add a callback to the beginning of the sequence:
 
 The callback will run `if` or `unless` the named method returns a truthy value.
 
-    before_transition :do_something, if: :valid?
+```ruby
+before_transition :do_something, if: :valid?
+
+# Array conditions apply if all aggregated conditions apply.
+before_transition :do_something, if: [:valid?, :kosher?]
+before_transition :do_something, if: [:valid?, "title == 'Good Title'"]
+before_transition :do_something, unless: [:valid?, -> {title == 'Good Title'}]
+```
 
 ### only/except
 
-The callback will run `if` or `unless` the event being processed is in the list given
+The three callback classes accept `:only` and `:except` parameters, and treat them slightly differnetly.
+
+    You can use `:only` and `:except` in conjunction with `:if` and `:unless`.
+
+* **Transition Callbacks** match on the name of the event being executed.
+  * `before_transition only: :submit` will run when the `:submit` event is fired
+  * `before_transition except: [:submit, :reject]` will run on any event except the two named
+* **Exit Callbacks** match on the name of the state being exited
+  * `before_exit only: :new` will run when an event causes the object to leave the `:new` state.
+* **Enter Callbacks** match on the name of the state being entered
+  * `before_enter only: [:cancelled, :rejected]` will run when an event leaves the object `:cancelled` or `:rejected`.
+
+## Parameterized Callbacks
+
+If you're passing parameters through the `transition!` method, you can receive
+them easily in your callbacks.  For example:
+
+```ruby
+class Article
+  include Workflow
+  workflow do
+    event_args :review_date
+  end
+  before_transition do |reviewer:|
+    logger.debug reviewer.name
+  end
+  after_transition do |author:, **arguments|
+    logger.debug arguments[:reviewer].name
+    logger.debug author.name
+  end
+end
+
+Article.last.transition! :submit, reviewer: current_user
+```
+
+If you don't like keyword arguments you can use standard arguments, but you
+need to receive the model as the first argument to your block, and you have to
+configure the `event_args` for the transition context, within your workflow definition.
+
+```ruby
+before_transition, only: :submit do |article, review_date, reviewer:|
+  puts review_date
+end
+
+Article.last.transition! :submit, Date.today, reviewer: current_user
+
+```
+
+## Catching Errors
 
-    #  Run this callback only on the `accept` and `publish` events.
-    before_transition :do_something, only: [:accept, :publish]
+```ruby
+class WorkflowModel
+  include Workflow
 
-    #  Run this callback on events other than the `accept` and `publish` events.
-    before_transition :do_something_else, except: [:accept, :publish]
+  #  Some possibilities:
+  on_error StandardError, rescue: "self.errors << 'oops!'"
+  on_error StandardError, rescue: :notify_error_service!
+
+  #  Default error class is Exception
+  on_error unless: "logger.nil?" do |ex|
+    logger.warn ex.message
+    raise ApplicationError.new('Whoopsies!')
+  end
+
+  on_error ensure: ->{self.always_run_this!}, only: :process
+
+  on_error SomeAppError, ensure: ->{self.always_run_this!} do |ex|
+    # SomeAppError and its subclasses will be rescued and this block will run.
+    # The ensure proc will be run in the ensure block.
+    logger.debug "Couldn't complete transition: #{transition_context.event} because: #{ex.message}"  
+  end
+
+  workflow do
+    state :initial do
+      on :process, to: :processing
+      on :different_process, to: :processing
+    end
+    state :processing do
+      on :finish, to: :done
+    end
+    state :done
+  end
+end
+```
+
+## Ensuring code will run
+
+```ruby
+
+#  This will happen no matter what, whenever the process! event is run.
+ensure_after_transitions only: :process do
+  self.messages << :foo
+end
+
+ensure_after_transitions :clean_up_resources!
+
+```
 
 ## Conditional Validations
 
@@ -188,26 +390,35 @@ Inside the same Article class which was begun above, the following three
 validations would all run when the `submit` event is used to transition
 from `new` to `awaiting_review`.
 
-    validates :title, presence: true, if: :transitioning_to_awaiting_review?
-    validates :body, presence: true, if: :transitioning_from_new?
-    validates :author, presence: true, if: :transitioning_via_event_submit?
+```ruby
+validates :title, presence: true, if: :transitioning_to_awaiting_review?
+validates :body, presence: true, if: :transitioning_from_new?
+validates :author, presence: true, if: :transitioning_via_event_submit?
+```
 
 ### Halting if validations fail
 
     #  This will create a transition callback which will stop the event
     #  and return false if validations fail.
+
     halt_transition_unless_valid!
 
-    #  This is the same as
+    #  This is the same as doing
+
+    before_transition do
+      throw :abort unless valid?
+    end
 
 ### Checking A Transition
 
 Call `can_transition?` to determine whether the validations would pass if a
 given event was called:
 
-    if article.can_transition?(:submit)
-      #  Do something interesting
-    end
+```ruby
+if article.can_transition?(:submit)
+  #  Do something interesting
+end
+```
 
 # Transition Context
 
@@ -219,65 +430,62 @@ for information about the current transition.  See [Workflow::TransitionContext]
 If you will normally call each of your events with the same arguments, the following
 will help:
 
-    class Article < ApplicationRecord
-      include Workflow
+```ruby
+class Article < ApplicationRecord
+  include Workflow
 
-      before_transition :check_reviewer
+  before_transition :check_reviewer
 
-      def check_reviewer
-        # Ability is a class from the cancan gem: https://github.com/CanCanCommunity/cancancan
-        halt('Access denied') unless Ability.new(transition_context.reviewer).can?(:review, self)
-      end
+  def check_reviewer
+    # Ability is a class from the cancan gem: https://github.com/CanCanCommunity/cancancan
+    halt('Access denied') unless Ability.new(transition_context.reviewer).can?(:review, self)
+  end
 
-      workflow do
-        event_args :reviewer, :reviewed_at
-        state :new do
-          event :review, transitions_to: :reviewed
-        end
-        state :reviewed
-      end
+  workflow do
+    event_args :reviewer, :reviewed_at
+    state :new do
+      on :review, to: :reviewed
     end
-
+    state :reviewed
+  end
+end
+```
 
 Transition event handler
 ------------------------
 
-The best way is to use convention over configuration and to define a
-method with the same name as the event. Then it is automatically invoked
+You can define a method with the same name as the event. Then it is automatically invoked
 when event is raised. For the Article workflow defined earlier it would
 be:
 
-    class Article
-      def reject
-        puts 'sending email to the author explaining the reason...'
-      end
-    end
+```ruby
+class Article
+  def reject
+    puts 'sending email to the author explaining the reason...'
+  end
+end
+```
 
 `article.review!; article.reject!` will cause state transition to
 `being_reviewed` state, persist the new state (if integrated with
 ActiveRecord), invoke this user defined `reject` method and finally
 persist the `rejected` state.
 
-Note: on successful transition from one state to another the workflow
-gem immediately persists the new workflow state with `update_column()`,
-bypassing any ActiveRecord callbacks including `updated_at` update.
-This way it is possible to deal with the validation and to save the
-pending changes to a record at some later point instead of the moment
-when transition occurs.
 
 You can also define event handler accepting/requiring additional
 arguments:
 
-    class Article
-      def review(reviewer = '')
-        puts "[#{reviewer}] is now reviewing the article"
-      end
-    end
-
-    article2 = Article.new
-    article2.submit!
-    article2.review!('Homer Simpson') # => [Homer Simpson] is now reviewing the article
+```ruby
+class Article
+  def review(reviewer = '')
+    puts "[#{reviewer}] is now reviewing the article"
+  end
+end
 
+article2 = Article.new
+article2.submit!
+article2.review!('Homer Simpson') # => [Homer Simpson] is now reviewing the article
+```
 
 Integration with ActiveRecord
 -----------------------------
@@ -286,12 +494,14 @@ Workflow library can handle the state persistence fully automatically. You
 only need to define a string field on the table called `workflow_state`
 and include the workflow mixin in your model class as usual:
 
-    class Order < ActiveRecord::Base
-      include Workflow
-      workflow do
-        # list states and transitions here
-      end
-    end
+```ruby
+class Order < ActiveRecord::Base
+  include Workflow
+  workflow do
+    # list states and transitions here
+  end
+end
+```
 
 On a database record loading all the state check methods e.g.
 `article.state`, `article.awaiting_review?` are immediately available.
@@ -311,19 +521,21 @@ method.
 Workflow library also adds automatically generated scopes with names based on
 states names:
 
-    class Order < ActiveRecord::Base
-      include Workflow
-      workflow do
-        state :approved
-        state :pending
-      end
-    end
+```ruby
+class Order < ActiveRecord::Base
+  include Workflow
+  workflow do
+    state :approved
+    state :pending
+  end
+end
 
-    # returns all orders with `approved` state
-    Order.with_approved_state
+# returns all orders with `approved` state
+Order.with_approved_state
 
-    # returns all orders with `pending` state
-    Order.with_pending_state
+# returns all orders with `pending` state
+Order.with_pending_state
+```
 
 ### Wrap State Transition in a locking transaction
 
@@ -331,39 +543,25 @@ Wrap your transition in a locking transaction to ensure that any exceptions
 raised later in the transition sequence will roll back earlier changes made to
 the record:
 
-    class Order < ActiveRecord::Base
-      include Workflow
-      workflow transactional: true do
-        state :approved
-        state :pending
-      end
-    end
-
-Conditional event transitions
------------------------------
-
-Conditions can be a "method name symbol" with a corresponding instance method, a `proc` or `lambda` which are added to events, like so:
+```ruby
+class Order < ActiveRecord::Base
+  include Workflow
 
-    state :off
-      event :turn_on, :transition_to => :on,
-                      :if => :sufficient_battery_level?
+  wrap_transition_in_transaction!
+  # which is the same as the following:
 
-      event :turn_on, :transition_to => :low_battery,
-                      :if => proc { |device| device.battery_level > 0 }
+  around_transition do |model, transition|
+    model.with_lock do
+      transition.call
     end
+  end
 
-    # corresponding instance method
-    def sufficient_battery_level?
-      battery_level > 10
-    end
-
-When calling a `device.can_<fire_event>?` check, or attempting a `device.<event>!`, each event is checked in turn:
-
-* With no `:if` check, proceed as usual.
-* If an `:if` check is present, proceed if it evaluates to true, or drop to the next event.
-* If you've run out of events to check (eg. `battery_level == 0`), then the transition isn't possible.
-
-
+  workflow do
+    state :approved
+    state :pending
+  end
+end
+```
 
 Accessing your workflow specification
 -------------------------------------
@@ -371,34 +569,31 @@ Accessing your workflow specification
 You can easily reflect on workflow specification programmatically - for
 the whole class or for the current object. Examples:
 
-    article2.current_state.events # lists possible events from here
-    article2.current_state.events[:reject].transitions_to # => :rejected
+```ruby
+article2.current_state.events # lists possible events from here
 
-    Article.workflow_spec.states.keys
-    #=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
-
-    Article.workflow_spec.state_names
-    #=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
-
-    # list all events for all states
-    Article.workflow_spec.states.values.collect &:events
+Article.workflow_spec.states.map &:name
+#=> [:rejected, :awaiting_review, :being_reviewed, :accepted, :new]
 
+# list all events for all states
+Article.workflow_spec.states.map(&:events).flatten
+```
 
 You can also store and later retrieve additional meta data for every
 state and every event:
 
-    class MyProcess
-      include Workflow
-      workflow do
-        state :main, :meta => {:importance => 8}
-        state :supplemental, :meta => {:importance => 1}
-      end
+```ruby
+class MyProcess
+  include Workflow
+  workflow do
+    state :main, meta: {importance: 8} do
+      on :change, to: :supplemental, meta: {whatever: true}
     end
-    puts MyProcess.workflow_spec.states[:supplemental].meta[:importance] # => 1
-
-The workflow library itself uses this feature to tweak the graphical
-representation of the workflow. See below.
-
+    state :supplemental, meta: {importance: 1}
+  end
+end
+puts MyProcess.workflow_spec.find_state(:supplemental).meta[:importance] # => 1
+```
 
 Earlier versions
 ----------------

data/lib/workflow.rb

@@ -51,7 +51,7 @@ module Workflow
     res || workflow_spec.initial_state
   end
 
-  # Deprecated.  Check for false return value from {#process_event!}
+  # Deprecated.  Check for false return value from {#transition!}
   # @return true if the last transition was halted by one of the transition callbacks.
   def halted?
     @halted
@@ -66,7 +66,7 @@ module Workflow
   # @param [Symbol] name name of event to initiate
   # @param [Mixed] *args Arguments passed to state transition. Available also to callbacks
   # @return [Type] description of returned object
-  def process_event!(name, *args, **attributes)
+  def transition!(name, *args, **attributes)
     name = name.to_sym
     event = current_state.find_event(name)
     raise NoTransitionAllowed.new(
@@ -95,7 +95,7 @@ module Workflow
       run_all_callbacks do
         callback_value  = run_action_callback name, *args
         persist_value   = persist_workflow_state(target.name)
-        callback_value || persist_value
+        return_value    = callback_value || persist_value
       end
     ensure
       @transition_context = nil
@@ -264,7 +264,7 @@ module Workflow
           event_name = event.name
           module_eval do
             define_method "#{event_name}!".to_sym do |*args|
-              process_event!(event_name, *args)
+              transition!(event_name, *args)
             end
 
             define_method "can_#{event_name}?" do

data/lib/workflow/adapters/active_record.rb

@@ -22,6 +22,7 @@ module Workflow
               attrs[:updated_at] = DateTime.now
             end
             update_columns attrs
+            new_value
           else
             self[self.class.workflow_column] = new_value
           end

data/lib/workflow/adapters/active_record_validations.rb

@@ -5,6 +5,10 @@ module Workflow
     module ActiveRecordValidations
       extend ActiveSupport::Concern
 
+      included do
+        prepend RevalidateOnlyAfterAttributesChange
+      end
+
       ###
       #
       # Captures instance method calls of the form `:transitioning_from_<state_name>`
@@ -25,14 +29,6 @@ module Workflow
         end
       end
 
-      def valid?(context=nil)
-        if errors.any?
-          false
-        else
-          super
-        end
-      end
-
       def can_transition?(event_id)
         event = current_state.find_event(event_id)
         return false unless event
@@ -43,8 +39,10 @@ module Workflow
         return false unless to
 
         within_transition(from, to.name, event_id) do
-          valid?
+          return valid?
         end
+      ensure
+        errors.clear
       end
 
       ###
@@ -78,6 +76,37 @@ module Workflow
         end
       end
 
+      # Override for ActiveRecord::Validations#valid?
+      # Since we are validating inside of a transition,
+      # We need to be able to maintain the errors list for the object
+      # through future valid? calls or the list will be cleared
+      # next time valid? is called.
+      #
+      # Once any attributes have changed on the object, the following call to {#valid?}
+      # will cause revalidation.
+      #
+      # Note that a change on an association will not trigger a reset,
+      # meaning that one should call `errors.clear` before {#valid?} will
+      # trigger validations to run anew.
+      module RevalidateOnlyAfterAttributesChange
+        def valid?(context=nil)
+          if errors.any? && !@changed_since_validation
+            false
+          else
+            begin
+              return super
+            ensure
+              @changed_since_validation = false
+            end
+          end
+        end
+
+        def write_attribute(attr_name, value)
+          @changed_since_validation = true
+          super
+        end
+      end
+
       module ClassMethods
         def halt_transition_unless_valid!
           before_transition unless: :valid? do |model|

data/lib/workflow/callbacks.rb

@@ -1,3 +1,6 @@
+require 'workflow/callbacks/callback'
+require 'workflow/callbacks/transition_callback_wrapper'
+
 module Workflow
   module Callbacks
 
@@ -23,6 +26,42 @@ module Workflow
     end
 
     module ClassMethods
+      def ensure_after_transitions(name=nil, **opts, &block)
+        _ensure_procs  = [name, block].compact.map do |exe|
+          Callback.new(exe)
+        end
+
+        prepend_around_transition **opts do |obj, callbacks|
+          begin
+            callbacks.call()
+          ensure
+            _ensure_procs.each {|l| l.callback.call obj, ->{}}
+          end
+        end
+      end
+
+      def on_error(error_class=Exception, **opts, &block)
+        _error_procs  = [opts.delete(:rescue)].compact.map do |exe|
+          Callback.new(exe)
+        end
+
+        _ensure_procs = [opts.delete(:ensure)].compact.map do |exe|
+          Callback.new(exe)
+        end
+
+        prepend_around_transition **opts do |obj, callbacks|
+          begin
+            callbacks.call
+          rescue error_class => ex
+            self.instance_exec(ex, &block) if block_given?
+            # block.call(ex) if block_given?
+            _error_procs.each {|l| l.callback.call self, ->{}}
+          ensure
+            _ensure_procs.each {|l| l.callback.call self, ->{}}
+          end
+        end
+      end
+
       ##
       # @!method before_transition
       #
@@ -207,13 +246,13 @@ module Workflow
         CALLBACK_MAP.each do |type, context_attribute|
           define_method "#{callback}_#{type}" do |*names, &blk|
             _insert_callbacks(names, context_attribute, blk) do |name, options|
-              set_callback(type, callback, name, options)
+              set_callback(type, callback, TransitionCallbackWrapper.build_wrapper(callback, name), options)
             end
           end
 
           define_method "prepend_#{callback}_#{type}" do |*names, &blk|
             _insert_callbacks(names, context_attribute, blk) do |name, options|
-              set_callback(type, callback, name, options.merge(prepend: true))
+              set_callback(type, callback, TransitionCallbackWrapper.build_wrapper(callback, name), options.merge(prepend: true))
             end
           end
 
@@ -221,7 +260,7 @@ module Workflow
           # for details on the allowed parameters.
           define_method "skip_#{callback}_#{type}" do |*names|
             _insert_callbacks(names, context_attribute) do |name, options|
-              skip_callback(type, callback, name, options)
+              skip_callback(type, callback, TransitionCallbackWrapper.build_wrapper(callback, name), options)
             end
           end
 
@@ -230,6 +269,16 @@ module Workflow
         end
       end
 
+      def applicable_callback?(callback, procedure)
+        arity = procedure.arity
+        return true if arity < 0 || arity > 2
+        if [:key, :keyreq, :keyrest].include? procedure.parameters[-1][0]
+          return true
+        else
+          return false
+        end
+      end
+
       private
       def _insert_callbacks(callbacks, context_attribute, block = nil)
         options = callbacks.extract_options!
@@ -259,6 +308,7 @@ module Workflow
     private
     #  TODO: Do something here.
     def halted_callback_hook(filter)
+      # byebug
     end
 
     def run_all_callbacks(&block)

data/lib/workflow/callbacks/callback.rb

@@ -0,0 +1,85 @@
+module Workflow
+  module Callbacks
+    #
+    #  Receives an expression and generates a lambda that can be called against
+    #  an object, for use in callback logic.
+    #
+    #  Adapted from ActiveSupport::Callbacks
+    #  https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L296
+    class Callback
+      include Comparable
+
+      attr_reader :expression, :callback
+      def initialize(expression, inverted=false)
+        @expression = expression
+        @callback     = make_lambda(expression)
+        if inverted
+          @callback = invert_lambda(@callback)
+        end
+      end
+
+      def call(target)
+        callback.call(target, ->{})
+      end
+
+      def self.build_inverse(expression)
+        new expression, true
+      end
+
+      private
+
+      def invert_lambda(l)
+        lambda { |*args, &blk| !l.call(*args, &blk) }
+      end
+
+      # Filters support:
+      #
+      #   Symbols:: A method to call.
+      #   Strings:: Some content to evaluate.
+      #   Procs::   A proc to call with the object.
+      #   Objects:: An object with a <tt>before_foo</tt> method on it to call.
+      #
+      # All of these objects are converted into a lambda and handled
+      # the same after this point.
+      def make_lambda(filter)
+        case filter
+        when Symbol
+          lambda { |target, _, &blk| target.send filter, &blk }
+        when String
+          l = eval "lambda { |value| #{filter} }"
+          lambda { |target, value| target.instance_exec(value, &l) }
+        # when Conditionals::Value then filter
+        when ::Proc
+          if filter.arity > 1
+            return lambda { |target, _, &block|
+              raise ArgumentError unless block
+              target.instance_exec(target, block, &filter)
+            }
+          end
+
+          if filter.arity <= 0
+            lambda { |target, _| target.instance_exec(&filter) }
+          else
+            lambda { |target, _| target.instance_exec(target, &filter) }
+          end
+        else
+          scopes = Array(chain_config[:scope])
+          method_to_call = scopes.map{ |s| public_send(s) }.join("_")
+
+          lambda { |target, _, &blk|
+            filter.public_send method_to_call, target, &blk
+          }
+        end
+      end
+
+      def compute_identifier(filter)
+        case filter
+        when String, ::Proc
+          filter.object_id
+        else
+          filter
+        end
+      end
+    end
+  end
+end

data/lib/workflow/callbacks/transition_callback_wrapper.rb

@@ -0,0 +1,100 @@
+module Workflow
+  module Callbacks
+    class TransitionCallbackWrapper
+      attr_reader :callback_type, :raw_proc
+      def initialize(callback_type, raw_proc)
+        @callback_type = callback_type
+        @raw_proc      = raw_proc
+      end
+
+      def self.build_wrapper(callback_type, raw_proc)
+        if raw_proc.kind_of? ::Proc
+          new(callback_type, raw_proc).wrapper
+        else
+          raw_proc
+        end
+      end
+
+      def wrapper
+        arguments = [
+          name_arguments_string,
+          rest_param_string,
+          kw_arguments_string,
+          keyrest_string,
+          procedure_string].compact.join(', ')
+
+        raw_proc = self.raw_proc
+        str = <<-EOF
+          Proc.new do |target#{', callbacks' if around_callback?}|
+            attributes = transition_context.attributes.dup
+            target.instance_exec(#{arguments})
+          end
+        EOF
+        eval(str)
+      end
+
+      private
+
+      def around_callback?
+        callback_type == :around
+      end
+
+      def name_arguments_string
+        params = name_params
+        names  = []
+        names << 'target'   if params.shift
+        (names << 'callbacks') && params.shift if around_callback?
+        names += params.map{|t| "transition_context.#{t}"}
+        return names.join(', ') if names.any?
+      end
+
+      def kw_arguments_string
+        params = kw_params.map do |name|
+          "#{name}: attributes.delete(#{name.inspect})"
+        end
+        params.join(', ') if params.any?
+      end
+
+      def keyrest_string
+        '**attributes' if keyrest_param
+      end
+
+      def rest_param_string
+        '*transition_context.event_args' if rest_param
+      end
+
+      def procedure_string
+        '&raw_proc'
+      end
+
+      def name_params
+        params_by_type :opt, :req
+      end
+
+      def kw_params
+        params_by_type :keyreq, :keyopt
+      end
+
+      def keyrest_param
+        params_by_type(:keyrest).first
+      end
+
+      def rest_param
+        params_by_type(:rest).first
+      end
+
+      def params_by_type(*types)
+        parameters.select do |type, name|
+          types.include? type
+        end.map(&:last)
+      end
+
+      def parameters
+        raw_proc.parameters
+      end
+      def arity
+        raw_proc.arity
+      end
+    end
+  end
+end

data/lib/workflow/event.rb

@@ -44,7 +44,6 @@ module Workflow
     end
 
     class Conditions #:nodoc:#
-
       def initialize(**options, &block)
         @if      = Array(options[:if])
         @unless  = Array(options[:unless])
@@ -57,72 +56,15 @@ module Workflow
       end
 
       def apply?(target)
-        # TODO: Remove the second parameter from the conditions below.
-        @conditions_lambdas.all?{|l| l.call(target, ->(){})}
+        @conditions_lambdas.all?{|l| l.call(target)}
       end
 
       private
 
-      # Copied from https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L366
-      def invert_lambda(l)
-        lambda { |*args, &blk| !l.call(*args, &blk) }
-      end
-
-      # Filters support:
-      #
-      #   Symbols:: A method to call.
-      #   Strings:: Some content to evaluate.
-      #   Procs::   A proc to call with the object.
-      #   Objects:: An object with a <tt>before_foo</tt> method on it to call.
-      #
-      # All of these objects are converted into a lambda and handled
-      # the same after this point.
-      # Copied from https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L379
-      def make_lambda(filter)
-        case filter
-        when Symbol
-          lambda { |target, _, &blk| target.send filter, &blk }
-        when String
-          l = eval "lambda { |value| #{filter} }"
-        lambda { |target, value| target.instance_exec(value, &l) }
-        # when Conditionals::Value then filter
-        when ::Proc
-          if filter.arity > 1
-            return lambda { |target, _, &block|
-              raise ArgumentError unless block
-              target.instance_exec(target, block, &filter)
-            }
-          end
-
-          if filter.arity <= 0
-            lambda { |target, _| target.instance_exec(&filter) }
-          else
-            lambda { |target, _| target.instance_exec(target, &filter) }
-          end
-        else
-          scopes = Array(chain_config[:scope])
-          method_to_call = scopes.map{ |s| public_send(s) }.join("_")
-
-          lambda { |target, _, &blk|
-            filter.public_send method_to_call, target, &blk
-          }
-        end
-      end
-
-      # From https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L410
-      def compute_identifier(filter)
-        case filter
-        when String, ::Proc
-          filter.object_id
-        else
-          filter
-        end
-      end
-
       # From https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L419
       def conditions_lambdas
-        @if.map { |c| make_lambda c } +
-          @unless.map { |c| invert_lambda make_lambda c }
+        @if.map { |c| Callbacks::Callback.new c } +
+          @unless.map { |c| Callbacks::Callback.new c, true }
       end
     end
   end

data/lib/workflow/specification.rb

@@ -42,7 +42,7 @@ module Workflow
         state.events.each do |event|
           event.transitions.each do |transition|
             target_state = spec.find_state(transition.target_state)
-            unless target_state.present?
+            if target_state.nil?
               raise Workflow::Errors::WorkflowDefinitionError.new("Event #{event.name} transitions to #{transition.target_state} but there is no such state.")
             end
             transition.target_state = target_state
@@ -117,9 +117,9 @@ module Workflow
     # end
     #
     # a = Article.new
-    # a.process_event! :foo
+    # a.transition! :foo
     # a.current_state.name          # => :bax
-    # a.process_event! :revert_bar
+    # a.transition! :revert_bar
     # a.current_state.name          # => :foo
     #```
     def define_revert_events!

data/lib/workflow/version.rb

@@ -1,3 +1,3 @@
 module Workflow
-  VERSION = "1.4.1.2"
+  VERSION = "1.4.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-workflow
 version: !ruby/object:Gem::Version
-  version: 1.4.1.2
+  version: 1.4.1.3
 platform: ruby
 authors:
 - Tyler Gannon
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-22 00:00:00.000000000 Z
+date: 2016-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -219,6 +219,8 @@ files:
 - lib/workflow/adapters/active_record_validations.rb
 - lib/workflow/adapters/remodel.rb
 - lib/workflow/callbacks.rb
+- lib/workflow/callbacks/callback.rb
+- lib/workflow/callbacks/transition_callback_wrapper.rb
 - lib/workflow/configuration.rb
 - lib/workflow/draw.rb
 - lib/workflow/errors.rb