teckel 0.1.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f8117e6d304e571ccfd26db58af5122330494e3df8b2597cfa5f8e11ad19b12
-  data.tar.gz: 9aeecbf92e87d3fa0610defed63f0e3f1048925348c43af00d83aab68ffb1265
+  metadata.gz: d55dd7fb782cfdcb3cc960423e46ab2ce8b49c9396273f10749105883d55ed6f
+  data.tar.gz: e3b7428d98daeb42cc086b4a5cd5081b5c3b4ca90c14b0cf3f4cd9576243d0e3
 SHA512:
-  metadata.gz: 7b6eef841002932cad55e8bd4a7121d173624633962de203e0eda72602bbf36afa947126100bd7795ab078540b4b7210a32fc0d51eea117c558943d418026526
-  data.tar.gz: 60c090f9fd1ec11deb535dcd0e9838146401f361754f15469a80104b69ec58d68a64c5d32399b29d1fb0264538e418e3cf1c3188df6f3fac1af6c87f2fca631b
+  metadata.gz: '0148d426e8e7124a08a3a7dd3c42487cac5944d17ba9cabb98a8c378a86a5d9813b7b62c483d2203809644528d2e6b6cc4de51476aa67261b1405f3f41576613'
+  data.tar.gz: 6792ad4806b977d21d0ea621e311306cb13c239d8604e35e61937e79ce4f5488cbb410aa6ae22e9e12e48b61529f97e924aab22e100717808885c0b0c76980fd

data/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changes
+
+## 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
+- `finalize!` 
+  - freezing Chains and Operations, to prevent further changes
+  - Operations check their config and raise if any is missing
+
+## 0.1.0
+
+- Initial release

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

@@ -5,7 +5,8 @@ Ruby service classes with enforced<sup name="footnote-1-source">[1](#footnote-1)
 [![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]
 [![Maintainability](https://api.codeclimate.com/v1/badges/b3939aaec6271a567a57/maintainability)](https://codeclimate.com/github/fnordfish/teckel/maintainability)
-[![API Documentation Coverage](http://inch-ci.org/github/dry-rb/dry-configurable.svg)][inch]
+[![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]
 
 ## Installation
 
@@ -33,30 +34,35 @@ Working with [Interactor](https://github.com/collectiveidea/interactor), [Trailb
 
 ## Usage
 
-For a full overview please see the [Api Docs](https://fnordfish.github.io/teckel/doc/)
+For a full overview please see the Docs:
+
+* [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/)
 
-This example uses [Dry::Types](https://dry-rb.org/gems/dry-types/) to illustrate the flexibility. There's no dependency on dry-rb, choose what you like.
 
 ```ruby
 class CreateUser
   include Teckel::Operation
-  
+
   # DSL style declaration
-  input Types::Hash.schema(name: Types::String, age: Types::Coercible::Integer)
-  
+  input Struct.new(:name, :age, keyword_init: true)
+
   # Constant style declaration
-  Output = Types.Instance(User)
+  Output = ::User
 
   # Well, also Constant style, but using classic `class` notation
-  class Error < Dry::Struct
-    attribute :message, Types::String
-    attribute :status_code, Types::Integer
-    attribute :meta, Types::Hash.optional
+  class Error
+    def initialize(message:, status_code:, meta:)
+      @message, @status_code, @meta = message, status_code, meta
+    end
+    attr_reader :message, :status_code, :meta
   end
+  error_constructor :new
 
   def call(input)
-    user = User.create(input)
-    if user.safe
+    user = User.new(name: input.name, age: input.age)
+    if user.save
       success!(user)
     else
       fail!(
@@ -68,7 +74,9 @@ class CreateUser
   end
 end
 
-result = CreateUser.call(name: "Bob", age: 23)
+CreateUser.call(name: "Bob", age: 23) #=> #<User @age=23, @name="Bob">
+
+CreateUser.call(name: "Bob", age: 5)  #=> #<CreateUser::Error @message="Could not create User", @meta={:validation=>[{:age=>"underage"}]}, @status_code=400>
 ```
 
 ## Development

data/lib/teckel.rb

@@ -3,11 +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/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,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,179 +11,71 @@ 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+ 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
-  # @see Teckel::Result
-  # @see Teckel::Chain::StepFailure
-  #
-  # @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.safe
-  #         success!(user)
-  #       else
-  #         fail!(message: "Could not safe 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."}
+  # @see Teckel::Operation#result!
   module Chain
-    # Like +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
-
     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
 
-      def call(input)
-        new.call!(@steps, input)
-      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::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
 
-      def step(name, operation)
-        @steps << [name, operation]
+        if around
+          around.call(runner, input)
+        else
+          runner.call(input)
+        end
       end
-    end
 
-    module InstanceMethods
-      def call!(steps, input)
-        result = input
-        failed = nil
-        steps.each do |(name, step)|
-          result = step.call(result)
-          if result.failure?
-            failed = StepFailure.new(step, name, result)
-            break
-          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
-
-        failed || result
       end
+      alias :set :with
     end
 
     def self.included(receiver)
-      receiver.extend         ClassMethods
-      receiver.send :include, InstanceMethods
-
-      receiver.class_eval do
-        @steps = []
-      end
+      receiver.extend Config
+      receiver.extend ClassMethods
     end
   end
 end