convenient_service 0.20.0 → 0.21.0

data/lib/convenient_service/support/unique_value.rb

@@ -54,10 +54,13 @@ module ConvenientService
       #   - https://github.com/ruby/ruby/blob/v3_3_0/hash.c#L3719
       #   - https://belighted.com/blog/overriding-equals-equals
       #
+      #   NOTE: Avoid comparing object ids. Prefer `equal?`.
+      #   - https://bugs.ruby-lang.org/issues/15408
+      #
       def eql?(other)
         return unless other.instance_of?(self.class)
 
-        object_id == other.object_id
+        equal?(other)
       end
 
       ##

data/lib/convenient_service/support.rb

@@ -30,3 +30,16 @@ require_relative "support/middleware"
 require_relative "support/raw_value"
 require_relative "support/safe_method"
 require_relative "support/thread_safe_counter"
+
+module ConvenientService
+  ##
+  # Namespace for Convenient Service utilities that can NOT be expressed as "functions".
+  #
+  # @api private
+  # @since 1.0.0
+  # @note Utilities from the `Support` module are NOT expected to be used by the end-users directly, but they still may interact with them when the `Support` instances are returned from the Convenient Service public methods.
+  # @note Plugin developers usually can rely on the `Support` module, but it is always a good idea to open an issue with the corresponding usage example. This way, the custom plugin may be added to the CI pipeline. So that any breaking change is caught before the new Convenient Service release.
+  #
+  module Support
+  end
+end

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

@@ -31,16 +31,25 @@ module ConvenientService
           @block = block
         end
 
-        ##
-        # @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_each { |item| return item if block.call(item) }
+        if Dependencies.ruby.version >= 4.0
+          ##
+          # @return [Object] Can be any type.
+          #
+          # @note Does NOT work with custom `Enumerable` objects.
+          # @note Use `ConvenientService::Utils::Enumerable.find_last` for custom enumerables.
+          #
+          def call
+            array.rfind(&block)
+          end
+        else
+          ##
+          # @return [Object] Can be any type.
+          #
+          def call
+            array.reverse_each { |item| return item if block.call(item) }
 
-          nil
+            nil
+          end
         end
       end
     end

data/lib/convenient_service/utils/class/display_name.rb

@@ -5,18 +5,18 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example Usual class.
-#   ConvenientService::Utils::Class::DisplayName.call(String)
-#   # => "String"
-#
-# @example Anonymous class.
-#   ConvenientService::Utils::Class::DisplayName.call(Сlass.new)
-#   # => "AnonymousClass(#76940)"
-#
 module ConvenientService
   module Utils
     module Class
+      ##
+      # @example Usual class.
+      #   ConvenientService::Utils::Class::DisplayName.call(String)
+      #   # => "String"
+      #
+      # @example Anonymous class.
+      #   ConvenientService::Utils::Class::DisplayName.call(Сlass.new)
+      #   # => "AnonymousClass(#76940)"
+      #
       class DisplayName < Support::Command
         ##
         # @api private

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Utils
+    module Enumerable
+      class FindLast < Support::Command
+        ##
+        # @!attribute [r] enumerable
+        #   @return [Enumerable]
+        #
+        attr_reader :enumerable
+
+        ##
+        # @!attribute [r] block
+        #   @return [Proc]
+        #
+        attr_reader :block
+
+        ##
+        # @param enumerable [Enumerable]
+        # @param block [Proc, nil]
+        # @return [void]
+        #
+        def initialize(enumerable, &block)
+          @enumerable = enumerable
+          @block = block
+        end
+
+        ##
+        # @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
+          enumerable.reverse_each { |item| return item if block.call(item) }
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/enumerable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "enumerable/find_last"
+
+module ConvenientService
+  module Utils
+    module Enumerable
+      class << self
+        def find_last(...)
+          FindLast.call(...)
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/hash/assert_valid_keys.rb

@@ -5,13 +5,13 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example
-#   ConvenientService::Utils::Hash::AssertValidKeys.call({foo: "foo", bar: "bar"}, [:foo, :bar])
-#
 module ConvenientService
   module Utils
     module Hash
+      ##
+      # @example Common usage.
+      #   ConvenientService::Utils::Hash::AssertValidKeys.call({foo: "foo", bar: "bar"}, [:foo, :bar])
+      #
       class AssertValidKeys < Support::Command
         ##
         # @!attribute [r] hash

data/lib/convenient_service/utils/hash/except.rb

@@ -5,13 +5,14 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example
-#   ConvenientService::Utils::Hash::Except.call({foo: :bar, baz: :qux}, [:foo])
-#
 module ConvenientService
   module Utils
     module Hash
+      ##
+      # @example Common usage.
+      #   ConvenientService::Utils::Hash::Except.call({foo: :bar, baz: :qux}, [:foo])
+      #   # => {baz: :qux}
+      #
       class Except < Support::Command
         ##
         # @!attribute [r] hash

data/lib/convenient_service/utils/hash/triple_equality_compare.rb

@@ -5,17 +5,17 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example
-#   {foo: (1..10), bar: /abc/} == {foo: 5, bar: :abc}
-#   # => false, since values are compared by `#==` under the hood.
-#
-#   ConvenientService::Utils::Hash::TripleEqualityCompare.call({foo: (1..10), bar: /abc/}, {foo: 5, bar: :abc})
-#   # => true, since values are compared by `#===` under the hood.
-#
 module ConvenientService
   module Utils
     module Hash
+      ##
+      # @example Common usage.
+      #   {foo: (1..10), bar: /abc/} == {foo: 5, bar: :abc}
+      #   # => false, since values are compared by `#==` under the hood.
+      #
+      #   ConvenientService::Utils::Hash::TripleEqualityCompare.call({foo: (1..10), bar: /abc/}, {foo: 5, bar: :abc})
+      #   # => true, since values are compared by `#===` under the hood.
+      #
       class TripleEqualityCompare < Support::Command
         ##
         # @!attribute [r] hash

data/lib/convenient_service/utils/kernel/silence_warnings.rb

@@ -5,13 +5,13 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example
-#   ConvenientService::Utils::Kernel::SilenceWarnings.call { String = String }
-#
 module ConvenientService
   module Utils
     module Kernel
+      ##
+      # @example Common usage.
+      #   ConvenientService::Utils::Kernel::SilenceWarnings.call { String = String }
+      #
       class SilenceWarnings < Support::Command
         ##
         # @!attribute [r] block

data/lib/convenient_service/utils/module/fetch_own_const.rb

@@ -5,40 +5,45 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example Two args form (works as GetOwnConst).
-#   module Test
-#   end
-#
-#   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File)
-#   # => nil, not File from Ruby Core.
-#
-#   module Test
-#     class File
-#     end
-#   end
-#
-#   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File)
-#   # => Test::File
-#
-# @example Two args + block form.
-#   module Test
-#   end
-#
-#   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File) { Class.new }
-#   # => Test::File, just created.
-#
-#   module Test
-#     class File
-#     end
-#   end
-#
-#   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File)
-#   # => Test::File, already existing.
-#
 module ConvenientService
   module Utils
     module Module
+      ##
+      # Returns a constant that is defined directly in module or defines it there.
+      #
+      # @api private
+      # @since 1.0.0
+      #
+      # @example Two args form (works as GetOwnConst).
+      #   module Test
+      #   end
+      #
+      #   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File)
+      #   # => nil, not File from Ruby Core.
+      #
+      #   module Test
+      #     class File
+      #     end
+      #   end
+      #
+      #   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File)
+      #   # => Test::File
+      #
+      # @example Two args + block form.
+      #   module Test
+      #   end
+      #
+      #   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File) { Class.new }
+      #   # => Test::File, just created.
+      #
+      #   module Test
+      #     class File
+      #     end
+      #   end
+      #
+      #   ConvenientService::Utils::Module::FetchOwnConst.call(Test, :File)
+      #   # => Test::File, already existing.
+      #
       class FetchOwnConst < Support::Command
         ##
         # @!attribute [r] mod

data/lib/convenient_service/utils/module/get_namespace.rb

@@ -5,30 +5,35 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example
-#   module Foo
-#     module Bar
-#       class Baz
-#       end
-#     end
-#   end
-#
-#   ConvenientService::Utils::Module::GetNamespace.call(Foo)
-#   # => nil
-#
-#   ConvenientService::Utils::Module::GetNamespace.call(Foo::Bar)
-#   # => Foo
-#
-#   ConvenientService::Utils::Module::GetNamespace.call(Foo::Bar::Baz)
-#   # => Foo::Bar
-#
-#   ConvenientService::Utils::Module::GetNamespace.call(Module.new)
-#   # => nil
-#
 module ConvenientService
   module Utils
     module Module
+      ##
+      # Returns parent namespace of class or module.
+      #
+      # @api private
+      # @since 1.0.0
+      #
+      # @example Common usage.
+      #   module Foo
+      #     module Bar
+      #       class Baz
+      #       end
+      #     end
+      #   end
+      #
+      #   ConvenientService::Utils::Module::GetNamespace.call(Foo)
+      #   # => nil
+      #
+      #   ConvenientService::Utils::Module::GetNamespace.call(Foo::Bar)
+      #   # => Foo
+      #
+      #   ConvenientService::Utils::Module::GetNamespace.call(Foo::Bar::Baz)
+      #   # => Foo::Bar
+      #
+      #   ConvenientService::Utils::Module::GetNamespace.call(Module.new)
+      #   # => nil
+      #
       class GetNamespace < Support::Command
         ##
         # @!attribute [r] mod

data/lib/convenient_service/utils/module/get_own_const.rb

@@ -5,25 +5,30 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# @example
-#   module Test
-#   end
-#
-#   ConvenientService::Utils::Module::GetOwnConst.call(Test, :File)
-#   # => nil, not File from Ruby Core.
-#
-#   module Test
-#     class File
-#     end
-#   end
-#
-#   ConvenientService::Utils::Module::GetOwnConst.call(Test, :File)
-#   # => Test::File
-#
 module ConvenientService
   module Utils
     module Module
+      ##
+      # Returns constant defined directly in `mod`.
+      #
+      # @api private
+      # @since 1.0.0
+      #
+      # @example Common usage.
+      #   module Test
+      #   end
+      #
+      #   ConvenientService::Utils::Module::GetOwnConst.call(Test, :File)
+      #   # => nil, not File from Ruby Core.
+      #
+      #   module Test
+      #     class File
+      #     end
+      #   end
+      #
+      #   ConvenientService::Utils::Module::GetOwnConst.call(Test, :File)
+      #   # => Test::File
+      #
       class GetOwnConst < Support::Command
         ##
         # @!attribute [r] mod

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

@@ -5,56 +5,59 @@
 # @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
 ##
 
-##
-# Returns class when `object` is a class, module when `object` is a module or object's class.
-#
-# @example Aloid `if` condition for `ConvenientService::Core::Concern::ClassMethod#middlewares`.
-#
-#   service = Service.new # || Service
-#
-#   if service.is_a?(Module)
-#     service.middlewares(:result)
-#   else
-#     service.class.middelewares(:result)
-#   end
-#
-#   ##
-#   # With `ConvenientService::Utils::Object::clamp_class` it can be rewritten in the followiing way:
-#   #
-#   ConvenientService::Utils::Object::clamp_class(service).middlewares(:result)
-#
-# @example Possible returns values.
-#
-#   module Musician
-#   end
-#
-#   class Person
-#   end
-#
-#   person = Person.new
-#
-#   ConvenientService::Utils::Object::ClampClass.call(42)
-#   # => Integer
-#
-#   ConvenientService::Utils::Object::ClampClass.call("foo")
-#   # => String
-#
-#   ConvenientService::Utils::Object::ClampClass.call(person)
-#   # => Person
-#
-#   ConvenientService::Utils::Object::ClampClass.call(Person)
-#   # => Person
-#
-#   ConvenientService::Utils::Object::ClampClass.call(Musician)
-#   # => Musician
-#
-# @note Name is inspired by `Comparable#clamp`.
-#
-# @see https://ruby-doc.org/core-2.7.0/Comparable.html#method-i-clamp
-#
 module ConvenientService
   module Utils
     module Object
+      ##
+      # Returns class when `object` is a class, module when `object` is a module or object's class.
+      #
+      # @api private
+      # @since 1.0.0
+      #
+      # @example Aloid `if` condition for `ConvenientService::Core::Concern::ClassMethod#middlewares`.
+      #
+      #   service = Service.new # || Service
+      #
+      #   if service.is_a?(Module)
+      #     service.middlewares(:result)
+      #   else
+      #     service.class.middelewares(:result)
+      #   end
+      #
+      #   ##
+      #   # With `ConvenientService::Utils::Object::clamp_class` it can be rewritten in the followiing way:
+      #   #
+      #   ConvenientService::Utils::Object::clamp_class(service).middlewares(:result)
+      #
+      # @example Possible returns values.
+      #
+      #   module Musician
+      #   end
+      #
+      #   class Person
+      #   end
+      #
+      #   person = Person.new
+      #
+      #   ConvenientService::Utils::Object::ClampClass.call(42)
+      #   # => Integer
+      #
+      #   ConvenientService::Utils::Object::ClampClass.call("foo")
+      #   # => String
+      #
+      #   ConvenientService::Utils::Object::ClampClass.call(person)
+      #   # => Person
+      #
+      #   ConvenientService::Utils::Object::ClampClass.call(Person)
+      #   # => Person
+      #
+      #   ConvenientService::Utils::Object::ClampClass.call(Musician)
+      #   # => Musician
+      #
+      # @note Name is inspired by `Comparable#clamp`.
+      #
+      # @see https://ruby-doc.org/core-2.7.0/Comparable.html#method-i-clamp
+      #
       class ClampClass < Support::Command
         ##
         # @!attribute [r] object