convenient_service 0.1.0 → 0.2.0

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/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/results/be_success.rb

@@ -27,6 +27,12 @@ module ConvenientService
               self
             end
 
+            def without_data
+              chain[:data] = {}
+
+              self
+            end
+
             def of(service_class)
               chain[:service_class] = service_class
 

data/lib/convenient_service/service/plugins/aliases.rb

@@ -4,5 +4,6 @@ module ConvenientService
   module Plugins
     Result = ::ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins
     Service = ::ConvenientService::Service::Plugins
+    Step = ::ConvenientService::Service::Plugins::HasResultSteps::Entities::Step::Plugins
   end
 end

data/lib/convenient_service/service/plugins/has_inspect/concern.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasInspect
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            ##
+            # @return [String]
+            # @since 0.2.0
+            #
+            def inspect
+              "<#{self.class.name}>"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_inspect.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "has_inspect/concern"

data/lib/convenient_service/service/plugins/has_result/commands/create_result_class.rb

@@ -8,10 +8,17 @@ module ConvenientService
           class CreateResultClass < Support::Command
             attr_reader :service_class
 
+            ##
+            # @param service_class [Class]
+            # @return [void]
+            #
             def initialize(service_class:)
               @service_class = service_class
             end
 
+            ##
+            # @return [void]
+            #
             def call
               result_class.include Entities::Result::Concern
 
@@ -45,6 +52,9 @@ module ConvenientService
 
             private
 
+            ##
+            # @return [Class]
+            #
             def result_class
               @result_class ||= Utils::Module.get_own_const(service_class, :Result) || ::Class.new(Entities::Result)
             end

data/lib/convenient_service/service/plugins/has_result/concern/class_methods.rb

@@ -7,28 +7,25 @@ module ConvenientService
         module Concern
           module ClassMethods
             ##
-            #
+            # @api public
+            # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
             #
             def result(...)
               new(...).result
             end
 
             ##
-            # https://ruby-doc.org/core-2.5.0/Class.html#method-i-allocate
-            # https://frontdeveloper.pl/2018/11/ruby-allocate-method/
+            # @api private
+            # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
             #
-            def new_without_initialize
-              allocate
-            end
-
-            ##
-            # NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
+            # @internal
+            #   NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
             #
             def success(
               service: Constants::DEFAULT_SERVICE_INSTANCE,
               data: Constants::DEFAULT_SUCCESS_DATA
             )
-              result_class.new(
+              result_class.create(
                 service: service,
                 status: Constants::SUCCESS_STATUS,
                 data: data,
@@ -38,14 +35,18 @@ module ConvenientService
             end
 
             ##
-            # NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
+            # @api private
+            # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+            #
+            # @internal
+            #   NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
             #
             def failure(
               service: Constants::DEFAULT_SERVICE_INSTANCE,
               data: Constants::DEFAULT_FAILURE_DATA,
               message: data.any? ? data.first.join(" ") : Constants::DEFAULT_FAILURE_MESSAGE
             )
-              result_class.new(
+              result_class.create(
                 service: service,
                 status: Constants::FAILURE_STATUS,
                 data: data,
@@ -55,14 +56,18 @@ module ConvenientService
             end
 
             ##
-            # NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
+            # @api private
+            # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+            #
+            # @internal
+            #   NOTE: This method is internally used by custom RSpec helper `stub_service`. It should NOT be used in the client code.
             #
             def error(
               service: Constants::DEFAULT_SERVICE_INSTANCE,
               message: Constants::DEFAULT_ERROR_MESSAGE,
               code: Constants::DEFAULT_ERROR_CODE
             )
-              result_class.new(
+              result_class.create(
                 service: service,
                 status: Constants::ERROR_STATUS,
                 data: Constants::ERROR_DATA,
@@ -71,6 +76,10 @@ module ConvenientService
               )
             end
 
+            ##
+            # @api private
+            # @return [Class]
+            #
             def result_class
               @result_class ||= Commands::CreateResultClass.call(service_class: self)
             end

data/lib/convenient_service/service/plugins/has_result/concern/instance_methods.rb

@@ -6,21 +6,37 @@ module ConvenientService
       module HasResult
         module Concern
           module InstanceMethods
+            ##
+            # @api public
+            # @raise [ConvenientService::Service::Plugins::HasResult::Errors::ResultIsNotOverridden]
+            #
             def result
               raise Errors::ResultIsNotOverridden.new(service: self)
             end
 
             ##
-            # TODO: Specs.
+            # @api public
+            # @param kwargs [Hash]
+            # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
             #
             def success(**kwargs)
               self.class.success(**kwargs.merge(service: self))
             end
 
+            ##
+            # @api public
+            # @param kwargs [Hash]
+            # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+            #
             def failure(**kwargs)
               self.class.failure(**kwargs.merge(service: self))
             end
 
+            ##
+            # @api public
+            # @param kwargs [Hash]
+            # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
+            #
             def error(**kwargs)
               self.class.error(**kwargs.merge(service: self))
             end

data/lib/convenient_service/service/plugins/has_result/entities/result/concern.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
-require_relative "concern/instance_methods"
-
 module ConvenientService
   module Service
     module Plugins
       module HasResult
         module Entities
           class Result
+            ##
+            # @internal
+            #   This concern is needed for `CastResultClass` and `be_success`, `be_error`, `be_failure` matchers.
+            #
             module Concern
-              include Support::Concern
             end
           end
         end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_inspect/concern.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasInspect
+                module Concern
+                  include Support::Concern
+
+                  instance_methods do
+                    ##
+                    # @return [String]
+                    # @since 0.2.0
+                    #
+                    def inspect
+                      "<#{service.class.name}::Result status: :#{status}>"
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_inspect.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "has_inspect/concern"

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_jsend_status_and_attributes/commands/cast_jsend_attributes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJsendStatusAndAttributes
+                module Commands
+                  class CastJSendAttributes < Support::Command
+                    attr_reader :attributes
+
+                    def initialize(attributes:)
+                      @attributes = attributes
+                    end
+
+                    def call
+                      Structs::JSendAttributes.new(
+                        service: attributes[:service],
+                        status: Entities::Status.cast!(attributes[:status]),
+                        data: Entities::Data.cast!(attributes[:data]),
+                        message: Entities::Message.cast!(attributes[:message]),
+                        code: Entities::Code.cast!(attributes[:code])
+                      )
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_jsend_status_and_attributes/commands.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "commands/cast_jsend_attributes"