nxt_pipeline 0.4.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f47be27dd03af5d8a11274b4667a40e2a0c14b4be0a373dd90e1fc7deb93c03
-  data.tar.gz: 6964e21671bb458e187dd3289538e49243e42b06c38c804ffc2b69ed94146612
+  metadata.gz: 77672035013c0cfe29bb5c5057178a9822e25c5b02e83b87a8cbb8dadac1d687
+  data.tar.gz: bb097fa702a19a9756d86a2ff63792bed998d9f8c5425263864695606bfca70d
 SHA512:
-  metadata.gz: 5ba8339e42e2e485e9c0c00a35d6df56324b1145605d564039a4931d384d0297ef44b3613c8e45e83dfcfea83f0ed7b5a377f3a6e89f2a03e5b9dbfcc6e47b9a
-  data.tar.gz: f9c938b9302bf9f2b4c126ddaa1b978b99c2f02fe1cdbc6d17be307135a22a504e002c6b110fa0b2eb92a04b5623f4293c8f92575c82ad2240f3de0b4a49a8ad
+  metadata.gz: 2d355345b5aadcb3d02895cd85196cc60b34caef8c919d11480a5a2cd429c5e32baa37c83f8e169ca316311735343297ba0a3b763044e12ac02c8349cc849929
+  data.tar.gz: eeaa40df4479d0b4b39e5cfe5fd89756d6681dc3d9e9f96e65f6f1e4f9793c588298c33c0fa446c0f7ddf73a3a9e4a43c5da5f371cf25928f18c80bed52e3e58

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## nxt_pipeline 1.0.0 (24.11.2020)
+
+Replace after and before execute hooks with proper callbacks.
+Introduce before, after and around step callbacks
+
 ## nxt_pipeline 0.4.3 (October 20, 2020)
 
 Add new attribute readers on step object.
@@ -42,4 +47,4 @@ will be set and can be accessed via attribute readers.
 
 * Initial Release.
 
-  *Nils Sommer*
+  *Nils Sommer*

data/Gemfile.lock

@@ -1,25 +1,26 @@
 PATH
   remote: .
   specs:
-    nxt_pipeline (0.4.3)
+    nxt_pipeline (1.0.0)
       activesupport
+      nxt_registry
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.3.4)
+    activesupport (6.1.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2, >= 2.2.2)
-    byebug (11.1.1)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.7)
-    diff-lcs (1.3)
-    ffi (1.11.1)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.8)
+    diff-lcs (1.4.4)
+    ffi (1.14.2)
     formatador (0.2.5)
-    guard (2.15.0)
+    guard (2.16.2)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
       lumberjack (>= 1.0.12, < 2.0)
@@ -33,51 +34,50 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.8.5)
+    i18n (1.8.7)
       concurrent-ruby (~> 1.0)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
-    lumberjack (1.0.13)
+    listen (3.4.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    lumberjack (1.2.8)
     method_source (1.0.0)
-    minitest (5.14.2)
+    minitest (5.14.3)
     nenv (0.3.0)
-    notiffany (0.1.1)
+    notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    pry (0.13.0)
+    nxt_registry (0.3.6)
+      activesupport
+    pry (0.13.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     pry-byebug (3.9.0)
       byebug (~> 11.0)
       pry (~> 0.13.0)
-    rake (13.0.1)
-    rb-fsevent (0.10.3)
-    rb-inotify (0.10.0)
+    rake (13.0.3)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.0)
-      rspec-support (~> 3.9.0)
-    rspec-expectations (3.9.0)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.1)
     rspec_junit_formatter (0.4.1)
       rspec-core (>= 2, < 4, != 2.12.0)
-    ruby_dep (1.5.0)
     shellany (0.0.1)
-    thor (0.20.3)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    zeitwerk (2.4.0)
+    thor (1.1.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby

data/README.md

@@ -176,24 +176,59 @@ NxtPipeline::Pipeline.new do |p|
 end
 ```
 
-### Before and After callbacks
+### Before, around and after callbacks
 
-You can also define callbacks that run before and after the `#execute` action. Both callback blocks get the pipeline instance (to access stuff like the `log`) and the argument of the pipeline yielded.
+You can also define callbacks :before, :around and :after each step and or the `#execute` method. You can also register
+multiple callbacks, but probably you want to keep them to a minimum to not end up in hell.
+
+#### Step callbacks
+
+```ruby
+NxtPipeline::Pipeline.new do |p|
+  p.before_step do |_, change_set|
+    change_set[:acc] << 'before step 1'
+    change_set
+  end
+
+  p.around_step do |_, change_set, execution|
+    change_set[:acc] << 'around step 1'
+    execution.call # you have to specify where in your callback you want to call the inner block
+    change_set[:acc] << 'around step 1'
+    change_set
+  end
+
+  p.after_step do |_, change_set|
+    change_set[:acc] << 'after step 1'
+    change_set
+  end
+end
+```
+
+#### Execution callbacks
 
 ```ruby
 NxtPipeline::Pipeline.new do |p|
-  p.before_execute do |pipeline, arg:|
-    # Will be called from within #execute before entering the first step
-    # After any configure block though!
+  p.before_execution do |_, change_set|
+    change_set[:acc] << 'before execution 1'
+    change_set
+  end
+
+  p.around_execution do |_, change_set, execution|
+    change_set[:acc] << 'around execution 1'
+    execution.call # you have to specify where in your callback you want to call the inner block
+    change_set[:acc] << 'around execution 1'
+    change_set
   end
 
-  p.after_execute do |pipeline, arg:|
-    # Will be called from within #execute after executing last step
+  p.after_execution do |_, change_set|
+    change_set[:acc] << 'after execution 1'
+    change_set
   end
 end
 ```
 
-Note that the `after_execute` callback will not be called, when an error is raised in one of the steps. See the previous section (_Error callbacks_) for how to define callbacks that run in case of errors.
+Note that the `after_execute` callback will not be called in case a step raises an error. 
+See the previous section (_Error callbacks_) for how to define callbacks that run in case of errors.
 
 ### Step resolvers
 
@@ -203,7 +238,6 @@ You can also use this if you are not fine with resolving the constructor from th
 
 
 ## Topics
-- Step orchestration (chainable steps)
 - Constructors should take arg as first and step as second arg
 
 ## Development

data/lib/nxt_pipeline.rb

@@ -1,9 +1,11 @@
 require 'active_support/all'
+require 'nxt_registry'
 require 'nxt_pipeline/version'
 require 'nxt_pipeline/logger'
 require 'nxt_pipeline/constructor'
 require 'nxt_pipeline/pipeline'
 require 'nxt_pipeline/step'
+require 'nxt_pipeline/callbacks'
 require 'nxt_pipeline/error_callback'
 
 module NxtPipeline

data/lib/nxt_pipeline/callbacks.rb

@@ -0,0 +1,58 @@
+module NxtPipeline
+  class Callbacks
+    def initialize(pipeline:)
+      @registry = build_registry
+      @pipeline = pipeline
+    end
+
+    def register(path, callback)
+      registry.resolve!(*path) << callback
+    end
+
+    def run(kind_of_callback, type, change_set)
+      registry.resolve!(kind_of_callback, type).each do |callback|
+        run_callback(callback, change_set)
+      end
+    end
+
+    def around(type, change_set, &execution)
+      around_callbacks = registry.resolve!(:around, type)
+      return execution.call unless around_callbacks.any?
+
+      callback_chain = around_callbacks.reverse.inject(execution) do |previous, callback|
+        -> { callback.call(pipeline, change_set, previous) }
+      end
+
+      callback_chain.call
+    end
+
+    private
+
+    attr_reader :registry, :pipeline
+
+    def run_callback(callback, change_set)
+      args = [pipeline, change_set]
+      args = args.take(callback.arity)
+      callback.call(*args)
+    end
+
+    def build_registry
+      NxtRegistry::Registry.new(:callbacks) do
+        register(:before) do
+          register(:step, [])
+          register(:execution, [])
+        end
+
+        register(:around) do
+          register(:step, [])
+          register(:execution, [])
+        end
+
+        register(:after) do
+          register(:step, [])
+          register(:execution, [])
+        end
+      end
+    end
+  end
+end

data/lib/nxt_pipeline/pipeline.rb

@@ -35,9 +35,9 @@ module NxtPipeline
       step_resolvers << block
     end
 
-    def set_default_constructor(name)
+    def set_default_constructor(default_constructor)
       raise_duplicate_default_constructor if default_constructor_name.present?
-      self.default_constructor_name = name
+      self.default_constructor_name = default_constructor
     end
 
     def raise_duplicate_default_constructor
@@ -46,8 +46,7 @@ module NxtPipeline
 
     def step(argument = nil, **opts, &block)
       constructor = if block_given?
-        # make type the :to_s of inline steps
-        # fall back to :inline if no type is given
+        # make type the :to_s of inline steps fall back to :inline if no type is given
         argument ||= :inline
         opts.reverse_merge!(to_s: argument)
         Constructor.new(:inline, **opts, &block)
@@ -66,40 +65,33 @@ module NxtPipeline
         end
       end
 
-      steps << Step.new(argument, constructor, steps.count, **opts)
+      register_step(argument, constructor, callbacks, **opts)
     end
 
-    def execute(**changeset, &block)
+    def execute(**change_set, &block)
       reset
 
       configure(&block) if block_given?
-      before_execute_callback.call(self, changeset) if before_execute_callback.respond_to?(:call)
-
-      result = steps.inject(changeset) do |changeset, step|
-        execute_step(step, **changeset)
-      rescue StandardError => error
-        logger_for_error = logger
-
-        error.define_singleton_method :details do
-          OpenStruct.new(
-            changeset: changeset,
-            logger: logger_for_error,
-            step: step
-          )
+      callbacks.run(:before, :execution, change_set)
+
+      result = callbacks.around :execution, change_set do
+        steps.inject(change_set) do |set, step|
+          execute_step(step, **set)
+        rescue StandardError => error
+          decorate_error_with_details(error, set, step, logger)
+          handle_error_of_step(error)
+          set
         end
-
-        callback = find_error_callback(error)
-        raise unless callback && callback.continue_after_error?
-        handle_step_error(error)
-        changeset
       end
 
-      after_execute_callback.call(self, result) if after_execute_callback.respond_to?(:call)
+      callbacks.run(:after, :execution, change_set)
       result
     rescue StandardError => error
       handle_step_error(error)
     end
 
+    alias_method :call, :execute
+
     def handle_step_error(error)
       log_step(current_step)
       callback = find_error_callback(error)
@@ -115,22 +107,40 @@ module NxtPipeline
 
     alias :on_error :on_errors
 
-    def before_execute(&callback)
-      self.before_execute_callback = callback
+    def before_step(&block)
+      callbacks.register([:before, :step], block)
+    end
+
+    def after_step(&block)
+      callbacks.register([:after, :step], block)
+    end
+
+    def around_step(&block)
+      callbacks.register([:around, :step], block)
     end
 
-    def after_execute(&callback)
-      self.after_execute_callback = callback
+    def before_execution(&block)
+      callbacks.register([:before, :execution], block)
+    end
+
+    def after_execution(&block)
+      callbacks.register([:after, :execution], block)
+    end
+
+    def around_execution(&block)
+      callbacks.register([:around, :execution], block)
     end
 
     private
 
+    def callbacks
+      @callbacks ||= NxtPipeline::Callbacks.new(pipeline: self)
+    end
+
     attr_reader :error_callbacks, :constructors, :step_resolvers
     attr_accessor :current_step,
                   :current_arg,
-                  :default_constructor_name,
-                  :before_execute_callback,
-                  :after_execute_callback
+                  :default_constructor_name
 
     def default_constructor
       return unless default_constructor_name
@@ -138,12 +148,12 @@ module NxtPipeline
       @default_constructor ||= constructors[default_constructor_name.to_sym]
     end
 
-    def execute_step(step, **changeset)
+    def execute_step(step, **change_set)
       self.current_step = step
-      self.current_arg = changeset
-      result = step.execute(**changeset)
+      self.current_arg = change_set
+      result = step.execute(**change_set)
       log_step(step)
-      result || changeset
+      result || change_set
     end
 
     def find_error_callback(error)
@@ -168,5 +178,30 @@ module NxtPipeline
     def default_step_resolvers
       [->(step_argument) { step_argument.is_a?(Symbol) && step_argument }]
     end
+
+    def decorate_error_with_details(error, change_set, step, logger)
+      error.define_singleton_method :details do
+        OpenStruct.new(
+          change_set: change_set,
+          logger: logger,
+          step: step
+        )
+      end
+      error
+    end
+
+    def register_step(argument, constructor, callbacks, **opts)
+      steps << Step.new(argument, constructor, steps.count, self, callbacks, **opts)
+    end
+
+    def handle_error_of_step(error)
+      error_callback = find_error_callback(error)
+      raise error unless error_callback.present? && error_callback.continue_after_error?
+
+      log_step(current_step)
+      raise error unless error_callback.present?
+
+      error_callback.call(current_step, current_arg, error)
+    end
   end
 end

data/lib/nxt_pipeline/step.rb

@@ -1,8 +1,10 @@
 module NxtPipeline
   class Step
-    def initialize(argument, constructor, index, **opts)
+    def initialize(argument, constructor, index, pipeline, callbacks, **opts)
       define_attr_readers(opts)
 
+      @pipeline = pipeline
+      @callbacks = callbacks
       @argument = argument
       @index = index
       @opts = opts
@@ -16,21 +18,37 @@ module NxtPipeline
       @mapped_options = nil
     end
 
-    attr_reader :argument, :result, :status, :execution_started_at, :execution_finished_at, :execution_duration, :error, :opts, :index, :mapped_options
+    attr_reader :argument,
+      :result,
+      :status,
+      :execution_started_at,
+      :execution_finished_at,
+      :execution_duration,
+      :error,
+      :opts,
+      :index,
+      :mapped_options
+
     attr_accessor :to_s
 
     alias_method :name=, :to_s=
     alias_method :name, :to_s
 
-    def execute(**changeset)
+    def execute(**change_set)
       track_execution_time do
-        set_mapped_options(changeset)
-        guard_args = [changeset, self]
+        set_mapped_options(change_set)
+        guard_args = [change_set, self]
+
+        callbacks.run(:before, :step, change_set)
 
         if evaluate_unless_guard(guard_args) && evaluate_if_guard(guard_args)
-          self.result = construct_result(changeset)
+          callbacks.around(:step, change_set) do
+            set_result(change_set)
+          end
         end
 
+        callbacks.run(:after, :step, change_set)
+
         set_status
         result
       end
@@ -40,16 +58,16 @@ module NxtPipeline
       raise
     end
 
-    def set_mapped_options(changeset)
+    def set_mapped_options(change_set)
       mapper = options_mapper || default_options_mapper
-      mapper_args = [changeset, self].take(mapper.arity)
+      mapper_args = [change_set, self].take(mapper.arity)
       self.mapped_options = mapper.call(*mapper_args)
     end
 
     private
 
     attr_writer :result, :status, :error, :mapped_options, :execution_started_at, :execution_finished_at, :execution_duration
-    attr_reader :constructor, :options_mapper
+    attr_reader :constructor, :options_mapper, :pipeline, :callbacks
 
     def evaluate_if_guard(args)
       execute_callable(if_guard, args)
@@ -59,9 +77,9 @@ module NxtPipeline
       !execute_callable(unless_guard, args)
     end
 
-    def construct_result(changeset)
-      args = [self, changeset]
-      execute_callable(constructor, args)
+    def set_result(change_set)
+      args = [self, change_set]
+      self.result = execute_callable(constructor, args)
     end
 
     def execute_callable(callable, args)
@@ -123,4 +141,4 @@ module NxtPipeline
       ->(_) { {} }
     end
   end
-end
+end

data/lib/nxt_pipeline/version.rb

@@ -1,4 +1,4 @@
 module NxtPipeline
-  VERSION = "0.4.3".freeze
+  VERSION = "1.0.0".freeze
 end
 

data/nxt_pipeline.gemspec

@@ -35,6 +35,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "activesupport"
+  spec.add_dependency "nxt_registry"
   spec.add_development_dependency "bundler", "~> 2.1"
   spec.add_development_dependency "guard-rspec"
   spec.add_development_dependency "rake", "~> 13.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nxt_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Nils Sommer
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-10-23 00:00:00.000000000 Z
+date: 2021-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -26,6 +26,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: nxt_registry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -121,6 +135,7 @@ files:
 - bin/rspec
 - bin/setup
 - lib/nxt_pipeline.rb
+- lib/nxt_pipeline/callbacks.rb
 - lib/nxt_pipeline/constructor.rb
 - lib/nxt_pipeline/error_callback.rb
 - lib/nxt_pipeline/logger.rb