business_flow 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d9c94efd239befaaff61cf57d19cb6b275435d02
-  data.tar.gz: 944f1a4075af4781ea1ee873366c4900e5e26241
+  metadata.gz: 1a7e45240693906221c1e55e093c0588274746f0
+  data.tar.gz: 4b2191aaf8e84752f4183f9ea89ce5fe1299ddda
 SHA512:
-  metadata.gz: 2fc9b094b2677ed5e13ed1b17c58d07de5340bef3608540f6171783656d238a54346988361dd96bf94665b9730941edffd247d06c9fd9695355cb6822df9e01a
-  data.tar.gz: a3a9e27a570b2e14669521de739982abb05558723c7b820a22c1d60ccbbd76b6e4a5e8fb589cf08e6f224b5ce04d9d5322b2f1fa1d10cc9689c410b58cf4fd5c
+  metadata.gz: 2907e0e9d8139972e810c667ce65a6dedbc4e95a5a069e16f40a59ba12dd1c808cfb77fe572089375b92a3c22c94bebe42f9dc8dfadea480938410049c092c22
+  data.tar.gz: aea9b30bd764f0ae977381ab77cf1b5d1c1d91e873ff8d6fe7ed57657d566d2bc5f94e68641fbcc84a09a1c5bf90cab447bca74e85950af147a7b99eb577732e

data/Gemfile.lock

@@ -3,6 +3,7 @@ PATH
   specs:
     business_flow (0.3.0)
       activemodel (>= 3.0)
+      activesupport (>= 3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -27,10 +28,12 @@ GEM
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.3)
+    docile (1.1.5)
     equalizer (0.0.11)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
+    json (2.1.0)
     minitest (5.11.3)
     parallel (1.12.1)
     parser (2.5.0.3)
@@ -62,7 +65,14 @@ GEM
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
+    rubocop-rspec (1.24.0)
+      rubocop (>= 0.53.0)
     ruby-progressbar (1.9.0)
+    simplecov (0.15.1)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
@@ -83,6 +93,8 @@ DEPENDENCIES
   reek (~> 4.8)
   rspec (~> 3.0)
   rubocop (~> 0.53)
+  rubocop-rspec (~> 1.24.0)
+  simplecov (~> 0.15.1)
 
 BUNDLED WITH
    1.16.1

data/business_flow.gemspec

@@ -21,10 +21,13 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'activemodel', '>= 3.0'
+  spec.add_dependency 'activesupport', '>= 3.0'
 
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'reek', '~> 4.8'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 0.53'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.24.0'
+  spec.add_development_dependency 'simplecov', '~> 0.15.1'
 end

data/lib/business_flow/base.rb

@@ -1,104 +1,40 @@
 # Magic!
 module BusinessFlow
   # More magic!
-  # Look at use of class attrs
   # call! to raise errors
   # Hooks for cross cutting concerns
   # Figure out how much we can freeze
-  # Check output slots even if they're not going through our defined setter
-  # Conditional steps?
-  # ActiveSupport notifiers
   module Base
     def self.included(klass)
       klass.include(DSL)
       klass.prepend(InstanceMethods)
     end
 
+    # "Helper" methods which we put on an object to provide some default
+    # behavior.
     module InstanceMethods
       attr_reader :parameter_object
       private :parameter_object
 
       def initialize(parameter_object)
         @parameter_object = parameter_object
-        super()
+        catch(:halt_step) do
+          super()
+        end
       end
 
       def call
-        return if invalid?
+        # If our initialization process set any errors, return
+        return if errors.any? || invalid?
         if defined?(super)
-          super
-        else
-          process_steps
-        end
-      end
-
-      private
-
-      def process_steps
-        steps.each do |step_name|
           catch(:halt_step) do
-            process_step(step_name)
+            super
           end
-          break if errors.any?
-        end
-      end
-
-      def process_step(step)
-        input_object = marshall_input_object(step.inputs)
-        result = step.dispatch(self, input_object)
-        marshall_outputs(result, step.outputs) if result.present?
-      end
-
-      def marshall_input_object(input_object)
-        return self if input_object.blank?
-        Hash[input_object.map do |input_name, input_value|
-               [
-                 input_name,
-                 process_input(input_value)
-               ]
-             end
-            ]
-      end
-
-      def marshall_outputs(result, output_object)
-        merge_other_errors(result.errors, result.class.name.underscore)
-        output_object.each do |(output_name, output_setter)|
-          break if errors.any?
-          output = result.public_send(output_name)
-          process_output(output, output_setter)
-        end
-      end
-
-      def merge_other_errors(other_errors, base_name)
-        other_errors.each do |attribute, message|
-          attribute = "#{base_name}.#{attribute}"
-          (errors[attribute] << message).uniq!
-        end
-      end
-
-      def process_input(input_value)
-        case input_value
-        when Symbol
-          send(input_value)
-        when Proc
-          instance_exec(&input_value)
         else
-          input_value
-        end
-      end
-
-      def process_output(output, output_setter)
-        case output_setter
-        when Symbol
-          send("#{output_setter}=", output)
-        when Proc
-          instance_exec(output, &output_setter)
+          ::BusinessFlow::DefaultStepExecutor.new(self.class.step_queue, self)
+                                             .call
         end
       end
-
-      def steps
-        self.class.step_queue || []
-      end
     end
   end
 end

data/lib/business_flow/callable.rb

@@ -13,14 +13,16 @@ module BusinessFlow
       cached_proc.call(instance, inputs)
     end
 
+    def to_s
+      @callable.to_s
+    end
+
     private
 
     # :reek:ManualDispatch Look reek I don't know what you want me to do.
     def check_callable
       if @callable.is_a?(Proc)
-        @cached_proc = proc do |instance, inputs|
-          instance.instance_exec(inputs, &@callable)
-        end
+        @cached_proc = proc_callable
       elsif @callable.respond_to?(:call)
         @cached_proc = proc { |_, inputs| @callable.call(inputs) }
       elsif !@callable.is_a?(Symbol)
@@ -32,23 +34,34 @@ module BusinessFlow
       @cached_proc ||=
         if @metaclass.method_defined?(@callable) ||
            @metaclass.private_method_defined?(@callable)
-          proc { |instance, _| instance.send(@callable) && nil }
+          proc { |instance, _| instance.send(@callable) }
         else
           @callable = lookup_callable ||
-                      raise(NameError, "undefined constant #{@klass}")
-          proc { |_, inputs| @callable.call(inputs) }
+                      raise(NameError, "undefined constant #{@callable}")
+          check_callable
+        end
+    end
+
+    def proc_callable
+      proc do |instance, inputs|
+        if @callable.arity.zero?
+          instance.instance_exec(&@callable)
+        else
+          instance.instance_exec(inputs, &@callable)
         end
+      end
     end
 
     def lookup_callable
       constant_name = @callable.to_s.camelcase
       @metaclass.parents.each do |parent|
         begin
-          break parent.const_get(constant_name)
+          return parent.const_get(constant_name)
         rescue NameError
           next
         end
       end
+      nil
     end
   end
 end

data/lib/business_flow/default_step_executor.rb

@@ -0,0 +1,35 @@
+module BusinessFlow
+  # Default behavior for running a step queue -- execute each step in turn
+  # halting the moment something goes wrong. Use the same flow as input
+  # and output to all steps.
+  class DefaultStepExecutor
+    def initialize(step_queue, flow)
+      @step_queue = step_queue
+      @flow = flow
+    end
+
+    def call
+      @step_queue.each do |step|
+        catch(:halt_step) { process_step(step) }
+        break if @flow.errors.any?
+      end
+    end
+
+    protected
+
+    def process_step(step)
+      ActiveSupport::Notifications.instrument(
+        event_name(step), flow: @flow
+      ) do |payload|
+        payload[:step_result] = result = step.call(@flow)
+        result.merge_into(@flow)
+        result
+      end
+    end
+
+    def event_name(step)
+      "business_flow.step.#{@flow.class.to_s.underscore}. " \
+        "#{step.to_s.underscore}"
+    end
+  end
+end

data/lib/business_flow/dsl.rb

@@ -1,55 +1,85 @@
 module BusinessFlow
+  # Core DSL for BusinessFlow. The relevant methods are all in
+  # ClassMethods.
   module DSL
-    def self.included(klass)
-      klass.include(ActiveModel::Validations)
-      klass.extend(ClassMethods)
-      klass.instance_eval do
-        class << self
-          alias invariant validates
-        end
-      end
-    end
-
+    # Contains the DSL for BusinessFlow
+    # The class that includes this must implement a parameter_object reader
+    # which returns a hash or object representing the parameters the flow
+    # was initialized with. The provided .call will instantiate the including
+    # class with a parameter_object as the only argument.
     module ClassMethods
-      def step_queue
-        @step_queue ||= []
-      end
-
-      def add_requirement(fields)
-        @requirements ||= []
-        @requirements.concat(fields)
-        fields.each do |field|
-          validates_with NotNilValidator, attributes: [field]
-        end
-      end
-
+      # Requires that a field be retrievable from the initialization parameters
+      #
+      # This will only require that the field is not nil. The field may still
+      # be #empty?
+      #
+      # @param fields The fields required from the initialization parameters
       def needs(*fields)
-        add_requirement(fields)
+        validates_with NotNilValidator, attributes: fields
         wants(*fields)
       end
 
+      # Allows a field to be retrieved from the initialiaztoin parameters
+      #
+      # Unlike needs, this applies no validation to the field. It may
+      # be nil.
+      #
+      # @param (see #needs)
       def wants(*fields)
-        fields.each { |field| add_parameter_field(field) }
+        fields.each do |field|
+          PrivateHelpers.create_parameter_field(self, field)
+        end
       end
 
+      # Declares that you will expose a field to the outside world.
       def provides(*fields)
-        attr_reader(*fields)
-        attr_writer(*fields)
-        fields.each { |field| private("#{field}=") }
+        fields.each { |field| PrivateHelpers.create_field(self, field) }
       end
 
+      # Declares that you expect to set this field during the course of
+      # processing, and that it should meet the given ActiveModel
+      # validations.
       def expects(field, options = {})
-        attr_reader field
         validates field, options.merge(on: field)
-        setter_name = "#{field}=".to_sym
-        unless method_defined?(setter_name) ||
-               private_method_defined?(setter_name)
-          create_setter(field)
+        provides field
+      end
+
+      def step(klass, opts = {})
+        callable = Callable.new(klass, self)
+        opts = opts.merge(
+          condition: PrivateHelpers.create_conditional_callable(self, opts)
+        )
+        step_queue << step = Step.new(callable, opts)
+        provides(*step.outputs.values)
+      end
+
+      def call(parameter_object)
+        new(parameter_object).tap(&:call)
+      end
+
+      def step_queue
+        @step_queue ||= []
+      end
+    end
+
+    def self.included(klass)
+      # That we include ActiveModel::Validations is considered part of our
+      # public API, even though we provide our own aliases.
+      klass.include(ActiveModel::Validations)
+      klass.extend(ClassMethods)
+      klass.instance_eval do
+        class << self
+          # See above -- that this is an alias is considered public API.
+          alias invariant validates
         end
       end
+    end
 
-      def add_parameter_field(field)
-        define_method field do
+    # Keep our internal helpers in a different module to avoid polluting the
+    # namespace of whoever includes us.
+    module PrivateHelpers
+      def self.create_parameter_field(klass, field)
+        klass.send(:define_method, field) do
           if parameter_object.is_a?(Hash) && parameter_object.key?(field)
             parameter_object[field]
           else
@@ -58,30 +88,27 @@ module BusinessFlow
         end
       end
 
-      def step(klass, opts = {})
-        create_fields_for_step_outputs(opts.fetch(:outputs, {}))
-        step_queue << Step.new(klass, opts, self)
+      def self.create_conditional_callable(klass, opts)
+        condition = opts[:if]
+        condition && Callable.new(condition, klass)
       end
 
-      def create_fields_for_step_outputs(outputs)
-        outputs.values.select { |field| field.is_a?(Symbol) }.map do |field|
-          attr_reader field
-          create_setter(field)
-        end
+      def self.create_field(klass, field)
+        return unless field.is_a?(Symbol)
+        klass.send(:attr_reader, field)
+        setter_name = "#{field}=".to_sym
+        define_setter(klass, setter_name, field)
+        klass.send(:private, setter_name)
       end
 
-      def create_setter(field)
-        setter_name = "#{field}=".to_sym
-        define_method setter_name do |new_value|
+      def self.define_setter(klass, setter_name, field)
+        return if klass.method_defined?(setter_name) ||
+                  klass.private_method_defined?(setter_name)
+        klass.send(:define_method, setter_name) do |new_value|
           instance_variable_set("@#{field}".to_sym, new_value)
           throw :halt_step unless valid?(field)
           new_value
         end
-        private(setter_name)
-      end
-
-      def call(parameter_object)
-        new(parameter_object).tap(&:call)
       end
     end
   end

data/lib/business_flow/step.rb

@@ -1,19 +1,124 @@
 module BusinessFlow
   class Step
-    attr_reader :klass, :inputs, :outputs
-    def initialize(klass, opts, flow_klass)
-      @klass = klass
-      @inputs = opts.fetch(:inputs, {})
-      @outputs = opts.fetch(:outputs, {})
-      if_condition = opts[:if]
-      @condition = Callable.new(if_condition, flow_klass) if if_condition
-      @callable = Callable.new(@klass, flow_klass)
+    class Inputs
+      attr_reader :inputs
+
+      def initialize(inputs)
+        @inputs = inputs
+      end
+
+      def parameters_from_source(source)
+        return source if inputs.blank?
+        Hash[inputs.map do |input_name, input_value|
+               [
+                 input_name,
+                 Inputs.process_input(source, input_value)
+               ]
+             end]
+      end
+
+      def self.process_input(source, input_value)
+        case input_value
+        when Symbol
+          source.send(input_value)
+        when Proc
+          source.instance_exec(&input_value)
+        else
+          input_value
+        end
+      end
+    end
+
+    class Result
+      def initialize(result, output_map)
+        @result = result
+        @output_map = output_map
+        @result_errors = begin
+                           result.errors
+                         rescue NoMethodError
+                           nil
+                         end
+      end
+
+      def merge_into(object)
+        merge_errors_into(object.errors)
+        merge_outputs_into(object)
+      end
+
+      def executed?
+        true
+      end
+
+      def errors?
+        @result_errors.present?
+      end
+
+      def self.process_output(object, output, output_setter)
+        case output_setter
+        when Symbol
+          object.send("#{output_setter}=", output)
+        when Proc
+          object.instance_exec(output, &output_setter)
+        end
+      end
+
+      private
+
+      def merge_errors_into(errors)
+        return if @result_errors.blank?
+        @result_errors.each do |attribute, message|
+          attribute = "#{@result.class.name}.#{attribute}"
+          (errors[attribute] << message).uniq!
+        end
+        throw :halt_step
+      end
+
+      def merge_outputs_into(object)
+        @output_map.each do |(output_name, output_setter)|
+          output = @result.public_send(output_name)
+          Result.process_output(object, output, output_setter)
+        end
+      end
+    end
+
+    # Returned if our conditional check failed. Does nothing.
+    class ConditionFailedResult
+      def executed?
+        false
+      end
+
+      def errors?
+        false
+      end
+
+      def merge_into(_object); end
+    end
+
+    attr_reader :outputs
+
+    def initialize(callable, opts)
+      @callable = callable
+      @input_object = Inputs.new(opts[:inputs] || {})
+      @outputs = opts[:outputs] || {}
+      @condition = opts[:condition] || proc { true }
     end
 
     # @klass can be a symbol or class
-    def dispatch(flow, inputs)
-      return if @condition && !@condition.call(flow, inputs)
-      @callable.call(flow, inputs)
+    def call(parameter_source)
+      parameters = @input_object.parameters_from_source(parameter_source)
+      if @condition.call(parameter_source, parameters)
+        Result.new(@callable.call(parameter_source, parameters), outputs)
+      else
+        ConditionFailedResult.new
+      end
+    end
+
+    def inputs
+      @input_object.inputs
+    end
+
+    def to_s
+      @callable.to_s
     end
   end
 end

data/lib/business_flow/version.rb

@@ -1,3 +1,3 @@
 module BusinessFlow
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.4.0'.freeze
 end

data/lib/business_flow.rb

@@ -1,8 +1,10 @@
 require 'active_model'
+require 'active_support/core_ext'
 require 'business_flow/version'
 require 'business_flow/not_nil_validator'
 require 'business_flow/callable'
 require 'business_flow/step'
+require 'business_flow/default_step_executor'
 require 'business_flow/dsl'
 require 'business_flow/base'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: business_flow
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alex Scarborough
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-10 00:00:00.000000000 Z
+date: 2018-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +108,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.53'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.24.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.24.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.1
 description: 
 email:
 - alex@teak.io
@@ -115,6 +157,7 @@ files:
 - lib/business_flow.rb
 - lib/business_flow/base.rb
 - lib/business_flow/callable.rb
+- lib/business_flow/default_step_executor.rb
 - lib/business_flow/dsl.rb
 - lib/business_flow/not_nil_validator.rb
 - lib/business_flow/step.rb