teckel 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f8117e6d304e571ccfd26db58af5122330494e3df8b2597cfa5f8e11ad19b12
-  data.tar.gz: 9aeecbf92e87d3fa0610defed63f0e3f1048925348c43af00d83aab68ffb1265
+  metadata.gz: a9fbb7828be6e84c5d609241e778e39e8509a4cede9f8960f097b31ef0d2473b
+  data.tar.gz: b646f5954b1fb331186f52cf2a6ccd8521004bb26e59a09ec6b6d4d8575affa2
 SHA512:
-  metadata.gz: 7b6eef841002932cad55e8bd4a7121d173624633962de203e0eda72602bbf36afa947126100bd7795ab078540b4b7210a32fc0d51eea117c558943d418026526
-  data.tar.gz: 60c090f9fd1ec11deb535dcd0e9838146401f361754f15469a80104b69ec58d68a64c5d32399b29d1fb0264538e418e3cf1c3188df6f3fac1af6c87f2fca631b
+  metadata.gz: 454b1869e2b2a8bf540f203fccf9962d628c236c2ced1411ded69ca2ccb1e0c361965c74ad73dea6c709b97b7757016c24487f983924111b03f4f0c1c2d0287e
+  data.tar.gz: fd5f0e9e4e147238423454ef7a801139fd6f0ef3b1a7c2198285b7c471f1a26fb64c879647a9c041edb8129e4279a00e52572038959e9b8bd473668772dd78e2

data/.codeclimate.yml

@@ -0,0 +1,3 @@
+plugins:
+  rubocop:
+    enabled: true

data/.github/workflows/ci.yml

@@ -50,6 +50,9 @@ jobs:
       fail-fast: false
       matrix:
         image: ["jruby:9.2.9", "ruby:2.7"]
+        include:
+        - image: "ruby:2.7"
+          coverage: "true"
     container:
       image: ${{matrix.image}}
 
@@ -59,9 +62,31 @@ jobs:
         run: |
           apt-get update
           apt-get install -y --no-install-recommends git
+      - name: Download test reporter
+        if: "matrix.coverage == 'true'"
+        run: |
+          mkdir -p tmp/
+          curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./tmp/cc-test-reporter
+          chmod +x ./tmp/cc-test-reporter
+          ./tmp/cc-test-reporter before-build
       - name: Bundle install
+        env:
+          COVERAGE: ${{matrix.coverage}}
         run: |
           gem install bundler
           bundle install --jobs 4 --retry 3 --without tools docs benchmarks
       - name: Run all tests
+        env:
+          COVERAGE: ${{matrix.coverage}}
         run: bundle exec rake
+      - name: Send coverage results
+        if: "matrix.coverage == 'true'"
+        env:
+          CC_TEST_REPORTER_ID: ${{secrets.CC_TEST_REPORTER_ID}}
+          GIT_COMMIT_SHA: ${{github.sha}}
+          GIT_BRANCH: ${{github.ref}}
+          GIT_COMMITTED_AT: ${{github.event.head_commit.timestamp}}
+        run: |
+          GIT_BRANCH=`ruby -e "puts ENV['GITHUB_REF'].split('/', 3).last"` \
+          GIT_COMMITTED_AT=`ruby -r time -e "puts Time.iso8601(ENV['GIT_COMMITTED_AT']).to_i"` \
+          ./tmp/cc-test-reporter after-build -t simplecov

data/.gitignore

@@ -11,3 +11,5 @@
 .rspec_status
 
 .rubocop-http*
+
+/Gemfile.lock

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changes
+
+## 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/DEVELOPMENT.md

@@ -1,12 +1,12 @@
 # Development Guidelines
 
-- Keep is simple.
+- Keep it simple.
 - Favor easy debug-ability over clever solutions.
 - Aim to be a 0-dependency lib (at runtime)
 
 ## Roadmap
 
-- Add "Settings" for Operations and Chains
+- Add "Settings"/Dependency injection for Operations and Chains
 
     ```
     MyOp.with(foo: "bar").call("input")
@@ -22,7 +22,11 @@
 
     MyCain.with(:step1) { { foo: "bar" } }.with(:stepX) { { another: :setting} }.call(params)
     ```
-- Add support for around hooks in Chains (for db transactions etc.)
-- Add a dry-monads mixin to wrap Operations and Chains result/error into a Result Monad
+- Add a dry-monads mixin to wrap Operations and Chains result/error into a Result Monad (for example see https://dry-rb.org/gems/dry-types/master/extensions/monads/)
+    ```
+    MyOp.call("input").to_monad do
+    end
+    ```
+- Check if/how to deal with inheritance 
 - ...
 

data/Gemfile

@@ -6,3 +6,11 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in teckel.gemspec
 gemspec
+
+group :development, :test do
+  gem "dry-struct", ">= 1.1.1", "< 2"
+end
+
+group :test do
+  gem "simplecov", require: false
+end

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 Api 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)
 
-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/Rakefile

@@ -7,6 +7,11 @@ require "yard/doctest/rake"
 
 RSpec::Core::RakeTask.new(:spec)
 
+task :docs do
+  Rake::Task["docs:yard"].invoke
+  Rake::Task["docs:yard:doctest"].invoke
+end
+
 namespace :docs do
   YARD::Rake::YardocTask.new do |t|
     t.files   = ['lib/**/*.rb']

data/lib/teckel.rb

@@ -4,9 +4,12 @@ require "teckel/version"
 
 module Teckel
   class Error < StandardError; end
+  class FrozenConfigError < Teckel::Error; end
+  class MissingConfigError < Teckel::Error; end
 end
 
 require_relative "teckel/config"
+require_relative "teckel/none"
 require_relative "teckel/operation"
 require_relative "teckel/result"
 require_relative "teckel/operation/results"

data/lib/teckel/chain.rb

@@ -8,14 +8,13 @@ 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
+  # - 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
   #
   # @see Teckel::Operation::Results
-  # @see Teckel::Result
-  # @see Teckel::Chain::StepFailure
   #
   # @example Defining a simple Chain with three steps
   #   class CreateUser
@@ -27,10 +26,10 @@ module Teckel
   #
   #     def call(input)
   #       user = User.new(name: input[:name], age: input[:age])
-  #       if user.safe
+  #       if user.save
   #         success!(user)
   #       else
-  #         fail!(message: "Could not safe User", errors: user.errors)
+  #         fail!(message: "Could not save User", errors: user.errors)
   #       end
   #     end
   #   end
@@ -92,8 +91,89 @@ module Teckel
   #   # 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."}
   module Chain
-    # Like +Teckel::Result+ but for failing Chains
+    # Like {Teckel::Result Teckel::Result} but for failing Chains
     #
     # When a Chain fails, it stores the failed +Operation+ and it's name.
     class StepFailure
@@ -133,15 +213,52 @@ module Teckel
       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
       end
 
+      # The expected output for this chain
+      # @return [Class] The {Teckel::Operation.output} of the last step
       def output
         @steps.last&.last&.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
@@ -149,37 +266,125 @@ module Teckel
         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)
-        new.call!(@steps, input)
+        runner = self.runner.new(@steps)
+        if around
+          around.call(runner, input)
+        else
+          runner.call(input)
+        end
       end
 
-      def step(name, operation)
-        @steps << [name, operation]
+      # Disallow any further changes to this Chain.
+      #
+      # @return [self] Frozen self
+      # @!visibility public
+      def finalize!
+        freeze
+        @steps.freeze
+        @config.freeze
+        self
       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
+      # @!visibility public
+      def dup
+        super.tap do |copy|
+          copy.instance_variable_set(:@steps, @steps.dup)
+          copy.instance_variable_set(:@config, @config.dup)
         end
+      end
 
-        failed || result
+      # @!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)
+          end
+        end
       end
     end
 
     def self.included(receiver)
-      receiver.extend         ClassMethods
-      receiver.send :include, InstanceMethods
+      receiver.extend ClassMethods
 
       receiver.class_eval do
         @steps = []
+        @config = Config.new
       end
     end
   end