cuprum 1.0.0 → 1.1.0

data/lib/cuprum/built_in/identity_command.rb

@@ -24,6 +24,10 @@ module Cuprum::BuiltIn
   #   result.error
   #   #=> 'errors.messages.unknown'
   class IdentityCommand < Cuprum::Command
+    def initialize
+      super(&nil)
+    end
+
     private
 
     def process(value = nil)

data/lib/cuprum/built_in/identity_operation.rb

@@ -14,15 +14,15 @@ module Cuprum::BuiltIn
   #   #=> true
   #
   # @example With a result.
-  #   errors    = ['errors.messages.unknown']
-  #   value     = Cuprum::Result.new('result value', :errors => errors)
+  #   error     = 'errors.messages.unknown'
+  #   value     = Cuprum::Result.new(value: 'result value', error: error)
   #   operation = IdentityOperation.new.call(value)
   #   operation.value
   #   #=> 'result value'
   #   operation.success?
   #   #=> false
-  #   operation.errors
-  #   #=> ['errors.messages.unknown']
+  #   operation.error
+  #   #=> 'errors.messages.unknown'
   class IdentityOperation < Cuprum::BuiltIn::IdentityCommand
     include Cuprum::Operation::Mixin
   end

data/lib/cuprum/built_in/null_command.rb

@@ -13,8 +13,12 @@ module Cuprum::BuiltIn
   #   result.success?
   #   #=> true
   class NullCommand < Cuprum::Command
+    def initialize
+      super(&nil)
+    end
+
     private
 
-    def process(*_args); end
+    def process(*_args, **_kwargs); end
   end
 end

data/lib/cuprum/command.rb

@@ -5,8 +5,15 @@ require 'cuprum/processing'
 require 'cuprum/steps'
 
 module Cuprum
-  # Functional object that encapsulates a business logic operation with a
-  # consistent interface and tracking of result value and status.
+  # Functional object that encapsulates a business logic operation or step.
+  #
+  # Using commands allows the developer to maintain a state or context, such as
+  # by passing context into the constructor. It provides a consistent interface
+  # by always returning a Cuprum::Result object, which tracks the status of the
+  # command call, the returned value, and the error object (if any). Finally, as
+  # a full-fledged Ruby object a Command can be passed around like any other
+  # object, including returned from a method (or another Command) or passed in
+  # as a parameter.
   #
   # A Command can be defined either by passing a block to the constructor, or
   # by defining a subclass of Command and implementing the #process method.
@@ -19,13 +26,11 @@ module Cuprum
   #
   # @example A Command subclass
   #   class MultiplyCommand < Cuprum::Command
-  #     def initialize multiplier
+  #     def initialize(multiplier)
   #       @multiplier = multiplier
   #     end
   #
-  #     private
-  #
-  #     def process int
+  #     private def process(int)
   #       int * @multiplier
   #     end
   #   end
@@ -37,13 +42,11 @@ module Cuprum
   #
   # @example A Command with an error state
   #   class DivideCommand < Cuprum::Command
-  #     def initialize divisor
+  #     def initialize(divisor)
   #       @divisor = divisor
   #     end
   #
-  #     private
-  #
-  #     def process int
+  #     private def process(int)
   #       if @divisor.zero?
   #         return Cuprum::Result.new(error: 'errors.messages.divide_by_zero')
   #       end
@@ -72,10 +75,16 @@ module Cuprum
 
     # Returns a new instance of Cuprum::Command.
     #
-    # @yield [*arguments, **keywords, &block] If a block is given, the
-    #   #call method will wrap the block and set the result #value to the return
-    #   value of the block. This overrides the implementation in #process, if
-    #   any.
+    # @yield If a block is given, the block is used to define a private #process
+    #   method. This overwrites any existing #process method. When the command
+    #   is called, #process will be called internally and passed the parameters.
+    #
+    # @yieldparam arguments [Array] the arguments passed to #call.
+    # @yieldparam keywords [Hash] the keywords passed to #call.
+    # @yieldparam block [Proc, nil] the block passed to call, #if any.
+    #
+    # @yieldreturn [Cuprum::Result, Object] the returned result or object is
+    #   converted to a Cuprum::Result and returned by #call.
     def initialize(&implementation)
       return unless implementation
 
@@ -96,11 +105,13 @@ module Cuprum
     #
     # @return [Proc] the wrapping proc.
     def to_proc
+      command = self
+
       @to_proc ||= lambda do |*args, **kwargs, &block|
         if kwargs.empty?
-          call(*args, &block)
+          command.call(*args, &block)
         else
-          call(*args, **kwargs, &block)
+          command.call(*args, **kwargs, &block)
         end
       end
     end

data/lib/cuprum/command_factory.rb

@@ -9,11 +9,11 @@ module Cuprum
   #
   # @example
   #   class SpaceFactory < Cuprum::CommandFactory
-  #     command :build, BuildCommand
+  #     command(:build, BuildCommand)
   #
-  #     command :fly { |launch_site:| FlyCommand.new(launch_site) }
+  #     command(:fly) { |launch_site:| FlyCommand.new(launch_site) }
   #
-  #     command_class :dream { DreamCommand }
+  #     command_class(:dream) { DreamCommand }
   #   end
   #
   #   factory = SpaceFactory.new
@@ -81,7 +81,7 @@ module Cuprum
       #
       #   @yield The block will be executed in the context of the factory
       #     instance.
-      #   @yieldparam *args [Array] Any arguments given to the method
+      #   @yieldparam args [Array] Any arguments given to the method
       #     factory.name() will be passed on the block.
       #   @yieldreturn [Cuprum::Command] The block return an instance of a
       #     Cuprum::Command subclass, or else raise an error.

data/lib/cuprum/currying/curried_command.rb

@@ -3,7 +3,7 @@
 require 'cuprum/currying'
 
 module Cuprum::Currying
-  # A CurriedCommand wraps another command and passes preset args to #call.
+  # A CurriedCommand wraps another command and passes preset params to #call.
   #
   # @example Currying Arguments
   #   # Our base command takes two arguments.

data/lib/cuprum/error.rb

@@ -7,6 +7,48 @@ module Cuprum
   #
   # Additional details can be passed by setting the #message or by using a
   # subclass of Cuprum::Error.
+  #
+  # @example
+  #   error = Cuprum::Error.new(message: 'Something went wrong')
+  #   error.type
+  #   #=> 'cuprum.error'
+  #   error.message
+  #   #=> 'Something went wrong'
+  #
+  # @example An Error With Custom Type
+  #   error = Cuprum::Error.new(
+  #     message: 'Something went wrong',
+  #     type:    'custom.errors.generic',
+  #   )
+  #   error.type
+  #   #=> 'custom.errors.generic'
+  #
+  # @example An Error Subclass
+  #   class LightsError < Cuprum::Error
+  #     TYPE = 'custom.errors.wrong_number_of_lights'
+  #
+  #     def initialize(count)
+  #       super(message: "There are #{count} lights!")
+  #
+  #       @count = count
+  #     end
+  #
+  #     private def as_json_data
+  #       { 'count' => count }
+  #     end
+  #   end
+  #
+  #   error = LightsError.new(4)
+  #   error.type
+  #   #=> 'custom.errors.wrong_number_of_lights'
+  #   error.message
+  #   #=> 'There are 4 lights!'
+  #   error.as_json
+  #   #=> {
+  #   #     'data'    => { 'count' => 4 },
+  #   #     'message' => 'There are 4 lights!',
+  #   #     'type'    => 'custom.errors.wrong_number_of_lights'
+  #   #   }
   class Error
     # Short string used to identify the type of error.
     #

data/lib/cuprum/errors/command_not_implemented.rb

@@ -4,14 +4,13 @@ require 'cuprum/error'
 require 'cuprum/errors'
 
 module Cuprum::Errors
-  # Error class to be used when a Command is called without defining a #process
-  # method.
+  # Error returned when a Command is called without defining a #process method.
   class CommandNotImplemented < Cuprum::Error
     COMPARABLE_PROPERTIES = %i[command].freeze
     private_constant :COMPARABLE_PROPERTIES
 
-    # Format for generating error message.
     MESSAGE_FORMAT = 'no implementation defined for %s'
+    private_constant :MESSAGE_FORMAT
 
     # Short string used to identify the type of error.
     TYPE = 'cuprum.errors.command_not_implemented'

data/lib/cuprum/errors/multiple_errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'cuprum/error'
+require 'cuprum/errors'
+
+module Cuprum::Errors
+  # Error wrapping multiple errors from a collection command.
+  class MultipleErrors < Cuprum::Error
+    # Short string used to identify the type of error.
+    TYPE = 'cuprum.errors.multiple_errors'
+
+    # @param errors [Array<Cuprum::Error>] The wrapped errors.
+    # @param message [String] Optional message describing the nature of the
+    #   error.
+    def initialize(errors:, message: nil)
+      @errors = errors
+
+      super(
+        errors:  errors,
+        message: message || default_message
+      )
+    end
+
+    # @return [Array<Cuprum::Error>] the wrapped errors.
+    attr_reader :errors
+
+    private
+
+    def as_json_data
+      {
+        'errors' => errors.map { |error| error&.as_json }
+      }
+    end
+
+    def default_message
+      'the command encountered one or more errors'
+    end
+  end
+end

data/lib/cuprum/errors/operation_not_called.rb

@@ -4,11 +4,10 @@ require 'cuprum/error'
 require 'cuprum/errors'
 
 module Cuprum::Errors
-  # Error class to be used when trying to access the result of an uncalled
-  # Operation.
+  # Error returned when trying to access the result of an uncalled Operation.
   class OperationNotCalled < Cuprum::Error
-    # Format for generating error message.
     MESSAGE_FORMAT = '%s was not called and does not have a result'
+    private_constant :MESSAGE_FORMAT
 
     # Short string used to identify the type of error.
     TYPE = 'cuprum.errors.operation_not_called'

data/lib/cuprum/errors/uncaught_exception.rb

@@ -4,7 +4,7 @@ require 'cuprum/error'
 require 'cuprum/errors'
 
 module Cuprum::Errors
-  # An error returned when a command encounters an unhandled exception.
+  # Error returned when a command encounters an unhandled exception.
   class UncaughtException < Cuprum::Error
     # Short string used to identify the type of error.
     TYPE = 'cuprum.collections.errors.uncaught_exception'
@@ -45,7 +45,7 @@ module Cuprum::Errors
     end
 
     def generate_message(message)
-      message = "#{message} #{exception.class}: #{exception.message}"
+      message = "#{message.rstrip} #{exception.class}: #{exception.message}"
 
       return message unless cause
 

data/lib/cuprum/errors.rb

@@ -4,5 +4,10 @@ require 'cuprum'
 
 module Cuprum
   # Namespace for custom Cuprum error classes.
-  module Errors; end
+  module Errors
+    autoload :CommandNotImplemented, 'cuprum/errors/command_not_implemented'
+    autoload :MultipleErrors,        'cuprum/errors/multiple_errors'
+    autoload :OperationNotCalled,    'cuprum/errors/operation_not_called'
+    autoload :UncaughtException,     'cuprum/errors/uncaught_exception'
+  end
 end

data/lib/cuprum/exception_handling.rb

@@ -3,7 +3,7 @@
 require 'cuprum/errors/uncaught_exception'
 
 module Cuprum
-  # Utility class for handling uncaught exceptions in commands.
+  # Utility module for handling uncaught exceptions in commands.
   #
   # @example
   #   class UnsafeCommand < Cuprum::Command
@@ -27,7 +27,7 @@ module Cuprum
   #   #=> a Cuprum::Errors::UncaughtException error.
   #   result.error.message
   #   #=> 'uncaught exception in SafeCommand -' \
-  #       ' StandardError: Something went wrong.'
+  #   #   ' StandardError: Something went wrong.'
   module ExceptionHandling
     # Wraps the #call method with a rescue clause matching any StandardError.
     #
@@ -37,6 +37,8 @@ module Cuprum
     #
     # @return [Cuprum::Result] the result of calling the superclass method, or
     #   a failing result if a StandardError is raised.
+    #
+    # @see Cuprum::Processing#call
     def call(*args, **kwargs, &block)
       super
     rescue StandardError => exception

data/lib/cuprum/map_command.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'cuprum'
+
+module Cuprum
+  # Calls the command implementation with each item in the given enumerable.
+  #
+  # A regular Command is called with a set of parameters, calls the command
+  # implementation once with those parameters, and returns the Result. In
+  # contrast, a MapCommand is called with an Enumerable object, such as an
+  # Array, a Hash, or an Enumerator (e.g. by calling #each without a block). The
+  # MapCommand implementation is then called with each item in the
+  # Enumerable - for example, if called with an Array with three items, the
+  # MapCommand implementation would be called three times, once with each item.
+  # Finally, the Results returned by calling the implementation with each item
+  # are aggregated together into a Cuprum::ResultList. A ResultList behaves like
+  # a Result, and provides the standard methods (such as #status, #error, and
+  # #value), but also includes a reference to the #results used to create the
+  # ResultList, and their respective #errors and #values as Arrays.
+  #
+  # Like a standard Command, a MapCommand can be defined either by passing a
+  # block to the constructor, or by defining a subclass of MapCommand and
+  # implementing the #process method. If the given block or the #process method
+  # accepts more than one argument, the enumerable item is destructured using
+  # the splat operator (*); this enables using a MapCommand to map over the keys
+  # and values of a Hash. This is the same behavior seen when passing a block
+  # with multiple arguments to a native #each method.
+  #
+  # If a MapCommand is initialized with the :allow_partial keyword, the
+  # ResultList will be passing as long as there is at least one passing Result
+  # (or if the MapCommand is called with an empty Enumerable). See
+  # ResultList#allow_partial? for details.
+  #
+  # @example A MapCommand with a block
+  #   titleize_command = Cuprum::MapCommand.new do |str|
+  #     if str.nil? || str.empty?
+  #       next failure(Cuprum::Error.new(message: "can't be blank"))
+  #     end
+  #
+  #     str.split(' ').map(&:capitalize).join(' ')
+  #   end
+  #
+  # @example A MapCommand Subclass
+  #   class TitleizeCommand < Cuprum::MapCommand
+  #     private
+  #
+  #     def process(str)
+  #       if str.nil? || str.empty?
+  #         return failure(Cuprum::Error.new(message: "can't be blank"))
+  #       end
+  #
+  #       str.split(' ').map(&:capitalize).join(' ')
+  #     end
+  #   end
+  #
+  #   titleize_command = TitleizeCommand.new
+  #
+  # @example With an Array with passing Results
+  #   results = titleize_command.call(['hello world', 'greetings programs'])
+  #   results.class
+  #   #=> Cuprum::ResultsList
+  #   results.status
+  #   #=> :success
+  #   results.value
+  #   #=> ['Hello World', 'Greetings Programs']
+  #   results.values
+  #   #=> ['Hello World', 'Greetings Programs']
+  #   results.error
+  #   #=> nil
+  #   results.errors
+  #   #=> [nil, nil]
+  #
+  # @example With an Array with failing Results
+  #   results = titleize_command.call([nil, ''])
+  #   results.status
+  #   #=> :failure
+  #   results.value
+  #   #=> [nil, nil]
+  #   results.values
+  #   #=> [nil, nil]
+  #   results.error.class
+  #   #=> Cuprum::Errors::MultipleErrors
+  #   results.errors.map(&:class)
+  #   #=> [Cuprum::Error, Cuprum::Error]
+  #   results.errors.first.message
+  #   #=> "can't be blank"
+  #
+  # @example With an Array with mixed passing and failing Results
+  #   results = titleize_command.call([nil, 'greetings programs'])
+  #   results.status
+  #   #=> :failure
+  #   results.value
+  #   #=> [nil, "Greetings Programs"]
+  #   results.values
+  #   #=> [nil, "Greetings Programs"]
+  #   results.error.class
+  #   #=> Cuprum::Errors::MultipleErrors
+  #   results.errors.map(&:class)
+  #   #=> [Cuprum::Error, nil]
+  #   results.errors.first.message
+  #   #=> "can't be blank"
+  #
+  # @example With an Empty Array
+  #   results = titleize_command.call([])
+  #   results.status
+  #   #=> :success
+  #   results.value
+  #   #=> []
+  #   results.values
+  #   #=> []
+  #   results.error
+  #   #=> nil
+  #   results.errors
+  #   #=> []
+  #
+  # @example With a Hash
+  #   inspect_command = Cuprum::MapCommand.new do |key, value|
+  #     "#{key.inspect} => #{value.inspect}"
+  #   end
+  #
+  #   results = inspect_command.call({ ichi: 1, "ni" => 2 })
+  #   results.status
+  #   #=> :success
+  #   results.value
+  #   #=> [':ichi => 1', '"ni" => 2']
+  #   results.values
+  #   #=> [':ichi => 1', '"ni" => 2']
+  #   results.error
+  #   #=> nil
+  #   results.errors
+  #   #=> [nil, nil]
+  #
+  # @example With an Enumerable
+  #   square_command = Cuprum::MapCommand.new { |i| i ** 2 }
+  #
+  #   results = square_command.call(0...4)
+  #   results.status
+  #   #=> :success
+  #   results.value
+  #   #=> [0, 1, 4, 9]
+  #   results.values
+  #   #=> [0, 1, 4, 9]
+  #
+  # @example With allow_partial: true
+  #   maybe_upcase_command = Cuprum::MapCommand.new do |str|
+  #     next str.upcase if str.is_a?(String)
+  #
+  #     failure(Cuprum::Error.new(message: 'not a String'))
+  #   end
+  #
+  #   results = maybe_upcase_command.call([nil, 'greetings', 'programs'])
+  #   results.status
+  #   #=> :success
+  #   results.value
+  #   #=> [nil, 'GREETINGS', 'PROGRAMS']
+  #   results.values
+  #   #=> [nil, 'GREETINGS', 'PROGRAMS']
+  #   results.error.class
+  #   #=> Cuprum::Errors::MultipleErrors
+  #   results.errors.map(&:class)
+  #   #=> [Cuprum::Error, nil, nil]
+  #   results.errors.first.message
+  #   #=> 'not a String'
+  #
+  # @see Cuprum::Command
+  # @see Cuprum::ResultList
+  class MapCommand < Cuprum::Command
+    # @overload initialize(allow_partial: false)
+    #   @param allow_partial [true, false] If true, allows for some failing
+    #     results as long as there is at least one passing result. Defaults to
+    #     false.
+    #
+    # @overload initialize(allow_partial: false) { |item| }
+    #   @param allow_partial [true, false] If true, allows for some failing
+    #     results as long as there is at least one passing result. Defaults to
+    #     false.
+    #   @yield The command implementation, to be called with each successive
+    #     item in the given enumerable. This overrides the #process method, if
+    #     any.
+    #   @yieldparam [Object] item Each item in the given Enumerable.
+    #
+    # @overload initialize(allow_partial: false) { |key, value| }
+    #   @param allow_partial [true, false] If true, allows for some failing
+    #     results as long as there is at least one passing result. Defaults to
+    #     false.
+    #   @yield The command implementation, to be called with each successive
+    #     item in the given enumerable. This overrides the #process method, if
+    #     any.
+    #   @yieldparam [Object] key Each key in the given Hash.
+    #   @yieldparam [Object] value Each value in the given Hash.
+    def initialize(allow_partial: false, &implementation)
+      super(&implementation)
+
+      @allow_partial = allow_partial
+    end
+
+    # @return [true, false] if true, allows for some failing results as long as
+    #   there is at least one passing result. Defaults to false.
+    def allow_partial?
+      @allow_partial
+    end
+
+    # Calls the command implementation for each item in the given Enumerable.
+    #
+    # @param enumerable [Array, Hash, Enumerable] The collection or enumerable
+    #   object to map.
+    #
+    # @return [Cuprum::ResultList] the aggregated results.
+    def call(enumerable)
+      build_result_list(
+        enumerable.map { |item| splat_items? ? super(*item) : super(item) }
+      )
+    end
+
+    private
+
+    def build_result_list(results)
+      Cuprum::ResultList.new(*results, allow_partial: allow_partial?)
+    end
+
+    def splat_items?
+      return @splat_items unless @splat_items.nil?
+
+      @splat_items = method(:process).arity > 1
+    end
+  end
+end

data/lib/cuprum/matcher.rb

@@ -63,6 +63,8 @@ module Cuprum
   class Matcher
     include Cuprum::Matching
 
+    # @!parse extend Cuprum::Matching::ClassMethods
+
     # @param match_context [Object] the execution context for a matching clause.
     #
     # @yield Executes the block in the context of the singleton class. This is

data/lib/cuprum/matcher_list.rb

@@ -76,10 +76,10 @@ module Cuprum
     #
     # @param result [Cuprum::Result] The result to match.
     #
-    # @raise Cuprum::Matching::NoMatchError if none of the matchers match the
+    # @raise [Cuprum::Matching::NoMatchError] if none of the matchers match the
     #   given result.
     #
-    # @see Cuprum::Matcher#call.
+    # @see Cuprum::Matching#call.
     def call(result)
       unless result.respond_to?(:to_cuprum_result)
         raise ArgumentError, 'result must be a Cuprum::Result'

data/lib/cuprum/matching.rb

@@ -114,6 +114,8 @@ module Cuprum
       end
     end
 
+    # @!parse extend ClassMethods
+
     # @return [Object, nil] the execution context for a matching clause.
     attr_reader :match_context
 
@@ -164,7 +166,7 @@ module Cuprum
     #
     # @raise [NoMatchError] if there is no clause matching the result.
     #
-    # @see ClassMethods::match
+    # @see ClassMethods#match
     # @see #match_context
     def call(result)
       unless result.respond_to?(:to_cuprum_result)

data/lib/cuprum/middleware.rb

@@ -62,7 +62,7 @@ module Cuprum
   #     end
   #   end
   #
-  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
+  #   command    = ExampleCommand.new
   #   middleware = LoggingMiddleware.new
   #   result     = middleware.call(command, { id: 0 })
   #   #=> logs "Calling command ExampleCommand"
@@ -81,8 +81,8 @@ module Cuprum
   #     end
   #   end
   #
-  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
-  #   middleware = LoggingMiddleware.new
+  #   command    = Command.new { |**options| "Options: #{options.inspect}" }
+  #   middleware = ApiMiddleware.new
   #   result     = middleware.call(command, { id: 0 })
   #   result.value
   #   #=> "Options: { id: 0, api_key: '12345' }"
@@ -92,8 +92,8 @@ module Cuprum
   #     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.
+  #     # middleware discards the failing result and returns a passing result
+  #     # with a value of nil.
   #     private def process(next_command, *args, **kwargs)
   #       result = super
   #
@@ -103,16 +103,23 @@ module Cuprum
   #     end
   #   end
   #
-  #   command    = Command.new { |**opts| "Called with #{opts.inspect}" }
-  #   middleware = LoggingMiddleware.new
-  #   result     = middleware.call(command, { id: 0 })
+  #   middleware = IgnoreFailure.new
+  #   command    = Command.new do |number|
+  #     return success('number is even') if number.even?
+  #
+  #     error = Cuprum::Error.new(message: 'number is odd')
+  #     failure(error)
+  #   end
+  #
+  #   # Calling the command without the middleware.
+  #   result = command.call(1)
   #   result.success?
-  #   #=> true
-  #   result.value
-  #   #=> "Options: { id: 0, api_key: '12345' }"
+  #   #=> false
+  #   result.error.message
+  #   #=> 'number is odd'
   #
-  #   error      = Cuprum::Error.new(message: 'Something went wrong.')
-  #   result     = middleware.call(command, error: error)
+  #   # Calling the command with the middleware.
+  #   result = middleware.call(command, 1)
   #   result.success?
   #   #=> true
   #   result.value