teckel 0.2.0 → 0.7.0

data/lib/teckel/chain/config.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Teckel
+  module Chain
+    module Config
+      # Declare a {Operation} as a named step
+      #
+      # @param name [String,Symbol] The name of the operation.
+      #   This name is used in an error case to let you know which step failed.
+      # @param operation [Operation] The operation to call, which
+      #   must return a {Teckel::Result} object.
+      def step(name, operation)
+        steps << Step.new(name, operation)
+      end
+
+      # Get the list of defined steps
+      #
+      # @return [<Step>]
+      def steps
+        @config.for(:steps) { [] }
+      end
+
+      # Set or get the optional around hook.
+      # A Hook might be given as a block or anything callable. The execution of
+      # the chain is yielded to this hook. The first argument being the callable
+      # chain ({Runner}) and the second argument the +input+ data. The hook also
+      # needs to return the result.
+      #
+      # @param callable [Proc,{#call}] The hook to pass chain execution control to. (nil)
+      #
+      # @return [Proc,{#call}] The configured hook
+      #
+      # @example Around hook with block
+      #   OUTPUTS = []
+      #
+      #   class Echo
+      #     include ::Teckel::Operation
+      #     result!
+      #
+      #     input Hash
+      #     output input
+      #
+      #     def call(hsh)
+      #       success!(hsh)
+      #     end
+      #   end
+      #
+      #   class MyChain
+      #     include Teckel::Chain
+      #
+      #     around do |chain, input|
+      #       OUTPUTS << "before start"
+      #       result = chain.call(input)
+      #       OUTPUTS << "after start"
+      #       result
+      #     end
+      #
+      #     step :noop, Echo
+      #   end
+      #
+      #   result = MyChain.call(some: 'test')
+      #   OUTPUTS #=> ["before start", "after start"]
+      #   result.success #=> { some: "test" }
+      def around(callable = nil, &block)
+        @config.for(:around, callable || block)
+      end
+
+      # @!attribute [r] runner()
+      # @return [Class] The Runner class
+      # @!visibility protected
+
+      # Overwrite the default runner
+      # @param klass [Class] A class like the {Runner}
+      # @!visibility protected
+      def runner(klass = nil)
+        @config.for(:runner, klass) { Runner }
+      end
+
+      # @overload result()
+      #   Get the configured result object class wrapping {.error} or {.output}.
+      #   @return [Class] The +result+ class, or {Teckel::Chain::Result} as default
+      #
+      # @overload result(klass)
+      #   Set the result object class wrapping {.error} or {.output}.
+      #   @param klass [Class] The +result+ class
+      #   @return [Class] The +result+ class configured
+      def result(klass = nil)
+        @config.for(:result, klass) { const_defined?(:Result, false) ? self::Result : Teckel::Chain::Result }
+      end
+
+      # @overload result_constructor()
+      #   The callable constructor to build an instance of the +result+ class.
+      #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
+      #   @return [Proc] A callable that will return an instance of +result+ class.
+      #
+      # @overload result_constructor(sym_or_proc)
+      #  Define how to build the +result+.
+      #  @param  sym_or_proc [Symbol, #call]
+      #    - Either a +Symbol+ representing the _public_ method to call on the +result+ class.
+      #    - Or anything that response to +#call+ (like a +Proc+).
+      #  @return [#call] The callable constructor
+      #
+      #  @example
+      #    class MyOperation
+      #      include Teckel::Operation
+      #      result!
+      #
+      #      settings Struct.new(:say, :other)
+      #      settings_constructor ->(data) { settings.new(*data.values_at(*settings.members)) }
+      #
+      #      input none
+      #      output Hash
+      #      error none
+      #
+      #      def call(_)
+      #        success!(settings.to_h)
+      #      end
+      #    end
+      #
+      #    class Chain
+      #      include Teckel::Chain
+      #
+      #      class Result < Teckel::Operation::Result
+      #        def initialize(value, success, step, opts = {})
+      #          super(value, success)
+      #          @step = step
+      #          @opts = opts
+      #        end
+      #
+      #        class << self
+      #          alias :[] :new # Alias the default constructor to :new
+      #        end
+      #
+      #        attr_reader :opts, :step
+      #      end
+      #
+      #      result_constructor ->(value, success, step) {
+      #        result.new(value, success, step, time: Time.now.to_i)
+      #      }
+      #
+      #      step :a, MyOperation
+      #    end
+      def result_constructor(sym_or_proc = nil)
+        constructor = build_constructor(result, sym_or_proc) unless sym_or_proc.nil?
+
+        @config.for(:result_constructor, constructor) {
+          build_constructor(result, Teckel::DEFAULT_CONSTRUCTOR)
+        } || raise(MissingConfigError, "Missing result_constructor config for #{self}")
+      end
+
+      # Declare default settings operation iin this chain should use when called without
+      # {Teckel::Chain::ClassMethods#with #with}.
+      #
+      # Explicit call-time settings will *not* get merged with declared default setting.
+      #
+      # @param settings [Hash{String,Symbol => Object}] Set settings for a step by it's name
+      #
+      # @example
+      #   class MyOperation
+      #     include Teckel::Operation
+      #     result!
+      #
+      #     settings Struct.new(:say, :other)
+      #     settings_constructor ->(data) { settings.new(*data.values_at(*settings.members)) }
+      #
+      #     input none
+      #     output Hash
+      #     error none
+      #
+      #     def call(_)
+      #       success!(settings.to_h)
+      #     end
+      #   end
+      #
+      #   class Chain
+      #     include Teckel::Chain
+      #
+      #     default_settings!(a: { say: "Chain Default" })
+      #
+      #     step :a, MyOperation
+      #   end
+      #
+      #   # Using the chains default settings
+      #   result = Chain.call
+      #   result.success #=> {say: "Chain Default", other: nil}
+      #
+      #   # explicit settings passed via `with` will overwrite all defaults
+      #   result = Chain.with(a: { other: "What" }).call
+      #   result.success #=> {say: nil, other: "What"}
+      def default_settings!(settings) # :nodoc: The bang is for consistency with the Operation class
+        @config.for(:default_settings, settings)
+      end
+
+      # Getter for configured default settings
+      # @return [nil|#call] The callable constructor
+      def default_settings
+        @config.for(:default_settings)
+      end
+
+      REQUIRED_CONFIGS = %i[around runner result result_constructor].freeze
+
+      # @!visibility private
+      # @return [void]
+      def define!
+        raise MissingConfigError, "Cannot define Chain with no steps" if steps.empty?
+
+        REQUIRED_CONFIGS.each { |e| public_send(e) }
+        steps.each(&:finalize!)
+        nil
+      end
+
+      # Disallow any further changes to this Chain.
+      # @note This also calls +finalize!+ on all Operations defined as steps.
+      #
+      # @return [self] Frozen self
+      # @!visibility public
+      def finalize!
+        define!
+        steps.freeze
+        @config.freeze
+        self
+      end
+
+      # Produces a shallow copy of this chain.
+      # It's {around}, {runner} and {steps} will get +dup+'ed
+      #
+      # @return [self]
+      # @!visibility public
+      def dup
+        dup_config(super)
+      end
+
+      # Produces a clone of this chain.
+      # It's {around}, {runner} and {steps} will get +dup+'ed
+      #
+      # @return [self]
+      # @!visibility public
+      def clone
+        if frozen?
+          super
+        else
+          dup_config(super)
+        end
+      end
+
+      # @!visibility private
+      def inherited(subclass)
+        super dup_config(subclass)
+      end
+
+      # @!visibility private
+      def self.extended(base)
+        base.instance_variable_set(:@config, Teckel::Config.new)
+      end
+
+      private
+
+      def dup_config(other_class)
+        new_config = @config.dup
+        new_config.replace(:steps) { steps.dup }
+
+        other_class.instance_variable_set(:@config, new_config)
+        other_class
+      end
+
+      def build_constructor(on, sym_or_proc)
+        if sym_or_proc.is_a?(Symbol) && on.respond_to?(sym_or_proc)
+          on.public_method(sym_or_proc)
+        elsif sym_or_proc.respond_to?(:call)
+          sym_or_proc
+        end
+      end
+    end
+  end
+end

data/lib/teckel/chain/result.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Teckel
+  module Chain
+    class Result < Teckel::Operation::Result
+      extend Forwardable
+
+      # @param value [Object] The result value
+      # @param success [Boolean] whether this is a successful result
+      # @param step [Teckel::Chain::Step]
+      def initialize(value, success, step)
+        super(value, success)
+        @step = step
+      end
+
+      class << self
+        alias :[] :new
+      end
+
+      # @!method step
+      #   Delegates to +step.name+
+      #   @return [String,Symbol] The step name of the failed operation.
+      def_delegator :@step, :name, :step
+
+      def deconstruct
+        [successful?, @step.name, value]
+      end
+
+      def deconstruct_keys(keys)
+        e = super
+        e[:step] = @step.name if keys.include?(:step)
+        e
+      end
+    end
+  end
+end

data/lib/teckel/chain/runner.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Teckel
+  module Chain
+    # The default implementation for executing a {Chain}
+    #
+    # @!visibility protected
+    class Runner
+      # @!visibility private
+      UNDEFINED = Object.new
+
+      # @!visibility private
+      StepResult = Struct.new(:value, :success, :step)
+
+      def initialize(chain, settings = UNDEFINED)
+        @chain, @settings = chain, settings
+      end
+      attr_reader :chain, :settings
+
+      # Run steps
+      #
+      # @param input Any form of input the first steps +input+ class can handle
+      #
+      # @return [Teckel::Chain::Result] The result object wrapping
+      #   either the success or failure value.
+      def call(input = nil)
+        step_result = run(input)
+        chain.result_constructor.call(*step_result)
+      end
+
+      def steps
+        settings == UNDEFINED ? chain.steps : steps_with_settings
+      end
+
+      private
+
+      def run(input)
+        steps.each_with_object(StepResult.new(input)) do |step, step_result|
+          result = step.operation.call(step_result.value)
+
+          step_result.step = step
+          step_result.value = result.value
+          step_result.success = result.successful?
+
+          break step_result if result.failure?
+        end
+      end
+
+      def step_with_settings(step)
+        settings.key?(step.name) ? step.with(settings[step.name]) : step
+      end
+
+      def steps_with_settings
+        Enumerator.new do |yielder|
+          chain.steps.each do |step|
+            yielder << step_with_settings(step)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/teckel/chain/step.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Teckel
+  module Chain
+    # Internal wrapper of a step definition
+    Step = Struct.new(:name, :operation) do
+      def finalize!
+        name.freeze
+        operation.finalize!
+        freeze
+      end
+
+      def with(settings)
+        self.class.new(name, operation.with(settings))
+      end
+    end
+  end
+end

data/lib/teckel/config.rb

@@ -2,42 +2,24 @@
 
 module Teckel
   class Config
-    @default_constructor = :[]
-    class << self
-      # @!attribute [r] default_constructor()
-      # The default constructor method for +input+, +output+ and +error+ class (default: +:[]+)
-      # @return [Class] The Output class
-
-      # @!method default_constructor(sym_or_proc)
-      # Set the default constructor method for +input+, +output+ and +error+ class
-      #
-      # defaults to +:[]+
-      #
-      # @param sym_or_proc [Symbol,#call] The method name on the +input+,
-      #   +output+ and +error+ class or a callable which accepts the
-      #   +input+, +output+ or +error+
-      #
-      # @return [Symbol,#call]
-      def default_constructor(sym_or_proc = nil)
-        return @default_constructor if sym_or_proc.nil?
-
-        @default_constructor = sym_or_proc
-      end
-    end
-
     # @!visibility private
     def initialize
       @config = {}
     end
 
+    # Allow getting or setting a value, with some weird rules:
+    # - The +value+ might not be +nil+
+    # - Setting via +value+ is allowed only once. Successive calls will raise a {FrozenConfigError}
+    # - Setting via +block+ works almost like {Hash#fetch}:
+    #   - returns the existing value if key is present
+    #   - sets (and returns) the blocks return value otherwise
+    # - calling without +value+ and +block+ works like {Hash#[]}
+    #
+    # @raise [FrozenConfigError] When overwriting a key
     # @!visibility private
     def for(key, value = nil, &block)
       if value.nil?
-        if block
-          @config[key] ||= @config.fetch(key, &block)
-        else
-          @config[key]
-        end
+        get_or_set(key, &block)
       elsif @config.key?(key)
         raise FrozenConfigError, "Configuration #{key} is already set"
       else
@@ -45,6 +27,11 @@ module Teckel
       end
     end
 
+    # @!visibility private
+    def replace(key)
+      @config[key] = yield if @config.key?(key)
+    end
+
     # @!visibility private
     def freeze
       @config.freeze
@@ -57,5 +44,15 @@ module Teckel
         copy.instance_variable_set(:@config, @config.dup)
       end
     end
+
+    private
+
+    def get_or_set(key, &block)
+      if block
+        @config[key] ||= @config.fetch(key, &block)
+      else
+        @config[key]
+      end
+    end
   end
 end