convenient_service 0.12.0 → 0.13.0

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/directions/input.rb

@@ -14,11 +14,11 @@ module ConvenientService
                   end
 
                   def validate_as_output_for_container!(container, method:)
-                    raise Errors::MethodIsNotOutputMethod.new(method: method, container: container)
+                    raise Exceptions::MethodIsNotOutputMethod.new(method: method, container: container)
                   end
 
                   def define_output_in_container!(container, index:, method:)
-                    raise Errors::MethodIsNotOutputMethod.new(method: method, container: container)
+                    raise Exceptions::MethodIsNotOutputMethod.new(method: method, container: container)
                   end
                 end
               end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/directions/output.rb

@@ -10,7 +10,7 @@ module ConvenientService
               module Directions
                 class Output < Base
                   def validate_as_input_for_container!(container, method:)
-                    raise Errors::MethodIsNotInputMethod.new(method: method, container: container)
+                    raise Exceptions::MethodIsNotInputMethod.new(method: method, container: container)
                   end
 
                   def validate_as_output_for_container!(container, method:)

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/factories/hash/base.rb

@@ -21,7 +21,7 @@ module ConvenientService
                     # @return [Object] Can be any object.
                     #
                     def value
-                      Utils::Object.memoize_including_falsy_values(self, :@value) { other.values.first }
+                      Utils.memoize_including_falsy_values(self, :@value) { other.values.first }
                     end
                   end
                 end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/key.rb

@@ -11,14 +11,34 @@ module ConvenientService
                 include Support::Copyable
                 include Support::Delegate
 
+                ##
+                # @!attribute [r] value
+                #   @return [Symbol]
+                #
                 attr_reader :value
 
+                ##
+                # @return [String]
+                #
                 delegate :to_s, :to_sym, to: :value
 
+                ##
+                # @return [Symbol]
+                #
+                delegate :to_sym, to: :value
+
+                ##
+                # @param value [Symbol]
+                # @return [void]
+                #
                 def initialize(value)
                   @value = value
                 end
 
+                ##
+                # @param other [Object] Can be any type.
+                # @return [Boolean, nil]
+                #
                 def ==(other)
                   return unless other.instance_of?(self.class)
 
@@ -27,8 +47,18 @@ module ConvenientService
                   true
                 end
 
+                ##
+                # @return [Array<Object>]
+                #
                 def to_args
-                  [value]
+                  to_arguments.args
+                end
+
+                ##
+                # @return [ConveninentService::Support::Arguments]
+                #
+                def to_arguments
+                  Support::Arguments.new(value)
                 end
               end
             end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/entities/name.rb

@@ -11,14 +11,34 @@ module ConvenientService
                 include Support::Copyable
                 include Support::Delegate
 
+                ##
+                # @!attribute [r] value
+                #   @return [Symbol]
+                #
                 attr_reader :value
 
+                ##
+                # @return [String]
+                #
                 delegate :to_s, :to_sym, to: :value
 
+                ##
+                # @return [Symbol]
+                #
+                delegate :to_sym, to: :value
+
+                ##
+                # @param value [Symbol]
+                # @return [void]
+                #
                 def initialize(value)
                   @value = value
                 end
 
+                ##
+                # @param other [Object] Can be any type.
+                # @return [Boolean, nil]
+                #
                 def ==(other)
                   return unless other.instance_of?(self.class)
 
@@ -27,8 +47,18 @@ module ConvenientService
                   true
                 end
 
+                ##
+                # @return [Array<Object>]
+                #
                 def to_args
-                  [value]
+                  to_arguments.args
+                end
+
+                ##
+                # @return [ConveninentService::Support::Arguments]
+                #
+                def to_arguments
+                  Support::Arguments.new(value)
                 end
               end
             end

data/lib/convenient_service/service/plugins/can_have_steps/entities/method/{errors.rb → exceptions.rb}

@@ -6,11 +6,18 @@ module ConvenientService
       module CanHaveSteps
         module Entities
           class Method
-            module Errors
-              class MethodHasNoOrganizer < ::ConvenientService::Error
+            module Exceptions
+              class MethodHasNoOrganizer < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @return [void]
+                #
+                # @internal
+                #   TODO: Introduce `Method#step` for more verbose message?
+                #
                 def initialize(method:)
                   message = <<~TEXT
-                    Organizer for method `#{method.name}` is NOT assigned yet.
+                    Organizer for method `:#{method.name}` is NOT assigned yet.
 
                     Did you forget to set it?
                   TEXT
@@ -19,7 +26,12 @@ module ConvenientService
                 end
               end
 
-              class InputMethodIsNotDefinedInContainer < ::ConvenientService::Error
+              class InputMethodIsNotDefinedInContainer < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     `in` method `#{method.name}` is NOT defined in `#{container.klass}`.
@@ -31,7 +43,12 @@ module ConvenientService
                 end
               end
 
-              class OutputMethodIsDefinedInContainer < ::ConvenientService::Error
+              class OutputMethodIsDefinedInContainer < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     `out` method `#{method.name}` is already defined in `#{container.klass}`.
@@ -43,7 +60,12 @@ module ConvenientService
                 end
               end
 
-              class AliasInputMethodIsNotDefinedInContainer < ::ConvenientService::Error
+              class AliasInputMethodIsNotDefinedInContainer < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Alias `in` method `#{method.name}` is NOT defined in `#{container.klass}`.
@@ -55,7 +77,12 @@ module ConvenientService
                 end
               end
 
-              class AliasOutputMethodIsDefinedInContainer < ::ConvenientService::Error
+              class AliasOutputMethodIsDefinedInContainer < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Alias `out` method `#{method.name}` is already defined in `#{container.klass}`.
@@ -67,7 +94,12 @@ module ConvenientService
                 end
               end
 
-              class OutputMethodProc < ::ConvenientService::Error
+              class OutputMethodProc < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Procs are not allowed for `out` methods.
@@ -77,7 +109,12 @@ module ConvenientService
                 end
               end
 
-              class OutputMethodRawValue < ::ConvenientService::Error
+              class OutputMethodRawValue < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Raw values are not allowed for `out` methods.
@@ -87,7 +124,11 @@ module ConvenientService
                 end
               end
 
-              class CallerCanNotCalculateReassignment < ::ConvenientService::Error
+              class CallerCanNotCalculateReassignment < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @return [void]
+                #
                 def initialize(method:)
                   message = <<~TEXT
                     Method caller failed to calculate reassignment for `#{method.name}`.
@@ -99,7 +140,12 @@ module ConvenientService
                 end
               end
 
-              class InputMethodReassignment < ::ConvenientService::Error
+              class InputMethodReassignment < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Reassignments are not allowed for `in` methods.
@@ -109,7 +155,12 @@ module ConvenientService
                 end
               end
 
-              class MethodIsNotInputMethod < ::ConvenientService::Error
+              class MethodIsNotInputMethod < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Method `#{method.name}` is NOT an `in` method.
@@ -119,7 +170,12 @@ module ConvenientService
                 end
               end
 
-              class MethodIsNotOutputMethod < ::ConvenientService::Error
+              class MethodIsNotOutputMethod < ::ConvenientService::Exception
+                ##
+                # @param method [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method]
+                # @param container [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [void]
+                #
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Method `#{method.name}` is NOT an `out` method.
@@ -129,7 +185,12 @@ module ConvenientService
                 end
               end
 
-              class NotCompletedStep < ::ConvenientService::Error
+              class NotCompletedStep < ::ConvenientService::Exception
+                ##
+                # @param method_name [Symbol]
+                # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+                # @return [void]
+                #
                 def initialize(method_name:, step:)
                   message = <<~TEXT
                     `out` method `#{method_name}` is called before its corresponding step `#{step.printable_service}` is completed.
@@ -141,7 +202,12 @@ module ConvenientService
                 end
               end
 
-              class NotExistingStepResultDataAttribute < ::ConvenientService::Error
+              class NotExistingStepResultDataAttribute < ::ConvenientService::Exception
+                ##
+                # @param key [Symbol]
+                # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+                # @return [void]
+                #
                 def initialize(key:, step:)
                   message = <<~TEXT
                     Step `#{step.printable_service}` result does NOT return `#{key}` data attribute.

data/lib/convenient_service/service/plugins/can_have_steps/entities/method.rb

@@ -3,7 +3,7 @@
 require_relative "method/commands"
 require_relative "method/concern"
 require_relative "method/entities"
-require_relative "method/errors"
+require_relative "method/exceptions"
 
 module ConvenientService
   module Service

data/lib/convenient_service/service/plugins/can_have_steps/entities/service/concern/class_methods.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Service
+            module Concern
+              module ClassMethods
+                ##
+                # @param other [Object] Can be any type.
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service, nil]
+                #
+                def cast(other)
+                  case other
+                  when ::Class then cast_klass(other)
+                  when Service then cast_service(other)
+                  end
+                end
+
+                private
+
+                ##
+                # @param klass [Class]
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                #
+                def cast_klass(klass)
+                  new(klass)
+                end
+
+                ##
+                # @param service [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                #
+                def cast_service(service)
+                  new(service.klass)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/service/concern/instance_methods.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Service
+            module Concern
+              module InstanceMethods
+                include Support::Delegate
+
+                ##
+                # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+                #
+                delegate :result, to: :klass
+
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+                #
+                delegate :step_class, to: :klass
+
+                ##
+                # @!attribute [r] klass
+                #   @return [Class]
+                #
+                attr_reader :klass
+
+                ##
+                # @param klass [Class]
+                #
+                def initialize(klass)
+                  @klass = klass
+                end
+
+                ##
+                # @param method [String, Symbol]
+                # @return [Boolean]
+                #
+                def has_defined_method?(method)
+                  Utils::Method.defined?(method, klass, private: true)
+                end
+
+                ##
+                # @param other [Object] Can be any type.
+                # @return [Boolean, nil]
+                #
+                def ==(other)
+                  casted = cast(other)
+
+                  return unless casted
+
+                  return false if klass != casted.klass
+
+                  true
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/service/concern.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "concern/instance_methods"
+require_relative "concern/class_methods"
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Service
+            module Concern
+              include Support::Concern
+
+              included do |service_klass|
+                service_klass.include Support::Castable
+
+                service_klass.include InstanceMethods
+
+                service_klass.extend ClassMethods
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/service.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "service/class_methods"
+require_relative "service/concern"
 
 module ConvenientService
   module Service
@@ -8,38 +8,15 @@ module ConvenientService
       module CanHaveSteps
         module Entities
           ##
-          # NOTE: Service is a wrapper for a service class (klass). For example:
+          # @internal
+          #   NOTE: Service is a wrapper for a service class (klass).
+          #   For example:
           #
-          #   step SomeService, in: :foo, out: :bar
-          #   # klass is `SomeService` in this particular case.
+          #     step SomeService, in: :foo, out: :bar
+          #     # klass is `SomeService` in this particular case.
           #
           class Service
-            include Support::Castable
-            include Support::Delegate
-
-            extend ClassMethods
-
-            delegate :result, :step_class, to: :klass
-
-            attr_reader :klass
-
-            def initialize(klass)
-              @klass = klass
-            end
-
-            def has_defined_method?(method)
-              Utils::Method.defined?(method, klass, private: true)
-            end
-
-            def ==(other)
-              casted = cast(other)
-
-              return unless casted
-
-              return false if klass != casted.klass
-
-              true
-            end
+            include Concern
           end
         end
       end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/commands/cast_params.rb

@@ -8,12 +8,23 @@ module ConvenientService
           class Step
             module Commands
               class CastParams < Support::Command
+                ##
+                # @!attribute [r] original_params
+                #   @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Structs::Params]
+                #
                 attr_reader :original_params
 
+                ##
+                # @param original_params [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Structs::Params]
+                # @return [void]
+                #
                 def initialize(original_params:)
                   @original_params = original_params
                 end
 
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Structs::Params]
+                #
                 def call
                   Structs::Params.new(
                     service: service,
@@ -21,36 +32,62 @@ module ConvenientService
                     outputs: outputs,
                     index: index,
                     container: container,
-                    organizer: organizer
+                    organizer: organizer,
+                    extra_kwargs: extra_kwargs
                   )
                 end
 
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                #
                 def service
                   @service ||= Entities::Service.cast!(original_params.service)
                 end
 
                 ##
-                # TODO: `cast_many`, `cast_many!`.
+                # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method>]
+                #
+                # @internal
+                #   TODO: `cast_many`, `cast_many!`.
                 #
                 def inputs
                   @inputs ||= original_params.inputs.map { |input| Entities::Method.cast!(input, direction: :input) }
                 end
 
+                ##
+                # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Method>]
+                #
                 def outputs
                   @outputs ||= original_params.outputs.map { |output| Entities::Method.cast!(output, direction: :output) }
                 end
 
+                ##
+                # @return [Integer]
+                #
                 def index
                   @index ||= original_params.index
                 end
 
+                ##
+                # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Service]
+                #
                 def container
                   @container ||= Entities::Service.cast!(original_params.container)
                 end
 
+                ##
+                # @return [ConvenientService::Service]
+                #
                 def organizer
                   @organizer ||= original_params.organizer
                 end
+
+                ##
+                # @return [Hash{Symbol => Object}]
+                #
+                def extra_kwargs
+                  @extra_kwargs ||= original_params.extra_kwargs
+                end
               end
             end
           end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/commands/extract_params.rb

@@ -21,11 +21,9 @@ module ConvenientService
                     inputs: Utils::Array.wrap(kwargs[:in]),
                     outputs: Utils::Array.wrap(kwargs[:out]),
                     index: kwargs[:index],
-                    ##
-                    # TODO: Specs.
-                    #
                     container: kwargs[:container],
-                    organizer: kwargs[:organizer]
+                    organizer: kwargs[:organizer],
+                    extra_kwargs: Utils::Hash.except(kwargs, [:in, :out, :index, :container, :organizer])
                   )
                 end
               end