cuprum 0.10.0 → 0.11.0.rc.0

data/lib/cuprum/matching/match_clause.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'cuprum/matching'
+
+module Cuprum::Matching
+  # @private
+  #
+  # Value object that represents a potential result match for a Matcher.
+  #
+  # Should not be instantiated directly; instead, instantiate a Cuprum::Matcher
+  # or include Cuprum::Matching in a custom class.
+  MatchClause = Struct.new(:block, :error, :status, :value) do
+    include Comparable
+
+    # @param other [Cuprum::Matching::MatchClause] The other result to compare.
+    #
+    # @return [Integer] the comparison result.
+    def <=>(other)
+      return nil unless other.is_a?(Cuprum::Matching::MatchClause)
+
+      cmp = compare(value, other.value)
+
+      return cmp unless cmp.zero?
+
+      compare(error, other.error)
+    end
+
+    # Checks if the match clause matches the specified error and value.
+    #
+    # @return [Boolean] true if the error and value match, otherwise false.
+    def matches_details?(error:, value:)
+      return false unless matches_detail?(error, self.error)
+      return false unless matches_detail?(value, self.value)
+
+      true
+    end
+
+    # Checks if the match clause matches the given result.
+    #
+    # @return [Boolean] true if the result matches, otherwise false.
+    def matches_result?(result:)
+      return false unless error.nil? || result.error.is_a?(error)
+      return false unless value.nil? || result.value.is_a?(value)
+
+      true
+    end
+
+    private
+
+    def compare(left, right)
+      return  0 if left.nil? && right.nil?
+      return  1 if left.nil?
+      return -1 if right.nil?
+
+      left <=> right || 0
+    end
+
+    def matches_detail?(actual, expected)
+      return true  if actual.nil? && expected.nil?
+      return false if actual.nil? || expected.nil?
+
+      actual <= expected
+    end
+  end
+end

data/lib/cuprum/middleware.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Implements a wrapper around another command.
+  #
+  # A middleware command wraps the execution of another command, allowing the
+  # developer to compose functionality without an explicit wrapper command.
+  # Because the middleware is responsible for calling the wrapped command, it
+  # has control over when that command is called, with what parameters, and how
+  # the command result is handled.
+  #
+  # To use middleware, start by defining a middleware command. This can either
+  # be a class that includes Cuprum::Middleware, or a command instance that
+  # extends Cuprum::Middleware. Each middleware command's #process method takes
+  # as its first argument the wrapped command. By convention, any additional
+  # arguments and any keywords or a block are passed to the wrapped command, but
+  # some middleware will override ths behavior.
+  #
+  # When defining #process, make sure to either call super or call the wrapped
+  # command directly, unless the middleware is specifically intended not to call
+  # the wrapped command under those circumstances.
+  #
+  # Middleware is powerful because it allows the developer to manipulate the
+  # parameters passed to a command, add handling to a result, or even intercept
+  # or override the command execution. These are some of the possible use cases
+  # for middleware:
+  #
+  # - Injecting code before or after a command.
+  # - Changing the parameters passed to a command.
+  # - Adding behavior based on the command result.
+  # - Overriding the command behavior based on the parameters.
+  #
+  # Middleware is loosely coupled, meaning that one middleware command can wrap
+  # any number of other commands. One example would be logging middleware, which
+  # could record when a command is called and with what parameters. For a more
+  # involved example, consider authorization in a web application. If individual
+  # actions are defined as commands, then a single authorization middleware
+  # class could wrap each individual action, reducing both the testing burden
+  # and the amount of code that must be maintained.
+  #
+  # @example Basic Middleware
+  #   class ExampleCommand < Cuprum::Command
+  #     private def process(**options)
+  #       return failure(options[:error]) if options[:error]
+  #
+  #       "Options: #{options.inspect}"
+  #     end
+  #   end
+  #
+  #   class LoggingMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware injects a logging step before the wrapped command is
+  #     # called. Notice that this middleware is generic, and can be used with
+  #     # virtually any other command.
+  #     private def process(next_command, *args, **kwargs)
+  #       Logger.info("Calling command #{next_command.class}")
+  #
+  #       super
+  #     end
+  #   end
+  #
+  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+  #   middleware = LoggingMiddleware.new
+  #   result     = middleware.call(command, { id: 0 })
+  #   #=> logs "Calling command ExampleCommand"
+  #   result.value
+  #   #=> "Options: { id: 0 }"
+  #
+  # @example Injecting Parameters
+  #   class ApiMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware adds the :api_key to the parameters passed to the
+  #     # command. If an :api_key keyword is passed, then the passed value will
+  #     # take precedence.
+  #     private def process(next_command, *args, **kwargs)
+  #       super(next_command, *args, api_key: '12345', **kwargs)
+  #     end
+  #   end
+  #
+  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+  #   middleware = LoggingMiddleware.new
+  #   result     = middleware.call(command, { id: 0 })
+  #   result.value
+  #   #=> "Options: { id: 0, api_key: '12345' }"
+  #
+  # @example Handling Results
+  #   class IgnoreFailure < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware runs the command once. On a failing result, the
+  #     # middleware discards the failing result and returns a result with a
+  #     # value of nil.
+  #     private def process(next_command, *args, **kwargs)
+  #       result = super
+  #
+  #       return result if result.success?
+  #
+  #       success(nil)
+  #     end
+  #   end
+  #
+  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+  #   middleware = LoggingMiddleware.new
+  #   result     = middleware.call(command, { id: 0 })
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> "Options: { id: 0, api_key: '12345' }"
+  #
+  #   error      = Cuprum::Error.new(message: 'Something went wrong.')
+  #   result     = middleware.call(command, error: error)
+  #   result.success?
+  #   #=> true
+  #   result.value
+  #   #=> nil
+  #
+  # @example Flow Control
+  #   class AuthenticationMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware finds the current user based on the given keywords. If
+  #     # a valid user is found, the user is then passed on to the command.
+  #     # If a user is not found, then the middleware will immediately halt (due
+  #     # to #step) and return the failing result from the authentication
+  #     # command.
+  #     private def process(next_command, *args, **kwargs)
+  #       current_user = step { AuthenticateUser.new.call(**kwargs) }
+  #
+  #       super(next_command, *args, current_user: current_user, **kwargs)
+  #     end
+  #   end
+  #
+  # @example Advanced Command Wrapping
+  #   class RetryMiddleware < Cuprum::Command
+  #     include Cuprum::Middleware
+  #
+  #     # The middleware runs the command up to three times. If a result is
+  #     # passing, that result is returned immediately; otherwise, the last
+  #     # failing result will be returned by the middleware.
+  #     private def process(next_command, *args, **kwargs)
+  #       result = nil
+  #
+  #       3.times do
+  #         result = super
+  #
+  #         return result if result.success?
+  #       end
+  #
+  #       result
+  #     end
+  #   end
+  module Middleware
+    # @!method call(next_command, *arguments, **keywords, &block)
+    #   Calls the next command with the given arguments, keywords, and block.
+    #
+    #   Subclasses can call super to easily call the next command with the given
+    #   parameters, or pass explicit parameters into super to call the next
+    #   command with those parameters.
+    #
+    #   @param next_command [Cuprum::Command] The command to call.
+    #   @param arguments [Array] The arguments to pass to the command.
+    #   @param keywords [Hash] The keywords to pass to the command.
+    #
+    #   @yield A block to pass to the command.
+    #
+    #   @return [Cuprum::Result] the result of calling the command.
+
+    # Helper method for wrapping a command with middleware.
+    #
+    # This method takes the given command and middleware and returns a command
+    # that will call the middleware in order, followed by the given command.
+    # This is done via partial application: the last item in the middleware is
+    # partially applied with the given command as the middleware's next command
+    # parameter. The next to last middleware is then partially applied with the
+    # last middleware as the next command and so on. This ensures that the
+    # middleware commands will be called in the given order, and that each
+    # middleware command wraps the next, down to the given command at the root.
+    #
+    # @param command [Cuprum::Command] The command to wrap with middleware.
+    # @param middleware [Cuprum::Middleware, Array<Cuprum::Middleware>] The
+    #   middleware to wrap around the command. Will be called in the order they
+    #   are given.
+    #
+    # @return [Cuprum::Command] the outermost middleware command, with the next
+    #   command parameter partially applied.
+    def self.apply(command:, middleware:)
+      middleware = Array(middleware)
+
+      return command if middleware.empty?
+
+      middleware.reverse_each.reduce(command) do |next_command, cmd|
+        cmd.curry(next_command)
+      end
+    end
+
+    private
+
+    def process(next_command, *args, **kwargs, &block)
+      if kwargs.empty?
+        step { next_command.call(*args, &block) }
+      else
+        step { next_command.call(*args, **kwargs, &block) }
+      end
+    end
+  end
+end

data/lib/cuprum/operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'cuprum/command'
 require 'cuprum/errors/operation_not_called'
 
@@ -26,8 +28,8 @@ module Cuprum
   #       @book = operation.value
   #
   #       render :new
-  #     end # if-else
-  #   end # create
+  #     end
+  #   end
   #
   # Like a Command, an Operation can be defined directly by passing an
   # implementation block to the constructor or by creating a subclass that
@@ -41,7 +43,7 @@ module Cuprum
     # @example
     #   class CustomOperation < CustomCommand
     #     include Cuprum::Operation::Mixin
-    #   end # class
+    #   end
     module Mixin
       # @return [Cuprum::Result] The result from the most recent call of the
       #   operation.
@@ -62,32 +64,32 @@ module Cuprum
       #     implementation.
       #
       # @see Cuprum::Command#call
-      def call *args, **kwargs, &block
+      def call(*args, **kwargs, &block)
         reset! if called? # Clear reference to most recent result.
 
         @result = super
 
         self
-      end # method call
+      end
 
       # @return [Boolean] true if the operation has been called and has a
       #   reference to the most recent result; otherwise false.
       def called?
         !result.nil?
-      end # method called?
+      end
 
       # @return [Object] the error (if any) from the most recent result, or nil
       #   if the operation has not been called.
       def error
         called? ? result.error : nil
-      end # method error
+      end
 
       # @return [Boolean] true if the most recent result had an error, or false
       #   if the most recent result had no error or if the operation has not
       #   been called.
       def failure?
         called? ? result.failure? : false
-      end # method failure?
+      end
 
       # Clears the reference to the most recent call of the operation, if any.
       # This allows the result and any referenced data to be garbage collected.
@@ -99,7 +101,7 @@ module Cuprum
       # an error.
       def reset!
         @result = nil
-      end # method reset
+      end
 
       # @return [Symbol, nil] the status of the most recent result, or nil if
       #   the operation has not been called.
@@ -112,7 +114,7 @@ module Cuprum
       #   been called.
       def success?
         called? ? result.success? : false
-      end # method success?
+      end
 
       # Returns the most result if the operation was previously called.
       # Otherwise, returns a failing result.
@@ -130,8 +132,8 @@ module Cuprum
       #   operation has not been called.
       def value
         called? ? result.value : nil
-      end # method value
-    end # module
+      end
+    end
     include Mixin
 
     # @!method call
@@ -156,9 +158,9 @@ module Cuprum
     #   (see Cuprum::Operation::Mixin#success?)
 
     # @!method to_cuprum_result
-    #   (see Cuprum::Operation::Mixin#to_cuprum_result?)
+    #   (see Cuprum::Operation::Mixin#to_cuprum_result)
 
     # @!method value
     #   (see Cuprum::Operation::Mixin#value)
-  end # class
-end # module
+  end
+end

data/lib/cuprum/result.rb

@@ -5,6 +5,7 @@ require 'cuprum'
 module Cuprum
   # Data object that encapsulates the result of calling a Cuprum command.
   class Result
+    # Enumerates the default permitted values for a Result#status.
     STATUSES = %i[success failure].freeze
 
     # @param value [Object] The value returned by calling the command.
@@ -28,8 +29,6 @@ module Cuprum
     # @return [Symbol] the status of the result, either :success or :failure.
     attr_reader :status
 
-    # rubocop:disable Metrics/CyclomaticComplexity
-
     # Compares the other object to the result.
     #
     # @param other [#value, #success?] An object responding to, at minimum,
@@ -45,7 +44,6 @@ module Cuprum
 
       true
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     # @return [Boolean] true if the result status is :failure, otherwise false.
     def failure?

data/lib/cuprum/rspec/be_a_result.rb

@@ -2,16 +2,25 @@
 
 require 'cuprum/rspec/be_a_result_matcher'
 
-module RSpec
+module Cuprum::RSpec
   module Matchers # rubocop:disable Style/Documentation
+    # Asserts that the object is a Cuprum::Result with status: :failure.
+    #
+    # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
     def be_a_failing_result
       be_a_result.with_status(:failure)
     end
 
+    # Asserts that the object is a Cuprum::Result with status: :success.
+    #
+    # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
     def be_a_passing_result
       be_a_result.with_status(:success).and_error(nil)
     end
 
+    # Asserts that the object is a Cuprum::Result.
+    #
+    # @return [Cuprum::RSpec::BeAResultMatcher] the generated matcher.
     def be_a_result
       Cuprum::RSpec::BeAResultMatcher.new
     end

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -46,9 +46,9 @@ module Cuprum::RSpec
       message = "expected #{actual.inspect} to #{description}"
 
       if !actual_is_result?
-        message + ', but the object is not a result'
+        "#{message}, but the object is not a result"
       elsif actual_is_uncalled_operation?
-        message + ', but the object is an uncalled operation'
+        "#{message}, but the object is an uncalled operation"
       elsif !properties_match?
         message + properties_failure_message
       else
@@ -182,7 +182,6 @@ module Cuprum::RSpec
       ' positives, since any other result will match.'
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     # rubocop:disable Metrics/AbcSize
     def properties_description
       msg = ''
@@ -200,7 +199,6 @@ module Cuprum::RSpec
 
       msg + " and status: #{expected_status.inspect}"
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/AbcSize
 
     def properties_failure_message