convenient_service 0.17.0 → 0.19.0

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/chain/concern/instance_methods.rb

@@ -42,12 +42,12 @@ module ConvenientService
                       # @return [Object] Can be any type.
                       #
                       def call(env)
-                        @__env__ = env
+                        @__env__ = Commands::NormalizeEnv.call(env: env)
 
                         ##
                         # IMPORTANT: This is a library code. Do NOT do things like this in your application code.
                         #
-                        chain.instance_variable_set(:@env, env)
+                        chain.instance_variable_set(:@env, @__env__)
 
                         ##
                         # NOTE: `__send__` is used since `next` is ruby keyword.
@@ -55,7 +55,7 @@ module ConvenientService
                         #
                         # TODO: Enforce to always pass args, kwargs, block.
                         #
-                        __send__(:next, *env[:args], **env[:kwargs], &env[:block])
+                        __send__(:next, *@__env__[:args], **@__env__[:kwargs], &@__env__[:block])
                       end
 
                       ##

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/classic.rb

@@ -9,6 +9,20 @@ module ConvenientService
             module Entities
               module Middlewares
                 ##
+                # Class `ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Classic` allows to define middlewares that interacts with `call` and `env` directly.
+                # For example `ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Chain::Commands::NormalizeEnv` was implemeted as middleware up to v0.18.
+                #
+                #   class Middleware < MethodClassicMiddleware
+                #     intended_for any_method, scope: any_scope, entity: any_entity
+                #
+                #     def call(env = nil)
+                #       env = env.to_h
+                #       env = env.merge(args: env[:args].to_a, kwargs: env[:kwargs].to_h, block: env[:block])
+                #
+                #       stack.call(env)
+                #     end
+                #   end
+                #
                 # @abstract Subclass and override `#call`.
                 #
                 # @internal

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/stack.rb

@@ -49,6 +49,23 @@ module ConvenientService
                   plain_stack.call(env)
                 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]
+                #
+                def unshift(middleware, *args, &block)
+                  plain_stack.unshift(middleware, *args, &block)
+
+                  self
+                end
+
+                ##
+                # @return [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Stack]
+                #
+                alias_method :prepend, :unshift
+
                 ##
                 # @param index_or_middleware [Integer, ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
@@ -140,6 +157,11 @@ module ConvenientService
                   self
                 end
 
+                ##
+                # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
+                #
+                alias_method :remove, :delete
+
                 ##
                 # @param middleware [ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Base]
                 # @param args [Array<Object>]

data/lib/convenient_service/core/entities/config/exceptions.rb

@@ -30,6 +30,8 @@ module ConvenientService
             #   TODO: Create a troubleshooting page with possible reasons (preliminary RSpec mocks etc).
             #   Append a link to it to the error message.
             #
+            #   TODO: Add a note of the most common scenario when this issue appears - when the RSpec stub is used before auto config commitment. For example, with `delegate_to`.
+            #
             def initialize_with_kwargs(config:)
               message = <<~TEXT
                 `#{config.klass}` config is committed too many times from `method_missing`.

data/lib/convenient_service/core/entities/config.rb

@@ -142,6 +142,9 @@ module ConvenientService
         # @internal
         #   IMPORTANT: `commit!` MUST be thread safe.
         #
+        #   NOTE: Inspired by `Response#commit!` and others.
+        #   - https://github.com/rails/rails/blob/36c1591bcb5e0ee3084759c7f42a706fe5bb7ca7/actionpack/lib/action_controller/metal/live.rb#L307
+        #
         def commit!(trigger: Constants::Triggers::USER)
           (committed? ? false : concerns.include!)
             .tap { Commands::TrackMethodMissingCommitTrigger.call(config: self, trigger: trigger) }

data/lib/convenient_service/dependencies/built_in.rb

@@ -28,13 +28,6 @@ require "erb"
 #
 require "logger"
 
-##
-# @internal
-#   - https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html
-#   - https://github.com/ruby/observer
-#
-require "observer"
-
 ##
 # @internal
 #   - https://ruby-doc.org/stdlib-2.7.0/libdoc/rubygems/rdoc/Gem/Version.html

data/lib/convenient_service/dependencies/extractions/ds.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+##
+# @api private
+#
+# Defines `ds` helper in order to have a quick way to find differences between strings like `git diff`.
+#
+# @param first_string [String]
+# @param second_string [String]
+# @return [nil]
+#
+# @note `ds' is a dev-only helper.
+# @note `ds` is a short for `diff_strings`.
+#
+# @example
+#   first_string = <<~TEXT
+#     Step of `AnonymousClass(#14360)` is passed as constructor argument `kwargs[:baz]` to `AnonymousClass(#14360)`.
+#
+#     It is an antipattern. It neglects the idea of steps.
+#
+#     Please, try to reorganize `AnonymousClass(#14400)` service.
+#   TEXT
+#
+#   second_string = <<~TEXT
+#     Step of `AnonymousClass(#14360)` is passed as constructor argument `kwargs[:baz]` to `AnonymousClass(#14400)`.
+#
+#     It is an antipattern. It neglects the idea of steps.
+#
+#     Please, try to reorganize `AnonymousClass(#14400)` service.
+#   TEXT
+#
+#   ds(first_string, second_string)
+#   =>
+#   -Step of `AnonymousClass(#14360)` is passed as constructor argument `kwargs[:baz]` to `AnonymousClass(#14360)`.
+#   +Step of `AnonymousClass(#14360)` is passed as constructor argument `kwargs[:baz]` to `AnonymousClass(#14400)`.
+#
+#   It is an antipattern. It neglects the idea of steps.
+#
+#   Please, try to reorganize `AnonymousClass(#14400)` service.
+#
+def ds(first_string, second_string)
+  require "diffy"
+
+  puts ::Diffy::Diff.new(first_string, second_string).to_s(:color)
+end

data/lib/convenient_service/dependencies/only_queries.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+##
+# @internal
+#   - https://ruby-doc.org/stdlib-2.7.0/libdoc/rubygems/rdoc/Gem/Version.html
+#   - https://github.com/rubygems/rubygems
+#   - https://github.com/rubygems/rubygems/blob/master/lib/rubygems/version.rb
+#
+require "rubygems"
+
+##
+# This file load extracted dependencies.
+#
+# @internal
+#   https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
+#
+require_relative "queries"
+
+##
+# `ConvenientService::Dependencies` can dynamically require plugins/extensions that have external dependencies.
+#
+# @internal
+#   https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
+#
+module ConvenientService
+  module Dependencies
+    extend Queries
+  end
+end

data/lib/convenient_service/dependencies/queries/gems/active_model.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      module Gems
+        ##
+        # @api private
+        #
+        class ActiveModel
+          class << self
+            ##
+            # @return [Boolean]
+            #
+            # @internal
+            #   `Style/TernaryParentheses` is disabled since `defined?` has too low priority without parentheses.
+            #
+            # rubocop:disable Style/TernaryParentheses
+            def loaded?
+              (defined? ::ActiveModel) ? true : false
+            end
+            # rubocop:enable Style/TernaryParentheses
+
+            ##
+            # @return [ConvenientService::Dependencies::Queries::Version]
+            #
+            # @internal
+            #   https://github.com/rails/rails/blob/main/activemodel/lib/active_model/version.rb
+            #
+            def version
+              loaded? ? Version.new(::ActiveModel.version) : Version.null_version
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/dependencies/queries/gems/logger.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      module Gems
+        class Logger
+          class << self
+            ##
+            # @api private
+            #
+            # @return [Boolean]
+            #
+            # @internal
+            #   `Style/TernaryParentheses` is disabled since `defined?` has too low priority without parentheses.
+            #
+            # rubocop:disable Style/TernaryParentheses
+            def loaded?
+              (defined? ::Logger) ? true : false
+            end
+            # rubocop:enable Style/TernaryParentheses
+
+            ##
+            # @api private
+            #
+            # @return [ConvenientService::Dependencies::Queries::Version]
+            #
+            # @internal
+            #   - https://github.com/ruby/logger/blob/v1.5.3/lib/logger/version.rb
+            #
+            def version
+              loaded? ? Version.new(::Logger::VERSION) : Version.null_version
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/dependencies/queries/gems/paint.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      module Gems
+        class Paint
+          class << self
+            ##
+            # @api private
+            #
+            # @return [Boolean]
+            #
+            # @internal
+            #   `Style/TernaryParentheses` is disabled since `defined?` has too low priority without parentheses.
+            #
+            # rubocop:disable Style/TernaryParentheses
+            def loaded?
+              (defined? ::Paint) ? true : false
+            end
+            # rubocop:enable Style/TernaryParentheses
+
+            ##
+            # @api private
+            #
+            # @return [ConvenientService::Dependencies::Queries::Version]
+            #
+            # @internal
+            #   - https://github.com/janlelis/paint/blob/v2.2.1/lib/paint/version.rb
+            #
+            def version
+              loaded? ? Version.new(::Paint::VERSION) : Version.null_version
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/dependencies/queries/gems/rspec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      module Gems
+        ##
+        # @api private
+        #
+        class RSpec
+          class << self
+            ##
+            # @return [Boolean]
+            #
+            # @internal
+            #   `Style/TernaryParentheses` is disabled since `defined?` has too low priority without parentheses.
+            #
+            # rubocop:disable Style/TernaryParentheses
+            def loaded?
+              (defined? ::RSpec) ? true : false
+            end
+            # rubocop:enable Style/TernaryParentheses
+
+            ##
+            # @return [ConvenientService::Dependencies::Queries::Version]
+            #
+            # @internal
+            #   https://github.com/rspec/rspec-core/blob/main/lib/rspec/core/version.rb
+            #
+            def version
+              loaded? ? Version.new(::RSpec::Core::Version::STRING) : Version.null_version
+            end
+
+            ##
+            # @return [RSpec::Core::Example, nil]
+            #
+            # @internal
+            #   NOTE: Returns `nil` in environments where RSpec is NOT fully loaded, e.g: irb, rails console, etc.
+            #
+            #   `::RSpec.current_example` docs:
+            #   - https://www.rubydoc.info/github/rspec/rspec-core/RSpec.current_example
+            #   - https://github.com/rspec/rspec-core/blob/v3.12.0/lib/rspec/core.rb#L122
+            #   - https://relishapp.com/rspec/rspec-core/docs/metadata/current-example
+            #
+            def current_example
+              return unless loaded?
+
+              ##
+              # NOTE: This happens in Ruby-only projects where RSpec is loaded by `Bundler.require`, not by `bundle exec rspec`.
+              #
+              return unless ::RSpec.respond_to?(:current_example)
+
+              ::RSpec.current_example
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/dependencies/queries/ruby.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      ##
+      # @api private
+      #
+      class Ruby
+        class << self
+          ##
+          # @return [ConvenientService::Dependencies::Queries::Version]
+          #
+          # @internal
+          #   NOTE: Ruby defines `RUBY_VERSION` global variable.
+          #   - https://ruby-doc.org/core-2.7.2/doc/globals_rdoc.html
+          #
+          def version
+            @version ||= Version.new(::RUBY_VERSION)
+          end
+
+          ##
+          # @return [String]
+          #
+          # @internal
+          #   TODO: Add direct specs.
+          #
+          def engine
+            ::RUBY_ENGINE.to_s
+          end
+
+          ##
+          # @return [ConvenientService::Dependencies::Queries::Version]
+          #
+          # @internal
+          #   NOTE: Ruby defines `RUBY_ENGINE_VERSION` global variable.
+          #   - https://ruby-doc.org/core-2.7.2/doc/globals_rdoc.html
+          #
+          #   NOTE: JRuby defines `RUBY_ENGINE_VERSION` global variable.
+          #   - https://github.com/jruby/jruby/blob/9.4.0.0/spec/jruby/compat_spec.rb#L6
+          #
+          #   NOTE: TruffleRuby defines `RUBY_ENGINE_VERSION` global variable.
+          #   - https://github.com/oracle/truffleruby/blob/vm-22.3.0/spec/truffle/identity_spec.rb#L23
+          #
+          #   TODO: Add direct specs.
+          #
+          def engine_version
+            @engine_version ||= Version.new(::RUBY_ENGINE_VERSION)
+          end
+
+          ##
+          # Returns `true` when MRI, `false` otherwise.
+          #
+          # @return [Boolean]
+          #
+          # @see https://github.com/janlelis/ruby_engine
+          #
+          # @internal
+          #   NOTE: Gratefully copied from the `ruby_engine` gem. Version `1.1.4`.
+          #   - https://github.com/janlelis/ruby_engine/blob/v2.0.0/lib/ruby_engine.rb#L19
+          #
+          def mri?
+            ::RUBY_ENGINE.to_s == "ruby"
+          end
+
+          alias_method :ruby?, :mri?
+
+          ##
+          # Returns `true` when JRuby, `false` otherwise.
+          #
+          # @return [Boolean]
+          #
+          # @see https://github.com/rdp/os
+          #
+          # @internal
+          #   NOTE: Gratefully copied from the `os` gem. Version `1.1.4`.
+          #   - https://github.com/rdp/os/blob/v1.1.4/lib/os.rb#L101
+          #
+          #   NOTE: Modified original implementation in order to return a boolean.
+          #   NOTE: Consider to use `RUBY_ENGINE` as for others?
+          #
+          def jruby?
+            ::RUBY_PLATFORM.to_s.match?(/java/)
+          end
+
+          ##
+          # Returns `true` when TruffleRuby, `false` otherwise.
+          #
+          # @return [Boolean]
+          #
+          # @internal
+          #   NOTE: Taken from irb testing. May NOT be stable.
+          #
+          #   TODO: Find a confirmation of stability.
+          #
+          def truffleruby?
+            ::RUBY_ENGINE.to_s.match?(/truffleruby/)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/dependencies/queries/version/null_version.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      class Version
+        ##
+        # @api private
+        #
+        # @internal
+        #   - https://thoughtbot.com/blog/rails-refactoring-example-introduce-null-object
+        #   - https://avdi.codes/null-objects-and-falsiness/
+        #
+        class NullVersion
+          ##
+          # @return [Boolean]
+          #
+          def null_version?
+            true
+          end
+
+          ##
+          # @return [nil]
+          #
+          def gem_version
+            nil
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [nil]
+          #
+          def <=>(other)
+            nil
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [nil]
+          #
+          def <(other)
+            nil
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [nil]
+          #
+          def <=(other)
+            nil
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [nil]
+          #
+          def ==(other)
+            nil
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [nil]
+          #
+          def >(other)
+            nil
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [nil]
+          #
+          def >=(other)
+            nil
+          end
+
+          ##
+          # @return [String]
+          #
+          def to_s
+            ""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/dependencies/queries/version.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "version/null_version"
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      class Version
+        include ::Comparable
+
+        undef_method :between?
+
+        undef_method :clamp
+
+        ##
+        # @param value [String]
+        # @return [void]
+        #
+        def initialize(value)
+          @value = value
+        end
+
+        class << self
+          ##
+          # @return [ConvenientService::Dependencies::Queries::Version::NullVersion]
+          #
+          def null_version
+            @null_version ||= Version::NullVersion.new
+          end
+        end
+
+        ##
+        # @return [Boolean]
+        #
+        def null_version?
+          false
+        end
+
+        ##
+        # @return [Gem::Version, nil]
+        #
+        def gem_version
+          cast_gem_version(value)
+        end
+
+        ##
+        # @return [String]
+        #
+        # @internal
+        #   TODO: Add direct specs.
+        #
+        def major_minor
+          to_s[/\d+\.\d+/]
+        end
+
+        ##
+        # @param other [Object] Can be any type.
+        # @return [Boolean, nil]
+        #
+        def <=>(other)
+          gem_version <=> cast_gem_version(other)
+        end
+
+        ##
+        # @return [String]
+        #
+        def to_s
+          gem_version.to_s
+        end
+
+        private
+
+        ##
+        # @return [String]
+        #
+        attr_reader :value
+
+        ##
+        # @return [Gem::Version, nil]
+        #
+        def cast_gem_version(value)
+          ::Gem::Version.create(value.to_s) if ::Gem::Version.correct?(value.to_s)
+        end
+      end
+    end
+  end
+end