convenient_service 0.11.0 → 0.12.0

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "entities/directions"
+require_relative "entities/factories"
 require_relative "entities/callers"
 require_relative "entities/key"
 require_relative "entities/name"

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

@@ -67,7 +67,7 @@ module ConvenientService
                 end
               end
 
-              class OutputMethodProc < ConvenientService::Error
+              class OutputMethodProc < ::ConvenientService::Error
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Procs are not allowed for `out` methods.
@@ -77,7 +77,7 @@ module ConvenientService
                 end
               end
 
-              class OutputMethodRawValue < ConvenientService::Error
+              class OutputMethodRawValue < ::ConvenientService::Error
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Raw values are not allowed for `out` methods.
@@ -99,7 +99,7 @@ module ConvenientService
                 end
               end
 
-              class InputMethodReassignment < ConvenientService::Error
+              class InputMethodReassignment < ::ConvenientService::Error
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Reassignments are not allowed for `in` methods.
@@ -109,7 +109,7 @@ module ConvenientService
                 end
               end
 
-              class MethodIsNotInputMethod < ConvenientService::Error
+              class MethodIsNotInputMethod < ::ConvenientService::Error
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Method `#{method.name}` is NOT an `in` method.
@@ -119,7 +119,7 @@ module ConvenientService
                 end
               end
 
-              class MethodIsNotOutputMethod < ConvenientService::Error
+              class MethodIsNotOutputMethod < ::ConvenientService::Error
                 def initialize(method:, container:)
                   message = <<~TEXT
                     Method `#{method.name}` is NOT an `out` method.
@@ -129,7 +129,7 @@ module ConvenientService
                 end
               end
 
-              class NotCompletedStep < ConvenientService::Error
+              class NotCompletedStep < ::ConvenientService::Error
                 def initialize(method_name:, step:)
                   message = <<~TEXT
                     `out` method `#{method_name}` is called before its corresponding step `#{step.printable_service}` is completed.
@@ -141,7 +141,7 @@ module ConvenientService
                 end
               end
 
-              class NotExistingStepResultDataAttribute < ConvenientService::Error
+              class NotExistingStepResultDataAttribute < ::ConvenientService::Error
                 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/step/errors.rb

@@ -4,16 +4,20 @@ module ConvenientService
   module Service
     module Plugins
       module CanHaveSteps
-        module Errors
-          class StepHasNoOrganizer < ConvenientService::Error
-            def initialize(step:)
-              message = <<~TEXT
-                Step `#{step.service}` has not assigned organizer.
+        module Entities
+          class Step
+            module Errors
+              class StepHasNoOrganizer < ::ConvenientService::Error
+                def initialize(step:)
+                  message = <<~TEXT
+                    Step `#{step.service}` has not assigned organizer.
 
-                Did you forget to set it?
-              TEXT
+                    Did you forget to set it?
+                  TEXT
 
-              super(message)
+                  super(message)
+                end
+              end
             end
           end
         end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Plugins
+    Step = ::ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step::Plugins
+  end
+end

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

@@ -2,3 +2,5 @@
 
 require_relative "plugins/can_have_parent_result"
 require_relative "plugins/has_inspect"
+
+require_relative "plugins/aliases"

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

@@ -8,33 +8,49 @@ module ConvenientService
           class StepCollection
             include ::Enumerable
 
+            ##
+            # @!attribute [r] steps
+            #   @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
+            #
             attr_reader :steps
 
-            def initialize
-              @steps = []
+            ##
+            # @param steps [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
+            # @return [void]
+            #
+            def initialize(steps: [])
+              @steps = steps
             end
 
             ##
-            # TODO: Specs.
+            # @return [Boolean] true if called for the first time, false otherwise (similarly as Kernel#require).
+            #
+            # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
+            #
+            # @internal
+            #   IMPORTANT: `step.validate!` is intentionally removed from `steps.each { |step| step.validate! && step.define! }.freeze` since it is NOT idempotent.
+            #
+            #   NOTE: `step.validate!` is still useful as a `doctor` command.
             #
             def commit!
               return false if committed?
 
-              ##
-              # IMPORTANT: Temporarily removed `step.validate!` since it is neither thread-safe nor idempotent.
-              #
-              steps.each { |step| step.define! }.freeze
+              steps.each(&:define!).freeze
 
               true
             end
 
             ##
-            # TODO: Specs.
+            # @return [Boolean]
             #
             def committed?
               steps.frozen?
             end
 
+            ##
+            # @param block [Proc, nil]
+            # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>, Enumerator]
+            #
             def each(&block)
               steps.each(&block)
             end
@@ -52,10 +68,20 @@ module ConvenientService
               steps[index]
             end
 
+            ##
+            # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
+            # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::StepCollection]
+            #
             def <<(step)
               steps << step.copy(overrides: {kwargs: {index: next_available_index}})
+
+              self
             end
 
+            ##
+            # @param other [Object] Can be any type.
+            # @return [Boolean, nil]
+            #
             def ==(other)
               return unless other.instance_of?(self.class)
 
@@ -66,6 +92,9 @@ module ConvenientService
 
             private
 
+            ##
+            # @return [Integer]
+            #
             def next_available_index
               steps.size
             end

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

@@ -7,6 +7,19 @@ module ConvenientService
         module Concern
           include Support::Concern
 
+          included do |service_class|
+            service_class.extend ClassMethods
+
+            ##
+            # IMPORTANT:
+            #   - Initializes `stubbed_results` during the `include Concern` process.
+            #   - Tries to enforce thread-safety in such a way.
+            #   - https://github.com/ruby/spec/blob/master/core/module/include_spec.rb
+            #   - https://github.com/ruby/ruby/blob/master/class.c
+            #
+            service_class.stubbed_results
+          end
+
           class_methods do
             ##
             # @return [ConvenientService::Support::Cache]
@@ -17,16 +30,8 @@ module ConvenientService
             #   - https://github.com/rspec/rspec-core/blob/v3.12.0/lib/rspec/core.rb#L122
             #   - https://relishapp.com/rspec/rspec-core/docs/metadata/current-example
             #
-            #   TODO: Mutex for thread-safety when parallel steps will be supported.
-            #
             def stubbed_results
-              return Support::Cache.new unless Support::Gems::RSpec.current_example
-
               ##
-              # IMPORTANT: ivar name with class and current thread enforces thread safety since there is no resource to share.
-              #
-              # TODO: Thread safety specs.
-              #
               # NOTE: `self` is a service class in the current context. For example:
               #
               #   before do
@@ -37,9 +42,12 @@ module ConvenientService
               #
               #   # Then `self` is `ConvenientService::Examples::Standard::Gemfile::Services::RunShell`.
               #
-              ivar_name = "@__convenient_service_stubbed_results__#{object_id}__#{Thread.current.object_id}__"
-
-              cache = Utils::Object.instance_variable_fetch(::RSpec.current_example, ivar_name) { Support::Cache.new }
+              cache =
+                if Support::Gems::RSpec.current_example
+                  Utils::Object.instance_variable_fetch(Support::Gems::RSpec.current_example, :@__convenient_service_stubbed_results__) { Support::Cache.new }
+                else
+                  Support::Cache.new
+                end
 
               cache.scope(self)
             end

data/lib/convenient_service/service/plugins/can_have_stubbed_result/middleware.rb

@@ -6,9 +6,9 @@ module ConvenientService
       module CanHaveStubbedResult
         class Middleware < Core::MethodChainMiddleware
           ##
-          # @param args [Array]
-          # @param kwargs [Hash]
-          # @param block [Proc]
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
+          # @param block [Proc, nil]
           # @return [Object] Can be any type.
           #
           def next(*args, **kwargs, &block)

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

@@ -16,7 +16,7 @@ module ConvenientService
 
             ##
             # @api public
-            # @param kwargs [Hash]
+            # @param kwargs [Hash{Symbol => Object}]
             # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
             #
             def success(**kwargs)
@@ -25,7 +25,7 @@ module ConvenientService
 
             ##
             # @api public
-            # @param kwargs [Hash]
+            # @param kwargs [Hash{Symbol => Object}]
             # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
             #
             def failure(**kwargs)
@@ -34,7 +34,7 @@ module ConvenientService
 
             ##
             # @api public
-            # @param kwargs [Hash]
+            # @param kwargs [Hash{Symbol => Object}]
             # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
             #
             def error(**kwargs)

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Plugins
+    Result = ::ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins
+  end
+end

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

@@ -16,11 +16,12 @@ module ConvenientService
                     # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result, nil]
                     #
                     def parent
-                      @parent ||= internals.cache[:parent]
+                      Utils::Object.memoize_including_falsy_values(self, :@parent) { internals.cache[:parent] }
                     end
 
                     ##
                     # @param include_self [Boolean]
+                    # @param limit [Integer]
                     # @return [Array<ConvenientService::Service::Plugins::HasResult::Entities::Result>]
                     #
                     # @internal
@@ -46,17 +47,18 @@ module ConvenientService
                     #     parents
                     #   end
                     #
-                    def parents(include_self: false)
-                      parents_enum(include_self: include_self).to_a
+                    def parents(include_self: false, limit: Constants::PARENTS_LIMIT)
+                      parents_enum(include_self: include_self, limit: limit).to_a
                     end
 
                     ##
                     # @param include_self [Boolean]
+                    # @param limit [Integer]
                     # @return [Enumerator<ConvenientService::Service::Plugins::HasResult::Entities::Result>]
                     #
                     # @see https://ruby-doc.org/core-2.7.0/Enumerator.html
                     #
-                    def parents_enum(include_self: false)
+                    def parents_enum(include_self: false, limit: Constants::PARENTS_LIMIT)
                       ::Enumerator.new do |yielder|
                         yielder.yield(self) if include_self
 
@@ -66,7 +68,12 @@ module ConvenientService
                         #
                         parent = parent()
 
-                        while parent
+                        ##
+                        # NOTE: `finite_loop` is used to avoid even a theoretical infinite loop.
+                        #
+                        Support::FiniteLoop.finite_loop(max_iteration_count: limit, raise_on_exceedance: false) do
+                          break unless parent
+
                           yielder.yield(parent)
 
                           parent = parent.parent

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/{has_jsend_status_and_attributes/concern/class_methods.rb → can_have_parent_result/constants.rb}

@@ -7,10 +7,9 @@ module ConvenientService
         module Entities
           class Result
             module Plugins
-              module HasJsendStatusAndAttributes
-                module Concern
-                  module ClassMethods
-                  end
+              module CanHaveParentResult
+                module Constants
+                  PARENTS_LIMIT = 1_000
                 end
               end
             end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "can_have_parent_result/concern"
+require_relative "can_have_parent_result/constants"
 require_relative "can_have_parent_result/initialize"
 require_relative "can_have_parent_result/to_kwargs"

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/{has_jsend_status_and_attributes/commands/cast_jsend_attributes.rb → has_j_send_status_and_attributes/commands/cast_j_send_attributes.rb}

@@ -7,7 +7,7 @@ module ConvenientService
         module Entities
           class Result
             module Plugins
-              module HasJsendStatusAndAttributes
+              module HasJSendStatusAndAttributes
                 module Commands
                   class CastJSendAttributes < Support::Command
                     attr_reader :attributes

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Commands
+                  class CreateCodeClass < Support::Command
+                    include Support::DependencyContainer::Import
+
+                    ##
+                    # @!attribute [r] result_class
+                    #   @return Class
+                    #
+                    attr_reader :result_class
+
+                    ##
+                    # @return Class
+                    #
+                    import :"commands.FindOrCreateEntity", from: Common::Plugins::CanHaveUserProvidedEntity::Container
+
+                    ##
+                    # @param result_class [Class]
+                    # @return [void]
+                    #
+                    def initialize(result_class:)
+                      @result_class = result_class
+                    end
+
+                    ##
+                    # @return [Class]
+                    #
+                    def call
+                      commands.FindOrCreateEntity.call(namespace: result_class, proto_entity: Entities::Code)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Commands
+                  class CreateDataClass < Support::Command
+                    include Support::DependencyContainer::Import
+
+                    ##
+                    # @!attribute [r] result_class
+                    #   @return Class
+                    #
+                    attr_reader :result_class
+
+                    ##
+                    # @return Class
+                    #
+                    import :"commands.FindOrCreateEntity", from: Common::Plugins::CanHaveUserProvidedEntity::Container
+
+                    ##
+                    # @param result_class [Class]
+                    # @return [void]
+                    #
+                    def initialize(result_class:)
+                      @result_class = result_class
+                    end
+
+                    ##
+                    # @return [Class]
+                    #
+                    def call
+                      commands.FindOrCreateEntity.call(namespace: result_class, proto_entity: Entities::Data)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Commands
+                  class CreateMessageClass < Support::Command
+                    include Support::DependencyContainer::Import
+
+                    ##
+                    # @!attribute [r] result_class
+                    #   @return Class
+                    #
+                    attr_reader :result_class
+
+                    ##
+                    # @return Class
+                    #
+                    import :"commands.FindOrCreateEntity", from: Common::Plugins::CanHaveUserProvidedEntity::Container
+
+                    ##
+                    # @param result_class [Class]
+                    # @return [void]
+                    #
+                    def initialize(result_class:)
+                      @result_class = result_class
+                    end
+
+                    ##
+                    # @return [Class]
+                    #
+                    def call
+                      commands.FindOrCreateEntity.call(namespace: result_class, proto_entity: Entities::Message)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Commands
+                  class CreateStatusClass < Support::Command
+                    include Support::DependencyContainer::Import
+
+                    ##
+                    # @!attribute [r] result_class
+                    #   @return Class
+                    #
+                    attr_reader :result_class
+
+                    ##
+                    # @return Class
+                    #
+                    import :"commands.FindOrCreateEntity", from: Common::Plugins::CanHaveUserProvidedEntity::Container
+
+                    ##
+                    # @param result_class [Class]
+                    # @return [void]
+                    #
+                    def initialize(result_class:)
+                      @result_class = result_class
+                    end
+
+                    ##
+                    # @return [Class]
+                    #
+                    def call
+                      commands.FindOrCreateEntity.call(namespace: result_class, proto_entity: Entities::Status)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "commands/cast_j_send_attributes"
+require_relative "commands/create_code_class"
+require_relative "commands/create_data_class"
+require_relative "commands/create_message_class"
+require_relative "commands/create_status_class"

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Concern
+                  module ClassMethods
+                    ##
+                    # @api private
+                    # @return [Class]
+                    #
+                    # @internal
+                    #   NOTE: A command instead of `import` is used in order to NOT pollute the public interface.
+                    #   TODO: Specs that prevent public interface accidental pollution.
+                    #
+                    def code_class
+                      @code_class ||= Commands::CreateCodeClass.call(result_class: self)
+                    end
+
+                    ##
+                    # @api private
+                    # @return [Class]
+                    #
+                    # @internal
+                    #   NOTE: A command instead of `import` is used in order to NOT pollute the public interface.
+                    #   TODO: Specs that prevent public interface accidental pollution.
+                    #
+                    def data_class
+                      @data_class ||= Commands::CreateDataClass.call(result_class: self)
+                    end
+
+                    ##
+                    # @api private
+                    # @return [Class]
+                    #
+                    # @internal
+                    #   NOTE: A command instead of `import` is used in order to NOT pollute the public interface.
+                    #   TODO: Specs that prevent public interface accidental pollution.
+                    #
+                    def message_class
+                      @message_class ||= Commands::CreateMessageClass.call(result_class: self)
+                    end
+
+                    ##
+                    # @api private
+                    # @return [Class]
+                    #
+                    # @internal
+                    #   NOTE: A command instead of `import` is used in order to NOT pollute the public interface.
+                    #   TODO: Specs that prevent public interface accidental pollution.
+                    #
+                    def status_class
+                      @status_class ||= Commands::CreateStatusClass.call(result_class: self)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end