convenient_service 0.18.0 → 0.19.0

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.rb

@@ -2,12 +2,14 @@
 
 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_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/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.rb

@@ -2,7 +2,7 @@
 
 ##
 # @internal
-#   NOTE: Order matters.
+#   NOTE: Some plugins are order-dependent.
 #
 require_relative "plugins/has_result"
 require_relative "plugins/has_negated_result"
@@ -18,8 +18,10 @@ require_relative "plugins/can_recalculate_result"
 require_relative "plugins/can_have_method_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"

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/middleware/stack_builder.rb

@@ -18,6 +18,9 @@ module ConvenientService
         #
         # @see https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L43
         #
+        # @internal
+        #   TODO: Direct specs.
+        #
         def initialize(opts = {}, &block)
           super
 
@@ -27,10 +30,41 @@ module ConvenientService
           self.stack = opts[:stack] if opts.has_key?(:stack)
         end
 
+        ##
+        # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
+        # @param args [Array<Object>]
+        # @param block [Proc, nil]
+        # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+        #
+        # @internal
+        #   TODO: Rewrite middleware backend. Consider to use `Array` descendant?
+        #
+        def unshift(middleware, *args, &block)
+          stack.unshift([middleware, args, block])
+
+          self
+        end
+
+        ##
+        # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+        #
+        alias_method :prepend, :unshift
+
+        ##
+        # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+        #
+        # @internal
+        #   TODO: Direct specs.
+        #
+        alias_method :remove, :delete
+
         ##
         # @param other [ConvenientService::Support::Middleware::StackBuilder, Object]
         # @return [Boolean, nil]
         #
+        # @internal
+        #   TODO: Direct specs.
+        #
         def ==(other)
           return unless other.instance_of?(self.class)
 
@@ -56,6 +90,9 @@ module ConvenientService
         ##
         # @return [ConvenientService::Support::Middleware::StackBuilder]
         #
+        # @internal
+        #   TODO: Direct specs.
+        #
         def dup
           self.class.new(
             ##

data/lib/convenient_service/support/thread_safe_counter.rb

@@ -2,6 +2,7 @@
 
 module ConvenientService
   module Support
+    ##
     # @internal
     #   NOTE: Mutex and Semaphore docs.
     #   - https://ruby-doc.org/core-2.7.0/Mutex.html

data/lib/convenient_service/support.rb

@@ -20,11 +20,8 @@ require_relative "support/counter"
 require_relative "support/delegate"
 require_relative "support/dependency_container"
 require_relative "support/finite_loop"
-require_relative "support/gems"
 require_relative "support/method_parameters"
 require_relative "support/middleware"
 require_relative "support/raw_value"
-require_relative "support/ruby"
 require_relative "support/safe_method"
 require_relative "support/thread_safe_counter"
-require_relative "support/version"

data/lib/convenient_service/utils/object/get_own_method.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Object
+      class GetOwnMethod < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @!attribute [r] method_name
+        #   @return [Symbol, String]
+        #
+        attr_reader :method_name
+
+        ##
+        # @!attribute [r] private
+        #   @return [Boolean]
+        #
+        attr_reader :private
+
+        ##
+        # @param object [Object] Can be any type.
+        # @param method_name [Symbol, String]
+        # @param private [Boolean]
+        #
+        def initialize(object, method_name, private: false)
+          @object = object
+          @method_name = method_name
+          @private = private
+        end
+
+        ##
+        # @return [Class]
+        #
+        # @internal
+        #   NOTE: `own_method.bind(object).call` is logically the same as `own_method.bind_call(object)`.
+        #   - https://ruby-doc.org/core-2.7.1/UnboundMethod.html#method-i-bind_call
+        #   - https://blog.saeloun.com/2019/10/17/ruby-2-7-adds-unboundmethod-bind_call-method.html
+        #
+        def call
+          own_method = Utils::Module.get_own_instance_method(object.class, method_name, private: private)
+
+          return unless own_method
+
+          own_method.bind(object)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/object/safe_send.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Utils
+    module Object
+      ##
+      # Returns `nil` when `object` does NOT respond to `method`.
+      # Otherwise it calls `method` on `object` and returns its value.
+      # If calling `method` on `object` raises an exception, it is rescued and `nil` is returned.
+      # Only `StandardError` exceptions are rescued.
+      # Uses `__send__` under the hood.
+      #
+      # @note `ArgumentError` is `StandardError` descendant, so it is also rescued. It is up to the client code to ensure that valid arguments are passed.
+      # @see https://ruby-doc.org/core-2.7.0/BasicObject.html#method-i-__send__
+      # @see https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to-3F
+      # @see https://ruby-doc.org/core-2.7.0/StandardError.html
+      # @see https://ruby-doc.org/core-2.7.0/ArgumentError.html
+      #
+      class SafeSend < Support::Command
+        ##
+        # @!attribute [r] object
+        #   @return [Object] Can be any type.
+        #
+        attr_reader :object
+
+        ##
+        # @!attribute [r] method
+        #   @return [String, Symbol]
+        #
+        attr_reader :method
+
+        ##
+        # @!attribute [r] args
+        #   @return [Array<Object>]
+        #
+        attr_reader :args
+
+        ##
+        # @!attribute [r] kwargs
+        #   @return [Hash{Symbol => Object}]
+        #
+        attr_reader :kwargs
+
+        ##
+        # @!attribute [r] block
+        #   @return [Proc, nil]
+        #
+        attr_reader :block
+
+        ##
+        # @param object [Object] Can be any type.
+        # @param method [String, Symbol]
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
+        #
+        def initialize(object, method, *args, **kwargs, &block)
+          @object = object
+          @method = method
+          @args = args
+          @kwargs = kwargs
+          @block = block
+        end
+
+        ##
+        # @return [Object] Can be any type.
+        #
+        # @internal
+        #   NOTE: `true` in `respond_to?(method, true)` means to look for protected and private methods as well.
+        #   - https://ruby-doc.org/core-2.7.0/Object.html#method-i-respond_to-3F
+        #
+        def call
+          return unless object.respond_to?(method, true)
+
+          begin
+            object.__send__(method, *args, **kwargs, &block)
+          rescue
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/object.rb

@@ -2,10 +2,12 @@
 
 require_relative "object/clamp_class"
 require_relative "object/duck_class"
+require_relative "object/get_own_method"
 require_relative "object/instance_variable_delete"
 require_relative "object/instance_variable_fetch"
 require_relative "object/memoize_including_falsy_values"
 require_relative "object/resolve_type"
+require_relative "object/safe_send"
 
 module ConvenientService
   module Utils
@@ -53,6 +55,20 @@ module ConvenientService
           MemoizeIncludingFalsyValues.call(...)
         end
 
+        ##
+        # @example
+        #   object = Object.new.tap { |object| object.instance_eval { self.class.attr_reader :foo } }
+        #
+        #   ConvenientService::Utils::Object.own_method(object, :foo)
+        #   # => #<Method: #<Object:0x0000555e524252d8>.foo() ...>
+        #
+        #   ConvenientService::Utils::Object.own_method(object, :puts)
+        #   # => nil
+        #
+        def own_method(...)
+          GetOwnMethod.call(...)
+        end
+
         ##
         # @example
         #   ConvenientService::Utils::Object.resolve_type("foo")
@@ -60,6 +76,14 @@ module ConvenientService
         def resolve_type(...)
           ResolveType.call(...)
         end
+
+        ##
+        # @example
+        #   ConvenientService::Utils::Object.safe_send(object, method, *args, **kwargs, &block)
+        #
+        def safe_send(...)
+          SafeSend.call(...)
+        end
       end
     end
   end

data/lib/convenient_service/utils/string/enclose.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+##
+# @example Common usage.
+#   ConvenientService::Utils::String::Enclose.call("foo", "_")
+#   # => "_foo_"
+#
+#   ConvenientService::Utils::String::Enclose.call("", "_")
+#   # => "_"
+#
+#   ConvenientService::Utils::String::Enclose.call(nil, "_")
+#   # => "_"
+#
+module ConvenientService
+  module Utils
+    module String
+      class Enclose < Support::Command
+        ##
+        # @!attribute [r] string
+        #   @return [String]
+        #
+        attr_reader :string
+
+        ##
+        # @!attribute [r] char
+        #   @return [String]
+        #
+        attr_reader :char
+
+        ##
+        # @param string [String]
+        # @param char [String]
+        # @return [void]
+        #
+        def initialize(string, char)
+          @string = string
+          @char = char
+        end
+
+        ##
+        # @return [String]
+        #
+        def call
+          return char unless string
+          return char if string.empty?
+
+          "#{char}#{string}#{char}"
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/string.rb

@@ -2,6 +2,7 @@
 
 require_relative "string/camelize"
 require_relative "string/demodulize"
+require_relative "string/enclose"
 require_relative "string/split"
 require_relative "string/truncate"
 
@@ -17,6 +18,10 @@ module ConvenientService
           Demodulize.call(...)
         end
 
+        def enclose(...)
+          Enclose.call(...)
+        end
+
         def split(...)
           Split.call(...)
         end

data/lib/convenient_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConvenientService
-  VERSION = "0.18.0"
+  VERSION = "0.19.0"
 end

data/lib/convenient_service.rb

@@ -35,6 +35,12 @@ require_relative "convenient_service/service"
 #
 require_relative "convenient_service/feature"
 
+##
+# @internal
+#   Convenient Service Commands.
+#
+require_relative "convenient_service/commands"
+
 ##
 # @internal
 #   Convenient Service Aliases.
@@ -52,6 +58,62 @@ module ConvenientService
       ::ENV["CONVENIENT_SERVICE_DEBUG"] == "true"
     end
 
+    ##
+    # Checks whether a class is a service class.
+    #
+    # @api public
+    #
+    # @param service_class [Object] Can be any type.
+    # @return [Boolean]
+    #
+    # @example Simple usage.
+    #   class Service
+    #     include ConvenientService::Standard::Config
+    #
+    #     def result
+    #       success
+    #     end
+    #   end
+    #
+    #   ConvenientService.service_class?(Service)
+    #   # => true
+    #
+    #   ConvenientService.service_class?(42)
+    #   # => false
+    #
+    def service_class?(service_class)
+      Commands::IsServiceClass[service_class: service_class]
+    end
+
+    ##
+    # Checks whether an object is a service instance.
+    #
+    # @api public
+    #
+    # @param service [Object] Can be any type.
+    # @return [Boolean]
+    #
+    # @example Simple usage.
+    #   class Service
+    #     include ConvenientService::Standard::Config
+    #
+    #     def result
+    #       success
+    #     end
+    #   end
+    #
+    #   service = Service.new
+    #
+    #   ConvenientService.service?(service)
+    #   # => true
+    #
+    #   ConvenientService.service?(42)
+    #   # => false
+    #
+    def service?(service)
+      Commands::IsService[service: service]
+    end
+
     ##
     # @api public
     #