convenient_service 0.3.1 → 0.5.0

data/lib/convenient_service/support/dependency_container/entities/method.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Entities
+        class Method
+          ##
+          # @!attribute [r] full_name
+          #   @return [String, Symbol]
+          #
+          attr_reader :full_name
+
+          ##
+          # @!attribute [r] scope
+          #   @return [:instance, :class]
+          #
+          attr_reader :scope
+
+          ##
+          # @!attribute [r] body
+          #   @return [Proc]
+          #
+          attr_reader :body
+
+          ##
+          # @param full_name [String, Symbol]
+          # @param scope [:instance, :class]
+          # @param body [Proc]
+          # @return [void]
+          #
+          def initialize(full_name:, scope:, body:)
+            @full_name = full_name
+            @scope = scope
+            @body = body
+          end
+
+          ##
+          # @return [String]
+          #
+          def name
+            @name ||= full_name_parts.last
+          end
+
+          ##
+          # @return [Array<ConvenientService::Support::DependencyContainer::Entities::Namespace>]
+          #
+          def namespaces
+            @namespaces ||= full_name_parts.slice(0..-2).map { |part| Entities::Namespace.new(name: part) }
+          end
+
+          ##
+          # @param mod [Module]
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Method]
+          #
+          def define_in_module!(mod)
+            ##
+            # NOTE: `innermost_namespace` is just `mod`, when `namespaces` are empty.
+            #
+            innermost_namespace =
+              namespaces.reduce(mod) do |namespace, sub_namespace|
+                already_defined_sub_namespace = namespace.namespaces.find_by(name: sub_namespace.name)
+
+                ##
+                # NOTE:
+                #   - Reuses already defined namespace from previous "imports".
+                #   - In contrast, same methods are always redefined.
+                #
+                next already_defined_sub_namespace if already_defined_sub_namespace
+
+                namespace.namespaces << sub_namespace
+
+                namespace.define_method(sub_namespace.name) { sub_namespace.body.call }
+
+                sub_namespace
+              end
+
+            ##
+            # NOTE:
+            #   - Same methods are redefined.
+            #   - In contrast, same namespaces are always reused.
+            #
+            innermost_namespace.define_method(method.name, &method.body)
+
+            method
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [Boolean]
+          #
+          def ==(other)
+            return unless other.instance_of?(self.class)
+
+            return false if full_name != other.full_name
+            return false if scope != other.scope
+            return false if body != other.body
+
+            true
+          end
+
+          private
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Method]
+          #
+          def method
+            self
+          end
+
+          ##
+          # @return [Array<String>]
+          #
+          def full_name_parts
+            @full_name_parts ||= Utils::String.split(full_name, ".", "::").map(&:to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/entities/method_collection.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Entities
+        class MethodCollection
+          ##
+          # @param methods [Array<ConvenientService::Support::DependencyContainer::Entities::Method>]
+          # @return [void]
+          #
+          def initialize(methods: [])
+            @methods = methods
+          end
+
+          ##
+          # @param name [String, Symbol]
+          # @param full_name [String, Symbol]
+          # @param scope [:instance, :class]
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Method, nil]
+          #
+          def find_by(name: Support::NOT_PASSED, full_name: Support::NOT_PASSED, scope: Support::NOT_PASSED)
+            rules = []
+
+            rules << ->(method) { method.name.to_s == name.to_s } if name != Support::NOT_PASSED
+            rules << ->(method) { method.full_name.to_s == full_name.to_s } if full_name != Support::NOT_PASSED
+            rules << ->(method) { method.scope == scope } if scope != Support::NOT_PASSED
+
+            condition = Utils::Proc.conjunct(rules)
+
+            methods.find(&condition)
+          end
+
+          ##
+          # @param method [ConvenientService::Support::DependencyContainer::Entities::Method]
+          # @return [ConvenientService::Support::DependencyContainer::Entities::MethodCollection]
+          #
+          def <<(method)
+            methods << method
+
+            self
+          end
+
+          ##
+          # @return [Boolean]
+          #
+          def empty?
+            methods.empty?
+          end
+
+          ##
+          # @param method [ConvenientService::Support::DependencyContainer::Entities::Method]
+          # @return [Boolean]
+          #
+          def include?(method)
+            methods.include?(method)
+          end
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::MethodCollection]
+          #
+          def clear
+            methods.clear
+
+            self
+          end
+
+          ##
+          # @return [Array]
+          #
+          def to_a
+            methods.to_a
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [Boolean]
+          #
+          def ==(other)
+            return unless other.instance_of?(self.class)
+
+            return false if methods != other.methods
+
+            true
+          end
+
+          protected
+
+          ##
+          # @!attribute [r] methods
+          #   @return [Array<ConvenientService::Support::DependencyContainer::Entities::Method>]
+          #
+          attr_reader :methods
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/entities/namespace.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Entities
+        class Namespace
+          ##
+          # @!attribute [r] name
+          #   @return [String, Symbol]
+          #
+          attr_reader :name
+
+          ##
+          # @param name [String, Symbol]
+          # @return [void]
+          #
+          def initialize(name:)
+            @name = name
+          end
+
+          ##
+          # @return [Proc]
+          #
+          def body
+            @body ||= -> { namespace }
+          end
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::NamespaceCollection]
+          #
+          def namespaces
+            @namespaces ||= Entities::NamespaceCollection.new
+          end
+
+          ##
+          # @param name [String, Symbol]
+          # @param body [Proc]
+          # @return [Symbol]
+          #
+          def define_method(name, &body)
+            define_singleton_method(name, &body)
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [Boolean]
+          #
+          def ==(other)
+            return unless other.instance_of?(self.class)
+
+            return false if name != other.name
+
+            true
+          end
+
+          private
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Namespace]
+          #
+          def namespace
+            self
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/entities/namespace_collection.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Entities
+        class NamespaceCollection
+          ##
+          # @param namespaces [Array<ConvenientService::Support::DependencyContainer::Entities::Namespace>]
+          # @return [void]
+          #
+          def initialize(namespaces: [])
+            @namespaces = namespaces
+          end
+
+          ##
+          #
+          #
+          def define_namespace(namespace)
+            namespaces << namespace
+
+            define_singleton_method(namespace.name) { namespace.body.call }
+          end
+
+          ##
+          # @param name [String, Symbol]
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Namespace, nil]
+          #
+          def find_by(name: Support::NOT_PASSED)
+            rules = []
+
+            rules << ->(namespace) { namespace.name.to_s == name.to_s } if name != Support::NOT_PASSED
+
+            condition = Utils::Proc.conjunct(rules)
+
+            namespaces.find(&condition)
+          end
+
+          ##
+          # @param namespace [ConvenientService::Support::DependencyContainer::Entities::Namespace]
+          # @return [ConvenientService::Support::DependencyContainer::Entities::NamespaceCollection]
+          #
+          def <<(namespace)
+            namespaces << namespace
+
+            self
+          end
+
+          ##
+          # @return [Boolean]
+          #
+          def empty?
+            namespaces.empty?
+          end
+
+          ##
+          # @param namespace [ConvenientService::Support::DependencyContainer::Entities::Namespace]
+          # @return [Boolean]
+          #
+          def include?(namespace)
+            namespaces.include?(namespace)
+          end
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::NamespaceCollection]
+          #
+          def clear
+            namespaces.clear
+
+            self
+          end
+
+          ##
+          # @return [Array]
+          #
+          def to_a
+            namespaces.to_a
+          end
+
+          ##
+          # @param other [Object] Can be any type.
+          # @return [Boolean]
+          #
+          def ==(other)
+            return unless other.instance_of?(self.class)
+
+            return false if namespaces != other.namespaces
+
+            true
+          end
+
+          protected
+
+          ##
+          # @!attribute [r] namespaces
+          #   @return [Array<ConvenientService::Support::DependencyContainer::Entities::Namespace>]
+          #
+          attr_reader :namespaces
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/entities.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "entities/method_collection"
+require_relative "entities/method"
+require_relative "entities/namespace_collection"
+require_relative "entities/namespace"

data/lib/convenient_service/support/dependency_container/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Errors
+        class NotExportableModule < ConvenientService::Error
+          ##
+          # @param mod [Module]
+          # @return [void]
+          #
+          def initialize(mod:)
+            message = <<~TEXT
+              Module `#{mod}` can NOT export methods.
+
+              Did you forget to include `ConvenientService::Container.export` into it?
+            TEXT
+
+            super(message)
+          end
+        end
+
+        class NotExportedMethod < ConvenientService::Error
+          ##
+          # @param method_name [String]
+          # @param method_scope [Symbol]
+          # @param mod [Module]
+          # @return [void]
+          #
+          def initialize(method_name:, method_scope:, mod:)
+            message = <<~TEXT
+              Module `#{mod}` does NOT export method `#{method_name}` with `#{method_scope}` scope.
+
+              Did you forget to export if from `#{mod}`? For example:
+
+              module #{mod}
+                export #{method_name}, scope: :#{method_scope} do |*args, **kwargs, &block|
+                  # ...
+                end
+              end
+            TEXT
+
+            super(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/export.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Export
+        include Support::Concern
+
+        class_methods do
+          ##
+          # @param full_name [String, Symbol]
+          # @param scope [:instance, :class]
+          # @param body [Proc]
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Method]
+          #
+          def export(full_name, scope: Constants::DEFAULT_SCOPE, &body)
+            Entities::Method.new(full_name: full_name, scope: scope, body: body).tap { |method| exported_methods << method }
+          end
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::MethodCollection]
+          #
+          def exported_methods
+            @exported_methods ||= Entities::MethodCollection.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/import.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Import
+        include Support::Concern
+
+        class_methods do
+          ##
+          # @param full_name [String, Symbol]
+          # @param from [Module]
+          # @param scope [:instance, :class]
+          # @param prepend [Boolean]
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Method]
+          #
+          def import(full_name, from:, scope: Constants::DEFAULT_SCOPE, prepend: Constants::DEFAULT_PREPEND)
+            raise Errors::NotExportableModule.new(mod: from) unless Utils::Module.include_module?(from, DependencyContainer::Export)
+
+            method = from.exported_methods.find_by(full_name: full_name, scope: scope)
+
+            raise Errors::NotExportedMethod.new(method_name: full_name, method_scope: scope, mod: from) unless method
+
+            Commands::ImportMethod.call(importing_module: self, exporting_module: from, method: method, scope: scope, prepend: prepend)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "dependency_container/commands"
+require_relative "dependency_container/constants"
+require_relative "dependency_container/entities"
+require_relative "dependency_container/errors"
+
+require_relative "dependency_container/export"
+require_relative "dependency_container/import"

data/lib/convenient_service/support/gems/rspec.rb

@@ -34,7 +34,7 @@ module ConvenientService
           # @return [RSpec::Core::Example, nil]
           #
           # @internal
-          #   NOTE: Returns `nil` in a non-test environment
+          #   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
@@ -42,7 +42,14 @@ module ConvenientService
           #   - https://relishapp.com/rspec/rspec-core/docs/metadata/current-example
           #
           def current_example
-            ::RSpec.current_example if loaded?
+            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

data/lib/convenient_service/support/not_passed.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    NOT_PASSED = ::Object.new
+  end
+end

data/lib/convenient_service/support/raw_value.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    class RawValue
+      ##
+      # @param object [Object] Can be any type.
+      # @return [void]
+      #
+      def initialize(object)
+        @object = object
+      end
+
+      class << self
+        ##
+        # @param object [Object] Can be any type.
+        # @return [ConvenientService::Support::RawValue]
+        #
+        def wrap(object)
+          new(object)
+        end
+
+        private :new
+      end
+
+      ##
+      # @return [Object] Can be any type.
+      #
+      def unwrap
+        object
+      end
+
+      ##
+      # @return [Boolean, nil]
+      #
+      def ==(other)
+        return unless other.instance_of?(self.class)
+
+        return false if object != other.object
+
+        true
+      end
+
+      protected
+
+      ##
+      # @return [Object] Can be any type.
+      #
+      attr_reader :object
+    end
+  end
+end

data/lib/convenient_service/support.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "support/not_passed"
 require_relative "support/concern"
 
 require_relative "support/abstract_method"
@@ -8,8 +9,10 @@ require_relative "support/castable"
 require_relative "support/command"
 require_relative "support/copyable"
 require_relative "support/delegate"
+require_relative "support/dependency_container"
 require_relative "support/finite_loop"
 require_relative "support/gems"
 require_relative "support/middleware"
+require_relative "support/raw_value"
 require_relative "support/ruby"
 require_relative "support/version"