convenient_service 0.19.1 → 0.21.0

data/lib/convenient_service/dependencies/queries.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "queries/version"
 require_relative "queries/ruby"
 require_relative "queries/gems"
 
-##
-# `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
     ##
@@ -24,12 +23,68 @@ module ConvenientService
       extend self
 
       ##
+      # Returns `true` when Convenient Service is in debug mode. In other words `$CONVENIENT_SERVICE_DEBUG` env variable is set to `true`.
+      #
       # @api private
+      # @since 1.0.0
+      # @return [Boolean]
+      #
+      def debug?
+        ::ENV["CONVENIENT_SERVICE_DEBUG"] == "true"
+      end
+
+      ##
+      # Returns `true` when Convenient Service is in benchmark mode. In other words `$CONVENIENT_SERVICE_BENCHMARK` env variable is set to `true`.
       #
+      # @api private
+      # @since 1.0.0
       # @return [Boolean]
-      # @see ConvenientService.Dependencies.require_has_j_send_result_params_validations_using_active_model_validations
       #
-      def support_has_j_send_result_params_validations_using_active_model_validations?
+      def benchmark?
+        ::ENV["CONVENIENT_SERVICE_BENCHMARK"] == "true"
+      end
+
+      ##
+      # Returns `true` when Convenient Service is in CI mode. In other words `$CONVENIENT_SERVICE_CI` env variable is set to `true`.
+      #
+      # @api private
+      # @since 1.0.0
+      # @return [Boolean]
+      #
+      def ci?
+        ::ENV["CONVENIENT_SERVICE_CI"] == "true"
+      end
+
+      ##
+      # @api private
+      #
+      # @return [Boolean]
+      #
+      # @see https://github.com/deivid-rodriguez/byebug/issues/289
+      #
+      # @internal
+      #   NOTE: Ruby 4.0 does not ship with the `readline` by default. That is why `byebug` throws the following error:
+      #     Sorry, you can't use byebug without Readline. To solve this, you need to
+      #     rebuild Ruby with Readline support. If using Ubuntu, try `sudo apt-get
+      #     install libreadline-dev` and then reinstall your Ruby.
+      #
+      #     LoadError:
+      #       cannot load such file -- readline
+      #
+      #   The bigger problem is that the `readline` (`libreadline-dev`) must be available before building Ruby.
+      #   In other words, the full Docker image source should be copied, extended, and built locally.
+      #
+      def support_byebug?
+        ruby.mri? && ruby.version < 4.0
+      end
+
+      ##
+      # @api private
+      #
+      # @return [Boolean]
+      # @see ConvenientService.Dependencies.require_has_j_send_result_params_validations_using_active_model_validations_plugin
+      #
+      def support_has_j_send_result_params_validations_using_active_model_validations_plugin?
         return false unless active_model.loaded?
         return false if ruby.version >= 3.0 && active_model.version < 6.0
 
@@ -48,22 +103,20 @@ module ConvenientService
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
       def require_alias
-        require "convenient_service/alias"
+        ::Object.const_set(:CS, ::ConvenientService)
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_assigns_attributes_in_constructor_using_active_model_attribute_assignment
+      def require_assigns_attributes_in_constructor_using_active_model_attribute_assignment_plugin
         ##
         # - https://edgeguides.rubyonrails.org/active_model_basics.html
         # - https://api.rubyonrails.org/classes/ActiveModel.html
@@ -75,12 +128,11 @@ module ConvenientService
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_assigns_attributes_in_constructor_using_dry_initializer
+      def require_assigns_attributes_in_constructor_using_dry_initializer_plugin
         ##
         # - https://dry-rb.org/gems/dry-initializer/main
         # - https://github.com/dry-rb/dry-initializer
@@ -91,22 +143,11 @@ module ConvenientService
       end
 
       ##
-      # @api public
-      #
-      # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
-      #
-      def require_can_utilize_finite_loop
-        require "convenient_service/common/plugins/can_utilize_finite_loop"
-      end
-
-      ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_has_attributes_using_active_model_attributes
+      def require_has_attributes_using_active_model_attributes_plugin
         ##
         # - https://edgeguides.rubyonrails.org/active_model_basics.html
         # - https://api.rubyonrails.org/classes/ActiveModel.html
@@ -118,12 +159,11 @@ module ConvenientService
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_amazing_print_inspect
+      def require_amazing_print_inspect_standard_config_option
         ##
         # - https://github.com/amazing-print/amazing_print
         #
@@ -136,17 +176,101 @@ module ConvenientService
         require "convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/plugins/has_amazing_print_inspect"
         require "convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/code/plugins/has_amazing_print_inspect"
         require "convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_amazing_print_inspect"
-        require "convenient_service/service/configs/amazing_print_inspect"
-        require "convenient_service/service/configs/amazing_print_inspect/aliases"
+        require "convenient_service/feature/plugins/has_amazing_print_inspect"
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_awesome_print_inspect
+      # Loads a config that patches services to use Awesome Print to generate colored `inspect` strings.
+      # Useful for debugging.
+      # Works as expected for `byebug` and `pry`.
+      #
+      # Has issues with escaping colors for `binding.break` and `irb`.
+      # There is a workaround in the examples, but its possible negative outcome has not been investigated yet. Use it at your own risk.
+      #
+      # @example `:awesome_print_inspect` output for `byebug` or `pry`.
+      #   class Service
+      #     include ::ConvenientService::Standard::Config.with(:awesome_print_inspect)
+      #
+      #     def result
+      #       success(foo: :bar)
+      #     end
+      #   end
+      #
+      #   Service.result
+      #   # =>
+      #   {
+      #     :ConvenientService => {
+      #            :entity => "Result",
+      #           :service => "Service",
+      #            :status => :success,
+      #         :data_keys => [
+      #             [0] :foo
+      #         ]
+      #     }
+      #   }
+      #
+      # @example `:awesome_print_inspect` output for `binding.break` or `irb`.
+      #
+      #   class Service
+      #     include ::ConvenientService::Standard::Config.with(:awesome_print_inspect)
+      #
+      #     def result
+      #       success(foo: :bar)
+      #     end
+      #   end
+      #
+      #   Service.result
+      #   # =>
+      #   {
+      #     :ConvenientService^[[0;37m => ^[[0m{
+      #            :entity^[[0;37m => ^[[0m^[[0;33m"Result"^[[0m,
+      #           :service^[[0;37m => ^[[0m^[[0;33m"Service"^[[0m,
+      #            :status^[[0;37m => ^[[0m^[[0;36m:success^[[0m,
+      #         :data_keys^[[0;37m => ^[[0m[
+      #             ^[[1;37m[0] ^[[0m^[[0;36m:foo^[[0m
+      #         ]
+      #       }
+      #   }
+      #
+      # @example `:awesome_print_inspect` output for `binding.break` or `irb` with `Reline` hack.
+      #
+      #   class Service
+      #     include ::ConvenientService::Standard::Config.with(:awesome_print_inspect)
+      #
+      #     def result
+      #       success(foo: :bar)
+      #     end
+      #   end
+      #
+      #   class Reline::Unicode
+      #     def self.escape_for_print(str)
+      #       str
+      #     end
+      #   end
+      #
+      #   Service.result
+      #   # =>
+      #   {
+      #     :ConvenientService => {
+      #            :entity => "Result",
+      #           :service => "Service",
+      #            :status => :success,
+      #         :data_keys => [
+      #             [0] :foo
+      #         ]
+      #     }
+      #   }
+      #
+      # @see https://github.com/awesome-print/awesome_print
+      # @see https://github.com/ruby/irb/blob/v1.13.1/lib/irb/inspector.rb#L113
+      # @see https://github.com/ruby/irb/blob/v1.13.1/lib/irb/color.rb#L150
+      # @see https://github.com/ruby/reline/blob/v0.5.8/lib/reline/unicode.rb#L30
+      #
+      def require_awesome_print_inspect_standard_config_option
         ##
         # - https://github.com/awesome-print/awesome_print
         #
@@ -159,19 +283,44 @@ module ConvenientService
         require "convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/plugins/has_awesome_print_inspect"
         require "convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/code/plugins/has_awesome_print_inspect"
         require "convenient_service/service/plugins/can_have_steps/entities/step/plugins/has_awesome_print_inspect"
-        require "convenient_service/service/configs/awesome_print_inspect"
-        require "convenient_service/service/configs/awesome_print_inspect/aliases"
+        require "convenient_service/feature/plugins/has_awesome_print_inspect"
       end
 
       ##
-      # @api public
+      # @api private
+      #
+      # @return [Boolean]
+      #
+      def require_dry_initializer_standard_config_option
+        require_assigns_attributes_in_constructor_using_dry_initializer_plugin
+      end
+
+      ##
+      # @api private
+      #
+      # @return [Boolean]
+      #
+      def require_active_model_validations_standard_config_option
+        require_has_j_send_result_params_validations_using_active_model_validations_plugin
+      end
+
+      ##
+      # @api private
+      #
+      # @return [Boolean]
+      #
+      def require_memo_wise_standard_config_option
+        require_has_memoization_using_memo_wise_plugin
+      end
+
+      ##
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
       # @see https://userdocs.convenientservice.org/troubleshooting/i18n_translate_wrong_number_of_arguments
       #
-      def require_has_j_send_result_params_validations_using_active_model_validations
+      def require_has_j_send_result_params_validations_using_active_model_validations_plugin
         ##
         # - https://edgeguides.rubyonrails.org/active_model_basics.html
         # - https://api.rubyonrails.org/classes/ActiveModel.html
@@ -183,12 +332,11 @@ module ConvenientService
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_has_j_send_result_params_validations_using_dry_validation
+      def require_has_j_send_result_params_validations_using_dry_validation_plugin
         ##
         # - https://dry-rb.org/gems/dry-validation/main/
         # - https://github.com/dry-rb/dry-validation
@@ -199,22 +347,25 @@ module ConvenientService
       end
 
       ##
-      # @api public
+      # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_rescues_result_unhandled_exceptions
-        require "convenient_service/service/plugins/rescues_result_unhandled_exceptions"
+      def require_has_memoization_using_memo_wise_plugin
+        ##
+        # - https://github.com/panorama-ed/memo_wise
+        #
+        require "memo_wise"
+
+        require "convenient_service/common/plugins/has_memoization/using_memo_wise"
       end
 
       ##
       # @api private
       #
       # @return [Boolean]
-      # @note Expected to be called from app entry points like `initializers` in Rails.
       #
-      def require_wraps_result_in_db_transaction
+      def require_wraps_result_in_db_transaction_using_active_record_base_transaction_plugin
         ##
         # - https://edgeguides.rubyonrails.org/active_record_basics.html
         # - https://api.rubyonrails.org/classes/ActiveRecord.html
@@ -222,7 +373,7 @@ module ConvenientService
         #
         require "active_record"
 
-        require "convenient_service/service/plugins/wraps_result_in_db_transaction"
+        require "convenient_service/service/plugins/wraps_result_in_db_transaction/using_active_record_base_transaction"
       end
 
       ##
@@ -237,6 +388,8 @@ module ConvenientService
       #   - https://github.com/deivid-rodriguez/byebug/issues/179#issuecomment-152727003
       #
       def require_development_tools(amazing_print: false, awesome_print: true)
+        return if ci?
+
         ##
         # - https://github.com/awesome-print/awesome_print
         #
@@ -255,7 +408,7 @@ module ConvenientService
         ##
         # - https://github.com/deivid-rodriguez/byebug
         #
-        require "byebug" if ruby.mri?
+        require "byebug" if support_byebug?
 
         ##
         # - https://github.com/ruby/debug
@@ -273,10 +426,15 @@ module ConvenientService
         #
         require "paint"
 
+        ##
+        # - https://github.com/ruby/pp
+        #
+        require "pp"
+
         ##
         # - https://github.com/rouge-ruby/rouge
         #
-        require "rouge"
+        require "rouge" if support_byebug?
 
         ##
         # - https://ruby-doc.org/stdlib-2.7.0/libdoc/tempfile/rdoc/Tempfile.html
@@ -284,22 +442,17 @@ module ConvenientService
         #
         require "tempfile"
 
-        ##
-        # - https://gist.github.com/marian13/5dade20a431d7254db30e543167058ce
-        #
-        require "convenient_service/dependencies/extractions/byebug_syntax_highlighting" if ruby.mri?
-
-        require "convenient_service/dependencies/extractions/b" if ruby.mri?
+        require "convenient_service/debug/convenient_service"
 
-        ##
-        #
-        #
-        require "convenient_service/dependencies/extractions/ce"
+        require "convenient_service/debug/b" if support_byebug?
+        require "convenient_service/debug/byebug_syntax_highlighting" if support_byebug?
+        require "convenient_service/debug/bb" if ruby.mri?
+        require "convenient_service/debug/ce"
+        require "convenient_service/debug/ds"
 
-        ##
-        #
-        #
-        require "convenient_service/dependencies/extractions/ds"
+        require "convenient_service/debug/thread_backtraces"
+        require "convenient_service/debug/break"
+        require "convenient_service/debug/timeout"
       end
 
       ##
@@ -309,6 +462,11 @@ module ConvenientService
       # @note Expected to be called from `spec_helper.rb`.
       #
       def require_test_tools
+        ##
+        # - https://github.com/janlelis/paint
+        #
+        require "paint"
+
         ##
         # - https://github.com/faker-ruby/faker
         #
@@ -320,6 +478,12 @@ module ConvenientService
         #
         require "ostruct"
 
+        ##
+        # - https://ruby-doc.org/stdlib-2.7.0/libdoc/strscan/rdoc/StringScanner.html
+        # - https://github.com/ruby/strscan
+        #
+        require "strscan"
+
         ##
         # - https://ruby-doc.org/stdlib-2.7.0/libdoc/tempfile/rdoc/Tempfile.html
         # - https://github.com/ruby/tempfile
@@ -328,7 +492,7 @@ module ConvenientService
       end
 
       ##
-      # @api public
+      # @api private
       #
       # Loads RSpec extensions like `be_success` matcher, `stub_service` helper, etc.
       #
@@ -340,6 +504,9 @@ module ConvenientService
         require "rspec/matchers"
         require "rspec/mocks"
 
+        require "convenient_service/service/plugins/can_have_rspec_stubbed_results"
+        require "convenient_service/feature/plugins/can_have_rspec_stubbed_entries"
+
         require "convenient_service/rspec"
       end
 
@@ -387,7 +554,6 @@ module ConvenientService
         require ::File.join("convenient_service", "examples", "standard", version, "factorial")
         require ::File.join("convenient_service", "examples", "standard", version, "gemfile")
         require ::File.join("convenient_service", "examples", "standard", version, "request_params")
-        require ::File.join("convenient_service", "examples", "standard", version, "comprehensive_suite") if version.empty?
       end
 
       ##
@@ -451,7 +617,7 @@ module ConvenientService
       ##
       # @api private
       #
-      # @return [ConvenientService::Dependencies::Queries::Ruby]
+      # @return [Class<ConvenientService::Dependencies::Queries::Ruby>]
       #
       def ruby
         Ruby
@@ -460,7 +626,16 @@ module ConvenientService
       ##
       # @api private
       #
-      # @return [ConvenientService::Dependencies::Queries::RSpec]
+      # @return [Class<ConvenientService::Dependencies::Queries::Gems::Minitest>]
+      #
+      def minitest
+        Gems::Minitest
+      end
+
+      ##
+      # @api private
+      #
+      # @return [Class<ConvenientService::Dependencies::Queries::Gems::RSpec>]
       #
       def rspec
         Gems::RSpec
@@ -469,7 +644,7 @@ module ConvenientService
       ##
       # @api private
       #
-      # @return [ConvenientService::Dependencies::Queries::Gems::ActiveModel]
+      # @return [Class<ConvenientService::Dependencies::Queries::Gems::ActiveModel>]
       #
       def active_model
         Gems::ActiveModel
@@ -478,7 +653,7 @@ module ConvenientService
       ##
       # @api private
       #
-      # @return [ConvenientService::Dependencies::Queries::Gems::Logger]
+      # @return [Class<ConvenientService::Dependencies::Queries::Gems::Logger>]
       #
       def logger
         Gems::Logger
@@ -487,7 +662,7 @@ module ConvenientService
       ##
       # @api private
       #
-      # @return [ConvenientService::Dependencies::Queries::Gems::Paint]
+      # @return [Class<ConvenientService::Dependencies::Queries::Gems::Paint>]
       #
       def paint
         Gems::Paint

data/lib/convenient_service/dependencies.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
 require_relative "dependencies/built_in"
 require_relative "dependencies/extractions"
 require_relative "dependencies/queries"
 
-##
-# `ConvenientService::Dependencies` can dynamically require plugins/extensions that have external dependencies.
-#
-# @internal
-#   https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
-#
 module ConvenientService
+  ##
+  # `ConvenientService::Dependencies` can dynamically require plugins/extensions that have external dependencies.
+  #
+  # @internal
+  #   https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
+  #
   module Dependencies
     extend Queries
   end

data/lib/convenient_service/exception.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
   ##
   # Base class for all `ConvenientService` exceptions.

data/lib/convenient_service/extras/alias.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+##
+# NOTE: This file is loaded by `require "convenient_service/alias"`.
+# NOTE: This file is expected to be called from app entry points like `initializers` in Rails.
+##
+
+##
+# @!visibility private
+#
+require "convenient_service"
+
+ConvenientService::Dependencies.require_alias
+
+##
+# `CS` is just an alias for `ConvenientService`. It becames available by `require "convenient_service/extra/alias"`.
+#
+# @api public
+# @since 1.0.0
+#
+# @internal
+#   NOTE: Added for visibility in YARD docs.
+#
+module CS
+end

data/lib/convenient_service/extras/plugins/assigns_attributes_in_constructor/using_active_model_attribute_assignment.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+##
+# NOTE: This file is loaded by `require "convenient_service/extras/plugins/assigns_attributes_in_constructor/using_active_model_attribute_assignment"`.
+# NOTE: This file is expected to be called from app entry points like `initializers` in Rails.
+#
+# @!visibility private
+#
+require "convenient_service"
+
+ConvenientService::Dependencies.require_assigns_attributes_in_constructor_using_active_model_attribute_assignment_plugin

data/lib/convenient_service/extras/plugins/assigns_attributes_in_constructor/using_dry_initializer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+##
+# NOTE: This file is loaded by `require "convenient_service/extras/plugins/assigns_attributes_in_constructor/using_dry_initializer"`.
+# NOTE: This file is expected to be called from app entry points like `initializers` in Rails.
+#
+# @!visibility private
+#
+require "convenient_service"
+
+ConvenientService::Dependencies.require_assigns_attributes_in_constructor_using_dry_initializer_plugin

data/lib/convenient_service/extras/plugins/has_attributes/using_active_model_attributes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+##
+# NOTE: This file is loaded by `require "convenient_service/extras/plugins/has_attributes/using_active_model_attributes"`.
+# NOTE: This file is expected to be called from app entry points like `initializers` in Rails.
+#
+# @!visibility private
+#
+require "convenient_service"
+
+ConvenientService::Dependencies.require_has_attributes_using_active_model_attributes_plugin

data/lib/convenient_service/extras/plugins/has_j_send_result_params_validations/using_active_model_validations.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+##
+# NOTE: This file is loaded by `require "convenient_service/extras/plugins/has_j_send_result_params_validations/using_active_model_validations"`.
+# NOTE: This file is expected to be called from app entry points like `initializers` in Rails.
+#
+# @!visibility private
+#
+require "convenient_service"
+
+ConvenientService::Dependencies.require_has_j_send_result_params_validations_using_active_model_validations_plugin