teckel 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213ed6f9b3d25db8b7fc284ced55aa1a3a71b4ec54f10fd3ed3bf4e0a315dbd3
-  data.tar.gz: d013f110763117b066987bfb6c085e8682db372856ea7ab27f4803858be96e3c
+  metadata.gz: c8dc1958f2645a6c57178a595b7d4364c9b2613e3c5adc532e0c8fd0cc8c2c22
+  data.tar.gz: cc0ef87983b17af9c16df5f4cc77a826a445fb7dc1f38db4de6cef7eef3b27c1
 SHA512:
-  metadata.gz: 82db9106f0da688411be738866692455653eb59298afa01ba24500975b0498bf9a164f9f59e2741a4ed9c0c252174bd86fa71dd4204338fe04424d961c21621b
-  data.tar.gz: 6c693373c212e3b127dde042fdaba1ab7865d813cba17d0624a73a62e62589fc68bfe86ed93b9e7c32295deb6053411e4ea0cf57f0897b6f8e7e339ce60dd7be
+  metadata.gz: 9b9e5dde43b07ec1ae8fb6a1964990cdbdac430bd2c3ba4e73fd137fbeac3f1e4a3faf10e05098da00414a8ed17b6b8ce4316593ea1160bf976aeb2bc550ab6d
+  data.tar.gz: 5fd5bd9a76fcf3ad4794de79e94eaba128dc6cbcac1a12e92eafa0aef36d5b18496d8d509738706f23fe555e6d482c21e20cd0384c756e4b02952d4ce52bf770

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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)
@@ -7,11 +19,13 @@
   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:
@@ -25,20 +39,20 @@ Internal:
 - 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
@@ -68,6 +82,7 @@ Internal:
   ```
 
 Internal:
+
 - Move operation and chain config dsl methods into own module [GH-15]
 - Code simplifications [GH-16]
 
@@ -77,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
@@ -94,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]
@@ -122,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/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,7 +143,7 @@ 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
@@ -153,7 +153,7 @@ module Teckel
       #
       # 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,9 +240,9 @@ 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
 
@@ -250,7 +253,7 @@ module Teckel
       def freeze
         steps.freeze
         @config.freeze
-        super()
+        super() # standard:disable Style/SuperArguments
       end
 
       # @!visibility private
@@ -263,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 }
 
@@ -273,7 +274,7 @@ module Teckel
         other_class
       end
 
-      def build_constructor(on, sym_or_proc)
+      private def build_constructor(on, sym_or_proc)
         case sym_or_proc
         when Proc
           sym_or_proc

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)
@@ -32,9 +36,7 @@ module Teckel
         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,16 +61,20 @@ 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)

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

data/lib/teckel/operation/config.rb

@@ -11,7 +11,7 @@ module Teckel
       #   @param  klass [Class] The +input+ class
       #   @return [Class] The +input+ class
       def input(klass = nil)
-        @config.for(:input, klass) { self::Input if const_defined?(:Input) } ||
+        @config.get_or_set(:input, klass) { self::Input if const_defined?(:Input) } ||
           raise(MissingConfigError, "Missing input config for #{self}")
       end
 
@@ -57,7 +57,7 @@ module Teckel
       #
       #     MyOperation.input_constructor.is_a?(Proc) #=> true
       def input_constructor(sym_or_proc = nil)
-        get_set_constructor(:input_constructor, input, sym_or_proc)
+        get_or_set_constructor(:input_constructor, input, sym_or_proc)
       end
 
       # @overload output()
@@ -70,7 +70,7 @@ module Teckel
       #   @param  klass [Class] The +output+ class
       #   @return [Class] The +output+ class
       def output(klass = nil)
-        @config.for(:output, klass) { self::Output if const_defined?(:Output) } ||
+        @config.get_or_set(:output, klass) { self::Output if const_defined?(:Output) } ||
           raise(MissingConfigError, "Missing output config for #{self}")
       end
 
@@ -102,7 +102,7 @@ module Teckel
       #       output_constructor ->(name, options) { Output.new(name: name, **options) }
       #     end
       def output_constructor(sym_or_proc = nil)
-        get_set_constructor(:output_constructor, output, sym_or_proc)
+        get_or_set_constructor(:output_constructor, output, sym_or_proc)
       end
 
       # @overload error()
@@ -114,7 +114,7 @@ module Teckel
       #   @param klass [Class] The +error+ class
       #   @return [Class,nil] The +error+ class or +nil+ if it does not error
       def error(klass = nil)
-        @config.for(:error, klass) { self::Error if const_defined?(:Error) } ||
+        @config.get_or_set(:error, klass) { self::Error if const_defined?(:Error) } ||
           raise(MissingConfigError, "Missing error config for #{self}")
       end
 
@@ -146,7 +146,7 @@ module Teckel
       #       error_constructor ->(name, options) { Error.new(name: name, **options) }
       #     end
       def error_constructor(sym_or_proc = nil)
-        get_set_constructor(:error_constructor, error, sym_or_proc)
+        get_or_set_constructor(:error_constructor, error, sym_or_proc)
       end
 
       # @!endgroup
@@ -160,7 +160,7 @@ module Teckel
       #   @param klass [Class] The +settings+ class
       #   @return [Class] The +settings+ class configured
       def settings(klass = nil)
-        @config.for(:settings, klass) { const_defined?(:Settings) ? self::Settings : none }
+        @config.get_or_set(:settings, klass) { const_defined?(:Settings) ? self::Settings : none }
       end
 
       # @overload settings_constructor()
@@ -187,7 +187,7 @@ module Teckel
       #      settings_constructor :new
       #    end
       def settings_constructor(sym_or_proc = nil)
-        get_set_constructor(:settings_constructor, settings, sym_or_proc) ||
+        get_or_set_constructor(:settings_constructor, settings, sym_or_proc) ||
           raise(MissingConfigError, "Missing settings_constructor config for #{self}")
       end
 
@@ -222,13 +222,14 @@ module Teckel
 
         callable ||= -> { settings_constructor.call(*args) }
 
-        @config.for(:default_settings, callable)
+        @config.get_or_set(:default_settings, callable)
       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
 
       # @overload runner()
@@ -240,12 +241,12 @@ 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()
       #   Get the configured result object class wrapping {error} or {output}.
-      #   The {ValueResult} default will act as a pass-through and does. Any error
+      #   The {ValueResult} default will act as a pass-through. Any error
       #   or output will just returned as-is.
       #   @return [Class] The +result+ class, or {ValueResult} as default
       #
@@ -254,9 +255,12 @@ 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 : ValueResult }
+        @config.get_or_set(:result, klass) { const_defined?(:Result, false) ? self::Result : ValueResult }
       end
 
+      # @param sym_or_proc [Symbol,Proc,NilClass]
+      # @return [#call]
+      #
       # @overload result_constructor()
       #   The callable constructor to build an instance of the +result+ class.
       #   Defaults to {Teckel::DEFAULT_CONSTRUCTOR}
@@ -282,7 +286,7 @@ module Teckel
       #      result_constructor ->(value, success) { result.new(value, success, {foo: :bar}) }
       #    end
       def result_constructor(sym_or_proc = nil)
-        get_set_constructor(:result_constructor, result, sym_or_proc) ||
+        get_or_set_constructor(:result_constructor, result, sym_or_proc) ||
           raise(MissingConfigError, "Missing result_constructor config for #{self}")
       end
 
@@ -293,14 +297,15 @@ module Teckel
       #
       # @!visibility protected
       # @note Don't use in conjunction with {result} or {result_constructor}
-      # @return [nil]
+      # @return [void]
       def result!
-        @config.for(:result, Result)
-        @config.for(:result_constructor, Result.method(:new))
+        @config.get_or_set(:result, Result)
+        @config.get_or_set(:result_constructor, Result.method(:new))
         nil
       end
 
       # @!visibility private
+      # @return [Array<Symbol>]
       REQUIRED_CONFIGS = %i[
         input input_constructor
         output output_constructor
@@ -334,7 +339,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 operation and all it's configuration
@@ -343,9 +348,9 @@ 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
 
@@ -355,7 +360,7 @@ module Teckel
       # @!visibility public
       def freeze
         @config.freeze
-        super()
+        super() # standard:disable Style/SuperArguments
       end
 
       # @!visibility private
@@ -372,22 +377,20 @@ module Teckel
         end
       end
 
-      private
-
-      def dup_config(other_class)
+      private def dup_config(other_class)
         other_class.instance_variable_set(:@config, @config.dup)
         other_class
       end
 
-      def get_set_constructor(name, on, sym_or_proc)
+      private def get_or_set_constructor(name, on, sym_or_proc)
         constructor = build_constructor(on, sym_or_proc)
 
-        @config.for(name, constructor) {
+        @config.get_or_set(name, constructor) {
           build_constructor(on, DEFAULT_CONSTRUCTOR)
         }
       end
 
-      def build_constructor(on, sym_or_proc)
+      private def build_constructor(on, sym_or_proc)
         case sym_or_proc
         when Proc
           sym_or_proc