Class: Cuprum::Operation

Inherits:
Command show all
Includes:
Mixin
Defined in:
lib/cuprum/operation.rb

Overview

Functional object with syntactic sugar for tracking the last result.

An Operation is like a Command, but with two key differences. First, an Operation retains a reference to the result object from the most recent time the operation was called and delegates the methods defined by Cuprum::Result to the most recent result. This allows a called Operation to replace a Cuprum::Result in any code that expects or returns a result. Second, the #call method returns the operation instance, rather than the result itself.

These two features allow developers to simplify logic around calling and using the results of operations, and reduce the need for boilerplate code (particularly when using an operation as part of an existing framework, such as inside of an asynchronous worker or a Rails controller action).

Like a Command, an Operation can be defined directly by passing an implementation block to the constructor or by creating a subclass that overwrites the #process method.

Examples:

def create
  operation = CreateBookOperation.new.call(book_params)

  if operation.success?
    redirect_to(operation.value)
  else
    @book = operation.value

    render :new
  end # if-else
end # create

See Also:

Defined Under Namespace

Modules: Mixin

Instance Method Summary collapse

Methods inherited from Command

#initialize

Methods included from ResultHelpers

#failure!, #halt!, #success!

Methods included from Chaining

#chain, #failure, #success, #tap_result, #yield_result

Methods included from Processing

#arity, #build_errors, #process

Constructor Details

This class inherits a constructor from Cuprum::Command

Instance Method Details

#call(*arguments, **keywords) { ... } ⇒ Cuprum::Operation

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.

Parameters:

  • arguments (Array) —

    Arguments to be passed to the implementation.

  • keywords (Hash) —

    Keywords to be passed to the implementation.

Yields:

  • If a block argument is given, it will be passed to the implementation.

Returns:

Raises:

  • (Cuprum::NotImplementedError) —

    Unless a block was passed to the constructor or the #process method was overriden by a Command subclass.

See Also:

  • Command#call



# File 'lib/cuprum/operation.rb', line 128

#called? ⇒ Boolean

Returns true if the operation has been called and has a reference to the most recent result; otherwise false.

Returns:

  • (Boolean) —

    true if the operation has been called and has a reference to the most recent result; otherwise false.




# File 'lib/cuprum/operation.rb', line 131

#errors ⇒ Array

Returns the errors from the most recent result, or nil if the operation has not been called.

Returns:

  • (Array) —

    the errors from the most recent result, or nil if the operation has not been called.




# File 'lib/cuprum/operation.rb', line 134

#failure? ⇒ Boolean

Returns true if the most recent result had errors, or false if the most recent result had no errors or if the operation has not been called.

Returns:

  • (Boolean) —

    true if the most recent result had errors, or false if the most recent result had no errors or if the operation has not been called.




# File 'lib/cuprum/operation.rb', line 137

#halted? ⇒ Boolean

Returns true if the most recent was halted, otherwise false.

Returns:

  • (Boolean) —

    true if the most recent was halted, otherwise false.




# File 'lib/cuprum/operation.rb', line 140

#reset! ⇒ Object

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. Use this method to clear any instance variables or state internal to the operation (an operation should never have external state apart from the last result).

If the operation cannot be run more than once, this method should raise an error.




# File 'lib/cuprum/operation.rb', line 143

#result ⇒ Cuprum::Result

Returns The result from the most recent call of the operation.

Returns:

  • (Cuprum::Result) —

    The result from the most recent call of the operation.




# File 'lib/cuprum/operation.rb', line 146

#success? ⇒ Boolean

Returns true if the most recent result had no errors, or false if the most recent result had errors or if the operation has not been called.

Returns:

  • (Boolean) —

    true if the most recent result had no errors, or false if the most recent result had errors or if the operation has not been called.




# File 'lib/cuprum/operation.rb', line 149

#value ⇒ Object

Returns the value of the most recent result, or nil if the operation has not been called.

Returns:

  • (Object) —

    the value of the most recent result, or nil if the operation has not been called.




# File 'lib/cuprum/operation.rb', line 152