teckel 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9fbb7828be6e84c5d609241e778e39e8509a4cede9f8960f097b31ef0d2473b
-  data.tar.gz: b646f5954b1fb331186f52cf2a6ccd8521004bb26e59a09ec6b6d4d8575affa2
+  metadata.gz: 520b717d1e115614b1c93cfac56deac0e567bfc5d39e2ca6e93094f3c958fd9b
+  data.tar.gz: d5f8f5a5dd2a2dabebe1add49ab139e9c5d14fd5c1fd3b1ef92f78c99c604401
 SHA512:
-  metadata.gz: 454b1869e2b2a8bf540f203fccf9962d628c236c2ced1411ded69ca2ccb1e0c361965c74ad73dea6c709b97b7757016c24487f983924111b03f4f0c1c2d0287e
-  data.tar.gz: fd5f0e9e4e147238423454ef7a801139fd6f0ef3b1a7c2198285b7c471f1a26fb64c879647a9c041edb8129e4279a00e52572038959e9b8bd473668772dd78e2
+  metadata.gz: cb4021c0102a0d18e45df23a40669984462b5d469608f16cefcff68fefa38a088ae4851f51052ba5b3c3f5305dc6d0abfbf2a50a81ca240748cf226ea5b66366
+  data.tar.gz: 4298d3bff376cace7dd78a863fc60da2f7e4600f8032da19a3c7ecaee6168146fe41658af16e1811ad7de157cf15a37aa0bad42cdc19602de8eac1b2a2f49a83

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changes
 
+## 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
+
 ## 0.2.0
 
 - Around Hooks for Chains

data/lib/teckel/chain.rb

@@ -77,20 +77,20 @@ module Teckel
   #
   #   result = MyChain.call(name: "Bob", age: 23)
   #   result.is_a?(Teckel::Result)          #=> true
-  #   result.success[:user].is_a?(User)    #=> true
-  #   result.success[:friend].is_a?(User)  #=> true
+  #   result.success[:user].is_a?(User)     #=> true
+  #   result.success[:friend].is_a?(User)   #=> true
   #
   #   AddFriend.fail_befriend = true
   #   failure_result = MyChain.call(name: "Bob", age: 23)
   #   failure_result.is_a?(Teckel::Chain::StepFailure) #=> true
   #
   #   # additional step information
-  #   failure_result.step_name                        #=> :befriend
-  #   failure_result.step                             #=> AddFriend
+  #   failure_result.step                   #=> :befriend
+  #   failure_result.operation              #=> AddFriend
   #
   #   # otherwise behaves just like a normal +Result+
-  #   failure_result.failure?                         #=> true
-  #   failure_result.failure                          #=> {message: "Did not find a friend."}
+  #   failure_result.failure?               #=> true
+  #   failure_result.failure                #=> {message: "Did not find a friend."}
   #
   # @example DB transaction around hook
   #   class CreateUser
@@ -163,33 +163,44 @@ module Teckel
   #   failure_result.is_a?(Teckel::Chain::StepFailure) #=> true
   #
   #   # triggered DB rollback
-  #   LOG                                              #=> [:before, :rollback]
+  #   LOG                                   #=> [:before, :rollback]
   #
   #   # additional step information
-  #   failure_result.step_name                         #=> :befriend
-  #   failure_result.step                              #=> AddFriend
+  #   failure_result.step                   #=> :befriend
+  #   failure_result.operation              #=> AddFriend
   #
   #   # otherwise behaves just like a normal +Result+
-  #   failure_result.failure?                          #=> true
-  #   failure_result.failure                           #=> {message: "Did not find a friend."}
+  #   failure_result.failure?               #=> true
+  #   failure_result.failure                #=> {message: "Did not find a friend."}
   module Chain
+    # Internal wrapper of a step definition
+    Step = Struct.new(:name, :operation) do
+      def finalize!
+        name.freeze
+        operation.finalize!
+        freeze
+      end
+    end
+
     # Like {Teckel::Result Teckel::Result} but for failing Chains
     #
     # When a Chain fails, it stores the failed +Operation+ and it's name.
     class StepFailure
       extend Forwardable
 
-      def initialize(step, step_name, result)
-        @step, @step_name, @result = step, step_name, result
+      def initialize(step, result)
+        @step, @result = step, result
       end
 
-      # @!attribute step [R]
-      # @return [Teckel::Operation] the failed Operation
-      attr_reader :step
+      # @!method step
+      #   Delegates to +step.name+
+      #   @return [String,Symbol] The name of the failed operation.
+      def_delegator :@step, :name, :step
 
-      # @!attribute step_name [R]
-      # @return [String] the step name of the failed Operation
-      attr_reader :step_name
+      # @!method operation
+      #   Delegates to +step.operation+
+      #   @return [Teckel::Operation] The failed Operation class.
+      def_delegator :@step, :operation
 
       # @!attribute result [R]
       # @return [Teckel::Result] the failure Result
@@ -232,10 +243,10 @@ module Teckel
       def call(input)
         last_result = input
         failed = nil
-        steps.each do |(name, step)|
-          last_result = step.call(last_result)
+        steps.each do |step|
+          last_result = step.operation.call(last_result)
           if last_result.failure?
-            failed = StepFailure.new(step, name, last_result)
+            failed = StepFailure.new(step, last_result)
             break
           end
         end
@@ -248,20 +259,20 @@ module Teckel
       # The expected input for this chain
       # @return [Class] The {Teckel::Operation.input} of the first step
       def input
-        @steps.first&.last&.input
+        steps.first&.operation&.input
       end
 
       # The expected output for this chain
       # @return [Class] The {Teckel::Operation.output} of the last step
       def output
-        @steps.last&.last&.output
+        steps.last&.operation&.output
       end
 
       # List of all possible errors
       # @return [<Class>] List of all steps {Teckel::Operation.error}s
       def errors
-        @steps.each_with_object([]) do |e, m|
-          err = e.last&.error
+        steps.each_with_object([]) do |step, m|
+          err = step.operation.error
           m << err if err
         end
       end
@@ -273,7 +284,14 @@ module Teckel
       # @param operation [Operation::Results] The operation to call.
       #   Must return a {Teckel::Result} object.
       def step(name, operation)
-        @steps << [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.
@@ -339,7 +357,7 @@ module Teckel
       #   either the success or failure value. Note that the {StepFailure} behaves
       #   just like a {Teckel::Result} with added information about which step failed.
       def call(input)
-        runner = self.runner.new(@steps)
+        runner = self.runner.new(steps)
         if around
           around.call(runner, input)
         else
@@ -347,33 +365,56 @@ module Teckel
         end
       end
 
+      # @!visibility private
+      # @return [void]
+      def define!
+        raise MissingConfigError, "Cannot define Chain with no steps" if steps.empty?
+
+        %i[around runner].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!
-        freeze
-        @steps.freeze
+        define!
+        steps.freeze
         @config.freeze
-        self
+        freeze
       end
 
+      # Produces a shallow copy of this chain.
+      # It's {around}, {runner} and {steps} will get +dup+'ed
+      #
+      # @return [self]
       # @!visibility public
       def dup
         super.tap do |copy|
-          copy.instance_variable_set(:@steps, @steps.dup)
-          copy.instance_variable_set(:@config, @config.dup)
+          new_config = @config.dup
+          new_config.replace(:steps) { steps.dup }
+
+          copy.instance_variable_set(:@config, new_config)
         end
       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
           super.tap do |copy|
-            copy.instance_variable_set(:@steps, @steps.dup)
-            copy.instance_variable_set(:@config, @config.dup)
+            new_config = @config.dup
+            new_config.replace(:steps) { steps.dup }
+
+            copy.instance_variable_set(:@config, new_config)
           end
         end
       end
@@ -383,7 +424,6 @@ module Teckel
       receiver.extend ClassMethods
 
       receiver.class_eval do
-        @steps = []
         @config = Config.new
       end
     end

data/lib/teckel/config.rb

@@ -30,6 +30,14 @@ module Teckel
       @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#[]}
+    #
     # @!visibility private
     def for(key, value = nil, &block)
       if value.nil?
@@ -45,6 +53,11 @@ module Teckel
       end
     end
 
+    # @!visibility private
+    def replace(key)
+      @config[key] = yield if @config.key?(key)
+    end
+
     # @!visibility private
     def freeze
       @config.freeze

data/lib/teckel/operation.rb

@@ -283,7 +283,8 @@ module Teckel
       end
 
       # Convenience method for setting {#input}, {#output} or {#error} to the {None} value.
-      # @return [None]
+      # @return [Object] The {Teckel::None} class.
+      #
       # @example Enforcing nil input, output or error
       #   class MyOperation
       #     include Teckel::Operation
@@ -333,7 +334,7 @@ module Teckel
       end
 
       # @!visibility private
-      # @return [nil]
+      # @return [void]
       def define!
         %i[input input_constructor output output_constructor error error_constructor runner].each { |e|
           public_send(e)
@@ -349,11 +350,13 @@ module Teckel
       # @!visibility public
       def finalize!
         define!
-        freeze
         @config.freeze
-        self
+        freeze
       end
 
+      # Produces a shallow copy of this operation and all it's configuration.
+      #
+      # @return [self]
       # @!visibility public
       def dup
         super.tap do |copy|
@@ -361,6 +364,9 @@ module Teckel
         end
       end
 
+      # Produces a clone of this operation and all it's configuration
+      #
+      # @return [self]
       # @!visibility public
       def clone
         if frozen?
@@ -384,13 +390,17 @@ module Teckel
     end
 
     module InstanceMethods
-      # Halt any further execution with a +output+ value
+      # Halt any further execution with a output value
+      #
+      # @return a thing matching your {Operation::ClassMethods#output Operation#output} definition
       # @!visibility protected
       def success!(*args)
         throw :success, args
       end
 
-      # Halt any further execution with an +error+ value
+      # Halt any further execution with an error value
+      #
+      # @return a thing matching your {Operation::ClassMethods#error Operation#error} definition
       # @!visibility protected
       def fail!(*args)
         throw :failure, args
@@ -404,8 +414,6 @@ module Teckel
       receiver.class_eval do
         @config = Config.new
 
-        @runner = Runner
-
         protected :success!, :fail!
       end
     end

data/lib/teckel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teckel
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: teckel
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Robert Schulze
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-14 00:00:00.000000000 Z
+date: 2020-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -135,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Operations with enforced in/out/err data structures