convenient_service 0.14.0 → 0.16.0

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

@@ -9,6 +9,14 @@ module ConvenientService
 
           instance_methods do
             ##
+            # @api public
+            #
+            # @note May be useful for debugging purposes.
+            # @see https://marian13.github.io/convenient_service_docs/guides/how_to_debug_services_via_callbacks
+            #
+            # @note `steps` are frozen.
+            # @see https://marian13.github.io/convenient_service_docs/faq#is-it-possible-to-modify-the-step-collection-from-a-callback
+            #
             # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
             #
             # @internal
@@ -20,6 +28,7 @@ module ConvenientService
                   .steps
                   .tap(&:commit!)
                   .map { |step| step.copy(overrides: {kwargs: {organizer: self}}) }
+                  .freeze
               end
             end
 
@@ -52,9 +61,6 @@ module ConvenientService
             end
 
             ##
-            # @param value [Object] Can be any type.
-            # @return [ConvenientService::Support::RawValue]
-            #
             # Allows to pass a value to `in` method without its intermediate processing.
             # @see https://marian13.github.io/convenient_service_docs/basics/step_to_result_translation_table
             #

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/raises_on_not_result_return_value/exceptions.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module RaisesOnNotResultReturnValue
+                module Exceptions
+                  class ReturnValueNotKindOfResult < ::ConvenientService::Exception
+                    def initialize(step:, result:)
+                      message = <<~TEXT
+                        Return value of step `#{step.printable_service}` is NOT a `Result`.
+                        It is `#{result.class}`.
+
+                        Did you forget to call `success`, `failure`, or `error`?
+                      TEXT
+
+                      super(message)
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/raises_on_not_result_return_value/middleware.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module CanHaveSteps
+        module Entities
+          class Step
+            module Plugins
+              module RaisesOnNotResultReturnValue
+                class Middleware < MethodChainMiddleware
+                  include Support::DependencyContainer::Import
+
+                  import :"commands.is_result?", from: ::ConvenientService::Service::Plugins::HasJSendResult::Container
+
+                  intended_for any_method, entity: :step
+
+                  def next(...)
+                    original_result = chain.next(...)
+
+                    return original_result if commands.is_result?(original_result)
+
+                    raise Exceptions::ReturnValueNotKindOfResult.new(step: entity, result: original_result)
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins/raises_on_not_result_return_value.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "raises_on_not_result_return_value/exceptions"
+require_relative "raises_on_not_result_return_value/middleware"

data/lib/convenient_service/service/plugins/can_have_steps/entities/step/plugins.rb

@@ -6,5 +6,6 @@ require_relative "plugins/can_be_result_step"
 require_relative "plugins/can_have_fallbacks"
 require_relative "plugins/can_have_parent_result"
 require_relative "plugins/has_inspect"
+require_relative "plugins/raises_on_not_result_return_value"
 
 require_relative "plugins/aliases"

data/lib/convenient_service/service/plugins/can_have_steps/entities/step_collection.rb

@@ -9,12 +9,16 @@ module ConvenientService
             include ::Enumerable
 
             ##
+            # @api private
+            #
             # @!attribute [r] steps
             #   @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
             #
             attr_reader :steps
 
             ##
+            # @api private
+            #
             # @param steps [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>]
             # @return [void]
             #
@@ -23,6 +27,8 @@ module ConvenientService
             end
 
             ##
+            # @api public
+            #
             # @return [Boolean] true if called for the first time, false otherwise (similarly as Kernel#require).
             #
             # @see https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
@@ -41,6 +47,8 @@ module ConvenientService
             end
 
             ##
+            # @api public
+            #
             # @return [Boolean]
             #
             def committed?
@@ -48,6 +56,8 @@ module ConvenientService
             end
 
             ##
+            # @api public
+            #
             # @param block [Proc, nil]
             # @return [Array<ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step>, Enumerator]
             #
@@ -56,6 +66,8 @@ module ConvenientService
             end
 
             ##
+            # @api public
+            #
             # Returns step by index.
             #
             # @param index [Integer]
@@ -69,6 +81,8 @@ module ConvenientService
             end
 
             ##
+            # @api private
+            #
             # @param step [ConvenientService::Service::Plugins::CanHaveSteps::Entities::Step]
             # @return [ConvenientService::Service::Plugins::CanHaveSteps::Entities::StepCollection]
             #
@@ -79,6 +93,8 @@ module ConvenientService
             end
 
             ##
+            # @api public
+            #
             # @param other [Object] Can be any type.
             # @return [Boolean, nil]
             #

data/lib/convenient_service/service/plugins/has_j_send_result/entities/result/plugins/has_j_send_status_and_attributes/entities/code/concern/instance_methods.rb

@@ -69,6 +69,30 @@ module ConvenientService
                         # @see https://rspec.info/documentation/3.12/rspec-mocks/RSpec/Mocks/ArgumentMatchers.html
                         # @see https://github.com/rspec/rspec-mocks/blob/v3.12.3/lib/rspec/mocks/argument_matchers.rb#L282
                         #
+                        # @example Just code does NOT work in case/when.
+                        #
+                        #   case result.code # `result.code` returns fancy object
+                        #   when :full_queue
+                        #     notify_devops
+                        #   when :duplicated_job
+                        #     notify_devs
+                        #   else
+                        #     # ...
+                        #   end
+                        #
+                        # @example Code converted to symbol works in case/when.
+                        #
+                        #   case result.code.to_sym
+                        #   when :full_queue
+                        #     notify_devops
+                        #   when :duplicated_job
+                        #     notify_devs
+                        #   else
+                        #     # ...
+                        #   end
+                        #
+                        # @see https://userdocs.convenientservice.org/faq#why-casewhen-does-not-work-with-just-result-codes
+                        #
                         # @internal
                         #   IMPORTANT: Must be kept in sync with `#==`.
                         #   NOTE: Ruby does NOT have `!==` operator.

data/lib/convenient_service/service.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
 require_relative "service/plugins"
+require_relative "service/configs"

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

@@ -4,5 +4,4 @@ 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.rb

@@ -5,7 +5,6 @@ require_relative "dependency_container/constants"
 require_relative "dependency_container/entities"
 require_relative "dependency_container/exceptions"
 
-require_relative "dependency_container/entry"
 require_relative "dependency_container/export"
 require_relative "dependency_container/import"
 

data/lib/convenient_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ConvenientService
-  VERSION = "0.14.0"
+  VERSION = "0.16.0"
 end

data/lib/convenient_service.rb

@@ -28,7 +28,6 @@ require_relative "convenient_service/core"
 #
 require_relative "convenient_service/common"
 require_relative "convenient_service/service"
-require_relative "convenient_service/configs"
 
 ##
 # @internal

data/yard/yard-convenient_service_concern.rb

@@ -0,0 +1,45 @@
+require "yard"
+
+##
+# This file is used to allow parsing of yard docs inside `included`, `instance_methods` and `class_methods` blocks.
+#
+# It is loaded by the `RUBYLIB` ENV variable passed to `task docs:generate` in `Taskfile`.
+#
+# @see https://rubydoc.info/gems/yard/file/docs/GettingStarted.md#plugin-support
+# @see https://github.com/digitalcuisine/yard-activesupport-concern
+# @see https://github.com/digitalcuisine/yard-activesupport-concern/blob/v0.0.1/lib/yard-activesupport-concern.rb
+# @see https://stackoverflow.com/a/901109/12201472
+#
+module YARD
+  module Concern
+    class IncludedHandler < YARD::Handlers::Ruby::Base
+      handles method_call(:included)
+
+      namespace_only
+
+      def process
+        parse_block(statement.last.last, namespace: namespace, scope: :instance)
+      end
+    end
+
+    class InstanceMethodsHandler < YARD::Handlers::Ruby::Base
+      handles method_call(:instance_methods)
+
+      namespace_only
+
+      def process
+        parse_block(statement.last.last, namespace: namespace, scope: :instance)
+      end
+    end
+
+    class ClassMethodsHandler < YARD::Handlers::Ruby::Base
+      handles method_call(:class_methods)
+
+      namespace_only
+
+      def process
+        parse_block(statement.last.last, namespace: namespace, scope: :class)
+      end
+    end
+  end
+end