teckel 0.4.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18179b7fd315a11bc51f0ac4cfbdba4c0e74ad82a6a7dc186289433906ec2783
-  data.tar.gz: 02eb5f5c59ac9983a92b457f9253a38f9188e3f2b17d4f30029aa545b3151181
+  metadata.gz: 213ed6f9b3d25db8b7fc284ced55aa1a3a71b4ec54f10fd3ed3bf4e0a315dbd3
+  data.tar.gz: d013f110763117b066987bfb6c085e8682db372856ea7ab27f4803858be96e3c
 SHA512:
-  metadata.gz: cbbbebfecccf6806da642dbc1dce843946c7dcaa27abb7c38467b0512ff5cb32d13b848fae0eaa0f8c4641f26e5b1f03f58f82fb70b3aa8aa1a891356698ff16
-  data.tar.gz: b312534680f31d7cff2a13326f3dc3cc01566110d3001b285d233c97548edbfb2fe008d59821ef0723b63687f12e95cca3f06f2f7c1a3f8d0e15d90caca4733d
+  metadata.gz: 82db9106f0da688411be738866692455653eb59298afa01ba24500975b0498bf9a164f9f59e2741a4ed9c0c252174bd86fa71dd4204338fe04424d961c21621b
+  data.tar.gz: 6c693373c212e3b127dde042fdaba1ab7865d813cba17d0624a73a62e62589fc68bfe86ed93b9e7c32295deb6053411e4ea0cf57f0897b6f8e7e339ce60dd7be

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changes
 
+## 0.8.0
+
+- Add mutation testing (currently about 80% covered)
+- Breaking: `Teckel::Operation::Result` no longer converts the `successful` value to a boolean.
+  When using the default result implementation, nothing changes for you.
+  When you manually pass anything else into it, `succesful?` will return this value. The `failure` and `success` methods
+  work on the "Truthy" value of `successful`
+  ```ruby
+  result = Result.new(some_value, 42)
+  result.successful?
+  # => 42
+  ```
+- Change: `freeze`ing an `Operation` or `Chain` will also freeze their internal config (input, output, steps, etc.)
+
+Internal:
+
+- Some refactoring to cover mutations
+- Extracted creating the runable `Operation` instance into a new, public `runable(settings = UNDEFINED)` method.
+  Mainly to reduce code duplication but this also makes testing, stubbing and mocking easier.
+
+## 0.7.0
+
+- Breaking: `Teckel::Chain` will not be required by default. require manually if needed `require "teckel/chain"` [GH-24]
+- Breaking: Internally, `Teckel::Operation::Runner` instead of `:success` and `:failure` now only uses `:halt` as it's throw-catch symbol. [GH-26]
+- Add: Using the default `Teckel::Operation::Runner`, `input_constructor` and `result_constructor` will be executed
+  within the context of the operation instance. This allows for `input_constructor` to call `fail!` and `success!` 
+  without ever `call`ing the operation. [GH-26]
+
+
+## 0.6.0
+
+- Breaking: Operations return values will be ignored. [GH-21]
+  * You'll need to use `success!` or `failure!` 
+  * `success!` and `failure!` are now implemented on the `Runner`, which makes it easier to change their behavior (including the one above).
+
+## 0.5.0
+
+- Fix: calling chain with settings and no input [GH-14]
+- Add: Default settings for Operation and Chains [GH-17], [GH-18]
+  ```ruby
+  class MyOperation
+    include Teckel::Operation
+
+    settings Struct.new(:logger) 
+
+    # If your settings class can cope with no input and you want to make sure
+    # `settings` gets initialized and set.
+    # settings will be #<struct logger=nil>
+    default_settings!
+
+    # settings will be #<struct logger=MyGlobalLogger>
+    default_settings!(MyGlobalLogger)
+
+    # settings will be #<struct logger=#<Logger:<...>>
+    default_settings! -> { settings.new(Logger.new("/tmp/my.log")) }
+  end
+
+  class Chain
+    include Teckel::Chain
+
+    # set or overwrite operation settings
+    default_settings!(a: MyOtherLogger)
+
+    step :a, MyOperation
+  end
+  ```
+
+Internal:
+- Move operation and chain config dsl methods into own module [GH-15]
+- Code simplifications [GH-16]
+
 ## 0.4.0
 
 - Moving verbose examples from API docs into github pages

data/README.md

@@ -3,10 +3,10 @@
 Ruby service classes with enforced<sup name="footnote-1-source">[1](#footnote-1)</sup> input, output and error data structure definition.
 
 [![Gem Version](https://img.shields.io/gem/v/teckel.svg)][gem]
-[![Build Status](https://github.com/dry-rb/dry-configurable/workflows/ci/badge.svg)][ci]
+[![Build Status](https://github.com/fnordfish/teckel/actions/workflows/specs.yml/badge.svg)][ci]
 [![Maintainability](https://api.codeclimate.com/v1/badges/b3939aaec6271a567a57/maintainability)](https://codeclimate.com/github/fnordfish/teckel/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/b3939aaec6271a567a57/test_coverage)](https://codeclimate.com/github/fnordfish/teckel/test_coverage)
-[![API Documentation Coverage](https://inch-ci.org/github/fnordfish/teckel.svg?branch=master)][inch]
+[![API Documentation Coverage](https://inch-ci.org/github/fnordfish/teckel.svg?branch=main)][inch]
 
 ## Installation
 
@@ -95,5 +95,5 @@ Please also see [DEVELOPMENT.md](DEVELOPMENT.md) for planned features and genera
 - <a name="footnote-1">1</a>: Obviously, it's still Ruby and you can cheat. Don’t! [↩](#footnote-1-source)
 
 [gem]: https://rubygems.org/gems/teckel
-[ci]: https://github.com/fnordfish/teckel/actions?query=workflow%3ACI
+[ci]: https://github.com/fnordfish/teckel/actions/workflows/specs.yml
 [inch]: http://inch-ci.org/github/fnordfish/teckel

data/lib/teckel/chain/config.rb

@@ -0,0 +1,286 @@
+# 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 in 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
+
+      # Prevents further modifications to this chain and its config
+      #
+      # @return [self]
+      # @!visibility public
+      def freeze
+        steps.freeze
+        @config.freeze
+        super()
+      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)
+        case sym_or_proc
+        when Proc
+          sym_or_proc
+        when Symbol
+          on.public_method(sym_or_proc) if on.respond_to?(sym_or_proc)
+        end
+      end
+    end
+  end
+end

data/lib/teckel/chain/result.rb

@@ -29,9 +29,9 @@ module Teckel
       end
 
       def deconstruct_keys(keys)
-        super.tap { |e|
-          e[:step] = @step.name if keys.include?(:step)
-        }
+        e = super
+        e[:step] = @step.name if keys.include?(:step)
+        e
       end
     end
   end

data/lib/teckel/chain/runner.rb

@@ -9,6 +9,9 @@ module Teckel
       # @!visibility private
       UNDEFINED = Object.new
 
+      # @!visibility private
+      StepResult = Struct.new(:value, :success, :step)
+
       def initialize(chain, settings = UNDEFINED)
         @chain, @settings = chain, settings
       end
@@ -20,29 +23,37 @@ module Teckel
       #
       # @return [Teckel::Chain::Result] The result object wrapping
       #   either the success or failure value.
-      def call(input)
-        last_result = nil
-        last_step = nil
-        steps.each do |step|
-          last_step = step
-          value     = last_result ? last_result.value : input
+      def call(input = nil)
+        step_result = run(input)
+        chain.result_constructor.call(*step_result)
+      end
+
+      def steps
+        settings.eql?(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)
 
-          last_result = step.operation.call(value)
+          step_result.step = step
+          step_result.value = result.value
+          step_result.success = result.successful?
 
-          break if last_result.failure?
+          break step_result if result.failure?
         end
+      end
 
-        chain.result_constructor.call(last_result.value, last_result.successful?, last_step)
+      def step_with_settings(step)
+        settings.key?(step.name) ? step.with(settings[step.name]) : step
       end
 
-      def steps
-        if settings == UNDEFINED
-          chain.steps
-        else
-          Enumerator.new do |yielder|
-            chain.steps.each do |step|
-              yielder << (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