convenient_service 0.10.1 → 0.12.0

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/service/plugins.rb

@@ -4,12 +4,13 @@
 # NOTE: Order matters.
 #
 require_relative "plugins/can_recalculate_result"
+require_relative "plugins/can_have_method_steps"
+require_relative "plugins/can_have_result_step"
+require_relative "plugins/can_have_steps"
 require_relative "plugins/can_have_stubbed_result"
 require_relative "plugins/has_inspect"
 require_relative "plugins/has_result"
-require_relative "plugins/has_result_method_steps"
 require_relative "plugins/has_result_short_syntax"
-require_relative "plugins/has_result_steps"
 require_relative "plugins/raises_on_double_result"
 require_relative "plugins/wraps_result_in_db_transaction"
 require_relative "plugins/has_result_status_check_short_syntax"

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

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Commands
+        class AssertValidMethod < Support::Command
+          ##
+          # @!attribute [r] full_name
+          #   @return [String, Symbol]
+          #
+          attr_reader :full_name
+
+          ##
+          # @!attribute [r] scope
+          #   @return [Symbol]
+          #
+          attr_reader :scope
+
+          ##
+          # @!attribute [r] container
+          #   @return [Module]
+          #
+          attr_reader :container
+
+          ##
+          # @param full_name [String, Symbol]
+          # @param scope [Symbol]
+          # @param container[Module]
+          # @return [void]
+          #
+          def initialize(full_name:, scope:, container:)
+            @full_name = full_name
+            @scope = scope
+            @container = container
+          end
+
+          ##
+          # @return [void]
+          # @raise [ConvenientService::Support::DependencyContainer::Errors::NotExportedMethod]
+          #
+          def call
+            raise Errors::NotExportedMethod.new(method_name: full_name, method_scope: scope, mod: container) unless method
+          end
+
+          private
+
+          ##
+          # @return [ConvenientService::Support::DependencyContainer::Entities::Method, nil]
+          #
+          def method
+            container.exported_methods.find_by(full_name: full_name, scope: scope)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,12 +7,12 @@ module ConvenientService
         class AssertValidScope < Support::Command
           ##
           # @!attribute [r] scope
-          #   @return [Object]
+          #   @return [Symbol]
           #
           attr_reader :scope
 
           ##
-          # @param scope [Object]
+          # @param scope [Symbol]
           # @return [void]
           #
           def initialize(scope:)
@@ -20,7 +20,8 @@ module ConvenientService
           end
 
           ##
-          # @return [Module]
+          # @return [void]
+          # @raise [ConvenientService::Support::DependencyContainer::Errors::InvalidScope]
           #
           def call
             raise Errors::InvalidScope.new(scope: scope) unless Constants::SCOPES.include?(scope)

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Commands
+        class DefineEntry < Support::Command
+          ##
+          # @!attribute [r] container
+          #   @return [Module]
+          #
+          attr_reader :container
+
+          ##
+          # @!attribute [r] name
+          #   @return [String, Symbol]
+          #
+          attr_reader :name
+
+          ##
+          # @!attribute [r] body
+          #   @return [Proc]
+          #
+          attr_reader :body
+
+          ##
+          # @param container [Module]
+          # @param name [String, Symbol]
+          # @param body [Proc]
+          #
+          def initialize(container:, name:, body:)
+            @container = container
+            @name = name
+            @body = body
+          end
+
+          ##
+          # @return [String, Symbol]
+          #
+          def call
+            container.define_singleton_method(name, &body)
+
+            name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "commands/assert_valid_scope"
+require_relative "commands/assert_valid_container"
+require_relative "commands/assert_valid_method"
 require_relative "commands/create_methods_module"
+require_relative "commands/define_entry"
 require_relative "commands/import_method"

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Container
+        include Export
+
+        export :"constants.DEFAULT_SCOPE" do
+          Constants::DEFAULT_SCOPE
+        end
+
+        export :"commands.AssertValidContainer" do
+          Commands::AssertValidContainer
+        end
+
+        export :"commands.AssertValidScope" do
+          Commands::AssertValidScope
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Support
+    module DependencyContainer
+      module Entry
+        include Support::Concern
+
+        class_methods do
+          ##
+          # @param name [String, Symbol]
+          # @param body [Proc]
+          # @return [String, Symbol]
+          #
+          def entry(name, &body)
+            Commands::DefineEntry.call(container: self, name: name, body: body)
+          end
+        end
+      end
+    end
+  end
+end