convenient_service 0.12.0 → 0.14.0

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/error/exceptions.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResultShortSyntax
+        module Error
+          module Exceptions
+            class BothArgsAndKwargsArePassed < ::ConvenientService::Exception
+              ##
+              # @return [void]
+              #
+              def initialize
+                message = <<~TEXT
+                  Both `args` and `kwargs` are passed to the `error` method.
+
+                  Did you mean something like:
+
+                  error("Helpful text")
+                  error("Helpful text", :descriptive_code)
+
+                  error(message: "Helpful text")
+                  error(message: "Helpful text", code: :descriptive_code)
+                TEXT
+
+                super(message)
+              end
+            end
+
+            class KwargsContainJSendAndExtraKeys < ::ConvenientService::Exception
+              ##
+              # @return [void]
+              #
+              def initialize
+                message = <<~TEXT
+                  `kwargs` passed to `error` method contain JSend keys and extra keys. That's NOT allowed.
+
+                  Please, consider something like:
+
+                  # Shorter form with one arg. Assumes that arg is `message`.
+                  error("foo")
+
+                  # Shorter form with two args. Assumes that first arg is `message` and second is `code`.
+                  error("foo", :foo)
+
+                  # Shorter form with kwargs. Assumes that all kwargs are `data`.
+                  error(foo: :bar)
+
+                  # Longer form. More explicit `message`.
+                  error(message: "foo")
+
+                  # Longer form. More explicit `code`.
+                  error(code: :foo)
+
+                  # Longer form. More explicit `message` and `code` together.
+                  error(message: "foo", code: :foo)
+
+                  # (Advanced) Longer form also supports any other variation of `data`, `message` and `code`.
+                  error(data: {foo: :bar}, message: "foo")
+                  error(data: {foo: :bar}, code: :foo)
+                  error(data: {foo: :bar}, message: "foo", code: :foo)
+                TEXT
+
+                super(message)
+              end
+            end
+
+            class MoreThanTwoArgsArePassed < ::ConvenientService::Exception
+              def initialize
+                message = <<~TEXT
+                  More than two `args` are passed to the `error` method.
+
+                  Did you mean something like:
+
+                  error("Helpful text")
+                  error("Helpful text", :descriptive_code)
+                TEXT
+
+                super(message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/error/middleware.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResultShortSyntax
+        module Error
+          class Middleware < MethodChainMiddleware
+            intended_for :error, entity: :service
+
+            ##
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            def next(*args, **kwargs, &block)
+              raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
+
+              args.any? ? error_from_args : error_from_kwargs
+            end
+
+            private
+
+            ##
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            def error_from_args
+              case next_arguments.args.size
+              when 0 then chain.next
+              when 1 then chain.next(message: next_arguments.args[0])
+              when 2 then chain.next(message: next_arguments.args[0], code: next_arguments.args[1])
+              else
+                raise Exceptions::MoreThanTwoArgsArePassed.new
+              end
+            end
+
+            ##
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            # @internal
+            #   TODO: Constant for `[:data, :message, :code]`.
+            #
+            def error_from_kwargs
+              return chain.next(data: next_arguments.kwargs) if [:data, :message, :code].none? { |key| next_arguments.kwargs.has_key?(key) }
+
+              raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
+
+              chain.next(**next_arguments.kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/{has_result_short_syntax → has_j_send_result_short_syntax}/error.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
-require_relative "error/commands"
-require_relative "error/errors"
+require_relative "error/exceptions"
 require_relative "error/middleware"

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/failure/exceptions.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResultShortSyntax
+        module Failure
+          module Exceptions
+            class KwargsContainJSendAndExtraKeys < ::ConvenientService::Exception
+              ##
+              # @return [void]
+              #
+              def initialize
+                message = <<~TEXT
+                  `kwargs` passed to `failure` method contain JSend keys and extra keys. That's NOT allowed.
+
+                  Please, consider something like:
+
+                  # Shorter form with one arg. Assumes that arg is `message`.
+                  failure("foo")
+
+                  # Shorter form with two args. Assumes that first arg is `message` and second is `code`.
+                  failure("foo", :foo)
+
+                  # Shorter form with kwargs. Assumes that all kwargs are `data`.
+                  failure(foo: :bar)
+
+                  # Longer form. More explicit `message`.
+                  failure(message: "foo")
+
+                  # Longer form. More explicit `code`.
+                  failure(code: :foo)
+
+                  # Longer form. More explicit `message` and `code` together.
+                  failure(message: "foo", code: :foo)
+
+                  # (Advanced) Longer form also supports any other variation of `data`, `message` and `code`.
+                  failure(data: {foo: :bar}, message: "foo")
+                  failure(data: {foo: :bar}, code: :foo)
+                  failure(data: {foo: :bar}, message: "foo", code: :foo)
+                TEXT
+
+                super(message)
+              end
+            end
+
+            class BothArgsAndKwargsArePassed < ::ConvenientService::Exception
+              ##
+              # @return [void]
+              #
+              def initialize
+                message = <<~TEXT
+                  Both `args` and `kwargs` are passed to the `failure` method.
+
+                  Did you mean something like:
+
+                  failure("Helpful text")
+                  failure("Helpful text", :descriptive_code)
+
+                  failure(message: "Helpful text")
+                  failure(message: "Helpful text", code: :descriptive_code)
+                TEXT
+
+                super(message)
+              end
+            end
+
+            class MoreThanTwoArgsArePassed < ::ConvenientService::Exception
+              ##
+              # @return [void]
+              #
+              def initialize
+                message = <<~TEXT
+                  More than two `args` are passed to the `failure` method.
+
+                  Did you mean something like:
+
+                  failure("Helpful text")
+                  failure("Helpful text", :descriptive_code)
+                TEXT
+
+                super(message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/failure/middleware.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResultShortSyntax
+        module Failure
+          class Middleware < MethodChainMiddleware
+            intended_for :failure, entity: :service
+
+            ##
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            def next(*args, **kwargs, &block)
+              raise Exceptions::BothArgsAndKwargsArePassed.new if args.any? && kwargs.any?
+
+              args.any? ? failure_from_args : failure_from_kwargs
+            end
+
+            private
+
+            ##
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            def failure_from_args
+              case next_arguments.args.size
+              when 0 then chain.next
+              when 1 then chain.next(message: next_arguments.args[0])
+              when 2 then chain.next(message: next_arguments.args[0], code: next_arguments.args[1])
+              else
+                raise Exceptions::MoreThanTwoArgsArePassed.new
+              end
+            end
+
+            ##
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            # @internal
+            #   TODO: Constant for `[:data, :message, :code]`.
+            #
+            def failure_from_kwargs
+              return chain.next(data: next_arguments.kwargs) if [:data, :message, :code].none? { |key| next_arguments.kwargs.has_key?(key) }
+
+              raise Exceptions::KwargsContainJSendAndExtraKeys.new if next_arguments.kwargs.keys.difference([:data, :message, :code]).any?
+
+              chain.next(**next_arguments.kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/failure.rb

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

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/commands/refute_kwargs_contain_j_send_and_extra_keys.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResultShortSyntax
+        module Success
+          module Commands
+            class RefuteKwargsContainJSendAndExtraKeys < Support::Command
+              ##
+              # @attribute [r] kwargs
+              #   @return [Hash{Symbol => Object}]
+              #
+              attr_reader :kwargs
+
+              ##
+              # @param kwargs [Hash{Symbol => Object}]
+              # @return [void]
+              #
+              def initialize(kwargs:)
+                @kwargs = kwargs
+              end
+
+              ##
+              # @return [void]
+              # @raise [ConvenientService::Service::Plugins::HasJSendResultShortSyntax::Success::Exceptions::KwargsContainJSendAndExtraKeys]
+              #
+              # @example `kwargs.keys.difference([:data, :message, :code]).none?`.
+              #
+              #   {}.keys.difference([:data, :message, :code]).none?
+              #   # => true
+              #
+              #   {a: 1}.keys.difference([:data, :message, :code]).none?
+              #   # => false
+              #
+              #   {data: {}}.keys.difference([:data, :message, :code]).none?
+              #   # => true
+              #
+              #   {data: {}, a: 1}.keys.difference([:data, :message, :code]).none?
+              #   # => false
+              #
+              #   {data: {}, message: ""}.keys.difference([:data, :message, :code]).none?
+              #   # => true
+              #
+              #   {data: {}, message: "", a: 1}.keys.difference([:data, :message, :code]).none?
+              #   # => false
+              #
+              #   {data: {}, message: "", code: :""}.keys.difference([:data, :message, :code]).none?
+              #   # => true
+              #
+              #   {data: {}, message: "", code: :"", a: 1}.keys.difference([:data, :message, :code]).none?
+              #   # => false
+              #
+              def call
+                return if [:data, :message, :code].none? { |key| kwargs.has_key?(key) }
+
+                return if kwargs.keys.difference([:data, :message, :code]).none?
+
+                raise Exceptions::KwargsContainJSendAndExtraKeys.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/commands.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "commands/refute_kwargs_contain_j_send_and_extra_keys"

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/exceptions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResultShortSyntax
+        module Success
+          module Exceptions
+            class KwargsContainJSendAndExtraKeys < ::ConvenientService::Exception
+              ##
+              # @return [void]
+              #
+              def initialize
+                message = <<~TEXT
+                  `kwargs` passed to `success` method contain JSend keys and extra keys. That's NOT allowed.
+
+                  Please, consider something like:
+
+                  # Shorter form. Assumes that all kwargs are `data`.
+                  success(foo: :bar)
+
+                  # Longer form. More explicit.
+                  success(data: {foo: :bar})
+
+                  # (Advanced) Longer form also supports any other variation of `data`, `message` and `code`...
+                  success(data: {foo: :bar}, message: "foo")
+                  success(data: {foo: :bar}, code: :foo)
+                  success(data: {foo: :bar}, message: "foo", code: :foo)
+                  success(message: "foo")
+                  success(code: :foo)
+                TEXT
+
+                super(message)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax/success/middleware.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasJSendResultShortSyntax
+        module Success
+          class Middleware < MethodChainMiddleware
+            intended_for :success, entity: :service
+
+            ##
+            # @param args [Array<Object>]
+            # @param kwargs [Hash{Symbol => Object}]
+            # @param block [Proc, nil]
+            # @return [ConvenientService::Service::Plugins::HasJSendResult::Entities::Result]
+            #
+            def next(*args, **kwargs, &block)
+              Commands::RefuteKwargsContainJSendAndExtraKeys[kwargs: kwargs]
+
+              ([:data, :message, :code].any? { |key| kwargs.has_key?(key) }) ? chain.next(**kwargs) : chain.next(data: kwargs)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/{has_result_short_syntax → has_j_send_result_short_syntax}/success.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 require_relative "success/commands"
-require_relative "success/errors"
+require_relative "success/exceptions"
 require_relative "success/middleware"

data/lib/convenient_service/service/plugins/has_j_send_result_short_syntax.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "has_j_send_result_short_syntax/concern"
+require_relative "has_j_send_result_short_syntax/success"
+require_relative "has_j_send_result_short_syntax/failure"
+require_relative "has_j_send_result_short_syntax/error"

data/lib/convenient_service/service/plugins/{has_result_status_check_short_syntax → has_j_send_result_status_check_short_syntax}/concern.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Service
     module Plugins
-      module HasResultStatusCheckShortSyntax
+      module HasJSendResultStatusCheckShortSyntax
         module Concern
           include Support::Concern
 

data/lib/convenient_service/service/plugins/has_j_send_result_status_check_short_syntax.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "has_j_send_result_status_check_short_syntax/concern"

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasMermaidFlowchart
+        module Concern
+          include Support::Concern
+
+          class_methods do
+            ##
+            # @api public
+            #
+            # @return [ConvenientService::Service::Plugins::HasMermaidFlowchart::Entities::Flowchart]
+            #
+            def mermaid_flowchart
+              Entities::Flowchart.new(service: self)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/service/plugins/has_mermaid_flowchart/entities/flowchart/entities/code/commands/generate_lines.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Service
+    module Plugins
+      module HasMermaidFlowchart
+        module Entities
+          class Flowchart
+            module Entities
+              class Code
+                module Commands
+                  class GenerateLines < Support::Command
+                    include Support::Delegate
+
+                    ##
+                    # @api private
+                    #
+                    # @!attribute code [r]
+                    #   @return [ConvenientService::Service::Plugins::HasMermaidFlowchart::Entities::Flowchart::Entities::Code]
+                    #
+                    attr_reader :code
+
+                    ##
+                    # @api private
+                    #
+                    # @return [ConvenientService::Service::Plugins::HasMermaidFlowchart::Entities::Flowchart]
+                    #
+                    delegate :flowchart, to: :code
+
+                    ##
+                    # @api private
+                    #
+                    # @return [ConvenientService::Service]
+                    #
+                    delegate :service, to: :flowchart
+
+                    ##
+                    # @api private
+                    #
+                    # @return [ConvenientService::Service::Plugins::HasMermaidFlowchart::Entities::Flowchart::Entities::Settings]
+                    #
+                    delegate :settings, to: :flowchart
+
+                    ##
+                    # @api private
+                    #
+                    # @param code [ConvenientService::Service::Plugins::HasMermaidFlowchart::Entities::Flowchart::Entities::Code]
+                    # @return [void]
+                    #
+                    def initialize(code:)
+                      @code = code
+                    end
+
+                    ##
+                    # @api private
+                    #
+                    # @return [Array<String>]
+                    #
+                    def call
+                      [first_line, *service_lines]
+                    end
+
+                    private
+
+                    ##
+                    # @return [String]
+                    #
+                    # @internal
+                    #   NOTE: Flowchart docs.
+                    #   - https://mermaid.js.org/syntax/flowchart.html
+                    #
+                    def first_line
+                      <<~MERMAID.chomp
+                        flowchart #{settings.direction}
+                      MERMAID
+                    end
+
+                    ##
+                    # @return [Array<String>]
+                    #
+                    def service_lines
+                      GenerateServiceLines[service: service, ids: [], settings: settings]
+                        .map { |line| "  #{line}" }
+                    end
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end