flow_machine 0.1.0

data/lib/flow_machine/workflow_state.rb

@@ -0,0 +1,162 @@
+require "active_support/core_ext/module/delegation"
+require "active_support/inflector"
+
+class FlowMachine::WorkflowState
+  attr_reader :workflow
+  attr_accessor :guard_errors
+
+  delegate :object, :options, to: :workflow
+
+  module ClassMethods
+    attr_accessor :state_callbacks
+    attr_accessor :expose_to_workflow_methods
+
+    def state_name
+      name.demodulize.sub(/State\z/, '').underscore.to_sym
+    end
+
+    # Maintains a list of methods that should be exposed to the workflow
+    # the workflow is responsible for reading this list
+    def expose_to_workflow(name)
+      self.expose_to_workflow_methods ||= []
+      self.expose_to_workflow_methods << name
+    end
+
+    def event(name, options = {}, &block)
+      define_may_event(name, options)
+      define_event(name, options, &block)
+      define_event_bang(name)
+    end
+
+    private
+
+    def define_event(name, options, &block)
+      define_method name do |*args|
+        return false unless self.send("may_#{name}?")
+        instance_exec *args, &block
+      end
+      expose_to_workflow name
+    end
+
+    def define_may_event(name, options)
+      define_method "may_#{name}?" do
+        run_guard_methods([*options[:guard]])
+      end
+      expose_to_workflow "may_#{name}?"
+    end
+
+    def define_event_bang(name)
+      define_method "#{name}!" do |*args|
+        workflow.persist if self.send(name, *args)
+      end
+      expose_to_workflow "#{name}!"
+    end
+  end
+  extend ClassMethods
+
+  # Callbacks may be a symbol method name on the state, workflow, or underlying object,
+  # and will look for that method on those objects in that order. You may also
+  # use a block.
+  # Callbacks will accept :if and :unless options, which also may be method name
+  # symbols or blocks. The option accepts an array meaning all methods must return
+  # true (for if) and false (for unless)
+  #
+  # class ExampleState < Workflow::State
+  #   on_enter :some_method, if: :allowed?
+  #   after_enter :after_enter_method, if: [:this_is_true?, :and_this_is_true?]
+  #   before_change(:field_name) { do_something }
+  # end
+  #
+  module CallbackDsl
+    # Called when the workflow `transition`s to the state
+    def on_enter(*args, &block)
+      add_callback(:on_enter, FlowMachine::StateCallback.new(*args, &block))
+    end
+
+    # Called after `persist` when the workflow transitioned into this state
+    def after_enter(*args, &block)
+      add_callback(:after_enter, FlowMachine::StateCallback.new(*args, &block))
+    end
+
+    # Happens before persistence if the field on the object has changed
+    def before_change(field, *args, &block)
+      add_callback(:before_change, FlowMachine::ChangeCallback.new(field, *args, &block))
+    end
+
+    # Happens after persistence if the field on the object has changed
+    def after_change(field, *args, &block)
+      add_callback(:after_change, FlowMachine::ChangeCallback.new(field, *args, &block))
+    end
+
+    private
+
+    def add_callback(hook, callback)
+      self.state_callbacks ||= {}
+      state_callbacks[hook] ||= []
+      state_callbacks[hook] << callback
+    end
+  end
+  extend CallbackDsl
+
+  def initialize(workflow)
+    @workflow = workflow
+    @guard_errors = []
+  end
+
+  def fire_callback_list(callbacks, changes = {})
+    callbacks.each do |callback|
+      callback.call(self, changes)
+    end
+  end
+
+  def fire_callbacks(event, changes = {})
+    return unless self.class.state_callbacks.try(:[], event)
+    fire_callback_list self.class.state_callbacks[event], changes
+  end
+
+  # Allows method calls to fallback up the object chain so
+  # guards and other methods can be defined on the object or workflow
+  # as well as the state
+  def run_workflow_method(method_name, *args, &block)
+    if target = object_chain(method_name)
+      target.send(method_name, *args, &block)
+    else
+      raise NoMethodError.new("undefined method #{method_name}", method_name)
+    end
+  end
+
+  def transition(options = {})
+    workflow.transition(options).tap do |new_state|
+      new_state.fire_callbacks(:on_enter) if new_state
+    end
+  end
+
+  def name
+    self.class.state_name
+  end
+
+  def ==(other)
+    self.class == other.class
+  end
+
+  private
+
+  def run_guard_methods(guard_methods)
+    self.guard_errors = []
+    # Use inject to ensure that all guard methods are run.
+    # all? short circuits on first false value
+    guard_methods.inject(true) do |valid, guard_method|
+      if self.run_workflow_method(guard_method)
+        valid
+      else
+        self.guard_errors << guard_method
+        false
+      end
+    end
+    #
+  end
+
+  def object_chain(method_name)
+    [self, workflow, object].find { |o| o.respond_to?(method_name, true) }
+  end
+end

data/lib/tasks/workflow_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :workflow do
+#   # Task goes here
+# end

data/spec/flow_machine/factory_spec.rb

@@ -0,0 +1,48 @@
+RSpec.describe FlowMachine::Factory do
+  class TestClass; end
+
+  class TestClassWorkflow
+    include FlowMachine::Workflow
+  end
+
+  describe '.workflow_class_for' do
+    subject(:workflow_class) { described_class.workflow_class_for(target) }
+
+    describe 'with a class' do
+      let(:target) { TestClass }
+      it { should eq(TestClassWorkflow) }
+    end
+
+    describe 'with an object' do
+      let(:target) { TestClass.new }
+      it { should eq(TestClassWorkflow) }
+    end
+  end
+
+  describe '.workflow_for' do
+    subject(:workflow) { described_class.workflow_for(target) }
+    class SomeNewClass; end
+
+    describe 'not found' do
+      let(:target) { SomeNewClass.new }
+      it { should be_nil }
+    end
+
+    describe 'with an object' do
+      let(:target) { TestClass.new }
+      it { should be_an_instance_of(TestClassWorkflow) }
+      its(:object) { should eq(target) }
+    end
+
+    describe 'with an array of objects' do
+      let(:target) { [TestClass.new, TestClass.new] }
+      it { should match [an_instance_of(TestClassWorkflow), an_instance_of(TestClassWorkflow)] }
+    end
+  end
+
+  describe '.workflow_for_collection' do
+    subject(:result) { described_class.workflow_for_collection(target) }
+    let(:target) { [TestClass.new, TestClass.new] }
+    it { should match [an_instance_of(TestClassWorkflow), an_instance_of(TestClassWorkflow)] }
+  end
+end

data/spec/flow_machine/multiple_workflow_spec.rb

@@ -0,0 +1,37 @@
+RSpec.describe FlowMachine::Workflow do
+  let(:state_class1) do
+    Class.new(FlowMachine::WorkflowState) do
+      def self.state_name; :state1; end
+      event :event1
+    end
+  end
+
+  let(:state_class2) do
+    Class.new(FlowMachine::WorkflowState) do
+      def self.state_name; :state2; end
+      event :event2
+    end
+  end
+
+  let(:workflow_class1) { Class.new }
+  let(:workflow_class2) { Class.new }
+
+  before do
+    workflow_class1.include described_class
+    workflow_class2.include described_class
+    workflow_class1.state state_class1
+    workflow_class2.state state_class2
+  end
+
+  context 'class1' do
+    subject { workflow_class1.new(double) }
+    it { should respond_to 'event1' }
+    it { should_not respond_to 'event2' }
+  end
+
+  context 'class2' do
+    subject { workflow_class2.new(double) }
+    it { should_not respond_to 'event1' }
+    it { should respond_to 'event2' }
+  end
+end

data/spec/flow_machine/workflow_callback_spec.rb

@@ -0,0 +1,131 @@
+RSpec.describe FlowMachine::Callback do
+  let(:object) { double }
+
+  describe 'callback with method' do
+    let(:callback) { described_class.new(:some_method) }
+
+    it 'calls the method' do
+      expect(object).to receive(:some_method)
+      callback.call(object)
+    end
+  end
+
+  describe 'callback with block' do
+    let(:callback) do
+      described_class.new { some_method }
+    end
+
+    it 'calls the method' do
+      expect(object).to receive(:some_method)
+      callback.call(object)
+    end
+
+  end
+
+  describe 'callback with if' do
+    context 'a single if' do
+      let(:callback) { described_class.new(:some_method, if: :if_method?) }
+
+      context 'if method returns true' do
+        before { allow(object).to receive(:if_method?).and_return true }
+        it 'calls the method' do
+          expect(object).to receive(:some_method)
+          callback.call(object)
+        end
+      end
+
+      context 'if method returns false' do
+        before { allow(object).to receive(:if_method?).and_return false }
+        it 'does not call the method' do
+          expect(object).not_to receive(:some_method)
+          callback.call(object)
+        end
+      end
+    end
+
+    context 'a lambda for if' do
+      let(:callback) do
+        described_class.new(:some_method, if: -> { if_method? })
+      end
+
+      it 'calls the method when true' do
+        allow(object).to receive(:if_method?).and_return true
+        expect(object).to receive(:some_method)
+        callback.call(object)
+      end
+
+      it 'does not call the method when false' do
+        allow(object).to receive(:if_method?).and_return false
+        expect(object).not_to receive(:some_method)
+        callback.call(object)
+      end
+    end
+
+    context 'an array of ifs' do
+      let(:callback) { described_class.new(:some_method, if: [:if_method?, :if2?]) }
+      context 'both return true' do
+        before :each do
+          allow(object).to receive(:if_method?).and_return true
+          allow(object).to receive(:if2?).and_return true
+        end
+        it 'calls the method' do
+          expect(object).to receive(:some_method)
+          callback.call(object)
+        end
+      end
+
+      context 'one returns false' do
+        before :each do
+          allow(object).to receive(:if_method?).and_return true
+          allow(object).to receive(:if2?).and_return false
+        end
+
+        it 'does not call the method' do
+          expect(object).to receive(:some_method).never
+          callback.call(object)
+        end
+      end
+    end
+  end
+
+  describe 'callback with unless' do
+    context 'a single if' do
+      let(:callback) { described_class.new(:some_method, unless: :unless_method?) }
+
+      context 'unless method returns false' do
+        before { allow(object).to receive(:unless_method?).and_return false }
+
+        it 'calls the method' do
+          expect(object).to receive(:some_method)
+          callback.call(object)
+        end
+      end
+
+      context 'unless method returns true' do
+                before { allow(object).to receive(:unless_method?).and_return true }
+        it 'does not call the method' do
+          expect(object).to receive(:some_method).never
+          callback.call(object)
+        end
+      end
+    end
+
+    context 'a lambda for unless' do
+      let(:callback) do
+        described_class.new(:some_method, unless: -> { unless_method? })
+      end
+
+      it 'calls the method when false' do
+        allow(object).to receive(:unless_method?).and_return false
+        expect(object).to receive(:some_method)
+        callback.call(object)
+      end
+
+      it 'does not call the method when true' do
+        allow(object).to receive(:unless_method?).and_return true
+        expect(object).not_to receive(:some_method)
+        callback.call(object)
+      end
+    end
+  end
+end

data/spec/flow_machine/workflow_change_callback_spec.rb

@@ -0,0 +1,26 @@
+RSpec.describe FlowMachine::ChangeCallback do
+  subject(:callback) { described_class.new(:field, :method, if: :condition?) }
+
+  specify { expect(callback.field).to eq(:field) }
+  specify { expect(callback.method).to eq(:method) }
+  specify { expect(callback.options).to eq({ if: :condition? }) }
+
+  let(:object) { double(condition?: true) }
+  before { allow(object).to receive(:run_workflow_method) { |m| object.send(m) } }
+
+  context 'the field changes' do
+    let(:changes) { { 'field' => [:old, :new] } }
+    it 'calls the method' do
+      expect(object).to receive(:method)
+      callback.call(object, changes)
+    end
+  end
+
+  context 'the field does not change' do
+    let(:changes) { { 'other_field' => [:old, :new] } }
+    it 'does not call the method' do
+      expect(object).to receive(:method).never
+      callback.call(object, changes)
+    end
+  end
+end

data/spec/flow_machine/workflow_spec.rb

@@ -0,0 +1,202 @@
+require 'ostruct'
+
+RSpec.describe FlowMachine::Workflow do
+  class Test1State < FlowMachine::WorkflowState
+    def state_method; end
+  end
+
+  class Test2State < FlowMachine::WorkflowState
+    def state_method; end
+  end
+
+  class TestWorkflow
+    include FlowMachine::Workflow
+    state Test1State
+    state Test2State
+    before_save :before_save_callback
+    after_save :after_save_callback
+    after_transition :after_transition_callback
+    def workflow_method; end
+    def before_save_callback; end
+    def after_save_callback; end
+    def after_transition_callback; end
+  end
+
+  describe 'state_names' do
+    it 'has the state names' do
+      expect(TestWorkflow.state_names).to eq(['test1', 'test2'])
+    end
+
+    it 'has the states in a hash keyed by names' do
+      expect(TestWorkflow.states).to eq({ test1: Test1State, test2: Test2State })
+    end
+  end
+
+  describe 'reading initial state' do
+    subject(:workflow) { TestWorkflow.new(object) }
+    context 'default state field' do
+      let(:object) { double(state: :test1) }
+      it 'has the state' do
+        expect(workflow.current_state_name).to eq(:test1)
+      end
+    end
+
+    context 'with a different state field on the object' do
+      before { TestWorkflow.send(:state_attribute, :status) }
+      # return to default
+      after { TestWorkflow.send(:state_attribute, :state) }
+
+      let(:object) { double(status: :test2) }
+      it 'has the state' do
+        expect(workflow.current_state_name).to eq(:test2)
+      end
+    end
+  end
+
+  describe '#transition' do
+    subject(:workflow) { TestWorkflow.new(object) }
+    let(:object) { double(state: :test1) }
+
+    it 'errors on an invalid state' do
+      expect { workflow.transition to: :invalid }.to raise_error(ArgumentError)
+    end
+
+    it 'changes the state of the object' do
+      expect(object).to receive(:state=).with('test2')
+      workflow.transition to: :test2
+    end
+
+    it 'leaves the state if transitions to itself' do
+      workflow.transition
+      expect(workflow.current_state_name).to eq(:test1)
+      expect(object.state).to eq(:test1)
+    end
+  end
+
+  describe 'transition :after hooks' do
+    subject(:workflow) { TestWorkflow.new(object) }
+    let(:object) { OpenStruct.new(state: :test1, changes: {}, save: true, object_method: true) }
+
+    it 'does not call the :after hook before saving' do
+      expect(workflow).not_to receive(:workflow_method)
+      workflow.transition to: :test2, after: :workflow_method
+    end
+
+    it 'does not calls the :after hook on failure' do
+      expect(workflow).not_to receive(:workflow_method)
+      workflow.transition to: :test1
+      workflow.save
+    end
+
+    it 'calls the :after hook on a state method' do
+      expect_any_instance_of(Test1State).to receive(:state_method)
+      expect_any_instance_of(Test2State).not_to receive(:state_method)
+      workflow.transition to: :test2, after: :state_method
+      workflow.save
+    end
+
+    it 'calls the :after hook on a workflow method' do
+      expect(workflow).to receive(:workflow_method)
+      workflow.transition to: :test2, after: :workflow_method
+      workflow.save
+    end
+
+    it 'calls the :after hook on an object method' do
+      expect(object).to receive(:object_method)
+      workflow.transition to: :test2, after: :object_method
+      workflow.save
+    end
+
+    it 'allows a lambda' do
+      expect_any_instance_of(Test1State).to receive(:state_method)
+      workflow.transition to: :test2, after: ->{ state_method }
+      workflow.save
+    end
+
+    describe 'after_transition hook' do
+      it 'calls the hook on transition' do
+        expect(workflow).to receive(:after_transition_callback)
+        workflow.transition to: :test2
+      end
+
+      it 'does not call for invalid states' do
+        expect(workflow).not_to receive(:after_transition_callback)
+        # Will throw an ArgumentError for invalid state
+        expect { workflow.transition to: :invalid_state }.to raise_error
+      end
+
+      it 'does not call for ending in the same state' do
+        expect(workflow).not_to receive(:after_transition_callback)
+        workflow.transition to: :test1
+      end
+    end
+  end
+
+  describe '#persist' do
+    subject(:workflow) { TestWorkflow.new(object) }
+    let(:object) { OpenStruct.new(state: :test1, changes: {}, save: true) }
+
+    context 'success' do
+      it 'saves the object' do
+        expect(workflow.persist).to be true
+      end
+
+      it 'runs before and after_change hooks' do
+        expect(workflow.current_state).to receive(:fire_callbacks).with(:before_change, {})
+        expect(workflow.current_state).to receive(:fire_callbacks).with(:after_change, {})
+        expect(workflow.persist).to be true
+      end
+
+      it "runs after_enter hooks if it's in a new state" do
+        allow(object).to receive(:changes).and_return({'state' => ['test1', 'test2']})
+        expect(workflow.current_state).to receive(:fire_callbacks).with(:before_change, { 'state' => ['test1', 'test2'] })
+        expect(workflow.current_state).to receive(:fire_callbacks).with(:after_change, { 'state' => ['test1', 'test2'] })
+        expect(workflow.current_state).to receive(:fire_callbacks).with(:after_enter, { 'state' => ['test1', 'test2'] })
+        expect(workflow.persist).to be true
+      end
+
+      it 'runs the before_save callback' do
+        expect(workflow).to receive(:before_save_callback)
+        workflow.persist
+      end
+
+      it 'runs the after_save callback' do
+        expect(workflow).to receive(:after_save_callback)
+        workflow.persist
+      end
+    end
+
+    context 'failure' do
+      before do
+        expect(object).to receive(:save).and_return false
+      end
+
+      it 'does not save the object' do
+        expect(workflow.persist).to be false
+      end
+
+      it 'runs the before_change callback' do
+        expect(workflow.current_state).to receive(:fire_callbacks).with(:before_change, {})
+        expect(workflow.persist).to be false
+      end
+
+      it 'runs the before_save callback' do
+        expect(workflow).to receive(:before_save_callback)
+        workflow.persist
+      end
+
+      it 'does not run the after_save callback' do
+        expect(workflow).to_not receive(:after_save_callback)
+        workflow.persist
+      end
+
+      it 'reverts to the old state' do
+        expect(workflow).to be_test1
+        workflow.transition to: :test2
+        expect(workflow).to be_test2
+        workflow.persist
+        expect(workflow).to be_test1
+      end
+    end
+  end
+end