flows 0.4.0 → 0.5.0

data/lib/flows/shared_context_pipeline/step.rb

@@ -19,11 +19,9 @@ module Flows
 
     Step.const_set(
       :NODE_PREPROCESSOR,
-      lambda do |_input, context, meta|
-        context[:last_step] = meta[:name]
-
+      lambda do |_input, context, node_meta|
         context[:class].before_each_callbacks.each do |callback|
-          callback.call(context[:class], meta[:name], context[:data])
+          callback.call(context[:class], node_meta[:name], context[:data], context[:meta])
         end
 
         [EMPTY_ARRAY, context[:data]]
@@ -32,14 +30,14 @@ module Flows
 
     Step.const_set(
       :NODE_POSTPROCESSOR,
-      lambda do |output, context, meta|
-        context[:data].merge!(output.instance_variable_get(:@data))
+      lambda do |result, context, node_meta|
+        context[:data].merge!(result.instance_variable_get(:@data))
 
         context[:class].after_each_callbacks.each do |callback|
-          callback.call(context[:class], meta[:name], context[:data], output)
+          callback.call(context[:class], node_meta[:name], result, context[:data], context[:meta])
         end
 
-        output
+        result
       end
     )
   end

data/lib/flows/shared_context_pipeline/track.rb

@@ -16,22 +16,9 @@ module Flows
         @step_list = @step_list.map(&:dup)
       end
 
-      def add_step(name:, lambda: nil, router_def:)
-        step = Step.new(name: name, lambda: lambda, router_def: router_def)
-
-        last_step = @step_list.last
-        last_step.next_step = name if last_step
-
-        @step_list << step
-
-        self
-      end
-
-      def add_mutation_step(name:, lambda: nil, router_def:)
-        step = MutationStep.new(name: name, lambda: lambda, router_def: router_def)
-
+      def add_step(step)
         last_step = @step_list.last
-        last_step.next_step = name if last_step
+        last_step.next_step = step.name if last_step
 
         @step_list << step
 

data/lib/flows/shared_context_pipeline/track_list.rb

@@ -18,12 +18,8 @@ module Flows
         @current_track = track_name
       end
 
-      def add_step(name:, lambda:, router_def:)
-        @tracks[@current_track].add_step(name: name, lambda: lambda, router_def: router_def)
-      end
-
-      def add_mutation_step(name:, lambda:, router_def:)
-        @tracks[@current_track].add_mutation_step(name: name, lambda: lambda, router_def: router_def)
+      def add_step(step)
+        @tracks[@current_track].add_step(step)
       end
 
       def first_step_name
@@ -41,6 +37,15 @@ module Flows
           )
         end
       end
+
+      def to_flow(method_source)
+        raise NoStepsError, method_source if main_track_empty?
+
+        Flows::Flow.new(
+          start_node: first_step_name,
+          node_map: to_node_map(method_source)
+        )
+      end
     end
   end
 end

data/lib/flows/shared_context_pipeline/wrap.rb

@@ -0,0 +1,64 @@
+module Flows
+  class SharedContextPipeline
+    # @api private
+    class Wrap
+      attr_reader :router_def
+
+      # :reek:Attribute:
+      attr_accessor :next_step
+
+      EMPTY_HASH = {}.freeze
+
+      NODE_PREPROCESSOR = lambda do |_input, context, _node_meta|
+        [[context], EMPTY_HASH]
+      end
+
+      NODE_POSTPROCESSOR = lambda do |result, context, _node_meta|
+        context[:data].merge!(result.instance_variable_get(:@data))
+
+        result
+      end
+
+      def initialize(method_name:, router_def:, &tracks_definitions)
+        @method_name = method_name
+        @router_def = router_def
+
+        singleton_class.extend DSL::Tracks
+        singleton_class.extend Result::Helpers
+
+        singleton_class.instance_exec(&tracks_definitions)
+      end
+
+      def name
+        singleton_class.tracks.first_step_name
+      end
+
+      def to_node(method_source)
+        Flows::Flow::Node.new(
+          body: make_body(method_source),
+          router: router_def.to_router(next_step),
+          meta: { wrap_name: @method_name },
+          preprocessor: NODE_PREPROCESSOR,
+          postprocessor: NODE_POSTPROCESSOR
+        )
+      end
+
+      private
+
+      def make_flow(method_source)
+        singleton_class.tracks.to_flow(method_source)
+      end
+
+      def make_body(method_source)
+        flow = make_flow(method_source)
+        wrapper = method_source.method(@method_name)
+
+        lambda do |context|
+          wrapper.call(context[:data], context[:meta]) do
+            flow.call(nil, context: context)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/flows/shared_context_pipeline.rb

@@ -4,6 +4,7 @@ require_relative 'shared_context_pipeline/step'
 require_relative 'shared_context_pipeline/mutation_step'
 require_relative 'shared_context_pipeline/track'
 require_relative 'shared_context_pipeline/track_list'
+require_relative 'shared_context_pipeline/wrap'
 require_relative 'shared_context_pipeline/dsl'
 
 module Flows
@@ -140,35 +141,124 @@ module Flows
   #       # steps implementations here
   #     end
   #
-  # ## Callbacks
+  # ## Wrappers
+  #
+  # Sometimes you have to execute some steps inside SQL-transaction or something like this.
+  # Most frameworks allow to do it in the following approach:
+  #
+  #     SQLDataBase.transaction do
+  #       # your steps are executed here
+  #       # special error must be executed to cancel the transaction
+  #     end
+  #
+  # It's impossible to do with just step or track DSL. That's why `wrap` DSL method has been added.
+  # Let's review it on example:
+  #
+  #     class MySCP < Flows::SharedContextPipeline
+  #       step :some_preparations
+  #       wrap :in_transaction do
+  #         step :action_a
+  #         step :action_b
+  #       end
+  #
+  #       def in_transaction(ctx, meta, &block)
+  #         result = nil
+  #
+  #         ActiveRecord::Base.transaction do
+  #           result = block.call
+  #
+  #           raise ActiveRecord::Rollback if result.err?
+  #         end
+  #
+  #         result
+  #       end
+  #
+  #       # step implementations here
+  #     end
+  #
+  # `wrap` DSL method receives name and block. Inside block you can define steps and tracks.
+  #
+  # `wrap` makes an isolated track and step structure.
+  # You cannot route between wrapped and unwrapped steps and tracks.
+  # One exception - you can route to the first wrapped step.
+  #
+  # The same wrapper with the same name can be used multiple times in the same operation:
+  #
+  #     class MySCP < Flows::SharedContextPipeline
+  #       step :some_preparations
+  #       wrap :in_transaction do
+  #         step :action_a
+  #         step :action_b
+  #       end
+  #       step :some_calculations
+  #       wrap :in_transaction do
+  #         step :action_c
+  #         step :action_d
+  #       end
+  #
+  #       # ...
+  #     end
+  #
+  # Unlike step implementations wrapper implementation has access to a shared meta (can be useful for plugins).
+  #
+  # You may think about steps and tracks inside wrapper as a nested pipeline.
+  # Wrapper implementation receives mutable data context, metadata and block.
+  # Block execution (`block.call`) returns a result object of the executed "nested pipeline".
+  #
+  # When you route to `:end` inside wrapper - you're leaving wrapper, **not** the whole pipeline.
+  #
+  # From the execution perspective wrapper is a single step. The step name is the first wrapped step name.
+  #
+  # `wrap` itself also can have overriden routes table:
+  #
+  #     wrap :in_transaction, routes(match_ok => :next, match_err => :end) do
+  #       # steps...
+  #     end
+  #
+  # Like a step, wrapper implementation must return {Flows::Result}.
+  # Result is processed with the same approach as for normal step.
+  # **Do not modify result returned from block - build a new one if needed.
+  # Otherwise mutation steps can be broken.**
+  #
+  # ## Callbacks and metadata
   #
   # You may want to have some logic to execute before all steps, or after all, or before each, or after each.
   # For example to inject generalized execution process logging.
   # To achieve this you can use callbacks:
   #
   #     class MySCP < Flows::SharedContextPipeline
-  #       before_all do |klass, context|
-  #         # you can modify execution context here
+  #       before_all do |klass, data, meta|
+  #         # you can modify execution data context and metadata here
   #         # return value will be ignored
   #       end
   #
-  #       after_all do |klass, pipeline_result|
-  #         # you must provide final result object for pipeline here
+  #       after_all do |klass, pipeline_result, data, meta|
+  #         # you can modify execution data context and metadata here
+  #         # you must return a final result object here
   #         # if no modifications needed - just return provided pipeline_result
   #       end
   #
-  #       before_each do |klass, step_name, context|
-  #         # you can modify context here
+  #       before_each do |klass, step_name, data, meta|
+  #         # you can modify execution data context and metadata here
   #         # return value will be ignored
   #       end
   #
-  #       after_each do |klass, step_name, context, step_result|
-  #         # you can modify context here
-  #         # you must not modify step_result
-  #         # context already has data from step_result at the moment of execution
+  #       after_each do |klass, step_name, step_result, data, meta|
+  #         # you can modify execution data context and metadata here
   #         # return value will be ignored
+  #         #
+  #         # callback executed after context is updated with result data
+  #         # (in the case of normal steps, mutation steps update context directly)
+  #         #
+  #         # DO NOT MODIFY RESULT OBJECT HERE - IT CAN BROKE MUTATION STEPS
   #       end
   #     end
+  #
+  # Metadata - is a Hash which is shared between step executions.
+  # This hash becomes metadata of a final {Flows::Result}.
+  #
+  # Metadata is designed to store non-business data such as execution times,
+  # some library specific data, and so on.
   class SharedContextPipeline
     extend ::Flows::Plugin::ImplicitInit
 
@@ -178,38 +268,31 @@ module Flows
     extend DSL
 
     def initialize
-      klass = self.class
-      tracks = klass.tracks
-
-      raise NoStepsError, klass if tracks.main_track_empty?
-
-      @__flow = Flows::Flow.new(
-        start_node: tracks.first_step_name,
-        node_map: tracks.to_node_map(self)
-      )
+      @__flow = self.class.tracks.to_flow(self)
     end
 
     # Executes pipeline with provided keyword arguments, returns Result Object.
     #
     # @return [Flows::Result]
-    def call(**kwargs) # rubocop:disable Metrics/MethodLength
+    def call(**data) # rubocop:disable Metrics/MethodLength
       klass = self.class
-      context = { data: kwargs, class: klass }
+      meta = {}
+      context = { data: data, meta: meta, class: klass }
 
       klass.before_all_callbacks.each do |callback|
-        callback.call(klass, context[:data])
+        callback.call(klass, data, meta)
       end
 
       flow_result = @__flow.call(nil, context: context)
 
       final_result = flow_result.class.new(
-        context[:data],
+        data,
         status: flow_result.status,
-        meta: { last_step: context[:last_step] }
+        meta: meta
       )
 
       klass.after_all_callbacks.reduce(final_result) do |result, callback|
-        callback.call(klass, result)
+        callback.call(klass, result, data, meta)
       end
     end
   end

data/lib/flows/util/inheritable_singleton_vars/dup_strategy.rb

@@ -23,85 +23,74 @@ module Flows
         VAR_LIST_VAR_NAME = :@inheritable_vars_with_dup
 
         # @api private
-        module InheritanceCallback
-          def inherited(child_class)
-            DupStrategy.migrate(self, child_class)
+        module Migrator
+          def self.call(from, to)
+            parent_var_list = from.instance_variable_get(VAR_LIST_VAR_NAME)
+            child_var_list = to.instance_variable_get(VAR_LIST_VAR_NAME) || []
 
-            super
-          end
+            to.instance_variable_set(VAR_LIST_VAR_NAME, child_var_list + parent_var_list)
 
-          def included(child_mod)
-            DupStrategy.migrate(self, child_mod)
+            parent_var_list.each do |name|
+              to.instance_variable_set(name, from.instance_variable_get(name).dup)
+            end
+          end
+        end
 
-            child_mod.singleton_class.prepend(InheritanceCallback)
+        # @api private
+        module Injector
+          def included(mod)
+            Migrator.call(self, mod)
+            mod.singleton_class.prepend Injector
 
             super
           end
 
-          def extended(child_mod)
-            DupStrategy.migrate(self, child_mod)
+          def extended(mod)
+            Migrator.call(self, mod)
+            mod.singleton_class.prepend Injector
 
-            child_mod.singleton_class.prepend(InheritanceCallback)
+            super
+          end
+
+          def inherited(mod)
+            Migrator.call(self, mod)
+            mod.singleton_class.prepend Injector
 
             super
           end
         end
 
         class << self
-          # Applies behaviour and defaults for singleton variables.
-          #
-          # @note Variable names should look like `:@var` or `'@var'`.
-          #
-          # @param klass [Class] target class.
-          # @param attrs_with_default [Hash<Symbol, String => Object>] keys are variable names,
-          #   values are default values.
+          # Generates a module which applies behaviour and defaults for singleton variables.
           #
           # @example
           #   class MyClass
-          #     Flows::Util::InheritableSingletonVars::DupStrategy.call(
-          #       self,
+          #     SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
           #       :@my_list => []
           #     )
+          #
+          #     include SingletonVarsSetup
           #   end
-          def call(klass, attrs_with_default = {})
-            init_variables_with_default_values(klass, attrs_with_default)
-
-            var_names = attrs_with_default.keys.map(&:to_sym)
-            add_var_list(klass, var_names)
-
-            inject_inheritance_hook(klass)
-          end
-
-          # Moves variables between modules
           #
-          # @api private
-          def migrate(from_mod, to_mod)
-            var_list = from_mod.instance_variable_get(VAR_LIST_VAR_NAME)
-            to_mod.instance_variable_set(VAR_LIST_VAR_NAME, var_list.dup)
-
-            var_list.each do |name|
-              to_mod.instance_variable_set(name, from_mod.instance_variable_get(name).dup)
+          # @note Variable names should look like `:@var` or `'@var'`.
+          #
+          # @param vars_with_default [Hash<Symbol, String => Object>] keys are variable names,
+          #   values are default values.
+          def make_module(vars_with_default = {})
+            Module.new.tap do |mod|
+              mod.instance_variable_set(VAR_LIST_VAR_NAME, vars_with_default.keys.map(&:to_sym))
+              init_vars(mod, vars_with_default)
+              mod.extend Injector
             end
           end
 
           private
 
-          def init_variables_with_default_values(klass, attrs_with_default)
-            attrs_with_default.each do |name, default_value|
-              klass.instance_variable_set(name, default_value)
+          def init_vars(mod, vars_with_default)
+            vars_with_default.each do |name, value|
+              mod.instance_variable_set(name, value)
             end
           end
-
-          def add_var_list(klass, var_names)
-            watch_list = klass.instance_variable_get(VAR_LIST_VAR_NAME) || []
-            watch_list.concat(var_names)
-            klass.instance_variable_set(VAR_LIST_VAR_NAME, watch_list)
-          end
-
-          def inject_inheritance_hook(klass)
-            singleton = klass.singleton_class
-            singleton.prepend(InheritanceCallback) unless singleton.is_a?(InheritanceCallback)
-          end
         end
       end
     end