convenient_service 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a82b04aed6d540c497da63b9398dc605319c95b6aeed0152edfa03c3e82f9f0d
-  data.tar.gz: 68ed1a1f53824b237f3cf322ae0130cec5ee04743368b84c536017f8d676e848
+  metadata.gz: dc0b70a8a73f6bffd654e90e8ad332f0132b7ea83255ad56860c6e3ac454492c
+  data.tar.gz: e9be9fdaf668c6fdd510b27af3a04b9fa01582891478c95cab72320236926939
 SHA512:
-  metadata.gz: 4ff920321871a94fb2424e2d732574494471560fd5d2f7e97abecd44822e755f2de1b38161e5afa31da98b32ff7bd71576d50c1352ef64530ceabaf34f65e372
-  data.tar.gz: '080d31c61846cb2d53dc771708deddbd0fb84252369baa663b7a57f740d8d082cc6e4d6893bdc3f82ca92653968646c9723b319aee753bdada09d2cf935ad69f'
+  metadata.gz: 372f4e96c265835df11321a7e30e2a8aaf5544ab6fea1d9b89084e4f1687a6399dbb72bea80b730fab31c5bc44722e0647260e717f518201c36a5e575f2cf074
+  data.tar.gz: 84852e20f09454a0181fc1438205f4ef446aba65d86c3c391838f4b340eb31546fe7e2bdd226da8bfc94c9d2ef80bf5e23c884d00282ef966c5384840f79e207

data/README.md

@@ -28,6 +28,8 @@
 [![Patreon](https://img.shields.io/badge/patreon-donate-orange.svg)](https://www.patreon.com/user?u=31435716&fan_landing=true)
 [![License: LGPL-3.0](https://img.shields.io/badge/license-LGPL--3.0-yellow.svg)](https://www.gnu.org/licenses/lgpl-3.0.html)
 
+[![GitHub Repo](https://img.shields.io/badge/github-repo-blue?logo=github)](https://github.com/marian13/convenient_service) [![GitLab Mirror](https://img.shields.io/badge/gitlab-mirror-orange?logo=gitlab)](https://gitlab.com/marian13/convenient_service) [![Codeberg Mirror](https://img.shields.io/badge/codeberg-mirror-green?logo=codeberg)](https://codeberg.org/marian13/convenient_service)
+
 <!-- NOTE: The "Visit Count" and the "Inline Docs" badges are commented since they are failing with errors most of the time -->
 <!-- ![visitors](https://visitor-badge.glitch.me/badge?page_id=marian13/convenient_service) -->
 <!-- [![inline docs](http://inch-ci.org/github/marian13/convenient_service.svg?branch=main)](http://inch-ci.org/github/marian13/convenient_service) -->
@@ -41,7 +43,11 @@
 <!-- logo:end -->
 
 <!-- general_description:start -->
-Yet another approach to revisit the service object pattern, but this time focusing on the unique, opinionated features.
+Manage complex business logic in Ruby applications using Service Objects with Results and Steps.
+
+Hide technical details with Configs, Concerns and Middlewares.
+
+Group related code with Features and Entries.
 <!-- general_description:end -->
 
 <!-- warning:start -->
@@ -73,12 +79,10 @@ This library is on the final stage of development before the v1.0.0 version. 90%
 
 - Have a look at [Convenient Service Development Wiki](https://github.com/marian13/convenient_service/wiki) for the contribution tutorials.
 
-- [Backlog](https://github.com/marian13/convenient_service/blob/main/BACKLOG.md).
-
 <!-- links:end -->
 
 ---
 
 <!-- author:start -->
-Copyright (c) 2022-2025 Marian Kostyk.
+Copyright (c) 2022-2026 Marian Kostyk.
 <!-- author:end -->

data/lib/convenient_service/aliases.rb

@@ -9,10 +9,122 @@
 # @internal
 #   NOTE: Aliases hide the full constants path from the end-users in order to increase DX.
 #   - https://en.wikipedia.org/wiki/User_experience#Developer_experience
-#
+##
+
 module ConvenientService
+  ##
+  # Convenient Service command (aka operation without results and steps).
+  # Useful for utils that are always "successful".
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [Class]
+  #
+  # @example Common usage.
+  #   class ToBool < ConvenientService::Command
+  #     attr_reader :object
+  #
+  #     def initialize(object)
+  #       @object = object
+  #     end
+  #
+  #     def call
+  #       !!object
+  #     end
+  #   end
+  #
+  #   ToBool.new(42).call
+  #   # => true
+  #
+  #   ToBool.call(42)
+  #   # => true
+  #
+  #   ToBool.(42)
+  #   # => true
+  #
+  #   ToBool[42]
+  #   # => true
+  #
+  # @example No need to define class `call` method.
+  #   class Command < ConvenientService::Command
+  #     # ...
+  #
+  #     ##
+  #     # Class `call` method in already defined in `ConvenientService::Command` like so:
+  #     #
+  #     # def call(...)
+  #     #   new.call(...)
+  #     # end
+  #     ##
+  #
+  #     # ...
+  #   end
+  #
   Command = ::ConvenientService::Support::Command
+
+  ##
+  # Convenient Service concern (Like Rails concern, but with some customizations).
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [Module]
+  #
+  # @note Expected to be used from Convenient Service plugins.
+  #
   Concern = ::ConvenientService::Support::Concern
+
+  ##
+  # Convenient Service dependency container.
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [Module]
+  #
+  # @example Common usage.
+  #   module Container
+  #     include ConvenientService::DependencyContainer::Export
+  #
+  #     export "foo" do |*args|
+  #       "foo"
+  #     end
+  #
+  #     export :bar do |**kwargs|
+  #       "bar"
+  #     end
+  #
+  #     export :baz do |&block|
+  #       "baz"
+  #     end
+  #   end
+  #
+  #   class User
+  #     include ConvenientService::DependencyContainer::Import
+  #
+  #     import :foo, from: Container
+  #     import "bar", as: :custom_bar, from: Container
+  #     import :baz, as: "namespaced.baz", from: Container
+  #   end
+  #
+  #   User.new.foo
+  #   # => "foo"
+  #
+  #   User.new.custom_bar
+  #   # => "bar"
+  #
+  #   User.new.namespaced.baz
+  #   # => "baz"
+  #
   DependencyContainer = ::ConvenientService::Support::DependencyContainer
+
+  ##
+  # Convenient Service base result class. Useful as a shortcut for result utilities.
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [Class]
+  #
+  # @example How to check whether an object is a result?
+  #   ConvenintService::Result.result?(some_object)
+  #
   Result = ::ConvenientService::Service::Plugins::HasJSendResult::Entities::Result
 end

data/lib/convenient_service/common/plugins/aliases.rb

@@ -6,7 +6,76 @@
 ##
 
 module ConvenientService
+  ##
+  # Intermediate module/namespace to access plugins. See `Constant Summary` for examples.
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [Module]
+  #
   module Plugins
+    ##
+    # Intermediate module/namespace to access plugins that can be applied to several types of entities.
+    #
+    # @api public
+    # @since 1.0.0
+    # @return [Module]
+    #
+    # @example Common plugin `CanHaveCallbacks` is used by both services and steps.
+    #   ##
+    #   # Since the `CanHaveCallbacks` common plugin is included by default by the standard config,
+    #   # the example below shows how to remove it instead of adding it.
+    #   #
+    #   class Service
+    #     include ConvenientService::Standard::Config
+    #
+    #     concerns do
+    #       delete ConvenientService::Plugins::Common::CanHaveCallbacks::Concern
+    #     end
+    #
+    #     middlewares :result do
+    #       delete ConvenientService::Plugins::Common::CanHaveCallbacks::Middleware
+    #     end
+    #
+    #     entity :Step do
+    #       concerns do
+    #         delete ConvenientService::Plugins::Common::CanHaveCallbacks::Concern
+    #       end
+    #
+    #       middlewares :result do
+    #         delete ConvenientService::Plugins::Common::CanHaveCallbacks::Middleware
+    #       end
+    #     end
+    #
+    #     ##
+    #     # Raises since `CanHaveCallbacks` is removed.
+    #     #
+    #     before :result do
+    #     end
+    #
+    #     def result
+    #       success
+    #     end
+    #   end
+    #
+    # @example Shorter way to remove `CanHaveCallbacks` plugin.
+    #   ##
+    #   # Some common plugin groups like `:callbacks` can be removed by config option.
+    #   #
+    #   class Service
+    #     include ConvenientService::Standard::Config.without(:callbacks)
+    #
+    #     ##
+    #     # Raises since `CanHaveCallbacks` is removed.
+    #     #
+    #     before :result do
+    #     end
+    #
+    #     def result
+    #       success
+    #     end
+    #   end
+    #
     Common = ::ConvenientService::Common::Plugins
   end
 end

data/lib/convenient_service/common/plugins/can_have_callbacks/entities/type_collection.rb

@@ -22,7 +22,7 @@ module ConvenientService
             # @return [void]
             #
             def initialize(types:)
-              @types = types.map(&Entities::Type.method(:cast!))
+              @types = types.map { |type| Entities::Type.cast!(type) }
             end
 
             ##
@@ -30,7 +30,7 @@ module ConvenientService
             # @return [Boolean]
             #
             def contain_exactly?(other_types)
-              other_types = other_types.map(&Entities::Type.method(:cast!))
+              other_types = other_types.map { |type| Entities::Type.cast!(type) }
 
               Utils::Array.contain_exactly?(types, other_types)
             end

data/lib/convenient_service/common/plugins/has_instance_proxy/entities/instance_proxy.rb

@@ -10,7 +10,7 @@ module ConvenientService
     module Plugins
       module HasInstanceProxy
         module Entities
-          class InstanceProxy
+          class InstanceProxy < ::BasicObject
             ##
             # @api private
             #
@@ -33,13 +33,13 @@ module ConvenientService
             ##
             # @return [Class]
             #
-            alias_method :instance_proxy_class, :class
-
-            ##
-            # @return [Class]
+            # @internal
+            #   NOTE: `alias_method :instance_proxy_class, :class` does NOT work, since `BasicObject` does NOT have `class` method. It is defined in `Kernel`.
+            #   - https://ruby-doc.org/core-3.0.2/Kernel.html#method-i-class
+            #   - https://ruby-doc.org/core-2.7.0/UnboundMethod.html#method-i-bind_call
             #
-            def class
-              instance_proxy_target.class
+            def instance_proxy_class
+              ::Kernel.instance_method(:class).bind_call(self)
             end
 
             ##
@@ -49,7 +49,7 @@ module ConvenientService
             # @return [Boolean, nil]
             #
             def ==(other)
-              return unless other.instance_of?(instance_proxy_class)
+              return unless ::Kernel.instance_method(:instance_of?).bind_call(other, instance_proxy_class)
 
               return false if instance_proxy_target != other.instance_proxy_target
 

data/lib/convenient_service/common.rb

@@ -6,3 +6,17 @@
 ##
 
 require_relative "common/plugins"
+
+module ConvenientService
+  ##
+  # Intermediate module/namespace to access plugins that can be applied to several types of entities.
+  #
+  # @api private
+  # @since 1.0.0
+  # @return [Module]
+  #
+  # @note Common plugins expected to be used via {ConvenientService::Plugins::Common} alias.
+  #
+  module Common
+  end
+end

data/lib/convenient_service/config.rb

@@ -129,6 +129,14 @@ module ConvenientService
               @options ||= default_options.dup
             end
 
+            ##
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Config::Entities::OptionCollection]
+            #
+            def available_options(&block)
+              block ? @available_options = Commands::NormalizeOptions[options: yield] : @available_options ||= empty_options
+            end
+
             ##
             # @param block [Proc, nil]
             # @return [ConvenientService::Config::Entities::OptionCollection]

data/lib/convenient_service/core/aliases.rb

@@ -6,8 +6,92 @@
 ##
 
 module ConvenientService
+  ##
+  # Base class for concern middlewares.
+  #
+  # @api private
+  # @since 1.0.0
+  # @return [Class]
+  #
   ConcernMiddleware = ::ConvenientService::Core::Entities::Config::Entities::Concerns::Entities::Middleware
 
+  ##
+  # Base class for method middlewares using classic `stack.call`.
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [Class]
+  #
+  # @note Prefer `ConvenientService::MethodChainMiddleware`.
+  #
+  # @example Common usage.
+  #   class Middleware < ConvenientService::MethodClassicMiddleware
+  #     def call(env)
+  #       p env
+  #
+  #       value = stack.call(env)
+  #
+  #       p value
+  #
+  #       value
+  #     end
+  #   end
+  #
+  #   class Service
+  #     include ConvenientService::Standard::Config
+  #
+  #     middlewares :result do
+  #       insert_before 0, Middleware
+  #     end
+  #
+  #     def result
+  #       success
+  #     end
+  #   end
+  #
+  #   Service.result
+  #   # {args: [], kwargs: {}, block: nil, entity: <Service>, method: :result}
+  #   # <Service::Result status: :success>
+  #   # => <Service::Result status: :success>
+  #
   MethodClassicMiddleware = ::ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Classic
+
+  ##
+  # Base class for method middlewares using `chain.next`.
+  #
+  # @api public
+  # @since 1.0.0
+  # @return [Class]
+  #
+  # @example Common usage.
+  #   class Middleware < ConvenientService::MethodChainMiddleware
+  #     def next(*args, **kwargs, &block)
+  #       p [args, kwargs, block]
+  #
+  #       value = chain.next(*args, **kwargs, &block)
+  #
+  #       p value
+  #
+  #       value
+  #     end
+  #   end
+  #
+  #   class Service
+  #     include ConvenientService::Standard::Config
+  #
+  #     middlewares :result do
+  #       insert_before 0, Middleware
+  #     end
+  #
+  #     def result
+  #       success
+  #     end
+  #   end
+  #
+  #   Service.result
+  #   # {args: [], kwargs: {}, block: nil, entity: <Service>, method: :result}
+  #   # <Service::Result status: :success>
+  #   # => <Service::Result status: :success>
+  #
   MethodChainMiddleware = ::ConvenientService::Core::Entities::Config::Entities::MethodMiddlewares::Entities::Middlewares::Chain
 end

data/lib/convenient_service/dependencies/built_in.rb

@@ -9,7 +9,10 @@
 # This file loads built-in dependencies (from Ruby standard library).
 #
 # @internal
-#   https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
+#   - https://github.com/marian13/convenient_service/wiki/Docs:-Dependencies
+#
+#   NOTE: Ensure all `require` for built-in dependencies are explicit.
+#   - https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Lint/RedundantRequireStatement
 ##
 
 ##
@@ -65,4 +68,15 @@ require "singleton"
 #
 # @!visibility private
 #
+# rubocop:disable Lint/RedundantRequireStatement
 require "thread"
+# rubocop:enable Lint/RedundantRequireStatement
+
+##
+# @internal
+#   - https://ruby-doc.org/stdlib-2.7.0/libdoc/set/rdoc/Set.html
+#   - https://github.com/ruby/set
+#
+# @!visibility private
+#
+require "set"

data/lib/convenient_service/dependencies/only_queries.rb

@@ -25,12 +25,6 @@ require "rubygems"
 #
 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

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+##
+# @author Marian Kostyk <mariankostyk13895@gmail.com>
+# @license LGPLv3 <https://www.gnu.org/licenses/lgpl-3.0.html>
+##
+
+module ConvenientService
+  module Dependencies
+    module Queries
+      module Gems
+        ##
+        # @api private
+        #
+        class Minitest
+          class << self
+            ##
+            # @return [Boolean]
+            #
+            # @internal
+            #   `Style/TernaryParentheses` is disabled since `defined?` has too low priority without parentheses.
+            #
+            # rubocop:disable Style/TernaryParentheses
+            def loaded?
+              (defined? ::Minitest) ? true : false
+            end
+            # rubocop:enable Style/TernaryParentheses
+
+            ##
+            # @return [ConvenientService::Dependencies::Queries::Version]
+            #
+            # @internal
+            #   - https://github.com/minitest/minitest/blob/master/lib/minitest.rb
+            #
+            def version
+              loaded? ? Version.new(::Minitest::VERSION) : Version.null_version
+            end
+
+            ##
+            # @internal
+            #   Minitest does NOT have `::RSpec.current_example` equivalent.
+            #   -
+            #
+            # def current_example
+            #   return unless loaded?
+            #
+            #   # ...
+            # end
+            ##
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -30,7 +30,7 @@ module ConvenientService
             # @return [ConvenientService::Dependencies::Queries::Version]
             #
             # @internal
-            #   https://github.com/rspec/rspec-core/blob/main/lib/rspec/core/version.rb
+            #   - 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

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

@@ -8,4 +8,6 @@
 require_relative "gems/active_model"
 require_relative "gems/logger"
 require_relative "gems/paint"
+
+require_relative "gems/minitest"
 require_relative "gems/rspec"

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

@@ -86,7 +86,7 @@ module ConvenientService
           # @see https://github.com/rdp/os
           #
           def jruby?
-            engine.match?(/jruby/)
+            engine.include?("jruby")
           end
 
           ##
@@ -95,7 +95,7 @@ module ConvenientService
           # @return [Boolean]
           #
           def truffleruby?
-            engine.match?(/truffleruby/)
+            engine.include?("truffleruby")
           end
 
           ##