convenient_service 0.1.0 → 0.2.1

data/lib/convenient_service/examples/rails/gemfile.rb

@@ -4,17 +4,18 @@ require_relative "gemfile/rails_service"
 require_relative "gemfile/services"
 
 ##
-# Usage example:
+# @internal
+#   Usage example:
 #
-# result = ConvenientService::Examples::Rails::Gemfile.format(path: "Gemfile")
-# result = ConvenientService::Examples::Rails::Gemfile.format(path: "spec/cli/gemfile/format/fixtures/Gemfile")
+#   result = ConvenientService::Examples::Rails::Gemfile.format("Gemfile")
+#   result = ConvenientService::Examples::Rails::Gemfile.format("spec/cli/gemfile/format/fixtures/Gemfile")
 #
 module ConvenientService
   module Examples
     module Rails
       module Gemfile
         class << self
-          def format
+          def format(path)
             Services::Format[path: path]
           end
         end

data/lib/convenient_service/examples/standard/cowsay/services/build_cloud.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Examples
+    module Standard
+      module Cowsay
+        module Services
+          class BuildCloud
+            include ConvenientService::Standard::Config
+
+            attr_reader :text
+
+            def initialize(text: "Hello World!")
+              @text = text
+            end
+
+            def result
+              success(cloud: cloud)
+            end
+
+            private
+
+            ##
+            # Copied with ❤️ from https://github.com/gaborbata/rosetta-cow
+            #
+            def cloud
+              <<~HEREDOC
+                 #{border(text, "_")}
+                < #{text} >
+                 #{border(text, "-")}
+              HEREDOC
+            end
+
+            def border(text, char)
+              char * (text.length + 2)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/cowsay/services/build_cow.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Examples
+    module Standard
+      module Cowsay
+        module Services
+          class BuildCow
+            include ConvenientService::Standard::Config
+
+            def result
+              success(cow: cow)
+            end
+
+            private
+
+            ##
+            # Copied with ❤️ from https://github.com/gaborbata/rosetta-cow
+            #
+            def cow
+              <<~'HEREDOC'.split("\n").map { |line| offset(line) }.join("\n")
+                \   ^__^
+                 \  (oo)\_______
+                    (__)\       )\/\
+                        ||----w |
+                        ||     ||
+              HEREDOC
+            end
+
+            def offset(line)
+              " " * 10 + line
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/cowsay/services/print.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Examples
+    module Standard
+      module Cowsay
+        module Services
+          class Print
+            include ConvenientService::Standard::Config
+
+            attr_reader :text, :out
+
+            step Services::BuildCloud, in: :text, out: :cloud
+            step Services::BuildCow, out: :cow
+            step :result
+
+            def initialize(text: "Hello World!", out: $stdout)
+              @text = text
+              @out = out
+            end
+
+            def result
+              out.puts cloud + cow
+
+              success
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/cowsay/services.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "services/build_cloud"
+require_relative "services/build_cow"
+require_relative "services/print"

data/lib/convenient_service/examples/standard/cowsay.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "cowsay/services"
+
+##
+# @internal
+#   Usage examples:
+#
+#   result = ConvenientService::Examples::Standard::Cowsay.print("Hello")
+#   result = ConvenientService::Examples::Standard::Cowsay.print("Hi")
+#
+module ConvenientService
+  module Examples
+    module Standard
+      module Cowsay
+        class << self
+          def print(text = "Hello World!", out: $stdout)
+            Services::Print[text: text, out: out]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/gemfile/services/format.rb

@@ -14,6 +14,8 @@ module ConvenientService
           class Format
             include ConvenientService::Standard::Config
 
+            attr_reader :path
+
             step Services::ReadFileContent, in: :path, out: :content
             step Services::StripComments, in: :content, out: :content_without_comments
             step Services::ParseContent, in: {content: :content_without_comments}, out: :parsed_content

data/lib/convenient_service/examples/standard/gemfile.rb

@@ -3,17 +3,18 @@
 require_relative "gemfile/services"
 
 ##
-# Usage example:
+# @internal
+#   Usage example:
 #
-# result = ConvenientService::Examples::Standard::Gemfile.format(path: "Gemfile")
-# result = ConvenientService::Examples::Standard::Gemfile.format(path: "spec/cli/gemfile/format/fixtures/Gemfile")
+#   result = ConvenientService::Examples::Standard::Gemfile.format("Gemfile")
+#   result = ConvenientService::Examples::Standard::Gemfile.format("spec/cli/gemfile/format/fixtures/Gemfile")
 #
 module ConvenientService
   module Examples
     module Standard
       module Gemfile
         class << self
-          def format
+          def format(path)
             Services::Format[path: path]
           end
         end

data/lib/convenient_service/rspec/helpers/custom/stub_service/entities/result_spec.rb

@@ -5,72 +5,140 @@ module ConvenientService
     module Helpers
       module Custom
         ##
-        # TODO: Specs.
+        # @internal
+        #   TODO: Specs.
         #
         class StubService < Support::Command
           module Entities
             class ResultSpec
+              ##
+              # @param status [Symbol]
+              # @param service_class [Class]
+              # @param chain [Hash]
+              # @return [void]
+              # @since 0.1.0
+              #
               def initialize(status:, service_class: nil, chain: {})
                 @status = status
                 @service_class = service_class
                 @chain = chain
               end
 
+              ##
+              # @param service_class [Class]
+              # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::ResultSpec]
+              # @since 0.1.0
+              #
               def for(service_class)
                 self.class.new(status: status, service_class: service_class, chain: chain)
               end
 
+              ##
+              # @param data [Hash]
+              # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::ResultSpec]
+              # @since 0.1.0
+              #
               def with_data(data)
                 chain[:data] = data
 
                 self
               end
 
+              ##
+              # @param message [String]
+              # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::ResultSpec]
+              # @since 0.1.0
+              #
               def with_message(message)
                 chain[:message] = message
 
                 self
               end
 
+              ##
+              # @param code [String]
+              # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::ResultSpec]
+              # @since 0.1.0
+              #
               def with_code(code)
                 chain[:code] = code
 
                 self
               end
 
+              ##
+              # @param data [Hash]
+              # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::ResultSpec]
+              # @since 0.1.0
+              #
               def and_data(data)
                 chain[:data] = data
 
                 self
               end
 
+              ##
+              # @param message [String]
+              # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::ResultSpec]
+              # @since 0.1.0
+              #
               def and_message(message)
                 chain[:message] = message
 
                 self
               end
 
+              ##
+              # @param code [String]
+              # @return [ConvenientService::RSpec::Helpers::Custom::StubService::Entities::ResultSpec]
+              # @since 0.1.0
+              #
               def and_code(code)
                 chain[:code] = code
 
                 self
               end
 
+              ##
+              # @return [Object]
+              #
+              # @internal
+              #    TODO: Assert.
+              #
               def calculate_value
-                ##
-                # TODO: Assert.
-                #
                 service_class.__send__(status, **kwargs)
               end
 
               private
 
-              attr_reader :status, :service_class, :chain
-
+              ##
+              # @!attribute [r] status
+              #   @return [Symbol]
+              #
+              attr_reader :status
+
+              ##
+              # @!attribute [r] service_class
+              #   @return [Class]
+              #
+              attr_reader :service_class
+
+              ##
+              # @!attribute [r] chain
+              #   @return [Hash]
+              #
+              attr_reader :chain
+
+              ##
+              # @return [Hash]
+              #
               def kwargs
                 @kwargs ||= calculate_kwargs
               end
 
+              ##
+              # @return [Hash]
+              #
               def calculate_kwargs
                 kwargs = {}
 
@@ -83,32 +151,53 @@ module ConvenientService
                 kwargs
               end
 
+              ##
+              # @return [Boolean]
+              #
               def used_data?
                 chain.key?(:data)
               end
 
+              ##
+              # @return [Boolean]
+              #
               def used_message?
                 chain.key?(:message)
               end
 
+              ##
+              # @return [Boolean]
+              #
               def used_code?
                 chain.key?(:code)
               end
 
+              ##
+              # @return [Hash]
+              #
               def data
                 @data ||= chain[:data] || {}
               end
 
+              ##
+              # @return [String]
+              #
               def message
                 @message ||= chain[:message] || ""
               end
 
+              ##
+              # @return [String]
+              #
               def code
                 @code ||= chain[:code] || ""
               end
 
+              ##
+              # @return [Object]
+              #
               def service_instance
-                @service_instance ||= service_class.new_without_initialize
+                @service_instance ||= service_class.create_without_initialize
               end
             end
           end

data/lib/convenient_service/rspec/helpers/custom/wrap_method/entities/wrapped_method.rb

@@ -4,17 +4,23 @@ module ConvenientService
   module RSpec
     module Helpers
       module Custom
-        ##
-        # TODO: Specs.
-        #
         class WrapMethod < Support::Command
           module Entities
             ##
-            # NOTE: Do NOT pollute the interface of this class until really needed. Avoid even pollution of private methods.
+            # @internal
+            #   TODO: A better name.
+            #
+            #   NOTE: Do NOT pollute the interface of this class until really needed. Avoid even pollution of private methods.
             #
             class WrappedMethod
               ##
-              # NOTE: `middlewares` are `MethodChainMiddleware` classes.
+              # @param entity [Object, Class]
+              # @param method [String]
+              # @param middlewares [Array<ConvenientService::Core::MethodChainMiddleware>]
+              # @return [void]
+              #
+              # @internal
+              #   NOTE: `middlewares` are `MethodChainMiddleware` classes.
               #
               def initialize(entity:, method:, middlewares:)
                 @entity = entity
@@ -29,9 +35,6 @@ module ConvenientService
                   #
                   stack.use(
                     proc do |env|
-                      ##
-                      # TODO: Enforce to always pass args, kwargs, block.
-                      #
                       entity.__send__(method, *env[:args], **env[:kwargs], &env[:block])
                         .tap { |value| @chain_value = value }
                         .tap { @chain_arguments = {args: env[:args], kwargs: env[:kwargs], block: env[:block]} }
@@ -40,32 +43,65 @@ module ConvenientService
                 end
               end
 
+              ##
+              # @param args [Array]
+              # @param kwargs [Hash]
+              # @param block [Proc]
+              # @return [Object] Can be any type.
+              #
               def call(*args, **kwargs, &block)
                 @stack.call(entity: @entity, method: @method, args: args, kwargs: kwargs, block: block)
               end
 
+              ##
+              # @return [void]
+              #
+              def reset!
+                remove_instance_variable(:@chain_value) if defined? @chain_value
+                remove_instance_variable(:@chain_arguments) if defined? @chain_arguments
+              end
+
+              ##
+              # @return [Boolean]
+              #
               def chain_called?
                 Utils::Bool.to_bool(defined? @chain_value)
               end
 
+              ##
+              # @return [Object] Can be any type.
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              #
               def chain_value
                 raise Errors::ChainAttributePreliminaryAccess.new(attribute: :value) unless chain_called?
 
                 @chain_value
               end
 
+              ##
+              # @return [Array]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              #
               def chain_args
                 raise Errors::ChainAttributePreliminaryAccess.new(attribute: :args) unless chain_called?
 
                 @chain_arguments[:args]
               end
 
+              ##
+              # @return [Hash]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              #
               def chain_kwargs
                 raise Errors::ChainAttributePreliminaryAccess.new(attribute: :kwargs) unless chain_called?
 
                 @chain_arguments[:kwargs]
               end
 
+              ##
+              # @return [Proc, nil]
+              # @raise [ConvenientService::RSpec::Helpers::Custom::WrapMethod::Errors::ChainAttributePreliminaryAccess]
+              #
               def chain_block
                 raise Errors::ChainAttributePreliminaryAccess.new(attribute: :block) unless chain_called?
 

data/lib/convenient_service/rspec/helpers/custom/wrap_method/errors.rb

@@ -5,16 +5,18 @@ module ConvenientService
     module Helpers
       module Custom
         class WrapMethod < Support::Command
-          class WrappedMethod
-            module Errors
-              class ChainAttributePreliminaryAccess < ::StandardError
-                def initialize(attribute:)
-                  message <<~TEXT
-                    Chain attribute `#{attribute}` is accessed before the chain is called.
-                  TEXT
+          module Errors
+            class ChainAttributePreliminaryAccess < ConvenientService::Error
+              ##
+              # @param attribute [Symbol]
+              # @return [void]
+              #
+              def initialize(attribute:)
+                message = <<~TEXT
+                  Chain attribute `#{attribute}` is accessed before the chain is called.
+                TEXT
 
-                  super(message)
-                end
+                super(message)
               end
             end
           end

data/lib/convenient_service/rspec/matchers/custom/cache_its_value.rb

@@ -23,26 +23,26 @@ module ConvenientService
           end
 
           def failure_message
-            "expected #{printable_block} to cache its value"
+            "expected #{printable_block_expectation} to cache its value"
           end
 
           def failure_message_when_negated
-            "expected #{printable_block} NOT to cache its value"
+            "expected #{printable_block_expectation} NOT to cache its value"
           end
 
           ##
           # NOTE: An example of how RSpec extracts block source, but they marked it as private.
           # https://github.com/rspec/rspec-expectations/blob/311aaf245f2c5493572bf683b8c441cb5f7e44c8/lib/rspec/matchers/built_in/change.rb#L437
           #
-          # TODO: `printable_block` when `method_source` is available.
+          # TODO: `printable_block_expectation` when `method_source` is available.
           # https://github.com/banister/method_source
           #
-          # def printable_block
-          #   @printable_block ||= block_expectation.source
+          # def printable_block_expectation
+          #   @printable_block_expectation ||= block_expectation.source
           # end
           #
-          def printable_block
-            @printable_block ||= "{ ... }"
+          def printable_block_expectation
+            @printable_block_expectation ||= "{ ... }"
           end
 
           private

data/lib/convenient_service/rspec/matchers/custom/call_chain_next.rb

@@ -84,6 +84,8 @@ module ConvenientService
           end
 
           def on(method)
+            method.reset!
+
             chain[:method] = method
 
             self

data/lib/convenient_service/rspec/matchers/custom/delegate_to.rb

@@ -1,5 +1,18 @@
 # frozen_string_literal: true
 
+##
+# IMPORTANT: This matcher has a dedicated end-user doc. Do NOT forget to update it when needed.
+# https://github.com/marian13/convenient_service_docs/blob/main/docs/api/tests/rspec/matchers/delegate_to.mdx
+#
+# TODO: Refactor into composition:
+#   - Ability to compose when `delegate_to` is used `without_arguments`.
+#   - Ability to compose when `delegate_to` is used `with_arguments`.
+#   - Ability to compose when `delegate_to` is used `and_return_its_value`.
+#
+# TODO: Refactor to NOT use `expect` inside this matcher.
+# This way the matcher will return true or false, but never raise exceptions (descendant of Exception, not StandardError).
+# Then it will be easier to developer a fully comprehensive spec suite for `delegate_to`.
+#
 module ConvenientService
   module RSpec
     module Matchers
@@ -81,15 +94,7 @@ module ConvenientService
               # https://relishapp.com/rspec/rspec-mocks/docs/configuring-responses/wrapping-the-original-implementation
               #
               allow(object).to receive(method).and_wrap_original do |original, *actual_args, **actual_kwargs, &actual_block|
-                ##
-                # TODO: Provide customized error messages?
-                # https://relishapp.com/rspec/rspec-expectations/docs/customized-message
-                #
-                # NOTE: `delegate_to` expects that delegation is executed only once during `block_expectation`.
-                #
-                expect(actual_args).to eq(expected_args)
-                expect(actual_kwargs).to eq(expected_kwargs)
-                expect(actual_block).to eq(expected_block)
+                actual_arguments_collection << [actual_args, actual_kwargs, actual_block]
 
                 ##
                 # NOTE: Imitates `and_call_original`.
@@ -108,7 +113,7 @@ module ConvenientService
             ##
             # NOTE: If this expectation fails, it means `delegate_to` is NOT met.
             #
-            expect(object).to have_received(method)
+            expect(object).to have_received(method).at_least(1) unless used_with_arguments?
 
             ##
             # IMPORTANT: `and_return_its_value` works only when `delegate_to` checks a pure function.
@@ -166,7 +171,13 @@ module ConvenientService
             # NOTE: RSpec raises exception when any `expect` is NOT satisfied.
             # So, this `true` is returned only when all `expect` are successful.
             #
-            true
+            if used_with_arguments?
+              actual_arguments_collection.any? do |(actual_args, actual_kwargs, actual_block)|
+                actual_args == expected_args && actual_kwargs == expected_kwargs && actual_block == expected_block
+              end
+            else
+              true
+            end
           end
 
           ##
@@ -184,8 +195,16 @@ module ConvenientService
             "delegate to `#{printable_method}`"
           end
 
+          def failure_message
+            if used_with_arguments?
+              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` with expected arguments at least once, but it didn't."
+            else
+              "expected `#{printable_block_expectation}` to delegate to `#{printable_method}` at least once, but it didn't."
+            end
+          end
+
           ##
-          # IMPORTANT: `failure_message`, `failure_message_when_negated` are NOT implemented, since they are never called (since `matches?` always returns `true`).
+          # IMPORTANT: `failure_message_when_negated` is NOT supported yet.
           #
 
           def with_arguments(*args, **kwargs, &block)
@@ -248,6 +267,25 @@ module ConvenientService
           end
 
           alias_method :expected_block, :block
+
+          def actual_arguments_collection
+            @actual_arguments_collection ||= []
+          end
+
+          ##
+          # NOTE: An example of how RSpec extracts block source, but they marked it as private.
+          # https://github.com/rspec/rspec-expectations/blob/311aaf245f2c5493572bf683b8c441cb5f7e44c8/lib/rspec/matchers/built_in/change.rb#L437
+          #
+          # TODO: `printable_block_expectation` when `method_source` is available.
+          # https://github.com/banister/method_source
+          #
+          # def printable_block_expectation
+          #   @printable_block_expectation ||= block_expectation.source
+          # end
+          #
+          def printable_block_expectation
+            @printable_block_expectation ||= "{ ... }"
+          end
         end
       end
     end