convenient_service 0.17.0 → 0.19.0

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/helps_to_learn_similarities_with_common_objects/concern/instance_methods.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResult
+        module Entities
+          class Result
+            module Plugins
+              module HelpsToLearnSimilaritiesWithCommonObjects
+                module Concern
+                  module InstanceMethods
+                    ##
+                    # Returns a boolean representation of `result`.
+                    # `success` may be considered as `true`.
+                    # `failure` may be considered as `false`.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [Boolean]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's booleans. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_bool
+                      case status.value
+                      when :success
+                        true
+                      when :failure
+                        false
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :boolean)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns a boolean representation of `result`.
+                    # `success` may be considered as `object`.
+                    # `failure` may be considered as `nil` (or null object).
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [ConvenientService::Support::Value]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_object
+                      case status.value
+                      when :success
+                        Support::Value.new("object")
+                      when :failure
+                        nil
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :object)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns an array representation of `result`.
+                    # `success` may be considered as array with items.
+                    # `failure` may be considered as empty array.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [Array<ConvenientService::Support::Value>]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_a
+                      case status.value
+                      when :success
+                        [Support::Value.new("item")]
+                      when :failure
+                        []
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :array)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns a hash representation of `result`.
+                    # `success` may be considered as hash with items.
+                    # `failure` may be considered as empty hash.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [Hash{ConvenientService::Support::Value => ConvenientService::Support::Value}]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_h
+                      case status.value
+                      when :success
+                        {Support::Value.new("key") => Support::Value.new("value")}
+                      when :failure
+                        {}
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :hash)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+
+                    ##
+                    # Returns a string representation of `result`.
+                    # `success` may be considered as string with content.
+                    # `failure` may be considered as empty string.
+                    # `error` may be considered as `raise exception`.
+                    #
+                    # @api public
+                    # @return [String]
+                    # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Status::Exceptions::ErrorHasNoOtherTypeRepresentation]
+                    #
+                    # @note This method is useful for learning purposes, to show similarities with Ruby's objects. Please, do NOT depend on it in production.
+                    #
+                    # @internal
+                    #   NOTE: When `value` is NOT `:success`, `:failure` or `:error`, then something fatal has happened.
+                    #
+                    def to_s
+                      case status.value
+                      when :success
+                        "string"
+                      when :failure
+                        ""
+                      when :error
+                        raise ::ConvenientService.raise Exceptions::ErrorHasNoOtherTypeRepresentation.new(type: :string)
+                      else
+                        raise ::ConvenientService.raise Support::NeverReachHere.new(extra_message: "Unknown result status `#{status.value}`.")
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/helps_to_learn_similarities_with_common_objects/concern.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "concern/instance_methods"
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResult
+        module Entities
+          class Result
+            module Plugins
+              module HelpsToLearnSimilaritiesWithCommonObjects
+                module Concern
+                  include Support::Concern
+
+                  included do |result_class|
+                    result_class.include InstanceMethods
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/helps_to_learn_similarities_with_common_objects/exceptions.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResult
+        module Entities
+          class Result
+            module Plugins
+              module HelpsToLearnSimilaritiesWithCommonObjects
+                module Exceptions
+                  class ErrorHasNoOtherTypeRepresentation < ::ConvenientService::Exception
+                    ##
+                    # @return [void]
+                    #
+                    def initialize_with_kwargs(type:)
+                      message = <<~TEXT
+                        Error results have no `#{type}` representation.
+
+                        They are semantically similar to exceptions.
+                      TEXT
+
+                      initialize(message)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/helps_to_learn_similarities_with_common_objects.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "helps_to_learn_similarities_with_common_objects/concern"
+require_relative "helps_to_learn_similarities_with_common_objects/exceptions"

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/raises_on_not_checked_result_status/middleware.rb

@@ -32,7 +32,7 @@ module ConvenientService
                   # @raise [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result::Plugins::RaisesOnNotCheckedResultStatus::Exceptions::StatusIsNotChecked]
                   #
                   def assert_has_checked_status!
-                    return if entity.internals.cache.exist?(:has_checked_status)
+                    return if entity.checked?
 
                     ::ConvenientService.raise Exceptions::StatusIsNotChecked.new(attribute: method)
                   end

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "plugins/can_recalculate_result"
+require_relative "plugins/has_negated_result"
+require_relative "plugins/can_be_from_exception"
 require_relative "plugins/can_be_own_result"
 require_relative "plugins/can_be_stubbed_result"
 require_relative "plugins/can_have_fallbacks"
 require_relative "plugins/has_j_send_status_and_attributes"
 require_relative "plugins/has_inspect"
 require_relative "plugins/has_stubbed_result_invocations_counter"
+require_relative "plugins/helps_to_learn_similarities_with_common_objects"
 require_relative "plugins/can_have_step"
 require_relative "plugins/can_have_parent_result"
 require_relative "plugins/can_have_checked_status"

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

@@ -5,7 +5,6 @@ require_relative "has_j_send_result/constants"
 require_relative "has_j_send_result/container"
 require_relative "has_j_send_result/commands"
 require_relative "has_j_send_result/entities"
-require_relative "has_j_send_result/exceptions"
 
 module ConvenientService
   module Service

data/lib/convenient_service/service/plugins/has_j_send_result_params_validations/using_dry_validation/middleware.rb

@@ -4,6 +4,10 @@ module ConvenientService
   module Service
     module Plugins
       module HasJSendResultParamsValidations
+        ##
+        # @internal
+        #   TODO: Consider to add versioning, since `dry` gems often modify thier public API.
+        #
         module UsingDryValidation
           class Middleware < MethodChainMiddleware
             intended_for :result, entity: :service

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

@@ -3,13 +3,18 @@
 module ConvenientService
   module Service
     module Plugins
+      ##
+      # @api private
+      #
+      # @note `HasMermaidFlowchart` is experimental. It is NOT decided yet whether its support will be continued. For example, it does NOT work with `or_step`.
+      #
       module HasMermaidFlowchart
         module Concern
           include Support::Concern
 
           class_methods do
             ##
-            # @api public
+            # @api private
             #
             # @return [ConvenientService::Service::Plugins::HasMermaidFlowchart::Entities::Flowchart]
             #

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasNegatedJSendResult
+        module Concern
+          include Support::Concern
+
+          instance_methods do
+            ##
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            # @note Users may override this method to provide custom `negataed_result` behavior.
+            #
+            def negated_result
+              result.negated_result
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasNegatedResult
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            ##
+            # @api public
+            # @raise [ConvenientService::Service::Plugins::HasNegatedResult::Exceptions::NegatedResultIsNotOverridden]
+            #
+            def negated_result(...)
+              new(...).negated_result
+            end
+          end
+
+          instance_methods do
+            ##
+            # @api public
+            # @raise [ConvenientService::Service::Plugins::HasNegatedResult::Exceptions::NegatedResultIsNotOverridden]
+            #
+            def negated_result
+              ::ConvenientService.raise Exceptions::NegatedResultIsNotOverridden.new(service: self)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/{has_j_send_result → has_negated_result}/exceptions.rb

@@ -3,12 +3,12 @@
 module ConvenientService
   module Service
     module Plugins
-      module HasJSendResult
+      module HasNegatedResult
         module Exceptions
-          class ResultIsNotOverridden < ::ConvenientService::Exception
+          class NegatedResultIsNotOverridden < ::ConvenientService::Exception
             def initialize_with_kwargs(service:)
               message = <<~TEXT
-                Result method (#result) of `#{service.class}` is NOT overridden.
+                Negated result method (#negated_result) of `#{service.class}` is NOT overridden.
               TEXT
 
               initialize(message)

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

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "has_negated_result/concern"
+require_relative "has_negated_result/exceptions"

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

@@ -74,6 +74,7 @@ module ConvenientService
               data: {exception: exception},
               message: format_exception(exception, *args, **kwargs, &block)
             )
+              .copy(overrides: {kwargs: {from_exception: true}})
           end
 
           ##

data/lib/convenient_service/service/plugins/{wraps_result_in_db_transaction → wraps_result_in_d_b_transaction}/middleware.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Service
     module Plugins
-      module WrapsResultInDbTransaction
+      module WrapsResultInDBTransaction
         class Middleware < MethodChainMiddleware
           intended_for :result, scope: :class, entity: :service
 

data/lib/convenient_service/service/plugins.rb

@@ -2,18 +2,26 @@
 
 ##
 # @internal
-#   NOTE: Order matters.
+#   NOTE: Some plugins are order-dependent.
 #
 require_relative "plugins/has_result"
+require_relative "plugins/has_negated_result"
+
 require_relative "plugins/has_j_send_result"
+require_relative "plugins/has_negated_j_send_result"
+
+require_relative "plugins/can_have_steps"
+require_relative "plugins/can_have_sequential_steps"
+require_relative "plugins/can_have_connected_steps"
 
 require_relative "plugins/can_recalculate_result"
 require_relative "plugins/can_have_method_steps"
-require_relative "plugins/can_have_steps"
 require_relative "plugins/can_have_stubbed_results"
 require_relative "plugins/can_have_fallbacks"
+require_relative "plugins/can_have_rollbacks"
 require_relative "plugins/collects_services_in_exception"
 require_relative "plugins/counts_stubbed_results_invocations"
+require_relative "plugins/forbids_convenient_service_entities_as_constructor_arguments"
 require_relative "plugins/has_inspect"
 require_relative "plugins/has_j_send_result_short_syntax"
 require_relative "plugins/has_j_send_result_status_check_short_syntax"
@@ -21,6 +29,5 @@ require_relative "plugins/has_mermaid_flowchart"
 require_relative "plugins/raises_on_not_result_return_value"
 require_relative "plugins/raises_on_double_result"
 require_relative "plugins/sets_parent_to_foreign_result"
-require_relative "plugins/wraps_result_in_db_transaction"
 
 require_relative "plugins/aliases"

data/lib/convenient_service/specification.rb

@@ -1,19 +1,47 @@
 # frozen_string_literal: true
 
+##
+# Convenient Service gem specification.
+# @see https://guides.rubygems.org/specification-reference
+#
+# @internal
+#   IMPORTNANT:
+#     This module must NOT be loaded by the `lib` folder.
+#     It is only intended for `gemspec`.
+#     `bundle` loads it inside specs.
+#
 module ConvenientService
   module Specification
+    ##
+    # @return [String]
+    #
     NAME = "convenient_service"
 
+    ##
+    # @return [Array<String>]
+    #
     AUTHORS = ["Marian Kostyk"].freeze
 
+    ##
+    # @return [Array<String>]
+    #
     EMAIL = ["mariankostyk13895@gmail.com"].freeze
 
+    ##
+    # @return [String]
+    #
     HOMEPAGE = "https://github.com/marian13/convenient_service"
 
+    ##
+    # @return [String]
+    #
     SUMMARY = <<~TEXT
       Service object pattern implementation in Ruby.
     TEXT
 
+    ##
+    # @return [String]
+    #
     DESCRIPTION = <<~TEXT
       Yet another approach to revisit the service object pattern in Ruby, but this time focusing on the unique, opinionated, moderately obtrusive, but not mandatory features.
     TEXT

data/lib/convenient_service/support/backtrace_cleaner.rb

@@ -87,7 +87,12 @@ module ConvenientService
       # @return [void]
       #
       def add_convenient_service_silencer
-        add_silencer { |line| line.start_with?(::ConvenientService.root.to_s) && !line.start_with?(::ConvenientService.examples_root.to_s) }
+        add_silencer do |line|
+          next false if line.start_with?(::ConvenientService.examples_root.to_s)
+          next false if line.start_with?(::ConvenientService.spec_root.to_s)
+
+          line.start_with?(::ConvenientService.root.to_s)
+        end
       end
 
       ##

data/lib/convenient_service/support/cache/entities/caches/base.rb

@@ -89,6 +89,9 @@ module ConvenientService
             # @param key [Object] Can be any type.
             # @return [ConvenientService::Support::Cache::Entities::Caches::Base]
             #
+            # @internal
+            #   TODO: What to do if `scope` was called accidentally? Currently, its `key` will NOT be garbage-collected.
+            #
             def scope(key)
               fetch(key) { self.class.new }
             end

data/lib/convenient_service/support/counter.rb

@@ -200,6 +200,8 @@ module ConvenientService
       end
 
       ##
+      # @return [Integer]
+      #
       # @internal
       #   NOTE: Instance variables are accessed directly to release the lock faster.
       #

data/lib/convenient_service/support/method_parameters.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    ##
+    # Wrapps `Method#parameters` return value to provide a higher level interface.
+    #
+    # @note `Method#parameters` return value may look like the following.
+    #
+    #   def foo(a, b = 1, *args, c:, d: 2, **kwargs, &block)
+    #   end
+    #
+    #   method(:foo).parameters
+    #   # => [[:req, :a], [:opt, :b], [:rest, :args], [:keyreq, :c], [:key, :d], [:keyrest, :kwargs], [:block, :block]]
+    #
+    # @see https://ruby-doc.org/core-2.7.1/Method.html#method-i-parameters
+    #
+    class MethodParameters
+      module Constants
+        module Types
+          REQUIRED_KEYWORD = :keyreq
+          OPTIONAL_KEYWORD = :key
+
+          REST_KEYWORDS = :keyrest
+        end
+      end
+
+      ##
+      # @!attribute [r] method_parameters
+      #   @return [Array]
+      #
+      attr_reader :method_parameters
+
+      ##
+      # @param method_parameters [Array]
+      # @return [void]
+      #
+      def initialize(method_parameters)
+        @method_parameters = method_parameters
+      end
+
+      ##
+      # Returns `true` when method definition has `**kwargs`.
+      # @return [Boolean]
+      #
+      # @example `rest_kwargs` means NOT named kwargs.
+      #
+      #   def foo(a, b = 1, *args, c:, d: 2, **kwargs, &block)
+      #   end
+      #
+      #   def bar(a, b = 1, *args, c:, d: 2, &block)
+      #   end
+      #
+      #   ConvenientService::Support::MethodParameters.new(method(:foo).parameters).has_rest_kwargs?
+      #   # => true
+      #
+      #   ConvenientService::Support::MethodParameters.new(method(:bar).parameters).has_rest_kwargs?
+      #   # => false
+      #
+      # @see https://ruby-doc.org/core-2.7.1/Method.html#method-i-parameters
+      #
+      def has_rest_kwargs?
+        return @has_rest_kwargs if defined? @has_rest_kwargs
+
+        @has_rest_kwargs = method_parameters.any? { |type, _name| type == Constants::Types::REST_KEYWORDS }
+      end
+
+      ##
+      # @return [Array<Symbol>]
+      #
+      # @example `named_kwargs_keys` are `kwargs` with or without `defaults`.
+      #
+      #   def foo(a, b = 1, *args, c:, d: 2, **kwargs, &block)
+      #   end
+      #
+      #   ConvenientService::Support::MethodParameters.new(method(:foo).parameters).named_kwargs_keys
+      #   # => [:c, :d]
+      #
+      # @note `named_kwargs_keys` is an optimized way to get `required_kwargs_keys + optional_kwargs_keys`.
+      # @see https://ruby-doc.org/core-2.7.1/Method.html#method-i-parameters
+      #
+      def named_kwargs_keys
+        @named_kwargs_keys ||= method_parameters.select { |type, _name| type == Constants::Types::REQUIRED_KEYWORD || type == Constants::Types::OPTIONAL_KEYWORD }.map { |_type, name| name }
+      end
+
+      ##
+      # @return [Array<Symbol>]
+      #
+      # @note `required_kwargs` are named `kwargs` without `defaults`.
+      #
+      #   def foo(a, b = 1, *args, c:, d: 2, **kwargs, &block)
+      #   end
+      #
+      #   ConvenientService::Support::MethodParameters.new(method(:foo).parameters).required_kwargs_keys
+      #   # => [:c]
+      #
+      # @see https://ruby-doc.org/core-2.7.1/Method.html#method-i-parameters
+      #
+      def required_kwargs_keys
+        @required_kwargs_keys ||= method_parameters.select { |type, _name| type == Constants::Types::REQUIRED_KEYWORD }.map { |_type, name| name }
+      end
+
+      ##
+      # @return [Array<Symbol>]
+      #
+      # @note `optional_kwargs` are named `kwargs` with `defaults`.
+      #
+      #   def foo(a, b = 1, *args, c:, d: 2, **kwargs, &block)
+      #   end
+      #
+      #   ConvenientService::Support::MethodParameters.new(method(:foo).parameters).optional_kwargs_keys
+      #   # => [:d]
+      #
+      # @see https://ruby-doc.org/core-2.7.1/Method.html#method-i-parameters
+      #
+      def optional_kwargs_keys
+        @optional_kwargs_keys ||= method_parameters.select { |type, _name| type == Constants::Types::OPTIONAL_KEYWORD }.map { |_type, name| name }
+      end
+    end
+  end
+end