convenient_service 0.19.0 → 0.20.0

data/lib/convenient_service/support/middleware/stack_builder.rb

@@ -1,113 +1,45 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+require_relative "stack_builder/constants"
+require_relative "stack_builder/entities"
+require_relative "stack_builder/exceptions"
+
 module ConvenientService
   module Support
     module Middleware
-      ##
-      # @internal
-      #   TODO: Contribute.
-      #
-      #   NOTE: Minimal `ibsciss-middleware` version - `0.4.2`.
-      #   https://github.com/marian13/ruby-middleware/tree/v0.4.2
-      #
-      class StackBuilder < Dependencies::Extractions::RubyMiddleware::Middleware::Builder
-        ##
-        # @param opts [Hash]
-        # @param block [Proc, nil]
-        # @return [void]
-        #
-        # @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
-
+      class StackBuilder
+        class << self
           ##
-          # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L174
+          # @return [ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::RubyMiddleware, ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Rack, ConvenientService::Support::Middleware::StackBuilder::Entities::Builders::Stateful]
           #
-          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
+          def new(...)
+            backed_by(Constants::Backends::DEFAULT).new(...)
+          end
 
-        ##
-        # @param other [ConvenientService::Support::Middleware::StackBuilder, Object]
-        # @return [Boolean, nil]
-        #
-        # @internal
-        #   TODO: Direct specs.
-        #
-        def ==(other)
-          return unless other.instance_of?(self.class)
-
-          return false if name != other.name
-          return false if stack != other.stack
-
-          true
-        end
-
-        ##
-        # @return [Array]
-        #
-        # @internal
-        #   NOTE: `use` can accept additional arguments and block, that is why `stack` contains tuples like [middleware, args, block].
-        #   https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L76
-        #
-        #   TODO: better name than just `to_a`.
-        #
-        def to_a
-          stack
-        end
-
-        ##
-        # @return [ConvenientService::Support::Middleware::StackBuilder]
-        #
-        # @internal
-        #   TODO: Direct specs.
-        #
-        def dup
-          self.class.new(
-            ##
-            # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L45
-            #
-            runner_class: @runner_class,
-            ##
-            # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L46
-            #
-            name: @middleware_name.dup,
-            ##
-            # https://github.com/marian13/ruby-middleware/blob/v0.4.2/lib/middleware/builder.rb#L167
-            #
-            stack: stack.dup
-          )
+          ##
+          # @param backend [Symbol]
+          # @return [Class]
+          # @raise [ConvenientService::Support::Middleware::StackBuilder::Exceptions::NotSupportedBackend]
+          #
+          def backed_by(backend)
+            case backend
+            when Constants::Backends::RUBY_MIDDLEWARE
+              Entities::Builders::RubyMiddleware
+            when Constants::Backends::RACK
+              Entities::Builders::Rack
+            when Constants::Backends::STATEFUL
+              Entities::Builders::Stateful
+            when Constants::Backends::NAIVE
+              Entities::Builders::Naive
+            else
+              ::ConvenientService.raise Exceptions::NotSupportedBackend.new(backend: backend)
+            end
+          end
         end
       end
     end

data/lib/convenient_service/support/middleware.rb

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "middleware/stack_builder"

data/lib/convenient_service/support/never_reach_here.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class NeverReachHere < ::ConvenientService::Exception

data/lib/convenient_service/support/not_passed.rb

@@ -1,10 +1,25 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
+    class NotPassed < Support::UniqueValue
+      ##
+      # @param value [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def [](value)
+        equal?(value)
+      end
+    end
+
     ##
     # @return [ConvenientService::Support::UniqueValue]
     #
-    NOT_PASSED = Support::UniqueValue.new("not_passed")
+    NOT_PASSED = Support::NotPassed.new("not_passed")
   end
 end

data/lib/convenient_service/support/raw_value.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class RawValue

data/lib/convenient_service/support/safe_method.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class SafeMethod

data/lib/convenient_service/support/thread_safe_counter.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     ##

data/lib/convenient_service/support/undefined.rb

@@ -1,10 +1,25 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
+    class Undefined < Support::UniqueValue
+      ##
+      # @param value [Object] Can be any type.
+      # @return [Boolean]
+      #
+      def [](value)
+        equal?(value)
+      end
+    end
+
     ##
     # @return [ConvenientService::Support::UniqueValue]
     #
-    UNDEFINED = Support::UniqueValue.new("undefined")
+    UNDEFINED = Support::Undefined.new("undefined")
   end
 end

data/lib/convenient_service/support/unique_value.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class UniqueValue
@@ -19,20 +24,21 @@ module ConvenientService
 
       ##
       # @param other [Object] Can be any type.
-      # @return [Boolean]
+      # @return [Boolean, nil]
       #
       # @internal
-      #   NOTE: Every single Ruby object responds to `object_id`.
+      #   NOTE: The `equal?` method should never be overridden by subclasses as it is used to determine object identity (that is, `a.equal?(b)` if and only if `a` is the same object as `b`).
+      #   - https://ruby-doc.org/core-2.7.2/BasicObject.html#method-i-equal-3F
       #
       def ==(other)
         return unless other.instance_of?(self.class)
 
-        object_id == other.object_id
+        equal?(other)
       end
 
       ##
       # @param other [Object] Can be any type.
-      # @return [Boolean]
+      # @return [Boolean, nil]
       #
       def ===(other)
         self == other
@@ -40,13 +46,29 @@ module ConvenientService
 
       ##
       # @param other [Object] Can be any type.
-      # @return [Boolean]
+      # @return [Boolean, nil]
       #
       # @internal
-      #   TODO: What to do in case unique value is used as hash key? See `ConveninetService::Support::Cache::Entities::Key`.
+      #   IMPORTANT: Do NOT delegate to `==` from `eql?`. When user overrides `==` then it can break `eql?`.
+      #   - https://shopify.engineering/implementing-equality-in-ruby
+      #   - https://github.com/ruby/ruby/blob/v3_3_0/hash.c#L3719
+      #   - https://belighted.com/blog/overriding-equals-equals
       #
       def eql?(other)
-        self == other
+        return unless other.instance_of?(self.class)
+
+        object_id == other.object_id
+      end
+
+      ##
+      # @return [Integer]
+      #
+      # @internal
+      #   NOTE: Common way to implement hash.
+      #   - https://shopify.engineering/implementing-equality-in-ruby
+      #
+      def hash
+        [self.class, label].hash
       end
 
       ##

data/lib/convenient_service/support/value.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 module ConvenientService
   module Support
     class Value
@@ -19,7 +24,7 @@ module ConvenientService
 
       ##
       # @param other [Object] Can be any type.
-      # @return [Boolean]
+      # @return [Boolean, nil]
       #
       def ==(other)
         return unless other.instance_of?(self.class)
@@ -29,7 +34,7 @@ module ConvenientService
 
       ##
       # @param other [Object] Can be any type.
-      # @return [Boolean]
+      # @return [Boolean, nil]
       #
       def ===(other)
         self == other
@@ -37,22 +42,29 @@ module ConvenientService
 
       ##
       # @param other [Object] Can be any type.
-      # @return [Boolean]
+      # @return [Boolean, nil]
+      #
+      # @internal
+      #   IMPORTANT: Do NOT delegate to `==` from `eql?`. When user overrides `==` then it can break `eql?`.
+      #   - https://shopify.engineering/implementing-equality-in-ruby
+      #   - https://github.com/ruby/ruby/blob/v3_3_0/hash.c#L3719
+      #   - https://belighted.com/blog/overriding-equals-equals
       #
       def eql?(other)
         return unless other.instance_of?(self.class)
 
-        hash == other.hash
+        label == other.label
       end
 
       ##
       # @return [Integer]
       #
       # @internal
-      #   IMPORTANT: What to do with collisions?
+      #   NOTE: Common way to implement hash.
+      #   - https://shopify.engineering/implementing-equality-in-ruby
       #
       def hash
-        label.hash
+        [self.class, label].hash
       end
 
       ##

data/lib/convenient_service/support.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "support/value"
 require_relative "support/unique_value"
 

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

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

@@ -1,5 +1,10 @@
 # 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 Array

data/lib/convenient_service/utils/array.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "array/exceptions"
 
 require_relative "array/contain_exactly"

data/lib/convenient_service/utils/bool/to_bool.rb

@@ -1,5 +1,10 @@
 # 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 Bool

data/lib/convenient_service/utils/bool.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "bool/to_bool"
 
 module ConvenientService

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

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 ##
 # @example Usual class.
 #   ConvenientService::Utils::Class::DisplayName.call(String)

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+##
+# @note This util is only available for Ruby 3.2+. There are no reliable and performant backports for older Rubies.
+#
+# @see https://github.com/marcandre/backports/blob/v3.25.0/lib/backports/3.2.0/class/attached_object.rb#L7
+# @see https://github.com/panorama-ed/memo_wise/blob/v1.9.0/lib/memo_wise/internal_api.rb#L222
+# @see https://bugs.ruby-lang.org/issues/12084
+# @see https://stackoverflow.com/questions/54531270/retrieve-a-ruby-object-from-its-singleton-class
+#
+# @example Usual class.
+#   ConvenientService::Utils::Class::GetAttachedObject.call(String)
+#   # => nil
+#
+# @example Singleton class.
+#   ConvenientService::Utils::Class::GetAttachedObject.call(String.singleton_class)
+#   # => String
+#
+# @example Usual module.
+#   ConvenientService::Utils::Class::GetAttachedObject.call(Kernel)
+#   # => nil
+#
+# @example Singleton module.
+#   ConvenientService::Utils::Class::GetAttachedObject.call(Kernel.singleton_class)
+#   # => Kernel
+#
+# @example Usual instance.
+#   ConvenientService::Utils::Class::GetAttachedObject.call("abc")
+#   # => nil
+#
+# @example Singleton instance.
+#   ConvenientService::Utils::Class::GetAttachedObject.call("abc".singleton_class)
+#   # => "abc"
+#
+return if ConvenientService::Dependencies.ruby.version < 3.2
+
+module ConvenientService
+  module Utils
+    module Class
+      class GetAttachedObject < Support::Command
+        ##
+        # @api private
+        #
+        # @!attribute [r] klass
+        #   @return [Class]
+        #
+        attr_reader :klass
+
+        ##
+        # @api private
+        #
+        # @param klass [Class]
+        # @return [void]
+        #
+        def initialize(klass)
+          @klass = klass
+        end
+
+        ##
+        # @api private
+        #
+        # @return [Class, nil]
+        #
+        def call
+          return unless klass
+          return unless klass.is_a?(::Module)
+          return unless klass.singleton_class?
+
+          klass.attached_object
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/utils/class.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "class/display_name"
+require_relative "class/get_attached_object"
 
 module ConvenientService
   module Utils
@@ -14,6 +20,15 @@ module ConvenientService
         def display_name(...)
           DisplayName.call(...)
         end
+
+        ##
+        # @api private
+        #
+        # @return [Class, nil]
+        #
+        def attached_object(...)
+          GetAttachedObject.call(...)
+        end
       end
     end
   end