convenient_service 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a908de0164e680bc5926c42eeeea9df2afdcddd065dcad74dcaf403aacfe22f5
-  data.tar.gz: f10f0debfa96eeef7bf37ff35332606cd8a936833ab0f3ff98490bc0f8e6af37
+  metadata.gz: 1943fd64d61a41a18701985f5a7296b7cf3337ab0562c1912ee7765668dd6f3a
+  data.tar.gz: 02e2d46311210cd922b606848f36c82db136a7f2ca2013fba269c6c5eb3adc3a
 SHA512:
-  metadata.gz: 4f172f536a57db46fd16a29ac859a59f32060c910db5ee568249be5a74328d001b152ad71cd81c35344085b41ea85f6e66f5dd8d9fdc414ed2fbe24433a3e002
-  data.tar.gz: a64c8dda2bce2f27f1462f485c3b62268d06c48367d464486fd7a51c2fba01b0ba96da27c5d66a4f467b053b556631d395a25735833c7c448ad733e474b28540
+  metadata.gz: 74cded446d90f5b06675c5c19f7647792e195b47178504b14dbf650640186f33679e8bf8c17ad73e214ff5f1b38d233c7919c361f3f90c569435fc14e4c5d999
+  data.tar.gz: a7773a495b1805778221b006427562bd25acd7420c243aab192abaf0460d661d905259aed97a2c489ccd9e77bac349da1516f9dd8ec8d7b573115b5872229b92

data/README.md

@@ -23,7 +23,7 @@
 [![Gem Version](https://badge.fury.io/rb/convenient_service.svg)](https://rubygems.org/gems/convenient_service) [![Gem Downloads](https://img.shields.io/gem/dt/convenient_service.svg)](https://rubygems.org/gems/convenient_service) ![visitors](https://visitor-badge.glitch.me/badge?page_id=marian13/convenient_service) ![GitHub repo size](https://img.shields.io/github/repo-size/marian13/convenient_service) [![GitHub Actions CI](https://github.com/marian13/convenient_service/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/marian13/convenient_service/actions/workflows/ci.yml) [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard) [![Coverage Status](https://coveralls.io/repos/github/marian13/convenient_service/badge.svg)](https://coveralls.io/github/marian13/convenient_service?branch=main) [![inline docs](http://inch-ci.org/github/marian13/convenient_service.svg?branch=main)](http://inch-ci.org/github/marian13/convenient_service) [![yard docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://marian13.github.io/convenient_service/)
 [![Convenient Service on stackoverflow](https://img.shields.io/badge/stackoverflow-community-orange.svg?logo=stackoverflow)](https://stackoverflow.com/tags/convenient-service)
 [![Patreon](https://img.shields.io/badge/patreon-donate-orange.svg)](https://www.patreon.com/user?u=31435716&fan_landing=true)
-[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: LGPL-3.0](https://img.shields.io/badge/license-LGPL--3.0-yellow.svg)](https://www.gnu.org/licenses/lgpl-3.0.html)
 <!-- badges:end -->
 
 <!-- logo:start -->
@@ -40,8 +40,7 @@ Yet another approach to revisit the service object pattern, but this time focusi
 <!-- warning:start -->
 ## ❗❗❗ WARNING ❗❗❗
 
-This library is under heavy development. Public API may be subject to change. The first major release is still to come. Use the current version at your own risk. Ruby 2.7+, JRuby 9.4+ (TruffleRuby support is planned as well). Thanks.
-<!-- features:end -->
+This library is under heavy development. Most of the public API is polished, but it still may be subject to change. It has already been successfully used in production environments for more than a year, but the first major version is planned for the second quarter of 2025. Use the current version at your own risk. Ruby 2.7+, JRuby 9.4+ (TruffleRuby support is planned as well). Thanks.
 <!-- warning:end -->
 
 <!-- links:start -->
@@ -63,6 +62,8 @@ This library is under heavy development. Public API may be subject to change. Th
 
 - [Static Content](https://github.com/marian13/static_content/tree/main/convenient_service) repo.
 
+- [Convenient Service Integration](https://github.com/marian13/convenient_service_integration) machinery.
+
 - Have a look at [Convenient Service Development Wiki](https://github.com/marian13/convenient_service/wiki) for the contribution tutorials.
 
 <!-- links:end -->

data/lib/convenient_service/commands/is_service.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Commands
+    class IsService < Support::Command
+      ##
+      # @!attribute [r] service
+      #   @return [Object] Can be any type.
+      #
+      attr_reader :service
+
+      ##
+      # @param service [Object] Can be any type.
+      # @return [void]
+      #
+      def initialize(service:)
+        @service = service
+      end
+
+      ##
+      # @return [Boolean]
+      #
+      def call
+        Commands::IsServiceClass[service_class: service.class]
+      end
+    end
+  end
+end

data/lib/convenient_service/commands/is_service_class.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Commands
+    class IsServiceClass < Support::Command
+      ##
+      # @!attribute [r] service_class
+      #   @return [Object] Can be any type.
+      #
+      attr_reader :service_class
+
+      ##
+      # @param service_class [Object] Can be any type.
+      # @return [void]
+      #
+      def initialize(service_class:)
+        @service_class = service_class
+      end
+
+      ##
+      # @return [Boolean]
+      #
+      def call
+        return unless service_class.instance_of?(::Class)
+
+        service_class.include?(Service::Configs::Essential)
+      end
+    end
+  end
+end

data/lib/convenient_service/commands.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "commands/is_service_class"
+require_relative "commands/is_service"

data/lib/convenient_service/common/plugins.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
 ##
-# NOTE: Order matters.
+# @internal
+#   NOTE: Some plugins are order-dependent.
 #
-require_relative "plugins/normalizes_env"
-
 require_relative "plugins/caches_constructor_arguments"
 require_relative "plugins/caches_return_value"
 require_relative "plugins/can_be_copied"

data/lib/convenient_service/core/concern/class_methods.rb

@@ -117,6 +117,9 @@ module ConvenientService
         #   - `lib/convenient_service/core/entities/config/entities/method_middlewares/entities/caller/commands/define_method_middlewares_caller.rb`
         #   - https://gist.github.com/marian13/9c25041f835564e945d978839097d419
         #
+        #   IMPORTANT: Psych has a monkey-patch `y` in IRB. That is why calling `Service.y` raise `private method called` instead of `undefined method`.
+        #   - https://github.com/ruby/psych/blob/v5.1.2/lib/psych/y.rb#L5
+        #
         def method_missing(method, *args, **kwargs, &block)
           commit_config!(trigger: Constants::Triggers::CLASS_METHOD_MISSING)
 

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

@@ -48,6 +48,23 @@ module ConvenientService
                   plain_stack.call(env)
                 end
 
+                ##
+                # @param concern [ConvenientService::Support::Concern, Module]
+                # @param args [Array<Object>]
+                # @param block [Proc, nil]
+                # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
+                #
+                def unshift(concern, *args, &block)
+                  plain_stack.unshift(cast(concern), *args, &block)
+
+                  self
+                end
+
+                ##
+                # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
+                #
+                alias_method :prepend, :unshift
+
                 ##
                 # @param index_or_concern [Integer, ConvenientService::Support::Concern, Module]
                 # @param concern [ConvenientService::Support::Concern, Module]
@@ -137,6 +154,11 @@ module ConvenientService
                   self
                 end
 
+                ##
+                # @return [ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Stack]
+                #
+                alias_method :remove, :delete
+
                 ##
                 # @param concern [ConvenientService::Support::Concern, Module]
                 # @param args [Array<Object>]

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

@@ -78,7 +78,7 @@ module ConvenientService
                     #   # [Service::ClassMethodsMiddlewaresCallers, #<Class:Service>, ConvenientService::Core::ClassMethods, #<Class:Object>, #<Class:BasicObject>, Class, Module, Object, Kernel, BasicObject]
                     #
                     #   ancestors_greater_than_methods_middlewares_callers # For the entity defined above.
-                    #   # [#<Class:Service>, ConvenientService::Core::ClassMethods, #<Class:Object>, #<Class:BasicObject>, Class, Module, Object, Kernel, BasicObject]# [Service::ClassMethodsMiddlewaresCallers, #<Class:Service>, ConvenientService::Core::ClassMethods, #<Class:Object>, #<Class:BasicObject>, Class, Module, Object, Kernel, BasicObject]
+                    #   # [#<Class:Service>, ConvenientService::Core::ClassMethods, #<Class:Object>, #<Class:BasicObject>, Class, Module, Object, Kernel, BasicObject]
                     #
                     # @note Returns empty array when `methods_middlewares_callers` are NOT prepended.
                     # @note If you expect to receive not empty array, make sure the config is committed.

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middleware_creators/observable/entities/event.rb

@@ -8,11 +8,16 @@ module ConvenientService
           class MethodMiddlewares
             module Entities
               module MiddlewareCreators
+                ##
+                # NOTE: `observer` is NOT a part of Ruby stdlib starting from Ruby 3.4. That is why a custom observer is implemented.
+                #
+                # @internal
+                #   - https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html
+                #   - https://github.com/ruby/observer
+                #
                 class Observable < MiddlewareCreators::Base
                   module Entities
                     class Event
-                      include ::Observable
-
                       ##
                       # @!attribute [r] type
                       #   @return [Symbol]
@@ -41,7 +46,7 @@ module ConvenientService
                       # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-add_observer
                       #
                       def add_observer(observer, func = default_handler_name)
-                        super
+                        observers[observer] = func
                       end
 
                       ##
@@ -50,10 +55,8 @@ module ConvenientService
                       # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-changed
                       # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-notify_observers
                       #
-                      def notify_observers(...)
-                        changed
-
-                        super
+                      def notify_observers(*args, **kwargs, &block)
+                        observers.each { |observer, method| observer.__send__(method, *args, **kwargs, &block) }
                       end
 
                       ##
@@ -64,7 +67,7 @@ module ConvenientService
                         return unless other.instance_of?(self.class)
 
                         return false if type != other.type
-                        return false if observer_peers != other.observer_peers
+                        return false if observers != other.observers
 
                         true
                       end
@@ -74,13 +77,8 @@ module ConvenientService
                       ##
                       # @return [Hash]
                       #
-                      # @see https://ruby-doc.org/stdlib-2.7.0/libdoc/observer/rdoc/Observable.html#method-i-count_observers
-                      #
-                      # @internal
-                      #   IMPORTANT: This method is using inherited private instance varaible. Ruby may change its name without any warning.
-                      #
-                      def observer_peers
-                        @observer_peers if defined? @observer_peers
+                      def observers
+                        @observers ||= {}
                       end
                     end
                   end

data/lib/convenient_service/core/entities/config/entities/method_middlewares/entities/middlewares/chain/commands/normalize_env.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Core
+    module Entities
+      class Config
+        module Entities
+          class MethodMiddlewares
+            module Entities
+              module Middlewares
+                class Chain < Middlewares::Base
+                  module Commands
+                    ##
+                    # - Single splat `*` converts `nil` to empty array.
+                    # - Double splat `**` raises on `nil`.
+                    # - Umpersand `&` converts `nil` to `nil`.
+                    #
+                    # The following middleware converts `env[:kwargs]` to a hash.
+                    # This way `__send__(:next, *env[:args], **env[:kwargs], &env[:block])` won't fail even if a user passes `nil` as `kwargs`.
+                    #
+                    # Check the following link for more details:
+                    # - https://bugs.ruby-lang.org/issues/8507
+                    #
+                    class NormalizeEnv < Support::Command
+                      ##
+                      # @!attribute [r] env
+                      #   @return [Hash, nil]
+                      #
+                      attr_reader :env
+
+                      ##
+                      # @param env [Hash, nil]
+                      # @return [void]
+                      #
+                      def initialize(env:)
+                        @env = env.to_h
+                      end
+
+                      ##
+                      # @return [Hash]
+                      #
+                      def call
+                        env.merge(args: env[:args].to_a, kwargs: env[:kwargs].to_h, block: env[:block])
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
 require_relative "commands/create_observable_middleware"
+require_relative "commands/normalize_env"

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/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