convenient_service 0.17.0 → 0.18.0

data/lib/convenient_service/service/plugins.rb

@@ -5,11 +5,17 @@
 #   NOTE: Order matters.
 #
 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/collects_services_in_exception"
@@ -21,6 +27,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/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

data/lib/convenient_service/support/never_reach_here.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class NeverReachHere < ::ConvenientService::Exception
+      ##
+      # @param extra_message [String]
+      # @return [void]
+      #
+      def initialize_with_kwargs(extra_message:)
+        message = <<~TEXT
+          The code that was supposed to be unreachable was executed.
+
+          #{extra_message}
+        TEXT
+
+        initialize(message)
+      end
+    end
+  end
+end

data/lib/convenient_service/support/unique_value.rb

@@ -42,6 +42,9 @@ module ConvenientService
       # @param other [Object] Can be any type.
       # @return [Boolean]
       #
+      # @internal
+      #   TODO: What to do in case unique value is used as hash key? See `ConveninetService::Support::Cache::Entities::Key`.
+      #
       def eql?(other)
         self == other
       end

data/lib/convenient_service/support/value.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class Value
+      ##
+      # @!attribute [r] label
+      #   @return [String]
+      #
+      attr_reader :label
+
+      ##
+      # @param label [String]
+      # @return [void]
+      #
+      def initialize(label = default_label)
+        @label = label
+      end
+
+      ##
+      # @param other [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def ==(other)
+        return unless other.instance_of?(self.class)
+
+        label == other.label
+      end
+
+      ##
+      # @param other [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def ===(other)
+        self == other
+      end
+
+      ##
+      # @param other [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def eql?(other)
+        return unless other.instance_of?(self.class)
+
+        hash == other.hash
+      end
+
+      ##
+      # @return [Integer]
+      #
+      # @internal
+      #   IMPORTANT: What to do with collisions?
+      #
+      def hash
+        label.hash
+      end
+
+      ##
+      # @return [String]
+      #
+      def inspect
+        return default_label if label.nil?
+        return default_label if label.empty?
+
+        label
+      end
+
+      private
+
+      ##
+      # @return [String]
+      #
+      def default_label
+        "value"
+      end
+    end
+  end
+end

data/lib/convenient_service/support.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "support/value"
 require_relative "support/unique_value"
 
 require_relative "support/not_passed"
 require_relative "support/undefined"
+require_relative "support/never_reach_here"
 
 require_relative "support/concern"
 
@@ -19,6 +21,7 @@ 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"

data/lib/convenient_service/utils/array/find_last.rb

@@ -6,7 +6,7 @@ module ConvenientService
       class FindLast < Support::Command
         ##
         # @!attribute [r] array
-        #   @return [Array]
+        #   @return [Array, Enumerable]
         #
         attr_reader :array
 
@@ -17,7 +17,7 @@ module ConvenientService
         attr_reader :block
 
         ##
-        # @param array [Array]
+        # @param array [Array, Enumerable]
         # @param block [Proc, nil]
         # @return [void]
         #
@@ -29,8 +29,13 @@ module ConvenientService
         ##
         # @return [Object] Can be any type.
         #
+        # @note Works with custom `Enumerable` objects.
+        # @see https://ruby-doc.org/core-2.7.0/Enumerable.html
+        #
         def call
-          array.reverse.find(&block)
+          array.reverse_each { |item| return item if block.call(item) }
+
+          nil
         end
       end
     end

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

@@ -33,7 +33,7 @@ module ConvenientService
         # @return [Object] Value of ivar. Can be any type.
         #
         def call
-          return object.remove_instance_variable(ivar_name) if object.instance_variable_defined?(ivar_name)
+          object.remove_instance_variable(ivar_name) if object.instance_variable_defined?(ivar_name)
         end
       end
     end

data/lib/convenient_service/version.rb

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

data/lib/convenient_service.rb

@@ -43,6 +43,15 @@ require_relative "convenient_service/aliases"
 
 module ConvenientService
   class << self
+    ##
+    # @api private
+    #
+    # @return [Boolean]
+    #
+    def debug?
+      ::ENV["CONVENIENT_SERVICE_DEBUG"] == "true"
+    end
+
     ##
     # @api public
     #
@@ -79,6 +88,18 @@ module ConvenientService
       @examples_root ||= ::Pathname.new(::File.join(root, "lib", "convenient_service", "examples"))
     end
 
+    ##
+    # Returns Convenient Service Specs folder.
+    # For example, it may return something like: `/Users/user/.asdf/installs/ruby/2.7.0/lib/ruby/gems/2.7.0/gems/convenient_service-0.16.0/spec`.
+    #
+    # @api private
+    #
+    # @return [Pathname]
+    #
+    def spec_root
+      @spec_root ||= ::Pathname.new(::File.join(root, "spec"))
+    end
+
     ##
     # @api public
     #
@@ -105,6 +126,8 @@ module ConvenientService
     #   - https://github.com/jruby/jruby/blob/9.4.0.0/core/src/main/java/org/jruby/RubyKernel.java#L881
     #   - https://github.com/ruby/spec/blob/master/core/kernel/raise_spec.rb#L5
     #
+    #   TODO: Create a custom Rubocop cop to statically catch all places where plain `raise` is used.
+    #
     if Dependencies.ruby.jruby?
       def raise(original_exception)
         ::Kernel.raise original_exception