cuprum 0.8.0 → 0.10.0

data/lib/cuprum/result_helpers.rb

@@ -1,113 +1,22 @@
+# frozen_string_literal: true
+
 require 'cuprum'
 
 module Cuprum
-  # Helper methods that delegate result methods to the currently processed
-  # result.
-  #
-  # @example
-  #   class LogCommand
-  #     include Cuprum::Processing
-  #     include Cuprum::ResultHelpers
-  #
-  #     private
-  #
-  #     def process log
-  #       case log[:level]
-  #       when 'fatal'
-  #         halt!
-  #
-  #         'error'
-  #       when 'error' && log[:message]
-  #         errors << message
-  #
-  #         'error'
-  #       when 'error'
-  #         failure!
-  #
-  #         'error'
-  #       else
-  #         'ok'
-  #       end # case
-  #     end # method process
-  #   end # class
-  #
-  #   result = LogCommand.new.call(:level => 'info')
-  #   result.success? #=> true
-  #
-  #   string = 'something went wrong'
-  #   result = LogCommand.new.call(:level => 'error', :message => string)
-  #   result.success? #=> false
-  #   result.errors   #=> ['something went wrong']
-  #
-  #   result = LogCommand.new.call(:level => 'error')
-  #   result.success? #=> false
-  #   result.errors   #=> []
-  #
-  #   result = LogCommand.new.call(:level => 'fatal')
-  #   result.halted? #=> true
-  #
-  # @see Cuprum::Command
+  # Helper methods for generating Cuprum result objects.
   module ResultHelpers
     private
 
-    # @!visibility public
-    #
-    # Provides a reference to the current result's errors object. Messages or
-    # error objects added to this will be included in the #errors method of the
-    # returned result object.
-    #
-    # @return [Array, Object] The errors object.
-    #
-    # @see Cuprum::Result#errors.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def errors
-      result&.errors
-    end # method errors
-
-    # @!visibility public
-    #
-    # Marks the current result as failed. Calling #failure? on the returned
-    # result object will evaluate to true, whether or not the result has any
-    # errors.
-    #
-    # @see Cuprum::Result#failure!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def failure!
-      result&.failure!
-    end # method failure!
+    def build_result(error: nil, status: nil, value: nil)
+      Cuprum::Result.new(error: error, status: status, value: value)
+    end
 
-    # @!visibility public
-    #
-    # Marks the current result as halted.
-    #
-    # @see Cuprum::Result#halt!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def halt!
-      result&.halt!
-    end # method halt!
+    def failure(error)
+      build_result(error: error)
+    end
 
-    # @!visibility public
-    #
-    # Marks the current result as passing. Calling #success? on the returned
-    # result object will evaluate to true, whether or not the result has any
-    # errors.
-    #
-    # @see Cuprum::Result#success!.
-    #
-    # @note This is a private method, and only available when executing the
-    #   command implementation as defined in the constructor block or the
-    #   #process method.
-    def success!
-      result&.success!
-    end # method success!
-  end # module
-end # module
+    def success(value)
+      build_result(value: value)
+    end
+  end
+end

data/lib/cuprum/rspec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Namespace for RSpec extensions for testing Cuprum applications.
+  module RSpec; end
+end

data/lib/cuprum/rspec/be_a_result.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'cuprum/rspec/be_a_result_matcher'
+
+module RSpec
+  module Matchers # rubocop:disable Style/Documentation
+    def be_a_failing_result
+      be_a_result.with_status(:failure)
+    end
+
+    def be_a_passing_result
+      be_a_result.with_status(:success).and_error(nil)
+    end
+
+    def be_a_result
+      Cuprum::RSpec::BeAResultMatcher.new
+    end
+  end
+end

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require 'cuprum/errors/operation_not_called'
+require 'cuprum/rspec'
+
+module Cuprum::RSpec
+  # Custom matcher that asserts the actual object is a Cuprum result object with
+  # the specified properties.
+  class BeAResultMatcher # rubocop:disable Metrics/ClassLength
+    DEFAULT_VALUE = Object.new.freeze
+    private_constant :DEFAULT_VALUE
+
+    RSPEC_MATCHER_METHODS = %i[description failure_message matches?].freeze
+    private_constant :RSPEC_MATCHER_METHODS
+
+    def initialize
+      @expected_error = DEFAULT_VALUE
+      @expected_value = DEFAULT_VALUE
+    end
+
+    # @return [String] a short description of the matcher and expected
+    #   properties.
+    def description
+      message = 'be a Cuprum result'
+
+      return message unless expected_properties?
+
+      "#{message} #{properties_description}"
+    end
+
+    # Checks that the given actual object is not a Cuprum result.
+    #
+    # @param actual [Object] The actual object to match.
+    #
+    # @return [Boolean] false if the actual object is a result; otherwise true.
+    def does_not_match?(actual)
+      @actual = actual
+
+      raise ArgumentError, negated_matcher_warning if expected_properties?
+
+      !actual_is_result?
+    end
+
+    # @return [String] a summary message describing a failed expectation.
+    def failure_message
+      message = "expected #{actual.inspect} to #{description}"
+
+      if !actual_is_result?
+        message + ', but the object is not a result'
+      elsif actual_is_uncalled_operation?
+        message + ', but the object is an uncalled operation'
+      elsif !properties_match?
+        message + properties_failure_message
+      else
+        # :nocov:
+        message
+        # :nocov:
+      end
+    end
+
+    # @return [String] a summary message describing a failed negated
+    #   expectation.
+    def failure_message_when_negated
+      "expected #{actual.inspect} not to #{description}"
+    end
+
+    # Checks that the given actual object is a Cuprum result or compatible
+    # object and has the specified properties.
+    #
+    # @param actual [Object] The actual object to match.
+    #
+    # @return [Boolean] true if the actual object is a result with the expected
+    #   properties; otherwise false.
+    def matches?(actual)
+      @actual = actual
+
+      actual_is_result? && !actual_is_uncalled_operation? && properties_match?
+    end
+
+    # Sets an error expectation on the matcher. Calls to #matches? will fail
+    # unless the actual object has the specified error.
+    #
+    # @param error [Cuprum::Error, Object] The expected error.
+    #
+    # @return [BeAResultMatcher] the updated matcher.
+    def with_error(error)
+      @expected_error = error
+
+      self
+    end
+    alias_method :and_error, :with_error
+
+    # Sets a status expectation on the matcher. Calls to #matches? will fail
+    # unless the actual object has the specified status.
+    #
+    # @param status [Symbol] The expected status.
+    #
+    # @return [BeAResultMatcher] the updated matcher.
+    def with_status(status)
+      @expected_status = status
+
+      self
+    end
+    alias_method :and_status, :with_status
+
+    # Sets a value expectation on the matcher. Calls to #matches? will fail
+    # unless the actual object has the specified value.
+    #
+    # @param value [Object] The expected value.
+    #
+    # @return [BeAResultMatcher] the updated matcher.
+    def with_value(value)
+      @expected_value = value
+
+      self
+    end
+    alias_method :and_value, :with_value
+
+    private
+
+    attr_reader \
+      :actual,
+      :expected_error,
+      :expected_status,
+      :expected_value
+
+    def actual_is_result?
+      actual.respond_to?(:to_cuprum_result)
+    end
+
+    def actual_is_uncalled_operation?
+      result.error.is_a?(Cuprum::Errors::OperationNotCalled)
+    end
+
+    def compare_items(expected, actual)
+      return expected.matches?(actual) if expected.respond_to?(:matches?)
+
+      expected == actual
+    end
+
+    def error_failure_message
+      return '' if error_matches?
+
+      "\n   expected error: #{inspect_expected(expected_error)}" \
+      "\n     actual error: #{result.error.inspect}"
+    end
+
+    def error_matches?
+      return @error_matches unless @error_matches.nil?
+
+      return @error_matches = true unless expected_error?
+
+      @error_matches = compare_items(expected_error, result.error)
+    end
+
+    def expected_properties?
+      (expected_error? && !expected_error.nil?) ||
+        expected_status? ||
+        expected_value?
+    end
+
+    def expected_error?
+      expected_error != DEFAULT_VALUE
+    end
+
+    def expected_status?
+      !!expected_status
+    end
+
+    def expected_value?
+      expected_value != DEFAULT_VALUE
+    end
+
+    def inspect_expected(expected)
+      return expected.description if rspec_matcher?(expected)
+
+      expected.inspect
+    end
+
+    def negated_matcher_warning
+      "Using `expect().not_to be_a_result#{properties_warning}` risks false" \
+      ' positives, since any other result will match.'
+    end
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/AbcSize
+    def properties_description
+      msg = ''
+      ary = []
+      ary << 'value' if expected_value?
+      ary << 'error' if expected_error? && !expected_error.nil?
+
+      unless ary.empty?
+        msg = "with the expected #{tools.array_tools.humanize_list(ary)}"
+      end
+
+      return msg unless expected_status?
+
+      return "with status: #{expected_status.inspect}" if msg.empty?
+
+      msg + " and status: #{expected_status.inspect}"
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/AbcSize
+
+    def properties_failure_message
+      properties_short_message +
+        status_failure_message +
+        value_failure_message +
+        error_failure_message
+    end
+
+    def properties_match?
+      error_matches? && status_matches? && value_matches?
+    end
+
+    def properties_short_message
+      ary = []
+      ary << 'status' unless status_matches?
+      ary << 'value'  unless value_matches?
+      ary << 'error'  unless error_matches?
+
+      ", but the #{tools.array_tools.humanize_list(ary)}" \
+      " #{tools.integer_tools.pluralize(ary.size, 'does', 'do')} not match:"
+    end
+
+    def properties_warning
+      ary = []
+      ary << 'value'  if expected_value?
+      ary << 'status' if expected_status?
+      ary << 'error'  if expected_error?
+
+      return '' if ary.empty?
+
+      message = ".with_#{ary.first}()"
+
+      return message if ary.size == 1
+
+      message + ary[1..-1].map { |str| ".and_#{str}()" }.join
+    end
+
+    def result
+      @result ||= actual.to_cuprum_result
+    end
+
+    def rspec_matcher?(value)
+      RSPEC_MATCHER_METHODS.all? do |method_name|
+        value.respond_to?(method_name)
+      end
+    end
+
+    def status_failure_message
+      return '' if status_matches?
+
+      "\n  expected status: #{expected_status.inspect}" \
+      "\n    actual status: #{result.status.inspect}"
+    end
+
+    def status_matches?
+      return @status_matches unless @status_matches.nil?
+
+      return @status_matches = true unless expected_status?
+
+      @status_matches = result.status == expected_status
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def value_failure_message
+      return '' if value_matches?
+
+      "\n   expected value: #{inspect_expected(expected_value)}" \
+      "\n     actual value: #{result.value.inspect}"
+    end
+
+    def value_matches?
+      return @value_matches unless @value_matches.nil?
+
+      return @value_matches = true unless expected_value?
+
+      @value_matches = compare_items(expected_value, result.value)
+    end
+  end
+end

data/lib/cuprum/steps.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require 'cuprum/result_helpers'
+
+module Cuprum
+  # The Steps supports step by step processes that halt on a failed step.
+  #
+  # After including Cuprum::Steps, use the #steps instance method to wrap a
+  # series of instructions. Each instruction is then defined using the #step
+  # method. Steps can be defined either as a block or as a method invocation.
+  #
+  # When the steps block is evaluated, each step is called in sequence. If the
+  # step resolves to a passing result, the result value is returned and
+  # execution continues to the next step. If all of the steps pass, then the
+  # result of the final step is returned from the #steps block.
+  #
+  # Conversely, if any step resolves to a failing result, that failing result is
+  # immediately returned from the #steps block. No further steps will be called.
+  #
+  # For example, consider updating a database record using a primary key and an
+  # attributes hash. Broken down into its basics, this requires the following
+  # instructions:
+  #
+  # - Using the primary key, find the existing record in the database.
+  # - Update the record object with the given attributes.
+  # - Save the updated record back to the database.
+  #
+  # Note that each of these steps can fail for different reasons. For example,
+  # if a record with the given primary key does not exist in the database, then
+  # the first instruction will fail, and the follow up steps should not be
+  # executed. Further, whatever context is executing these steps probably wants
+  # to know which step failed, and why.
+  #
+  # @example Defining Methods As Steps
+  #   def assign_attributes(record, attributes); end
+  #
+  #   def find_record(primary_key); end
+  #
+  #   def save_record(record); end
+  #
+  #   def update_record(primary_key, attributes)
+  #     steps do
+  #       record = step :find_record,       primary_key
+  #       record = step :assign_attributes, record, attributes
+  #       step :save_record, record
+  #     end
+  #   end
+  #
+  # @example Defining Blocks As Steps
+  #   class AssignAttributes < Cuprum::Command; end
+  #
+  #   class FindRecord < Cuprum::Command; end
+  #
+  #   class SaveRecord < Cuprum::Command; end
+  #
+  #   def update_record(primary_key, attributes)
+  #     steps do
+  #       record = step { FindRecord.new.call(primary_key) }
+  #       record = step { AssignAttributes.new.call(record, attributes) }
+  #       step { SaveRecord.new.call(record) }
+  #     end
+  #   end
+  module Steps
+    include Cuprum::ResultHelpers
+
+    class << self
+      # @!visibility private
+      def execute_method(receiver, method_name, *args, **kwargs, &block)
+        if block_given? && kwargs.empty?
+          receiver.send(method_name, *args, &block)
+        elsif block_given?
+          receiver.send(method_name, *args, **kwargs, &block)
+        elsif kwargs.empty?
+          receiver.send(method_name, *args)
+        else
+          receiver.send(method_name, *args, **kwargs)
+        end
+      end
+
+      # @!visibility private
+      def extract_result_value(result)
+        return result unless result.respond_to?(:to_cuprum_result)
+
+        result = result.to_cuprum_result
+
+        return result.value if result.success?
+
+        throw :cuprum_failed_step, result
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      # @!visibility private
+      def validate_method_name(method_name)
+        if method_name.nil?
+          raise ArgumentError,
+            'expected a block or a method name',
+            caller(1..-1)
+        end
+
+        unless method_name.is_a?(String) || method_name.is_a?(Symbol)
+          raise ArgumentError,
+            'expected method name to be a String or Symbol',
+            caller(1..-1)
+        end
+
+        return unless method_name.empty?
+
+        raise ArgumentError, "method name can't be blank", caller(1..-1)
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+
+    # @overload step()
+    #   Executes the block and returns the value, or halts on a failure.
+    #
+    #   @yield Called with no parameters.
+    #
+    #   @return [Object] the #value of the result, or the returned object.
+    #
+    #   The #step method is used to evaluate a sequence of processes, and to
+    #   fail fast and halt processing if any of the steps returns a failing
+    #   result. Each invocation of #step should be wrapped in a #steps block,
+    #   or used inside the #process method of a Command.
+    #
+    #   If the object returned by the block is a Cuprum result or compatible
+    #   object (such as a called operation), the value is converted to a Cuprum
+    #   result via the #to_cuprum_result method. Otherwise, the object is
+    #   returned directly from #step.
+    #
+    #   If the returned object is a passing result, the #value of the result is
+    #   returned by #step.
+    #
+    #   If the returned object is a failing result, then #step will throw
+    #   :cuprum_failed_result and the failing result. This is caught by the
+    #   #steps block, and halts execution of any subsequent steps.
+    #
+    #   @example Calling a Step
+    #     # The #do_something method returns the string 'some value'.
+    #     step { do_something() } #=> 'some value'
+    #
+    #     value = step { do_something() }
+    #     value #=> 'some value'
+    #
+    #   @example Calling a Step with a Passing Result
+    #     # The #do_something_else method returns a Cuprum result with a value
+    #     # of 'another value'.
+    #     step { do_something_else() } #=> 'another value'
+    #
+    #     # The result is passing, so the value is extracted and returned.
+    #     value = step { do_something_else() }
+    #     value #=> 'another value'
+    #
+    #   @example Calling a Step with a Failing Result
+    #     # The #do_something_wrong method returns a failing Cuprum result.
+    #     step { do_something_wrong() } # Throws the :cuprum_failed_step symbol.
+    #
+    # @overload step(method_name, *arguments, **keywords)
+    #   Calls the method and returns the value, or halts on a failure.
+    #
+    #   @param method_name [String, Symbol] The name of the method to call. Must
+    #     be the name of a method on the current object.
+    #   @param arguments [Array] Positional arguments to pass to the method.
+    #   @param keywords [Hash] Keyword arguments to pass to the method.
+    #
+    #   @yield A block to pass to the method.
+    #
+    #   @return [Object] the #value of the result, or the returned object.
+    #
+    #   The #step method is used to evaluate a sequence of processes, and to
+    #   fail fast and halt processing if any of the steps returns a failing
+    #   result. Each invocation of #step should be wrapped in a #steps block,
+    #   or used inside the #process method of a Command.
+    #
+    #   If the object returned by the block is a Cuprum result or compatible
+    #   object (such as a called operation), the value is converted to a Cuprum
+    #   result via the #to_cuprum_result method. Otherwise, the object is
+    #   returned directly from #step.
+    #
+    #   If the returned object is a passing result, the #value of the result is
+    #   returned by #step.
+    #
+    #   If the returned object is a failing result, then #step will throw
+    #   :cuprum_failed_result and the failing result. This is caught by the
+    #   #steps block, and halts execution of any subsequent steps.
+    #
+    #   @example Calling a Step
+    #     # The #zero method returns the integer 0.
+    #     step :zero #=> 0
+    #
+    #     value = step :zero
+    #     value #=> 0
+    #
+    #   @example Calling a Step with a Passing Result
+    #     # The #add method adds the numbers and returns a Cuprum result with a
+    #     # value equal to the sum.
+    #     step :add, 2, 2
+    #     #=> 4
+    #
+    #     # The result is passing, so the value is extracted and returned.
+    #     value = step :add, 2, 2
+    #     value #=> 4
+    #
+    #   @example Calling a Step with a Failing Result
+    #     # The #divide method returns a failing Cuprum result when the second
+    #     # argument is zero.
+    #     step :divide, 1, 0
+    #     # Throws the :cuprum_failed_step symbol, which should be caught by the
+    #     # enclosing #steps block.
+    def step(method_name = nil, *args, **kwargs, &block)
+      result =
+        if !block_given? || method_name || !args.empty? || !kwargs.empty?
+          Cuprum::Steps.validate_method_name(method_name)
+
+          Cuprum::Steps
+            .execute_method(self, method_name, *args, **kwargs, &block)
+        else
+          block.call
+        end
+
+      Cuprum::Steps.extract_result_value(result)
+    end
+
+    # Returns the first failing #step result, or the final result if none fail.
+    #
+    # The #steps method is used to wrap a series of #step calls. Each step is
+    # executed in sequence. If any of the steps returns a failing result, that
+    # result is immediately returned from #steps. Otherwise, #steps wraps the
+    # value returned by a block in a Cuprum result.
+    #
+    # @yield Called with no parameters.
+    #
+    # @yieldreturn A Cuprum result, or an object to be wrapped in a result.
+    #
+    # @return [Cuprum::Result] the result or object returned by the block,
+    #   wrapped in a Cuprum result.
+    #
+    # @example With A Passing Step
+    #   result = steps do
+    #     step { success('some value') }
+    #   end
+    #   result.class    #=> Cuprum::Result
+    #   result.success? #=> true
+    #   result.value    #=> 'some value'
+    #
+    # @example With A Failing Step
+    #   result = steps do
+    #     step { failure('something went wrong') }
+    #   end
+    #   result.class    #=> Cuprum::Result
+    #   result.success? #=> false
+    #   result.error    #=> 'something went wrong'
+    #
+    # @example With Multiple Steps
+    #   result = steps do
+    #     # This step is passing, so execution continues on to the next step.
+    #     step { success('first step') }
+    #
+    #     # This step is failing, so execution halts and returns this result.
+    #     step { failure('second step') }
+    #
+    #     # This step will never be called.
+    #     step { success('third step') }
+    #   end
+    #   result.class    #=> Cuprum::Result
+    #   result.success? #=> false
+    #   result.error    #=> 'second step'
+    def steps
+      result = catch(:cuprum_failed_step) { yield }
+
+      return result if result.respond_to?(:to_cuprum_result)
+
+      success(result)
+    end
+  end
+end