teckel 0.2.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9fbb7828be6e84c5d609241e778e39e8509a4cede9f8960f097b31ef0d2473b
-  data.tar.gz: b646f5954b1fb331186f52cf2a6ccd8521004bb26e59a09ec6b6d4d8575affa2
+  metadata.gz: df9c73577c9c93fbaaf2e7661a07bdc3b1b0397832a62a8edbe4eea846c4c029
+  data.tar.gz: 037041bf0eb6ae8bc41e354772d3ce1d04002a35ecccc0b1ecefa33a85845c3b
 SHA512:
-  metadata.gz: 454b1869e2b2a8bf540f203fccf9962d628c236c2ced1411ded69ca2ccb1e0c361965c74ad73dea6c709b97b7757016c24487f983924111b03f4f0c1c2d0287e
-  data.tar.gz: fd5f0e9e4e147238423454ef7a801139fd6f0ef3b1a7c2198285b7c471f1a26fb64c879647a9c041edb8129e4279a00e52572038959e9b8bd473668772dd78e2
+  metadata.gz: 2f6f601e816c972aed8e511b05fdbc418a48aab10c2ca246d108661cc25a8d514a41944b2e01b9294757a2a717696491f20f601f5f60e53faa45651aec48bc7f
+  data.tar.gz: 68bc46e5ed21cf5e639ee1fc00265b278f9062f42de9d179a07559862990a078df9dcb2ef26956eb629cf08e71409b9b05bd363a11930cb64ecdee533d63d2ea

data/CHANGELOG.md

@@ -1,5 +1,116 @@
 # Changes
 
+## 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
+- `#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
+    # you won't be able to overwrite any configuration in child classes,
+    # so take care which you want to declare
+    result!
+    settings Struct.new(:logger)
+    input_constructor :new
+    error Struct.new(:status, :messages)
+
+    def log(message)
+      return unless settings&.logger
+      logger << message
+    end
+    # 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]
+    # handle failure
+  in [true, value]
+    # handle success
+  end
+
+  case MyChain.call(params)
+  in { success: false, step: :foo, value: value } 
+    # handle foo failure
+  in [success: false, step: :bar, value: value }
+    # handle bar failure
+  in { success: true, value: value }
+    # 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
+
 ## 0.2.0
 
 - Around Hooks for Chains

data/LICENSE_LOGO

@@ -0,0 +1,4 @@
+The Teckel Logo artwork is NOT part of the Work as described in the LICENSE.
+Any Derivative Works shall not use the Teckel Logo.
+
+Copyright 2020 Jana Vogel <jana@dotless.de>

data/README.md

@@ -34,11 +34,11 @@ Working with [Interactor](https://github.com/collectiveidea/interactor), [Trailb
 
 ## Usage
 
-For a full overview please see the Api Docs:
+For a full overview please see the Docs:
 
-* [Operations](https://fnordfish.github.io/teckel/doc/Teckel/Operation.html)
-* [Operations with Result objects](https://fnordfish.github.io/teckel/doc/Teckel/Operation/Results.html)
-* [Chains](https://fnordfish.github.io/teckel/doc/Teckel/Chain.html)
+* [Operations](https://fnordfish.github.io/teckel/operations/basics/)
+* [Result Objects](https://fnordfish.github.io/teckel/operations/result_objects/)
+* [Chains](https://fnordfish.github.io/teckel/chains/basics/)
 
 
 ```ruby

data/lib/teckel.rb

@@ -3,14 +3,19 @@
 require "teckel/version"
 
 module Teckel
+  # Base error class for this lib
   class Error < StandardError; end
+
+  # configuring the same value twice will raise this
   class FrozenConfigError < Teckel::Error; end
+
+  # missing important configurations (like contracts) will raise this
   class MissingConfigError < Teckel::Error; end
+
+  DEFAULT_CONSTRUCTOR = :[]
 end
 
 require_relative "teckel/config"
-require_relative "teckel/none"
-require_relative "teckel/operation"
+require_relative "teckel/contracts"
 require_relative "teckel/result"
-require_relative "teckel/operation/results"
-require_relative "teckel/chain"
+require_relative "teckel/operation"

data/lib/teckel/chain.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-require 'forwardable'
+require_relative 'chain/config'
+require_relative 'chain/step'
+require_relative 'chain/result'
+require_relative 'chain/runner'
 
 module Teckel
   # Railway style execution of multiple Operations.
@@ -8,338 +11,49 @@ module Teckel
   # - Runs multiple Operations (steps) in order.
   # - The output of an earlier step is passed as input to the next step.
   # - Any failure will stop the execution chain (none of the later steps is called).
-  # - All Operations (steps) must behave like
-  #   {Teckel::Operation::Results Teckel::Operation::Results} and return a result
-  #   object like {Teckel::Result}
-  # - A failure response is wrapped into a {Teckel::Chain::StepFailure} giving
-  #   additional information about which step failed
+  # - All Operations (steps) must return a {Teckel::Result}
+  # - The result is wrapped into a {Teckel::Chain::Result}
   #
-  # @see Teckel::Operation::Results
-  #
-  # @example Defining a simple Chain with three steps
-  #   class CreateUser
-  #     include ::Teckel::Operation::Results
-  #
-  #     input  Types::Hash.schema(name: Types::String, age: Types::Coercible::Integer.optional)
-  #     output Types.Instance(User)
-  #     error  Types::Hash.schema(message: Types::String, errors: Types::Array.of(Types::Hash))
-  #
-  #     def call(input)
-  #       user = User.new(name: input[:name], age: input[:age])
-  #       if user.save
-  #         success!(user)
-  #       else
-  #         fail!(message: "Could not save User", errors: user.errors)
-  #       end
-  #     end
-  #   end
-  #
-  #   class LogUser
-  #     include ::Teckel::Operation::Results
-  #
-  #     input Types.Instance(User)
-  #     output input
-  #
-  #     def call(usr)
-  #       Logger.new(File::NULL).info("User #{usr.name} created")
-  #       usr # we need to return the correct output type
-  #     end
-  #   end
-  #
-  #   class AddFriend
-  #     class << self
-  #       # Don't actually do this! It's not safe and for generating the failure sample only.
-  #       attr_accessor :fail_befriend
-  #     end
-  #
-  #     include ::Teckel::Operation::Results
-  #
-  #     input Types.Instance(User)
-  #     output Types::Hash.schema(user: Types.Instance(User), friend: Types.Instance(User))
-  #     error  Types::Hash.schema(message: Types::String)
-  #
-  #     def call(user)
-  #       if self.class.fail_befriend
-  #         fail!(message: "Did not find a friend.")
-  #       else
-  #         { user: user, friend: User.new(name: "A friend", age: 42) }
-  #       end
-  #     end
-  #   end
-  #
-  #   class MyChain
-  #     include Teckel::Chain
-  #
-  #     step :create, CreateUser
-  #     step :log, LogUser
-  #     step :befriend, AddFriend
-  #   end
-  #
-  #   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
-  #
-  #   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
-  #
-  #   # otherwise behaves just like a normal +Result+
-  #   failure_result.failure?                         #=> true
-  #   failure_result.failure                          #=> {message: "Did not find a friend."}
-  #
-  # @example DB transaction around hook
-  #   class CreateUser
-  #     include ::Teckel::Operation::Results
-  #
-  #     input  Types::Hash.schema(name: Types::String, age: Types::Coercible::Integer.optional)
-  #     output Types.Instance(User)
-  #     error  Types::Hash.schema(message: Types::String, errors: Types::Array.of(Types::Hash))
-  #
-  #     def call(input)
-  #       user = User.new(name: input[:name], age: input[:age])
-  #       if user.save
-  #         success!(user)
-  #       else
-  #         fail!(message: "Could not safe User", errors: user.errors)
-  #       end
-  #     end
-  #   end
-  #
-  #   class AddFriend
-  #     class << self
-  #       # Don't actually do this! It's not safe and for generating the failure sample only.
-  #       attr_accessor :fail_befriend
-  #     end
-  #
-  #     include ::Teckel::Operation::Results
-  #
-  #     input Types.Instance(User)
-  #     output Types::Hash.schema(user: Types.Instance(User), friend: Types.Instance(User))
-  #     error  Types::Hash.schema(message: Types::String)
-  #
-  #     def call(user)
-  #       if self.class.fail_befriend
-  #         fail!(message: "Did not find a friend.")
-  #       else
-  #         { user: user, friend: User.new(name: "A friend", age: 42) }
-  #       end
-  #     end
-  #   end
-  #
-  #   LOG = []
-  #
-  #   class MyChain
-  #     include Teckel::Chain
-  #
-  #     around ->(chain, input) {
-  #       result = nil
-  #       begin
-  #         LOG << :before
-  #
-  #         FakeDB.transaction do
-  #           result = chain.call(input)
-  #           raise FakeDB::Rollback if result.failure?
-  #         end
-  #
-  #         LOG << :after
-  #         result
-  #       rescue FakeDB::Rollback
-  #         LOG << :rollback
-  #         result
-  #       end
-  #     }
-  #
-  #     step :create, CreateUser
-  #     step :befriend, AddFriend
-  #   end
-  #
-  #   AddFriend.fail_befriend = true
-  #   failure_result = MyChain.call(name: "Bob", age: 23)
-  #   failure_result.is_a?(Teckel::Chain::StepFailure) #=> true
-  #
-  #   # triggered DB rollback
-  #   LOG                                              #=> [:before, :rollback]
-  #
-  #   # additional step information
-  #   failure_result.step_name                         #=> :befriend
-  #   failure_result.step                              #=> AddFriend
-  #
-  #   # otherwise behaves just like a normal +Result+
-  #   failure_result.failure?                          #=> true
-  #   failure_result.failure                           #=> {message: "Did not find a friend."}
+  # @see Teckel::Operation#result!
   module Chain
-    # 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
-      end
-
-      # @!attribute step [R]
-      # @return [Teckel::Operation] the failed Operation
-      attr_reader :step
-
-      # @!attribute step_name [R]
-      # @return [String] the step name of the failed Operation
-      attr_reader :step_name
-
-      # @!attribute result [R]
-      # @return [Teckel::Result] the failure Result
-      attr_reader :result
-
-      # @!method value
-      #   Delegates to +result.value+
-      #   @see Teckel::Result#value
-      # @!method successful?
-      #   Delegates to +result.successful?+
-      #   @see Teckel::Result#successful?
-      # @!method success
-      #   Delegates to +result.success+
-      #   @see Teckel::Result#success
-      # @!method failure?
-      #   Delegates to +result.failure?+
-      #   @see Teckel::Result#failure?
-      # @!method failure
-      #   Delegates to +result.failure+
-      #   @see Teckel::Result#failure
-      def_delegators :@result, :value, :successful?, :success, :failure?, :failure
-    end
-
-    # The default implementation for executing a {Chain}
-    #
-    # @!visibility protected
-    class Runner
-      def initialize(steps)
-        @steps = steps
-      end
-      attr_reader :steps
-
-      # Run steps
-      #
-      # @param input Any form of input the first steps +input+ class can handle
-      #
-      # @return [Teckel::Result,Teckel::Chain::StepFailure] The result object wrapping
-      #   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)
-        last_result = input
-        failed = nil
-        steps.each do |(name, step)|
-          last_result = step.call(last_result)
-          if last_result.failure?
-            failed = StepFailure.new(step, name, last_result)
-            break
-          end
-        end
-
-        failed || last_result
-      end
-    end
-
     module ClassMethods
       # 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
 
-      # 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::Results] The operation to call.
-      #   Must return a {Teckel::Result} object.
-      def step(name, operation)
-        @steps << [name, operation]
-      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::Results
-      #
-      #     input Hash
-      #     output input
-      #
-      #     def call(hsh)
-      #       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
-
       # The primary interface to call the chain with the given input.
       #
       # @param input Any form of input the first steps +input+ class can handle
       #
-      # @return [Teckel::Result,Teckel::Chain::StepFailure] The result object wrapping
-      #   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)
+      # @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
+
+        runner =
+          if default_settings
+            self.runner.new(self, default_settings)
+          else
+            self.runner.new(self)
+          end
+
         if around
           around.call(runner, input)
         else
@@ -347,45 +61,21 @@ module Teckel
         end
       end
 
-      # Disallow any further changes to this Chain.
-      #
-      # @return [self] Frozen self
-      # @!visibility public
-      def finalize!
-        freeze
-        @steps.freeze
-        @config.freeze
-        self
-      end
-
-      # @!visibility public
-      def dup
-        super.tap do |copy|
-          copy.instance_variable_set(:@steps, @steps.dup)
-          copy.instance_variable_set(:@config, @config.dup)
-        end
-      end
-
-      # @!visibility public
-      def clone
-        if frozen?
-          super
+      # @param settings [Hash{String,Symbol => Object}] Set settings for a step by it's name
+      def with(settings)
+        runner = self.runner.new(self, settings)
+        if around
+          ->(input) { around.call(runner, input) }
         else
-          super.tap do |copy|
-            copy.instance_variable_set(:@steps, @steps.dup)
-            copy.instance_variable_set(:@config, @config.dup)
-          end
+          runner
         end
       end
+      alias :set :with
     end
 
     def self.included(receiver)
+      receiver.extend Config
       receiver.extend ClassMethods
-
-      receiver.class_eval do
-        @steps = []
-        @config = Config.new
-      end
     end
   end
 end