flow_machine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0e9a4fd3c30a8e7920333c34c4cb23b075648f91
+  data.tar.gz: 6df24793c54c72d1498ab49b40da25b3aa29820f
+SHA512:
+  metadata.gz: 4d287bcf3788aeec09232337a905d8c851065c0e2067455480f95308dd764d8c8567e5b11beadf316919e64ee94c3921ec9d2035afb6c014bc43205820433ae6
+  data.tar.gz: cfc7ec61704bb070cf216704edd496f5d1719f3f4c52c026c6e92dd1de013ea4ab9ce4bdcc72e4bd18eb85a019e1ad2c5ff3536ed76d8a4d65d3c5be2e6b5a7d

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 Table XI. http://www.tablexi.com
+
+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,177 @@
+# FlowMachine
+
+Build finite state machines in a backend-agnostic, class-centric way.
+
+The basic features will work with any PORO, and more features and callbacks are available when used with an ORM like `ActiveRecord` and/or `ActiveModel::Dirty`.
+
+## *Raison d'être*
+
+After exploring several of the existing Ruby state machine options, they all seem too tightly coupled to an ORM models and tend to pollute the object model's code far too much. The goal of this gem is to provide a clean, testable interface for working with a state machine that decouples as much as possible from the model object itself.
+
+## Simple Usage
+
+```ruby
+class BlogPost
+  attr_accessor :state, :title, :body, :author
+
+  def initialize
+    self.state = :draft
+  end
+end
+
+class PublishingWorkflow
+  include FlowMachine::Workflow
+
+  state DraftState
+  state PublishedState
+end
+
+class DraftState < FlowMachine::WorkflowState
+  event :publish do
+    transition to: :published
+  end
+end
+
+class PublishedState < FlowMachine::WorkflowState
+  on_enter :notify_email_author
+
+  def notify_email_author
+    # Send an email
+  end
+end
+```
+
+```ruby
+blog_post = BlogPost.new
+blog_post.author = "author@example.org"
+workflow = PublishingWorkflow.new(blog_post)
+workflow.publish # notify_email_author is called (returns true if successful)
+workflow.published? # => true
+blog_post.state # => :published
+```
+
+
+## `transition!`
+
+If you are using the workflow around an ORM model like ActiveRecord, calling the bang version of the transition will perform the transition and call `save` on the object. This method will return the value returned by `save` (`true`/`false` for ActiveRecord) or `false` if any of the guards fail.
+
+E.g. `workflow.publish!` will transition the object to `published` and call `save` on the object.
+
+## Guards
+
+Guards are used to allow or prevent `event`s from being called. `:guard` accepts a single symbol or an array of symbols representing methods. The method may be on the state, the workflow, or the object itself, and the method will be searched for in that order.
+
+**Best practice** Use predicate methods that return a simple true/false. All guard methods are called, so avoid side affects in these methods.
+
+Calling the transition with a failing guard will result in the object not being transitioned and returning `false`. If using the bang version, `save` will not be called.
+
+#### may_xxx?
+
+`workflow.may_publish?` will call all the guard methods and return `false` if any of the guard methods return `false`. It will also return `false` if you are not in a state that has a defined event (e.g. `published_workflow.may_publish?` will always return `false`)
+
+#### guard_errors
+
+After calling `may_xxx?`, the workflow will have an array of the guard methods that failed. to avoid additional dependencies, the developer is responsible for converting these to human readable messages (using I18n or the like).
+
+```ruby
+class DraftState < FlowMachine::WorkflowState
+  event :publish, guard: [:content_present?, :can_publish?]
+    transition to: :published
+  end
+
+  def can_publish?
+    false
+  end
+end
+
+class BlogPost
+  def content_present?
+    content.present? # assuming you have ActiveSupport loaded
+  end
+end
+```
+
+```ruby
+workflow.may_publish? # => false
+workfow.guard_errors # => [:can_publish?]
+workflow.publish # => false
+```
+
+## Callbacks
+
+State and Workflow callbacks accept `if` and `unless` options. They may be a symbol or array of symbols (looking for the method in the state, workflow, and object in that order) or a Proc.
+
+### State callbacks
+
+Declared in the `WorkflowState` class.
+
+* `on_enter` Called after the object has transitioned into the state
+
+The following are available when `Workflow#save` is used (`workflow.save` or `workflow.transition!`) *Not called if you call `save` directly on the decorated model*.
+
+* `after_enter` Called when the object has transitioned into the state and the object has been saved either `workflow.save` or `workflow.transition!` has been called.
+* `before_change` Useful when watching for changes to a model, but only when in a certain state. Will be called if anything exists in the `object#changes` hash (if it exists), often provided by `ActiveModel#dirty`.
+* `after_change` Useful when watching for changes to a model in a certain state, but you only want to trigger when the save is successful (e.g. the model is `valid?`)
+
+### Workflow callbacks
+
+Declared in the `Workflow` class.
+
+* `after_transition` Called anytime a transition takes place
+
+The following are available when `Workflow#save` is used:
+
+* `before_save` Called when `Workflow#save` is called, but before `object#save` is called
+* `after_save` Called after `object#save` has returned `true`
+
+### Transition callbacks
+
+Declared as an option to the `transition` method inside an `event` block.
+
+* `after` Will be called after the transition has happened successfully. Useful when you only want something to trigger when moving from a specific state to another.
+
+`transition to: :published, after: :send_mailing_list_email`
+
+## Scopes and Predicate methods
+
+If you want scopes and predicate methods defined on your model, use the following:
+
+`PublishingWorkflow.create_scopes_on(self)` within the model.
+
+Assuming BlogPost is an ActiveRecord model, this will create `BlogPost.draft` and `BlogPost.published` scopes as well as the `BlogPost#draft?` and `BlogPost#published?` methods.
+
+## Other useful features
+
+### Use a different attribute for the state
+
+If you don't want to use `state` as your field for storing state, simply declare `state_attribute :status` in the Workflow class.
+
+### List of state names
+
+```ruby
+PublishingWorkflow.state_names` # => ['draft', 'published']
+```
+
+Especially useful in an ActiveModel validation:
+
+```ruby
+validates :state, presence: true, inclusion: { in: PublishingWorkflow.state_names }
+```
+
+### Options Hash
+
+You can pass an options hash into the workflow which is available at any time while using the workflow. A prime example is tracking the user who performed an action.
+
+```ruby
+class PublishedState < FlowMachine::WorkflowState
+  on_enter :update_published_by
+
+  def update_published_by
+    object.published_by = options[:current_user]
+  end
+end
+
+workflow = PublishingWorkflow.new(blog_post, current_user: User.find(123))
+workflow.published
+blog_post.published_by # => User #123
+```

data/Rakefile

@@ -0,0 +1,38 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Workflow'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+end

data/lib/flow_machine.rb

@@ -0,0 +1,12 @@
+$:.unshift(File.dirname(__FILE__))
+
+require "flow_machine/workflow"
+require "flow_machine/factory"
+require "flow_machine/workflow_state"
+require "flow_machine/callback"
+require "flow_machine/state_callback"
+require "flow_machine/change_callback"
+
+module FlowMachine
+end
+

data/lib/flow_machine/callback.rb

@@ -0,0 +1,43 @@
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/array/extract_options'
+
+class FlowMachine::Callback
+  attr_accessor :method, :options
+  def initialize(*args, &block)
+    @options = args.extract_options!
+    @method = args.shift unless block
+    @block = block
+  end
+
+  def call(target, changes = {})
+    return unless will_run? target, changes
+    call!(target)
+  end
+
+  # Runs the callback without any validations
+  def call!(target)
+    run_method_or_lambda(target, method.presence || @block)
+  end
+
+  def run_method_or_lambda(target, method)
+    if method.respond_to? :call # is it a lambda
+      target.instance_exec &method
+    else
+      run_method(target, method)
+    end
+  end
+
+  def run_method(target, method)
+    target.send(method)
+  end
+
+  def will_run?(target, changes = {})
+    if options[:if]
+      [*options[:if]].all? { |m| run_method_or_lambda(target, m) }
+    elsif options[:unless]
+      [*options[:unless]].none? { |m| run_method_or_lambda(target, m) }
+    else
+      true
+    end
+  end
+end

data/lib/flow_machine/change_callback.rb

@@ -0,0 +1,11 @@
+class FlowMachine::ChangeCallback < FlowMachine::StateCallback
+  attr_accessor :field
+  def initialize(field, *args, &block)
+    @field = field
+    super(*args, &block)
+  end
+
+  def will_run?(object, changes = {})
+    changes.keys.include?(field.to_s) && super
+  end
+end

data/lib/flow_machine/factory.rb

@@ -0,0 +1,27 @@
+module FlowMachine
+  class Factory
+    def self.workflow_for(object, options = {})
+      # If the object is enumerable, delegate. This allows workflow_for
+      # as shorthand
+      return workflow_for_collection(object, options) if object.respond_to?(:map)
+
+      klazz = workflow_class_for(object)
+      return nil unless klazz
+      klazz.new(object, options)
+    end
+
+    def self.workflow_for_collection(collection, options = {})
+      collection.map { |item| workflow_for(item, options) }
+    end
+
+    def self.workflow_class_for(object_or_class)
+      if object_or_class.is_a? Class
+        "#{object_or_class.name}Workflow".constantize
+      else
+        workflow_class_for(object_or_class.class)
+      end
+    rescue NameError # if the workflow class doesn't exist
+      nil
+    end
+  end
+end

data/lib/flow_machine/state_callback.rb

@@ -0,0 +1,5 @@
+class FlowMachine::StateCallback < FlowMachine::Callback
+  def run_method(target, method)
+    target.run_workflow_method(method)
+  end
+end

data/lib/flow_machine/version.rb

@@ -0,0 +1,3 @@
+module FlowMachine
+  VERSION = "0.1.0"
+end

data/lib/flow_machine/workflow.rb

@@ -0,0 +1,206 @@
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/try"
+
+module FlowMachine
+  module Workflow
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.send(:attr_reader, :object)
+    end
+
+    module ClassMethods
+      # resolves to
+      # class Model
+      #   def self.published
+      #     where(status: 'published')
+      #   end
+      #
+      #   def published?
+      #     self.status == 'published'
+      #   end
+      # end
+      def create_scopes_on(content_class)
+        self.state_names.each do |status|
+          content_class.singleton_class.send(:define_method, status) do
+            where(status: status)
+          end
+
+          content_class.send(:define_method, "#{status}?") do
+            self.status == status
+          end
+        end
+      end
+
+      attr_accessor :callbacks
+
+      def state_names
+        states.keys.map &:to_s
+      end
+
+      def states
+        @states ||= {}
+      end
+
+      # Mainly to be used in testing, call this method to ensure that
+      # any dynamically created state methods get exposed to the workflow
+      def refresh_state_methods!
+        states.values.each do |state_class|
+          add_state_methods_from(state_class)
+        end
+      end
+
+      def state(state_class)
+        name = get_state_name(state_class)
+        states[name] = state_class
+        add_state_methods_from(state_class)
+
+        define_method "#{name}?" do
+          current_state_name.to_s == name.to_s
+        end
+      end
+
+      def state_attribute(method)
+        @state_attribute = method
+      end
+
+      def state_method
+        @state_attribute || :state
+      end
+
+      def before_save(*args, &block)
+        add_callback(:before_save, FlowMachine::Callback.new(*args, &block))
+      end
+
+      def after_save(*args, &block)
+        add_callback(:after_save, FlowMachine::Callback.new(*args, &block))
+      end
+
+      def after_transition(*args, &block)
+        add_callback(:after_transition, FlowMachine::Callback.new(*args, &block))
+      end
+
+      private
+
+      def add_callback(hook, callback)
+        self.callbacks ||= {}
+        callbacks[hook] ||= []
+        callbacks[hook] << callback
+      end
+
+      # Defines an instance method on Workflow that delegates to the
+      # current state, but only if the current_state implements the method
+      def define_state_method(method_name)
+        define_method method_name do |*args|
+          current_state.respond_to?(method_name) && current_state.send(method_name, *args)
+        end
+      end
+
+      def add_state_methods_from(state_class)
+        state_class.expose_to_workflow_methods.try(:each) do |method_name|
+          define_state_method(method_name) unless method_defined?(method_name)
+        end
+      end
+
+      def get_state_name(state_class)
+        state_class.state_name
+      end
+    end
+
+    attr_accessor :options, :previous_state_persistence_callbacks, :previous_state
+    attr_accessor :changes
+
+    # extend Forwardable
+    # def_delegators :current_state, :guard_errors
+    delegate :guard_errors, to: :current_state
+
+    def initialize(object, options = {})
+      @object = object
+      @options = options
+      @previous_state_persistence_callbacks = []
+    end
+
+    def current_state_name
+      object.send(self.class.state_method)
+    end
+    alias_method :state, :current_state_name
+
+    def previous_state_name
+      @previous_state.try(:name)
+    end
+
+    def current_state
+      @current_state ||= self.class.states[current_state_name.to_sym].new(self)
+    end
+
+    def transition(options = {})
+      @previous_state = current_state
+      @current_state = nil
+      self.current_state_name = options[:to].to_s if options[:to]
+      @previous_state_persistence_callbacks << FlowMachine::StateCallback.new(options[:after]) if options[:after]
+      fire_callbacks(:after_transition) unless previous_state == current_state
+      current_state
+    end
+
+    def save
+      persist
+    end
+
+    def persist
+      self.changes = object.changes
+      # If the model has a default state from the database, then it doesn't get
+      # included in `changes` when you're first saving it.
+      self.changes[state_method.to_s] ||= [nil, current_state_name] if object.new_record?
+
+      fire_callbacks(:before_save)
+      current_state.fire_callbacks(:before_change, changes)
+
+      if persist_object
+        fire_state_callbacks
+        fire_callbacks(:after_save)
+        true
+      else
+        self.current_state_name = @previous_state.name.to_s if @previous_state
+        false
+      end
+    end
+
+    # Useful for using in if/unless on state and after_save callbacks so you can
+    # run the callback only on the initial persistence
+    def create?
+      self.changes[state_method.to_s].try(:first).blank?
+    end
+
+    def persist_object
+      object.save
+    end
+
+    def current_state_name=(new_state)
+      raise ArgumentError.new("invalid state: #{new_state}") unless self.class.state_names.include?(new_state.to_s)
+      object.send("#{self.class.state_method}=", new_state)
+    end
+
+    def current_user
+      options[:current_user]
+    end
+
+    private
+
+    def fire_callbacks(event)
+      self.class.callbacks ||= {}
+      self.class.callbacks[event].try(:each) do |callback|
+        callback.call(self, changes)
+      end
+    end
+
+    def fire_state_callbacks
+      previous_state.fire_callback_list(previous_state_persistence_callbacks) if previous_state
+      @previous_state_persistence_callbacks = []
+      current_state.fire_callbacks(:after_enter, changes) if changes.include? state_method.to_s
+      current_state.fire_callbacks(:after_change, changes)
+    end
+
+    def state_method
+      self.class.state_method
+    end
+  end
+end