convenient_service 0.12.0 → 0.13.0

data/lib/convenient_service/examples/standard/date_time.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "date_time/services"
+
+##
+# @internal
+#   Usage examples:
+#
+#   result = ConvenientService::Examples::Standard::DateTime.safe_parse("24-02-2024", "%d-%m-%Y")
+#
+module ConvenientService
+  module Examples
+    module Standard
+      class DateTime
+        include ConvenientService::Feature
+
+        entry :safe_parse do |string, format|
+          Services::SafeParse[string: string, format: format]
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/factorial/services/calculate.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Examples
+    module Standard
+      class Factorial
+        module Services
+          class Calculate
+            include ConvenientService::Standard::Config
+
+            attr_reader :number, :timeout_seconds
+
+            def initialize(number:, timeout_seconds: 10)
+              @number = number
+              @timeout_seconds = timeout_seconds
+            end
+
+            def result
+              return failure(number: "is `nil`") if number.nil?
+              return failure(number: "is NOT an integer") unless number.instance_of?(::Integer)
+              return failure(number: "is lower than `0`") if number < 0
+
+              return error("Timeout (`#{timeout_seconds}` seconds) is exceeded for `#{number}`") if factorial.timeout?
+
+              success(factorial: factorial.value)
+            end
+
+            private
+
+            def factorial
+              @factorial ||= Utils::Timeout.with_timeout(timeout_seconds) { calculate_factorial }
+            end
+
+            ##
+            # @internal
+            #   NOTE: What is a Factorial?
+            #   - https://en.wikipedia.org/wiki/Factorial
+            #
+            def calculate_factorial
+              return 1 if [0, 1].include?(number)
+
+              1.upto(number).reduce(1) { |prev_value, next_value| prev_value * next_value }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/factorial/services.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "services/calculate"

data/lib/convenient_service/examples/standard/factorial/utils/timeout/with_timeout.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ConvenientService
+  module Examples
+    module Standard
+      class Factorial
+        module Utils
+          module Timeout
+            class WithTimeout < ConvenientService::Command
+              ReturnStruct = ::Struct.new(:timeout?, :value, keyword_init: true)
+
+              attr_reader :seconds, :block
+
+              def initialize(seconds, &block)
+                @seconds = seconds
+                @block = block
+              end
+
+              ##
+              # @internal
+              #   NOTE: Prefer to avoid `Timeout.timeout` if you are NOT absolutely 100% sure what you are doing. See the following articles for details.
+              #   - https://github.com/ruby/timeout/blob/master/lib/timeout.rb
+              #   - https://adamhooper.medium.com/in-ruby-dont-use-timeout-77d9d4e5a001
+              #   - https://flushentitypacket.github.io/ruby/2015/02/21/ruby-timeout-how-does-it-even-work.html
+              #   - https://www.exceptionalcreatures.com/bestiary/Timeout/Error
+              #   - https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts#regexp
+              #
+              def call
+                return struct(timeout?: false, value: block.call) if seconds.nil?
+                return struct(timeout?: true, value: nil) if seconds.zero?
+
+                begin
+                  struct(timeout?: false, value: ::Timeout.timeout(seconds, &block))
+                rescue ::Timeout::Error
+                  struct(timeout?: true, value: nil)
+                end
+              end
+
+              private
+
+              def struct(**kwargs)
+                ReturnStruct.new(**kwargs)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/factorial/utils/timeout.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "timeout/with_timeout"
+
+module ConvenientService
+  module Examples
+    module Standard
+      class Factorial
+        module Utils
+          module Timeout
+            class << self
+              def with_timeout(...)
+                WithTimeout.call(...)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/factorial/utils.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "utils/timeout"

data/lib/convenient_service/examples/standard/factorial.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "factorial/services"
+require_relative "factorial/utils"
+
+##
+# @internal
+#   Usage examples:
+#
+#   result = ConvenientService::Examples::Standard::Factorial.calculate(10)
+#
+module ConvenientService
+  module Examples
+    module Standard
+      class Factorial
+        include ConvenientService::Feature
+
+        entry :calculate do |number|
+          Services::Calculate[number: number]
+        end
+      end
+    end
+  end
+end

data/lib/convenient_service/examples/standard/gemfile/services/assert_file_exists.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class AssertFileExists
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/gemfile/services/assert_file_not_empty.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class AssertFileNotEmpty
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/gemfile/services/assert_node_available.rb

@@ -8,7 +8,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class AssertNodeAvailable
             include ConvenientService::Standard::Config
@@ -17,7 +17,7 @@ module ConvenientService
             # NOTE: `> /dev/null 2>&1` is used to hide output.
             # https://unix.stackexchange.com/a/119650/394253
             #
-            step Services::RunShell, in: {command: -> { "which node > /dev/null 2>&1" }}
+            step Services::RunShellCommand, in: {command: -> { "which node > /dev/null 2>&1" }}
           end
         end
       end

data/lib/convenient_service/examples/standard/gemfile/services/assert_npm_package_available.rb

@@ -8,7 +8,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class AssertNpmPackageAvailable
             include ConvenientService::Standard::Config
@@ -26,7 +26,7 @@ module ConvenientService
             # NOTE: For `npm list` and its options docs, see
             # https://docs.npmjs.com/cli/v7/commands/npm-ls
             #
-            step Services::RunShell, in: {command: -> { "npm list #{name} --depth=0 > /dev/null 2>&1" }}
+            step Services::RunShellCommand, in: {command: -> { "npm list #{name} --depth=0 > /dev/null 2>&1" }}
 
             def initialize(name:)
               @name = name

data/lib/convenient_service/examples/standard/gemfile/services/assert_valid_ruby_syntax.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class AssertValidRubySyntax
             include ConvenientService::Standard::Config
@@ -19,7 +19,7 @@ module ConvenientService
               # NOTE: `> /dev/null 2>&1` is used to hide output.
               # https://unix.stackexchange.com/a/119650/394253
               #
-              check_ruby_syntax_result = Services::RunShell.result(command: "ruby -c #{file.path} > /dev/null 2>&1")
+              check_ruby_syntax_result = Services::RunShellCommand.result(command: "ruby -c #{file.path} > /dev/null 2>&1")
 
               return error("`#{content}` contains invalid Ruby syntax") unless check_ruby_syntax_result.success?
 

data/lib/convenient_service/examples/standard/gemfile/services/format.rb

@@ -9,7 +9,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class Format
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/gemfile/services/format_body.rb

@@ -43,7 +43,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class FormatBody
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/gemfile/services/format_gems_with_envs.rb

@@ -31,7 +31,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class FormatGemsWithEnvs
             BLOCK_END = "end"

data/lib/convenient_service/examples/standard/gemfile/services/format_gems_without_envs.rb

@@ -35,7 +35,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class FormatGemsWithoutEnvs
             EMPTY_LINE = ""

data/lib/convenient_service/examples/standard/gemfile/services/format_header.rb

@@ -23,7 +23,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class FormatHeader
             FROZEN_STRING_LITERAL = "# frozen_string_literal: true"

data/lib/convenient_service/examples/standard/gemfile/services/merge_sections.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class MergeSections
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/gemfile/services/parse_content.rb

@@ -27,7 +27,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class ParseContent
             RUBY_REGEX = /\A\s*ruby/

data/lib/convenient_service/examples/standard/gemfile/services/print_shell_command.rb

@@ -3,31 +3,38 @@
 ##
 # Usage example:
 #
-#   ConvenientService::Examples::Standard::Gemfile::Services::PrintShellCommand.result(text: "ls -a")
+#   ConvenientService::Examples::Standard::Gemfile::Services::PrintShellCommand.result(command: "ls -a")
 #
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class PrintShellCommand
             include ConvenientService::Standard::Config
 
-            attr_reader :text, :out
+            attr_reader :command, :skip, :out
 
-            def initialize(text:, out: $stdout)
-              @text = text
+            def initialize(command:, skip: false, out: $stdout)
+              @command = command
+              @skip = skip
               @out = out
             end
 
             def result
-              return failure(text: "Text is `nil`") if text.nil?
-              return failure(text: "Text is empty?") if text.empty?
+              return failure(command: "Command is `nil`") if command.nil?
+              return failure(command: "Command is empty?") if command.empty?
+
+              return error("Printing of shell command `#{command}` is skipped") if skip
 
               out.puts
 
-              out.puts ::Paint["$ #{text}", :blue, :bold]
+              out.puts ::Paint["$ #{command}", :blue, :bold]
+
+              success
+            end
 
+            def fallback_result
               success
             end
           end

data/lib/convenient_service/examples/standard/gemfile/services/read_file_content.rb

@@ -3,14 +3,14 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class ReadFileContent
             include ConvenientService::Standard::Config
 
             attr_reader :path
 
-            step :validate_path
+            step :validate_path, in: :path
             step Services::AssertFileExists, in: :path
             step Services::AssertFileNotEmpty, in: :path
             step :result, in: :path, out: :content

data/lib/convenient_service/examples/standard/gemfile/services/replace_file_content.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class ReplaceFileContent
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/gemfile/services/{run_shell.rb → run_shell_command.rb}

@@ -3,23 +3,31 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
-          class RunShell
+          class RunShellCommand
             include ConvenientService::Standard::Config
 
             attr_reader :command, :debug
 
+            step :validate_command,
+              in: :command
+
+            step Services::PrintShellCommand,
+              in: [:command, {skip: -> { !debug }}],
+              fallback: true
+
+            step :result,
+              in: :command
+
             def initialize(command:, debug: false)
               @command = command
               @debug = debug
             end
 
             def result
-              Services::PrintShellCommand[text: command] if debug
-
               ##
-              # NOTE: When the command exit code is 0, `system` return true, and false otherwise.
+              # NOTE: When the command exit code is 0, `system` return `true`, and `false` otherwise.
               # - https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-system
               # - https://stackoverflow.com/a/37329716/12201472
               #
@@ -29,6 +37,15 @@ module ConvenientService
                 error(message: "#{command} returned non-zero exit code")
               end
             end
+
+            private
+
+            def validate_command
+              return failure(command: "Command is `nil`") if command.nil?
+              return failure(command: "Command is empty") if command.empty?
+
+              success
+            end
           end
         end
       end

data/lib/convenient_service/examples/standard/gemfile/services/strip_comments.rb

@@ -8,7 +8,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         module Services
           class StripComments
             include ConvenientService::Standard::Config
@@ -18,7 +18,7 @@ module ConvenientService
             alias_method :content_with_comments, :content
 
             step Services::AssertNpmPackageAvailable, in: {name: -> { "strip-comments" }}
-            step Services::RunShell, in: {command: -> { "node -e '#{js_script}' #{file_with_comments.path} #{file_without_comments.path}" }}
+            step Services::RunShellCommand, in: {command: -> { "node -e '#{js_script}' #{file_with_comments.path} #{file_without_comments.path}" }}
             step :result, in: :file_without_comments, out: :content_without_comments
 
             def initialize(content:)

data/lib/convenient_service/examples/standard/gemfile/services.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "services/run_shell"
+require_relative "services/print_shell_command"
+require_relative "services/run_shell_command"
 
 require_relative "services/assert_file_exists"
 require_relative "services/assert_file_not_empty"
@@ -13,7 +14,6 @@ require_relative "services/format_gems_with_envs"
 require_relative "services/format_body"
 require_relative "services/merge_sections"
 require_relative "services/parse_content"
-require_relative "services/print_shell_command"
 require_relative "services/read_file_content"
 require_relative "services/replace_file_content"
 require_relative "services/strip_comments"

data/lib/convenient_service/examples/standard/gemfile.rb

@@ -12,7 +12,7 @@ require_relative "gemfile/services"
 module ConvenientService
   module Examples
     module Standard
-      module Gemfile
+      class Gemfile
         include ConvenientService::Feature
 
         entry :format do |path|

data/lib/convenient_service/examples/standard/request_params/constants.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Constants
           module Tags
             EMPTY = ""

data/lib/convenient_service/examples/standard/request_params/entities/description.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           class Description
             def initialize(value:)

data/lib/convenient_service/examples/standard/request_params/entities/format.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           class Format
             def initialize(value:)

data/lib/convenient_service/examples/standard/request_params/entities/id.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           ##
           # TODO: https://ruby-doc.org/3.1.3/stdlibs/yaml/YAML/DBM.html

data/lib/convenient_service/examples/standard/request_params/entities/logger.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           class Logger
             class << self

data/lib/convenient_service/examples/standard/request_params/entities/request.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           class Request
             attr_reader :http_string

data/lib/convenient_service/examples/standard/request_params/entities/source.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           class Source
             def initialize(value:)

data/lib/convenient_service/examples/standard/request_params/entities/tag.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           class Tag
             def initialize(value:)

data/lib/convenient_service/examples/standard/request_params/entities/title.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Entities
           class Title
             def initialize(value:)

data/lib/convenient_service/examples/standard/request_params/services/apply_default_param_values.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class ApplyDefaultParamValues
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/cast_params.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class CastParams
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/extract_params_from_body.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class ExtractParamsFromBody
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/extract_params_from_path.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class ExtractParamsFromPath
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/filter_out_unpermitted_params.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class FilterOutUnpermittedParams
             include ConvenientService::Standard::Config

data/lib/convenient_service/examples/standard/request_params/services/log_request_params.rb

@@ -3,7 +3,7 @@
 module ConvenientService
   module Examples
     module Standard
-      module RequestParams
+      class RequestParams
         module Services
           class LogRequestParams
             include ConvenientService::Standard::Config