nxt_pipeline 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77672035013c0cfe29bb5c5057178a9822e25c5b02e83b87a8cbb8dadac1d687
-  data.tar.gz: bb097fa702a19a9756d86a2ff63792bed998d9f8c5425263864695606bfca70d
+  metadata.gz: 5682c4e905d939b057c79b775c8401f1da648a0e5793c1c438dfef3cdb741147
+  data.tar.gz: 8908bf0ab622f472ccdb1a91cce704b0e88181352f4dfa0bb1942a684b60729b
 SHA512:
-  metadata.gz: 2d355345b5aadcb3d02895cd85196cc60b34caef8c919d11480a5a2cd429c5e32baa37c83f8e169ca316311735343297ba0a3b763044e12ac02c8349cc849929
-  data.tar.gz: eeaa40df4479d0b4b39e5cfe5fd89756d6681dc3d9e9f96e65f6f1e4f9793c588298c33c0fa446c0f7ddf73a3a9e4a43c5da5f371cf25928f18c80bed52e3e58
+  metadata.gz: e33df278d8ba33998cc798f6b1a97461360e81af3a0bad83549d74bf00190e8ef7d4aa2459f513bc1e4b3e750785058ae708c90136bfc17bebf0faf79fa7aed0
+  data.tar.gz: '09d1caf2cd41693f56fddbcf6e70e4ba4b2212b7ce9fd3669e736a6afa39245a177d79171a5819bd3842192a5a3927931a4cb99dd86a3b98e24a834e18460218'

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## nxt_pipeline 2.0.0 (10.05.2022)
+
+- Rename `Pipeline.execute` to `Pipeline.call`
+- Pipeline#call accepts any argument instead of just key word arguments or hashes 
+- Introduce constructor resolvers
+- Expose :new and :call directly on NxtPipeline instead of only through NxtPipeline::Pipeline class
+- Change step DSL: Introduce constructor option to specify the constructor to use for a step
+- Introduce Configurations
+- Expose step.status and step.meta_data accessors to set status and meta_data of steps in constructors
+- Change arguments of error callbacks to be error, acc, step instead of acc, step, error and only pass by arity of callback
+
 ## nxt_pipeline 1.0.0 (24.11.2020)
 
 Replace after and before execute hooks with proper callbacks.

data/Gemfile.lock

@@ -1,32 +1,31 @@
 PATH
   remote: .
   specs:
-    nxt_pipeline (1.0.0)
+    nxt_pipeline (2.0.0)
       activesupport
       nxt_registry
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.1.1)
+    activesupport (7.0.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       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.16.2)
+    concurrent-ruby (1.1.10)
+    diff-lcs (1.5.0)
+    ffi (1.15.5)
+    formatador (1.1.0)
+    guard (2.18.0)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
       lumberjack (>= 1.0.12, < 2.0)
       nenv (~> 0.1)
       notiffany (~> 0.0)
-      pry (>= 0.9.12)
+      pry (>= 0.13.0)
       shellany (~> 0.0)
       thor (>= 0.18.1)
     guard-compat (1.2.1)
@@ -34,19 +33,19 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.8.7)
+    i18n (1.10.0)
       concurrent-ruby (~> 1.0)
-    listen (3.4.1)
+    listen (3.7.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.3)
+    minitest (5.15.0)
     nenv (0.3.0)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    nxt_registry (0.3.6)
+    nxt_registry (0.3.10)
       activesupport
     pry (0.13.1)
       coderay (~> 1.1)
@@ -54,30 +53,29 @@ GEM
     pry-byebug (3.9.0)
       byebug (~> 11.0)
       pry (~> 0.13.0)
-    rake (13.0.3)
-    rb-fsevent (0.10.4)
+    rake (13.0.6)
+    rb-fsevent (0.11.1)
     rb-inotify (0.10.1)
       ffi (~> 1.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)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.1)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-support (3.10.1)
-    rspec_junit_formatter (0.4.1)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    rspec_junit_formatter (0.5.1)
       rspec-core (>= 2, < 4, != 2.12.0)
     shellany (0.0.1)
-    thor (1.1.0)
+    thor (1.2.1)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
-    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby

data/README.md

@@ -2,7 +2,17 @@
 
 # NxtPipeline
 
-nxt_pipeline provides a DSL to define pipeline classes which take an object and pass it through multiple steps which can read or modify the object.
+NxtPipeline is an orchestration framework for your service objects or function objects, how I like to call them.
+Service objects are a very wide spread way of organizing code in the Ruby and Rails communities. Since it's little classes
+doing one thing you can think of them as function objects and thus they often share a common interface in a project. 
+There are also many frameworks out there that normalize the usage of service objects and provide a specific way
+of writing service objects and often also allow to orchestrate (reduce) these service objects.
+Compare [light-service](https://github.com/adomokos/light-service) for instance.
+
+The idea of NxtPipeline was to build a flexible orchestration framework for service objects without them having to conform
+to a specific interface. Instead NxtPipeline expects you to specify how to execute different kinds of service objects
+through so called constructors and thereby does not dictate you how to write your service objects. Nevertheless this still
+mostly makes sense if your service objects share common interfaces to keep the necessary configuration to a minimum.
 
 ## Installation
 
@@ -22,155 +32,260 @@ Or install it yourself as:
 
 ## Usage
 
-### Constructors
+### Example
 
-First you probably want to configure a pipeline so that it can execute your steps.
-Therefore you want to define constructors for your steps. Constructors take a name
-as the first argument and step options as the second. All step options are being exposed
-by the step yielded to the constructor.
+Let's look at an example. Here validator service objects are orchestrated with NxtPipeline to build a validation 
+pipeline. We inject the accumulator `{ value: 'aki', errors: [] }` that is then passed through all validation steps. 
+If an validator returns an error it's added to the array of errors of the accumulator to collect all errors of all steps.
 
 ```ruby
-pipeline = NxtPipeline::Pipeline.new do |p|
-  # Add a named constructor that will be used to execute your steps later
-  # All options that you pass in your step will be available through accessors in your constructor
-  # You can call :to_s on a step to set it by default. You can later overwrite at execution for each step if needed.
-  p.constructor(:service, default: true) do |step, arg:|
-    step.to_s = step.service_class.to_s
-    result = step.service_class.new(options: arg).call
-    result && { arg: result }
+class Validator
+  attr_accessor :error
+end
+
+class TypeChecker < Validator
+  def initialize(value, type:)
+    @value = value
+    @type = type
   end
 
-  p.constructor(:job) do |step, arg:|
-    step.job_class.perform_later(*arg) && { arg: arg }
+  attr_reader :value, :type
+
+  def call
+    return if value.is_a?(type)
+    self.error = "Value does not match type #{type}"
   end
 end
 
-# Once a pipeline was created you can still configure it
-pipeline.constructor(:call) do |step, arg:|
-  result = step.caller.new(arg).call
-  result && { arg: result }
+class MinSize < Validator
+  def initialize(value, size:)
+    @value = value
+    @size = size
+  end
+
+  attr_reader :value, :size
+
+  def call
+    return if value.size >= size
+    self.error = "Value size must be greater than #{size-1}"
+  end
 end
 
-# same with block syntax
-# You can use this to split up execution from configuration
-pipeline.configure do |p|
- p.constructor(:call) do |step, arg:|
-   result = step.caller.new(arg).call
-   result && { arg: result }
- end
+class MaxSize < Validator
+  def initialize(value, size:)
+    @value = value
+    @size = size
+  end
+
+  attr_reader :value, :size
+
+  def call
+    return if value.size <= size
+    self.error = "Value size must be less than #{size+1}"
+  end
 end
+
+class Uniqueness < Validator
+  def initialize(value, scope:)
+    @value = value
+    @scope = scope
+  end
+
+  attr_reader :value, :scope
+
+  def call
+    return if scope.count { |item| item == value }
+    self.error = "Value is not unique in: #{scope}"
+  end
+end
+
+result = NxtPipeline.call({ value: 'aki', errors: [] }) do |p|
+  p.constructor(:validator, default: true) do |acc, step|
+    validator = step.argument.new(acc.fetch(:value), **step.options)
+    validator.call
+    acc[:errors] << validator.error if validator.error.present?
+
+    acc
+  end
+
+  p.step TypeChecker, options: { type: String }
+  p.step MinSize, options: { size: 4 }
+  p.step MaxSize, options: { size: 10 }
+  p.step Uniqueness, options: { scope: ['andy', 'aki', 'lütfi', 'rapha'] }
+end
+
+result # => { value: 'aki', errors: ['Value size must be greater than 3'] } 
 ```
 
-### Defining steps
+### Constructors
+
+In order to reduce over your service objects you have to define constructors so that the pipeline knows how to execute
+a specific step. You can define constructors globally and specific to a pipeline.
+
+Make a constructor available for all pipelines of your project by defining it globally with:
+
+```ruby
+NxtPipeline.constructor(:service) do |acc, step|
+  validator = step.argument.new(acc.fetch(:value), **step.options)
+  validator.call
+  acc[:errors] << validator.error if validator.error.present?
+
+  acc
+end
+```
 
-Once your pipeline knows how to execute your steps you can add those.
+Or define a constructor only locally for a specific pipeline.
 
 ```ruby
-pipeline.step :service, service_class: MyServiceClass, to_s: 'First step'
-pipeline.step service_class: MyOtherServiceClass, to_s: 'Second step'
-# ^ Since service is the default step you don't have to specify it the step type each time
-pipeline.step :job, job_class: MyJobClass # to_s is optional
-pipeline.step :job, job_class: MyOtherJobClass
+NxtPipeline.new({ value: 'aki', errors: [] }) do |p|
+  p.constructor(:validator, default: true) do |acc, step|
+    validator = step.argument.new(acc.fetch(:value), **step.options)
+    validator.call
+    acc[:errors] << validator.error if validator.error.present?
+
+    acc
+  end
 
-pipeline.step :step_name_for_better_log do |_, arg:|
+  p.step TypeChecker, options: { type: String }
   # ...
 end
+```
+
+Constructor Hierarchy
 
-pipeline.step to_s: 'This is the same as above' do |step, arg:|
-  # ... step.to_s => 'This is the same as above'
+In order to execute a specific step the pipeline firstly checks whether a constructor was specified for a step: 
+`pipeline.step MyServiceClass, constructor: :service`. If this is not the case it checks whether there is a resolver 
+registered that applies. If that's not the case the pipeline checks if there is a constructor registered for the 
+argument that was passed in. This means if you register constructors directly for the arguments you pass in you don't
+have to specify this constructor option. Therefore the following would work without the need to provide a constructor 
+for the steps.
+
+```ruby
+NxtPipeline.new({}) do |p|
+  p.constructor(:service) do |acc, step|
+    step.service_class.new(acc).call
+  end
+
+  p.step :service, service_class: MyServiceClass
+  p.step :service, service_class: MyOtherServiceClass
+  # ...
 end
 ```
 
-You can also define inline steps, meaning the block will be executed. When you do not provide a :to_s option, type
-will be used as :to_s option per default. When no type was given for an inline block the type of the inline block
-will be set to :inline.
+Lastly if no constructor could be resolved directly from the step argument, the pipelines falls back to the locally
+and then to the globally defined default constructors.
 
-### Execution
+### Defining steps
 
-You can then execute the steps with:
+Once your pipeline knows how to execute your steps you can add those. The `pipeline.step` method expects at least one
+argument which you can access in the constructor through `step.argument`. You can also pass in additional options
+that you can access through readers of a step. The `constructor:` option defines which constructor to use for a step
+where as you can name a step with the `to_s:` option.
 
 ```ruby
-pipeline.execute(arg: 'initial argument')
+# explicitly define which constructor to use 
+pipeline.step MyServiceClass, constructor: :service
+# use a block as inline constructor
+pipeline.step SpecialService, constructor: ->(step, arg:) { step.argument.call(arg: arg) }
+# Rely on the default constructor
+pipeline.step MyOtherServiceClass
+# Define a step name
+pipeline.step MyOtherServiceClass, to_s: 'First Step'
+# Or simply execute a (named) block - NO NEED TO DEFINE A CONSTRUCTOR HERE  
+pipeline.step :step_name_for_better_log do |acc, step|
+  # ...
+end
+```
 
-# Or run the steps directly using block syntax
+Defining multiple steps at once. This is especially useful to dynamically configure a pipeline for execution and
+can potentially even come from a yaml configuration or from the database.
 
-pipeline.execute(arg: 'initial argument') do |p|
-  p.step :service, service_class: MyServiceClass, to_s: 'First step'
-  p.step :service, service_class: MyOtherServiceClass, to_s: 'Second step'
-  p.step :job, job_class: MyJobClass # to_s is optional
-  p.step :job, job_class: MyOtherJobClass
-end
+```ruby
+pipeline.steps([
+  [MyServiceClass, constructor: :service],
+  [MyOtherServiceClass, constructor: :service],
+  [MyJobClass, constructor: :job]
+])
+
+# You can also overwrite the steps of a pipeline through explicitly setting them. This will remove any previously 
+# defined steps.
+pipeline.steps = [
+  [MyServiceClass, constructor: :service],
+  [MyOtherServiceClass, constructor: :service]
+]
+```
+
+### Execution
 
+Once a pipeline contains steps you can call it with `call(accumulator)` whereas it expects you to inject the accumulator
+as argument that is then passed through all steps.
+
+```ruby
+pipeline.call(arg: 'initial argument')
+
+# Or directly pass the steps you want to execute:
+pipeline.call(arg: 'initial argument') do |p|
+  p.step MyServiceClass, to_s: 'First step'
+  p.step MyOtherServiceClass, to_s: 'Second step'
+  p.step MyJobClass, constructor: :job
+  p.step MyOtherJobClass, constructor: :job
+end
 ```
 
-You can also directly execute a pipeline with:
+You can also create a new instance of a pipeline and directly run it with `call`:
 
 ```ruby
-NxtPipeline::Pipeline.execute(arg: 'initial argument') do |p|
-  p.step do |_, arg:|
-    { arg: arg.upcase }
-  end
+NxtPipeline.call(arg: 'initial argument') do |p|
+  p.steps # ...
 end
 ```
 
 You can query the steps of your pipeline simply by calling `pipeline.steps`. A NxtPipeline::Step will provide you with
-an interface to it's type, options, status (:success, :skipped, :failed), execution_finished_at execution_started_at, execution_duration, result, error and the index in the pipeline.
+an interface for options, status, execution_finished_at execution_started_at,
+execution_duration, result, error and the index in the pipeline.
 
 ```
 pipeline.steps.first
-# will give you something like this:
-
-#<NxtPipeline::Step:0x00007f83eb399448
- @constructor=
-  #<Proc:0x00007f83eb399498@/Users/andy/workspace/nxt_pipeline/spec/pipeline_spec.rb:467>,
- @error=nil,
- @index=0,
- @opts={:to_s=>:transformer, :method=>:upcase},
- @result=nil,
- @status=nil,
- @type=:transformer
- @execution_duration=1.0e-05,
- @execution_finished_at=2020-10-22 15:52:55.806417 +0100,
- @execution_started_at=2020-10-22 15:52:55.806407 +0100,>
+# will give you a step object
+#<NxtPipeline::Step:0x00007f83eb399448...>
 ```
 
 ### Guard clauses
 
 You can also define guard clauses that take a proc to prevent the execution of a step.
-When the guard takes an argument the step argument is yielded.
+A guard can accept the change set and the step as arguments.
 
  ```ruby
- pipeline.execute(arg: 'initial argument') do |p|
-   p.step :service, service_class: MyServiceClass, if: -> (arg:) { arg == 'initial argument' }
-   p.step :service, service_class: MyOtherServiceClass, unless: -> { false }
- end
+ pipeline.call('initial argument') do |p|
+  p.step MyServiceClass, if: -> (acc, step) { acc == 'initial argument' }
+  p.step MyOtherServiceClass, unless: -> { false }
+end
 
  ```
 
 ### Error callbacks
 
-Apart from defining constructors and steps you can also define error callbacks.
+Apart from defining constructors and steps you can also define error callbacks. Error callbacks can accept up to  
+three arguments: `error, acc, step`.
 
 ```ruby
-NxtPipeline::Pipeline.new do |p|
-  p.step do |_, arg:|
-    { arg: arg.upcase }
-  end
+NxtPipeline.new do |p|
+  p.step # ... 
 
-  p.on_error MyCustomError do |step, opts, error|
+  p.on_error MyCustomError do |error|
     # First matching error callback will be executed!
   end
 
-  p.on_errors ArgumentError, KeyError do |step, opts, error|
+  p.on_errors ArgumentError, KeyError do |error, acc|
     # First matching error callback will be executed!
   end
 
-  p.on_errors YetAnotherError, halt_on_error: false do |step, opts, error|
+  p.on_errors YetAnotherError, halt_on_error: false do |error, acc, step|
     # After executing the callback the pipeline will not halt but continue to
     # execute the next steps.
   end
 
-  p.on_errors do |step, opts, error|
+  p.on_errors do |error, acc, step|
     # This will match all errors inheriting from StandardError
   end
 end
@@ -179,12 +294,13 @@ end
 ### Before, around and after callbacks
 
 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.
+multiple callbacks, but probably you want to keep them to a minimum to not end up in hell. Also note that before and
+after callbacks will run even if a step was skipped through a guard clause.
 
 #### Step callbacks
 
 ```ruby
-NxtPipeline::Pipeline.new do |p|
+NxtPipeline.new do |p|
   p.before_step do |_, change_set|
     change_set[:acc] << 'before step 1'
     change_set
@@ -207,7 +323,7 @@ end
 #### Execution callbacks
 
 ```ruby
-NxtPipeline::Pipeline.new do |p|
+NxtPipeline.new do |p|
   p.before_execution do |_, change_set|
     change_set[:acc] << 'before execution 1'
     change_set
@@ -227,18 +343,121 @@ NxtPipeline::Pipeline.new do |p|
 end
 ```
 
-Note that the `after_execute` callback will not be called in case a step raises an error. 
+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
+### Constructor resolvers
+
+You can also define constructor resolvers for a pipeline to dynamically define which previously registered constructor
+to use for a step based on the argument and options passed to the step.
+
+```ruby
+class Transform
+  def initialize(word, operation)
+    @word = word
+    @operation = operation
+  end
+
+  attr_reader :word, :operation
+
+  def call
+    word.send(operation)
+  end
+end
+
+NxtPipeline.new do |pipeline|
+  # dynamically resolve to use a proc as constructor
+  pipeline.constructor_resolver do |argument, **opts|
+    argument.is_a?(Class) &&
+      ->(step, arg:) {
+        result = step.argument.new(arg, opts.fetch(:operation)).call
+        # OR result = step.argument.new(arg, step.operation).call
+        { arg: result }
+      }
+  end
+
+  # dynamically resolve to a defined constructor
+  pipeline.constructor_resolver do |argument|
+    argument.is_a?(String) && :dynamic
+  end
+
+  pipeline.constructor(:dynamic) do |step, arg:|
+    if step.argument == 'multiply'
+      { arg: arg * step.multiplier }
+    elsif step.argument == 'symbolize'
+      { arg: arg.to_sym }
+    else
+      raise ArgumentError, "Don't know how to deal with argument: #{step.argument}"
+    end
+  end
+
+  pipeline.step Transform, operation: 'upcase'
+  pipeline.step 'multiply', multiplier: 2
+  pipeline.step 'symbolize'
+  pipeline.step :extract_value do |arg|
+    arg
+  end
+end
+```
+
+### Configurations
+
+You probably do not have that many different kinds of steps that you execute within your pipelines. Otherwise the whole
+concept does not make much sense. To make constructing a pipeline simpler you can therefore define configurations on
+a global level simply by providing a name for a configuration along with a configuration block.
+Then you then create a preconfigure pipeline by passing in the name of the configuration when creating a new pipeline.
+
+```ruby
+# Define configurations in your initializer or somewhere upfront 
+NxtPipeline.configuration(:test_processor) do |pipeline|
+  pipeline.constructor(:processor) do |arg, step|
+    { arg: step.argument.call(arg: arg) }
+  end
+end
+
+NxtPipeline.configure(:validator) do |pipeline|
+  pipeline.constructor(:validator) do |arg, step|
+    # ..
+  end
+end
 
-NxtPipeline is using so called step_resolvers to find the constructor for a given step by the arguments passed in.
-You can also use this if you are not fine with resolving the constructor from the step argument. Check out the
-`nxt_pipeline/spec/step_resolver_spec.rb` for examples how you can implement your own step_resolvers.
+# ...
 
+# Later create a pipeline with a previously defined configuration
+NxtPipeline.new(configuration: :test_processor) do |p|
+  p.step ->(arg) { arg + 'first ' }, constructor: :processor
+  p.step ->(arg) { arg + 'second ' }, constructor: :processor
+  p.step ->(arg) { arg + 'third' }, constructor: :processor
+end
+```
+
+### Step status and meta_data
+When executing your steps you can also log the status of a step by setting it in your constructors or callbacks in 
+which you have access to the steps.
+
+```ruby
+pipeline = NxtPipeline.new do |pipeline|
+  pipeline.constructor(:step, default: true) do |acc, step|
+    result = step.proc.call(acc)
+    step.status = result.present? # Set the status here
+    step.meta_data = 'additional info' # or some meta data
+    acc
+  end
+
+  pipeline.step :first_step do |acc, step|
+    step.status = 'it worked'
+    step.meta_data = { extra: 'info' }
+    acc
+  end
+
+  pipeline.step :second, proc: ->(acc) { acc }
+end
+
+pipeline.logger.log # => { "first_step" => 'it worked', "second" => true } 
+pipeline.steps.map(&:meta_data) # => [{:extra=>"info"}, "additional info"]
+```
 
 ## Topics
-- Constructors should take arg as first and step as second arg
 
 ## Development
 

data/lib/nxt_pipeline/callbacks.rb

@@ -10,8 +10,11 @@ module NxtPipeline
     end
 
     def run(kind_of_callback, type, change_set)
-      registry.resolve!(kind_of_callback, type).each do |callback|
-        run_callback(callback, change_set)
+      callbacks = registry.resolve!(kind_of_callback, type)
+      return unless callbacks.any?
+
+      callbacks.inject(change_set) do |changes, callback|
+        run_callback(callback, changes)
       end
     end
 
@@ -20,7 +23,7 @@ module NxtPipeline
       return execution.call unless around_callbacks.any?
 
       callback_chain = around_callbacks.reverse.inject(execution) do |previous, callback|
-        -> { callback.call(pipeline, change_set, previous) }
+        -> { callback.call(change_set, previous, pipeline) }
       end
 
       callback_chain.call
@@ -31,8 +34,8 @@ module NxtPipeline
     attr_reader :registry, :pipeline
 
     def run_callback(callback, change_set)
-      args = [pipeline, change_set]
-      args = args.take(callback.arity)
+      args = [change_set, pipeline]
+      args = args.take(callback.arity) unless callback.arity.negative?
       callback.call(*args)
     end
 

data/lib/nxt_pipeline/error_callback.rb

@@ -20,8 +20,11 @@ module NxtPipeline
       (error.class.ancestors & errors).any?
     end
 
-    def call(step, arg, error)
-      callback.call(step, arg, error)
+    def call(error, acc, step)
+      args = [error, acc, step]
+      args = args.take(callback.arity) unless callback.arity.negative?
+
+      callback.call(*args)
     end
   end
 end

data/lib/nxt_pipeline/pipeline.rb

@@ -1,10 +1,10 @@
 module NxtPipeline
   class Pipeline
-    def self.execute(**opts, &block)
-      new(&block).execute(**opts)
+    def self.call(acc, configuration: nil, resolvers: [], &block)
+      new(configuration: configuration, resolvers: resolvers, &block).call(acc)
     end
 
-    def initialize(step_resolvers = default_step_resolvers, &block)
+    def initialize(configuration: nil, resolvers: [], &block)
       @steps = []
       @error_callbacks = []
       @logger = Logger.new
@@ -12,27 +12,34 @@ module NxtPipeline
       @current_arg = nil
       @default_constructor_name = nil
       @constructors = {}
-      @step_resolvers = step_resolvers
+      @constructor_resolvers = resolvers
+      @result = nil
+
+      if configuration.present?
+        config = ::NxtPipeline.configuration(configuration)
+        configure(&config)
+      end
 
       configure(&block) if block_given?
     end
 
     alias_method :configure, :tap
 
-    attr_accessor :logger, :steps
+    attr_accessor :logger
+    attr_reader :result
 
-    def constructor(name, **opts, &constructor)
+    def constructor(name, default: false, &constructor)
       name = name.to_sym
       raise StandardError, "Already registered step :#{name}" if constructors[name]
 
-      constructors[name] = Constructor.new(name, **opts, &constructor)
+      constructors[name] = constructor
 
-      return unless opts.fetch(:default, false)
+      return unless default
       set_default_constructor(name)
     end
 
-    def step_resolver(&block)
-      step_resolvers << block
+    def constructor_resolver(&block)
+      constructor_resolvers << block
     end
 
     def set_default_constructor(default_constructor)
@@ -44,61 +51,128 @@ module NxtPipeline
       raise ArgumentError, 'Default step already defined'
     end
 
-    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
-        argument ||= :inline
-        opts.reverse_merge!(to_s: argument)
-        Constructor.new(:inline, **opts, &block)
+    # Overwrite reader to also define steps
+    def steps(steps = [])
+      return @steps unless steps.any?
+
+      steps.each do |args|
+        arguments = Array(args)
+        if arguments.size == 1
+          step(arguments.first)
+        elsif arguments.size == 2
+          step(arguments.first, **arguments.second)
+        else
+          raise ArgumentError, "Either pass a single argument or an argument and options"
+        end
+      end
+    end
+
+    # Allow to force steps with setter
+    def steps=(steps = [])
+      # reset steps to be zero
+      @steps = []
+      steps(steps)
+    end
+
+    def step(argument, constructor: nil, **opts, &block)
+
+      if constructor.present? and block_given?
+        msg = "Either specify a block or a constructor but not both at the same time!"
+        raise ArgumentError, msg
+      end
+
+      to_s = if opts[:to_s].present?
+               opts[:to_s] = opts[:to_s].to_s
+             else
+               if argument.is_a?(Proc) || argument.is_a?(Method)
+                 steps.count.to_s
+               else
+                 argument.to_s
+               end
+             end
+
+
+      opts.reverse_merge!(to_s: to_s)
+
+      if constructor.present?
+        # p.step Service, constructor: ->(step, **changes) { ... }
+        if constructor.respond_to?(:call)
+          resolved_constructor = constructor
+        else
+          # p.step Service, constructor: :service
+          resolved_constructor = constructors.fetch(constructor) {
+            ::NxtPipeline.constructor(constructor) || (raise ArgumentError, "No constructor defined for #{constructor}")
+          }
+        end
+      elsif block_given?
+        # p.step :inline do ... end
+        resolved_constructor = block
       else
-        constructor = step_resolvers.lazy.map do |resolver|
-          resolver.call(argument)
+        # If no constructor was given try to resolve one
+        resolvers = constructor_resolvers.any? ? constructor_resolvers : []
+
+        constructor_from_resolvers = resolvers.map do |resolver|
+          resolver.call(argument, **opts)
         end.find(&:itself)
 
-        if constructor
-          constructor && constructors.fetch(constructor) { raise KeyError, "No step :#{argument} registered" }
-        elsif default_constructor
-          argument ||= default_constructor_name
-          default_constructor
+        # resolved constructor is a proc
+        if constructor_from_resolvers.is_a?(Proc)
+          resolved_constructor = constructor_from_resolvers
+        elsif constructor_from_resolvers.present?
+          resolved_constructor = constructors[constructor_from_resolvers]
         else
-          raise StandardError, "Could not resolve step from: #{argument}"
+          # try to resolve constructor by argument --> #TODO: Is this a good idea?
+          resolved_constructor = constructors[argument]
+        end
+
+
+        # if still no constructor resolved
+        unless resolved_constructor.present?
+          if argument.is_a?(NxtPipeline::Pipeline)
+            pipeline_constructor = ->(changes) { argument.call(changes) }
+            resolved_constructor = pipeline_constructor
+          # last chance: default constructor
+          elsif default_constructor.present?
+            resolved_constructor = default_constructor
+          # now we really give up :-(
+          else
+            raise ArgumentError, "Could neither find nor resolve any constructor for #{argument}, #{opts}"
+          end
         end
       end
 
-      register_step(argument, constructor, callbacks, **opts)
+      register_step(argument, resolved_constructor, callbacks, **opts)
     end
 
-    def execute(**change_set, &block)
+    def call(acc, &block)
       reset
 
       configure(&block) if block_given?
-      callbacks.run(:before, :execution, change_set)
+      callbacks.run(:before, :execution, acc)
 
-      result = callbacks.around :execution, change_set do
-        steps.inject(change_set) do |set, step|
-          execute_step(step, **set)
+      self.result = callbacks.around :execution, acc do
+        steps.inject(acc) do |changes, step|
+          self.result = call_step(step, changes)
         rescue StandardError => error
-          decorate_error_with_details(error, set, step, logger)
-          handle_error_of_step(error)
-          set
+          decorate_error_with_details(error, changes, step, logger)
+          handle_error_of_step(step, error)
+          result
         end
       end
 
-      callbacks.run(:after, :execution, change_set)
-      result
+      # callbacks.run(:after, :execution, result) TODO: Better pass result to callback?
+      self.result = callbacks.run(:after, :execution, acc) || 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)
 
       raise unless callback
 
-      callback.call(current_step, current_arg, error)
+      callback.call(error, current_arg, current_step)
     end
 
     def on_errors(*errors, halt_on_error: true, &callback)
@@ -133,14 +207,15 @@ module NxtPipeline
 
     private
 
+    attr_writer :result
+
     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
+    attr_reader :error_callbacks, :constructors, :constructor_resolvers
+    attr_writer :default_constructor_name
+    attr_accessor :current_step, :current_arg
 
     def default_constructor
       return unless default_constructor_name
@@ -148,12 +223,12 @@ module NxtPipeline
       @default_constructor ||= constructors[default_constructor_name.to_sym]
     end
 
-    def execute_step(step, **change_set)
+    def call_step(step, acc)
       self.current_step = step
-      self.current_arg = change_set
-      result = step.execute(**change_set)
+      self.current_arg = acc
+      result = step.call(acc)
       log_step(step)
-      result || change_set
+      result || acc
     end
 
     def find_error_callback(error)
@@ -171,13 +246,6 @@ module NxtPipeline
       self.current_step = nil
     end
 
-    def raise_reserved_type_inline_error
-      raise ArgumentError, 'Type :inline is reserved for inline steps!'
-    end
-
-    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
@@ -194,14 +262,18 @@ module NxtPipeline
       steps << Step.new(argument, constructor, steps.count, self, callbacks, **opts)
     end
 
-    def handle_error_of_step(error)
+    def handle_error_of_step(step, error)
       error_callback = find_error_callback(error)
       raise error unless error_callback.present? && error_callback.continue_after_error?
 
-      log_step(current_step)
+      log_step(step)
       raise error unless error_callback.present?
 
-      error_callback.call(current_step, current_arg, error)
+      error_callback.call(error, current_arg, step)
+    end
+
+    def default_constructor_name
+      @default_constructor_name || ::NxtPipeline.default_constructor_name
     end
   end
 end

data/lib/nxt_pipeline/step.rb

@@ -1,26 +1,29 @@
 module NxtPipeline
   class Step
+    RESERVED_OPTION_KEYS  = %i[to_s unless if]
+
     def initialize(argument, constructor, index, pipeline, callbacks, **opts)
-      define_attr_readers(opts)
+      @opts = opts.symbolize_keys
 
       @pipeline = pipeline
       @callbacks = callbacks
       @argument = argument
       @index = index
-      @opts = opts
       @constructor = constructor
-      @to_s = "#{opts.merge(argument: argument)}"
+      @to_s = opts.fetch(:to_s) { argument }
       @options_mapper = opts[:map_options]
 
       @status = nil
       @result = nil
       @error = nil
       @mapped_options = nil
+      @meta_data = nil
+
+      define_option_readers
     end
 
     attr_reader :argument,
       :result,
-      :status,
       :execution_started_at,
       :execution_finished_at,
       :execution_duration,
@@ -29,25 +32,23 @@ module NxtPipeline
       :index,
       :mapped_options
 
-    attr_accessor :to_s
+    attr_writer :to_s
+    attr_accessor :meta_data, :status
 
-    alias_method :name=, :to_s=
-    alias_method :name, :to_s
-
-    def execute(**change_set)
+    def call(acc)
       track_execution_time do
-        set_mapped_options(change_set)
-        guard_args = [change_set, self]
+        set_mapped_options(acc)
+        guard_args = [acc, self]
 
-        callbacks.run(:before, :step, change_set)
+        callbacks.run(:before, :step, acc)
 
         if evaluate_unless_guard(guard_args) && evaluate_if_guard(guard_args)
-          callbacks.around(:step, change_set) do
-            set_result(change_set)
+          callbacks.around(:step, acc) do
+            set_result(acc)
           end
         end
 
-        callbacks.run(:after, :step, change_set)
+        callbacks.run(:after, :step, acc)
 
         set_status
         result
@@ -58,15 +59,19 @@ module NxtPipeline
       raise
     end
 
-    def set_mapped_options(change_set)
+    def set_mapped_options(acc)
       mapper = options_mapper || default_options_mapper
-      mapper_args = [change_set, self].take(mapper.arity)
+      mapper_args = [acc, self].take(mapper.arity)
       self.mapped_options = mapper.call(*mapper_args)
     end
 
+    def to_s
+      @to_s.to_s
+    end
+
     private
 
-    attr_writer :result, :status, :error, :mapped_options, :execution_started_at, :execution_finished_at, :execution_duration
+    attr_writer :result, :error, :mapped_options, :execution_started_at, :execution_finished_at, :execution_duration
     attr_reader :constructor, :options_mapper, :pipeline, :callbacks
 
     def evaluate_if_guard(args)
@@ -77,19 +82,15 @@ module NxtPipeline
       !execute_callable(unless_guard, args)
     end
 
-    def set_result(change_set)
-      args = [self, change_set]
+    def set_result(acc)
+      args = [acc, self]
       self.result = execute_callable(constructor, args)
     end
 
     def execute_callable(callable, args)
-      args =  args.take(callable.arity)
+      args = args.take(callable.arity) unless callable.arity.negative?
 
-      if args.last.is_a?(Hash)
-        callable.call(*args.take(args.length - 1), **args.last)
-      else
-        callable.call(*args)
-      end
+      callable.call(*args)
     end
 
     def if_guard
@@ -104,8 +105,10 @@ module NxtPipeline
       -> { result }
     end
 
-    def define_attr_readers(opts)
-      opts.each do |key, value|
+    def define_option_readers
+      raise ArgumentError, "#{invalid_option_keys} are not allowed as options" if invalid_option_keys.any?
+
+      options_without_reserved_options.each do |key, value|
         define_singleton_method key.to_s do
           value
         end
@@ -113,6 +116,8 @@ module NxtPipeline
     end
 
     def set_status
+      return if status.present? # We do not set it if the constructor did already
+
       self.status = result.present? ? :success : :skipped
     end
 
@@ -140,5 +145,17 @@ module NxtPipeline
       # returns an empty hash
       ->(_) { {} }
     end
+
+    def options_without_reserved_options
+      opts.except(*reserved_option_keys)
+    end
+
+    def reserved_option_keys
+      @reserved_option_keys ||= methods + RESERVED_OPTION_KEYS
+    end
+
+    def invalid_option_keys
+      opts.except(*RESERVED_OPTION_KEYS).keys & methods
+    end
   end
 end

data/lib/nxt_pipeline/version.rb

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

data/lib/nxt_pipeline.rb

@@ -2,11 +2,48 @@ 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
+  class << self
+    delegate :new, :call, to: Pipeline
+  end
+
+  def configuration(name, &block)
+    @configurations ||= {}
+
+    if block_given?
+      raise ArgumentError, "Configuration already defined for #{name}" if @configurations[name].present?
+      @configurations[name] = block
+    else
+      @configurations.fetch(name)
+    end
+  end
+
+  def constructor(name, default: false, &block)
+    @constructors ||= {}
+
+    if block_given?
+      raise ArgumentError, "Constructor already defined for #{name}" if @constructors[name].present?
+
+      default_constructor_name(name) if default
+      @constructors[name] = block
+    else
+      @constructors.fetch(name)
+    end
+  end
+
+  def default_constructor_name(name = nil)
+    if name.present?
+      raise ArgumentError, "Default constructor #{@default_constructor_name} defined already" if @default_constructor_name.present?
+      @default_constructor_name = name
+    else
+      @default_constructor_name
+    end
+  end
+
+  module_function :configuration, :constructor, :default_constructor_name
 end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: nxt_pipeline
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Nils Sommer
 - Andreas Robecke
 - Raphael Kallensee
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-20 00:00:00.000000000 Z
+date: 2022-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -110,7 +110,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
 - mail@nilssommer.de
 executables: []
@@ -136,7 +136,6 @@ files:
 - 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
 - lib/nxt_pipeline/pipeline.rb
@@ -150,7 +149,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/nxt-insurance/nxt_pipeline
   source_code_uri: https://github.com/nxt-insurance/nxt_pipeline.git
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -166,7 +165,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: DSL to build Pipeline with mountable Segments to process things.
 test_files: []

data/lib/nxt_pipeline/constructor.rb

@@ -1,20 +0,0 @@
-module NxtPipeline
-  class Constructor
-    def initialize(name, **opts, &block)
-      @name = name
-      @block = block
-      @opts = opts
-    end
-
-    attr_reader :opts, :block
-    
-    delegate :arity, to: :block
-    
-    def call(*args, **opts, &block)
-      # ActiveSupport's #delegate does not properly handle keyword arg passing
-      # in the latest released version. Thefore we bypass delegation by reimplementing
-      # the method ourselves. This is already fixed in Rails master though.
-      self.block.call(*args, **opts, &block)
-    end
-  end
-end