cuprum 1.0.0 → 1.1.0

data/lib/cuprum/operation.rb

@@ -37,8 +37,9 @@ module Cuprum
   #
   # @see Cuprum::Command
   class Operation < Cuprum::Command
-    # Module-based implementation of the Operation methods. Use this to convert
-    # an already-defined command into an operation.
+    # Module-based implementation of the Operation methods.
+    #
+    # Use this to convert an already-defined command into an operation.
     #
     # @example
     #   class CustomOperation < CustomCommand
@@ -50,9 +51,7 @@ module Cuprum
       attr_reader :result
 
       # @overload call(*arguments, **keywords, &block)
-      #   Executes the logic encoded in the constructor block, or the #process
-      #   method if no block was passed to the constructor, and returns the
-      #   operation object.
+      #   Calls the command implementation and stores the result.
       #
       #   @param arguments [Array] Arguments to be passed to the implementation.
       #
@@ -63,7 +62,7 @@ module Cuprum
       #   @yield If a block argument is given, it will be passed to the
       #     implementation.
       #
-      # @see Cuprum::Command#call
+      #   @see Cuprum::Command#call
       def call(*args, **kwargs, &block)
         reset! if called? # Clear reference to most recent result.
 
@@ -116,10 +115,9 @@ module Cuprum
         called? ? result.success? : false
       end
 
-      # Returns the most result if the operation was previously called.
-      # Otherwise, returns a failing result.
-      #
-      # @return [Cuprum::Result] the most recent result or failing result.
+      # @return [Cuprum::Result] the most recent result if the operation was
+      #   previously called; otherwise, returns a failing result with a
+      #   Cuprum::Errors::OperationNotCalled error.
       def to_cuprum_result
         return result if result
 

data/lib/cuprum/processing.rb

@@ -60,18 +60,23 @@ module Cuprum
   module Processing
     include Cuprum::ResultHelpers
 
-    # Returns a nonnegative integer for commands that take a fixed number of
-    # arguments. For commands that take a variable number of arguments, returns
-    # -n-1, where n is the number of required arguments.
+    # Returns an indication of the number of arguments accepted by #call.
+    #
+    # If the method takes a fixed number N of arguments, returns N. If the
+    # method takes a variable number of arguments, returns -N-1, where N is the
+    # number of required arguments. Keyword arguments will be considered as a
+    # single additional argument, that argument being mandatory if any keyword
+    # argument is mandatory.
     #
     # @return [Integer] The number of arguments.
+    #
+    # @see Method#arity.
     def arity
       method(:process).arity
     end
 
     # @overload call(*arguments, **keywords, &block)
-    #   Executes the command implementation and returns a Cuprum::Result or
-    #   compatible object.
+    #   Executes the command and returns a Cuprum::Result or compatible object.
     #
     #   Each time #call is invoked, the object performs the following steps:
     #
@@ -107,11 +112,16 @@ module Cuprum
 
     # @!visibility public
     # @overload process(*arguments, **keywords, &block)
-    #   The implementation of the command, to be executed when the #call method
-    #   is called. If #process returns a result, that result will be returned by
+    #   The implementation of the command.
+    #
+    #   Whereas the #call method provides the public interface for calling a
+    #   command, the #process method defines the actual implementation. This
+    #   method should not be called directly.
+    #
+    #   When the command is called via #call, the parameters are passed to
+    #   #process. If #process returns a result, that result will be returned by
     #   #call; otherwise, the value returned by #process will be wrapped in a
-    #   successful Cuprum::Result object. This method should not be called
-    #   directly.
+    #   successful Cuprum::Result object.
     #
     #   @param arguments [Array] The arguments, if any, passed from #call.
     #
@@ -119,9 +129,10 @@ module Cuprum
     #
     #   @yield The block, if any, passed from #call.
     #
-    #   @return [Object] the value of the result object to be returned by #call.
+    #   @return [Cuprum::Result, Object] a result object, or the value of the
+    #     result object to be returned by #call.
     #
-    # @note This is a private method.
+    #   @note This is a private method.
     def process(*_args)
       error = Cuprum::Errors::CommandNotImplemented.new(command: self)
 

data/lib/cuprum/result_list.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require 'cuprum'
+require 'cuprum/errors/multiple_errors'
+
+module Cuprum
+  # Collection object that encapsulates a set of Cuprum results.
+  #
+  # Each Cuprum::ResultList wraps an Array of Cuprum::Result objects, and itself
+  # implements the same methods as a Result: #status, #value, #error, and the
+  # #success? and #failure? predicates. As such, a Command's #process method can
+  # return a ResultList instead of a Result. This is useful for commands that
+  # operate on a collection of items, such as a MapCommand or a controller
+  # endpoint that performs a bulk operation.
+  #
+  # @see Cuprum::Result.
+  class ResultList
+    extend  Forwardable
+    include Enumerable
+
+    UNDEFINED = Object.new.freeze
+    private_constant :UNDEFINED
+
+    # @!method each
+    #   Iterates over the results.
+    #
+    #   @overload each()
+    #     @return [Enumerator] an enumerator over the results.
+    #
+    #   @overload each(&block)
+    #     Yields each result to the block.
+    #
+    #     @yieldparam result [Cuprum::Result] the yielded result.
+
+    # @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.
+    # @param error [Cuprum::Error] If given, sets the error for the result list
+    #   to the specified error object.
+    # @param results [Array<Cuprum::Result>] The wrapped results.
+    # @param status [:success, :failure] If given, sets the status of the result
+    #   list to the specified value.
+    # @param value [Object] The value of the result. Defaults to the mapped
+    #   values of the results.
+    def initialize(
+      *results,
+      allow_partial: false,
+      error: UNDEFINED,
+      status: UNDEFINED,
+      value: UNDEFINED
+    )
+      @allow_partial = allow_partial
+      @results       = normalize_results(results)
+      @error         = error  == UNDEFINED ? build_error  : error
+      @status        = status == UNDEFINED ? build_status : status
+      @value         = value  == UNDEFINED ? values : value
+    end
+
+    # @return [Array<Cuprum::Result>] the wrapped results.
+    attr_reader :results
+    alias_method :to_a, :results
+
+    # Returns the error for the result list.
+    #
+    # If the result list was initialized with an error, returns that error.
+    #
+    # If any of the results have errors, aggregates the result errors into a
+    # Cuprum::MultipleErrors object.
+    #
+    # If none of the results have errors, returns nil.
+    #
+    # @return [Cuprum::Errors::MultipleErrors, Cuprum::Error, nil] the error for
+    #   the result list.
+    attr_reader :error
+
+    # Determines the status of the combined results.
+    #
+    # If the result list was initialize with a status, returns that status.
+    #
+    # If there are no failing results, i.e. the results array is empty or all of
+    # the results are passing, returns :success.
+    #
+    # If there is at least one failing result, it instead returns :failure.
+    #
+    # If the :allow_partial flag is set to true, returns :success if the results
+    # array is empty or there is at least one passing result. If there is at
+    # least one failing result and no passing results, it instead returns
+    # :failure.
+    #
+    # @return [:success, :failure] the status of the combined results.
+    attr_reader :status
+
+    # @return [Object] The value of the result. Defaults to the mapped values of
+    #   the results.
+    attr_reader :value
+
+    def_delegators :@results, :each
+
+    # @return [true, false] true if the other object is a ResultList with
+    #   matching results and options; otherwise false.
+    def ==(other)
+      other.is_a?(ResultList) &&
+        results        == other.results &&
+        allow_partial? == other.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.
+    #
+    # @see #status
+    # @see #to_cuprum_result
+    def allow_partial?
+      @allow_partial
+    end
+
+    # @return [Array<Cuprum::Error, nil>] the error, if any, for each result.
+    def errors
+      @errors ||= results.map(&:error)
+    end
+
+    # @return [Boolean] true if the result status is :failure, otherwise false.
+    def failure?
+      status == :failure
+    end
+
+    # @return [Array<Symbol>] the status for each result.
+    def statuses
+      @statuses ||= results.map(&:status)
+    end
+
+    # @return [Boolean] true if the result status is :success, otherwise false.
+    def success?
+      status == :success
+    end
+
+    # Converts the result list to a Cuprum::Result.
+    #
+    # @return [Cuprum::Result] the converted result.
+    #
+    # @see #error
+    # @see #status
+    # @see #value
+    def to_cuprum_result
+      Cuprum::Result.new(error: error, status: status, value: value)
+    end
+
+    # @return [Array<Object, nil>] the value, if any, for each result.
+    def values
+      @values ||= results.map(&:value)
+    end
+
+    private
+
+    def build_error
+      return if errors.compact.empty?
+
+      Cuprum::Errors::MultipleErrors.new(errors: errors)
+    end
+
+    def build_status
+      passing_result? ? :success : :failure
+    end
+
+    def normalize_results(results)
+      results.map do |obj|
+        next obj if obj.is_a?(Cuprum::ResultList)
+
+        next obj.to_cuprum_result if obj.respond_to?(:to_cuprum_result)
+
+        raise ArgumentError,
+          "invalid result: #{obj.inspect} does not respond to #to_cuprum_result"
+      end
+    end
+
+    def passing_result?
+      return true if results.empty?
+
+      if allow_partial?
+        results.any?(&:success?)
+      else
+        results.all?(&:success?)
+      end
+    end
+  end
+end

data/lib/cuprum/rspec/be_a_result_matcher.rb

@@ -142,7 +142,7 @@ module Cuprum::RSpec
       return '' if error_matches?
 
       "\n   expected error: #{inspect_expected(expected_error)}" \
-      "\n     actual error: #{result.error.inspect}"
+        "\n     actual error: #{result.error.inspect}"
     end
 
     def error_matches?
@@ -179,7 +179,7 @@ module Cuprum::RSpec
 
     def negated_matcher_warning
       "Using `expect().not_to be_a_result#{properties_warning}` risks false" \
-      ' positives, since any other result will match.'
+        ' positives, since any other result will match.'
     end
 
     # rubocop:disable Metrics/AbcSize
@@ -219,7 +219,7 @@ module Cuprum::RSpec
       ary << 'error'  unless error_matches?
 
       ", but the #{tools.array_tools.humanize_list(ary)}" \
-      " #{tools.integer_tools.pluralize(ary.size, 'does', 'do')} not match:"
+        " #{tools.integer_tools.pluralize(ary.size, 'does', 'do')} not match:"
     end
 
     def properties_warning
@@ -234,7 +234,7 @@ module Cuprum::RSpec
 
       return message if ary.size == 1
 
-      message + ary[1..-1].map { |str| ".and_#{str}()" }.join
+      message + ary[1..].map { |str| ".and_#{str}()" }.join
     end
 
     def result
@@ -251,7 +251,7 @@ module Cuprum::RSpec
       return '' if status_matches?
 
       "\n  expected status: #{expected_status.inspect}" \
-      "\n    actual status: #{result.status.inspect}"
+        "\n    actual status: #{result.status.inspect}"
     end
 
     def status_matches?
@@ -270,7 +270,7 @@ module Cuprum::RSpec
       return '' if value_matches?
 
       "\n   expected value: #{inspect_expected(expected_value)}" \
-      "\n     actual value: #{result.value.inspect}"
+        "\n     actual value: #{result.value.inspect}"
     end
 
     def value_matches?

data/lib/cuprum/steps.rb

@@ -128,7 +128,8 @@ module Cuprum
     #
     # @yield Called with no parameters.
     #
-    # @yieldreturn A Cuprum result, or an object to be wrapped in a result.
+    # @yieldreturn [Cuprum::Result, Object] 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.
@@ -163,6 +164,8 @@ module Cuprum
     #   result.class    #=> Cuprum::Result
     #   result.success? #=> false
     #   result.error    #=> 'second step'
+    #
+    # @raise [ArgumentError] if a block is not given.
     def steps(&block)
       raise ArgumentError, 'no block given' unless block_given?
 

data/lib/cuprum/utils/instance_spy.rb

@@ -3,54 +3,52 @@
 require 'cuprum/utils'
 
 module Cuprum::Utils
-  # Utility module for instrumenting calls to the #call method of any instance
-  # of a command class. This can be used to unobtrusively test the
-  # functionality of code that calls a command without providing a reference to
-  # the command instance, such as chained commands or methods that create and
-  # call a command instance.
+  # Instruments calls to the #call method of any instance of a command class.
+  #
+  # This can be used to unobtrusively test the functionality of code that calls
+  # a command without providing a reference to the command instance, such
+  # methods that create and call a command instance.
   #
   # @example Observing calls to instances of a command.
   #   spy = Cuprum::Utils::InstanceSpy.spy_on(CustomCommand)
   #
-  #   expect(spy).to receive(:call).with(1, 2, 3, :four => '4')
+  #   allow(spy).to receive(:call)
   #
   #   CustomCommand.new.call(1, 2, 3, :four => '4')
   #
-  # @example Observing calls to a chained command.
-  #   spy = Cuprum::Utils::InstanceSpy.spy_on(ChainedCommand)
-  #
-  #   expect(spy).to receive(:call)
-  #
-  #   Cuprum::Command.new {}.
-  #     chain { |result| ChainedCommand.new.call(result) }.
-  #     call
+  #   expect(spy).to have_received(:call).with(1, 2, 3, :four => '4')
   #
   # @example Block syntax
   #   Cuprum::Utils::InstanceSpy.spy_on(CustomCommand) do |spy|
-  #     expect(spy).to receive(:call)
+  #     allow(spy).to receive(:call)
   #
   #     CustomCommand.new.call
+  #
+  #     expect(spy).to have_received(:call)
   #   end
   module InstanceSpy
-    # Minimal class that implements a #call method to mirror method calls to
-    # instances of an instrumented command class.
+    # Minimal class double implementing the #call method.
     class Spy
-      # Empty method that accepts any arguments and an optional block.
-      def call(*_args, &block); end
+      # Empty method that accepts any parameters and an optional block.
+      def call(*_args, **_kwargs, &block); end
     end
 
     class << self
-      # Retires all spies. Subsequent calls to the #call method on command
-      # instances will not be mirrored to existing spy objects.
+      # Retires all spies.
+      #
+      # Subsequent calls to the #call method on command instances will not be
+      # mirrored to existing spy objects.
       def clear_spies
         Thread.current[:cuprum_instance_spies] = nil
 
         nil
       end
 
-      # Finds or creates a spy object for the given module or class. Each time
-      # that the #call method is called for an object of the given type, the
-      # spy's #call method will be invoked with the same arguments and block.
+      # Finds or creates a spy object for the given module or class.
+      #
+      # Each time that the #call method is called for an object of the given
+      # type, the spy's #call method will be invoked with the same arguments and
+      # block.
       #
       # @param command_class [Class, Module] The type of command to spy on.
       #   Must be either a Module, or a Class that extends Cuprum::Command.

data/lib/cuprum/version.rb

@@ -10,7 +10,7 @@ module Cuprum
     # Major version.
     MAJOR = 1
     # Minor version.
-    MINOR = 0
+    MINOR = 1
     # Patch version.
     PATCH = 0
     # Prerelease version.

data/lib/cuprum.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
-# A lightweight, functional-lite toolkit for making business logic a first-class
-# citizen of your application.
+# Toolkit for implementing business logic as function objects.
 module Cuprum
   autoload :Command,    'cuprum/command'
   autoload :Error,      'cuprum/error'
+  autoload :MapCommand, 'cuprum/map_command'
   autoload :Matcher,    'cuprum/matcher'
   autoload :Middleware, 'cuprum/middleware'
   autoload :Operation,  'cuprum/operation'
   autoload :Result,     'cuprum/result'
+  autoload :ResultList, 'cuprum/result_list'
   autoload :Steps,      'cuprum/steps'
 
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuprum
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-16 00:00:00.000000000 Z
+date: 2023-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sleeping_king_studios-tools
@@ -44,56 +44,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.7'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.10.0
+        version: '1.31'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.10.0
+        version: '1.31'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.11'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.21'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.21'
 description: |-
   An opinionated implementation of the Command pattern for Ruby applications.
   Cuprum wraps your business logic in a consistent, object-oriented interface
@@ -123,9 +123,11 @@ files:
 - lib/cuprum/error.rb
 - lib/cuprum/errors.rb
 - lib/cuprum/errors/command_not_implemented.rb
+- lib/cuprum/errors/multiple_errors.rb
 - lib/cuprum/errors/operation_not_called.rb
 - lib/cuprum/errors/uncaught_exception.rb
 - lib/cuprum/exception_handling.rb
+- lib/cuprum/map_command.rb
 - lib/cuprum/matcher.rb
 - lib/cuprum/matcher_list.rb
 - lib/cuprum/matching.rb
@@ -135,6 +137,7 @@ files:
 - lib/cuprum/processing.rb
 - lib/cuprum/result.rb
 - lib/cuprum/result_helpers.rb
+- lib/cuprum/result_list.rb
 - lib/cuprum/rspec.rb
 - lib/cuprum/rspec/be_a_result.rb
 - lib/cuprum/rspec/be_a_result_matcher.rb
@@ -150,7 +153,7 @@ metadata:
   bug_tracker_uri: https://github.com/sleepingkingstudios/cuprum/issues
   source_code_uri: https://github.com/sleepingkingstudios/cuprum
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -158,15 +161,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
-signing_key: 
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: An opinionated implementation of the Command pattern.
 test_files: []