w_flow 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 30c37c21823d83b687e0751155b7bb9a353233ff
-  data.tar.gz: 4cfb08e1e2966154536b8746e5d60e5db25208f8
+  metadata.gz: 4c6971610a0278716309118842acdfd7532ed202
+  data.tar.gz: bbda595555d7dcc881280bd7369d1456c8561ff6
 SHA512:
-  metadata.gz: 337e619cfbffce4225809913df1a0843f87312c3125e4826e35612799625583278ec9467c7952b86e3f2724027e7d54b94e7dc366baa0bee2bd89f35e6f5ebd0
-  data.tar.gz: bd40ac136446646d0985ee0bc4f4ed92c37a56fc70c41380803275a2318d8aa85e14f38b363c963fde4754a421c18772b105ad8f235b0dee1365cfd23b04be92
+  metadata.gz: 2012a6ea13452f2dc30418ea861fe8f54b5dcb30723cf8aa4a372835b25a9713670695ec4efee5a187b70885f40830e15fe9ddf62c0d85d9ff8c994915c4404d
+  data.tar.gz: fca65b36b9966e01f743fe9619b9477e5200ff96ddf2b23100749d2101b6a26a15a1550cac133067c3a843a52dc9ec81e5782a120e88b3b86480055e52a1f575

data/README.md

@@ -8,8 +8,7 @@
 
 WFlow aims to help on designing workflows based on [Single
 Responsibility Principle](http://en.wikipedia.org/wiki/Single_responsibility_principle). WFlow
-proposes to achieve this by providing tools to build classes where each are responsible for a task
-and one task only, and by providing tools to compose these classes.
+proposes to achieve this by providing tools to help compose those classes into a workflow.
 
 Word of appreciation for [usecasing](https://github.com/tdantas/usecasing),
 [interactor](https://github.com/collectiveidea/interactor) and
@@ -40,66 +39,139 @@ Or install it yourself as:
 
 ## Usage
 
-Imagine a situation where we want to update an appointment, notify the user of that update,
-and publish it in google calendar if needed:
+In its most simplest form a Process would look like this:
 
 ```ruby
-class Find
+# Process to retrive a user from the database given a user_id
+class FindUser
+  # include module Process
   include WFlow::Process
 
-  # helper for flow.data
-  data_reader :appointment_id
-  data_writer :appointment
-
-  # perform is the name of the method that will be invoked when calling 'run'
+  # perform is where you'll execute your business logic
   def perform
-    self.appointment = Appointment.find(appointment_id)
+    # flow is an object present in a Process, and it is how you retrieve data
+    # from the current flow, in this case the input user_id
+    user_id = flow.data.user_id
 
-    # the previous code is the same as:
-    # flow.data.appointment = Appointment.find(flow.data.appointment_id)
+    # when you want to output a value from the Process you set it in data
+    flow.data.user = User.find(user_id)
   end
 end
+```
 
-class UpdateAppointment
-  include WFlow::Process
+And you invoke it like this:
+
+```ruby
+# run will returns a report object
+report = FindUser.run(user_id: 10)
 
-  execute Find, Update, NotifyUser
+# this report object will contain the output from the Process
+report.data.user
+```
 
-  execute PublishInGoogleCalendar, if: :publish_in_google_calendar?
+This and any other Process can be used to compose a workflow, so lets try that:
 
-protected
+```ruby
+class SendWelcomeEmail
+  include WFlow::Process
+
+  # use previously created Process to find the user
+  execute FindUser
 
-  def publish_in_google_calendar?
-    flow.data.appointment.synch_in_google_calendar?
+  def perform
+    # code to send email to user
   end
 end
 
-# imagining that we have the id of the appointment to be updated and the new attributes for the appointment
-report = UpdateAppointment.run(appointment_id: appointment_id, attributes: new_attributes)
-
-# ask if workflow was a success
-report.success?
+report = SendWelcomeEmail.run(user_id: 10)
 ```
 
-So what's going on here? We first declare a class and included the module WFlow::Process, so that
-we can compose the workflow for this process:
+Processes passed to execute will be called before the perform method. You can
+have as any execute as you want and as many Processes (and method nomes and Procs) in a execute.
+This means that when you run SendWelcomeEmail process, it will first execute FindUser which will
+set the user under flow.data, and than you can use that user to get the email address
+for where to send the email.
+
+So far so good, but lets go back to FindUser. Looking at it, we are currently not accounting for
+errors cases, like what should happen when we can't find an user, or when the connection to the
+database fails? This depends on what you want to do, but for this example we'll raise a flow failure,
+and we'll also simplify the code a bit using data helpers:
 
 ```ruby
-class UpdateAppointment
+class FindUser
   include WFlow::Process
+
+  # helper methods to access attributes under flow.data
+  data_reader   :user_id
+  data_accessor :user
+
+  def perform
+    self.user = User.find(user_id)
+  rescue
+    # you can pass whatever you want to the failure! method (or even call it without arguments)
+    # passed value will be available in returned report under failure_log
+    flow.failure!('unable to find user')
+  end
+end
+
+report = FindUser.run(user_id: 10)
+
+# check if success
+unless report.success? # there's also a report.failure?
+  # failure_log is an array that contains all the objects passed to failure!
+  report.failure_log.each do |log|
+    puts log
+  end
+end
 ```
 
-Now we can start composing. We compose by reusing other processes like this:
+Invoking failure! will interrupt a workflow immediatly. This means that if you run
+SendWelcomeEmail for a non existing user it will never run the code under perform (which
+is a good thing, since there's no one to send the email to). But what if we want to do
+something more even in case of failure? You can pass a handler for that:
 
 ```ruby
-  # this indicates that it will first Find, Update next and NotifyUser last
-  execute Find, Update, NotifyUser
+class SendWelcomeEmail
+  include WFlow::Process
+
+  attr_writer :admin_email
+
+  # you can pass a name or a proc as a failure handler, which will be called if one
+  # of the Processes in execute chain raises a flow failure
+  execute FindUser, failure: :on_failure
+
+  # we'll use an if handler (there's also an unless handler), which allows us to control if a execute chain
+  # should be executed or not
+  execute :compose_email, SendMessageToAdmin, -> { flow.failure! }, if: -> { @no_user_found }
+
+  def perform
+    # ...
+  end
+
+protected
 
-  # execute this process, only if method returns true
-  execute PublishInGoogleCalendar, if: :publish_in_google_calendar?
+  # failure handler, return false to cancel failure, or true to let Process fail
+  def on_failure
+    @no_user_found = true
+
+    false
+  end
+
+  def compose_email
+    self.admin_email = "we were unable to find user :("
+  end
+end
 ```
 
-TODO: more documentation
+Wow it suddenly become complex, but it reflects a more realistic situation. So what's
+going on? First we try to find the user, which will raise a flow failure if no user
+is found. In this case we want to inform the admin that something went wrong, so instead of allowing
+the flow to be interrupted right away, we return false in the failure handler to cancel failure.
+After that, the second execute chain will be executed, because @no_user_found is set to true. This
+execution chain will invoke the method compose_email, SendMessageToAdmin, and than
+call proc that reraises failure.
+
+This is some of the features of WFlow, please check [wiki](https://github.com/junhanamaki/w_flow/wiki) for more details.
 
 ## Contributing
 

data/lib/w_flow/configuration.rb

@@ -1,5 +1,6 @@
 module WFlow
   class Configuration
+
     attr_reader :supress_errors
 
     class << self
@@ -25,5 +26,6 @@ module WFlow
     def initialize
       @supress_errors = false
     end
+
   end
 end

data/lib/w_flow/data.rb

@@ -1,5 +1,6 @@
 module WFlow
   class Data
+
     def initialize(data)
       @data = data
     end
@@ -15,5 +16,6 @@ module WFlow
         @data[method_name.to_sym]
       end
     end
+
   end
 end

data/lib/w_flow/node.rb

@@ -3,115 +3,15 @@ module WFlow
 
     class << self
 
-      attr_reader :components,
-                  :if_condition,
-                  :unless_condition,
-                  :stop_condition,
-                  :failure_condition,
-                  :around_handler
+      attr_reader :tasks, :options
 
-      def build(components, options)
+      def build(tasks, options)
         Class.new(self) do |klass|
-          @components        = components
-          @if_condition      = options[:if]
-          @unless_condition  = options[:unless]
-          @stop_condition    = options[:stop]
-          @failure_condition = options[:failure]
-          @around_handler    = options[:around]
+          @tasks   = tasks
+          @options = options
         end
       end
 
-      def execute?(process)
-        (if_condition.nil?     || process_eval(process, if_condition)) &&
-        (unless_condition.nil? || !process_eval(process, unless_condition))
-      end
-
-      def cancel_stop?(process)
-        !stop_condition.nil? && !process_eval(process, stop_condition)
-      end
-
-      def cancel_failure?(process)
-        !failure_condition.nil? && !process_eval(process, failure_condition)
-      end
-
-      def process_eval(process, object, *args)
-        if object.is_a?(String) || object.is_a?(Symbol)
-          process.send(object.to_s, *args)
-        elsif object.is_a?(Proc)
-          process.instance_exec(*args, &object)
-        else
-          raise InvalidArguments, UNKNOWN_EXPRESSION
-        end
-      end
-
-    end
-
-    def initialize(owner_process)
-      @owner_process     = owner_process
-      @components        = self.class.components
-      @around_handler    = self.class.around_handler
-    end
-
-    def run(flow)
-      @flow             = flow
-      @execution_chains = []
-
-      if @around_handler.nil?
-        execute_components
-      else
-        @around_handler.call(method(:execute_components))
-      end
-    end
-
-    def finalize
-      @execution_chains.reverse_each do |execution_chain|
-        execution_chain.reverse_each(&:finalize)
-      end
-    end
-
-    def rollback
-      @execution_chains.reverse_each do |execution_chain|
-        execution_chain.reverse_each(&:rollback)
-      end
-    end
-
-  protected
-
-    def execute_components(options = {})
-      execution_chain = []
-
-      @components.each do |component|
-        report = Supervisor.supervise do
-          if component.is_a?(Class) && component <= Process
-            process_worker = ProcessWorker.new(component)
-
-            execution_chain << process_worker
-
-            process_worker.run_as_child(@flow)
-          else
-            self.class.process_eval(@owner_process, component)
-          end
-        end
-
-        if report.failed?
-          execution_chain.reverse_each(&:rollback)
-          execution_chain.reverse_each(&:finalize)
-
-          if options[:failure].nil? || options[:failure].call
-            @flow.log_failure(report.message)
-            return
-          else
-            Supervisor.resignal!(report)
-          end
-        else
-          if report.stopped? && (options[:stop].nil? || !options[:stop].call)
-            @execution_chains << execution_chain
-            Supervisor.resignal!(report)
-          end
-        end
-      end
-
-      @execution_chains << execution_chain
     end
 
   end

data/lib/w_flow/node_worker.rb

@@ -0,0 +1,91 @@
+module WFlow
+  class NodeWorker
+
+    def initialize(owner_process, node_class)
+      @owner_process = owner_process
+      @tasks   = node_class.tasks
+
+      options  = node_class.options
+
+      @execute_if      = options[:if]
+      @execute_unless  = options[:unless]
+      @around_proc     = options[:around]
+      @confirm_stop    = options[:stop]
+      @confirm_failure = options[:failure]
+    end
+
+    def execute?
+      (@execute_if.nil?     || process_eval(@execute_if)) &&
+      (@execute_unless.nil? || !process_eval(@execute_unless))
+    end
+
+    def run(flow)
+      @flow = flow
+      @executed_tasks_workers = []
+
+      report = Supervisor.supervise do
+        if @around_proc.nil?
+          execute_tasks
+        else
+          process_eval(@around_proc, method(:execute_tasks))
+        end
+      end
+
+      if report.failed?
+        rollback
+        finalize
+
+        @executed_tasks_workers.clear
+
+        if signal_failure?
+          Supervisor.resignal!(report)
+        else
+          @flow.log_failure(report.message)
+        end
+      elsif report.stopped? && signal_stop?
+        Supervisor.resignal!(report)
+      end
+    end
+
+    def finalize
+      executed_do(:finalize)
+    end
+
+    def rollback
+      executed_do(:rollback)
+    end
+
+    def process_eval(object, *args)
+      if object.is_a?(String) || object.is_a?(Symbol)
+        @owner_process.send(object.to_s, *args)
+      elsif object.is_a?(Proc)
+        @owner_process.instance_exec(*args, &object)
+      else
+        raise InvalidArguments, UNKNOWN_EXPRESSION
+      end
+    end
+
+  protected
+
+    def execute_tasks(options = {})
+      tasks_worker = TasksWorker.new(self, @tasks)
+
+      @executed_tasks_workers << tasks_worker
+
+      tasks_worker.run(@flow, options)
+    end
+
+    def signal_stop?
+      @confirm_stop.nil? || process_eval(@confirm_stop)
+    end
+
+    def signal_failure?
+      @confirm_failure.nil? || process_eval(@confirm_failure)
+    end
+
+    def executed_do(order)
+      @executed_tasks_workers.reverse_each(&order)
+    end
+
+  end
+end

data/lib/w_flow/process.rb

@@ -46,10 +46,10 @@ module WFlow
         end
       end
 
-      def execute(*components, &block)
-        options = components.last.is_a?(Hash) ? components.pop : {}
-        components << block if block_given?
-        wflow_nodes << Node.build(components, options)
+      def execute(*tasks, &block)
+        options = tasks.last.is_a?(Hash) ? tasks.pop : {}
+        tasks << block if block_given?
+        wflow_nodes << Node.build(tasks, options)
       end
 
       def run(params = {})

data/lib/w_flow/process_worker.rb

@@ -1,5 +1,6 @@
 module WFlow
   class ProcessWorker
+
     def initialize(process_class)
       @process_class = process_class
     end
@@ -28,59 +29,45 @@ module WFlow
     end
 
     def finalize
-      @nodes.reverse_each(&:finalize)
+      @executed_nodes.reverse_each(&:finalize)
 
       @process.finalize if @setup_completed
     end
 
     def rollback
-      @nodes.reverse_each(&:rollback)
+      @executed_nodes.reverse_each(&:rollback)
 
       @process.rollback if @perform_completed
     end
 
   protected
 
+    def setup(flow)
+      @flow    = flow
+      @process = @process_class.new(flow)
+
+      @executed_nodes    = []
+      @setup_completed   = false
+      @perform_completed = false
+    end
+
     def run
       @process.setup
       @setup_completed = true
 
       @process_class.wflow_nodes.each do |node_class|
-        next unless node_class.execute?(@process)
-
-        node = node_class.new(@process)
+        node_worker = NodeWorker.new(@process, node_class)
 
-        report = Supervisor.supervise { node.run(@flow) }
+        next unless node_worker.execute?
 
-        if report.failed?
-          node.rollback
-          node.finalize
+        @executed_nodes << node_worker
 
-          if node_class.cancel_failure?(@process)
-            @flow.log_failure(report.message)
-          else
-            Supervisor.resignal!(report)
-          end
-        else
-          @nodes << node
-
-          if report.stopped? && !node_class.cancel_stop?(@process)
-            Supervisor.resignal!(report)
-          end
-        end
+        report = node_worker.run(@flow)
       end
 
       @process.perform
       @perform_completed = true
     end
 
-    def setup(flow)
-      @flow    = flow
-      @process = @process_class.new(flow)
-      @nodes   = []
-      @setup_completed   = false
-      @perform_completed = false
-    end
-
   end
 end

data/lib/w_flow/tasks_worker.rb

@@ -0,0 +1,70 @@
+module WFlow
+  class TasksWorker
+
+    def initialize(owner_node, tasks)
+      @owner_node = owner_node
+      @tasks      = tasks
+    end
+
+    def run(flow, options = {})
+      @flow           = flow
+      @options        = options
+      @executed_tasks = []
+
+      @tasks.each do |task|
+        report = Supervisor.supervise { execute_task(task) }
+
+        if report.failed?
+          rollback
+          finalize
+
+          @executed_tasks.clear
+
+          if signal_failure?
+            Supervisor.resignal!(report)
+          else
+            flow.log_failure(report.message)
+            return
+          end
+        else
+          Supervisor.resignal!(report) if report.stopped? && signal_stop?
+        end
+      end
+    end
+
+    def finalize
+      executed_do(:finalize)
+    end
+
+    def rollback
+      executed_do(:rollback)
+    end
+
+  protected
+
+    def execute_task(task)
+      if task.is_a?(Class) && task <= Process
+        process_worker = ProcessWorker.new(task)
+
+        @executed_tasks << process_worker
+
+        process_worker.run_as_child(@flow)
+      else
+        @owner_node.process_eval(task)
+      end
+    end
+
+    def signal_failure?
+      @options[:failure].nil? || @options[:failure].call
+    end
+
+    def signal_stop?
+      @options[:stop].nil? || @options[:stop].call
+    end
+
+    def executed_do(order)
+      @executed_tasks.reverse_each(&order)
+    end
+
+  end
+end

data/lib/w_flow/version.rb

@@ -1,3 +1,3 @@
 module WFlow
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/w_flow.rb

@@ -6,8 +6,10 @@ require "w_flow/supervisor"
 require "w_flow/flow"
 require "w_flow/flow_report"
 require "w_flow/node"
+require "w_flow/node_worker"
 require "w_flow/process"
 require "w_flow/process_worker"
+require "w_flow/tasks_worker"
 
 module WFlow
 

data/w_flow.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["junhanamaki"]
   spec.email         = ["jun.hanamaki@gmail.com"]
 
-  spec.summary       = %q{A workflow composer based on Single Responsability Principle to help organize projects}
-  spec.description   = %q{WFlow is a workflow composer that helps in organizing projects by splitting logic into reusable modules (processes)}
+  spec.summary       = %q{A workflow composer based on Single Responsability Principle}
+  spec.description   = %q{WFlow is a workflow composer that helps in code organization by splitting logic into reusable modules, more at https://github.com/junhanamaki/w_flow}
   spec.homepage      = "https://github.com/junhanamaki/w_flow"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: w_flow
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - junhanamaki
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-06-03 00:00:00.000000000 Z
+date: 2015-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,8 +80,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.4'
-description: WFlow is a workflow composer that helps in organizing projects by splitting
-  logic into reusable modules (processes)
+description: WFlow is a workflow composer that helps in code organization by splitting
+  logic into reusable modules, more at https://github.com/junhanamaki/w_flow
 email:
 - jun.hanamaki@gmail.com
 executables: []
@@ -100,10 +100,12 @@ files:
 - lib/w_flow/flow.rb
 - lib/w_flow/flow_report.rb
 - lib/w_flow/node.rb
+- lib/w_flow/node_worker.rb
 - lib/w_flow/process.rb
 - lib/w_flow/process_worker.rb
 - lib/w_flow/supervisor.rb
 - lib/w_flow/supervisor_report.rb
+- lib/w_flow/tasks_worker.rb
 - lib/w_flow/version.rb
 - w_flow.gemspec
 homepage: https://github.com/junhanamaki/w_flow
@@ -129,6 +131,5 @@ rubyforge_project:
 rubygems_version: 2.4.7
 signing_key: 
 specification_version: 4
-summary: A workflow composer based on Single Responsability Principle to help organize
-  projects
+summary: A workflow composer based on Single Responsability Principle
 test_files: []