Class: Cuprum::ResultList

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/cuprum/result_list.rb

Overview

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 Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*results, allow_partial: false, error: UNDEFINED, status: UNDEFINED, value: UNDEFINED) ⇒ ResultList

Returns a new instance of ResultList.

Parameters:

  • allow_partial (true, false) (defaults to: false) —

    If true, allows for some failing results as long as there is at least one passing result. Defaults to false.

  • error (Cuprum::Error) (defaults to: UNDEFINED) —

    If given, sets the error for the result list to the specified error object.

  • results (Array<Cuprum::Result>) —

    The wrapped results.

  • status (:success, :failure) (defaults to: UNDEFINED) —

    If given, sets the status of the result list to the specified value.

  • value (Object) (defaults to: UNDEFINED) —

    The value of the result. Defaults to the mapped values of the results.



47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/cuprum/result_list.rb', line 47

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

Instance Attribute Details

#error ⇒ Cuprum::Errors::MultipleErrors, ... (readonly)

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.

Returns:



76
77
78
 
# File 'lib/cuprum/result_list.rb', line 76

def error
  @error
end

#results ⇒ Array<Cuprum::Result> (readonly) Also known as: to_a

Returns the wrapped results.

Returns:



62
63
64
 
# File 'lib/cuprum/result_list.rb', line 62

def results
  @results
end

#status ⇒ :success, :failure (readonly)

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.

Returns:

  • (:success, :failure) —

    the status of the combined results.



93
94
95
 
# File 'lib/cuprum/result_list.rb', line 93

def status
  @status
end

#value ⇒ Object (readonly)

Returns The value of the result. Defaults to the mapped values of the results.

Returns:

  • (Object) —

    The value of the result. Defaults to the mapped values of the results.



97
98
99
 
# File 'lib/cuprum/result_list.rb', line 97

def value
  @value
end

Instance Method Details

#==(other) ⇒ true, false

Returns true if the other object is a ResultList with matching results and options; otherwise false.

Returns:

  • (true, false) —

    true if the other object is a ResultList with matching results and options; otherwise false.



103
104
105
106
107
 
# File 'lib/cuprum/result_list.rb', line 103

def ==(other)
  other.is_a?(ResultList) &&
    results        == other.results &&
    allow_partial? == other.allow_partial?
end

#allow_partial? ⇒ true, false

Returns if true, allows for some failing results as long as there is at least one passing result. Defaults to false.

Returns:

  • (true, false) —

    if true, allows for some failing results as long as there is at least one passing result. Defaults to false.

See Also:



114
115
116
 
# File 'lib/cuprum/result_list.rb', line 114

def allow_partial?
  @allow_partial
end

#each ⇒ Enumerator #each {|result| ... } ⇒ Object

Iterates over the results.

Overloads:

  • #each ⇒ Enumerator

    Returns an enumerator over the results.

    Returns:

    • (Enumerator) —

      an enumerator over the results.

  • #each {|result| ... } ⇒ Object

    Yields each result to the block.

    Yield Parameters:




# File 'lib/cuprum/result_list.rb', line 26

#errors ⇒ Array<Cuprum::Error, nil>

Returns the error, if any, for each result.

Returns:

  • (Array<Cuprum::Error, nil>) —

    the error, if any, for each result.



119
120
121
 
# File 'lib/cuprum/result_list.rb', line 119

def errors
  @errors ||= results.map(&:error)
end

#failure? ⇒ Boolean

Returns true if the result status is :failure, otherwise false.

Returns:

  • (Boolean) —

    true if the result status is :failure, otherwise false.



124
125
126
 
# File 'lib/cuprum/result_list.rb', line 124

def failure?
  status == :failure
end

#statuses ⇒ Array<Symbol>

Returns the status for each result.

Returns:

  • (Array<Symbol>) —

    the status for each result.



129
130
131
 
# File 'lib/cuprum/result_list.rb', line 129

def statuses
  @statuses ||= results.map(&:status)
end

#success? ⇒ Boolean

Returns true if the result status is :success, otherwise false.

Returns:

  • (Boolean) —

    true if the result status is :success, otherwise false.



134
135
136
 
# File 'lib/cuprum/result_list.rb', line 134

def success?
  status == :success
end

#to_cuprum_result ⇒ Cuprum::Result

Converts the result list to a Cuprum::Result.

Returns:

See Also:



145
146
147
 
# File 'lib/cuprum/result_list.rb', line 145

def to_cuprum_result
  Cuprum::Result.new(error: error, status: status, value: value)
end

#values ⇒ Array<Object, nil>

Returns the value, if any, for each result.

Returns:

  • (Array<Object, nil>) —

    the value, if any, for each result.



150
151
152
 
# File 'lib/cuprum/result_list.rb', line 150

def values
  @values ||= results.map(&:value)
end