teckel 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 520b717d1e115614b1c93cfac56deac0e567bfc5d39e2ca6e93094f3c958fd9b
-  data.tar.gz: d5f8f5a5dd2a2dabebe1add49ab139e9c5d14fd5c1fd3b1ef92f78c99c604401
+  metadata.gz: 18179b7fd315a11bc51f0ac4cfbdba4c0e74ad82a6a7dc186289433906ec2783
+  data.tar.gz: 02eb5f5c59ac9983a92b457f9253a38f9188e3f2b17d4f30029aa545b3151181
 SHA512:
-  metadata.gz: cb4021c0102a0d18e45df23a40669984462b5d469608f16cefcff68fefa38a088ae4851f51052ba5b3c3f5305dc6d0abfbf2a50a81ca240748cf226ea5b66366
-  data.tar.gz: 4298d3bff376cace7dd78a863fc60da2f7e4600f8032da19a3c7ecaee6168146fe41658af16e1811ad7de157cf15a37aa0bad42cdc19602de8eac1b2a2f49a83
+  metadata.gz: cbbbebfecccf6806da642dbc1dce843946c7dcaa27abb7c38467b0512ff5cb32d13b848fae0eaa0f8c4641f26e5b1f03f58f82fb70b3aa8aa1a891356698ff16
+  data.tar.gz: b312534680f31d7cff2a13326f3dc3cc01566110d3001b285d233c97548edbfb2fe008d59821ef0723b63687f12e95cca3f06f2f7c1a3f8d0e15d90caca4733d

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changes
 
+## 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

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,20 @@
 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/operation"
 require_relative "teckel/chain"

data/lib/teckel/chain.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require 'forwardable'
+require_relative 'chain/step'
+require_relative 'chain/result'
+require_relative 'chain/runner'
 
 module Teckel
   # Railway style execution of multiple Operations.
@@ -8,253 +10,11 @@ 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                   #=> :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."}
-  #
-  # @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                   #=> :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."}
+  # @see Teckel::Operation#result!
   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, result)
-        @step, @result = step, result
-      end
-
-      # @!method step
-      #   Delegates to +step.name+
-      #   @return [String,Symbol] The name of the failed operation.
-      def_delegator :@step, :name, :step
-
-      # @!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
-      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 |step|
-          last_result = step.operation.call(last_result)
-          if last_result.failure?
-            failed = StepFailure.new(step, 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
@@ -281,8 +41,8 @@ module Teckel
       #
       # @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.
+      # @param operation [Operation] The operation to call, which
+      #   must return a {Teckel::Result} object.
       def step(name, operation)
         steps << Step.new(name, operation)
       end
@@ -308,7 +68,8 @@ module Teckel
       #   OUTPUTS = []
       #
       #   class Echo
-      #     include ::Teckel::Operation::Results
+      #     include ::Teckel::Operation
+      #     result!
       #
       #     input Hash
       #     output input
@@ -349,15 +110,57 @@ module Teckel
         @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
+      #
+      #      class Result < Teckel::Operation::Result
+      #        def initialize(value, success, step, options = {}); end
+      #      end
+      #
+      #      # If you need more control over how to build a new +Settings+ instance
+      #      result_constructor ->(value, success, step) { result.new(value, success, step, {foo: :bar}) }
+      #    end
+      def result_constructor(sym_or_proc = nil)
+        constructor = build_counstructor(result, sym_or_proc) unless sym_or_proc.nil?
+
+        @config.for(:result_constructor, constructor) {
+          build_counstructor(result, Teckel::DEFAULT_CONSTRUCTOR)
+        } || raise(MissingConfigError, "Missing result_constructor config for #{self}")
+      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)
+        runner = self.runner.new(self)
         if around
           around.call(runner, input)
         else
@@ -365,12 +168,23 @@ module Teckel
         end
       end
 
+      # @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
+          runner
+        end
+      end
+      alias :set :with
+
       # @!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) }
+        %i[around runner result result_constructor].each { |e| public_send(e) }
         steps.each(&:finalize!)
         nil
       end
@@ -384,7 +198,7 @@ module Teckel
         define!
         steps.freeze
         @config.freeze
-        freeze
+        self
       end
 
       # Produces a shallow copy of this chain.
@@ -393,12 +207,7 @@ module Teckel
       # @return [self]
       # @!visibility public
       def dup
-        super.tap do |copy|
-          new_config = @config.dup
-          new_config.replace(:steps) { steps.dup }
-
-          copy.instance_variable_set(:@config, new_config)
-        end
+        dup_config(super)
       end
 
       # Produces a clone of this chain.
@@ -410,22 +219,41 @@ module Teckel
         if frozen?
           super
         else
-          super.tap do |copy|
-            new_config = @config.dup
-            new_config.replace(:steps) { steps.dup }
+          dup_config(super)
+        end
+      end
 
-            copy.instance_variable_set(:@config, new_config)
-          end
+      # @!visibility private
+      def inherited(subclass)
+        dup_config(subclass)
+      end
+
+      # @!visibility private
+      def self.extended(base)
+        base.instance_variable_set(:@config, 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_counstructor(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)
+          sym_or_proc
         end
       end
     end
 
     def self.included(receiver)
       receiver.extend ClassMethods
-
-      receiver.class_eval do
-        @config = Config.new
-      end
     end
   end
 end