feat!: improve callback api (#8)

* docs(readme): add section about GitHub flow

* docs(readme): update CI badge

* feat!: change SCP before_all callback #6

* feat!: change SCP after_all callback #6

* feat!: change SCP before_each callback #6

* feat!: change SCP after_each callback #6

* docs: update CHANGELOG

Author: ffloyd

CHANGELOG.md

@@ -16,6 +16,10 @@ Types of changes:
 
 ## [Unreleased]
 
+### Changed
+
+* `Flows::SharedContextPipeline` callback API, GitHub issue: #6
+
 ## [0.4.0] - 2020-04-21
 
 ### Added

README.md

@@ -1,6 +1,6 @@
 # Flows
 
-[![Build Status](https://github.com/ffloyd/flows/workflows/Build/badge.svg)](https://github.com/ffloyd/flows/actions)
+[![Build Status](https://github.com/ffloyd/flows/workflows/Test/badge.svg)](https://github.com/ffloyd/flows/actions)
 [![codecov](https://codecov.io/gh/ffloyd/flows/branch/master/graph/badge.svg)](https://codecov.io/gh/ffloyd/flows)
 [![Gem Version](https://badge.fury.io/rb/flows.svg)](https://badge.fury.io/rb/flows)
 
@@ -251,6 +251,16 @@ version. _No exceptions._
 
 Commit with a version bump should contain _only_ version bump and CHANGELOG.md update.
 
+### GitHub Flow
+
+Since `v0.4.0` this repo strictly follow [GitHub
+Flow](https://guides.github.com/introduction/flow/) with some additions:
+
+* branch naming using dash: `improved-contexts`
+* use [references to
+  issues](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
+  in commit messages and CHANGELOG.md
+
 ### Planned features for v1.0.0
 
 * validation framework

docs/README.md

@@ -1,6 +1,6 @@
 # Flows
 
-[![Build Status](https://github.com/ffloyd/flows/workflows/Build/badge.svg)](https://github.com/ffloyd/flows/actions)
+[![Build Status](https://github.com/ffloyd/flows/workflows/Test/badge.svg)](https://github.com/ffloyd/flows/actions)
 [![codecov](https://codecov.io/gh/ffloyd/flows/branch/master/graph/badge.svg)](https://codecov.io/gh/ffloyd/flows)
 [![Gem Version](https://badge.fury.io/rb/flows.svg)](https://badge.fury.io/rb/flows)
 

lib/flows/shared_context_pipeline.rb

@@ -140,35 +140,45 @@ module Flows
   #       # steps implementations here
   #     end
   #
-  # ## Callbacks
+  # ## 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
 
@@ -192,24 +202,25 @@ def initialize
     # 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

lib/flows/shared_context_pipeline/mutation_step.rb

@@ -1,28 +1,26 @@
 module Flows
   class SharedContextPipeline
     EMPTY_HASH = {}.freeze
-    EMPTY_OK = Flows::Result::Ok.new(nil).freeze
-    EMPTY_ERR = Flows::Result::Err.new(nil).freeze
+    EMPTY_OK = Flows::Result::Ok.new({}.freeze).freeze
+    EMPTY_ERR = Flows::Result::Err.new({}.freeze).freeze
 
     # @api private
     class MutationStep < Step
-      NODE_PREPROCESSOR = lambda do |_input, context, meta|
-        context[:last_step] = meta[:name]
-
+      NODE_PREPROCESSOR = 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
 
         [[context[:data]], EMPTY_HASH]
       end
 
-      NODE_POSTPROCESSOR = lambda do |output, context, meta|
+      NODE_POSTPROCESSOR = lambda do |output, context, node_meta|
         case output
         when Flows::Result then output
         else output ? EMPTY_OK : EMPTY_ERR
         end.tap do |result|
           context[:class].after_each_callbacks.each do |callback|
-            callback.call(context[:class], meta[:name], context[:data], result)
+            callback.call(context[:class], node_meta[:name], result, context[:data], context[:meta])
           end
         end
       end

lib/flows/shared_context_pipeline/step.rb

@@ -19,11 +19,9 @@ def to_node(pipeline_class)
 
     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 @@ def to_node(pipeline_class)
 
     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