convenient_service 0.11.0 → 0.12.0

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status/concern.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "concern/class_methods"
+require_relative "concern/instance_methods"
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Entities
+                  class Status
+                    module Concern
+                      include Support::Concern
+
+                      included do |code_class|
+                        code_class.include Support::Castable
+
+                        code_class.include InstanceMethods
+
+                        code_class.extend ClassMethods
+                      end
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_j_send_status_and_attributes/entities/status.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "status/concern"
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasResult
+        module Entities
+          class Result
+            module Plugins
+              module HasJSendStatusAndAttributes
+                module Entities
+                  class Status
+                    include Concern
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/{has_jsend_status_and_attributes → has_j_send_status_and_attributes}/errors.rb

@@ -7,9 +7,13 @@ module ConvenientService
         module Entities
           class Result
             module Plugins
-              module HasJsendStatusAndAttributes
+              module HasJSendStatusAndAttributes
                 module Errors
-                  class NotExistingAttribute < ConvenientService::Error
+                  class NotExistingAttribute < ::ConvenientService::Error
+                    ##
+                    # @param attribute [Symbol]
+                    # @return [void]
+                    #
                     def initialize(attribute:)
                       message = <<~TEXT
                         Data attribute `#{attribute}` does NOT exist. Make sure the corresponding result returns it.

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/{has_jsend_status_and_attributes → has_j_send_status_and_attributes}/middleware.rb

@@ -7,12 +7,12 @@ module ConvenientService
         module Entities
           class Result
             module Plugins
-              module HasJsendStatusAndAttributes
+              module HasJSendStatusAndAttributes
                 class Middleware < Core::MethodChainMiddleware
                   ##
-                  # @param args [Array]
-                  # @param kwargs [Hash]
-                  # @param block [Proc]
+                  # @param args [Array<Object>]
+                  # @param kwargs [Hash{Symbol => Object}]
+                  # @param block [Proc, nil]
                   # @return [void]
                   #
                   def next(*args, **kwargs, &block)

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/{has_jsend_status_and_attributes/structs/jsend_attributes.rb → has_j_send_status_and_attributes/structs/j_send_attributes.rb}

@@ -7,7 +7,7 @@ module ConvenientService
         module Entities
           class Result
             module Plugins
-              module HasJsendStatusAndAttributes
+              module HasJSendStatusAndAttributes
                 module Structs
                   JSendAttributes = ::Struct.new(:service, :status, :data, :message, :code, keyword_init: true)
                 end

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_j_send_status_and_attributes/structs.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "structs/j_send_attributes"

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_j_send_status_and_attributes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "has_j_send_status_and_attributes/commands"
+require_relative "has_j_send_status_and_attributes/concern"
+require_relative "has_j_send_status_and_attributes/entities"
+require_relative "has_j_send_status_and_attributes/errors"
+require_relative "has_j_send_status_and_attributes/middleware"
+require_relative "has_j_send_status_and_attributes/structs"

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/has_result_short_syntax/concern.rb

@@ -31,21 +31,21 @@ module ConvenientService
                     end
 
                     ##
-                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Data]
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Data]
                     #
                     def ud
                       unsafe_data
                     end
 
                     ##
-                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Message]
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Message]
                     #
                     def um
                       unsafe_message
                     end
 
                     ##
-                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJsendStatusAndAttributes::Entities::Code]
+                    # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result::Plugins::HasJSendStatusAndAttributes::Entities::Code]
                     #
                     def uc
                       unsafe_code

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins/raises_on_not_checked_result_status/errors.rb

@@ -9,7 +9,7 @@ module ConvenientService
             module Plugins
               module RaisesOnNotCheckedResultStatus
                 module Errors
-                  class StatusIsNotChecked < ConvenientService::Error
+                  class StatusIsNotChecked < ::ConvenientService::Error
                     def initialize(attribute:)
                       message = <<~TEXT
                         Attribute `#{attribute}` is accessed before result status is checked.

data/lib/convenient_service/service/plugins/has_result/entities/result/plugins.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "plugins/can_recalculate_result"
-require_relative "plugins/has_jsend_status_and_attributes"
+require_relative "plugins/has_j_send_status_and_attributes"
 require_relative "plugins/has_inspect"
 require_relative "plugins/has_step"
 require_relative "plugins/can_have_parent_result"
 require_relative "plugins/has_result_short_syntax"
 require_relative "plugins/marks_result_status_as_checked"
 require_relative "plugins/raises_on_not_checked_result_status"
+
+require_relative "plugins/aliases"

data/lib/convenient_service/service/plugins/has_result/errors.rb

@@ -5,7 +5,7 @@ module ConvenientService
     module Plugins
       module HasResult
         module Errors
-          class ResultIsNotOverridden < ConvenientService::Error
+          class ResultIsNotOverridden < ::ConvenientService::Error
             def initialize(service:)
               message = <<~TEXT
                 Result method (#result) of `#{service.class}` is NOT overridden.
@@ -15,7 +15,7 @@ module ConvenientService
             end
           end
 
-          class ServiceReturnValueNotKindOfResult < ConvenientService::Error
+          class ServiceReturnValueNotKindOfResult < ::ConvenientService::Error
             def initialize(service:, result:)
               message = <<~TEXT
                 Return value of service `#{service.class}` is NOT a `Result`.

data/lib/convenient_service/service/plugins/has_result_status_check_short_syntax/concern.rb

@@ -55,6 +55,22 @@ module ConvenientService
             def not_failure?(...)
               result(...).not_failure?
             end
+
+            ##
+            # @return [Boolean]
+            # @since 0.12.0
+            #
+            def ok?(...)
+              result(...).success?
+            end
+
+            ##
+            # @return [Boolean]
+            # @since 0.12.0
+            #
+            def not_ok?(...)
+              result(...).not_success?
+            end
           end
         end
       end

data/lib/convenient_service/service/plugins/raises_on_double_result/errors.rb

@@ -5,7 +5,7 @@ module ConvenientService
     module Plugins
       module RaisesOnDoubleResult
         module Errors
-          class DoubleResult < ConvenientService::Error
+          class DoubleResult < ::ConvenientService::Error
             def initialize(service:)
               message = <<~TEXT
                 `#{service.class}` service has a double result.

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/commands/format_backtrace.rb

@@ -28,7 +28,7 @@ module ConvenientService
             #   - https://blog.kalina.tech/2019/04/exception-without-backtrace-in-ruby.html
             #   - https://github.com/jruby/jruby/issues/4467
             #
-            def initialize(backtrace:, max_size:)
+            def initialize(backtrace:, max_size: Constants::DEFAULT_MAX_BACKTRACE_SIZE)
               @backtrace = backtrace.to_a
               @max_size = max_size
             end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/commands/format_exception.rb

@@ -12,6 +12,12 @@ module ConvenientService
             #
             attr_reader :exception
 
+            ##
+            # @!attribute [r] max_backtrace_size
+            #   @return [Integer]
+            #
+            attr_reader :max_backtrace_size
+
             ##
             # @!attribute [r] args
             #   @return [StandardError]
@@ -32,16 +38,18 @@ module ConvenientService
 
             ##
             # @param exception [StandardError]
-            # @param args [Array]
-            # @param kwargs [Hash]
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
             # @param block [Proc, nil]
+            # @param max_backtrace_size [Integer]
             # @return [void]
             #
-            def initialize(exception:, args:, kwargs:, block:)
+            def initialize(exception:, args:, kwargs:, block:, max_backtrace_size: Constants::DEFAULT_MAX_BACKTRACE_SIZE)
               @exception = exception
               @args = args
               @kwargs = kwargs
               @block = block
+              @max_backtrace_size = max_backtrace_size
             end
 
             ##
@@ -179,13 +187,6 @@ module ConvenientService
             def formatted_exception_cause
               Commands::FormatCause.call(cause: exception.cause)
             end
-
-            ##
-            # @return [Integer]
-            #
-            def max_backtrace_size
-              Constants::DEFAULT_MAX_BACKTRACE_SIZE
-            end
           end
         end
       end

data/lib/convenient_service/service/plugins/rescues_result_unhandled_exceptions/middleware.rb

@@ -6,8 +6,8 @@ module ConvenientService
       module RescuesResultUnhandledExceptions
         class Middleware < Core::MethodChainMiddleware
           ##
-          # @param args [Array]
-          # @param kwargs [Hash]
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
           # @param block [Proc, nil]
           # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
           #
@@ -29,8 +29,8 @@ module ConvenientService
 
           ##
           # @param exception [StandardError]
-          # @param args [Array]
-          # @param kwargs [Hash]
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
           # @param block [Proc, nil]
           # @return [ConvenientService::Service::Plugins::HasResult::Entities::Result]
           #
@@ -43,13 +43,20 @@ module ConvenientService
 
           ##
           # @param exception [StandardError]
-          # @param args [Array]
-          # @param kwargs [Hash]
+          # @param args [Array<Object>]
+          # @param kwargs [Hash{Symbol => Object}]
           # @param block [Proc, nil]
           # @return [String]
           #
           def format_exception(exception, *args, **kwargs, &block)
-            Commands::FormatException.call(exception: exception, args: args, kwargs: kwargs, block: block)
+            Commands::FormatException.call(exception: exception, args: args, kwargs: kwargs, block: block, max_backtrace_size: max_backtrace_size)
+          end
+
+          ##
+          # @return [Integer]
+          #
+          def max_backtrace_size
+            arguments.kwargs.fetch(:max_backtrace_size) { Constants::DEFAULT_MAX_BACKTRACE_SIZE }
           end
         end
       end

data/lib/convenient_service/services/run_own_method_in_organizer.rb

@@ -4,7 +4,7 @@ module ConvenientService
   module Services
     class RunOwnMethodInOrganizer
       module Errors
-        class MethodForStepIsNotDefined < ConvenientService::Error
+        class MethodForStepIsNotDefined < ::ConvenientService::Error
           def initialize(service_class:, method_name:)
             message = <<~TEXT
               Service #{service_class} tries to use `#{method_name}` method in a step, but it NOT defined.

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

@@ -4,7 +4,7 @@ module ConvenientService
   module Support
     module AbstractMethod
       module Errors
-        class AbstractMethodNotOverridden < ::StandardError
+        class AbstractMethodNotOverridden < ::ConvenientService::Error
           def initialize(instance:, method:)
             klass = instance.is_a?(::Class) ? instance : instance.class
             method_type = Utils::Object.resolve_type(instance)

data/lib/convenient_service/support/arguments.rb

@@ -24,9 +24,9 @@ module ConvenientService
       attr_reader :block
 
       ##
-      # @param args [Array]
-      # @param kwargs [Hash]
-      # @param block [Proc]
+      # @param args [Array<Object>]
+      # @param kwargs [Hash{Symbol => Object}]
+      # @param block [Proc, nil]
       # @return [void]
       #
       def initialize(*args, **kwargs, &block)

data/lib/convenient_service/support/cache/key.rb

@@ -5,9 +5,9 @@ module ConvenientService
     class Cache
       class Key
         ##
-        # @param args [Array]
-        # @param kwargs [Hash]
-        # @param block [Proc]
+        # @param args [Array<Object>]
+        # @param kwargs [Hash{Symbol => Object}]
+        # @param block [Proc, nil]
         # @return [void]
         #
         def initialize(*args, **kwargs, &block)

data/lib/convenient_service/support/cache.rb

@@ -98,7 +98,7 @@ module ConvenientService
 
       ##
       # @param key [Object] Can be any type.
-      # @param block [Proc]
+      # @param block [Proc, nil]
       # @return [Object] Can be any type.
       #
       # @internal

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

@@ -4,7 +4,7 @@ module ConvenientService
   module Support
     module Castable
       module Errors
-        class CastIsNotOverridden < ::StandardError
+        class CastIsNotOverridden < ::ConvenientService::Error
           def initialize(klass:)
             message = <<~TEXT
               Cast method (.cast) of `#{klass}` is NOT overridden.
@@ -14,7 +14,7 @@ module ConvenientService
           end
         end
 
-        class FailedToCast < ::StandardError
+        class FailedToCast < ::ConvenientService::Error
           def initialize(other:, klass:)
             message = <<~TEXT
               Failed to cast `#{other.inspect}` into `#{klass}`.

data/lib/convenient_service/support/counter.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    ##
+    # @internal
+    #   NOTE: `return` exits from the enclosing method. `break` from the iterator method. `next` from the block.
+    #   - https://github.com/ruby/spec/blob/master/language/return_spec.rb
+    #   - https://github.com/ruby/spec/blob/master/language/break_spec.rb
+    #   - https://github.com/ruby/spec/blob/master/language/next_spec.rb
+    #   - https://stackoverflow.com/a/1402764/12201472
+    #
+    class Counter
+      module Errors
+        class ValueAfterIncrementIsGreaterThanMaxValue < ::ConvenientService::Error
+          ##
+          # @param n [Integer]
+          # @param current_value [Integer]
+          # @param max_value [Integer]
+          # @return [void]
+          #
+          def initialize(n:, current_value:, max_value:)
+            message = <<~TEXT
+              Value after increment by `#{n}` is greater than the max value.
+
+              Current value is `#{current_value}`.
+
+              Max value is `#{max_value}`.
+            TEXT
+
+            super(message)
+          end
+        end
+
+        class ValueAfterDecrementIsLowerThanMinValue < ::ConvenientService::Error
+          ##
+          # @param n [Integer]
+          # @param current_value [Integer]
+          # @param min_value [Integer]
+          # @return [void]
+          #
+          def initialize(n:, current_value:, min_value:)
+            message = <<~TEXT
+              Value after decrement by `#{n}` is lower than the min value.
+
+              Current value is `#{current_value}`.
+
+              Min value is `#{min_value}`.
+            TEXT
+
+            super(message)
+          end
+        end
+      end
+
+      ##
+      # @!attribute [r] initial_value
+      #   @return [Integer]
+      #
+      attr_reader :initial_value
+
+      ##
+      # @!attribute [rw] current_value
+      #   @return [Integer]
+      #
+      attr_accessor :current_value
+
+      ##
+      # @!attribute [r] min_value
+      #   @return [Integer, Float::INFINITY]
+      #
+      attr_reader :min_value
+
+      ##
+      # @!attribute [r] max_value
+      #   @return [Integer, Float::INFINITY]
+      #
+      attr_reader :max_value
+
+      ##
+      # @param initial_value [Integer]
+      # @param min_value [Integer, -::Float::Infinity]
+      # @param max_value [Integer, Float::Infinity]
+      # @return [void]
+      #
+      # @note Do NOT rely on the fact that `min_value` and `max_value` are almost always `Integer` instances since they are set to `-Float::INFINITY` and `Float::INFINITY` by default.
+      # @note `Float::INFINITY` and `Integer` are just contextual ducks, NOT full ducks. For example, `Float::INFINITY.to_i` raises `FloatDomainError`.
+      #
+      def initialize(initial_value: 0, min_value: -::Float::INFINITY, max_value: ::Float::INFINITY)
+        @initial_value = initial_value
+        @current_value = initial_value
+        @min_value = min_value
+        @max_value = max_value
+        @lock = ::Mutex.new
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Redis and Concurrent Ruby.
+      #   - https://redis.io/commands/incr/
+      #   - https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicFixnum.html#increment-instance_method
+      #
+      def increment(n = 1)
+        return @current_value if @current_value + n > @max_value
+
+        @current_value += n
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      # @raise [ConvenientService::Support::ThreadSafeCounter::Errors::ValueAfterIncrementIsGreaterThanMaxValue]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Rails.
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save-21
+      #
+      def increment!(n = 1)
+        raise Errors::ValueAfterIncrementIsGreaterThanMaxValue.new(n: n, current_value: @current_value, max_value: @max_value) if @current_value + n > @max_value
+
+        @current_value += n
+      end
+
+      ##
+      # `bincrement` means boolean increment. Works exactly in the same way as `increment` except returns a boolean value.
+      # If incremented successfully then returns `true`, otherwise - returns `false`.
+      #
+      # @param n [Integer]
+      # @return [Boolean]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      def bincrement(n = 1)
+        return false if @current_value + n > @max_value
+
+        @current_value += n
+
+        true
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Redis and Concurrent Ruby.
+      #   - https://redis.io/commands/decr/
+      #   - https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicFixnum.html#decrement-instance_method
+      #
+      def decrement(n = 1)
+        return @current_value if @current_value - n < @min_value
+
+        @current_value -= n
+      end
+
+      ##
+      # @param n [Integer]
+      # @return [Integer]
+      # @raise [ConvenientService::Support::ThreadSafeCounter::Errors::ValueAfterDecrementIsLowerThanMinValue]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      #   NOTE: The name is inspired by Rails.
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save
+      #   - https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-save-21
+      #
+      def decrement!(n = 1)
+        raise Errors::ValueAfterDecrementIsLowerThanMinValue.new(n: n, current_value: @current_value, min_value: @min_value) if @current_value - n < @min_value
+
+        @current_value -= n
+      end
+
+      ##
+      # `bdecrement` means boolean decrement. Works exactly in the same way as `decrement` except returns a boolean value.
+      # If decremented successfully then returns `true`, otherwise - returns `false`.
+      #
+      # @param n [Integer]
+      # @return [Boolean]
+      #
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      def bdecrement(n = 1)
+        return false if @current_value - n < @min_value
+
+        @current_value -= n
+
+        true
+      end
+
+      ##
+      # @internal
+      #   NOTE: Instance variables are accessed directly to release the lock faster.
+      #
+      def reset
+        @current_value = @initial_value
+      end
+    end
+  end
+end

data/lib/convenient_service/support/dependency_container/commands/assert_valid_container.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Commands
+        class AssertValidContainer < Support::Command
+          ##
+          # @!attribute [r] container
+          #   @return [Module]
+          #
+          attr_reader :container
+
+          ##
+          # @param container [Module]
+          # @return [void]
+          #
+          def initialize(container:)
+            @container = container
+          end
+
+          ##
+          # @return [void]
+          # @raise [ConvenientService::Support::DependencyContainer::Errors::NotExportableModule]
+          #
+          def call
+            raise Errors::NotExportableModule.new(mod: container) unless Utils::Module.include_module?(container, DependencyContainer::Export)
+          end
+        end
+      end
+    end
+  end
+end