nxt_pipeline 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3905e37feab9967d3cf749542c69adaa64280b788a7b862348e6002eff0e863f
-  data.tar.gz: d899cfc62cda30aaef508168130884ed1150f49120aae8b2ffe6552a03a61929
+  metadata.gz: 1a0f00d3ec3878cedc3f87bbd4a95d48ac4c16dcc998ad44a4b92aa083a91ac4
+  data.tar.gz: '0698836b0f3f0cf567faf3cd4fded931617a4b733eb58514dab0b89bed62963c'
 SHA512:
-  metadata.gz: 3de1e8ee02aa0778e673f97a2a58701ec548a6546f84d0bf2d63db5bf339fa267d61a6ff5193353e83f2ce3cfeb259b2ce2f08cab52150ca675364d018c83611
-  data.tar.gz: 65eec50438f474ae1d54c70e4baa6648e91cd8a28a662ece2efcec1a30eaf66350252541049995c66ef221fe77ba4f8bcd1f5a56aa97d9b59d96d731639ba801
+  metadata.gz: 23410c5a8ab7c9fd036ae4c6ad9b3cca91c849b121f4afc02f0658b87b261efb0542bdbd0d687067390e4e3c7ce2ae0ae3ccfbb36a42b1a07d94855aea1263f7
+  data.tar.gz: cf7a641b429f16655ef6f3103995a19661e2b4c2dc7ad9029c0053a90f18ff785565646f7a6da121a70cc2d84ca7bb8b6721eb680bc354a628a951c725f1940c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nxt_pipeline (0.2.8)
+    nxt_pipeline (0.3.0)
       activesupport
 
 GEM

data/README.md

@@ -32,26 +32,31 @@ by the step yielded to the constructor.
 ```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 
-  p.constructor(:service, default: true) do |step, arg|
-    step.service_class.new(options: arg).call
+  # 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 }
   end
   
-  p.constructor(:job) do |step, arg|
-    step.job_class.perform_later(*arg) && arg
+  p.constructor(:job) do |step, arg:|
+    step.job_class.perform_later(*arg) && { arg: arg }
   end
 end
 
 # Once a pipeline was created you can still configure it 
-pipeline.constructor(:call) do |step, arg|
-  step.caller.new(arg).call
+pipeline.constructor(:call) do |step, arg:|
+  result = step.caller.new(arg).call
+  result && { arg: result }
 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|
-   step.caller.new(arg).call
+ p.constructor(:call) do |step, arg:|
+   result = step.caller.new(arg).call
+   result && { arg: result }
  end
 end
 ```
@@ -67,11 +72,11 @@ pipeline.step service_class: MyOtherServiceClass, to_s: 'Second step'
 pipeline.step :job, job_class: MyJobClass # to_s is optional
 pipeline.step :job, job_class: MyOtherJobClass
 
-pipeline.step :step_name_for_better_log do |_, arg|
+pipeline.step :step_name_for_better_log do |_, arg:|
   # ...
 end
 
-pipeline.step to_s: 'This is the same as above' do |step, arg|
+pipeline.step to_s: 'This is the same as above' do |step, arg:|
   # ... step.to_s => 'This is the same as above'
 end
 ```
@@ -102,8 +107,8 @@ You can also directly execute a pipeline with:
 
 ```ruby
 NxtPipeline::Pipeline.execute('initial argument') do |p|
-  p.step do |_, arg|
-    arg.upcase
+  p.step do |_, arg:|
+    { arg: arg.upcase }
   end
 end
 ``` 
@@ -133,7 +138,7 @@ When the guard takes an argument the step argument is yielded.
 
  ```ruby
  pipeline.execute('initial argument') do |p|
-   p.step :service, service_class: MyServiceClass, if: -> (arg) { arg == 'initial argument' }
+   p.step :service, service_class: MyServiceClass, if: -> (arg:) { arg == 'initial argument' }
    p.step :service, service_class: MyOtherServiceClass, unless: -> { false }
  end
  
@@ -145,24 +150,24 @@ Apart from defining constructors and steps you can also define error callbacks.
 
 ```ruby
 NxtPipeline::Pipeline.new do |p|
-  p.step do |_, arg|
-    arg.upcase
+  p.step do |_, arg:|
+    { arg: arg.upcase }
   end
   
-  p.on_error MyCustomError do |step, arg, error|
+  p.on_error MyCustomError do |step, opts, error|
     # First matching error callback will be executed!
   end
   
-  p.on_errors ArgumentError, KeyError do |step, arg, error|
+  p.on_errors ArgumentError, KeyError do |step, opts, error|
     # First matching error callback will be executed!
   end
   
-  p.on_errors YetAnotherError, halt_on_error: false do |step, arg, error|
+  p.on_errors YetAnotherError, halt_on_error: false do |step, opts, error|
     # After executing the callback the pipeline will not halt but continue to
     # execute the next steps.
   end
   
-  p.on_errors do |step, arg, error|
+  p.on_errors do |step, opts, error|
     # This will match all errors inheriting from StandardError
   end
 end
@@ -174,12 +179,12 @@ You can also define callbacks that run before and after the `#execute` action. B
 
 ```ruby
 NxtPipeline::Pipeline.new do |p|
-  p.before_execute do |pipeline, arg|
+  p.before_execute do |pipeline, arg:|
     # Will be called from within #execute before entering the first step
     # After any configure block though!  
   end
   
-  p.after_execute do |pipeline, arg|
+  p.after_execute do |pipeline, arg:|
     # Will be called from within #execute after executing last step
   end
 end
@@ -187,6 +192,59 @@ 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. 
 
+### DSL
+
+The gem also comes with an easy DSL to make pipeline handling in your code more convenient. 
+Simply include NxtPipeline::Dsl in your class:
+
+```ruby
+class MyAwesomeClass
+  include NxtPipeline::Dsl
+  
+  # register a pipeline with a name and a block
+  pipeline :validation do |p|
+    pipeline.constructor(:validate) do |step, arg:|
+      result = step.validator.call(arg: arg)
+      result && { arg: result }
+    end
+    
+    pipeline.step :validate, validator: NameValidator
+    pipeline.step :validate, validator: AdressValidator
+    pipeline.step :validate, validator: BankAccountValidator
+    pipeline.step :validate, validator: PhoneNumberValidator
+    
+    p.on_error ValidationError do |step, opts, error|
+      # ...
+    end
+  end
+  
+  pipeline :execution do |p|
+    p.step do |_, arg:|
+      { arg: arg.upcase }
+    end
+      
+    p.on_error MyCustomError do |step, opts, error|
+      # nesting pipelines also works
+      pipeline(:error).execute(error)
+    end
+  end
+  
+  pipeline :error do |p|
+    p.step do |_, error|
+      error # do something here
+    end
+  end
+  
+  def call(arg)
+    # execute a pipeline simply by fetching it and calling execute on it as you would normally
+    pipeline(:execution).execute(arg: arg)
+  end
+end
+```
+
+## Topics
+- Step orchestration (chainable steps)
+- Constructors should take arg as first and step as second arg 
 
 ## Development
 

data/lib/nxt_pipeline/constructor.rb

@@ -0,0 +1,13 @@
+module NxtPipeline
+  class Constructor
+    def initialize(name, opts, block)
+      @name = name
+      @block = block
+      @opts = opts
+    end
+
+    attr_reader :opts, :block
+
+    delegate :call, :arity, to: :block
+  end
+end

data/lib/nxt_pipeline/dsl.rb

@@ -0,0 +1,44 @@
+module NxtPipeline
+  module Dsl
+    module ClassMethods
+      def pipeline(name = :default, &block)
+        name = name.to_sym
+
+        if block_given?
+          raise_already_registered_error(name) if pipeline_registry.key?(name)
+          pipeline_registry[name] = block
+        else
+          config = pipeline_registry.fetch(name) { raise KeyError, "No pipeline #{name} registered"}
+          NxtPipeline::Pipeline.new(&config)
+        end
+      end
+
+      def pipeline!(name, &block)
+        raise ArgumentError, "No block given!" unless block_given?
+        pipeline_registry[name] = block
+      end
+
+      private
+
+      def inherited(child)
+        child.instance_variable_set(:@pipeline_registry, pipeline_registry.clone)
+      end
+
+      def raise_already_registered_error(name)
+        raise KeyError, "Already registered a pipeline #{name}. Call pipeline! to overwrite already registered pipelines"
+      end
+
+      def pipeline_registry
+        @pipeline_registry ||= ActiveSupport::HashWithIndifferentAccess.new
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+
+      def pipeline(name = :default)
+        self.class.pipeline(name)
+      end
+    end
+  end
+end

data/lib/nxt_pipeline/pipeline.rb

@@ -1,7 +1,7 @@
 module NxtPipeline
   class Pipeline
-    def self.execute(opts, &block)
-      new(&block).execute(opts)
+    def self.execute(**opts, &block)
+      new(&block).execute(**opts)
     end
 
     def initialize(&block)
@@ -20,12 +20,11 @@ module NxtPipeline
 
     attr_accessor :logger, :steps
 
-    # register steps with name and block
     def constructor(name, **opts, &constructor)
       name = name.to_sym
       raise StandardError, "Already registered step :#{name}" if registry[name]
 
-      registry[name] = constructor
+      registry[name] = Constructor.new(name, opts, constructor)
 
       return unless opts.fetch(:default, false)
       set_default_constructor(name)
@@ -48,7 +47,7 @@ module NxtPipeline
         # fall back to :inline if no type is given
         type ||= :inline
         opts.reverse_merge!(to_s: type)
-        block
+        Constructor.new(type, opts, block)
       else
         if type
           raise_reserved_type_inline_error if type == :inline
@@ -64,19 +63,19 @@ module NxtPipeline
       steps << Step.new(type, constructor, steps.count, **opts)
     end
 
-    def execute(arg, &block)
+    def execute(**opts, &block)
       reset
 
       configure(&block) if block_given?
-      before_execute_callback.call(self, arg) if before_execute_callback.respond_to?(:call)
+      before_execute_callback.call(self, opts) if before_execute_callback.respond_to?(:call)
 
-      result = steps.inject(arg) do |argument, step|
-        execute_step(step, argument)
+      result = steps.inject(opts) do |options, step|
+        execute_step(step, **options)
       rescue StandardError => error
         callback = find_error_callback(error)
         raise unless callback && callback.continue_after_error?
         handle_step_error(error)
-        argument
+        options
       end
 
       after_execute_callback.call(self, result) if after_execute_callback.respond_to?(:call)
@@ -123,12 +122,12 @@ module NxtPipeline
       @default_constructor ||= registry[default_constructor_name.to_sym]
     end
 
-    def execute_step(step, arg)
+    def execute_step(step, **opts)
       self.current_step = step
-      self.current_arg = arg
-      result = step.execute(arg)
+      self.current_arg = opts
+      result = step.execute(**opts)
       log_step(step)
-      result || arg
+      result || opts
     end
 
     def find_error_callback(error)

data/lib/nxt_pipeline/step.rb

@@ -5,22 +5,27 @@ module NxtPipeline
 
       @type = type
       @index = index
-      @result = nil
       @opts = opts
-      @status = nil
       @constructor = constructor
+      @to_s = "#{opts.merge(type: type)}"
+
+      @status = nil
+      @result = nil
       @error = nil
     end
 
     attr_reader :type, :result, :status, :error, :opts, :index
+    attr_accessor :to_s
+
+    alias_method :name=, :to_s=
 
-    def execute(arg)
-      guard_args = [arg, self]
+    def execute(**opts)
+      guard_args = [opts, self]
       if_guard_args = guard_args.take(if_guard.arity)
       unless_guard_guard_args = guard_args.take(unless_guard.arity)
 
-      if unless_guard.call(*unless_guard_guard_args) && if_guard.call(*if_guard_args)
-        self.result = constructor.call(self, arg)
+      if !unless_guard.call(*unless_guard_guard_args) && if_guard.call(*if_guard_args)
+        self.result = constructor.call(self, **opts)
       end
 
       set_status
@@ -31,10 +36,6 @@ module NxtPipeline
       raise
     end
 
-    def to_s
-      "#{opts.merge(type: type)}"
-    end
-
     def type?(potential_type)
       type.to_sym == potential_type.to_sym
     end
@@ -45,15 +46,15 @@ module NxtPipeline
     attr_reader :constructor
 
     def if_guard
-      opts.fetch(:if) { no_guard }
+      opts.fetch(:if) { guard(true) }
     end
 
     def unless_guard
-      opts.fetch(:unless) { no_guard }
+      opts.fetch(:unless) { guard(false) }
     end
 
-    def no_guard
-      -> { true }
+    def guard(result)
+      -> { result }
     end
 
     def define_attr_readers(opts)

data/lib/nxt_pipeline/version.rb

@@ -1,3 +1,3 @@
 module NxtPipeline
-  VERSION = "0.2.8".freeze
+  VERSION = "0.3.0".freeze
 end

data/lib/nxt_pipeline.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nxt_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 platform: ruby
 authors:
 - Nils Sommer
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-09 00:00:00.000000000 Z
+date: 2019-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -120,6 +120,8 @@ files:
 - bin/rspec
 - bin/setup
 - lib/nxt_pipeline.rb
+- lib/nxt_pipeline/constructor.rb
+- lib/nxt_pipeline/dsl.rb
 - lib/nxt_pipeline/error_callback.rb
 - lib/nxt_pipeline/logger.rb
 - lib/nxt_pipeline/pipeline.rb