teckel 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df9c73577c9c93fbaaf2e7661a07bdc3b1b0397832a62a8edbe4eea846c4c029
-  data.tar.gz: 037041bf0eb6ae8bc41e354772d3ce1d04002a35ecccc0b1ecefa33a85845c3b
+  metadata.gz: c8dc1958f2645a6c57178a595b7d4364c9b2613e3c5adc532e0c8fd0cc8c2c22
+  data.tar.gz: cc0ef87983b17af9c16df5f4cc77a826a445fb7dc1f38db4de6cef7eef3b27c1
 SHA512:
-  metadata.gz: 2f6f601e816c972aed8e511b05fdbc418a48aab10c2ca246d108661cc25a8d514a41944b2e01b9294757a2a717696491f20f601f5f60e53faa45651aec48bc7f
-  data.tar.gz: 68bc46e5ed21cf5e639ee1fc00265b278f9062f42de9d179a07559862990a078df9dcb2ef26956eb629cf08e71409b9b05bd363a11930cb64ecdee533d63d2ea
+  metadata.gz: 9b9e5dde43b07ec1ae8fb6a1964990cdbdac430bd2c3ba4e73fd137fbeac3f1e4a3faf10e05098da00414a8ed17b6b8ce4316593ea1160bf976aeb2bc550ab6d
+  data.tar.gz: 5fd5bd9a76fcf3ad4794de79e94eaba128dc6cbcac1a12e92eafa0aef36d5b18496d8d509738706f23fe555e6d482c21e20cd0384c756e4b02952d4ce52bf770

data/CHANGELOG.md

@@ -1,24 +1,58 @@
 # Changes
 
+## 0.9.0
+
+- Internal housekeeping
+  - Add ruby 3.4 and 'head' to CI
+  - Ruby < 3 won't run mutation test
+  - moved to standard.rb for linting and formatting
+  - removed usage of `forwardable` in favor of explicit delegation methods
+  - renamed internal `Teckel::Config.for` to `get_or_set`
+  - renamed internal `Teckel::Operation::Config.get_set_constructor` to `get_or_set_constructor`
+  - fixed specs that test backtrace outputs on ruby 3.4
+- Documentation now uses modern (Ruby 3.4) output syntax. (`{foo: 1}` is now printed as is, instead of `{:foo => 1}`
+
+## 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!` 
+  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).
+  - 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
@@ -48,6 +82,7 @@
   ```
 
 Internal:
+
 - Move operation and chain config dsl methods into own module [GH-15]
 - Code simplifications [GH-16]
 
@@ -57,6 +92,7 @@ Internal:
 - `#finalize!` no longer freezes the entire Operation or Chain class, only it's settings. [GH-13]
 - Add simple support for using Base classes. [GH-10]
   Removes global configuration `Teckel::Config.default_constructor`
+
   ```ruby
   class ApplicationOperation
     include Teckel::Operation
@@ -74,17 +110,21 @@ Internal:
     # you cannot call `finalize!` on partially declared Operations
   end
   ```
+
 - Add support for setting your own Result objects. [GH-9]
   - They should include and implement `Teckel::Result` which is needed by `Chain`.
   - `Chain::StepFailure` got replaced with `Chain::Result`.
   - the `Teckel::Operation::Results` module was removed. To let Operation use the default Result object, use the new helper `result!` instead.
 - Add "settings"/dependency injection to Operation and Chains. [GH-7]
+
   ```ruby
   MyOperation.with(logger: STDOUT).call(params)
 
   MyChain.with(some_step: { logger: STDOUT }).call(params)
   ```
+
 - [GH-5] Add support for ruby 2.7 pattern matching on Operation and Chain results. Both, array and hash notations are supported:
+
   ```ruby
   case MyOperation.call(params)
   in [false, value]
@@ -102,19 +142,20 @@ Internal:
     # handle success
   end
   ```
+
 - Fix setting a config twice to raise an error
 
 ## 0.3.0
 
 - `finalize!`'ing a Chain will also finalize all it's Operations
 - Changed attribute naming of `StepFailure`:
-    + `.operation` will now give the operation class of the step - was `.step` before
-    + `.step` will now give the name of the step (which Operation failed) - was `.step_name` before
+  - `.operation` will now give the operation class of the step - was `.step` before
+  - `.step` will now give the name of the step (which Operation failed) - was `.step_name` before
 
 ## 0.2.0
 
 - Around Hooks for Chains
-- `finalize!` 
+- `finalize!`
   - freezing Chains and Operations, to prevent further changes
   - Operations check their config and raise if any is missing
 

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

@@ -17,7 +17,7 @@ module Teckel
       #
       # @return [<Step>]
       def steps
-        @config.for(:steps) { [] }
+        @config.get_or_set(:steps) { [] }
       end
 
       # Set or get the optional around hook.
@@ -26,9 +26,9 @@ module Teckel
       # 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)
+      # @param callable [Proc,#call] The hook to pass chain execution control to. (nil)
       #
-      # @return [Proc,{#call}] The configured hook
+      # @return [Proc,#call] The configured hook
       #
       # @example Around hook with block
       #   OUTPUTS = []
@@ -62,7 +62,7 @@ module Teckel
       #   OUTPUTS #=> ["before start", "after start"]
       #   result.success #=> { some: "test" }
       def around(callable = nil, &block)
-        @config.for(:around, callable || block)
+        @config.get_or_set(:around, callable || block)
       end
 
       # @!attribute [r] runner()
@@ -73,7 +73,7 @@ module Teckel
       # @param klass [Class] A class like the {Runner}
       # @!visibility protected
       def runner(klass = nil)
-        @config.for(:runner, klass) { Runner }
+        @config.get_or_set(:runner, klass) { Runner }
       end
 
       # @overload result()
@@ -85,7 +85,7 @@ module Teckel
       #   @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 }
+        @config.get_or_set(:result, klass) { const_defined?(:Result, false) ? self::Result : Teckel::Chain::Result }
       end
 
       # @overload result_constructor()
@@ -143,17 +143,17 @@ module Teckel
       def result_constructor(sym_or_proc = nil)
         constructor = build_constructor(result, sym_or_proc) unless sym_or_proc.nil?
 
-        @config.for(:result_constructor, constructor) {
+        @config.get_or_set(: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
+      # 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
+      # @param settings [Hash{(String,Symbol) => Object}] Set settings for a step by it's name
       #
       # @example
       #   class MyOperation
@@ -188,15 +188,18 @@ module Teckel
       #   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)
+        @config.get_or_set(:default_settings, settings)
       end
 
       # Getter for configured default settings
-      # @return [nil|#call] The callable constructor
+      # @return [NilClass]
+      # @return [#call] The callable constructor
       def default_settings
-        @config.for(:default_settings)
+        @config.get_or_set(:default_settings)
       end
 
+      # @!visibility private
+      # @return [Array<Symbol>]
       REQUIRED_CONFIGS = %i[around runner result result_constructor].freeze
 
       # @!visibility private
@@ -227,7 +230,7 @@ module Teckel
       # @return [self]
       # @!visibility public
       def dup
-        dup_config(super)
+        dup_config(super()) # standard:disable Style/SuperArguments
       end
 
       # Produces a clone of this chain.
@@ -237,15 +240,25 @@ module Teckel
       # @!visibility public
       def clone
         if frozen?
-          super
+          super() # standard:disable Style/SuperArguments
         else
-          dup_config(super)
+          dup_config(super()) # standard:disable Style/SuperArguments
         end
       end
 
+      # Prevents further modifications to this chain and its config
+      #
+      # @return [self]
+      # @!visibility public
+      def freeze
+        steps.freeze
+        @config.freeze
+        super() # standard:disable Style/SuperArguments
+      end
+
       # @!visibility private
       def inherited(subclass)
-        super dup_config(subclass)
+        super(dup_config(subclass))
       end
 
       # @!visibility private
@@ -253,9 +266,7 @@ module Teckel
         base.instance_variable_set(:@config, Teckel::Config.new)
       end
 
-      private
-
-      def dup_config(other_class)
+      private def dup_config(other_class)
         new_config = @config.dup
         new_config.replace(:steps) { steps.dup }
 
@@ -263,11 +274,12 @@ module Teckel
         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)
+      private 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

data/lib/teckel/chain/result.rb

@@ -1,12 +1,8 @@
 # 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]
@@ -16,13 +12,13 @@ module Teckel
       end
 
       class << self
-        alias :[] :new
+        alias_method :[], :new
       end
 
-      # @!method step
-      #   Delegates to +step.name+
-      #   @return [String,Symbol] The step name of the failed operation.
-      def_delegator :@step, :name, :step
+      # @return [String,Symbol] The step name of the failed operation.
+      def step
+        @step.name
+      end
 
       def deconstruct
         [successful?, @step.name, value]

data/lib/teckel/chain/runner.rb

@@ -7,9 +7,13 @@ module Teckel
     # @!visibility protected
     class Runner
       # @!visibility private
-      UNDEFINED = Object.new
+      # @return [Object]
+      UNDEFINED = Teckel::UNDEFINED
 
       # @!visibility private
+      # @attr [Object] value the return value / result of the step execution
+      # @attr [Boolean] success whether the step has been executed successfully
+      # @attr [Teckel::Chain::Step] the step instance
       StepResult = Struct.new(:value, :success, :step)
 
       def initialize(chain, settings = UNDEFINED)
@@ -29,12 +33,10 @@ module Teckel
       end
 
       def steps
-        settings == UNDEFINED ? chain.steps : steps_with_settings
+        settings.eql?(UNDEFINED) ? chain.steps : steps_with_settings
       end
 
-      private
-
-      def run(input)
+      private def run(input)
         steps.each_with_object(StepResult.new(input)) do |step, step_result|
           result = step.operation.call(step_result.value)
 
@@ -46,11 +48,11 @@ module Teckel
         end
       end
 
-      def step_with_settings(step)
+      private def step_with_settings(step)
         settings.key?(step.name) ? step.with(settings[step.name]) : step
       end
 
-      def steps_with_settings
+      private def steps_with_settings
         Enumerator.new do |yielder|
           chain.steps.each do |step|
             yielder << step_with_settings(step)

data/lib/teckel/chain.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require_relative 'chain/config'
-require_relative 'chain/step'
-require_relative 'chain/result'
-require_relative 'chain/runner'
+require_relative "chain/config"
+require_relative "chain/step"
+require_relative "chain/result"
+require_relative "chain/runner"
 
 module Teckel
   # Railway style execution of multiple Operations.
@@ -45,13 +45,13 @@ module Teckel
       # @return [Teckel::Chain::Result] The result object wrapping
       #   the result value, the success state and last executed step.
       def call(input = nil)
-        default_settings = self.default_settings
+        default_settings = default_settings()
 
         runner =
           if default_settings
-            self.runner.new(self, default_settings)
+            runner().new(self, default_settings)
           else
-            self.runner.new(self)
+            runner().new(self)
           end
 
         if around
@@ -61,21 +61,27 @@ module Teckel
         end
       end
 
-      # @param settings [Hash{String,Symbol => Object}] Set settings for a step by it's name
+      # Provide settings to the configured steps.
+      #
+      # @param settings [Hash{(String,Symbol) => Object}] Set settings for a step by it's name
+      # @return [#call] A callable, either a {Teckel::Chain::Runner} or,
+      #   when configured with an around hook, a +Proc+
       def with(settings)
-        runner = self.runner.new(self, settings)
+        runner = runner().new(self, settings)
         if around
-          ->(input) { around.call(runner, input) }
+          around.curry[runner]
         else
           runner
         end
       end
-      alias :set :with
+      alias_method :set, :with
     end
 
     def self.included(receiver)
-      receiver.extend Config
-      receiver.extend ClassMethods
+      receiver.class_eval do
+        extend Config
+        extend ClassMethods
+      end
     end
   end
 end

data/lib/teckel/config.rb

@@ -15,11 +15,16 @@ module Teckel
     #   - sets (and returns) the blocks return value otherwise
     # - calling without +value+ and +block+ works like {Hash#[]}
     #
+    # @param key [Symbol,String] Name of the configuration
+    # @param value [Object] Value of the configuration
+    # @yield [key] If using in fetch mode and no value has been set
+    # @yieldparam key [Symbol,String] Name of the configuration
+    # @return [Object]
     # @raise [FrozenConfigError] When overwriting a key
     # @!visibility private
-    def for(key, value = nil, &block)
+    def get_or_set(key, value = nil, &block)
       if value.nil?
-        get_or_set(key, &block)
+        _get_or_set(key, &block)
       elsif @config.key?(key)
         raise FrozenConfigError, "Configuration #{key} is already set"
       else
@@ -28,6 +33,9 @@ module Teckel
     end
 
     # @!visibility private
+    # @param key [Symbol,String] Name of the configuration
+    # @yieldreturn [Object] The new setting
+    # @return [Object,nil] The new setting or +nil+ if not replaced
     def replace(key)
       @config[key] = yield if @config.key?(key)
     end
@@ -35,19 +43,17 @@ module Teckel
     # @!visibility private
     def freeze
       @config.freeze
-      super
+      super() # standard:disable Style/SuperArguments
     end
 
     # @!visibility private
     def dup
-      super.tap do |copy|
-        copy.instance_variable_set(:@config, @config.dup)
-      end
+      copy = super() # standard:disable Style/SuperArguments
+      copy.instance_variable_set(:@config, @config.dup)
+      copy
     end
 
-    private
-
-    def get_or_set(key, &block)
+    private def _get_or_set(key, &block)
       if block
         @config[key] ||= @config.fetch(key, &block)
       else

data/lib/teckel/contracts.rb

@@ -5,14 +5,14 @@ module Teckel
     # Simple contract for enforcing data to be not set or +nil+
     module None
       class << self
-        # Always return nil
-        # @return nil
+        # Always return +nil+
+        # @return [NilClass]
         # @raise [ArgumentError] when called with any non-nil arguments
         def [](*args)
           raise ArgumentError, "None called with arguments" if args.any?(&:itself)
         end
 
-        alias :new :[]
+        alias_method :new, :[]
       end
     end
   end